Manuel PHP
Publié par
08-07-2002
Copyright © 1997, 1998, 1999, 2000, 2001, 2002 par PHP Documentation Group
Copyright
Ce manuel est © Copyright 1997, 1998, 1999, 2000, 2001, 2002 par PHP Documentation Group. Les membres de ce groupe sont listés sur la première page de ce manuel.
Ce manuel peut être redistribué sous licence GNU General Public License, comme stipulé par la Free Software Foundation; soit la version 2 de la Licence, soit (à votre choix), une version ultérieure.
- Table des matières
- Préface
- I. Comment commencer
- 1. Introduction
- 2. Installation
- 3. Configuration
- 4. Sécurité
- II. Référence
- III. Caractéristiques
- IV. Index des fonctions
- I. Apache
- II. Tableaux
- III. Aspell
- IV. Nombres de grande taille
- V. Compression Bzip2
- VI. Calendrier
- VII. Paiement CCVS
- VIII. Support COM pour Windows
- IX. Objets
- X. ClibPDF
- XI. Crack
- XII. CURL
- XIII. Paiement Cybercash
- XIV. CyberMUT : Crédit Mutuel
- XV. Administration Cyrus IMAP
- XVI. Caractères
- XVII. DBA
- XVIII. Dates et heures
- XIX. dBase
- XX. DBM
- XXI. dbx
- XXII. DB++ Functions
- XXIII. Direct IO
- XXIV. Accès aux dossiers
- XXV. DOM XML
- XXVI. .NET
- XXVII. Gestion des erreurs
- XXVIII. FrontBase
- XXIX. FilePro
- XXX. Système de fichiers
- XXXI. Forms Data Format
- XXXII. FriBiDi
- XXXIII. FTP
- XXXIV. Fonctions
- XXXV. Gettext (GNU)
- XXXVI. GMP
- XXXVII. HTTP
- XXXVIII. Hyperwave
- XXXIX. Hyperwave API functions
- XL. ICAP
- XLI. Iconv
- XLII. Images
- XLIII. IMAP
- XLIV. Informix
- XLV. InterBase
- XLVI. Ingres II
- XLVII. IRC
- XLVIII. Java
- XLIX. LDAP
- L. Email
- LI. mailparse functions
- LII. Mathématiques
- LIII. Chaînes de caractères multi-octets
- LIV. MCAL
- LV. Chiffrage mcrypt
- LVI. Hash
- LVII. Mimetype Functions
- LVIII. Microsoft SQL Server
- LIX. Ming pour Flash
- LX. Fonctions diverses
- LXI. mnoGoSearch
- LXII. mSQL
- LXIII. MySQL
- LXIV. Mohawk Software session handler functions
- LXV. Fonctions muscat
- LXVI. Réseau
- LXVII. Ncurses terminal screen control functions
- LXVIII. Lotus Notes functions
- LXIX. ODBC unifié
- LXX. Oracle 8
- LXXI. OpenSSL
- LXXII. Oracle
- LXXIII. Ovrimos SQL
- LXXIV. Entrées/sorties
- LXXV. Overload
- LXXVI. PDF
- LXXVII. Paiement par Verisign
- LXXVIII. Options PHP et informations
- LXXIX. POSIX
- LXXX. PostgreSQL
- LXXXI. Contrôle des processus
- LXXXII. Exécution de programmes externes
- LXXXIII. Printer functions
- LXXXIV. Pspell
- LXXXV. Readline (GNU)
- LXXXVI. Recode (GNU)
- LXXXVII. Expressions régulières compatibles Perl
- LXXXVIII. qtdom
- LXXXIX. Expressions régulières
- XC. Sémaphores et gestion de la mémoire partagée
- XCI. SESAM
- XCII. Sessions
- XCIII. Mémoire partagée
- XCIV. Shockwave Flash
- XCV. SNMP
- XCVI. Sockets
- XCVII. Chaîne de caractères
- XCVIII. Sybase
- XCIX. Tokenizer functions
- C. URL
- CI. Variables
- CII. vpopmail functions
- CIII. API Windows 32 bits
- CIV. WDDX
- CV. Analyseur syntaxique XML
- CVI. XMLRPC
- CVII. XSLT
- CVIII. YAZ
- CIX. NIS
- CX. Zip (décompression)
- CXI. Zlib (Compression)
- V. Extending PHP 4.0
- 25. Overview
- 26. Extension Possibilities
- 27. Source Layout
- 28. PHP's Automatic Build System
- 29. Creating Extensions
- 30. Using Extensions
- 31. Troubleshooting
- 32. Source Discussion
- 33. Accepting Arguments
- 34. Creating Variables
- 35. Duplicating Variable Contents: The Copy Constructor
- 36. Returning Values
- 37. Printing Information
- 38. Startup and Shutdown Functions
- 39. Calling User Functions
- 40. Initialization File Support
- 41. Where to Go from Here
- 42. Reference: Some Configuration Macros
- 43. API Macros
- VI. FAQ : Foire Aux Questions
- VII. Appendices
Préface
PHP, est un acronyme récursif, qui signifie "PHP: Hypertext Preprocessor" : c'est un langage de script HTML, exécuté coté serveur. L'essentiel de sa syntaxe est emprunté aux langages C, Java et Perl, avec des améliorations spécifiques. L'objet de ce langage est de permettre aux développeurs web d'écrire des pages dynamiques rapidement.
Notez qu'aujourd'hui, les capacités de PHP vont bien au-dela de la génération de pages HTML : PHP génère des documents PDF, des images ou même des animations Flash à la volée. PHP-GTK permet à PHP de faire des scripts utilisant des interfaces X.
A propos de ce manuel
Ce manuel est écrit en XML avec DocBook XML DTD, en utilisant DSSSL (Document Style and Semantics Specification Language) pour l'affichage. Les outils utilisés pour les formats HTML et TeX sont Jade, écrit par James Clark et The Modular DocBook Stylesheets écrit par Norman Walsh. Nous utilisons aussi Microsoft HTML Help Workshop pour générer le format HTML.
Vous pouvez télécharger le manuel courant dans divers langages et formats, y compris en texte seul, HTML, PDF, PalmPilot DOC, PalmPilot iSilo et WinHelp, depuis http://www.php.net/docs.php. Les manuels sont mis à jour quotidiennement.
La version française est traduite quotidiennement et disponible chez Nexen (nexen.net/). Ce manuel a été généré à partir de la documentation originale en anglais du PHP Documentation Group, au format XML, grâce à une version adaptée de texi.
Vous pouvez avoir d'autres informations sur le téléchargement des sources XML de cette documentation à http://cvs.php.net/. La documentation est stockée dans le module phpdoc.
Si vous rencontrez des erreurs dans ce manuel, rapportez les dans le système de rapport de bug : http://bugs.php.net/, et classez les comme des "Problème de documentation" (en anglais, "Documentation Problem"). De cette façon, nous pourrons être prévenu de chaque bug, et nous pourrons les corriger.
Pour les problèmes liés à la traduction, vous pouvez aussi contacter directement l'éditeur de ce manuel damien.seguy@nexen.net.
I. Comment commencer
- Table des matières
- 1. Introduction
- 2. Installation
- 3. Configuration
- 4. Sécurité
Chapitre 1. Introduction
Qu'est ce que PHP?
PHP (officiellement "PHP: Hypertext Preprocessor") est un langage de script HTML, qui fonctionne côté serveur.
Réponse simple et claire, mais qu'est ce que cela veut dire? Un exemple :
Il est à noter la différence avec les autres scripts CGI écrit dans d'autres langages tels que le Perl ou le C : Au lieu d'écrire un programme avec de nombreuses lignes de commandes afin d'afficher une page HTML, vous écrivez une page HTML avec du code inclus à l'intérieur afin de réaliser une action précise (dans ce cas là, afficher du texte). Le code PHP est inclus entre une balise de début et une balise de fin qui permettent au navigateur de passer en "mode PHP".
Ce qui distingue le PHP des langages de script comme le Javascript est que le code est exécuté sur le serveur. Si vous avez un script similaire sur votre serveur, 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. Vous pouvez configurer votre serveur web afin qu'il analyse tous vos fichiers HTML comme des fichiers PHP. Ainsi, il n'y a aucun moyen de distinguer les pages qui sont produites dynamiquement des pages statiques.
Que peut faire PHP?
Le langage PHP possède les même fonctionnalités que les autres langages permettant d'écrire des scripts CGI, comme collecter des données, générer dynamiquement des pages web ou bien envoyer et recevoir des cookies.
La plus grande qualité et le plus important avantage du langage PHP est le support d'un grand nombre de bases de données. Réaliser une page web dynamique interfacant une base de donnés est extrêmement simple. Les bases de données suivantes sont supportées par PHP:
Adabas D InterBase PostgreSQL dBase FrontBase Sesam Empress mSQL Solid FilePro (lecutre seule) Direct MS-SQL Sybase Hyperwave MySQL Velocis IBM DB2 ODBC Unix dbm Informix Oracle (OCI7 et OCI8) Ingres Ovrimos
Le langage PHP inclus le support des services utilisant les protocoles tels que IMAP, SNMP, NNTP, POP3 ou encore HTTP. Vous pouvez également ouvrir des connexions et interagir en utilisant d'autres protocoles.
La genèse du PHP
Le langage PHP a été conçu durant l'automne 1994 par Rasmus Lerdorf. Les premières versions (qui restèrent privées) étaient utilisées afin de savoir qui venait consulter son CV en ligne. La première version publique fut disponible au début de l'année 1995. Elle fut connue sous le nom de "Personal Sommaire Page Tools". Elle était composée d'un analyseur extrêmement simple qui ne reconnaissait que quelques macros spéciales et d'un petit nombre d'utilitaires couramment utilisés dans les pages web. Un livre d'or, un compteur, etc... L'analyseur fut réécrit durant l'été 1995 et fut appelé PHP/FI Version 2. FI etaient les initiales d'un autre package que Rasmus avait écrit qui interprétait les formulaires HTML. C'est alors qu'il combina le "Personnal Sommaire Page tools" avec le "Form Interpreter" et il y ajouta le support de mSQL: c'est comme cela que naquît PHP/FI. PHP/FI grandit de manière spectaculaire et de nombreuses personnes commencèrent à contribuer à son amélioration.
Il est relativement peu aisé de donner des statistiques, mais on estime que PHP/FI est utilisé sur 15 000 sites web dans le monde entier, fin 1996. Ce chiffre atteint 50 000 durant l'été 1997. L'été 1997 voit aussi un profond changement dans le développement du PHP: d'un projet personnel (celui de Ramsus), on passe alors à une projet d'équipe. L'analyseur fut de nouveau réécrit par Zeev Suraski et Andi Gutmans et ce nouvel analyseur forma la base de la version 3 du PHP. Une grande partie du code de PHP/FI fut complètement réécrit alors que l'autre partie fut portée pour donner le PHP Version 3. La dernière version de PHP (PHP 4) utilise le moteur d'analyse Zend pour atteindre de nouveaux niveaux de performance, et supporter un nombre encore plus grand de librairies et extensions. Il tourne de manière native sur tous les serveurs web les plus répandus.
Aujourd'hui (Janvier 2001) PHP 3 ou PHP 4 sont distribués avec de nombreux produits commerciaux comme "C2's StrongHold web server" et "RedHat Linux" et il est admis (d'après les chiffres de NetCraft, et leurs statistiques Netcraft Web Server Survey) que le PHP est utilisé sur 5 100 000 sites web dans le monde entier. Pour comparaison, ce chiffre est légèrement supérieur au nombre de serveurs tournant sous Microsoft Information server (IIS) : 5.03 millions.
Enfin, à l'heure où ce document est rédigé, la nouvelle génération du PHP est en cours de création. Elle utilisera les qualités de Zend pour améliorer les performances et améliorera le support des serveurs web autres que Apache.
Chapitre 2. Installation
Considérations générales sur l'installation
Avant d'installer PHP, vous devez savoir ce que vous voulez faire de PHP. Il y a trois cas d'utilisation que vous a décrit la section Que peut faire? section:
Scripts web
Scripts de ligne de commande
Application à interface graphique
Pour la première tâche, qui est de loin la plus répandue, vous avez besoin de trois choses : PHP lui-même, un serveur web et un navigateur. Vous avez probablement un navigateur, et en fonction de votre système d'exploitation, vous pouvez aussi disposer d'un serveur Web (i.e. Apache sous Linux ou IIS sous Windows). Vous pouvez aussi louer un espace à une société. De cette façon, vous n'aurez pas à mettre en place PHP, mais uniquement à écrire vos scripts, les charger sur le serveur et voir le résultat sur votre navigateur. Vous pouvez trouver une liste de ces compagnies à http://hosts.php.net/.
Si vous installez PHP et le serveur par vous-même, vous avez 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 iPlanet. D'autres serveurs ont aussi le support ISAPI, l'interface de module Microsoft (OmniHTTPd par exemple). Si PHP ne supporte pas l'interface de module de votre serveur web, vous pouvez toujours l'utiliser comme processeur CGI. Cela signifie que vous devez configurer votre serveur pour qu'il utilise l'exécutable PHP (php.exe sous Windows), pour qu'il traite les fichiers PHP sur le serveur.
Si vous souhaitez aussi 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 fonctions d'information que vous leur passeriez), vous aurez besoin d'un exécutable PHP. Pour plus de détails, lisez la section écrire des applications PHP en ligne de commande. Dans ce cas, vous n'aurez pas besoin de serveur web, ni de navigateur.
Avec PHP, vous pouvez aussi écrire des interfaces graphiques clientes, en utilisant l'extension PHP-GTK. C'est une approche complètement différente de l'écriture des pages web, car vous ne générerez pas de fichiers HTML, mais vous aurez à gérer des fenêtres et des objets. Pour plus de détails sur PHP-GTK, voyez le site officiel. PHP-GTK n'est pas inclus dans la distribution officielle de PHP.
A 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 exécutables compilés de certains OS (y compris Windows), sont disponibles à http://www.php.net/. Nous recommandons l'utilisation du miroir le plus proche pour accélérer les chargements.
Installation sous UNIX
Cette section va vous guider lors du processus d'installation et de configuration de PHP sous Unix. Commencez par étudier les sections spécifiques à votre plate-forme ou à votre serveur web avant de passer à l'installation.
Pré-requis :
Connaissance de base d'UNIX (savoir faire un "make" et compiler en C, si besoin).
Un compilateur ANSI C (pour les codes sources)
flex (pour les codes sources)
bison (pour les codes sources)
Un serveur web
Tous les composants nécessaires aux extensions (librairie GD, PDF, etc...)
Il y a plusieurs façons d'installer PHP sur une plate-forme UNIX : soit un processus de compilation-configuration, ou bien avec des packages déjà tout prêts. Cette documentation se concentre sur la première solution.
La première partie du processus est faite en ligne de commande, grâce aux options du script configure. Cette section présente l'utilisation des options les plus courantes, mais il y en a beaucoup d'autres à essayer. Reportez-vous à la liste complète des options de configuration pour une liste exhaustive. Voici les différentes méthodes d'installation de PHP :
Comme module Apache
Comme module fhttpd
Pour l'utiliser avec AOLServer, NSAPI, phttpd, Pi3Web, Roxen, thttpd, ou Zeus.
Comme exécutable CGI
Référence Module Apache
PHP peut être compilé de nombreuses manières différentes, mais la plus populaire est le module Apache. La liste suivante est un récapitulatif de l'installation.
Compilation
Lorsque PHP est configuré, vous êtes prêts à compiler l'exécutable CGI. La commande make doit prendre tout en charge. Si ce n'est pas le cas et que vous restez bloqué, reportez-vous aux problèmes courants.
Installation sous Linux
Cette section contient les notes et conseils d'installation de PHP sur les distributions Linux.
Utilisation des packages
De nombreuses distributions Linux disposent d'un système d'installation par package, comme le fameux RPM. Ils vous permettent de faire des installations standard, mais si vous avez des configurations spécifiques (comme par exemple un serveur sécurisé, ou un pilote de base de données exotique), vous aurez probablement à compiler vous-même votre PHP et votre serveur web. Si vous n'êtes pas familier avec la compilation de vos propres logiciels, il vaut mieux rechercher le package qui pourra répondre à vos besoins.
Installation sous HP-UX
Cette section contient les notes et conseils d'installation de PHP sur les distributions HP-UX.
Exemple 2-2. Instructions d'installation pour HP-UX 10
|
Installation sous Solaris
Cette section contient les notes et conseils d'installation de PHP sur les distributions Solaris.
Logiciels nécessaires
L'installation Solaris oublie généralement les compilateurs C, et leurs utilitaires. Voici la liste des outils nécessaires :
gcc (recommandé, mais d'autres compilateurs C peuvent fonctionner)
make
flex
bison
m4
autoconf
automake
perl
gzip
tar
Utilisation des packages
Vous pouvez simplifier l'installation Solaris en utilisant pkgadd pour installer la plupart des composants.
Installations Unix/OpenBSD
Cette section contient les notes spécifiques à l'installation de PHP sous OpenBSD.
Utilisation des ports
Ceci est la méthode recommandée d'installation de PHP sous OpenBSD, car elle prend en compte les dernières modifications et mises à jour de sécurité. Pour utiliser cette méthode, assurez vous que vous avez bien ports tree récent. Choisissez alors simplement la version que vous souhaitez installer, et utilisez la commande make install. Ci-dessous, voici un exemple.
Utilisation des Packages
Il existe des packages pré-compilés disponibles en téléchargement à OpenBSD. Ils s'intègrent automatiquement avec la version d'Apache installée sur votre OS. Cependant, comme il y a un grand nombre d'options (appelées flavors) disponibles, vous trouverez peut-être plus facile de le compiler à partir de l'arbre de ports. Lisez le manuel packages(7) pour plus de détails sur les packages disponibles (en anglais).
Installation sous Mac OS X
Cette section contient les notes et conseils d'installation de PHP sur les distributions Mac OS X.
Utilisation des packages
Il existe quelques versions pré-packagée et pré-compilées de PHP pour Mac OS X. Ils permettent de réaliser rapidement des installations standard, mais si vous avez des configurations personnelles, (comme un serveur sécurisé SSL ou un pilote de base de données exotique), vous devrez compiler PHP et/ou votre serveur web vous-même. Si vous n'êtes pas familier avec la compilation de vos propres logiciels, il vaut mieux rechercher le package qui pourra répondre à vos besoins.
Compilation pour serveur OS X
Il existe deux versions légèrement différentes de Mac OS X, client et serveur. Cette installation est faite pour le OS X Serveur.
Exemple 2-4. Installation sous Mac OS X serveur
|
D'autres exemples pour Mac OS X client et Mac OS X server sont disponibles à Stepwise.
Compilation pour MacOS X client
Ces conseils sont gracieusement fourni par Marc Liyanage.
Le module PHP pour Apache est inclus dans Mac OS X. Cette version inclus le support des bases de données MySQL et PostgreSQL.
NOTE: Soyez prudent avec cette manipulation, vous risquez de mettre votre serveur Apache à terre!
Insctructions :
1. Ouvrez un terminal
2. Tapez "wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz", attendez la fin du téléchargement.
3. Tapez "gunzip libphp4.so.gz"
4. Tapez "sudo apxs -i -a -n php4 libphp4.so"
* #AddType application/x-httpd-php .php * #AddType application/x-httpd-php-source .phps |
Finalement, tapez "sudo apachectl graceful" pour redémarrer le serveur Apache.
PHP devrait fonctionner. Vous pouvez le tester en placant un script dans le dossier "Sites". Par exemple, le fichier "test.php", qui contient la simple ligne : "<?php phpinfo() ?>".
Ouvrez l'URL 127.0.0.1/~your_username/test.php dans votre navigateur. Vous obtiendrez le tableau de bord de PHP.
Liste complète des options de configuration
Cette section rassemble la liste complète des options de configuration supportées par PHP 3 et PHP 4, à utiliser avec le fichier configure, lors de la configuration sous Unix. Certaines options sont disponibles sous PHP 3, d'autres sous PHP 4 et certains sous PHP 3 et PHP 4, comme inidiqué. Il y a de nombreuses options dont le nom a changé entre PHP 3 et PHP 4. Ces options ont des liens entre elles : si vous vous souvenez d'un nom d'option en PHP 3, regardez si le nom a changé.
Base de données
- --with-adabas[=DIR]
PHP 3, PHP 4: Inclut le support Adabas D. DIR est le dossier d'installation de Adabas (par défaut, /usr/local).
- --enable-dba=shared
PHP 3: Option non disponible en PHP 3
PHP 4: Compile DBA comme module partagé
- --enable-dbx
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support DBX.
- --enable-dbase
PHP 3: Option non disponible; utilisez plutôt --with-dbase instead.
PHP 4: Active la librairie dbase livrée avec PHP. Aucune librairie supplémentaire n'est nécessaire.
- --with-dbase
PHP 3: Active la librairie dbase livrée avec PHP. Aucune librairie supplémentaire n'est nécessaire.
PHP 4: Option non disponible; utilisez plutôt --enable-dbase instead.
- --with-db2[=DIR]
PHP 3, PHP 4: Active le support Berkeley DB2.
- --with-db3[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support Berkeley DB3.
- --with-dbm[=DIR]
PHP 3, PHP 4: Active le support DBM.
- --with-dbmaker[=DIR]
PHP 3: Option non disponible en PHP 3.
PHP 4: Inclut le support DBMaker. DIR est le dossier d'installation DBMaker (par défaut, c'est le dossier de la dernière installation DBMaker, comme /home/dbmaker/3.6).
- --with-empress[=DIR]
PHP 3, PHP 4: Inclut le support Empress. DIR est le dossier d'installation Empress (par défaut, $EMPRESSPATH).
- --enable-filepro
PHP 3: Option non disponible; utilisez plutôt --with-filepro instead.
PHP 4: Active la librairie filePro (lecture seule) livrée avec PHP. Aucune librairie supplémentaire n'est nécessaire.
- --with-fbsql[=DIR]
PHP 3: Option non disponible.
PHP 4: Inclut le support de FrontBase SQL. DIR est le chemin jusqu'à l'installation de FrontBase base. Par défaut, c'est le dossier standard d'installation Frontbase. L'installation dépend de votre OS : Solaris: /opt/FrontBase, WinNT: \usr\FrontBase, Linux: /usr/frontbase, Mac OSX: /Library/FrontBase.
- --with-filepro
PHP 3: Inclut le support IBM DB2. Aucune librairie supplémentaire n'est nécessaire.
PHP 4: Option non disponible; utilisez plutôt --enable-filepro.
- --with-gdbm[=DIR]
PHP 3, PHP 4: Active le support GDBM.
- --with-hyperwave
PHP 3, PHP 4: Active le support Hyperwave.
- --with-ibm-db2[=DIR]
PHP 3, PHP 4: Inclut le support IBM DB2. DIR est le dossier d'installation de DB2 (par défaut, /home/db2inst1/sqllib).
- --with-informix[=DIR]
PHP 3, PHP 4: Inclut le support Informix. DIR est le dossier d'installation d'Informix (par défaut, aucune valeur).
- --with-ingres[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support Ingres II. DIR est le dossier d'installation d'Ingres (par défaut, /II/ingres).
- --with-interbase[=DIR]
PHP 3, PHP 4: Inclut le support InterBase. DIR est le dossier d'installation d'InterBase (par défaut, /usr/interbase).
- --with-ldap[=DIR]
PHP 3: Inclut le support LDAP. DIR est le dossier d'installation de LDAP (par défaut /usr et /usr/local).
PHP 4: Inclut le support LDAP. DIR est le dossier d'installation de LDAP. (par défaut; /usr/local/ldap).
Plus de détails sur LDAP sont disponibles à RFC1777 et RFC1778.
- --with-msql[=DIR]
PHP 3, PHP 4: Active le support mSQL. DIR est le dossier d'installation de mSQL (par défaut /usr et /usr/local/Hughes, pour la version 2.0). configure détecte automatiquement la version de mSQL qui fonctionne. PHP supporte les versions 1.0 et 2.0, mais si vous compilez PHP avec mSQL 1.0, vous ne pourrez accéder qu'à des bases mSQL 1.0, et vice-versa.
Voir aussi Configuration mSQL dans le fichier de configuration.
- --with-mysql[=DIR]
PHP 3: Inclut le support MySQL. DIR est le dossier d'installation de MySQL (par défaut, il cherche dans différents dossiers où MySQL a coutume d'être installé).
PHP 4: Inclut le support MySQL. DIR est le dossier de l'installation MySQL. S'il est omis, la librairie MySQL livrée en standard avec PHP sera utilisée par défaut.
Voir aussi Configuration MySQL dans le fichier de configuration.
- --with-ndbm[=DIR]
PHP 3, PHP 4: Active le support NDBM.
- --with-ovrimos
PHP 3, PHP 4: Inclut le support Ovrimos.
- --with-oci8[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support Oracle-oci8. DIR est le dossier d'installation de Oracle-oci8 (par défaut, ORACLE_HOME).
- --with-oracle[=DIR]
PHP 3: Inclut le support Oracle database. DIR est le dossier d'installation de Oracle (par défaut, $ORACLE_HOME).
PHP 4: Inclut le support Oracle-oci7. DIR est le dossier d'installation de Oracle-oci7 (par défaut, ORACLE_HOME).
Inclut le support Oracle. Ce support a été testé et permet de travailler avec les versions d'Oracle de 7.0 à 7.3. Le paramètre est le dossier ORACLE_HOME. Vous n'avez pas à spécifier ce paramètre si votre environnement Oracle a été configuré.
- --with-pgsql[=DIR]
PHP 3: Inclut le support PostgresSQL. DIR est le dossier d'installation de PostgresSQL (par défaut, /usr/local/pgsql).
PHP 4: Inclut le support PostgreSQL. DIR est le dossier d'installation de PostgreSQL (par défaut, /usr/local/pgsql). Pour compiler en "dl", utilisez la valeur "shared", ou "shared,DIR", pour compiler en "dl", mais spécifier DIR malgré tout.
Voir aussi Postgres dans le fichier de configuration.
- --with-solid[=DIR]
PHP 3, PHP 4: Inclut le support Solid. DIR est le dossier d'installation de Solid (par défaut, /usr/local/solid).
- --with-sybase-ct[=DIR]
PHP 3, PHP 4: Inclut le support Sybase-CT. DIR est le dossier d'installation de Sybase (par défaut, /home/sybase).
Voir aussi Sybase-CT dans le fichier de configuration.
- --with-sybase[=DIR]
PHP 3, PHP 4: Inclut le support Sybase-DB. DIR est le dossier d'installation de Sybase (par défaut, /home/sybase).
Voir aussi Sybase dans le fichier de configuration.
- --with-openlink[=DIR]
PHP 3, PHP 4: Inclut le support OpenLink ODBC. DIR est le dossier d'installation d'OpenLink (par défaut /usr/local/openlink). A partir de PHP 4.0.6, cette option n'est plus valable. Utilisez plutôt --with-iodbc si vous voulez utiliser l'ODBC de OpenLink Software.
- --with-iodbc[=DIR]
PHP 3, PHP 4: Inclut le support iODBC. DIR est le dossier d'installation d'iODBC (par défaut, /usr/local).
Cette fonctionnalité a d'abord été développée avec le gestionnaire iODBC Driver Manager, un pilote ODBC librement distribuable, qui fonctionne sous divers UNIX.
- --with-custom-odbc[=DIR]
PHP 3, PHP 4: Inclut le support ODBC, avec une librairie tierce. Le paramètre DIR est le nom du dossier d'installation de cette librairie. Par défaut, il vaut /usr/local.
Cette option implique qus vous avez défini CUSTOM_ODBC_LIBS lorsque vous éxécutez le script de configuration. Vous devez aussi avoir une en-tête odbc.h valide dans vos dossiers d'Inclution. Si vous n'en avez pas, créez le, et ajoutez-y vos en-têtes spécifiques. Votre en-tête peut aussi réclamer d'autres définitions, surtout si elle est multi-plate-forme. Définissez les dans CFLAGS.
Par exemple, vous pouvez utilisez Sybase SQL Anywhere sous QNX comme ceci : CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50
- --disable-unified-odbc
PHP 3: Inactive le support unified ODBC. Uniquement valable si iODBC, Adabas, Solid, Velocis ou une interface spéciale ODBC a été activée.
PHP 4: Option non disponible en PHP 4
Le module Unified ODBC est commun à toutes les bases de données ODBC, comme par exemple Solid, IBM DB2 et Adabas D. Il fonctionne aussi avec les librairies ODBC normales. Des tests ont été menés avec iODBC, Solid, Adabas D, IBM DB2 et Sybase SQL Anywhere. Il requiert une (et une seule) de ces extensions, ou l'extension Velocis, ou une librairie ODBC spéciale. Cette option n'est possible qu'avec l'utilisation de l'une des options suivantes : --with-iodbc, --with-solid, --with-ibm-db2, --with-adabas, --with-velocis, ou --with-custom-odbc.
Voir aussi Unified ODBC dans le fichier de configuration.
- --with-unixODBC[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support unixODBC. DIR est le dossier d'installation d'unixODBC (par défaut, /usr/local).
- --with-velocis[=DIR]
PHP 3, PHP 4: Inclus le support Velocis. DIR est le dossier d'installation de Velocis (par défaut, /usr/local/velocis).
E-commerce
- --with-ccvs[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Ajoute le support CCVS. DIR est le dossier d'installation de CCVS.
- --with-cybermut[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support de Cybermut pour PHP 4. DIR est le dossier du SDK Cybermut, qui contient les deux fichiers libcm-mac.a et cm-mac.h.
- --with-mck[=DIR]
PHP 3: Inclut le support Cybercash MCK. DIR est le dossier d'installation de cybercash mck (par défaut, /usr/src/mck-3.2.0.3-linux). Plus d'aide dans le dossier extra/cyberlib.
PHP 4: Option non disponible; utilisez plutôt --with-cybercash instead.
- --with-cybercash[=DIR]
PHP 3: Option non disponible; utilisez plutôt --with-mck instead.
PHP 4: Inclut le support CyberCash. DIR est le dossier d'installation de CyberCash MCK.
- --with-pfpro[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support Verisign Payflow Pro.
Images
- --enable-freetype-4bit-antialias-hack
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support de FreeType2 (expérimental).
- --with-gd[=DIR]
PHP 3: Inclut le support GD. DIR est le dossier d'installation de GD.
PHP 4: Inclut le support GD. DIR est le dossier d'installation de GD. Pour compiler en "dl", utilisez la valeur "shared", ou "shared,DIR", pour compiler en "dl", mais spécifier DIR malgré tout.
- --without-gd
PHP 3, PHP 4: Inactive le support GD .
- --with-imagick[=DIR]
PHP 3: Inclut le support ImageMagick. DIR est le dossier d'installation de ImageMagick. S'il est omis, PHP essaiera de le trouver de lui-même (expérimental).
PHP 4: Option non disponible en PHP 4
- --with-jpeg-dir[=DIR]
PHP 3: dossier JPEG pour pdflib 2.0
PHP 4: dossier JPEG pour pdflib 3.x et 4.x
- --with-png-dir[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: dossier PNG pour pdflib 3.x et 4.x
- --enable-t1lib
PHP 3: Active le support t1lib.
PHP 4: Option non disponible; utilisez plutôt --with-t1lib
- --with-t1lib[=DIR]
PHP 3: Option non disponible; utilisez plutôt --enable-t1lib.
PHP 4: Inclut le support T1lib.
- --with-tiff-dir[=DIR]
PHP 3: dossier TIFF pour pdflib 2.0
PHP 4: dossier TIFF pour pdflib 3.x et 4.x
- --with-ttf[=DIR]
PHP 3, PHP 4: Active le support FreeType.
- --with-xpm-dir[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: dossier XPM pour GD-1.8+
Divers
Ces options seront classées ultérieurement, lorsqu'une catégorie adéquate apparaîtra.
- --disable-bcmath
PHP 3: Inactive la librairie BCmath.
PHP 4: Option non disponible en PHP 4. La librairie BCmath n'est pas compilée par défaut. Utilisez --enable-bcmath pour l'inclure.
- --with-gmp
PHP 3, PHP 4 : Inclut le support GMP.
- --disable-display-source
PHP 3: Compile sans afficher le support des sources
PHP 4: Option non disponible en PHP 4
- --disable-libtool-lock
PHP 3: Option non disponible en PHP 3
PHP 4: Empêche le verrouillage (risque d'empêcher certaines compilations paralléles).
- --disable-pear
PHP 3: Option non disponible en PHP 3
PHP 4: N'installe pas PEAR
- --disable-pic
PHP 3: Option non disponible en PHP 3
PHP 4: Inactive PIC pour les shared objects
- --disable-posix
PHP 3: Option non disponible en PHP 3; Utilisez plutôt --without-posix
PHP 4: Inactive les fonctions POSIX.
- --disable-rpath
PHP 3: Option non disponible en PHP 3
PHP 4: Inactive le passage de chemins supplémentaires pour la recherche de librairie lors de l'exécution.
- --disable-session
PHP 3: Option non disponible en PHP 3
PHP 4: Inactive le support session.
- --enable-bcmath
PHP 3: Option non disponible en PHP 3; bcmath est compilée par défaut. Utilisez plutôt --disable-bcmath, pour l'inactiver.
PHP 4: Active le support de l'extension bc maths. Voir aussi les fonctions BCMath.
- --enable-c9x-inline
PHP 3: Option non disponible en PHP 3
PHP 4: Active les sémantiques C9x-inline
- --enable-calendar
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support des conversions calendaires
- --enable-debug
PHP 3, PHP 4: Compile sans les symboles de débuggages
- --enable-debugger
PHP 3: Compile avec les fonctions de débuggage à distance
PHP 4: Option non disponible en PHP 4
- --enable-discard-path
PHP 3, PHP 4: Si cette option est activée, le CGI PHP peut être placé hors de l'arborescence web, pour que personne ne puisse l'atteindre, même en contournant les .htaccess.
- --enable-dmalloc
PHP 3, PHP 4: Active dmalloc
- --enable-exif
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support exif.
- --enable-experimental-zts
PHP 3: Option non disponible en PHP 3
PHP 4: Cela risque fortement de ne plus compiler du tout!
- --enable-fast-install[=PKGS]
PHP 3: Option non disponible en PHP 3
PHP 4: Optimise pour les installations rapides for fast installation (par défaut, no).
- --enable-force-cgi-redirect
PHP 3, PHP 4: Active la vérification interne des redirections serveurs. Il est recommandé d'utiliser cette option si vous avez compilé PHP en CGI.
- --enable-inline-optimization
PHP 3: Option non disponible en PHP 3
PHP 4: Si vous avez beaucoup de mémoire disponible et que vous utilisez gcc, essayez donc ça.
- --enable-libgcc
PHP 3: Option non disponible en PHP 3
PHP 4: Active explicitement les liens avec libgcc
- --enable-maintainer-mode
PHP 3, PHP 4: Active des règles de make et de dépendances qui sont parfois absconses et ne servent pas aux utilisateurs habituels (Bref, ne l'utilisez pas).
- --enable-memory-limit
PHP 3, PHP 4: Compile avec le support de la limitation de mémoire (par défaut, no).
- --enable-safe-mode
PHP 3, PHP 4: Active le SAFE_MODE (par défaut, yes).
- --enable-satellite
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support CORBA via Satellite (Requiert ORBit)
- --enable-shared[=PKGS]
PHP 3: Option non disponible en PHP 3
PHP 4: Compile les librairies partagées (par défaut, yes).
- --enable-sigchild
PHP 3, PHP 4: Active le gestionnaire SIGCHLD propre à PHP.
- --enable-static[=PKGS]
PHP 3: Option non disponible en PHP 3
PHP 4: Compile les librairies en statique (par défaut, yes).
- --enable-sysvsem
PHP 3, PHP 4: Active le support des sémaphores System V.
- --enable-sysvshm
PHP 3, PHP 4: Active le support de partage de mémoire System V.
- --enable-trans-sid
PHP 3: Option non disponible en PHP 3
PHP 4: Active la propagation transparente des identifiants de session.
- --with-cdb[=DIR]
PHP 3, PHP 4: Active le support CDB.
- --with-config-file-path=PATH
PHP 3: Indique le chemin dans lequel aller lire le fichier php3.ini. Par défaut, c'est /usr/local/lib.
PHP 4: Indique le chemin dans lequel allet lire le fichier php.ini. Par défaut, c'est /usr/local/lib.
- --with-cpdflib[=DIR]
PHP 3: Inclut le support ClibPDF. DIR est le dossier d'installation de ClibPDF (par défaut, /usr/local).
PHP 4: Inclut le support ClibPDF.(requires cpdflib >= 2). DIR est le dossier d'installation de cpdfllib (par défaut, /usr).
- --with-esoob[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support Easysoft OOB. DIR est le dossier d'installation de OOB (par défaut, /usr/local/easysoft/oob/client).
- --with-exec-dir[=DIR]
PHP 3, PHP 4: N'autorise que les exécutables placés dans le dossier DIR, lorsque le SAFE MODE est activé (par défaut, c'est /usr/local/php/bin).
- --with-fdftk[=DIR]
PHP 3, PHP 4: Inclut le support fdftk. DIR est le dossier d'installation de fdftk (par défaut, /usr/local).
- --with-gnu-ld
PHP 3: Option non disponible en PHP 3
PHP 4: Suppose que le compilateur C utilise GNU ld (par défaut, no).
- --with-icap[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support ICAP.
- --with-imap[=DIR]
PHP 3, PHP 4: Inclut le support IMAP. DIR est le dossier d'include d'IMAP (et aussi c-client.a).
- --with-imsp[=DIR]
PHP 3: Inclut le support IMSP.(DIR est le dossier d'installation IMSP, là où il y a les dossiers d'include et libimsp.a).
PHP 4: Option non disponible en PHP 4
- --with-java[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support Java. DIR est le dossier d'installation du JDK). Cette extension peut uniquement être compilée comme "dl".
- --with-kerberos[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support Kerberos dans IMAP.
- --with-mcal[=DIR]
PHP 3, PHP 4: Inclut le support MCAL.
- --with-mcrypt[=DIR]
PHP 3, PHP 4: Inclut le support mcrypt. DIR est le dossier d'installation de mcrypt.
- --with-mhash[=DIR]
PHP 3, PHP 4: Inclut le support mhash. DIR est le dossier d'installation de mhash.
- --with-mm[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support mm pour le stockage de session.
- --with-mod_charset
PHP 3, PHP 4: Active le transfert des tables depuis le module Apache mod_charset (Rus Apache).
- --with-pdflib[=DIR]
PHP 3: Inclut le support pdflib (testé avec 0.6 et 2.0). DIR est le dossier d'installation de pdflib (par défaut, c'est /usr/local).
PHP 4: Inclut le support pdflib 3.x/4.x. DIR est le dossier d'installation de pdflib. Par défaut, c'est /usr/local.
PHP 4 et PDFlib 3.x/4.x requiert les librairies JPEG et TIFF. Lors de la compilation du support PDFlib utilise les options --with-jpeg-dir et --with-tiff-dir. Vous pouvez aussi utiliser --with-png-dir et --with-zlib-dir, pour compiler le support PNG et Zlib avec PDFlib.
- --enable-shared-pdflib
PHP 3, PHP 4: Inclut pdflib comme shared librairy.
- --with-readline[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support readline. DIR est le dossier d'installation de readline.
- --with-regex=TYPE
PHP 3: Option non disponible en PHP 3
PHP 4: Type de librairie d'expressions régulières : système, apache, php
- --with-servlet[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support servlet. DIR est le dossier d'installation de JSDK. Ce SAPI demande que l'extension Java soit compilée comme shared dl.
- --with-ming
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support Flash 4 avec Ming.
- --with-swf[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support SWF.
- --with-system-regex
PHP 3: Inactive la librairie d'expressions régulières livrée avec PHP.
PHP 4: (Obsolète) Utilise la librairie d'expressions régulières système.
- --with-tsrm-pth[=pth-config]
PHP 3: Option non disponible en PHP 3
PHP 4: Utilise GNU Pth.
- --with-tsrm-pthreads
PHP 3: Option non disponible en PHP 3
PHP 4: Utilise les threads POSIX (par défaut).
- --with-x
PHP 3: Utilise X Window System
PHP 4: Option non disponible en PHP 4
- --with-bz2[=DIR]
PHP 4: Ajoute le support bzip2. DIR est le dossier d'installation de bzip2.
- --with-zlib-dir[=DIR]
PHP 3: Dossier zlib pour pdflib 2.0 ou active le support zlib.
PHP 4: Dossier zlib pour pdflib 3.x/4.x ou active le support zlib.
- --with-zlib[=DIR]
PHP 3, PHP 4: Inclut le support zlib. (requiert zlib >= 1.0.9). DIR est le dossier d'installation de zlib (par défaut, /usr).
- --with-zziplib[=DIR]
PHP 4: Inclut le support ZZIPlib (requiert ZZIPlib >= 0.10.6). DIR est le dossier d'installation de ZZIPliby (par défaut, /usr/local).
La dernière version de ZZIPlib est disponible à http://zziplib.sourceforge.net/.
- --without-pcre-regex
PHP 3: Inactive le support des expressions régulières Perl.
PHP 4: Inactive le support des expressions régulières Perl. Utilisez --with-pcre-regex=DIR pour spécifier le dossier d'installation de PCRE, si vous n'utilisez pas la librairie livrée en standard.
- --without-posix
PHP 3: N'Inclut pas lrs fonctions POSIX.
PHP 4: Option non disponible en PHP 4; utilisez plutôt --disable-posix.
Réseau
- --with-curl[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support CURL.
- --enable-ftp
PHP 3: Option non disponible; utilisez plutôt --with-ftp
PHP 4: Active le support FTP.
- --with-ftp
PHP 3: Inclut le support FTP.
PHP 4: Option non disponible; utilisez plutôt --enable-ftp instead
- --disable-url-fopen-wrapper
PHP 3, PHP 4: Inactive le support des URL avec fopen().
Avertissement Cette option n'est disponible que jusqu'à la version 4.0.3. Les versions plus récentes fournissent un paramètre dans le fichier php.ini appelé allow_url_fopen, afin de vous éviter de faire ce choix au moment de la compilation.
- --with-mod-dav=DIR
PHP 3, PHP 4: Inclut le support DAV, grâce au module Apache mod_dav. DIR est le dossier d'installation de mod_dav (valable uniquement pour les serveurs Apache).
- --with-openssl[=DIR]
PHP 3, PHP 4: Inclut le support OpenSSL avec SNMP.
- --with-snmp[=DIR]
PHP 3, PHP 4: Inclut le support SNMP. DIR est le dossier d'installation de SNMP (par défaut, il scanne un nombre de dossiers habituels de l'installation SNMP). Utilisez la valeur de "shared" pour compiler sous forme de "dl", ou "shared,DIR" pour compiler sous forme de "dl" tout en spécifiant un dossier.
- --enable-ucd-snmp-hack
PHP 3, PHP 4: Active le hack UCD SNMP
- --enable-sockets
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support des sockets.
- --with-yaz[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support YAZ.(ANSI/NISO Z39.50). DIR est le dossier d'installation de YAZ (dossier bin).
- --enable-yp
PHP 3: Option non disponible; utilisez plutôt --with-yp
PHP 4: Active le support YellowPages (YP).
- --with-yp
PHP 3: Active le support YellowPages (YP).
PHP 4: Option non disponible; utilisez plutôt --enable-yp
- --with-mnogosearch
PHP 3, PHP 4: Inclut le support mnoGoSearch.
Comportement PHP
- --enable-magic-quotes
PHP 3, PHP 4: Active les magic quotes par défaut.
- --disable-short-tags
PHP 3, PHP 4: Désactive la forme courte des balises PHP (<? ?>).
- --enable-track-vars
PHP 3: Active le suivi des variables GET/POST/Cookie par défaut.
PHP 4: Option non disponible en PHP 4; à partir de PHP 4.0.2, cette option est toujours activée.
Serveur
- --with-aolserver-src=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Indique le chemin jusqu'à la distribution source de AOLserver
- --with-aolserver=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Indique le chemin jusqu'à la distribution installée de AOLserver.
- --with-apache[=DIR]
PHP 3, PHP 4: Compile PHP en module Apache. DIR est le dossier d'installation supérieur d'Apache (par défaut, /usr/local/etc/httpd.
- --with-apxs[=FILE]
PHP 3, PHP 4: Compile PHP comme module partagé d'Apache module. FILE est le chemin optionnel jusqu'à Apache apxs tool; par défaut, c'est apxs).
- --enable-versioning
PHP 3: Tire profit du système de versionnage et de scoping fourni par Solaris 2.x et Linux
PHP 4: Exporte uniquement les symboles nécessaires. Voyez l'installation pour plus de détails.
- --with-caudium[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Compile PHP sous forme de module Pike pour être utilisé avec le serveur web Caudium. DIR est le dossier d'installation de Caudium (par défaut, $prefix/caudium/server. Le préfixe est paramétré par l'option --prefix (par défaut, /usr/local).
- --with-fhttpd[=DIR]
PHP 3, PHP 4: Compile PHP comme module fhttpd. DIR est le dossier d'installation de fhttpd (par défaut, /usr/local/src/fhttpd).
- --with-nsapi=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Indique le chemin jusqu'au serveur Netscape
- --with-phttpd=DIR
PHP 3: Option non disponible en PHP 3
PHP 4:
- --with-pi3web=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Compile PHP comme module pour Pi3Web.
- --with-roxen=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Compile PHP comme module pour Pi3Web Pike. DIR est le dossier d'installation de Roxen (par défaut, /usr/local/roxen/server).
- --enable-roxen-zts
PHP 3: Option non disponible en PHP 3
PHP 4: Compile le module Roxen en utilisant Zend Thread Safety.
- --with-thttpd=SRCDIR
PHP 3: Option non disponible en PHP 3
PHP 4:
- --with-zeus=DIR
PHP 3: Option non disponible en PHP 3
PHP 4: Compile PHP comme module ISAPI pour Zeus.
Texte et langue
- --with-aspell[=DIR]
PHP 3, PHP 4: Inclut le support ASPELL.
- --with-gettext[=DIR]
PHP 3, PHP 4: Inclut le support GNU gettext. DIR est le dossier d'installation de gettext (par défaut, /usr/local).
- --with-iconv[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support iconv.
- --with-pspell[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Inclut le support PSPELL.
- --with-recode[=DIR]
PHP 3: Inclut le support GNU recode.
PHP 4: Inclut le support recode. DIR est le dossier d'installation de recode.
- --enable-shmop
PHP 3, PHP 4 : Inclut le support shmop.
XML
- --with-dom[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support DOM. (requiert libxml >= 2.0). DIR est le dossier d'installation de libxml (par défaut, /usr).
- --enable-sablot-errors-descriptive
PHP 3: Option non disponible en PHP 3
PHP 4: Active les erreurs descriptives.
- --with-sablot[=DIR]
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support Sablotron.
- --enable-wddx
PHP 3: Option non disponible en PHP 3
PHP 4: Active le support WDDX.
- --disable-xml
PHP 3: Option non disponible en PHP 3; Les fonctions XML ne sont pas construites par défaut. Utilisez plutôt --with-xml pour les activer.
PHP 4: Inactive le support XML, qui utilise la librairie expat, livrée avec PHP.
- --with-xml
PHP 3: Active le support XML.
PHP 4: Option non disponible en PHP 4; Le support XML est activé par défaut. Utilisez plutôt --disable-xml pour l'inactiver.
Installation sous Windows
Cette section s'applique aux systèmes Windows 95/98/Me et Windows NT/2000/XP. (La configuration n'est actuellement pas confirmée sous XP). Ne vous attendez pas à ce que PHP fonctionne sur les plateformes 16 bits, comme Windows 3.1. Parfois, on décrira les plateformes supportées sous le nom de Win32.
Il y a deux méthodes principales pour installer PHP sous Windows : soit manuellement, soit avec InstallShield.
Si vous avez Microsoft Visual Studio, vous pouvez aussi compiler PHP à partir des sources.
Une fois que PHP est installé sur votre Windows, vous pouvez aussi ajouter diverses extensions.
InstallShield sous Windows
L'installeur Windows de PHP disponible depuis les pages de téléchargement, installe la version CGI de PHP, et configure les serveurs web IIS, PWS, et Xitami. Notez bien que bien que InstallShield soit une méthode simple pour installer PHP, il est limité dans son fonctionnement, puisque l'installation automatique des extensions n'est pas prise en compte.
Installez votre serveur HTTP favori sur votre système et assurez-vous qu'il fonctionne.
Exécutez l'installeur et suivez les instructions fournies par le wizard. Deux types d'installation sont fournis : standard, qui utilise toutes les configurations par défaut les plus pratiques, et avancée, qui pose un maximum de questions pour paramétrer le plus finement.
Le wizard d'installation rassemble suffisamment d'informations pour configurer php.ini et le serveur web qui utilisera PHP. Pour IIS, mais aussi PWS sous NT Workstation, une liste de l'arboresence web est affichée, et vous pouvez sélectionner les dossiers qui utiliseront PHP.
Une fois l'installation terminée, l'installeur vous informera que vous devez redémarrer. Suivez ce conseil, ou commencez à utiliser PHP immédiatement.
| Avertissement |
Gardez bien à l'esprit que cette installation de PHP n'est pas sécurisée. Si vous voulez avoir une installation sécurisée de PHP, vous devriez commencer par lire la documentation, et choisir toutes vos options avec soin. Cet installeur automatique vous permet de réaliser l'installation en un tour de main, mais n'est pas destinée à l'utilisation sur des serveurs de production. |
Instructions Générales d'installation
Ce guide vous permet d'installer et de configurer manuellement PHP sur vos stations Windows 9x/Me/NT/2000. La première version de ce guide a été compilée par Bob Silva. La version originale est disponible (en anglais) à http://www.umesd.k12.or.us/php/win32install.html.
Ce guide fournit une aide d'installation pour :
Personal Web Server (Version la plus récente recommandée)
Internet Information Server 3 ou 4
Apache 1.3.x
Omni HTTPd 2.0b1 et plus récent
Oreilly Website Pro
Xitami
Netscape Enterprise Server, iPlanet
PHP 4 pour Windows est décliné en deux versions : un exécutable CGI (php.exe), et plusieurs modules SAPI (par exemple php4isapi.dll). Cette dernière forme est nouvelle pour PHP 4 et founit des performances améliorées ainsi que des fonctionnalités supplémentaires.
Notez cependant que les modules SAPI ne sont pas considéré comme ayant atteint une qualité de production. La raison à cela est que les modules SAPI utilisent le système de thread sécurisé de PHP, ce qui est nouveau en PHP 4, et qui n'a pas été testé et torturé suffisamment pour être considérés comme stable.
Il y a encore quelques bugs qui trainent. D'un autre côté, certains d'entre vous ont rapporté des résultats significativement meilleurs avec les modules SAPI, même si nous ne connaissons actuellement personne qui le fasse fonctionner en production. En clair, faites votre choix : soit vous avez absolument besoin de stabilité, et il vaut mieux laisser les performances SAPI de côté; soit vous avez besoin de performances, et alors c'est l'occasion de tester en production et de nous rapporter vos résultats.
Si vous choisissez l'un des modules SAPI et utilisez Windows 95, pensez à télécharger la mise à jour DCOM à Microsoft DCOM pages. Pour le module ISAPI, comme un serveur web compatible est nécessaire (testé avec IIS 4.0, PWS 4.0 et IIS 5.0). IIS 3.0 n'est pas supporté; vous devez télécharger et installer le Windows NT 4.0 Option Pack avec IIS 4.0 si vous voulez le support natif de PHP.
Voici les différentes étapes d'installation avant les étapes spécifiques au serveur.
Extrayez la distribution dans le dossier de votre choix. "C:\php\" est une bonne idée.
Vous devez vous assurer que les DLL que PHP utilise sont disponibles. La liste précise des DLL dépend du serveur web que vous utiliser, et de la méthode que vous utiliser pour faire exécuter vos script (CGI ou module). php4ts.dll est toujours nécessaire. Si vous utiliser PHP en module, (e.g. ISAPI or Apache), vous aurez besoin de la DLL ad hoc, dans le dossier sapi. Si vous utilisez des extensions PHP, vous aurez besoin des DLL associées. Pour être certains que les DLL sont accessibles, vous pouvez les copier dans le dossier système (i.e. winnt/system32 ou windows/system) ou vous pouvez vous assurer qu'elles sont dans le même dossier que l'exécutable PHP ou les autres DLL de votre serveur web (i.e. php.exe, ou php4apache.dll).
L'exécutable binaire PHP, les modules SAPI, et certaines extensions utilisent des DLL externes. Assurez vous que ces DLL sont dans votre distribution, et dans un dossier qui est cité dans le PATH Windows. Le mieux à faire est de copier les fichiers ci-dessous dans votre dossier système, qui est généralement :
Les fichiers à copier sont :c:\windows\system pour Windows 9x/Me c:\winnt\system32 pour Windows NT/2000 'php4ts.dll', s'il existe, écrasez le Les fichiers 'dlls' de votre distribution. Si vous les avez déjà installé, ne les remplacez pas, sauf si quelquechose ne fonctionne pas correctement (avant de les écraser, il est recommandé de les sauver de toutes manières, au cas où quelque chose irait de travers). Téléchargez la dernière version de Microsoft Data Access Components (MDAC) pour votre plateforme, spécialement si vous utilisez Microsoft Windows 9x/NT4. MDAC est disponible à http://www.microsoft.com/data/.
Copiez le fichier 'php.ini-dist' dans votre dossier '%WINDOWS%' sous Windows 95/98, ou vers votre dossier '%SYSTEMROOT%' sous Windows NT ou Windows 2000 et renommez le en 'php.ini'. Votre dossier '%WINDOWS%' ou '%SYSTEMROOT%' est généralement :
c:\windows pour Windows 9x/Me c:\winnt ou c:\winnt40 pour les serveurs NT/2000 Il y a deux fichiers ini, distribués dans le fichier zip, php.ini-dist et php.ini-optimized. Nous vous recommandons d'utiliser php.ini-optimized, car nous l'avons optimisé d'un point de vue sécurité et vitesse d'exécution. Le mieux est tout de même de lire le fichier de configuration php.ini et de choisir vos options manuellement. Si vous voulez atteindre un meilleur niveau de sécurité, c'est par ce moyen que vous pourez le faire, même si PHP focntionne parfaitement avec les configurations par défaut.
Editez votre fichier php.ini :
Vous devez changer votre option 'extension_dir' pour qu'il pointe sur votre dossier d'installation PHP, ou vers l'endroit où vous avez installé vos 'php_*.dll'. ex: c:\php\extensions
Si vous utilisez Omni Httpd, sautez l'étape suivante. Modifiez 'doc_root' pour qu'il pointe sur votre racine de serveur web. ex: c:\apache\htdocs ou c:\webroot.
Choisissez les modules que vous voulez charger lorsque PHP démarre. Vous pouvez décommenter les lignes 'extension=php_*.dll' pour charger ces modules. Certains modules requièrent que des librairies supplémentaires soient installées sur votre système. La FAQ PHP a plus d'informations sur ces librairies. Vous pouvez aussi charger dynamiquement ces librairies avec dl("php_*.dll");. Voyez la section sur les extensions Windows.
Sous PWS et IIS, vous pouvez modifier le fichier browscap.ini pour qu'il pointe sur : c:\windows\system\inetsrv\browscap.ini sous Windows 9x/Me et c:\winnt\system32\inetsrv\browscap.ini sous NT/2000.
Notez que le dossier mibs fourni avec la distribution Windows, contient des fichiers de support du protocole SNMP. Ce dpssier doit être déplacé dans le dossier DRIVE:\usr\mibs (DRIVE est le périphérique où PHP est installé.)
Compilation des sources
Avant de commencer, il est bon de se poser la question suivante : "Pourquoi la compilation de PHP sous Windows est si difficile?". Deux raisons viennent immédiatement à l'esprit :
Windows ne dispose pas (encore) d'une grande communauté de développeurs qui partagent librement leurs sources. La conséquence directe est que les investissements nécessaires en infrastructure pour supporter ce type de développement n'ont pas été faits. Ce qui fait que le portage des utilitaires Unix a été la solution pour pallier ce manque. Ne soyez donc pas surpris de rencontrer cette parenté de temps en temps.
La majorité des instructions que vous allez rencontrer sont du type : "faire et oublier". Alors, asseyez-vous confortablement et suivez aussi scrupuleusement que possible les instructions.
Préparation
Avant de commencer, il faut télécharger un maximum de fichiers!
Pour commencer, téléchargez le Cygwin depuis le miroir cygwin le plus proche. Cela vous donnera les utilitaires GNU les plus populaires, utilisés durant le processus de compilation.
Téléchargez le reste des utilitaires de compilation dont vous aurez besoin depuis le site PHP à http://www.php.net/extra/win32build.zip.
Téléchargez le code source du DNS utilisé par PHP à http://www.php.net/extra/bindlib_w32.zip. Il remplacera le fichier resolv.lib inclut dans win32build.zip.
Si vous n'avez pas d'utilitaire de dézippage, vous devez en télécharger un. Une version libre est disponible à InfoZip.
Finalement, vous aurez besoin des sources PHP 4 elles-mêmes!! Les dernières versions sont accessibles sur le serveur CVS anonyme. Si vous téléchargez une version intermédiaire ou la source, vous devez non seulement extraire les fichiers, mais aussi convertir les nouvelles lignes en leur équivalent windows (crlf) dans les fichiers *.dsp et *.dsw avant que Microsoft Visual C++ ne soit capable de les comprendre.
Note : Placez les dossiers Zend et TSRM dans le dossier php4 pour que les projets puissent les trouver durant la compilation.
Mettre tout ensemble
Suivez les instructions pour installer l'utilitaire d'unzip de votre choix.
Exécutez setup.exe et suivez les instructions d'installation. Si vous décidez d'installer dans un autre dossier que c:\cygnus, indiquez le au processus de compilation en modifiant la variable d'environnement Cygwin. Sous Windows 9x/Me, modifier une variable d'environnement se fait en ajoutant une ligne dans le fichier autoexec.bat. Sous Windows NT, allez dans le menu "Démarrer => Paramètres => Panneau de contrôle => Système " ("My Computer => Control Panel => System ") et sélectionnez l'onglet "environnement" ("environment").
Avertissement Créez un dossier temporaire pour Cygwin, sinon de nombreuses commandes (comme bison) échoueront. Sous Windows 9x/Me, mkdir C:\TMP. Sous Windows NT, mkdir %SystemDrive%\tmp.
Créez un dossier et dézippez win32build.zip dedans.
Lancez Microsoft Visual C++, et allez dans le menu "select Tools => Options". Dans le dialogue, sélectionnez l'onglet "directories". Assurez-vous que cygwin\bin, win32build\include, et win32build\lib sont bien dans les menus déroulants "Executables", "Include", et "Library". (Pour ajouter une entrée, sélectionnez une ligne blanche, et tapez). Une entrée typique ressemble à ceci :
c:\cygnus\bin
c:\php-win32build\include
c:\php-win32build\lib
Pressez "OK", et sortez de Visual C++.
Créez un autre dossier et dézippez bindlib_w32.zip dedans. Décidez si vous avez besoin des symboles de débuggage (bindlib - Win32 Debug) ou non (bindlib - Win32 Release). Compilez la configuration adéquate :
Pour les utilisateurs de GUI, lancez VC++, puis sélectionnez le menu "File => Open Workspace" et "bindlib". Puis sélectionnez "Build=>Set Active Configuration" et sélectionnez la configuration voulue. Enfin, sélectionnez "Build=>Rebuild All".
Pour les utilisateurs en ligne de commande, assurez-vous que vous avez enregistré les variables d'environnement C++, ou que vous avez exécuté vcvars.bat. Exécutez maintenant l'une des commandes suivantes :
msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"
msdev bindlib.dsp /MAKE "bindlib - Win32 Release"
A ce stade, vous avez une librairie resolv.lib utilisable, soit dans votre dossier Debug, soit sans le dossier Release. Copiez ce fichier dans votre dossier win32build\lib, en remplaçant le fichier du même nom.
Compilation
La meilleure façon de compiler est de commander par la version CGI/exécutable.
Pour les utilisateurs GUI, lancez VC++, puis sélectionnez le menu "File => Open Workspace" et sélectionnez "php4ts". Ensuite, sélectionnez le menu "Build=>Set Active Configuration", et sélectionnez la configuration voulue. Finalement, sélectionnez le menu "Build=>Rebuild All".
Pour les utilisateurs en ligne de commande, assurez-vous que vous avez enregistré les variables d'environnement C++, ou que vous avez exécuté vcvars.bat. Exécutez maintenant l'une des commandes suivantes :
msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"
msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"
A ce stade, vous avez une librairie php.exe utilisable, soit dans votre dossier Debug_TS soit sans le dossier Release_TS.
Répétez les instructions ci-dessus avec php4isapi.dsp (qui est dans sapi\isapi) pour compiler le code nécessaire pour intégrer PHP avec Microsoft IIS.
Installation des extensions sous Windows
Après avoir installé PHP et votre serveur web sous Windows, vous voudrez sÛrement ajouter quelques extensions bien pratiques. La table suivante liste une partie des extensions disponibles. Comme indiqué dans le manuel, vous pouvez choisir quelles extensions vous voulez charger en décommentant la ligne 'extension=php_*.dll' dans le fichier php.ini. Vous pouvez aussi charger dynamiquement un module avec la fonction dl().
Les fichiers DLLs des extensions PHP sont préfixés par 'php_' en PHP 4, et 'php3_' en PHP 3. Cela évite la confusion des extensions PHP et de leurs librairies.
Note : En PHP 4.0.4pl1, les extensions BCMath, BCMath,Calendar, COM, FTP, MySQL, ODBC, PCRE, Sessions, WDDX et XML sont activées par défaut. Vous n'avez rien à faire pour qu'elles soient inclues. Lisez le fichier README.txt ou install.txt dans votre distribution pour connaître la liste des modules par défaut.
Note : Certaines de ces extensions requièrent des librairies DLL supplémentaires pour fonctionner correctement. Certaines d'entre elles sont disponibles dans la distribution. dans le dossier dlls mais certaines (comme Oracle (php_oci8.dll)), demandent des dlls qui ne sont pas dans la distribution.
Copiez les dlls fournies depuis le dossier dlls dans votre PATH Windows. Les bons emplacements sont typiquement
Si vous les avez déjà d'installées sur votre système, ne les écrasez que si PHP ne fonctionne pas correctement (et de toutes manières, faites une sauvegarde de ces DLL, en cas de problème).
c:\windows\system pour Windows 9x/Me c:\winnt\system32 pour Windows NT/2000
Tableau 2-1. Extensions PHP
| Extension | Description | Notes |
|---|---|---|
| php_bz2.dll | Fonctions de compression Bzip2 | Aucune |
| php_calendar.dll | Fonctions de conversions calendaires (Depuis PHP 4.03, elles sont activées par défaut) | Activée automatiquement depuis PHP 4.0.3 |
| php_cpdf.dll | Fonctions ClibPDF | |
| php_crypt.dll | Fonctions de cryptage | Aucune |
| php_ctype.dll | Fonctions ctype | Aucune |
| php_curl.dll | Fonctions CURL | Requiert : libeay32.dll, ssleay32.dll (fournies) |
| php_cybercash.dll | Fonctions de paiement Cybercash | Aucune |
| php_db.dll | Fonctions DBM | Obsolète. Utilisez DBA à la place (php_dba.dll) |
| php_dba.dll | Fonctions dbm-style | Aucune |
| php_dbase.dll | Fonctions DBase | Aucune |
| php3_dbm.dll | Librairie d'émulation GDBM via Berkely DB2 | Aucune |
| php_domxml.dll | Fonctions DOM XML | Requiert : libxml2.dll (fournie) |
| php_dotnet.dll | Fonctions .NET | Aucune |
| php_exif.dll | Entêtes EXIF des images JPEG | Aucune |
| php_fbsql.dll | Fonctions FrontBase | Aucune |
| php_fdf.dll | Fonction FDF (Forms Data Format) | Requiert: fdftk.dll (fournie) |
| php_filepro.dll | Lecture des bases filepro | Accès en lecture seule |
| php_ftp.dll | Fonctions FTP | Activée par défaut depuis PHP 4.0.3 |
| php_gd.dll | Bibliothèque GD (pour les manipulations d'images) | Aucune |
| php_gettext.dll | Fonctions GNU Gettext | Requiert : gnu_gettext.dll (fournie) |
| php_hyperwave.dll | Fonctions HyperWave | Aucune |
| php_iconv.dll | Fonctions de conversions ICONV | Requiert : iconv-1.3.dll (fournie) |
| php_ifx.dll | Fonctions Informix | Requiert: librairies Informix |
| php_iisfunc.dll | Fonctions IIS | Aucune |
| php_imap.dll | Fonctions IMAP 4(en PHP 3: php3_imap4r1.dll) | PHP 3: php3_imap4r1.dll |
| php_ingres.dll | Fonctions Ingres II | Requiert: librairies Ingres II |
| php_interbase.dll | Fonctions InterBase | Requiert: gds32.dll (fournie) |
| php_java.dll | Extension Java | Requiert: jvm.dll (fournie) |
| php_ldap.dll | Fonctions LDAP | Requiert: libsasl.dll (fournie) |
| php_mhash.dll | Fonctions Mhash | Aucune |
| php_ming.dll | Fonctions Ming pour Flash | Aucune |
| php_msql.dll | Fonctions mSQL | Requiert: msql.dll (fournie) |
| php3_msql1.dll | Fonctions mSQL 1 | Aucune |
| php3_msql2.dll | Fonctions mSQL 2 | Aucune |
| php_mssql.dll | Fonctions MSSQL (anciennement php_mssql70.dll, requiert MSSQL DB-Libraries) | Requiert: ntwdblib.dll (fournie) |
| php3_mysql.dll | Fonctions MySQL (Activées par défaut en PHP 4) | Aucune |
| php_nsmail.dll | Fonctions Netscape mail | Aucune |
| php3_oci73.dll | Fonctions Oracle | Aucune |
| php_oci8.dll | Fonctions Oracle 8 | Requiert: librairies clientes Oracle 8 |
| php_openssl.dll | Fonctions OpenSSL | Requiert: libeay32.dll (fournie) |
| php_oracle.dll | Fonctions Oracle | Requiert: librairies clientes Oracle 7 |
| php_pdf.dll | Fonctions PDF | Aucune |
| php_pgsql.dll | Fonctions PostgreSQL | Aucune |
| php_printer.dll | Fonctions d'impression | Aucune |
| php_sablot.dll | Focntions XSLT | Requiert: sablot.dll (fournie) |
| php_snmp.dll | Fonctions SNMP get et walk | NT uniquement! |
| php_sybase_ct.dll | Fonctions Sybase | Requiert: librairies clientes Sybase |
| php_yaz.dll | Fonctions YAZ | Aucune |
| php_zlib.dll | Fonctions ZLib | Aucune |
Installation du serveur Apache
Cette section contient des notes spécifiques pour l'installation de PHP avec Apache, aussi bien pour la version Unix que Windows.
Détails pour l'installation de PHP sous Apache sous Unix.
Il y a deux méthodes d'installation de PHP avec Apache 1.3.x sous Windows. L'une passe par les CGI (php.exe), l'autre est d'utiliser la DLL de module d'apache. Dans les deux cas, vous devrez arrêter le serveur Apache, et éditer le fichier srm.conf ou httpd.conf, pour configurer Apache avec PHP.
Vous pouvez sélectionner des options à ajouter au fichier configure à la ligne 8 depuis la liste complète des options de configuration.
Exemple 2-5. Instructions d'installation (version module)
|
Suivant votre installation d'Apache et votre variante d'Unix, il existe de nombreuses façons d'arrêter et redémarrer Apache. Voici une liste des commandes typiques, pour différentes installations. Remplacez /path/to/ par le chemin d'accès à vos applications sur votre système.
1. Nombreuses variantes Linux SysV : /etc/rc.d/init.d/httpd restart 2. Avec les scripts apachectl : /path/to/apachectl stop /path/to/apachectl start 3. httpdctl et httpsdctl (utilisant OpenSSL), similaire à apachectl: /path/to/httpsdctl stop /path/to/httpsdctl start 4. En utilisant mod_ssl, ou un autre seveur SSL, manuellement : /path/to/apachectl stop /path/to/apachectl startssl |
Différents exemples de compilation PHP pour Apache suivent :
Cette commande va créer une librairie partagée libphp4.so qui sera chargée par Apache avec une ligne LoadModule dans le fichier httpd.conf. Le support PostgreSQL est aussi inclut dans libphp4.so.
Cette commande va créer une autre librairie partagée libphp4.so, mais va aussi créer une librairie partagée pgsql.so qui sera chargée dans PHP avec les options de configurations du fichier php.ini ou par chargement dynamique avec dl().
Cette commande va créer une autre librairie partagée libmodphp4.a, un fichier mod_php4.c et quelques fichiers compagnons dans le dossier src/modules/php4 de dossier Apache. Puis, vous devez compiler Apache avec --activate-module=src/modules/php4/libphp4.a et le système de compilation d'Apache va créer un fichier libphp4.a et le lien statiquement avec httpd. Le support PostgreSQL est alors inclut directement dans l'exécutable httpd, ce qui fait que le résultat final est un fichier unique httpd, qui inclus Apache et PHP.
Identique à la version précédente, mais au lieu d'inclure le support PostgreSQL directement dans l'exécutable final httpd, vous allez obtenir une librairie partagée pgsql.so que vous pouvez charger dans PHP soit grâce au fichier de configuration php.ini ou dynamiquement avec dl().
Lorsque vous faites le choix entre les différents modes de compilation de PHP, vous devez prendre en compte leurs avantages et inconvénients respectifs. Les objets partagés permettent de compiler PHP et Apache de manière séparée, et vous n'aurez pas à compiler l'ensemble pour faire évoluer PHP. La compilation statique permet de charger et d'éxécuter plus rapidement PHP. Pour plus d'informations, voyez webpage on DSO support.
Détails sur l'installation de PHP sous Windows avec Apache 1.3.x
Il y a deux méthodes pour faire fonctionner PHP avec Apache 1.3.x sous Windows. La première est d'utiliser l'exécutable CGI (php.exe), l'autre est d'utiliser les modules Apache DLL. Dans les deux cas, vous devez arrêter le serveur Apache, éditer votre fichier srm.conf ou httpd.conf pour configurer Apache.
Bien qu'il puisse y avoir quelques différences de configurations de PHP sous Apache, le processus reste simple et à la portée du néophyte. Reportez-vous aux documentations Apache pour plus de détails sur ces directives.
Si vous avez dézippé le package dans C:\PHP\ comme indiqué dans Instructions Générales d'installation, vous devez insérer les lignes suivantes dans votre fichier srm.conf ou httpd.conf pour qu'il fonctionne en CGI :
ScriptAlias /php/ "c:/php/"
AddType application/x-httpd-php .php .phtml
Action application/x-httpd-php "/php/php.exe"
Si vous voulez utiliser PHP comme module Apache, vous devez déplacer le fichier php4ts.dll dans le dossier windows/system (pour Windows 9x/Me) ou winnt/system32 (pour Windows NT/2000), en écrasant les anciennes versions. Puis, vous devez ajouter les deux lignes suivantes dans le fichier de configuration Apache :
LoadModule php4_module c:/php/sapi/php4apache.dll
AddType application/x-httpd-php .php .phtml
Note : Avec Apache 1.3.22 pour Windows, le fichier de configuration par défaut (httpd.conf-dist-win) a une directive ClearModuleList incluse par défaut. Si cette directive est utilisé, il est nécessaire de mettre une ligne AddModule mod_php4.c à la liste AddModule, sinon PHP ne sera pas enregistré comme Module Apache.
Pour utiliser les fonctionnalités de mise en évidence du code source, créez simplement un script PHP et ajoutez le code suivant : <?php show_source("original_php_script.php"); ?>. Remplacez le fichier original_php_script.php par le fichier que vous voulez afficher : c'est la seule manière de le faire, car il n'y a pas de fonctionnalités phps sous Windows.
Note : Sous Win-Apache tous les antislash des noms de chemins tels que "c:\directory\file.ext", doivent être convertis en slash c'est à dire "c:/directory/file.ext".
CGI/ Installation pour exécution en ligne de commande
Par défaut, PHP est compilé comme une CGI. Si PHP peut être incorporé au serveur web que vous utilisez en tant que module, de manière générale c'est cette solution que vous devriez adopter pour des raisons de performances. Cependant, la version CGI permet aux utilisateurs de lancer des scripts PHP sous leur UID respectives. Lisez attentivement le chapitre consacré à la sécurité si vous souhaitez utiliser cette solution.
Tests
Si vous avez compilé PHP comme programme CGI, vous pouvez tester votre produit en tapant : make test. C'est toujours une bonne chose de tester le résultat d'une compilation. Cela vous permet de repérer des problèmes entre PHP et votre plate-forme, bien plus facilement que si vous attendez.
Performances
Si vous avez compilé PHP comme programme CGI, vous pouvez évaluer les performances de PHP 3 avec la commande make bench. Notez que si le safe mode est activé (par défaut), vous ne risquez pas de voir l'évaluation s'arrêter une fois les 30 secondes réglementaires écoulées. En effet, la fonction set_time_limit() ne peut pas être utilisée si le safe mode fonctionne. Utilisez l'option max_execution_time pour contrôler le temps d'éxécution de vos scripts. make bench ignore le fichier de configuration file.
Note : make bench n'est disponible qu'en PHP 3.
Installation avec les serveurs fhttpd
Pour compiler PHP comme un module fhttpd, répondre "yes" à la question "Build as an fhttpd module ?" (cela correspond à l'option de configuration --with-fhttpd=DIR et spécifier la racine de la distribution fhttpd. Le répertoire par défaut est: /usr/local/src/fhttpd. Si vous utilisez fhttpd, compiler PHP en module vous permettra d'obtenir des performances supérieures, plus de contrôle et la possibilité d'exécution à distance.
Installation sur serveur Caudium
PHP 4 peut être compilé comme module Pike pour le serveur web Caudium. Notez que ce mode n'est pas supporté en PHP 3. Suivez simplement les instructions suivantes pour installer PHP 4 sur un serveur Caudium.
Exemple 2-6. Instructions d'installation Caudium
|
Vous pouvez bien sÛr compiler votre module Caudium avec les diverses extensions disponibles. Voyez la liste complète des options de configuration pour une liste exhaustive.
Note : Lorsque vous ajoutez le support MySQL à PHP 4, vous devez-vous assurer que le client MySQL normal est utilisé. Sinon, il peut y avoir des conflits avec Pike, qui dispose déjà du support MySQL. Vous pouvez le faire en spécifiant le dossier d'installation de MySQL grâce à l'option --with-mysql.
Installation avec les serveurs IIS/PWS
Cette section contient des notes sur l'installation de PHP avec IIS ( Microsoft Internet Information Server) : PWS/IIS 3, PWS 4 ou plus récent et IIS 4 ou plus récent.
Windows et PWS/IIS 3
La méthode recommandée pour configurer ces serveurs est d'utiliser le fichier INF inclus dans la distribution (php_iis_reg.inf). Vous pouvez éditer ce fichier, pour vous assurer que les extenstions et les dossiers d'installation de PHP sont bien ceux de votre configuration. Ou alors, vous pouvez suivre les instructions suivantes :
| Avertissement |
ATTENTION: Ces instructions requièrent la manipulation du fichier de registry de Windows. Une erreur peut laisser votre système dans un état instable. Nous vous recommandons vivement de sauvegarder ce fichier en lieu sÛr. L'équipe de développement et les traducteurs de cette documentation ne pourront pas être tenus responsable d'un quelconque dommage qui pourrait survenir dans votre registry. |
Lancez Regedit.
Naviguez jusqu'à : HKEY_LOCAL_MACHINE /System /CurrentControlSet /Services /W3Svc /Parameters /ScriptMap.
Dans le menu "edit", sélectionnez : New->String Value.
Entrez l'extension que vous voulez utiliser pour les scripts PHP. Par exemple : .php
Double-cliquez sur la chaîne, et entrez le chemin jusqu'à php.exe dans le champ "value data". ex: c:\php\php.exe.
Les étapes suivantes n'affectent pas la configuration du serveur web, et ne s'appliquent que si vous voulez que vos scripts PHP soient exécutés lorsqu'il sont exécutés en ligne de commande (par exemple, run c:\messcripts\test.php) ou en double-cliquant sur l'icone. Vous pouvez ignorer ces étapes si vous préférez que vos scripts PHP s'ouvrent dans éditeur de texte, plutôt que de les voir s'exécuter lorsque vous double-cliquez dessus.
Répétez ces instructions pour toutes les extensions que vous voulez associer aux scripts PHP.
Naviguez jusqu'à : HKEY_CLASSES_ROOT
Dans le menu edit, sélectionnez: New->Key.
Donnez le nom de votre extension à la clé : ex: .php
Sélectionnez le nom de la nouvelle clée dans le panneau de droite, et double cliquez dans "default value", puis entrez phpfile.
Répétez ces instructions pour toutes les extensions que vous avez associées aux scripts PHP.
Créez une autre New->Key sous HKEY_CLASSES_ROOT et nommez-la phpfile.
Sélectionnez la nouvelle clé phpfile et dans le panneau de doite, double-cliquez dans "default value" et entrez PHP Script.
Faites un clic droit dans phpfile et sélectionnez New->Key, appelez-le Shell.
Faites un clic droit dans Shell et sélectionnez New->Key, appelez-le open.
Faites un clic droit dans open et sélectionnez New->Key, appelez-le command.
Sélectionnez la nouvelle clé command et dans le panneau de droite, faites un double clic dans "default value", puis entrez le chemin jusqu'à php.exe. ex: c:\php\php.exe -q %1. (n'oubliez pas le %1).
Quittez Regedit.
Si vous utilisez PWS sous Windows, redémarrez pour prendre en compte la nouvelle registry.
Les utilisateurs de PWS et IIS 3 sont prêts à utiliser leur serveur. Avec IIS 3, vous pouvez utiliser un outil bien pratique de Steven Genusa pour configurer votre carte des scripts.
Windows et PWS 4 ou plus récent
Pour installer PHP sous Windows avec PWS 4 ou plus récent, vous avez deux options : l'une est d'avoir PHP sous forme de CGI, l'autre est d'utiliser les modules SAPI, sous forme de DLL.
Si vous optez pour le CGI, faites ceci :
Editez le fichier pws-php4cgi.reg (dans le dossier sapi) pour indiquer la localisation de votre fichier php.exe. Les slash doivent être échappés. Par exemple : [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\PHP\\php.exe"
Dans le gestionnaire PWS Manager, faites un clic droit sur les dossiers qui supporteront PHP, et sélectionnez "Properties". Cochez l'option "Execute" et confirmez.
Si vous optez pour les modules ISAPI, faites ceci :
Editez le fichier pws-php4isapi.reg (dans le dossier sapi) pour indiquer la localisation de votre fichier php4isapi.dll. Les slash doivent être échappés. Par exemple : [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\PHP\\sapi\\php4isapi.dll"
Dans le gestionnaire PWS Manager, faites un clic droit sur les dossiers qui supporteront PHP, et sélectionnez "Properties". Cochez l'option "Execute" et confirmez.
Windows NT/2000 et IIS 4 ou plus récent
Pour installer PHP sous Windows NT/2000 serveyr avec IIS 4 ou plus récent, vous avez deux options : l'une est d'avoir PHP sous forme de CGI, l'autre est d'utiliser les modules SAPI, sous forme de DLL.
Dans les deux cas, vous devez lancer la console "Microsoft Management" (elle peut aussi s'appeler "Internet Services Manager". Elle est située soit dans "Windows NT 4.0 Option Pack" ou dans "Control Panel=>Administrative Tools" sous Windows 2000). Puis, faites un clic droit sur votre dossier web (qui apparaitra probablement comme Default Web Server), et sélectionnez "Properties".
Si vous optez pour le CGI, faites ceci :
Sous "Home Directory", "Virtual Directory", ou "Directory", cliquez sur le bouton "Configuration", et sélectionnez l'onglet "App Mappings".
Cliquez sur "Add", puis dans la boîte "Executable", tapez : c:\php\php.exe (si vous avez installé PHP dans le dossier c:\php\.)
Dans la boîte "Extension", tapez le nom de l'extension que vous voulez associer aux scripts PHP. Laissez "Method exclusions" vide, et cochez "Script engine". Vous pouvez aussi préférer cocher la boîte 'check that file exists' - pour un coÛt faible, IIS (ou PWS) s'assirurera que le script existe, et résoudra les problèmes d'autentification avant de démarrer PHP. Cela signifie que vous obtiendrez des messages d'erreur 404 intelligents, plutôt que d'avoir simplement une plainte du serveur comme quoi les CGI n'ont rien retournés.
Répétez les étapes 3 et 4 pour chaque extension que vous souhaitez associer aux scripts PHP. (.php et .phtml sont les plus répandues.)
Configurer la sécurité nécessaire (dans "Internet Service Manager"), et si votre serveur NT utilise NTFS, ajoutez les droits adéquats pour I_USR_, au dossier qui contient php.exe.
Si vous optez pour les modules ISAPI, faites ceci :
Si vous ne voulez pas effectuer des authentifications HTTP avec PHP, vous pouvez (et devez) sauter cette étape. Avec ISAPI Filters, ajoutez un nouveau filtre ISAPI. Utilisez PHP comme nom de filtre, et ajoutez simplement le chemin jusqu'à php4isapi.dll.
Sous "Home Directory", cliquez sur le bouton "Configuration". Ajoutez une nouvelle entrée dans "Application Mappings". Utilisez le chemin jusqu'à php4isapi.dll comme "Executable", indiquez ".php" comme extension, laissez "Method exclusions" vide, et cochez "Script engine".
Arrêtez totalement IIS (NET STOP iisadmin)
Démarrez IIS (NET START w3svc)
Installation sous Netscape et iPlanet Enterprise Serveur
Cette section contient les notes et détails spécifique à l'installation Netscape et iPlanet, aussi bien pour Sun Solaris que Windows.
Vous pouvez trouvez plus d'informations sur la configuration de PHP avec Netscape Enterprise Server : http://benoit.noss.free.fr/php/install-php4.html
Installer PHP avec Netscape sous Sun Solaris
Pour compiler PHP avec NES ou iPlanet, indiquez le bon dossier d'installation pour l'option de configuration --with-nsapi = DIR option. Le dossier par défaut est généralement /opt/netscape/suitespot/. Lisez aussi /php-xxx-version/sapi/nsapi/nsapi-readme.txt.
Exemple 2-7. Exemple d'installation pour Netscape Enterprise sous Solaris
|
D'abord, vous devez ajouter des chemins dans la variable LD_LIBRARY_PATH pour que PHP trouve toutes les librairies partagées. Le mieux est de le faire dans le script de démarrage de votre serveur Netscape. Les utilisateurs Windows peuvent probablement ignorer cette étape. Le script de démarrage est situé dans : /path/to/server/https-servername/start
Vous pouvez aussi avoir besoin d'éditer les fichiers de configuration qui sont situés dans : /path/to/server/https-servername/config/.
Exemple 2-8. Exemple de configuration pour Netscape Enterprise
|
Si vous utilisez Netscape Enterprise 4.x, alors, il faut utiliser ceci :
Exemple 2-9. Exemple de configuration pour Netscape Enterprise 4.x
|
Installer PHP avec Netscape Enterprise sous Windows
Pour installer PHP sous forme de CGI (pour Netscape Enterprise Server, iPlanet, peut être Fastrack), suivez ces instructions :
Copiez le fichier php4ts.dll dans votre dossier systemroot (le dossier où vous avez installé windows)
Faîtes un fichier d'association depuis la ligne de commande. Tapez les lignes suivantes :
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
Dans le serveur Netscape Enterprise Administration Server, créez un dossier shellcgi et supprimez le aussitôt (cette opération créee 5 lignes importantes dans le fichier obj.conf et permet au serveur de gérer les scripts CGI).
Dans le serveur Netscape Enterprise Administration Server, créeez un nouveau type MIME (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).
Recommencez pour chaque instance de serveur web qui devra exécuter PHP.
Plus de détails sur la configuration de PHP comme CGI sont disponibles à http://benoit.noss.free.fr/php/install-php.html
Pour installer PHP avec l'interface NSAPI (pour Netscape Enterprise Server, iPlanet, peut-être Fastrack), faîtes ceci :
Copiez le fichier php4ts.dll dans votre dossier systemroot (le dossier où vous avez installé windows)
Faîtes un fichier d'association depuis la ligne de commande. Tapez les lignes suivantes :
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
Dans le serveur Netscape Enterprise Administration Server, créeez un nouveau type MIME (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).
Stoppez votre serveur web et éditez le fichier obj.conf. A la fin de la section Init, placez ces deux lignes (obligatoirement après l'init de type MIME) :
Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" errorString="Failed to initialise PHP!"
Dans la section < Object name="default" >, placez cette ligne, obligatoirement après toutes les lignes 'ObjectType' et avamt les lignes 'AddLog' :
Service fn="php4_execute" type="magnus-internal/x-httpd-php"
A la fin du fichier, créez un nouvel objet appelé x-httpd-php, en insérant ces lignes :
+<Object name="x-httpd-php"> +ObjectType fn="force-type" type="magnus-internal/x-httpd-php" +Service fn=php4_execute +</Object>
Redémarrez votre serveur web, et validez les modifications
Recommencez pour chaque serveur qui doit utiliser PHP.
Plus ded détails sur la configiration de PHP en filtre NSAPI sont disponibles : http://benoit.noss.free.fr/php/install-php4.html
Installation OmniHTTPd
Cette section contient des notes et conseils spécifiques à OmniHTTPd.
OmniHTTPd 2.0b1 et plus récent pour Windows
Vous devez compléter les étapes suivantes pour configurer PHP avec OmniHTTPd. Ceci est une installation sous forme de CGI. SAPI est supporté par OmniHTTPd, mais des tests ont montrés que ce n'est pas stable d'utiliser PHP en module ISAPI avec OmniHTTPd.
Step 1: Installez Omni server.
Step 2: Faites un clic-droit sur l'icone bleue d'OmniHTTPd, sur le bureau, et sélectionnez Properties
Step 3: Cliquez sur Web Server Global Settings
Step 4: Dans l'onglet 'External', entrez: virtual = .php | actual = c:\path-to-php-dir\php.exe, et utilisez le bouton "Add".
Step 5: Dans l'onglet Mime, entrez: virtual = wwwserver/stdcgi | actual = .php et utilisez le bouton "Add".
Step 6: Cliquez sur OK.
Réptez les étapes 2 à 6 pour chaque extension que vous voulez associer à PHP.
Note : Certains packages OmniHTTPd sont livrés avec le support PHP déjà intégré. Vous pouvez choisir au moment de la configuration de faire un paramétrage poussé et de décocher le support PHP. Nous vous conseillons d'utiliser les dernières versions de PHP. Certains serveurs OmniHTTPd sont encore livrés avec des versions beta de PHP : il est recommandé de ne pas les installer, mais d'installer votre propre version. Si le serveur est déjà sur votre machine, vous pouvez utiliser le bouton "Replace" dans les étapes 4 et 5 pour en choisir un nouveau et à jour.
Installation Oreilly Website Pro Server
Cette section contient les conseils d'installation spécifiques à Oreilly Website Pro.
Oreilly Website Pro 2.5 et plus récent pour Windows
Cette liste décrit comment installer PHP comme CGI exécutable ou module ISAPI avec Oreilly Website Pro sous Windows.
Editez les "Server Properties" et sélectionnez l'onglet "Mapping".
Dans la "List" sélectionnez "Associations" et entrez le nom de l'extension voulue (".php") et le chemin jusqu'à l'exécutable (ex. c:\php\php.exe) ou la DLL ISAPI (ex. c:\php\sapi\php4isapi.dll).
Sélectionnez "Content Types", ajoutez la même extension ".php" et entrez le "content type". Si vous choisissez la forme CGI, entrez "wwwserver/shellcgi"; si vous choisissez la forme module ISAPI, entrez "wwwserver/isapi" (sans les guillemets).
Installation Xitami
Cette section contient les conseils d'installation spécifiques à Xitami.
Xitami pour Windows
Cette liste décrit comment installer PHP comme CGI exécutable ou module ISAPI avec Xitami sous Windows.
Assurez-vous que le serveur web fonctionne, et allez dans la console d'administration du serveur (généralement http://127.0.0.1/admin), puis cliquez sur "Configuration".
Naviguez dans les "Filters", et ajoutez l'extension que vous souhaitez (souvent ".php") dans le champs "File extensions".
Dans la commande "Filter", ajoutez le nom et le chemin de votre exécutable PHP (souvent c:\php\php.exe).
Cliquez sur le bouton "Save".
Autres serveurs web
PHP peut être compilé pour fonctionner avec de nombreux autres serveurs web. Reportez-vous à Options particulières aux serveurs web pour une liste complète des options de configuration. Les exécutables PHP CGI sont compatibles avec la majorité des serveurs supportant les interfaces CGI.
Des problèmes?
Lisez la FAQ
Certains problèmes sont récurrents : les plus communs sont listés dans la FAQ PHP, disponible à http://www.php.net/FAQ.php. N'envoyez pas de rapport de bug ou de courriers personnels sur la liste de diffusion. Le système de bug est aussi capable de traiter les suggestions.
Rapports de Bug
Si vous pensez avoir trouvé un bug dans PHP, n'oubliez pas de le signaler. L'équipe de développement PHP ne le connaît peut être pas, et si vous ne le signaler pas, vos chances de voir le bug corrigé sont nulles. Vous pouvez rapporter des bugs grâce au système de suivi, accessible à http://bugs.php.net/.
Lisez les guides (Les bugs : ce qu'il faut faire, et ce qu'il ne faut pas faire) avant d'envoyer n'importe quel rapport!
Autres problèmes
Si vous êtes complètement bloqués, quelqu'un sur la liste de diffusion PHP pourra probablement vous aider. Essayez de consulter les archives, au cas où quelqu'un aurait déjà rencontré votre problème. Les archives sont toujours accessibles à : http://www.php.net/. Pour souscrire à la liste de diffusion, envoyez un mail vide à php-install-subscribe@lists.php.net. L'adresse de la mailing liste : php-install@lists.php.net.
Si vous voulez obtenir de l'aide sur la liste de diffusion PHP, essayez d'être concis et clair, et pensez à donner tous les détails sur votre environnement (OS, version de PHP, serveur web, CGI ou module, safe mode...), et n'hésitez pas à envoyer suffisamment de code pour que nous puissions reproduire l'erreur.
Chapitre 3. Configuration
Le fichier de configuration
Le fichier de configuration (appelé php3.ini dans la version 3.0 du PHP, et simplement php.ini dans la version 4.0) est lu par le PHP au démarrage. Si vous avez compilé PHP en module, le fichier n'est lu qu'une seule fois, au lancement du démon HTTP. Pour la version CGI le fichier est lu à chaque invocation.
Exemple 3-1. Extrait du php.ini
|
Lorsque vous utilisez le module Apache, vous pouvez aussi changer les paramètres de configurations en utilisant les directives dans les fichiers de configuration d'Apache et dans les fichiers .htaccess.
Dans la version 3.0, à chaque directive de configuration présente dans le fichier de configuration d'Apache correspond une directive de configuration dans le fichier php3.ini, à l'exception des directives préfixées par "php3_".
Dans la version 4.0, il n'y a que quelques directives dans le fichier de configuration d'Apache qui vous permettent de modifier la configuration de PHP.
- php_value name value
Cette directive affecte une valeur à la variable spécifiée.
- php_flag name on|off
Cette directive est utilisée pour activer ou désactiver une option.
- php_admin_value name value
Cette directive affecte une valeur à la variable spécifiée. La directive "Admin" ne peut être utilisée que dans le fichier de configuration d'Apache, et non dans un fichier .htaccess.
- php_admin_flag name on|off
Cette directive est utilisée pour activer ou désactiver l'option précédente.
Vous pouvez voir l'état de votre configuration en utilisant la fonction phpinfo(). Vous pouvez aussi accéder aux valeurs de votre configuration de manière individuelle en utilisant la fonction get_cfg_var().
Directives de configuration générale
- allow_url_fopen boolean
Cette option autorise les accès au réseau des fonctions fopen(). Par défaut, l'accès est autorisé aux procédures d'accès distants, avec les protocoles FTP, NNTP, et certaines extensions telles ques zlib.
Note : Cette option a été introduite immédiatement après la version 4.0.3. Pour les versions jusqu'à 4.0.3 incluse, vous pouvez désactiver cette fonctionnalité au moment de la compilation en utilisant la configuration --disable-url-fopen-wrapper.
- asp_tags booléen
Active l'utilisation des balises de type ASP <% %>, en plus des traditionnelles balises <?php ?> . Cela inclut l'utilisation du raccourcid <%= $value %>. Pour plus d'informations, reportez-vous à inclusion dans le HTML.
Note : Le support des balises ASP a été ajouté dans la version 3.0.4.
- auto_append_file chaîne de caractères
Spécifie le nom d'un fichier qui sera automatiquement ajouté après le fichier principal. Le fichier est inclus comme s'il avait été appelé avec la fonction include(), donc include_path est utilisé.
Le mot réservé NONE désactive l'auto-appending.
Note : Si le script s'arrête par la fonction exit(), auto-append ne fonctionnera pas.
- auto_prepend_file chaîne de caractères
Spécifie le nom d'un fichier qui sera automatiquement ajouté avant le fichier principal. Le fichier est inclus comme s'il avait été appelé avec la fonction include(), donc include_path est utilisé.
Le mot réservé NONE désactive l'auto-appending.
- cgi_ext chaîne de caractères
(NDT : aucune documentation n'est fournie).
- display_errors booléen
Cette directive détermine si les erreurs doivent être affichées à l'écran au format HTML ou non.
- doc_root string
Le dossier racine de PHP. Cette directive n'est utilisée que si elle est définie. Si PHP est configuré en safe mode, aucun fichier en dehors de ce dossier ne sera accessible.
- engine boolean
Cette directive ne sert vraiment que si PHP est un module Apache. Elle sert aux sites qui veulent activer ou désactiver l'analyse des fichiers par PHP, dossier par dossier. En mettant php3_engine off au bon endroit, dans le fichier httpd.conf, PHP peut être activé ou désactivé.
- error_log string
Nom du fichier où les erreurs seront enregistrées. Si la valeur spéciale syslog est utilisée, les erreurs sont envoyées au système standard d'historique. Sous UNIX, c'est syslog(3) et sous Windows NT, c'est l'historique d'événements. L'historique système n'est pas supporté sous Windows 95.
- error_reporting integer
Fixe le niveau d'erreur. Ce paramètre est un entier, représentant un champs de bits. Ajoutez les valeurs suivantes pour choisir le niveau que vous désirez :
Par défaut, la valeur est de 7 (erreurs normales, alertes normales et erreurs d'analyseur sont affichées).- open_basedir string
Limite l'espace où PHP peut ouvrir des fichiers.
Lorsqu'un script essaie d'ouvrir un fichier avec les fonctions fopen ou gzopen (par exemple), la localisation du fichier est vérifiée. Si ce fichier est hors du dossier cité dans cette directive, PHP refusera de l'ouvrir. Tous les liens symboliques sont résolus, et subissent aussi la restriction.
La valeur spéciale . indique que le dossier courant du script est utilisé comme open_basedir.
Sous Windows, séparez les noms de dossiers par un point virgule (;). Sur les autres systèmes, séparez les noms de dossiers par des deux points (:). Lorsque PHP est un module Apache, la valeur de la directive open_basedir des dossiers parents est automatiquement héritée par les fils.
Note : Le support pour les dossiers multiples a été ajouté dans 3.0.7.
La valeur par défaut est : libre accès à tous les fichiers.
- gpc_order chaîne de caractères
Etablit l'ordre de préséance des méthodes GET/POST/COOKIE. Par défaut, cette directive est établie à "GPC". En affectant "GP" à cette directive, PHP ignorera les cookies, et écrasera toute méthode GET utilisée par une méthode POST avec des variables du même nom.
- ignore_user_abort chaîne de caractères
Désactivée par défaut. Si cette directive est activée, alors tous les scripts lancés iront jusqu'à leur terme, même si le client se déconnecte en plein milieu. Voir aussi la fonction ignore_user_abort().
- include_path string
Spécifie une liste de dossiers, où les fonctions require(), include() et fopen_with_path() (NDtraducteur : cette fonction semble avoir disparu) iront chercher les fichiers. Le format est le même que celui de la variable d'environnement PATH : une liste de dossiers, séparés par des deux points (:) sous UNIX, et par des points virgules (;) sous Windows.
La valeur par défaut pour cette directive est ., c'est-à-dire le dossier courant.- isapi_ext string
(Aucune documentation n'est fournie)
- log_errors boolean
Indique où les messages d'erreur générés doivent être écrits. Cette fonction est spécifique aux serveurs.
- magic_quotes_gpc boolean
Fixe le mode magic_quotes pour les opérations GPC (Get/Post/Cookie). Lorsque magic_quotes est activé, tous les caractères ' (guillemets simples), " (guillemets doubles), \ (antislash) et NUL sont échappés avec un antislash. Si magic_quotes_sybase fonctionne aussi, les guillemets simples seront échappés avec un autre guillemet simple, plutôt qu'un antislash.
- magic_quotes_runtime boolean
Si magic_quotes_runtime est activé, toutes les fonctions qui obtiennent des données auprès d'une source externe, y compris les bases de données et les fichiers texte, verront leur guillemets échappés avec un antislash. Si magic_quotes_sybase est aussi activé, les guillemets simples seront échappés avec un autre guillemet simple, plutôt qu'un antislash.
- magic_quotes_sybase boolean
Si magic_quotes_sybase est activé, les guillemets simples seront échappés avec un autre guillemet simple, plutôt qu'un antislash, si magic_quotes_gpc ou magic_quotes_runtime est activé.
- max_execution_time integer
Fixe le temps maximal d'éxécution d'un script, en secondes. Cela permet d'éviter que des scripts en boucles infinies saturent le serveur.
- memory_limit entier
Grâce à cette option, vous pouvez donner la quantité maximale de mémoire qu'un script peut allouer. Ceci permet de se prevenir contre des scripts mal codés pouvant consommer toute la mémoire disponible d'un serveur
- nsapi_ext chaîne de caractères
Aucune documentation n'est fournie.
- register_globals boolean
Cette option active l'enregistrement des variables EGPCS (Environnement, GET, POST, Cookie, Serveur), en tant que variables globales. Vous pouvez désactiver cette fonction si vous ne voulez pas truffer vos scripts avec des valeurs utilisateurs. Cette option est surtout utile lorsqu'elle est utilisée conjointement avec track_vars - dans ce cas, vous pouvez accéder à toutes les variables EGPCS grâce aux tableaux $HTTP_ENV_VARS, $HTTP_GET_VARS, $HTTP_POST_VARS, $HTTP_COOKIE_VARS, et $HTTP_SERVER_VARS.
- short_open_tag booléen
Active ou désactive l'utilisation des balises courtes, (<? ?>). Si vous voulez utiliser PHP et XML en même temps, vous devez désactiver cette option. Si cette option est désactivée, vous devez utiliser la forme longue des tags, (<?php ?>).
- sql.safe_mode booléen
Aucune documentation n'est fournie.
- track_errors booléen
Si cette option est activée, le dernier message d'erreur sera placé dans la variable globale $php_errormsg.
- track_vars booléen
Si cette option est activée, lors de l'appel des méthodes GET, POST et l'utilisation des cookies, les variables sont disponibles dans des tableaux associatifs globaux appelés respectivement $HTTP_GET_VARS, $HTTP_POST_VARS et $HTTP_COOKIE_VARS.
- upload_tmp_dir chaîne de caractères
Indique le répertoire utilisé lors du chargement d'un fichier sur un serveur. Ce répertoire doit être accessible en lecture pour l'utilisateur qui lance le script PHP.
- upload_max_filesize entier
La taille maximale d'un fichier téléchargé sur le serveur. La valeur doit être en octets. Par défaut, elle est de 2 méga-octets. in bytes.
- user_dir chaîne de caractères
Répertoire où sont stockés les fichiers PHP dans le répertoire d'un utilisateur. Par exemple, public_html.
- warn_plus_overloading booléen
Si cette option est activée, PHP émet une alerte lorsque l'opérateur plus (+) est utilisé sur une chaîne de caractères. Cela permet de réperer plus facilement les scripts qui doivent être réécrits en utilisant l'opérateur de concaténation (.) plutôt que l'opérateur plus.
Directives de configuration concernant le mail
- SMTP chaîne de caractères
Sous Windows, adresse IP ou nom que PHP doit utiliser pour envoyer du mail avec la fonction mail().
- sendmail_from chaîne de caractères
Sous Windows, valeur du champs "From:" qui doit être utilisée lors de l'envoi de mail.
- sendmail_path chaîne de caractères
Localisation du programme de 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, vous pouvez é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, Qmail. Dans ce cas là, vous devez mettre: /var/qmail/bin/sendmail.
Directives de configuration du "Safe Mode"
- safe_mode booléen
Cette directive active ou désactive l'option "safe mode". Lisez le chapitre sécurité pour plus d'informations.
- safe_mode_exec_dir chaîne de caractères
Si l'option "SAFE MODE" est activée, system() et les autres fonctions exécutant des programmes systèmes refusent de se lancer si ces programmes ne sont pas placés dans ce répertoire.
Directives de configuration de débugage.
- debugger.host chaîne de caractères
Adresse IP ou nom de l'hôte utilisé pour le débugage.
- debugger.port chaîne de caractères
Numéro du port utilisé pour le débugage.
- debugger.enabled booléen
Activation ou désactivation du débugueur.
Directives de chargement des extensions
- enable_dl booléen
Cette directive n'est réellement utile que dans le cas d'une compilation comme module Apache. Vous pouvez activer le chargement dynamique des extensions avec la fonction dl(), et cela de manière locale à chaque serveur virtuel ou à chaque répertoire.
La principale raison qui pousse à désactiver le chargement dynamique est un problème de sécurité. Lorsque le chargement dynamique est activé, il est possible d'ignorer les directives safe mode ou "open_basedir".
Par défaut, il est possible d'utiliser le chargement dynamique, sauf lorsque la directive safe mode est activée. En effet, il est alors impossible d'utiliser la fonction dl().
- extension_dir chaîne de caractères
Définit le répertoire dans lequel le PHP doit chercher les extensions lors du chargement dynamique.
- extension chaîne de caractères
Définit les extensions qui doivent être chargées lors du démarrage du PHP.
Directives de configuration MySQL
- mysql.allow_persistent booléen
Active ou désactive les connexions persistantes à la base de données MySQL.
- mysql.default_host chaîne de caractères
Adresse par défaut du serveur, à utiliser lors de la connexion à un serveur MySQL, si aucun hôte n'est spécifié.
- mysql.default_user chaîne de caractères
Utilisateur par défaut, à utiliser lors de la connexion à un serveur MySQL, si aucun utilisateur n'est spécifié.
- mysql.default_password chaîne de caractères
Mot de passe par défaut, à utiliser lors de la connexion à un serveur MySQL, si aucun mot de passe n'est spécifié.
- mysql.default_port string
Le numéro de port TCP par défaut, utilisé pour se connecter à la base de données, lorsqu'aucun port n'est spécifié. Si aucun port par défaut 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 order. Win32 n'utilisera aussi que la constante MYSQL_PORT.
- mysql.default_socket string
Le nom par défaut de la socket lorsque l'on se conecte au serveur local, si aucune autre socket n'est spécifiée.
- mysql.max_persistent entier
Nombre maximum de connexions persistantes à une base de données MySQL, par processus.
- mysql.max_links entier
Nombre de connexions maximum à une base de données MySQL, par processus, incluant les connexions persistantes
Directives de configuration mSQL
- msql.allow_persistent booléen
Active ou désactive les connexions persistantes à la base de données mSQL.
- msql.max_persistent entier
Nombre maximum de connexions persistantes à une base de données mSQL, par processus.
- msql.max_links entier
Nombre maximum de connexions à une base de données mSQL, par processus, incluant les connexions persistantes.
Directives de configuration Postgres
- pgsql.allow_persistent booléen
Active ou désactive les connexions persistantes à la base de données Postgres.
- pgsql.max_persistent entier
Nombre maximum de connexions persistantes à une base de données Postgres, par processus.
- pgsql.max_links entier
Nombre maximal de connexions à une base de données Postgres, par processus, incluant les connexions persistantes.
Directives de configuration SESAM
- sesam_oml string
Nom de la librairieBS2000 PLAM contenant les pilotes de connexion SESAM. Obligatoire pour les fonctions SESAM. La librairie BS2000 PLAM doit être configurée avec ACCESS=READ,SHARE=YES, car elle doit être accessible à l'utilisateur Apache.
- sesam_configfile string
Nom du fichier de configuration de l'application SESAM. Obligatoire pour les fonctions SESAM. Le fichier BS2000 doit être accessible être accessible à l'utilisateur Apache.
Le fichier de configuration de l'application va contenir la configuration sur le schéma suivant (voir le manuel SESAM) :
- sesam_messagecatalog string
Nom du catalogue de messages SESAM. Dans la plupart des cas, cette directive n'est pas nécessaire. Seulement, si le fichier de messages SESAM n'est pas installé dans la table de messages BS2000, il faut indiquer sa localisation avec cette directive.
Le catalogue de messages doit être paramétré avec ACCESS=READ,SHARE=YES, car il doit être accessible à l'utilisateur Apache.
Directives de configuration Sybase
- sybase.allow_persistent booléen
Active ou désactive les connexions persistantes à la base de données Sybase.
- sybase.max_persistent entier
Nombre maximum de connexions persistantes à une base de données Sybase par processus.
- sybase.max_links entier
Nombre maximum de connexions à une base de données Sybase, par processus, incluant les connexions persistantes.
Directives de configuration Sybase-CT
- sybct.allow_persistent booléen
Active ou désactive les connexions persistantes à la base de données Sybase-CT. Par défaut, cette option est activée.
- sybct.max_persistent entier
Nombre maximum de connexions persistantes à une base de données Sybase-CT par processus. Par défaut, cette option est à -1, ce qui signifie que le nombre de connexion est illimité.
- sybct.max_links entier
Nombre maximum de connexions à une base de données Sybase-CT, par processus, incluant les connexions persistantes. Par défaut, cette option est à -1, ce qui signifie que le nombre de connexions est illimité.
- sybct.min_server_severity entier
Les messages en provenance du serveur d'un niveau d'erreur égal à sybct.min_server_severity seront considérés comme des alertes (warnings). Cette valeur peut être modifiée à l'intérieur du script en appelant la fonction sybase_min_server_severity (NDtraducteur : cette fonction semble ne pas exister). Par défaut, cette valeur vaut 10.
- sybct.min_client_severity entier
Les messages en provenance de la librairie client avec un niveau d'erreur égal ou supérieur à sybct.min_client_severity seront considérés comme des alertes. Cette valeur peut être modifiée à l'intérieur du script en appelant la fonction sybase_min_client_severity (NDtraducteur : cette fonction semble ne pas exister). Par défaut, cette valeur vaut 10, ce qui annule tout rapport d'erreur.
- sybct.login_timeout entier
Délai de validité d'une tentative de connexion. Il est à noter que si max_execution_time est dépassé avant que la connexion n'expire, le script sera terminé avant le message d'erreur. Par défaut, cette valeur vaut 1 minute.
- sybct.timeout entier
Temps maximum en secondes avant qu'une tentative de requête "select_db" ou "query" non aboutie renvoie une erreur. Il est à noter que si max_execution_time est dépassé avant que la requête n'expire, votre script sera terminé avant le message d'erreur. Par défaut, il n'y a pas de limite.
- sybct.hostname chaîne de caractères
Nom de l'hôte à partir duquel vous vous connectez, afin d'être affiché par la fonction sp_who (NDtraducteur : cette fonction semble ne pas exister). Par défaut, cette valeur égale à 0.
Directives de configuration Informix
- ifx.allow_persistent booléen
Active les connexions persistantes à une base de données Informix.
- ifx.max_persistent entier
Nombre maximum de connexions persistantes à une base de données Informix, par processus.
- ifx.max_links entier
Nombre maximum de connexions à une base de données Informix par processus, en incluant les connexions persistantes.
- ifx.default_host chaîne de caractères
Hôte par défaut où se connecter si aucun hôte n'est spécifié par les fonctions ifx_connect() ou ifx_pconnect().
- ifx.default_user chaîne de caractères
Utilisateur par défaut si aucun utilisateur n'est spécifié par les fonctions ifx_connect() ou ifx_pconnect().
- ifx.default_password chaîne de caractères
Mot de passe par défaut si aucun mot de passe n'est spécifié par les fonctions ifx_connect() ou ifx_pconnect().
- ifx.blobinfile booléen
Lorsque cette option est activée, les colonnes de type "blob" seront retournées dans un fichier. Par défaut, elles seront retournées en mémoire. Il est possible de modifier dynamiquement cette valeur grâce à la fonction ifx_blobinfile_mode().
- ifx.textasvarchar booléen
Lorsque cette option est activée, les colonnes de type "TEXT" seront retournées dans une chaîne de caractères. Par défaut, elles seront retournées en mémoire. Il est possible de modifier dynamiquement cette valeur grâce à la fonction ifx_textasvarchar().
- ifx.byteasvarchar booléen
Lorsque cette option est activée, les colonnes de type "BYTE" seront retournées dans une chaîne de caractères. Par défaut, elles seront retournées en mémoire. Il est possible de modifier dynamiquement cette valeur grâce à la fonction ifx_textasvarchar().
- ifx.charasvarchar booléen
Lorsque cette option est activée, les espaces en fin de chaîne de caractères seront conservés lors d'une commande FETCH.
- ifx.nullformat booléen
Lorsque cette option est activée, les colonnes de valeur NULL seront retournées comme des chaînes de caractères vides. Il est possible de modifier dynamiquement cette valeur grâce à la fonction ifx_nullformat().
Directives de configuration pour les calculs mathématiques.
- bcmath.scale entier
Nombre de chiffres après la virgule pour toutes les fonctions de précision mathématique arbitraire.
Directives de configuration du navigateur.
- browscap chaîne de caractères
Nom du fichier de descriptif des clients HTML. Voir aussi get_browser().
Directives de configuration du pilote ODBC unifié
- uodbc.default_db chaîne de caractères
Source de données ODBC à utiliser par défaut avec les fonctions odbc_connect() ou odbc_pconnect().
- uodbc.default_user chaîne de caractères
Nom d'utilisateur défaut avec les fonctions odbc_connect() ou odbc_pconnect().
- uodbc.default_pw chaîne de caractères
Mot de passe par défaut dans les fonctions odbc_connect() ou odbc_pconnect().
- uodbc.allow_persistent booléen
Cette option active ou désactive les connexions persistantes à la base de données, via le canal ODBC.
- uodbc.max_persistent entier
Nombre maximum de connexions persistantes autorisées à la base de données.
- uodbc.max_links entier
Nombre maximum de connexions (persistantes ou non), par processus, à la base de données.
Directives de configuration des chaînes mulit-octets
- mbstring.internal_encoding string
mbstring.internal_encoding définit l'encodage interne par défaut.
- mbstring.http_input string
mbstring.http_input définit l'encodage de reception HTTP par défaut.
- mbstring.http_output string
mbstring.http_output définit l'encodage d'affichage HTTP par défaut.
- mbstring.detect_order string
mbstring.detect_order définit l'ordre de détection des encodages par défaut.
- mbstring.substitute_character string
mbstring.substitute_character définit l'encodage de substitution par défaut : il est utilisé pour les caractères invalides.
Chapitre 4. Sécurité
PHP est un langage puissant et l'interpréteur, qu'il soit inclus dans le serveur web ou bien compilé en version CGI, 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. Le langage PHP a été pensé afin d'être un langage beaucoup plus sécurisé pour écrire des CGI que le Perl ou le langage C. De plus, une sélection rigoureuse des options de compilation et d'exécution vous permettra d'obtenir un équilibre parfait entre liberté et sécurité.
Etant donné qu'il y a de nombreux moyens d'utiliser le langage PHP, il y a de nombreuses directives de configuration afin d'en contrôler le comportement. Un grand nombre d'options permettent d'utiliser le PHP dans de nombreuses situations, mais cela signifie aussi qu'il y a certaines combinaisons d'options de compilation et d'exécution qui fragilisent la sécurité du serveur. Ce chapitre explique comme les différentes options de configurations peuvent être combinées, tout en conservant une sécurité maximum.
La flexibilité de configuration de PHP est épaulée par la flexibilité du code. PHP peut être compilé pour constituer une application serveur complète, avec toutes les fonctionnalités d'un shell, ou il peut encore être utilisé comme simple SSI (server side include) avec peu de risque, dans un environnement à sécurité renforcée. Comment créer cet environnement et le sécuriser est largement à la charge du développeur PHP.
Ce chapitre commence par expliquer les différentes options de configuration et les situations dans lesquelles elles peuvent être utilisées en toute sécurité. Puis, viennent les considérations de niveaux de sécurité, et les conseils généraux.
Considérations générales
Un système complètement sÛr est une impossiblité virtuelle. L'approche souvent utilisée par les professionnels de la sécurité est d'équilibrer les risques et l'ergonomie. Si chaque variable fournie par l'utilisateur demandaient deux formes de validation biométrique (un scan de la rétine et une empreinte digitale), on obtiendrait un système avec un niveau de sécurité d'un bon niveau. Il faudrait aussi une bonne heure pour remplir un formulaire simple, ce qui encouragerait les utilisateurs à trouver un moyen de contourner cette sécurité.
La meilleure sécurité est suffisamment discrète pour assurer un maximum de sécurité sans ajouter de contraintes insurmontables pour l'utilisateur ou de systèmes complexes de programmation. Souvent, les attaques sur un script sont des exploitations des sysèmes de sécurité trop complexes, qui s'érodent au cour du temps.
Un principe qu'il est bon de retenir : Un système est aussi sur que son maillon le plus faible. Si toutes les transactions sont bien notées dans une base, avec confirmation mais que l'utilisateur n'est authentifiée que par un cookie, la robustesse de votre système est sévèrement réduite.
Lorsque vous testez votre site, gardez en tête que vous ne pourrez jamais tester toutes les situations, même pour les pages les plus simples. Les valeurs que vous attendez seront toujours complétement différentes des valeurs qu'un employé négligent, un hacker qui a toute la nuit 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 d'entrée des données inattendues, puis de voir comment elles pourront être modifiées, amplifiées ou réduites.
L'Internet est rempli d'individu qui tentent de se faire une renommée en piratant vos programmes, en bloquant votre site, en envoyant des contenus inappropriés, qui rendent vos journées si "spéciales". Peut importe que vous ayez un grand portail ou un petit web, vous pouvez être la cible pour tout quidam avec une connexion. Vous êtes une cible potentielle dès que vous êtes connecté vous-même. Certains programmes de piratage ne font pas dans la demi-mesure, et testent systématiquement des millions d'IP, à la recherche de victimes : ne soyez pas la prochaine.
Binaires CGI
Faiblesses connues
Utiliser le PHP comme un CGI exécutable vient la majorité du temps du fait que l'on ne veut pas l'utiliser comme un module du serveur web, (comme Apache), ou bien que l'on souhaite l'utiliser en combinaison d'un 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 vous installez votre exécutable dans le répertoire cgi-bin de votre serveur web. CERT CA-96.11 recommande effectivement de placer l'interpréteur à l'intérieur du répertoire cgi-bin. Même si le binaire PHP peut être utilisé comme interpréteur indépendant, PHP a été pensé afin de rendre impossible les attaques que ce type d'installation induit.
Accès au système de fichier: http://ma.machine/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, le PHP refuse d'interpréter les arguments de la ligne de commande.
Accès d'un 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 du binaire PHP, /secret/doc.html est utilisé par convention pour spécifier le nom du fichier qui doit être ouvert et interprété par le programe CGI. Habituellement, des directives de configuration du serveur web (pour le serveur Apache: Action) sont utilisées pour rediriger les requêtes afin d'obtenir un document http://my.host/secret/script.php par 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 après cette vérification redirige 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 aux documents protégés sur le serveur web.
Avec le PHP, l'option de compilation --enable-force-cgi-redirect et les options d'exécution doc_root et user_dir peuvent être utilisées pour prévenir ce genre d'attaques, 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: Tous les fichiers sont publics
Si votre serveur n'a aucun document dont l'accès est restreint par un mot de passe ou un système de vérification de l'adresse IP, vous n'avez aucun besoin de ce type de configuration. Si votre serveur web ne permet pas les redirections, ou si votre serveur web n'a aucun besoin de communiquer avec le binaire PHP de manière sécurisée, vous pouvez utiliser l'option de compilation --disable-force-cgi-redirect. Vous devez quand même vérifier qu'aucun script ne fait appel au PHP, de manière directe, http://my.host/cgi-bin/php/dir/script.php ou bien de manière indirecte, par redirection, http://my.host/dir/script.php.
Les redirections peuvent être configurées dans les fichiers de configuration d'Apache en utilisant les directives "AddHandler" et "Action" (voir ci-dessous).
Cas 2: Utilisation de la directive de compilation --enable-force-cgi-redirect
Cette option de compilation prévient quiconque d'appeler directement un script avec l'url http://my.host/cgi-bin/php/secretdir/script.php. Dans ce cas là, PHP parsera le fichier uniquement s'il y a eu redirection.
Habituellement, le serveur web Apache réalise une redirection grâce aux directives suivantes :
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-standart REDIRECT_STATUS pour les requêtes redirigées. Dans le cas où votre serveur web ne supporte pas le renseignement du PHP, pour savoir si la requête a été redirigée ou non, vous ne pouvez pas utiliser cette option de compilation. Vous devez alors utiliser une des autres méthodes d'exploitation de la version binaire CGI du PHP, comme exposé ci-dessous.
Cas 3: Utilisation du "doc_root" ou du "user_dir"
Ajouter un contenu interactif dans votre serveur web, comme des scripts ou des exécutables, est souvent considéré comme une pratique non-sécurisée. Si, par erreur, le script n'est pas exécuté mais affiché comme une page HTML classique, il peut en résulter un vol de propriété intellectuelle ou des problèmes de sécurité à propos des mots de passe notamment. Donc, la majorité des 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 du PHP, et donc, tous les fichiers de ce répertoire seront interprétés et non affichés tels quels.
Aussi, si vous ne pouvez pas utiliser la méthode présentée ci-dessus, il est nécessaire de mettre en place un répertoire "doc_root" différent de votre répertoire "document root" de votre serveur web.
Vous pouvez utiliser la directive doc_root dans le fichier de configuration, ou vous pouvez affecter la variable d'environnement PHP_DOCUMENT_ROOT. Si cette variable d'environnement est affectée, le binaire CGI du PHP construira toujours le nom de fichier à ouvrir avec doc_root et le "path information" de la requête, et donc vous serez sÛr qu'aucun script n'est 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 la directive n'est pas activé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 correspond pas à l'ouverture d'un fichier sous le répertoire racine de l'utilisateur mais à l'ouverture du fichier ~user/doc.php sous le repertoire "doc_root" (oui, un répertoire commence par un tilde [~]).
Si la directive "user_dir" est activée à la valeur public_php par exemple, une requête du type http://my.host/~user/doc.php ouvrira un fichier appelé doc.php sous le répertoire appelé public_php sous le répertoire racine de l'utilisateur. Si le répertoire racine des utilisateurs 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 donc vous pouvez contrôler l'accès au répertoire "document root" séparément des répertoires "user directory".
Cas 4: L'exécutable PHP à l'extérieur de l'arborescence du serveur
Une solution extrêmement sécurisée consiste à mettre l'exécutable PHP à l'extérieur de l'arborescence du serveur web. Dans le répertoire /usr/local/bin, par exemple. Le problème de cette méthode est que vous aurez à rajouter la ligne suivante :
dans tous les fichiers contenant des tags PHP. Vous devrez aussi rendre le binaire PHP exécutable. Dans ce cas-là, traitez le fichier exactement comme si vous aviez un 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, vous devez utiliser l'option de compilation --enable-discard-path.
Module Apache
Lorsque le PHP est compilé en tant que module Apache, ce module hérite des permissions accordées à l'utilisateur faisant tourner Apache ( par défaut, l'utilisateur "nobody"). Par exemple, si vous utilisez PHP pour accéder à une base de données, à moins que la base n'ait un système de droits d'accès interne, vous devrez rendre la base accessible à l'utilisateur "nobody". Cela signifie qu'un script mal intentionné peut accéder à la base, la modifier sans authentification. Il est aussi possible qu'un robot accède à la page d'administration, et détruise toutes les pages. Vous devez aussi protéger vos bases de données avec les autorisations Apache, ou définir votre propre modèle d'accès avec LDAP, .htaccess, etc... et inclure ce code dans tous vos 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 des virus dans les fichiers des utilisateurs. Ou encore, de modifier une base de données privée. Il est aussi incapable de modifier des fichiers qu'il devrait pouvoir modifier, ou effectuer certaines transactions.
Une erreur fréquente de sécurité est de donner à l'utilisateur Apache les droits de superadministrateur.
Donner de telles permissions à l'utilisateur Apache est extrêmement dangereux, et peut compromettre tout le système, telle que l'utilisation des sudo ou du chroot. Pour les professionnels de la sécurité, une telle utilisation est à exclure d'office.
Il existe des solutions plus simples. En utilisant open_basedir() vous pouvez contrôler et restraindre l'accès à certains dossiers qui pourront être utilisés par PHP. Vous pouvez aussi des aires de restrictions Apache, pour restraindre les activités anonymes liées aux internautes.
Sécurité des fichiers
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 qui vous permet de lire des fichiers tels que /etc/password, de modifier les connexions ethernet, lancer des impressions de documents, etc... Cela implique notamment que vous devez-vous assurer que les fichiers accédés par les scripts sont bien ceux qu'il faut.
Considérez le script suivant, où 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 4-2. Une attaque du système de fichiers!
|
Limiter les permissions du l'utilisateur web PHP.
Vérifier toutes les variables liées aux chemins et aux fichiers qui sont fournie.
Exemple 4-3. Une vérification renforcée
|
Suivant votre système d'exploitation, vous devrez 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 stockages 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 que vous autorisez.
Rapport d'erreur
En terme de sécurité, il y a deux conséquence au rapport d'erreur. D'un coté, 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 lire les variables d'environnement et de contexte qui sont retournées. Cela permet au pirate de lire de nombreuses informations sur le serveur, et de détecter des faiblesses du serveur. Par exemple, si un intrus a glané des informations sur votre page, avec une première utilisation de votre site, il peut essayer de remplacer les variables par ses propres valeurs :
Les erreurs PHP qui sont normalement retournées peuvent être très pratiques pour un développeur qui essaie de débugger un script, car elles donnent de précieux renseignements tels que quelle fonction a échoué, quel fichier n'a pas été trouvé, quel script PHP a buggé, et quelle ligne est en faute. Toutes ces informations sont exploitables. Il est commun aux développeurs PHP d'utiliser les fonctions show_source(), highlight_string(), ou highlight_file() comme outils de débuggage, mais sur un site en production, cela expose des variables cachées, des syntaxes non vérifiées ou d'autres informations critiques. Il est particulièrement dangeureux d'exécuter du code de sources connues, avec les gestionnaires de débuggage. Si l'intrus peut comprendre votre technique habituelle d'utilisation, il peut tenter une attaque frontale sur une page, en envoyant des chaînes de débuggage :
Indépendamment de la gestion des erreurs, la possibilité de tester la gestion des erreurs d'un système conduit à un trou de sécurité, et la diffusion de plus d'informations sur votre système.
Si un pirate affiche une page html, et essaye de la tester (pour rechercher des faiblesses du système), il peut déterminer sur quel système PHP a été compilé.
Une erreur de fonction indique si un système supporte une base de données spécifique, ou bien indique comment la page a été généré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'authentification dans un script (à partir des lignes d'erreurs), et d'essayer de les exploiter ailleurs, dans le script.
Une erreur de fichier, ou une erreur générale PHP peut indiquer quelles sont les permissions du serveur web, ainsi que la structure et l'organisation des fichiers. Les gestionnaires d'erreurs utilisateurs peuvent 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 deuxième est d'inactiver le rapport d'erreur, dès que le script est en production. La troisième est d'utiliser les fonctions de gestions des erreurs. Suivant votre politique de sécurité, vous pouvez utiliser un panachage savant des trois méthodes.
Une méthode pour gagner du temps est d'utiliser la fonction error_reporting(), pour vous aider à sécuriser le code, et détecter les utilisations dangeureuses de variables. Vous testez votre code en béta-test avec la valeur E_ALL, et vous pouvez rapidement repérer les variables qui ne sont pas protégées. Une fois que le code est prêt à être déployé, utilisez la constante E_NONE, pour isoler votre code.
Exemple 4-7. Détecter des variables non protégées avec E_ALL
|
Utilisation des variables HTTP
Une fonctionnalité de PHP qui peut être utilisée pour améliorer la sécurité est de configurer PHP en inactivant l'option register_globals. En supprimant la possibilité que les variables envoyées par les internautes soient injectées automatiquement dans le script PHP, vous pouvez restreindre la quantité de variables non-protégées. Les intrus devront prendre beaucoup plus de temps pour corrompre les mécanismes d'envoi de données, et vos variables internes seront nettement mieux protégées.
Bien que cela augmente d'autant les efforts à fournir pour écrire un script PHP, les bénéfices peuvent en être nettement plus interessants.
Exemple 4-8. Travailler avec register_globals actif
|
Exemple 4-10. Détection de corruption de variables
|
Données transmises par les internautes
Les plus grandes faiblesses de nombreux programmes PHP ne viennent pas du langage lui-même, mais de son utilisation en omettant les caractéristiques de sécurité. Pour cette raison, vous devez toujours prendre le temps de prendre en compte les implications d'une fonction, et de cerner toutes les applications d'une utilisation exotiques des paramètres.
Exemple 4-11. Utilisation dangereuse de variables
|
Est-ce que ce script n'affectera que les fichiers prévus?
Est-il possible que des valeurs incohérentes soient exploitées ici?
Est-ce que ce script peut être utilisé dans un but différent?
Est-ce que ce script peut être utilisé malicieusement, en conjonction avec d'autres?
Est-ce que toutes les actions seront notées?
Vous pouvez aussi envisager de supprimer l'acquisition automatique des variables d'environnement, les guillemets magiques (magic_quotes), ou encore toute option qui pourrait vous conduire à mésévaluer la validité, la source ou la valeur d'une variable. En travaillant avec error_reporting(E_ALL), vous pouvez être averti que certaines variables sont utilisées avant d'être exploitées, ou vérifiées (et donc, vous pourrez traiter des valeurs exotiques à la source).
Masquer PHP
Quelques astuces permettent de masquer PHP, et cela entrave les pirates qui recherchent des faiblesses dans votre système. En inactivant l'option expose_php dans votre fichier php.ini, vous pouvez 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 le fichier .htaccess, soit dans le fichier de configuration lui-même. Vous pouvez utiliser des informations déroutantes comme ceci :
Etre à jour
PHP, comme de nombreux systèmes 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 les problèmes de conceptions de configuration, et d'autres points qui peuvent affecter la sécurité globale et la stabilité de votre système.
Comme les autres langages de scripts systèmes, la meilleure approche est de mettre à jour souvent PHP, et de rester à l'écoute des dernières versions et des modifications qu'elles apportent.
II. Référence
- Table des matières
- 5. La syntaxe de base
- 6. Les types
- 7. Les variables
- 8. Les constantes
- 9. Les expressions
- 10. Les opérateurs
- 11. Les structures de contrôle
- 12. Les fonctions
- 13. Les classes et les objets
- 14. Les références
Chapitre 5. La syntaxe de base
Le passage du HTML au PHP
Lorsque PHP commence à traiter un fichier, il ne fait qu'afficher le texte HTML qu'il rencontre. Si vous renommez un fichier .html en .php, il s'affichera exactement comme avant.
Si vous voulez insérer des commandes PHP dans votre fichier, vous devez indiquer à PHP le début d'une telle séquence, en passant en mode PHP. Il y a quatre moyens pour passer du mode HTML au mode PHP :
Exemple 5-1. Le passage du HTML au PHP
|
La deuxième méthode est généralement utilisée, car elle permet une implémentation aisée de PHP avec la prochaine génération de XHTML.
La première possibilité n'est valable que si vous l'avez activée. Soit en faisant appel à la fonction short_tags() (NdT : semble avoir disparu), soit en utilisant l'option d'exécution short_open_tag dans le fichier de configuration, soit en utilisant l'option de compilation --enable-short-tags.
La quatrième possibilité est seulement disponible si vous l'avez activée en utilisant soit l'option d'exécution asp_tags, soit en utilisant l'option de compilation --enable-asp-tags.
Note : Le support de la quatrième possibilité, ASP-style, a été ajouté dans la version 3.0.4.
La marque de fermeture d'un bloc (?>) comprend la nouvelle ligne suivante, s'il y en a une.
PHP vous permet d'utiliser des structures telles que :
Le séparateur d'instruction
Les instructions sont séparées par un point virgule à chaque fin d'instruction, comme en langage C ou en Perl.
La balise de fin (?>) implique la fin d'un instruction, et donc ajoute implicitement un point virgule. Les deux exemples suivants sont équivalents.
Commentaires
Le PHP supporte les commentaires comme en C, C++ et Shell Unix. Par exemple:
<?php
echo "Ceci est un test"; // Ceci est un commentaire sur une ligne comme en C++
/* Ceci est un commentaire sur plusieurs lignes,
comme en C et C++ */
echo "Ceci est encore un test";
echo "Enfin, le test final"; # Ceci est un commentaire comme en Shell Unix
?> |
Le premier type de commentaire ne commente que jusqu'à la fin de la ligne ou bien jusqu'à la fin du bloc, cela dépend du premier rencontré.
La ligne du dessus affichera 'Ceci est un simple exemple'.
Faites attention à ne pas emboîter les commentaires de type 'C', ce qui arrive de temps en temps lorsque vous voulez commenter une grande partie de code.
Chapitre 6. Les types
Introduction
PHP supporte les 8 types basiques suivants :
PHP supporte quatres types scalaires :
PHP supporte deux types composés :
PHP supporte deux types spéciaux :
Note : Dans ce manuel, vous rencontrerez souvant le type mixed. C'est un pseudo-type, qui indique que le paramètre peut indifféremment prendre plusieurs types.
Habituellement, le type d'une variable n'est pas déclaré par le programmeur. Il est décidé au moment de l'exécution par le PHP, en fonction du contexte dans lequel la variable est utilisée.
Si vous voulez forcer une variable à être convertie en un certain type, vous devez transtyper (cast) la variable ou utiliser la fonction settype().
Il est à noter qu'une variable peut se comporter de manière différente suivant les situations, en fonction du type qui lui est affecté. Pour plus d'informations, voir le paragraphe transtypage.
Booléens
C'est le type le plus simple. Un booléen exprime les valeurs de vrai TRUE ou FALSE.
Vous pouvez utiliser les constantes 'TRUE' et 'FALSE' pour spécifier une valeur de type boolean. Généralement, vous les créerez avec un des operateurs qui retourne une valeur boolean, pour le passer à une structure de contrôle.
<?php
if ($action == "show_version"){
// == is an operator
// qui retourne un booléen
echo "La version est 1.23";
}
// ceci n'est pas nécessaire
if ($show_separators == true){
echo "<hr>\n";
}
// ceci est plus pratique
if ($show_separators){
echo "<hr>\n";
}
?> |
Note : Le type booéen a été introduit en PHP 4.
Conversion en booléen
Reportez-vous au chapitre "Définition du type" pour plus d'informations sur les conversions.
Lors des conversions de valeurs de type boolean, les valeurs suivantes sont considérées comme fausse (FALSE) :
Le booléen FALSE
L'entier 0 (zéro)
Le nombre à virgule flottante 0.0 (zéro)
Le tableau vide (aucun élément)
L'objet vide (aucun élément)
La constante spéciale NULL
| Avertissement |
-1 est considéré comme vrai! |
Entiers
Un entier est un nombre de l'ensemble des entiers naturels Z : Z = {...., -2, -1, 0, 1, 2, ...}. Il est possible de spécifier les nombres entiers (integers) de toutes les manières suivantes : décimale (base 10), hexadécimale (base 16), octale (base 8) éventuellement précédé du signe moins (-).
Pour utiliser la notation octale, vous devez préfixer le nombre avec un zéro; pour utiliser la notation hexadécimale, vous devez préfixer le nombre avec 0x.
<?php
$a = 1234; # nombre entier en base 10
$a = -123; # nombre entier négatif
$a = 0123; # nombre entier en base 8, octale (équivalent à 83 en base 10)
$a = 0x12; # nombre entier en base 16, hexadécimale
# (équivalent à 18 en base 10)
?> |
Note : En PHP, il n'existe pas de type fraction. 1/2 se transforme en nombre à virgule flottante 0.5.
Dépassement de capacité des entiers
Si un nombre est hors de l'intervalle de validité des entiers, il sera interprété comme un float.
<?php $large_number = 2147483647; var_dump($large_number); // affiche : int(2147483647) var_dump( 0x80000000 ); // affiche : float(2147483648) var_dump( 25/7 ); // affiche : float(3.5714285714286) ?> |
<?php $million = 1000000; $large_number = 50000 * $million; var_dump($large_number); // affiche : float(50000000000) ?> |
En PHP, il n'y a pas de division entière. 1/2 sera un nombre 1agrave; virgule flottante (float) de valeur 0.5.
| Avertissement |
Malheureusement, il y a un bug dans le moteur (corrigé en 4.1.0), qui fait que PHP que fonctionne pas toujours bien lorsque des nombres négatifs sont utilisés. Lorsque les deux opérandes sont positifs, il n'y a pas de problèmes. Par exemple : -50000 * $million, conduit à -429496728. |
Conversion en entiers
Pour explicitement convertir une valeur en integer, utilisez les opérateurs de transtypage (int) ou (integer). Cependant, dans la plupart des situations, vous n'en aurez pas besoin, car une valeur sera automatiquement convertie si un opérateur, un fonction ou tout autre élément du langage requiert un entier.
Reportez-vous à la section définition de type pour plus d'informations sur les conversions.
Depuis un nombre à virgule flottante
Lors de conversion entre nombre à virgule flottante et un entier, le nombre sera arrondi à la valeur inférieure s'il est positif, et supérieure s'il est négatif (conversion dite 'vers zéro').
Si le nombre est hors de l'intervalle de validité des entiers, (généralement +/- 2.15e+9 = 2^31), le résultat est indéfinit, car les nombres à virgule flottante n'ont pas assez de précision pour fournir une valeur exacte pour un entier.
| Avertissement |
Aucune alerte, même pas le plus petit message ne sera affiché dans ce cas. |
| Avertissement |
Ne transformez jamais une fraction inconnue en entier, car cela peut conduire à des résultats irrationnels. Pour plus d'informations, reportez-vous aux alertes liées aux nombres à virgule flottante. |
Conversion d'autres types
La conversion d'autres types en entier est indéfinie. Actuellement, PHP convertit d'abord la valeur en booléen.
| Attention |
Mais, ne vous fiez pas à ce comportement, car il est susceptible de changer sans préavis! |
Voir aussi : Nombres de grande taille et Nombres à virgules flottantes.
Les nombres à virgule flottante
Les nombres à virgule flottante (connus aussi sous le vocable de "double" ou "float" "nombre rééls") peuvent être spécifiés en utilisant la syntaxe suivante:
| Précision des nombres à virgule flottante |
Il est fréquent que de simples fractions décimales telles que 0.1 ou 0.7 ne puissent être converties au format interne binaire sans une légère perte de précision. Cela peut conduire à des résultats étonnants : par exemple, floor((0.1+0.7)*10) retournera 7 au lieu de 8 car le résultat de la représentation interne est 7.9999999999.... Tout ceci est lié au fait qu'il est impossible d'exprimer certaines fractions en un nombre fini de chiffres. Par exemple 1/3 s'écrira 0.3333333... en mode décimal. Ne faites donc jamais confiance aux nombres à virgule jusqu'à leur dernière décimale, et ne comparez jamais ces nombres avec l'opérateur d'égalité. Si vous avez besoin d'une précision particulière, reportez-vous au traitement des nombres de grande taille avec les librairies BC ou GMP. |
Les chaînes de caractères
Les chaînes de caractères sont des séquences de caractères. En PHP, un caractère est un octet, et il y en 256 de possibles. PHP n'a pas (encore?) de support natif d'Unicode.
Note : La taille n'est pas un problème majeur pour une chaîne. Elle peut devenir très grande sans problème. Il n'y a a pas à s'en faire pour cela.
Syntax
Une chaîne peut être spécifiée de trois manières différentes :
guillemets simples
Le moyen le plus simple de spécifier une chaîne de caractères est d'utiliser les guillemets simples : '.
Pour spécifier un guillemet simple littéral, vous devez l'échapper avec un anti-slash (\), comme dans de nombreux langages. Si un anti-slash doit apparaître dans votre chaîne ou bien en fin de chaîne, il faudra le doubler. Notez que si vous essayez d'échapper n'importe quel autre caractère, l'anti-slash sera conservé! Il n'y a pas besoin d'échapper d'autres caractères que le guillemets lui-même.
Note : En PHP 3, une alerte sera affichée si cela arrive avec un niveau de rapport d'erreur de E_NOTICE.
Note : Contrairement aux autres syntaxes, les variables présentes dans la chaîne ne seront PAS remplacées par leurs valeurs.
<?php echo 'Ceci est une chaîne simple'; echo 'Vous pouvez inclure des nouvelles lignes dans une chaîne, comme ceci.'; echo 'Arnold a coutume de dire : "I\'ll be back"'; // affiche : ... "I'll be back" echo 'Etes vous sÛr de vouloir effacer le dossier C:\\*.*?'; // affiche : Etes vous sÛr de vouloir effacer le dossier C:\*.*? echo 'Etes vous sÛr de vouloir effacer le dossier C:\*.*?'; // affiche : Etes vous sÛr de vouloir effacer le dossier C:\*.*? echo 'Je suis en train de mettre une nouvelle ligne comme ceci : \n'; // affiche : Je suis en train de mettre une nouvelle ligne comme ceci : \n ?> |
Guillemets doubles
Si la chaîne est entourés de guillemets doubles, PHP va comprendre certaines séquences de caractères :
Tableau 6-1. Les caractères spéciaux
| Séquence | Valeur |
|---|---|
| \n | Nouvelle ligne (linefeed, LF ou 0x0A (10) en ASCII) |
| \r | Retour à la ligne(carriage return, CR ou 0x0D (13) en ASCII) |
| \t | Tabulation horizontale (HT ou 0x09 (9) en ASCII) |
| \\ | Antislash |
| \$ | Caractère $ |
| \" | Guillemets doubles |
| \[0-7]{1,3} | Une séquence de caractères qui permet de rechercher un nombre en notation octale. |
| \x[0-9A-Fa-f]{1,2} | Une séquence de caractères qui permet de rechercher un nombre en notation hexadécimale. |
Si vous essayez d'utiliser l'anti-slash sur n'importe quelle autre séquence, l'anti-slash sera affiché dans votre chaîne.
Le plus important des chaînes à guillemets doubles est le fait que les variables qui s'y trouvent seront remplacées par leurs valeurs. Voir la section sur le traitement des variables dans les chaînes pour plus de détails.
Syntaxe Heredoc
Un autre moyen de délimiter les chaînes est d'utiliser la syntaxe de "Here doc" (en français, documentation ici): <<<, suivi d'un identifiant arbitraire, puis de la chaîne. Cette séquence se termine par l'identifiant initial, placé en premier sur une nouvelle ligne.
L'identifiant utilisé doit suivre les mêmes règles que les étiquettes PHP : il ne doit contenir uniquement que des caractères alpha-numériques, et des soulignés ("_"), et enfin, commencer par un caractère alphabétique ou un souligné.
| Avertissement |
Il est très important de noter que la ligne qui contient l'identifiant de fermeture ne doit contenir aucun autre caractère, hormis, éventuellement, un point-virgule ;. Cela signifie notamment que l'identifiant ne doit pas être indenté, et qu'il n'y a aucun caractère blanc entre le retour à la ligne et l'identifiant, ou bien entre l'identifiant et le ;. Le plus dur est peut être qu'il ne faut pas qu'il y ait un retour à la ligne ((\r) à la fin de cette ligne, mais seulement un form-feed (\n). Puisque Microsoft Windows utilise la séquence \r\n comme terminaison de ligne, la syntaxe heredoc risque de ne pas fonctionner là. Cependant, la plupart des éditeurs PHP fournissent une sauvegarde au format UNIX. |
La syntaxe Here doc se comporte exactement comme une chaîne à guillemets doubles, sans les guillemets doubles. Cela signifie que vous n'avez pas à échapper les guillemets (simples ou doubles) dans cette syntaxe. Les variables sont remplacées par leur valeur, et le même soin doit leur être apporté que dans les chaînes à guillemets doubles.
Exemple 6-1. Exemple de chaîne HereDoc
|
Note : Le support Here doc a été ajouté en PHP 4.
Traitement des variables dans les chaînes
Lorsqu'une chaîne est spécifiée avec des guillemets doubles, ou en utilisant la syntaxe heredoc, les variables qu'elle contient sont remplacées par leur valeur.
Il y a deux types de syntaxe, une simple et une complexe. La syntaxe simple est la plus courante, et la plus pratique : elle fournit un moyen d'utiliser les variables, que ce soit des chaînes, des tableaux ou des membres d'objets.
La syntaxe complexe a été introduite en PHP 4 et peut être reconnue grâce aux accolades entourant les expressions.
Syntaxe simple
Dès qu'un signe dollar $ est rencontré, l'analyseur PHP va lire autant de caractère qu'il peut pour former un nom de variable valide. Entourez le nom de la variable avec des accolades pour indiquer explicitement son nom.
<?php
$boisson = 'vin';
echo "Du $boisson, du pain et du fromage!';
// OK, car "," n'est pas autorisé dans les noms de variables
echo "Il a goÛté plusieurs $vins";
// Pas OK, car 's' peut entrer dans un nom de variable, et PHP recherche $boissons
echo "Il a goÛté plusieurs ${vin}s";
// OK
?> |
Similairement, vous pouvez aussi utiliser un élément de tableau, ou un membre d'objet. Pour les éléments de tableau, le crochet fermant ']' marquera la fin du nom de la variable. Pour les membres d'objets, les mêmes règles que ci-dessus s'appliquent. Cependant, il n'existe pas de truc comme pour les variables simples.
$fruits = array( 'fraise' => 'rouge' , 'banane' => 'jaune' ); echo "Une banane est $fruits[banane]."; // OK. Notez toutefois que pour cet exemple, cela fonctionne // différemment. Voyez $foo[bar] hors des chaînes echo "Ce carré est large de $carre->largeur mètres."; // OK echo "Ce carré est large de $carre->largeur00 mètres.."; // pas OK // pour résoudre ce problème, voyez syntaxe complexe. |
Pour tout ce qui sera plus compliqué, voyez la syntaxe complexe.
Syntaxe complexe
La syntaxe est dite "complexe" car elle permet l'utilisation d' expressions complexes, et non pas parcequ'elle serait obscure. Nuance.
En fait, vous pouvez inclure n'importe quelle valeur qui est dans l'espace de nom avec cette syntaxe. Il suffit d'écrire une expression exactement comme si elle était hors de la chaîne, puis de l'entourer d'accolades {}. Puisque vous ne pouvez pas échapper les accolades, cette syntaxe ne commence qu'à partir du signe dollar, qui suit immédiatement l'accolade ouvrante. Par exemple, vous pouvez utiliser "{\$" pour obtenir un "{$" littéral. Voici quelques exemples :
<?php
$super = 'fantastique';
echo "C'est { $super}";
// ne fonctionne pas,
// affiche "C'est { fantastique}"
echo "C'est {$super}";
// fonctionne,
// affiche "C'est fantastique"
echo "Ce carré a {$square->width}00 centimètres de large.";
echo "Ceci fonctionne : {$tableau[4][3]}";
echo "Ceci échoue : {$tableau[foo][3]}";
// pour la même raison que $tableau[bar] ne fonctionne pas hors d'une chaîne
echo "Essayez plutôt comme ceci : {$tableau['foo'][3]}";
echo "Vous pouvez même écrire {$objet->valeurs[3]->nom}";
echo "Voici la valeur de la variable nommée $name: {${$name}}";
// cela fonctionne, mais c'est vivement déconseillé.
// Et pour finir, on peut combiner avec des fonctions
$inv = 'Bordeaux';
echo "Je reprendrai bien un verre de cet excellent {${ strrev('niv') }}, hips";
?> |
Accès aux caractères d'une chaîne
Les caractères d'une chaîne sont accessibles en spécifiant leur offset (le premier caractère est d'offset 0) entre accolade, après le nom de la variable.
Note : Pour assurer la compatibilité ascendante, vous pouvez toujours accéder aux caractères avec des crochets. Mais cette syntaxe est obsolète en PHP 4.
Exemple 6-2. Exemples de chaînes
|
Fonctions et opérateurs pratiques
Les chaînes peuvent être concaténées avec l'opérateur '.' (point). Notez que l'opérateur d'addition '+' (plus) ne fonctionnera pas. Reportez-vous à la section opérateurs de chaînes.
Il y a une grande quantité de fonctions pratiques pour modifier les chaînes.
Reportez-vous à la section chaînes de caractères pour les fonctions les plus générales, à Expressions régulières Perl et Expressions régulières POSIX extendues pour les recherches et remplacements.
Il y a aussi les fonctions sur les URL, ainsi que des fonctions de chiffrage (mcrypt et mhash).
Finalement, si vous ne trouvez toujours pas votre bonheure, il y a les fonctions de types de caractères.
Conversion de type
Lorsqu'une chaîne de caractère est évaluée comme une valeur numérique, le résultat et le type de la variable sont déterminés comme suit.
La chaîne de caractères est de type "double" si elle contient un des caractère '.', 'e' ou 'E'. Sinon, elle est de type entier ("integer").
La valeur est définie par la première partie de la chaîne. Si la chaîne de caractères débute par une valeur numérique cette valeur sera celle utilisée. Sinon, la valeur sera égale à 0 (zéro).
Lorsque la première expression est une chaîne de caractères, le type de la variable dépend de la seconde expression.
<?php $foo = 1 + "10.5"; // $foo est du type float (11.5) $foo = 1 + "-1.3e3"; // $foo est du type float (-1299) $foo = 1 + "bob-1.3e3"; // $foo est du type integer (1) $foo = 1 + "bob3"; // $foo est du type integer (1) $foo = 1 + "10 Small Pigs"; // $foo est du type integer (11) $foo = 1 + "10 Little Piggies"; // $foo est du type integer (11) $foo = "10.0 pigs " + 1; // $foo est du type integer (11) $foo = "10.0 pigs " + 1.0; // $foo est du type float (11) ?> |
Pour plus d'informations sur les conversions de type, voir les pages de man à propos de la fonction strtod(3).
Si vous voulez testez l'un des exemples de cette section, vous pouvez faire un copier/coller et l'insérer dans un script pour voir comment il se comporte.
Les tableaux
Un tableau PHP est en fait une association ordonnée (map). Une association est un type qui fait correspondre des valeurs à des clés. Ce type est optimisé de diverses façons, qui font que vous pouvez le manipuler comme un tableau à indices réels, une liste (vecteur), ou un table de hachage (qui est une implémentation d'association), dictionnaire, collection, pile, queue et encore d'autres. Comme une valeur peut elle-même être un tableau, vous pouvez simuler facilement un arbre.
Les détails d'implémentation de ces structures sont hors du champs de ce manuel, mais vous trouverez ici un exemple de toutes ces structures.
Syntaxe
Créer un tableau array()
Un tableau array peut être créé avec la fonction array(). Cette fonction prend en argument des structures key => value, séparées par des virgules.
Une clé key est soit un entier positif ou bien une chaîne. Si une clé est la représentation standard d'un entier positif, elle sera interprété comme tel. (i.e. '8' sera interprété comme 8, tandis que '08' sera interprété comme '08').
Une valeur peut être n'importe quoi.
Omettre des clés
Si vous omettez une clé lors de la spécification d'un tableau, l'indice maximum + 1 sera utilisé comme clé par défaut. Si aucun indice numérique n'a été généré, ce sera 0. Si vous spécifiez une qui a déjà été assigné, la nouvelle valeur écrasera la précédente.
array( [key =>]
value
, ...
)
// key is either string
ou entier integer positif
// value peut être n'importe quoi |
La syntaxe à crochets
Vous pouvez aussi modifier un tableau existant en lui assignant simplement des valeurs.
L'assignement de valeurs de tableau se fait en spécifiant la clé entre crochets. Si vous omettez la clé ("$tableau[]"), la valeur sera ajoutée à la fin du tableau.
$arr[key] = value; $arr[] = value; // key est soit une chaîne, soit un entier // value peut être n'importe quoi |
Fonctions pratiques
Il y a toute une panoplie de fonctions pratiques pour travailler avec les tableau : array-functions.
L'élément de langage foreach est spécifiquement dédiée aux tableau : elle permet de passer en revue simplement les valeurs d'un tableau.
Exemples
Le type tableau de PHP est très souple. Voici quelques exemples d'utilisation :
<?php
// ceci
$a = array( 'couleur' => 'rouge'
, 'gout' => 'sucre'
, 'forme' => 'rond'
, 'nom' => 'pomme'
, 4 // cette clé sera 0
);
// est complétement équivalent à
$a['couleur'] = 'rouge';
$a['gout'] = 'sucre';
$a['forme'] = 'rond';
$a['nom'] = 'pomme';
$a[] = 4; // cette clé sera 0
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// va créer le tableau array( 0 => 'a' , 1 => 'b' , 2 => 'c' )
// ou plus simplement array('a' , 'b' , 'c' )
?< |
Exemple 6-3. Utilisation de array()
|
Notez qu'il n'est pas possible actuellement de modifier les valeurs d'un tableau avec une telle boucle. Une solution pour cela est :
Cet exemple crée un tableau d'index minimal 1.
Les tableaux sont ordonnés. Vous pouvez modifier l'ordre des valeurs avec de nombreuses fonctions de classement. Voyez les fonctions de tableaux.
Comme une valeur de tableau peut être n'importe quoi, elle peut aussi être un autre tableau. Comme cela, vous pouvez avoir des tableaux multi-dimensionnels, ou récursifs.
Attention aux tableaux
Pourquoi est ce que $foo[bar] est invalide?
Dans vos vieux scripts, vous pouvez avoir utilisé la syntaxe suivante :
Cela est mauvais, mais ca marche. Pourquoi est-ce mauvais? La raison est que PHP réclame une expression entre les crochets (comme indiqué dans la section sur la syntaxe des tableaux). Cela signifie que vous pouvez écrire quelque chose comme : Ceci est un exemple d'utilisation de retour de fonction dans un index de tableau. PHP reconnait aussi les constantes, et vous pouvez avoir déjà rencontré E_*.<?php $error_descriptions[E_ERROR] = "Une erreur fatale est survenue"; $error_descriptions[E_WARNING] = "PHP a généré une alerte"; $error_descriptions[E_NOTICE] = "Ceci est juste une note grâcieuse"; ?> |
<?php $error_descriptions[1] = "Une erreur fatale est survenue"; $error_descriptions[2] = "PHP a généré une alerte"; $error_descriptions[8] = "Ceci est juste une note grâcieuse"; ?> |
Alors, comment se fait-tile que $foo[bar] fonctionne? C'est parce que bar est attendu comme une constante. Cependant, dans ce cas, aucune constante n'a pour nom bar. PHP suppose alors que vous voulez dire bar littéralement, c'est-à-dire la chaîne "bar", mais que vous avez oublié les guillements.
Alors, pourquoi est-ce mal?
Dans le futur, l'équipe de développement peut vouloir ajouter une nouvelle constante et vous vous retrouverez dans la panade. Par exemple, vous ne pouvez déjà pas utiliser les constantes empty et default, car ce sont des mots reservés.
Et, pour en mettre une autre couche, cette syntaxe est tout simplement obsolète, et risque de ne plus fonctionner du tout un jour ou l'autre.
Note : Lorsque vous activez le rapport d'erreur avec error_reporting() avec E_ALL, PHP générera des notes à chaque fois que cette syntaxe est utilisée. Essayez donc error_reporting(E_ALL); dans vos scripts, pour voir).
Note : Dans une chaîne à guillements doubles, une autre syntaxe est valide. Voyez la section sur Traitement des variables dans les chaînes pour plus de détails.
Les objets
Initialisation d'un objet
Pour initialiser un objet, vous devez utiliser la commande "new" afin de créer linstance de l'objet.
Ressources
Une ressource (resource en anglais), est un type spécial, qui représente une référence sur une ressource externe. Les ressources sont créées par des fonctions dédiées. Reportez vous à l'annexe ressource pour une liste exhaustive des fonctions créant et utilisant ces ressources.
Note : Le type ressource a été introduit en PHP 4.
Libérer des ressources
Grâce au système de comptabilisation des références introduit en PHP 4 (avec le moteur Zend), PHP détecte automatiquement qu'une ressource n'est plus utilisée (comme Java). Dans ce cas, toutes les ressources systèmes utilisées par cette ressource sont libérées automatiquement.
Note : Les connexions persistantes représentent un cas particulier, elles ne seront PAS détruites. Voyez connexions persistantes.
La valeur NULL
La valeur spéciale NULL représente l'absence de valeur. Une variable avec la valeur NULL n'a pas de valeur.
Syntaxe
Il y a seulement une valeur de type NULL, et c'est la constante NULL, insensible à la casse.
Note : La valeur NULL a été introduite en PHP 4.
Définition du type
PHP ne nécessite pas de déclaration explicite du type d'une variable. Le type d'une variable est déterminé par le contexte d'utilisation. Par exemple, si vous assignez une chaîne de caractères à la variable var, var devient une chaîne de caractère. Si vous assignez un nombre entier à var, elle devient un entier.
Un exemple de convertisseur automatique de type est l'opérateur '+'. Si un des opérandes est de type double, alors tous les opérandes sont évalués comme des variables de type double et le résultat est de type double. Sinon, tous les opérandes sont évalués comme des variables de type entier et le résultat sera du type entier. Il est à noter que cela NE CHANGE PAS le type des opérandes. Le seul changement est la manière dont les opérandes sont évaluées.
<?php $foo = "0"; // $foo est une chaîne de caractères (ASCII 48) $foo += 2; // $foo est maintenant du type entier (2) $foo = $foo + 1.3; // $foo est maintenant du type double (3.3) $foo = 5 + "10 Petits cochons"; // $foo est du type entier (15) $foo = 5 + "10 cochonnets"; // $foo est du type entier (15) ?> |
Si les deux derniers exemples vous semblent obscurs ou si vous voulez forcer une variable a être évaluée avec un certain type, reportez-vous au paragraphe Conversion de type ci-dessous. Si vous voulez changer le type d'une variable, intéressez-vous à aux fonctions de conversion de chaînes.
Si vous voulez forcer le type d'une variable, vous pouvez vous reporter à la section transtypage. Si vous voulez changer le type d'une variable, utilisez settype().
Pour tester les exemples de cette section, il suffit d'en faire un copier/coller, et d'insérer les lignes dans un script PHP.
Note : Le comportement de la conversion automatique est actuellement indéfinie.
Bien que dans l'exemple ci-dessus, il semble évident que $a va devenir un tableau, dont le premier élément est 'f', considérez l'exemple suivant :
Etant donné que PHP supporte l'indexation de chaîne avec des offsets identiques à celles des tableaux, l'exemple ci-dessus conduit à un problème : est ce que $a est un tableau, dont le premier élément est "f", ou bien est ce que "f" est le premier élément de la chaîne de caractères $a?
Pour cette raison, aussi bien pour PHP 3.0.12 que PHP 4.0b3-RC4, le résultat de la conversion automatique est considéré comme indéfinie. Des solutions sont en cours de discussion.
Transtypage
La conversion de type en PHP fonctionne de la même manière qu'en C: le nom du type désiré est écrit entre parenthèses devant la variable à transtyper ("cast").
Les conversions autorisées sont:
(int), (integer) - type entier
(bool), (boolean) - booléen
(real), (double), (float) - type double
(string) - ctype chaîne
(array) - type tableau
(object) - type objet
Il est à noter que les tabulations et les espaces sont autorisés à l'intérieur des parenthèses, donc les lignes suivantes sont équivalentes:
Le transtypage n'a pas toujours de résultat prévisible. Pour plus d'informations, voyez :
| Avertissement |
Pour transformer facilement une variable en chaîne, entourez la simplement de guillements doubles. |
Lors de la conversion d'un tableau en chaîne, le résultat sera le mot Array (tableau, en anglais). Lors de la conversion d'un objet en chaîne, le résultat sera le mot Object (objet, en anglais). Dans les deux cas, une alerte sera affichée.
Lorsque vous transtypez un scalaire ou une chaîne en tableau, la variable verra son contenu affecté au premier élément du tableau.
Lorsque vous transtypez un scalaire ou une chaîne en objet, la valeur de la variable sera transformée en attribut de l'objet. L'attribut s'appellera 'scalar':
Chapitre 7. Les variables
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 (ie : $x != $X).
Les noms de variables suivent les mêmes règles de nommage que les autres entités PHP. Un nom de variable valide doit commencer par une lettre ou un souligné (_), suivi de lettres, chiffres ou soulignés. Exprimé sous la forme d'une expression régulière, cela donne : '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Note : Dans nos propos, une lettre peut être une des lettres minuscules (a à z) ou majuscules (A à Z), et les caractères ASCII de 127 à 255 (0x7f-0xff).
<?php $var = "Jean"; $Var = "Paul"; echo "$var, $Var"; // affiche "Jean, Paul" $4site = 'pas encore'; // invalide : commence par un nombre $_4site = 'pas encore'; // valide : commence par un souligné $maïs = 'jaune'; // valide; 'ï' est ASCII 239. ?> |
En PHP 3, les variables sont toujours assignées par valeur. C'est-à-dire, lorsque vous assignez une expression à 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, reportez-vous à Expressions.
PHP 4 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 terme, "devient un alias de", ou encore "pointe sur") la variable originale. Les modifications de la nouvelle variable affecteront l'ancienne, et vice versa. Cela signifie aussi qu'aucune copie n'est faite : l'assignation est donc beaucoup plus rapide. Cela se fera notamment sentir dans des boucles, ou lors d'assignation de grands objets (tableaux).
Pour assigner par référence, ajoutez simplement 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 Pierre"; // Modifie $bar... echo $foo; // $foo est aussi modifiée echo $bar; ?> |
Une chose importante à noter est que seules les variables nommées peuvent être assignées par référence.
Variables prédéfinies
PHP fourni un grand nombre de variables prédéfinies. Cependant, beaucoup de ces variables ne peuvent pas être présentées ici, car elles dépendent du serveur sur lequel elles tournent, de la version du serveur, et de la configuration du serveur, ou encore d'autres facteurs. Certaines de ces variables ne seront pas accessibles lorsque PHP fonctionne en exécutable.
| Avertissement |
En PHP 4.2.0 et plus récent, le jeu de variables prédéfinies qui sont disponibles dans l'environnement global a changé. Les variables d'entrées et de serveurs ne sont plus par défaut placées dans le contexte d'exécution global. Elles sont placées dans les tableaux superglobaux. Vous pouvez toujours forcer l'ancien comportement de PHP en le configurant avec register_globals à On votre fichier php.ini. Pour plus d'informations et d'explications sur ce changement, voyez l'annonce de PHP 4.1.0 (en anglais). |
Depuis la version 4.1.0, PHP fourni un jeu de tableaux prédéfinis, contenant les variables du serveur (si possible), les variables d'environnement et celle d'entrées. Ces nouveaux tableaux sont un peut particuliers, car ils ont automatiquement globaux : ils sont automatiquement disponibles dans tous les environnements d'exécution, sans avoir à utiliser le mot réservé global. Pour cette raison, ils sont dits 'auto-globaux' ou bien encore 'superglobaux' (il n'y a pas de mécanisme PHP pour créer de telles variables. Les superglobales sont listées ci-dessous. Cependant, pour connaître le détails de leur contenu, et une présentation approfondie sur les variables prédéfinies PHP, et leur nature, reportez vous à la section variables prédefinies.
Tableaux superglobaux de PHP
- $GLOBALS
Contient une référence sur chaque variable qui est actuellement disponible dans l'environnement d'exécution global. Les clés de ce tableau sont les noms des variables globales.
- $_SERVER
Les variables fournies par le serveur web, ou bien directement liées à l'environnement d'exécution du script courant. C'est la nouvelle version de l'ancienne variable $HTTP_SERVER_VARS, qui est maintenant obsolète, mais toujours là.
- $_GET
Les variables fournies par le protocole HTTP en méthode GET. C'est la nouvelle version de l'ancienne variable $HTTP_GET_VARS qui est maintenant obsolète, mais toujours là.
- $_POST
Les variables fournies par le protocole HTTP en méthode POST. C'est la nouvelle version de l'ancienne variable $HTTP_POST_VARS qui est maintenant obsolète, mais toujours là.
- $_COOKIE
Les variables fournies par le protocole HTTP, dans les cookies. C'est la nouvelle version de l'ancienne variable $HTTP_COOKIE_VARS qui est maintenant obsolète, mais toujours là.
- $_FILES
Les variables fournies par le protocole HTTP, suite à un téléchargement de fichier. C'est la nouvelle version de l'ancienne variable $HTTP_POST_FILES qui est maintenant obsolète, mais toujours là. Voir Téléchargement par méthode POST, pour plus d'informations.
- $_ENV
Les variables fournies par l'environnement. C'est la nouvelle version de l'ancienne variable $HTTP_ENV_VARS qui est maintenant obsolète, mais toujours là.
- $_REQUEST
Les variables fournies au script par n'importe quel mécanisme d'entrée et qui ne doit recevoir une confiance limitée. Note : lorsque vous exécutez un script en ligne de commande, cette variable ne va pas inclure les variables argv et argc. Elles seront présentes dans la variable $_SERVER. La présence et la valeur des entrées de ce tableau sont réglés par la directive variables_order. Ce tableau n'est l'évolution d'aucune variable d'avant PHP 4.1.0.
- $_SESSION
Les variables qui sont actuellement enregistrées dans la session attachée au script. which are currently registered to a script's session.C'est la nouvelle version de l'ancienne variable $HTTP_SESSION_VARS. Voir le chapitre Sessions handling functions pour plus d'informations.
Missing title
| Avertissement |
Cette section est la documentation qui avait cours jusqu'en PHP version 4.1.2. Elle est laissée ici pour assurer la transition avec les nouvelles versions, qui ont abandonné définitivement leur usage. Nous recommandons vivement au lecteur la section précédente. Pour assurer une meilleure compatibilité de vos scripts avec les nouvelles versions de PHP, n'utilisez plus ces variables. |
Malgré ces données, voici une liste de variables prédéfinies, qui seront accessibles avec une installation ad hoc de PHP3, fonctionnant en module, sous Apache 1.3.6.
Pour la liste complète des variables prédéfinies (et d'autres informations pratiques) reportez-vous (et usez) de phpinfo().
Note : Cette liste n'est pas exhaustive et ne le sera pas. C'est simplement un aperçu des variables prédéfinies qui peuvent être accessibles dans les scripts.
Variables Apache
Ces variables sont créées par le serveur Apache. Si vous utilisez un autre serveur web, il n'est pas sur que celui-ci vous fournira les mêmes variables. Il peut ne pas les fournir, en fournir d'autres. Cependant, un bon nombre de ces variables font partie de l'interface CGI 1.1, et on peut s'attendre à les retrouver.
Notez que peu d'entre elles seront accessibles lorsque PHP est appelé en ligne de commande, (et elles n'auront alors peut être pas de sens)
- $GATEWAY_INTERFACE
Numéro de révision de l'interface CGI du serveur : i.e. 'CGI/1.1'.
- $SERVER_NAME
Le nom du serveur hôte qui éxécute le script suivant. Si le script est exécuté sur un hôte virtuel, ce sera la valeur définie pour cet hôte virtuel.
- $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 : i.e. 'HTTP/1.0';
- $REQUEST_METHOD
Méthode de requête utilisée pour accéder à la page; i.e. 'GET', 'HEAD', 'POST', 'PUT'.
- $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.
- $HTTP_ACCEPT
Contenu de l'en-tête Accept: de la requête courante, s'il y en a une.
- $HTTP_ACCEPT_CHARSET
Contenu de l'en-tête Accept-Charset: de la requête courante, s'elle existe. Par exemple : 'iso-8859-1,*,utf-8'.
- $HTTP_ACCEPT_ENCODING
Contenu de l'en-tête Accept-Encoding: de la requête courante, si elle existe. Par exemple : 'gzip'.
- $HTTP_ACCEPT_LANGUAGE
Contenu de l'en-tête Accept-Language: de la requête courante, si elle existe. Par exemple : 'en'.
- $HTTP_CONNECTION
Contenu de l'en-tête Connection: de la requête courante, si elle existe. Par exemple : 'Keep-Alive'.
- $HTTP_HOST
Contenu de l'en-tête Host: de la requête courante, si elle existe.
- $HTTP_REFERER
L'adresse de la page (si elle existe) qui a conduit le client à la page courante. Cette valeur est affectée par le client, et tous les clients ne le font pas.
- $HTTP_USER_AGENT
Contenu de l'en-tête User_Agent: de la requête courante, si elle existe. C'est une chaîne qui décrit le client HTML utilisé pour voir la page courante. Par exemple : Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Entre autres choses, vous pouvez utiliser cette valeur avec get_browser() pour optimiser votre page en fonction des capacités du client.
- $REMOTE_ADDR
L'adresse IP du client qui demande la page courante.
- $REMOTE_PORT
Le port utilisé par la machine cliente pour communiquer avec le serveur web.
- $SCRIPT_FILENAME
Le chemin absolu jusqu'au script courant.
- $SERVER_ADMIN
La valeur donnée à la directive SERVER_ADMIN (pour Apache), dans le fichier de configuration. Si le script est exécuté par un hôte virtuel, ce sera la valeur définie par l'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é.
- $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 fichier (pas le document root-) jusqu'au script courant, une fois que le serveur a fait une chemin traduction virtuel->réel.
- $SCRIPT_NAME
Contient le nom du script courant. Cela sert lorsque les pages doivent s'appeler elles-mêmes.
- $REQUEST_URI
L'URI qui a été fourni pour accéder à cette page. Par exemple : '/index.html'.
Variables d'environnement
Ces variables sont importées dans l'espace de nom global de PHP, depuis l'environnement sous lequel PHP fonctionne. Beaucoup d'entre elles sont fournies par le shell qui exécute PHP et différents systèmes étant susceptibles de disposer de différents shells, une liste définitive est impossible à établir. Reportez-vous à la documentation de votre shell, pour connaître la liste des variables d'environnement prédéfinies.
Les autres variables d'environment incluent les variables CGI, placées ici, quelquefois la méthode d'éxécution de PHP (CGI ou module).
Variables PHP
Ces variables sont créées par PHP lui_même. Les variables $HTTP_*_VARS ne sont disponibles que si l'option de configuration track_vars a été activée. Lorsque c'est le cas, ces variables existent toujours, même si ce sont des tableaux vides. Cela évite les usurpations mal intentionnées de ces variables.
Note : Depuis PHP 4.0.3, track_vars est toujours activé, quelle que soit la configuration.
Si la directive register_globals est activée, alors ces variables seront aussi disponibles comme variables globales du script : c'est-à-dire, indépendamment des tableaux $HTTP_*_VARS. Cette fonctionnalité doit être utilisée avec précautions, et de préférence, désactivée. Si $HTTP_*_VARS est sécurisé, les équivalents globaux peuvent être écrasés par les données d'entrée de l'utilisateur, avec des intrusions possibles. Si vous ne pouvez pas désactiver register_globals, vous devez prendre toutes les dispositions possibles pour vous assurer que les données utilisées sont sÛres.
- $argv
Tableau des arguments passées 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).
- $PHP_SELF
Le nom du fichier du script en cour d'éxécution, par rapport au document root. Si PHP fonctionne en ligne de commande, cette variable n'est pas disponible.
- $HTTP_COOKIE_VARS
Un tableau associatif des variables passées au script courant via les HTTP cookies. Uniquement possible si le suivi des variables a été activé avec la directive générale track_vars ou avec la directive locale <? php_track_vars ?>.
- $HTTP_GET_VARS
Un tableau associatif des variables passées au script courant via les HTTP GET. Uniquement possible si le suivi des variables a été activé avec la directive générale track_vars ou avec la directive locale <? php_track_vars ?>.
- $HTTP_POST_VARS
Un tableau associatif des variables passées au script courant via les HTTP POST. Uniquement possible si le suivi des variables a été activé avec la directive générale track_vars ou avec la directive locale <? php_track_vars ?>.
- $HTTP_POST_FILES
Un tableau associatif contenant les informations sur les fichiers téléchargés avec la méthode HTTP POST. Reportez-vous au chapitre Téléchargement par méthode POST pour plus de détails sur le contenu de $HTTP_POST_FILES.
$HTTP_POST_FILES n'est disponible que dans les versions 4.0.0 et plus récentes de PHP.
- $HTTP_ENV_VARS
Un tableau associatif des variables passées au script par l'environnement parent.
- $HTTP_SERVER_VARS
Un tableau associatif des variables passées au script par le serveur HTTP. Ces variables sont analogues aux variables décrites ci-dessus.
Portée des variables
La portée d'une variable dépend du contexte dans lequel la variable est définie. Pour la majorité des variables, la portée concerne la totalité d'un script PHP. Mais, lorsque vous définissez une fonction, la portée d'une variable définie dans cette fonction est locale à la fonction. Par exemple:
Ici, la variable $a sera accessible dans le script inclus b.inc. Cependant, dans les fonctions définies par l'utilisateur, une nouvelle définition de cette variable sera donnée, limitée à la fonction. Toute variable utilisée dans une fonction est par définition, locale. Par exemple :
Le script n'affichera rien à l'écran car la fonction echo() utilise la variable locale $a, et celle-ci n'a pas été assignée préalablement dans la fonction. Vous pouvez 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 si vous redéfinissez des 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. Par exemple:
Le script ci-dessus va afficher la valeur "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:
<?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 clef et les valeurs des éléments du tableau comme valeur des variables.
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:
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 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:
Maintenant, à 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 lorsque vous faites des appels récursifs à une fonction. Une fonction récursive est une fonction qui s'appelle elle-même. Il faut faire attention lorsque vous écrivez une fonction récursive car il est facile de faire une boucle infinie. Vous devez vérifier que vous avez bien une condition qui permet de terminer votre récursivité. La fonction suivante compte récursivement jusqu'à 10:
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ée et utilisée dynamiquement. Une variable classique est affecté avec l'instruction suivante:
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édent la variable. C'est-à-dire
A 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
produira le même affichage que :
c'est-à-dire : bonjour monde.
Afin de pouvoir utiliser les variables dynamiques avec les tableaux, vous avez à résoudre un problème ambigu. Si vous écrivez $$a[1], le parseur a besoin de savoir si vous parler de la variable qui a pour nom $a[1] ou bien si vous voulez l'index [1] de la variable $$a. La syntaxe pour résoudre cette ambiguïté est la suivante: ${$a[1]} pour le premier cas, et ${$a}[1] pour le deuxième.
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. Par exemple, considérons le formulaire suivant:
Lorsque ce formulaire est envoyé, le PHP va créer la variable $nom, qui contiendra la valeur que vous avez entrée dans le champs Nom: du formulaire.
Note : La directive de configuration magic_quotes_gpc affecte les valeurs issues des méthodes GET et POST ainsi aue des Cookies. Si cette directive est active, une valeur telle que It's "PHP!" sera automagiquement transformée en It\'s \"PHP!\". L'échappement est nécessaire pour les insertions en base de données. Voyez addslashes(), stripslashes() et magic_quotes_sybase.
Le PHP permet aussi l'utilisation des tableaux dans le contexte de formulaire, mais seulement des tableaux à une seule dimension. Comme cela, vous pouvez rassembler des variables ou utiliser cette fonctionnalité pour récupérer les valeurs d'un choix multiple :
Exemple 7-2. Variables complexes de formulaire
|
Si l'option "track_vars" est activée, soit par l'option de compilation track_vars, soit par la directive de configuration <? php_track_vars ?>, les variables transmises par les méthodes POST et GET pourront aussi être trouvées dans le tableau associatif global $HTTP_POST_VARS ou $HTTP_GET_VARS suivant la méthode utlisée.
Bouton "submit" sous forme d'image
Lorsque vous envoyez le résultat d'un formulaire, vous pouvez utiliser une image au lieu du bouton "submit" standard en utilisant un tag :
Lorsqu'un utilisateur clique sur l'image, le formulaire sera transmis au serveur avec deux variables de plus, sub_x et sub_y. Ces deux variables contiennent les coordonnées de l'endroit où l'utilisateur à cliqué. Les utilisateurs expérimentés remarqueront que les noms de variables sont transmis avec une virgule à la place du caractère "_", mais le PHP fait la conversion automatiquement.
HTTP Cookies
Le PHP supporte les cookies HTTP de manière totalement transparente, comme défini dans les Netscape's Spec. Les cookies sont un mécanisme permettant de stocker des données sur la machine cliente à des fins d'authentification de l'utilisateur. Vous pouvez établir un cookie grâce à la fonction setcookie(). Les cookies font partie intégrante du "header" 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(). Tout cookie envoyé depuis le client sur le serveur sera automatiquement stocké sous forme de variable, comme pour la méthode POST ou GET.
Si vous souhaitez assigner plusieurs valeurs à un seul cookie, il vous faut ajouter les caractères [] au nom de votre cookie. Par exemple :
Il est à noter qu'un cookie remplace le cookie précédent par un cookie de même nom tant que le "path" ou le domaine sont identiques. Donc, pour une application de caddie, vous devez implémenter un compteur et l'incrémenter au fur et à mesure. C'est-à-dire:
Exemple 7-3. Exemple avec setcookie()
|
Variables d'environnement
Le PHP fait en sorte que les variables d'environnement soient accessibles directement comme des variables PHP normales.
<?php
echo $HOME; /* Affiche la valeur de la variable d'environnement HOME,
si celle-ci est affectée. */
?> |
Même si le PHP crée les variables lors de l'utilisation des méthodes GET, POST et cookie, il est de temps en temps préférable de transmettre explicitement la valeur de la variable afin d'être sÛr de la valeur. La fonction getenv() peut être utilisée pour récupérer la valeur des variables d'environnement. Vous pouvez aussi affecter une variable d'environnement grâce à la fonction putenv().
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, jetez un oeil sur :
<?php $varname.ext; /* nom de variable invalide */ ?> |
Pour cette raison, il est important de noter que PHP remplacera automatiquement les points des noms de variables entrantes par des soulignés (underscore).
Détermination du type des variables
Parceque le 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 que vous souhaitez. PHP inclut des fonctions permettant de déterminer le type d'une variable : gettype(), is_long(), is_double(), is_string(), is_array() et is_object().
Chapitre 8. Les constantes
Une constante est un identifiant (un nom) qui représente une valeur simple. Comme leur nom le suggère, cette valeur ne peut jamais être modifiée durant l'exécution du script (les constantes magiques __FILE__ et __LINE__ sont les seules exception). Le nom d'une constante est sensible à la casse, par défaut. Par convention, les constantes sont toujours en majuscules.
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 lettre, chiffres ou soulignés. Sous forme d'expression régulière, cela peut s'exprimer comme ceci : [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
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 127 à 255 (0x7f-0xff).
Les constantes sont accessibles de manière globale.
Syntaxe
Vous pouvez définir une constante en utilisant la fonction define(). Une fois qu'une constante est définie, elle ne peut jamais être modifiée, ou détruite.
Seuls les types de données scalaires peuvent être placés dans une constante : c'est à dire les types booléen, entier, double et chaîne de caractères (soit boolean, integer, double et string).
Vous povuez accéder à la valeur d'une constante en spécifiant simplement son nom. Contrairement aux variables, vous ne devez PAS préfixer le nom de la constante avec $. Vous pouvez aussi utiliser la fonction constant(), pour lire dynamiquement la valeur d'une constante, si vous obtenez le nom de cette constante dynamiquement (retour de fonction, par exemple). Utilisez la fonction get_defined_constants() pour connaître la liste de toutes les fonctions 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 tous cas, ils peuvent avoir des valeurs différentes).
Lorsque vous utilisez une constante non définie, PHP suppose que vous utilisez le nom de la constante. Une note sera générée. Utilisez la fonction defined() pour savoir si une constante existe ou pas.
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 ne peuvent contenir que des scalaires.
Constantes prédéfinies
Les constantes prédéfinies sont toujours disponibles. En voici la liste :
- __FILE__ (insensible à la casse)
Le nom du fichier qui est actuellement exécuté. Si cette constante est utilisée dans le cadre d'un fichier "inclus" (après utilisation de require()), alors le nom du fichier inclus est renvoyée, et non le nom du fichier parent.
- __LINE__ (insensible à la casse)
Le numéro de la ligne qui est actuellement exécutée. Si cette constante est utilisée dans le cadre d'un fichier "inclus" (après utilisation de require()), c'est la position dans le fichier inclus qui est renvoyé.
- PHP_VERSION
La chaîne de caractères de présentation de la version du PHP qui est actuellement utilisée. Par exemple '4.1.0'.
- PHP_OS
Nom du système d'exploitation qui est utilisé par la machine qui fait tourner le PHP. Parmi les valeurs possibles : "AIX", "Darwin" (MacOS), "Linux", "SunOS", "WIN32", "WINNT". Note : cette liste n'est pas exhaustive.
- TRUE
La valeur vraie booléenne, TRUE.
- FALSE
La valeur faux booléenne, FALSE.
- E_ERROR
Dénote une erreur autre qu'une erreur d'analyse ("parse error") qu'il n'est pas possible de corriger.
- E_WARNING
Dénote un contexte dans lequel le PHP trouve que quelque chose ne va pas. Mais l'exécution se poursuit tout de même. Ces alertes-là peuvent être récupérées par le script lui-même. Un exemple serait une expression régulière (regexp) invalide dans la fonction ereg().
- E_PARSE
L'analyseur a rencontré une forme syntaxique invalide dans le script. Correction de l'erreur impossible.
- E_NOTICE
Quelque chose s'est produit, qui peut être ou non une erreur. L'exécution continue. Par exemple, le cas de guillemets doubles (") non refermés, ou bien la tentative d'accéder à une variable qui n'est pas encore affectée.
- E_ALL
Toutes les constantes E_* rassemblées en une seule. Si vous l'utilisez avec error_reporting(), toutes les erreurs et les problèmes que PHP rencontrera seront notifiés.
Les constantes E_* sont généralement utilisées avec la fonction error_reporting().
Vous pouvez définir d'autres constantes en utilisant la fonction define().
Il est à noter que ce sont des constantes, et non pas des macros comme en C. Seulement les données scalaires peuvent être représentées par des constantes.
Chapitre 9. Les expressions
Les expressions sont la partie la plus importante du PHP. En PHP, presque tout ce que vous écrivez 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 vous écrivez "$a = 5", vous assignez 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, vous pouvez 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 :
Considérant que vous êtes familier avec le concept de fonction, (si ce n'est pas le cas, jetez un oeil au chapitre concernant les fonctions), vous serez d'accord que $c = foo() est équivalent à $c = 5, et vous aurez tout à fait raison. 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 3 types de variables scalaires : les valeurs entières, les nombres à virgule flottante et les chaînes de caractères (une variable scalaire est une variable que vous ne pouvez pas scinder en morceau, 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.
Les utilisateurs de PHP/FI 2 ne verront aucun changement. Malgré tout, 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 jeux ici, la valeur numérique constante '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é de droite à gauche, vous pouvez aussi bien écrire '$b = $a = 5'.
Un autre bon exemple du langage orienté expression est la pré-incrémentation et la post-incrémentation, (ainsi que la décrémentation). Les utilisateurs de PHP/FI 2 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. En PHP/FI 2, l'instruction '$a++' n'a aucune valeur (c'est-à-dire que ce n'est pas une expression) et vous ne pouvez donc pas l'utiliser. 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 (pré-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 pré-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 'pré-incrémentation'). L'opérateur de post-incrémentation, qui s'écrit '$variable++', évalue la valeur de la 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 à 0 ou 1, autrement dit FALSE ou TRUE (respectivement). PHP supporte les opérateurs de comparaison > (plus grand que), => (plus grand ou égal), == (égal à), < (plus petit que), <= (plus petit ou égal). 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. Vous savez que si vous voulez incrémenter la variable $a d'une unité, vous devez simplement écrire '$a++'. Mais si vous voulez ajouter la valeur '3' à votre variable ? Vous pouvez écrire plusieurs fois '$a++', mais ce n'est pas la meilleure des méthodes. Un 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. En PHP, comme dans de nombreux autres langages comme le C, vous pouvez é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 vous ne l'avez pas vueà-dire dans d'autre langage, l'opérateur conditionnel ternaire:
Si la valeur de la première sous-expression est vraie (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 troisème sous-expression qui est évaluée et qui constitue le résultat de l'expression.Les exemples suivants devraient vous permettre de mieux comprendre la pré- et 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 */
$e = $d = ++$b; /* Pré-incrémentation, et assignation de la valeur aux
variables $d et $e */
/* à 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 */
$g = double(++$e); /* assigne deux fois la valeur de $e après
incrémentation, 2*7 = 14 to $g */
$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. */
?> |
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. L'expression '$b = $a = 5;', '$a = 5' est 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. Lorsque vous faites des tests sur une variable, dans une boucle conditionnelle par exemple, cela ne vous intéresse pas de savoir qu'elle est la valeur exacte de l'expression. Mais vous voulez seulement savoir si le résultat signifie TRUE ou FALSE (PHP n'a pas de type booléen). La véritable valeur d'une expression en PHP est calculée de la même manière qu'en Perl. Toute valeur numérique différente de 0 est considérée comme étant TRUE. Une chaîne de caractères vide et la chaîne de caractère 0 sont considérées comme FALSE. Toutes les autres valeurs sont vraies. Avec les types de variables non-scalaires (les tableaux et les objets), s'ils ne contiennent aucun élément, renvoient FALSE, sinon, ils renvoient TRUE.
PHP propose une implémentation complète et détaillée des expressions. PHP documente toutes ses expressions dans le manuel que vous êtes en train de lire. Les exemples qui vont suivre devraient vous donner une bonne idée de ce qu'est une expression et comment construire vos propres expressions. Dans tout ce qui va suivre, nous écrirons expr pour indiquer toute expression PHP valide.
Chapitre 10. Les opérateurs
La précédence 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 ("*") à une priorité supérieure par rapport à à l'addition ("+").
Le tableau suivant dresse une liste de la priorité des différents opérateurs dans un ordre croissant de priorité.
Tableau 10-1. Précédence des opérateurs
| Associativité | Opérateurs |
|---|---|
| gauche | , |
| gauche | or |
| gauche | xor |
| gauche | and |
| droite | |
| gauche | = += -= *= /= .= %= &= |= ^= ~= <<=>>= |
| gauche | ? : |
| gauche | || |
| gauche | && |
| gauche | | |
| gauche | ^ |
| gauche | & |
| non-associative | == != === !== |
| non-associative | < <= > >= |
| gauche | << >> |
| gauche | + - . |
| gauche | * / % |
| droite | ! ~ ++ -- (int) (double) (string) (array) (object) @ |
| droite | [ |
| non-associative | new |
Les opérateurs arithmétiques
Vous rappelez-vous des opérations élémentaires apprises à l'école ?
Tableau 10-2. Opérations élémentaires
| Exemple | Nom | Résultat |
|---|---|---|
| $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. |
L'opérateur de division ("/") retourne une valeur entière (le résultat d'une division entière) si les deux opérandes sont entiers (ou bien des chaînes converties en entier. Si l'un des opérandes est un nombre à virgule flottante, ou bien le résultat d'une opération qui retourne une valeur non entière, un nombre à virgule flottante sera retourné.
Les opérateurs d'assignation
L'opérateur d'assignation 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'assignation est la valeur assignée. Par exemple, la valeur de l'expression '$a = 3' est la valeur 3. Cela permet d'utiliser des astuces telles que :
En plus du simple opérateur d'assignation, il existe des "opérateurs combinés" pour tous les opérateurs arithmétiques 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:
<?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!"; ?> |
On peut noter que l'assignation copie le contenu de la variable originale dans la nouvelle variable (assignation par valeur), ce qui fait que les changements de valeur d'une variable ne modifieront pas la valeur de l'autre. Cela peut se revéler important lors de la copie d'un grand tableau durant une boucle. PHP 4 supporte aussi l'assignation par référence, en utilisant la syntaxe $var = &$othervar;, mais ce n'était pas possible en PHP 3. 'L'assignation par référence' signifie que les deux variables contiennent les mêmes données, et que la modification de l'une affecte l'autre. D'un autre côté, la recopie est très rapide.
Opérateurs sur les bits
Les opérateurs sur les bits vous permettent de manipuler les bits dans un entier.
Tableau 10-3. Les opérateurs sur les bits
| Exemple | Nom | Résultat |
|---|---|---|
| $a & $b | ET (AND) | Les bits positionnés à 1 dans $a ET dans $b sont positionnés à 1. |
| $a | $b | OU (OR) | Les bits positionnés à 1 dans $a OU $b sont sont positionnés à 1. |
| $a ^ $b | Xor | Les bits positionnés à 1 dans $a OU dans $b sont positionnés à 1. |
| ~ $a | NON (Not) | 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écalage des bits de $a $b fois par la droite (chaque décalage équivaut à une division par 2). |
Opérateurs de comparaison
Les opérateurs de comparaison, comme leur nom l'indique, vous permettent de comparer deux valeurs.
Tableau 10-4. Opérateurs de comparaison
| Exemple | Nom | Résultat |
|---|---|---|
| $a == $b | Egal | Vrai si $a est égal à $b. |
| $a === $b | Identique | Vrai si $a est égal à $b et qu'ils sont de même type (PHP 4 seulement). |
| $a != $b | Différent | Vrai si $a est différent de $b. |
| $a <> $b | Différent | Vrai si $a est différent de $b. |
| $a < $b | Plus petit que | Vrai si $a est plus petit strictement que $b. |
| $a > $b | Plus grand | Vrai si $a est plus grand strictement que $b. |
| $a <= $b | Inférieur ou égal | Vrai si $a est plus petit ou égal à $b. |
| $a >= $b | Supérieur ou égal | Vrai si $a est plus grand ou égal à $b. |
Un autre opérateur conditionnel est l'opérateur ternaire (":?"), qui fonctionne comme en langage C.
Cette expression renvoie la valeur de l'expression expr2 si l'expression expr1 est vraie, et l'expression expr3 si l'expression expr1 est fausse.Opérateur de contrôle d'erreur
PHP supporte un opérateur de contrôle d'erreur : c'est @. Lorsque cet opérateur est ajouté en préfixe d'une expression PHP, les messages d'erreur qui peuvent être générés par cette expression seront ignorés.
Si l'option track_errors est activée, les messages d'erreurs générés par une expression seront sauvés dans la variable globale $php_errormsg. Cette variable sera écrasée à chaque erreur. Il faut alors la surveiller souvent pour pouvoir l'utiliser.
<?php
/* Erreur intentionnelle (le fichier n'existe pas): */
$my_file = @file ('non_persistent_file') or
die ("Impossible d'ouvrir le fichier : L'erreur est : '$php_errormsg'");
// 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 de fonctionnement est la suivante : si vous pouvez prendre la valeur de quelquechose, vous pouvez le préfixer avec @. Par exemple, vous pouvez ajouter @ aux variables, fonctions, à include(), aux constantes, etc... Vous ne pourrez pas le faire avec des éléments de langage tels que les classes, if et foreach, etc...
Note : La plupart des fonctions d'accès aux bases de données ne retournent pas d'erreur PHP. Il faut y accéder avec une fonction du type base_de_donnees_get_error().
Voir aussi error_reporting().
Opérateur d'exécutions
PHP supporte un opérateur d'exécution : guillemets obliques ("``"). Notez bien la différence entre les guillemets simples (sur la touche 4), et ceux-ci (sur la touche de la livre anglaise). PHP essaiera d'exécuter le contenu de ces guillemets obliques comme une commande shell. Le résultat sera retourné (i.e. : il ne sera pas simplement envoyé à la sortie standard, il peut être assigné à une variable).
Note : Cet opérateur est désactivé lorsque le safe mode est activé.
Voir aussi system(), passthru(), exec(), popen() et escapeshellcmd().
Opérateurs d'incrémentation/Décrémentation
PHP supporte les opérateurs de pré et post incrémentation et décrémentation, comme en C.
Tableau 10-5. Opérateurs d'incrémentation/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 l'incrémente 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. |
Voici un exempla simple
<?php echo "<h3>Post-incrémentation</h3>"; $a = 5; echo "Devrait valoir 5: " . $a++ . "<br>\n"; echo "Devrait valoir 6: " . $a . "<br>\n"; echo "<h3>Pré-incrémentation</h3>"; $a = 5; echo "Devrait valoir 6: " . ++$a . "<br>\n"; echo "Devrait valoir 6: " . $a . "<br>\n"; echo "<h3>Post-décrémentation</h3>"; $a = 5; echo "Devrait valoir 5: " . $a-- . "<br>\n"; echo "Devrait valoir 4: " . $a . "<br>\n"; echo "<h3>Pré-décrémentation</h3>"; $a = 5; echo "Devrait valoir 4: " . --$a . "<br>\n"; echo "Devrait valoir 4: " . $a . "<br>\n"; ?> |
Les opérateurs logiques
Tableau 10-6. Les opérateurs logiques
| Exemple | Nom | Résultat |
|---|---|---|
| $a and $b | ET (And) | Vrai si $a ET $b sont vrais. |
| $a or $b | OU (Or) | Vrai si $a OU $b est vrai |
| $a xor $b | XOR (Xor) | Vrai si $a OU $b est vrai, mais pas les deux en même temps. |
| ! $a | NON (Not) | Vrai si $a est faux. |
| $a && $b | ET (And) | Vrai si $a ET $b sont vrais. |
| $a || $b | OU (Or) | Vrai si $a OU $b est vrai. |
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.
Opérateurs de chaînes
Il y a deux opérateurs de chaînes. 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'assignation concaténant ('.='). Reportez-vous à Opérateurs d'assignations pour plus de détails.
Chapitre 11. Les structures de contrôle
Tous les scripts PHP sont une suite d'instructions. Une instruction peut être une assignation, un appel de fonction, 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'instruction sont décrits dans ce chapitre.
if
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 :
Comme nous l'avons vu dans le paragraphe consacré aux expressions, expr est évaluée à sa vraie valeur. Si l'expression expr est TRUE, PHP exécutera l'instruction et si elle est FALSE, l'instruction sera ignorée.
L'exemple suivant affiche la phrase a est plus grand que b si $a est plus grand que $b:
Souvent, vous voulez 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 autant de fois que vous avez d'instructions à exécuter. A la place, vous pouvez rassembler toutes les instructions dans un bloc. L'exemple suivant affiche a est plus grand que b, et assigne la valeur de la variable $a à la variable $b:
Vous pouvez imbriquer indéfiniment des instructions if les unes dans les autres, ce qui permet une grande flexibilité dans l'exécution d'une partie de code suivant un grand nombre de conditions.
else
Souvent, vous voulez 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 $a, et a est plus petit que b sinon:
Les instructions après le else ne sont exécutées que si l'expression du if est FALSE, et si elle n'est pas suivi par l'expression elseif.elseif
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è 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 condionnelle 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) {
print "a est plus grand que b";
} elseif ($a == $b) {
print "a est égal à b";
} else {
print "a est plus petit que b";
}
?> |
Vous pouvez avoir plusieurs elseif qui s'imbriquent les uns dans les autres, après un if initial. Le premier elseif qui sera évalué à TRUE sera exécuté. En PHP, vous pouvez aussi écrire "else if" en deux mots et son comportement sera identique à la version en un seul mot.
L'expression elseif est exécutée seulement si le if précédent et tout autre elseif précédent est évalués comme FALSE, et que votre elseif est évalué à TRUE.
Syntaxe alternative
Le PHP propose une autre manière de rassembler des instructions à l'intérieur d'un bloc, pour les fonctions 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;, ou endswitch;.
Dans l'exemple ci-desssus, le block HTML "A = 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 elsif et un else utilisant cette autre syntaxe:
while
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 :
La signification d'une boucle while est très simple. Le 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 le PHP exécute l'instruction, on appelle cela une itération). De temps en temps, 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, vous pouvez regrouper plusieurs instructions dans la même boucle while en les regroupant à l'intérieur de parenthèses ou en utilisant la syntaxe suivante:
Les exemples suivants sont identiques, et affichent tous les nombres de 1 à 10:
do..while
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 lorsque vous utilisez une boucle while (l'expression est vérifiée au début de chaque itération).
Il n'y a qu'une syntaxe possible pour les boucles do..while:
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 l'encapsulant dans un do..while(0) la fonction break. Le code suivant montre une utilisation possible:
<?php
do {
if ($i < 5) {
print "i n'est pas suffisamment grand";
break;
}
$i *= $factor;
if ($i < $minimum_limit) {
break;
}
print "i est bon";
...process i...
} while(0);
?> |
Ne vous inquiétez pas si vous ne comprenez pas tout correctement. Vous pouvez écrire des scripts très très puissants sans utiliser cette fonctionnalité.
for
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:
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 l'instruction est exécutée. Si l'évaluation vaut FALSE, l'exécution de la boucle s'arrête.
A la fin de chaque itération, l'expression expr3 est évaluée (exécutée).
Les expressions peuvent éventuellement être laissées vides. 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 n'est pas vraiment très utile, à moins que vous souhaitiez terminer votre boucle par l'instruction conditionnelle break.
Considérons les exemples suivants. Tous affichent les chiffres de 1 à 10:
<?php
/* exemple 1 */
for ($i = 1; $i <= 10; $i++) {
print $i;
}
/* exemple 2 */
for ($i = 1;;$i++) {
if ($i > 10) {
break;
}
print $i;
}
/* exemple 3 */
$i = 1;
for (;;) {
if ($i > 10) {
break;
}
print $i;
$i++;
}
/* exemple 4 */
for ($i = 1; $i <= 10; print $i, $i++) ;
?> |
Bien évidemment, le premier exemple est le plus simple de tous (ou peut être le quatrième), mais vous pouvez aussi pensez qu'utiliser une expression vide dans une boucle for peut être utile parfois.
PHP supporte aussi la syntaxe alternative suivante pour les boucles for :
Les autres langages ont l'instruction foreach pour accéder aux éléments d'un tableau. PHP 3 ne dispose pas d'une telle fonction; PHP 4 en dispose (voir foreach). En PHP 3, vous pouvez combiner while avec list() et each() pour obtenir le même résultat. Reportez-vous aux exemples de la documentation.
foreach
PHP 4 (mais pas PHP 3) inclut une commande foreach, comme en Perl ou d'autres langages. C'est un moyen simple de passer en revue un tableau. Il y a deux syntaxes possibles : la seconde est une extension mineure mais pratique de la première:
<?php foreach(array_expression as $value) commandes foreach(array_expression as $key => $value) commandes ?> |
La première forme passe en revue le tableau array_expression. A chaque itération, la valeur de l'élément courant est assignée à $value et le pointeur interne de tableau est avancé d'un élément (ce qui fait qu'à la prochaine itération, on accédera à l'élément suivant).
La deuxième forme fait exactement la même chose, mais c'est la clé de l'élément courant qui est assigné à la variable $key.
Lorsque foreach démarre, le pointeur interne de fichier est automatiquement ramené au premier élément du tableau. Cela signifie que vous n'aurez pas à faire appel à reset() avant foreach.
Note : De plus, notez que foreach travaille sur une copie du tableau spécifié, et pas sur le tableau lui-même. Par conséquent, le pointeur de tableau n'est pas modifié, comme il le serait avec le fonction each(), et les modifications faites dans le tableau ne seront pas prises en compte dans le tableau original.
Note : foreach n'accepte pas l'opérateur de supppression des erreurs @.
Vous pouvez remarquer que les exemples suivants fonctionnent de manière identique :
<?php
reset($arr);
while (list(, $value) = each ($arr)) {
echo "Valeur: $value<br>\n";
}
foreach ($arr as $value) {
echo "Valeur: $value<br>\n";
}
?> |
<?php
reset($arr);
while (list($key, $value) = each ($arr)) {
echo "Clé: $key; Valeur: $value<br>\n";
}
foreach ($arr as $key => $value) {
echo "Clé: $key; Valeur: $value<br>\n";
}
?> |
Voici quelques exemples de plus :
<?php
/* exemple 1: valeurs seules */
$a = array (1, 2, 3, 17);
foreach ($a as $v) {
print "Valeur courante de \$a: $v.\n";
}
/* exemple 2: valeurs (avec la clé correspondante) */
$a = array (1, 2, 3, 17);
$i = 0; /* pour l'illustration uniquement */
foreach($a as $v) {
print "\$a[$i] => $v.\n";
}
/* exemple 3: clé et valeur */
$a = array (
"un" => 1,
"deux" => 2,
"trois" => 3,
"dix-sept" => 17
);
foreach($a as $k => $v) {
print "\$a[$k] => $v.\n";
}
/* exemple 4: tableaux multi-dimensionnels */
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";
foreach($a as $v1) {
foreach ($v1 as $v2) {
print "$v2\n";
}
}
/* exemple 5: tableaux dynamique */
foreach(array(1, 2, 3, 4, 5) as $v) {
print "$v\n";
}
?> |
break
L'instruction break permet de sortir d'une structure for, while, foreach ou switch.
break accepte un argument numérique optionnel qui vous indiquera combien de structures emboitées ont été interrompues.
<?php
$i = 0;
while ($i < 10) {
if ($arr[$i] == "stop") {
break; /* Vous pouvez aussi écrire 'break 1;' ici. */
}
$i++;
}
/* Utilisation de l'argument optionnel. */
$i = 0;
while ( ++$i ) {
switch ( $i ) {
case 5:
echo "à 5<br>\n";
break 1; /* Ne sort que du switch. */
case 10:
echo "à 10; quitting<br>\n";
break 2; /* Sort du switch et du while. */
default:
break;
}
}
?> |
continue
L'instruction continue est utilisée dans une boucle afin d'éluder les instructions de l'itération courante afin de passer directement à l'itération suivante.
continue accepte un argument numérique optionnel qui vous indiquera combien de structures emboitées ont été ignorées.
<?php
while (list ($cle, $valeur) = each ($arr)) {
if (!($cle % 2)) { // évite les membres impairs
continue;
}
fonction_quelconque($valeur);
}
$i = 0;
while ($i++ < 5) {
echo "Dehors<br>\n";
while (1) {
echo " Milieu<br>\n";
while (1) {
echo " Intérieur<br>\n";
continue 3;
}
echo "Ceci n'est jamais atteint.<br>\n";
}
echo "Ceci non plus.<br>\n";
}
?> |
switch
L'instruction switch équivaut à une série d'instructions if. En de nombreuses occasions, vous aurez besoin 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.
Les deux exemples suivants sont deux manières différentes d'écrire la même chose, l'une en utilisant une séries de if, et l'autre en utilisant l'instruction switch:
<?php
if ($i == 0) {
print "i égale 0";
}
if ($i == 1) {
print "i égale 1";
}
if ($i == 2) {
print "i égale 2";
}
switch ($i) {
case 0:
print "i égale 0";
break;
case 1:
print "i égale 1";
break;
case 2:
print "i égale 2";
break;
}
?> |
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é. Seulement lorsqu'un case est vérifié, 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 vous ne pouvez pas utiliser l'instruction break à la fin de l'instruction case, PHP continuera à exécuter toutes les instructions qui suivent. Par exemple :
<?php
switch ($i) {
case 0:
print "i égale 0";
case 1:
print "i égale 1";
case 2:
print "i égale 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, vous obtiendrez le résultat escompté, c'est-à-dire, l'affiche de "i égal 2". Donc, l'important est de ne pas oublier l'instruction break (même s'il est possible que vous l'omettiez dans certaines circonstances).
Dans une commande 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 votre condition est plus compliquée qu'une simple comparaison, ou bien fait partie d'une boucle, switch sera plus rapide.
La liste de commandes d'un case peut être vide, auquel cas PHP utilisera la liste de commandes du cas suivant.
<?php
switch ($i) {
case 0:
case 1:
case 2:
print "i est plus petit que 3 mais n'est pas négatif";
break;
case 3:
print "i égale 3";
}
?> |
Un case spécial est default. Ce cas est utilisé lorsque tous les case ont échoués. Il doit être le dernier cas listé. Par exemple :
<?php
switch ($i) {
case 0:
print "i égale 0";
break;
case 1:
print "i égale 1";
break;
case 2:
print "i égale 2";
break;
default:
print "i n'est ni égal à 2, ni à 1, ni à 0.";
}
?> |
Une autre chose à mentionner est que l'instruction case peut être une expression à de type scalaire, c'est-à-dire nombre entier, nombre à virgule flottante et chaîne de caractères. Les tableaux sont sans intérêt dans ce contexte-là.
La syntaxe alternative pour cette structure de contrôle est la suivante : pour plus d'informations, voir syntaxes alternatives).
declare
L'élément de langage declare sert à ajouter des directives d'éxécutions dans un bloc de code. La syntaxe de declare est similaire à la syntaxe des autres fonctions de contrôle :
L'expression directive permet de contrôler l'intervention du bloc declare. Actuellement, une seule directive est reconnue : la directive ticks (Voir plus bas pour plus de détails) sur les ticks).
L'expression statement 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.
Ticks
Un tick est un événement qui intervient toutes les N commandes bas niveau, exécutées par l'analyseur dans le bloc de declare. La valeur de N est spécifiée avec la syntaxe ticks=N dans le bloc de directive declare.
Un événement qui intervient à chaque tick est spécifié avec la fonction register_tick_function(). Reportez vous à l'exemple ci-dessous pour plus de détails. Notez que plus d'un événement peut intervenir par tick.
<PRE>
<?php
// Un fonction qui enregistre l'heure à laquelle elle est appelée
function profile($dump = FALSE){
static $profile;
// Retourne les horaires stockés dans le profile, et l'efface
if ($dump) {
$temp = $profile;
unset ($profile);
return ($temp);
}
$profile[] = microtime ();
}
// Enregistre un gestionnaire de tick
register_tick_function("profile");
// Initialise la fonction avant le bloc de déclaration
profile();
// Exécute un bloc de code, et appele un tick toutes les deux secondes
declare (ticks=2) {
for ($x = 1; $x < 50; ++$x) {
echo similar_text(md5($x), md5($x*$x)), "<br>";
}
}
?> |
Les ticks sont bien pratiques pour débugger, implémenter un multi-tâches simple, des entrées sorties en tâche de fond, ou bien d'autres choses, avec PHP.
Voir aussi register_tick_function() et unregister_tick_function().
require()
La commande require() se remplace elle-même par le contenu du fichier spécifié, comme les préprocesseurs C le font avec la commande #include.
Il est important de noter que lorsqu'un fichier est include() ou require(), les erreurs d'analyse apparaîtront en HTML tout au début du fichier, et l'analyse du fichier parent ne sera pas interrompue. Pour cette raison, le code qui est dans le fichier doit être placé entre les balises habituelles de PHP.
require() n'est pas vraiment une fonction PHP : c'est plus une instruction du langage. Elle ne fonctionne pas comme les fonctions standards. Par exemple, require() est indépendante des structures de contrôle (cela ne sert à rien de la placer dans une condition, elle sera toujours exécutée). De plus, elle ne retourne aucune valeur. Lire une valeur retournée par un require() retourne une erreur d'analyse.
Contrairement à include(), require() va toujours lire dans le fichier cible, même si la ligne n'est jamais exécutée. Si vous souhaitez une inclusion conditionnelle, utilisez include(). La condition ne va jamais affecter require(). Cependant, si la ligne de require() n'est jamais exécutée, le code du fichier ne le sera jamais non plus.
Les boucles n'affectent pas le comportement de require(). Même si le code contenu dans le fichier source est appelé dans la boucle, require() n'est exécuté qu'une fois.
Cela signifie qu'on ne peut pas mettre un require() dans une boucle, et s'attendre à ce qu'il inclue du code à chaque itération. Pour cela, il faut utiliser include().
Attention : include() et require() ajoutent le contenu du fichier cible dans le script lui-même. Elles n'utilisent pas le protocole HTTP ou tout autre protocole. Toute variable qui est dans le champs du script sera accessible dans le fichier d'inclusion, et vice-versa.
<?php
require ("file.inc?varone=1&vartwo=2");
/* Ne fonctionne pas. */
$varone = 1;
$vartwo = 2;
require ("file.inc");
/* $varone et $vartwo seront accessibles à file.inc */
?> |
Ne vous laissez pas abuser par le fait que vous pouvez requérir ou inclure des fichiers via HTTP en utilisant la fonctionnalité de gestion des fichiers distants ce qui est au dessus reste vrai.
En PHP 3, il est possible d'exécuter une commande return depuis un fichier inclut, tant que cette commande intervient au niveau global du fichier inclus. Elle ne doit intervenir dans aucun bloc (entre accolade {}). En PHP 4, cette possibilité a été supprimée. Si vous en avez besoin, utilisez plutôt include().
include()
La fonction include() inclus et évalue le fichier spécifié en argument.
Il est important de noter que lorsqu'un fichier est include() ou require(), les erreurs d'analyse apparaîtront en HTML tout au début du fichier, et l'analyse du fichier parent ne sera pas interrompue. Pour cette raison, le code qui est dans le fichier doit être placé entre les balises habituelles de PHP.
Cela se produit à chaque fois que la fonction include() est rencontrée. Donc, vous pouvez utiliser la fonction include() dans une boucle pour inclure un nombre infini de fois un fichier, ou même des fichiers différents.
<?php
$files = array ('premier.inc', 'second.inc', 'troisieme.inc');
for ($i = 0; $i < count($files); $i++) {
include $files[$i];
}
?> |
include() diffère de require() car le fichier inclus est ré-évaluée à chaque fois que la commande est exécutée, tandis que require() est remplacée par le fichier cible lors de la première exécution, que son contenu soit utilisé ou non. De plus, cela se fait même s'il est placé dans une structure conditionnelle, comme dans un if).
Parceque la fonction include() nécessite une construction particulière, vous devez l'inclure dans un bloc si elle est incluse dans une structure conditionnelle.
<?php
/* Ceci est faux, et ne fonctionnera pas comme on l'attend. */
if ($condition)
include($file);
else
include($other);
/* Ceci est CORRECT. */
if ($condition) {
include($file);
} else {
include($other);
}
?> |
En PHP 3, il est possible d'exécuter une commande return depuis un fichier inclus, tant que cette commande intervient au niveau global du fichier inclus. Elle ne doit intervenir dans aucun bloc (entre accolade {}). En PHP 4, cette possibilité a été supprimée. Cependant, PHP 4 vous autorise à retourner des valeurs d'un fichier inclus. Vous pouvez traiter include() comme une fonction normale, qui retourne une valeur. Mais cela génère une erreur d'analyse en PHP 3.
Exemple 11-1. include() en PHP 3 et PHP 4 On suppose que le fichier test.inc existe, et est placé dans le même dossier que le fichier principal :
On suppose que le fichier main.html contient ceci :
Lorsque main.html est appelé en PHP 3, il va générer une erreur d'analyse (parse error) à la ligne 2; vous ne pouvez pas vous attendre à un retour sur une fonction include() en PHP 3. En PHP 4, cependant,le résultat sera :
Supposons maintenant que main.html a été modifié et contient maintenant le code suivant :
En PHP 4, l'affichage sera :
L'erreur d'analyse ci-dessus est le résultat du fait que la commande return est dans un bloc qui n'est pas une fonction, dans test.inc. Lorsque le return est sorti du bloc, l'affichage devient :
Le '27' est du au fait que PHP 3 ne supporte pas le return dans ces fichiers. |
Il est important de noter que lorsqu'un fichier est include() ou require(), les erreurs d'analyse apparaîtront en HTML tout au début du fichier, et l'analyse du fichier parent ne sera pas interrompue. Pour cette raison, le code qui est dans le fichier doit être placé entre les balises habituelles de PHP.
<?php
include ("file.inc?varone=1&vartwo=2"); /* ne fonctionne pas. */
$varone = 1;
$vartwo = 2;
include ("file.inc"); /* $varone et $vartwo sont accessibles dans file.inc */
?> |
Ne vous laissez pas abuser par le fait que vous pouvez requérir ou inclure des fichiers via HTTP en utilisant la fonctionnalité de gestion des fichiers distants ce qui est au dessus reste vrai.
Voir aussi readfile(), require() et virtual().
require_once()
La commande require_once() se remplace elle-même par le fichier spécifié, un peu comme les commandes de préprocesseur C #include, et ressemble sur ce point à require(). La principale différence est qu'avec require_once(), vous êtes assurés que ce code ne sera ajouté qu'une seule fois, évitant de ce fait les redéfinitions de variables ou de fonctions, génératrices d'alertes.
Par exemple, si vous créez les deux fichiers d'inclusion utils.inc et foolib.inc
Exemple 11-4. cause_error_require.php
|
LES GLOBALES SONT SYMPA
Ce code requiert utils.inc une deuxième fois, car il est requis
dans foolib.inc
Utilisation de GoodTea: Le Earl Grey est délicieux!
Affichage de foo:
Array
(
[0] => 1
[1] => Array
(
[0] => complexe
[1] => quaternion
)
) |
Notez aussi que, de la même manière que les préprocesseurs traitent les #include, cette commande est exécutée au moment de la compilation, c'est-à-dire lorsque le script est analysée, et avant qu'il soit exécuté, et ne doit pas être utilisée pour insérer des données dynamiques liées à l'éxécution. Il vaut alors mieux utiliser include_once() ou include().
Pour plus d'exemples avec require_once() et include_once(), jetez un oeil dans le code de PEAR inclus dans la dernière distribution de PHP.
Voir aussi : require(), include(), include_once(), get_required_files(), get_included_files(), readfile(), et virtual().
include_once()
La commande 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.
Comme précisé dans la section require_once(), la fonction include_once() est utilisée de préférence lorsque le fichier doit être inclus ou évalué plusieurs fois dans un script, ou bien lorsque vous voulez être sÛr qu'il ne sera inclus qu'une seule fois, pour éviter des redéfinitions de fonction.
Pour plus d'exemples avec require_once() et include_once(), jetez un oeil dans le code de PEAR inclus dans la dernière distribution de PHP.
Voir aussi: require(), include(), require_once(), get_required_files(), get_included_files(), readfile(), et virtual().
Chapitre 12. Les fonctions
Les fonctions utilisateur
Une fonction peut être définie en utilisant la syntaxe suivante :
<?php
function foo ($arg_1, $arg_2, ..., $arg_n) {
echo "Exemple de fonction.\n";
return $retval;
}
?> |
Tout code PHP, correct syntaxiquement, peut apparaître dans une fonction et dans une définition de classe.
En PHP 3, les fonctions doivent être définies avant qu'elles ne soient utilisées. Ce n'est plus le cas en PHP 4.
PHP ne supporte pas le surchargement de fonction, ni la destruction ou la redéfinition de fonctions déjà déclarées.
PHP 3 ne supporte pas un nombre variable d'arguments (voir valeurs par défault d'arguments pour plus d'informations). PHP 4 supporte les deux : voir liste variable d'arguments de fonction et les fonctions de références que sont func_num_args(), func_get_arg(), et func_get_args() pour plus d'informations.
Les arguments de fonction
Des informations peuvent être passées à une fonction en utilisant un tableau d'arguments, dont chaque élément est séparé par une virgule. Un élément peut être une variable ou une constante.
PHP supporte le passage d'arguments par valeur (méthode par défaut), par référence. Les listes variables d'arguments sont supportées par PHP 4 et les versions plus récentes. Voir liste variable d'arguments de fonction et les fonctions utiles que sont func_num_args(), func_get_arg(), et func_get_args(). Fonctionnellement, on peut arriver au même résultat en passant un tableau comme argument :
Passage d'arguments par référence
Par défaut, les arguments sont passés à la fonction par valeur (donc vous pouvez changer la valeur d'un argument dans la fonction, cela ne change pas sa valeur à l'extérieur de la fonction). Si vous voulez que vos fonctions puissent changer la valeur des arguments, vous devez passer ces arguments par référence.
Si vous voulez qu'un argument soit toujours passé par référence, vous pouvez ajouter un '&' devant l'argument dans la déclaration de la fonction :
<?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.'
?> |
Si vous souhaitez passer une variable par référence à une fonction mais de manière ponctuelle, vous pouvez ajouter un '&' devant l'argument dans l'appel de la fonction:
Valeur par défaut des arguments
Vous pouvez définir comme en C++ des valeurs par défaut pour les arguments de type scalaire :
<?php
function servir_apero ($type = "ricard") {
return "Servir un verre de $type.\n";
}
echo servir_apero();
echo servir_apero("whisky");
?> |
La fonction ci-dessus affichera :
Servir un verre de ricard. Servir un verre de whisky. |
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.
Il est à noter que si vous utilisez des arguments avec valeur par défaut avec d'autres sans valeur par défaut, les premiers doivent être placés à la suite de tous les paramètres sans valeur par défaut. Sinon, cela ne fonctionnera pas. Considérons le code suivant :
<?php
function faireunyaourt ($type = "acidophilus", $flavour) {
return "Préparer un bol de $type $flavour.\n";
}
echo faireunyaourt ("framboise"); // ne fonctionne pas comme voulu
?> |
L'affiche du code ci-dessus est le suivant :
Warning: Missing argument 2 in call to faireunyaourt() in /usr/local/etc/httpd/htdocs/PHP 3test/functest.html on line 41 Préparer un bol de framboise. |
Maintenant comparons l'exemple précédent avec l'exemple suivant :
<?php
function faireunyaourt ($flavour, $type = "acidophilus") {
return "Préparer un bol de $type $flavour.\n";
}
echo faireunyaourt ("framboise"); // fonctionne comme voulu
?> |
L'affichage de cet exemple est le suivant :
Préparer un bol de acidophilus framboise. |
Nombre d'arguments variable
PHP 4 supporte les fonctions à nombre d'arguments variable. C'est très simple à utiliser, avec les fonctions func_num_args(), func_get_arg(), et func_get_args().
Aucune syntaxe particulière n'est nécessaire, et la liste d'argument doit toujours être fournie explicitement avec la définition de la fonction, et se comportera normalement.
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.
Vous ne pouvez pas renvoyer plusieurs valeurs en même temps, mais vous pouvez obtenir le même résultat en renvoyant un tableau.
<?php
function petit_nombre() {
return array (0, 1, 2);
}
list ($zero, $one, $two) = petit_nombre();
?> |
Pour retourner une référence d'une fonction, utilisez l'opérateur & aussi bien dans la déclaration de la fonction que dans l'assignation de la valeur de retour.
old_function
L'instruction old_function vous permet de déclarer une fonction en utilisant une syntaxe du type PHP/FI2 (au détail près que vous devez remplacer l'instruction 'function' par 'old_function'.)
C'est une fonctionnalité obsolète et elle ne devrait être utilisée que dans le cadre de conversion de PHP/FI2 vers PHP 3
| Avertissement |
Les fonctions déclarées comme old_function ne peuvent pas être appelées à partir du code interne du PHP. Cela signifie, par exemple, que vous ne pouvez pas les utiliser avec des fonctions comme usort(), array_walk(), et register_shutdown_function(). Vous pouvez contourner ce problème en écrivant une fonction d'encapsulation qui appellera la fonction old_function. |
Fonctions-variable
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 autre, pour faire des fonctions call-back, des tables de fonctions...
Les fonctions-variables ne peuvent pas fonctionner avec les éléments de langage comme les echo(), unset(), isset() et empty(). C'est une des différences majeures entre les fonctions PHP et les éléments de langage.
Chapitre 13. Les classes et les objets
Les classes : class
Une classe est une collection de variables et de fonctions qui fonctionnent avec ces variables. Une classe est définie en utilisant la syntaxe suivante :
<?php
class Caddie {
var $items; // Eléments de notre panier
// Ajout de $num articles de type $artnr au panier
function add_item ($artnr, $num) {
$this->items[$artnr] += $num;
}
// Suppression de $num articles du type $artnr du panier
function remove_item ($artnr, $num) {
if ($this->items[$artnr] > $num) {
$this->items[$artnr] -= $num;
return TRUE;
} else {
return FALSE;
}
}
}
?> |
L'exemple ci-dessus définit la classe Caddie qui est composée d'un tableau associatif contenant les articles du panier et de deux fonctions, une pour ajouter et une pour enlever des éléments au panier.
| Attention |
Les notes suivantes ne sont valable que pour PHP 4. Le nom stdClass est utilisé en interne par Zend et ne doit pas être utilisé. Vous ne pouvez pas nommer une classe stdClass en PHP. Les noms de fonctions __sleep et __wakeup sont magiques en PHP. Vous ne pouvez pas utiliser ces noms de fonctions dans vos classes, à moins que vous ne souhaitiez utiliser la magie qui y est associée. PHP se réserve l'usage de tous les noms de fonctions commençants par __, pour sa propre magie. Il est vivement recommandé de ne pas utilser des noms de fonctions commençants par __, à moins que vous ne souhaitiez utiliser la magie qui y est associée. |
Note : En PHP 4, seuls les initialiseurs constants pour les variables var sont autorisés. Utilisez les constructeurs pour les initialisations variables, ou utilisant des expressions.
<?php /* Aucune de ces syntaxes ne fonctionnera en PHP 4 */ class Caddie { var $date_du_jour = date("d/m/Y"); var $name = $firstname; var $owner = 'Fred ' . 'Jones'; var $items = array("DVD", "Télé","Magnétoscope"); } /* Voici comment cela doit se faire désormais. */ class Caddie { var $date_du_jour; var $name; var $owner; var $items; function Caddie() { $this->date_du_jour = date("d/m/Y"); $this->name = $GLOBALS['firstname']; /* etc... */ } } ?>
Les classes forment un type de variable. Pour créer une variable du type désiré, vous devez utiliser l'opérateur new.
<?php
$cart = new Caddie;
$cart->add_item("10", 1);
$another_cart = new Cart;
$another_cart->add_item("0815", 3);
?> |
L'instruction ci-dessus crée l'objet $cart de la class Caddie. La fonction add_idem() est appelée afin d'ajouter l'article numéro 10 dans le panier. 3 articles numéro 0815 sont ajoutés au cart $another_cart.
$cart et $another_cart disposent des fonctions add_item(), remove_item() et de la variable items. Ce sont des fonctions et variables distinctes. Vous pouvez vous représenter les objets comme des dossiers sur votre disque dur. Vous pouvez avoir deux fichiers "lisez-moi.txt" sur votre disque dur, tant qu'ils ne sont pas dans le même répertoire. De même que vous devez alors taper le chemin complet jusqu'au fichier, vous devez spécifier le nom complet de la méthode avant de l'employer : en termes PHP, le dossier racine est l'espace de nom global, et le séparateur de dossier est ->. Par exemple, les noms $cart->items et $another_cart->items représentent deux variables distinctes. Notez que le nom de la variable est alors $cart->items, et non pas $cart->$items : il n'y a qu'un seul signe $ dans un nom de variable.
<?php
// correct, $ unique
$cart->items = array("10" => 1);
// incorrect, car $cart->$items devient $cart->""
$cart->$items = array("10" => 1);
// correct, mais risque de ne pas se comporter comme prévu
// $cart->$myvar devient $ncart->items
$myvar = 'items';
$cart->$myvar = array("10" => 1);
?> |
A l'intérieur d'une définition de classe, vous ne savez pas le nom de la variable à partir duquel l'objet sera accessible dans le script. On ne peut prévoir que l'objet créé sera affecté à la variable $cart ou $another_cart. Donc, vous ne pouvez pas utiliser la syntaxe $cart->items. Mais pour pouvoir accéder à aux méthodes et membres d'un objet, vous pouvez utiliser la variable spéciale $this, qui peut s'interpréter comme 'moi-même', ou bien 'l'objet courant'. Par exemple, '$this->items[$artnr] += $num;' peut se lire comme 'ajouter $num au compteur $artnr de mon propre tableau de compteur' ou bien 'ajouter $num au compteur $artnr du tableau de compteurs de l'objet courant'.
extends : héritage
Souvent, vous aurez besoin d'une classe avec des méthodes et fonctions similaires à une autre classe. En fait, il est bon de définir des classes génériques, qui pourront être réutilisées et adaptées à tous vos projets. Pour faciliter cela, une classe peut être une extension d'une autre classe. La classe dérivée hérite alors de toutes les méthodes et variables de la classe de base (cet héritage a ça de bien que personne ne meurt pour en profiter), mais peut définir ses propres fonctions et variables, qui s'ajouteront. Une classe ne peut hériter que d'une seule autre classe, et l'héritage multiple n'est pas supporté. Les héritages se font avec le mot clé 'extends'.
<?php
class Caddie_nomme extends Caddie {
var $owner;
function set_owner ($name) {
$this->owner = $name;
}
}
?> |
L'exemple ci-desssus définit la classe Caddie_nomme qui possède les même variables que la classe Caddie et la variable $owner en plus, ainsi que la fonction set_owner(). Vous créez un panier nominatif de la même manière que précédemment, et vous pouvez alors affecter un nom au panier ou en connaître le nom. Vous pouvez de toutes les façons utiliser les même fonctions que sur un panier classique.
Constructor : constructeur
| Attention |
En PHP 3 et PHP 4, les constructeurs se comportent différemment. La sémantique de PHP 4 est fortement recommandée. |
Le constructeur est la fonction qui est appelée automatiquement par la classe lorsque vous créez une nouvelle instance d'une classe a l'aide de l'opérateur new. La fonction constructeur a le même nom que la classe. En PHP 3, une fonction devient le constructeur si elle porte le même nom que la classe. En PHP 4, une fonction devient un constructeur si elle porte le même nom que la classe dans laquelle elle est définit. La différence est subtile, mais cruciale.
<?php
class Auto_Caddie extends Caddie {
function Auto_Caddie () {
$this->add_item ("10", 1);
}
}
// Cette syntaxe est valable en PHP 3 et 4
?> |
L'exemple ci-dessus définit la classe Auto_Caddie qui hérite de la classe Caddie et définit le construteur de la classe. Ce dernier initialise le panier avec 1 article de type numéro 10 dès que l'instruction "new" est appelée. La fonction constructeur peut prendre ou non des paramètres optionnels, ce qui la rend beaucoup plus pratique. Pour pouvoir utiliser cette classe sans paramètre, tous les paramètres du constructeurs devraient être optionnels, en fournissant une valeur par défaut, comme ci-dessous.
<?php
// Cette syntaxe est valable en PHP 3 et 4
class Constructor_Cart extends Cart {
function Constructor_Cart ($item = "10", $num = 1) {
$this->add_item ($item, $num);
}
}
// Création du caddie
$default_cart = new Constructor_Cart;
// Création d'un vrai caddie
$different_cart = new Constructor_Cart ("20", 17);
?> |
| Attention |
En PHP 3, les classes dérivées et les constructeurs ont un certains nombre de limitations. Les exemples suivants doivent être lus avec beaucoup d'attention pour comprendre ces limitations. |
<?php
class A {
function A() {
echo "Je suis le constructeur de A.<br>\n";
}
}
class B extends A {
function C() {
"Je suis une fonction standard.<br>\n";
}
}
// Aucun constructeur n'est appelé en PHP 3!!
$b = new B;
?> |
En PHP 3, aucun constructeur ne sera appelé dans l'exemple ci-dessus. La règle en PHP 3 est : 'Un constructeur est une fonction qui a le même nom que la classe'. Le nom de la classe est B, et il n'y a pas de fonctions qui s'appelle B() dans la classe B. Rien ne se passe.
Ceci est corrigé en PHP 4, avec l'introduction d'une nouvelle règle : Si une classe n'a pas de constructeur, le constructeur de la classe de basse est appelé, s'il existe. L'exemple ci-dessus affichera 'Je suis le constructeur de A.<br>' en PHP 4.
<?php
class A {
function A() {
echo "Je suis le constructeur de A.<br>\n";
}
function B() {
echo "Je suis une fonction standard appelée B dans la classe A.<br>\n";
echo "Je ne suis pas le constructeur de A.<br>\n";
}
}
class B extends A {
function C() {
echo "Je suis une fonction standard.<br>\n";
}
}
// Cette syntaxe va appeler B() comme constructeur.
$b = new B;
?> |
En PHP 3, la fonction B() de la classe A va soudaiement devenir le constructeur de la classe B, bien qu'il n'ai pas été prévu pour. La règle de PHP 3 est 'Un constructeur est une fonction qui a le même nom que la classe'. PHP 3 ne se soucie guère si la fonction est définie dans la classe B ou si elle a été héritée.
Ceci est corrigé en PHP 4, avec l'introduction d'une nouvelle règle : 'Un constructeur est une classe de même nom, définit dans la classe elle-même'. Donc, en PHP 4, la classe B n'a pas de constructeur par elle-même, et le constructeur de la classe A aura été appelé, affichant : 'Je suis le constructeur de A.<br>'.
| Attention |
Ni PHP 3 ni PHP 4 n'appelle automatiquement le constructeur de la classe supérieure depuis le constructeur de la classe dérivée. Il est de votre responsabilité de propager l'appel des constructeurs. |
Note : Il n'y a pas de destructeurs en PHP 3 et PHP 4. Vous pouvez utiliser la fonction register_shutdown_function() à la place, pour simuler un destructeur.
Les destructeurs sont des fonctions qui sont appelées lorsqu'un objet est détruit, soit avec la fonction unset() soit par simple sortie d'une fonction (cas des variables locales). Il n'y a pas de destructeurs en PHP.
Opérateur ::
| Attention |
La documentation suivante n'est valable que pour PHP 4. |
Parfois, il est pratique de faire référence aux fonctions est variables d'une classe de base, ou bien d'utiliser des méthodes de classes qui n'ont pas encore d'objets créés. L'opérateur :: est là pour ces situations.
<?php
class A {
function example() {
echo "Je suis la fonction originale A::example().<br>\n";
}
}
class B extends A {
function example() {
echo "Je suis la fonction redéfinie B::example().<br>\n";
A::example();
}
}
// Il n'y a pas d'objets de classe A.
// L'affichage est :
// Je suis la fonction originale A::example().<br>
A::example();
// Création d'un objet de la classe B.
$b = new B;
// L'affichage est :
// Je suis la fonction redéfinie B::example().<br>
// Je suis la fonction originale A::example().<br>
$b->example();
?> |
Les exemples ci-dessus appellent la fonction example() dans la classe A, mais il n'y a pas encore d'objet de classe A, alors il n'est pas possible d'écrire $a->example(). A la place, on appelle la fonction example() comme une fonction de classe, c'est-à-dire avec le nom de la classe elle-même, et sans objet.
Il y a des fonctions de classe, mais pas de variables de classe. En fait, il n'y a aucun objet au moment de l'appel de la fonction. Donc, une fonction de classe ne peut accéder à aucune variable (mais elle peut accéder aux variables locales et globales). Il faut proscire l'utilisation de $this.
Dans l'exemple ci-dessus, la classe B redéfinit la fonction example(). La définition originale dans la classe A est remplacée par celle de B, et n'est plus accessible depuis B, à moins que vous n'appeliez spécifiquement la fonction example() de la classe A avec l'opérateur ::. Ecrivez A::example() pour cela (en fait, il faudrait écrire parent::example(), comme expliqué dans la section suivante).
Dans ce contexte, il y a un objet courant, qui peut avoir d'autres variables objets. De ce fait, lorsqu'il est utilisé depuis une méthode d'un objet, vous pouvez utiliser $this.
parent
Il arrive que vous ayez à écrire du code qui faire référence aux variables et fonctions des classes de base. C'est particulièrement vrai si votre classe dérivée est une spécialisation de votre classe de base.
Au lieu d'utiliser le nom litéral de votre classe de base dans votre code, vous pouvez utiliser le mot réservé parent, qui représente votre classe de base (celle indiqué par extends, dans la déclaration de votre classe). En faisant cela, vous éviter d'appeler le nom de votre classe de base directement dans votre code. Si votre héritage change, vous n'aurez plus qu'à modifier le nom de la classe dans la déclaration extends de votre classe.
<?php
class A {
function example() {
echo "Je suis A::example() et je fournis une fonctionnalité de base.<br>\n";
}
}
class B extends A {
function example() {
echo "Je suis B::example() et je fournis une fonctionnalité supplémentaire.<br>\n";
parent::example();
}
}
$b = new B;
// Cette syntaxe va appeler B::example(), qui, à sont tour, va appeler A::example().
$b->example();
?> |
Sauvegarde d'objets - cas des sessions
Note : En PHP 3, les objets perdent leur association de classe à travers le processus de sauvegarde et relecture. Le type de la variable après relecture est bien objet mais il n'a plus de méthode ou de nom de classe. Cela rend la focntionnalité plutôt inutile (l'objet est devenu un tableau avec une syntaxe étrange).
| Attention |
La documentation suivante n'est valable que pour PHP 4. |
serialize() retourne une chaîne représentant une valeur qui peut être stockée dans les sessions de PHP, ou une base de données. unserialize() peut relire cette chaîne pour recréer la valeur originale. serialize() va sauver toutes les variables d'un objet. Le nom de la classe sera sauvé mais par les méthodes de cet objet.
Pour permettre à unserialize() de lire un objet, la classe de cet objet doit être définie. C'est-à-dire, si vous avez un objet $a de la classe A dans une page php1.php, et que vous le linéarisez avec serialize(), vous obtiendrez une chaîne qui fait référence à la classe A, et contient toutes les valeurs de $a. Pour pouvoir le relire avec la fonction unserialize() dans une page page2.php, il faut que la définition de la classe A soit présente dans cette deuxième page. Cela peut se faire de manière pratique en sauvant la définition de la classe A dans un fichier séparé, et en l'incluant dans les deux pages page1.php et page2.php.
<?php
classa.inc:
class A {
var $one = 1;
function show_one() {
echo $this->one;
}
}
?>
page1.php:
<?php
include("classa.inc");
$a = new A;
$s = serialize($a);
// enregistrez $s où la page2.php pourra le trouver.
$fp = fopen("store", "w");
fputs($fp, $s);
fclose($fp);
?>
page2.php:
<?php
// Ceci est nécessaire pour que unserialize() fonctionne correctement
include("classa.inc");
$s = implode("", @file("store"));
unserialize($s);
// maintenant, utilisez la méthode show_one de l'objet $a.
$a->show_one();
?> |
Si vous utilisez les sessions et la fonction session_register() pour sauver des objets, ces objets seront linéarisés automatiquement avec la fonction serialize() à la fin de chaque script, et relus avec unserialize() au début du prochain script. Cela signifie que ces objets peuvent apparaître dans n'importe quelle page qui utilise vos sessions.
Il est vivement recommandé d'inclure la définition de classe dans toutes vos pages, même si vous n'utilisez pas ces classes dans toutes vos pages. Si vous l'oubliez et qu'un tel objet est présent, il perdra sa classe, et deviendra un objet de classe stdClass sans aucune fonction, et donc, plutôt inutile.
Si, dans l'exemple ci-dessus, $a devient un objet de session avec l'utilisation de session_register("a"), vous devez pensez à inclure le fichier classa.inc dans toutes vos pages, et pas seulement page1.php et page2.php.
Les fonctions magiques __sleep et __wakeup
serialize() s'assure que votre classe a une méthode avec le nom magique __sleep. Si c'est le cas, cette fonction est appelée avant toute linéarisation. Elle peut alors nettoyer l'objet et on s'attend à ce qu'elle retourne un tableau avec la liste des noms de variables qui doivent être sauvées.
Le but de cette fonction __sleep est de fermer proprement toute connexion à une base de données, de valider les requêtes, de finaliser toutes les actions commencées. Cette fonction est aussi pratique si vous ave de très grands objets qui n'ont pas besoin d'être sauvé entièrement.
A l'inverse, unserialize() s'assure de la présence de la fonction magique __wakeup. Si elle existe, cette fonction reconstruit toutes les ressources d'un objet.
Le but de cette fonction __wakeup est de rétablit toutes les connexions aux bases de données, et de recréer les variables qui n'ont pas été sauvées.
Références dans un constructeur
Créer des références dans un constructeur peut conduire à des résultats étranges. Ce tutorial vous guide pour éviter ces problèmes.
<?php
class foo {
function foo($name) {
// crée une référence dans le tableau global $globalref
global $globalref;
$globalref[] = &$this;
// donne le nom de la variable
$this->setName($name);
// et l'affiche
$this->echoName();
}
function echoName() {
echo "<br>",$this->Name;
}
function setName($name) {
$this->Name = $name;
}
}
?> |
Vérifions maintenant qu'il y a une différence entre $bar1 qui a été créé avec = et $bar2 qui a été créé avec l'opérateur de référence =& :
<?php
$bar1 = new foo('crée dans le constructeur');
$bar1->echoName();
$globalref[0]->echoName();
/* affiche :
crée dans le constructeur
crée dans le constructeur
crée dans le constructeur */
$bar2 =&new foo('crée dans le constructeur');
$bar2->echoName();
$globalref[1]->echoName();
/* affiche :
crée dans le constructeur
crée dans le constructeur
crée dans le constructeur */
?> |
Apparament, il n'y a pas de différence, mais en fait, il y en a une significative : $bar1 et $globalref[0] ne sont pas référencées, ces deux variables sont différentes. Cela est du au fait que l'opérateur "new"ne retourne par de référence, mais retourne une copie.
Note : Il n'y a aucune perte de performance (puisque PHP 4 utilise un compteur de référence) à retourner des copies au lieu de références. Au contraire, il est souvent mieux de travailler sur les copies plutôt que sur les références, car créer une référence prend un peu plus de temps que de créer une copie qui ne prend virtuellement pas de temps (à moins de créer un tableau géant ou un objet monstreux, auquel cas il est préférable de passer par des références).
<?php
// maintenant, nous allons changer de nom. Qu'attendez-vous?
// Vous pouvez vous attendre à ce que les deux variables $bar
// et $globalref[0] changent de nom...
$bar1->setName('modifié');
// comme prédit, ce n'est pas le cas
$bar1->echoName();
$globalref[0]->echoName();
/* affiche :
crée dans le constructeur
modifié */
// quelle est la différence entre $bar2 et $globalref[1]
$bar2->setName('modifié');
// Heureusement, elles sont non seulement égales, mais
// elles représentent la même variable.
// donc $bar2->Name et $globalref[1]->Name sont les mêmes
$bar2->echoName();
$globalref[1]->echoName();
/* affiche :
modifié
modifié */
?> |
Un dernier exemple pour bien comprendre.
<?php
class a {
function a($i) {
$this->value = $i;
// Essayez de comprendre on n'a pas besoin de
// référence ici
$this->b = new b($this);
}
function createRef() {
$this->c = new b($this);
}
function echoValue() {
echo "<br>","class ",get_class($this),': ',$this->value;
}
}
class b {
function b(&$a) {
$this->a = &$a;
}
function echoValue() {
echo "<br>","class ",get_class($this),': ',$this->a->value;
}
}
// Essayez de comprendre pourquoi une copie simple va
// conduire à un résultat indésirable à
// la ligne marquée d'une étoile
$a =&new a(10);
$a->createRef();
$a->echoValue();
$a->b->echoValue();
$a->c->echoValue();
$a->value = 11;
$a->echoValue();
$a->b->echoValue(); // *
$a->c->echoValue();
/*
output:
class a: 10
class b: 10
class b: 10
class a: 11
class b: 11
class b: 11
*/
?> |
Chapitre 14. Les références
Qu'est ce qu'une référence?
En PHP, les références sont destinées à appeler le contenu d'une variable avec un autre nom. Ce n'est pas comme en C : ici, les références sont des alias dans la table des symboles. Le nom de la variable et son contenu ont des noms différents, 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 leur nom de fichier : les noms des variables sont les entrées dans un repertoire, tandis que le contenu de la variable est le contenu même du fichier. Faire des références en PHP revient alors à faire des liens sous Unix.
Que font les références ?
Les références vous permettent de faire pointer deux variables sur le même contenu. Par exemple, lorsque vous faites :
cela signifie que $a et $b pointent sur la même variable.Note : $a et $b sont complètement égales ici : ce n'est pas $a qui pointe sur $b, ou vice versa. C'est bien $a et $b qui pointent sur le même contenu.
Note : A moins d'utiliser la syntaxe ci-dessus, le résultat de $bar = new fooclass() ne sera pas la même variable que $this dans le constructeur, ce qui signifie que si vous avez utilisé la référence $this dans le constructeur, vous devez assigner la référence, ou bien obtenir deux objets différents.
Le deuxième intérêt des références est de pouvoir passer des variables par référence. On réalise ceci en faisant pointer des variables locales vers le contenu des variables de fonction. Exemple :
$a vaut 6. Cela provient du fait que dans la fonction foo, la variable $var pointe sur le même contenu que $a. Voir aussi les explications détaillées dans passage par référence.Le troisième intérêt des références est de retourner des valeurs par référence.
Ce que les références ne sont pas
Comme précisé ci-dessus, les références ne sont pas des pointeurs. Cela signifie que le script suivant ne fera pas ce à quoi on peut s'attendre :
Il va se passer que $var dans foo() sera lié à $bar, mais il sera aussi relié à $GLOBALS["baz"]. Il n'y a pas moyen de lier $bar à quelque chose d'autre en utilisant le mécanisme de référence, car $bar n'est pas accessible dans la fonction foo() (certes, il est représenté par $var et $var possède la même valeur, mais n'est pas relié par la table des symboles).
Passage par référence
Vous pouvez passer des variables par référence, de manière à ce que la fonction modifie ses arguments. La syntaxe est la suivante :
Notez qu'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 est suffisante pour passer correctement des arguments par référence.Les objets suivants peuvent être passés par référence :
Une variable, i.e. foo($a)
Un nouvel objet, i.e. foo(new foobar())
Une référence, retournée par une fonction :
Voir aussi des détails dans retourner des références.
Toutes les autres expressions ne doivent 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 :
Ces fonctionnalités sont valables à partir de PHP 4.0.4.Retourner des références
Retourner des références est toujours utile lorsque vous voulez utiliser une fonction pour savoir à quoi est liée une variable. Lorsque vous retournez une variable par paramètre, utilisez le code suivant
<?php
function &find_var($param) {
// ...code...
return $found_var;
}
$foo =& find_var ($bar);
$foo->x = 2;
?> |
Note : Contrairement au passage de paramètre, vous devez utiliser & aux deux endroits, à la fois pour indiquer que vous retournez par référence (pas une copie habituelle), et pour indiquer que vous assignez aussi par référence (pas la copie habituelle).
Détruire une référence
Lorsque vous détruisez une référence, vous ne faites que casser le lien entre le nom de la variable et son contenu. Cela ne signifie pas que le contenu est détruit. Par exemple,
Cet exemple ne détruira pas $b, mais juste $a.Encore une fois, on peut comparer cette action avec la fonction 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. Par exemple, le passage et le retour d'arguments par référence. Quelques autres exemples de syntaxes :
Références globales
Lorsque vous déclarez une variable global $var, vous créez en fait une référence sur une variable globale. Ce qui signifie que
Et que, si vous détruisez la variable $var, la variable globale ne sera pas détruite.
III. Caractéristiques
- Table des matières
- 15. Gestion des erreurs
- 16. Création d'images
- 17. Authentification HTTP avec PHP
- 18. Cookies
- 19. Gestion des chargements de fichier
- 20. Utilisation des fichiers à distance
- 21. Gestion des connexions
- 22. Connexions persistantes aux bases de données
- 23. Safe mode
- 24. Using PHP from the command line
Chapitre 15. Gestion des erreurs
Il y a plusieurs types d'erreur et d'alerte.
Tableau 15-1. Types d'erreur PHP
| Valeur | Constante | Description | Note |
|---|---|---|---|
| 1 | E_ERROR | Erreur fatale d'exécution | |
| 2 | E_WARNING | Alerte d'exécution ( erreur non-fatale ) | |
| 4 | E_PARSE | Erreur de compilation | |
| 8 | E_NOTICE | Notes d'exécution (moins critique que les alertes) | |
| 16 | E_CORE_ERROR | Erreurs qui surviennent lors de l'initialisation de PHP | PHP 4 seulement |
| 32 | E_CORE_WARNING | Alertes qui surviennent lors de l'initialisation de PHP | PHP 4 seulement |
| 64 | E_COMPILE_ERROR | Erreur fatale de compilation | PHP 4 seulement |
| 128 | E_COMPILE_WARNING | Alerte de compilation (erreur non fatale) | PHP 4 seulement |
| 256 | E_USER_ERROR | Erreur générée par l'utilisateur | PHP 4 seulement |
| 512 | E_USER_WARNING | Alerte générée par l'utilisateur | PHP 4 seulement |
| 1024 | E_USER_NOTICE | Note générée par l'utilisateur | PHP 4 seulement |
| E_ALL | Toutes les erreurs ci-dessus |
Les valeurs ci-dessus (numériques ou symboliques) sont utilisées pour construire un champs de bit, qui spécifie quelles erreurs rapporter. Vous pouvez utiliser les opérateurs de bits pour combiner ces valeurs et conserver uniquement celle qui vous intéresse. Notez que seuls, '|', '~', '!', et '&' seront utilisables dans php.ini, et qu'aucun opérateur ne sera utilisable dans php3.ini.
En PHP 4, la valeur par défaut de error_reporting est à E_ALL & ~E_NOTICE, ce qui signifie que toutes les erreurs et alertes seront affichées, mais pas les notes. En PHP 3, la valeur par défaut est (E_ERROR | E_WARNING | E_PARSE), c'est-à-dire la même chose. Notez bien que ces constantes ne sont pas supportées dans le fichier php3.ini de PHP 3, la valeur de error_reporting doit être numérique, c'est-à-dire 7.
La valeur initiale peut être modifiée dans le fichier php.ini, avec la directive error_reporting, dans le fichier de configuration d'Apache httpd.conf, avec la directive php_error_reporting (php3_error_reporting pour PHP 3), et enfin, dans le script même, en utilisant la fonction error_reporting().
| Avertissement |
Lorsque vous portez votre code ou vos serveurs de PHP 3 en PHP 4 vous devez vérifier les options et les appels à error_reporting(). Sinon, vous courrez le risque d'inactiver certains types d'erreurs et notamment E_COMPILE_ERROR. Cela peut conduire à des documents vides, sans aucun retour d'erreur. |
Toutes les expressions PHP peuvent être appelées avec le préfixe "@", qui annule le rapport d'erreur pour cette expression en particulier. Si une erreur survient durant une telle expression, et que l'option de suivi des erreurs est activée, vous pourrez trouver le message d'erreur dans la variable globale, $php_errormsg.
Note : Le préfixe opérateur @ ne supprimera pas les messages liés aux erreurs d'analyse.
| Avertissement |
Actuellement, le préfixe @, opérateur de rapport d'erreur désactive tous les rapports, y compris les erreurs critiques qui interrompent le script. Entre autre, cela signifique que si vous utilisez @ pour supprimer des erreurs dans une fonction qui n'existe pas, ou qui a été mal orthographiée, le script sera terminé sans aucune indication. |
Ci-dessous, voici un exemple de gestion des erreurs avec PHP. On définit une fonction de gestion des erreurs qui enregistre les informations dans un fichier (au format XML), et envoie un email au développeur en cas d'erreur critique.
Exemple 15-1. Utiliser le contrôle d'erreur dans un script
|
Voir aussi error_reporting(), error_log(), set_error_handler(), restore_error_handler(), trigger_error(), user_error()
Chapitre 16. Création d'images
PHP n'est pas limité à la création de fichier HTML. Il peut aussi servir à créer des images GIF, PNG, JPG, wbmp et xpm, à la volée, aussi bien pour les émettre que pour les sauver. Il faut alors compiler PHP avec la librairie GD. GD et PHP requièrent aussi d'autres librairies, suivant le format d'images que vous voulez supporter. GD a cessé de supporter le format GIF depuis la version 1.6.
Exemple 16-1. Création d'images GIF avec PHP
|
Chapitre 17. Authentification HTTP avec PHP
Les fonctions d'authentification HTTP de PHP ne sont disponibles que si PHP est exécuté comme module Apache, et non pas sous la forme d'un CGI. Sous cette forme, il est possible d'utiliser la fonction header() pour demander une authentification ("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 $PHP_AUTH_USER, $PHP_AUTH_PW et $PHP_AUTH_TYPE contenant respectivement le nom d'utilisateur, le mot de passe et le type d'authentification. Actuellement, seule l'authentification simple ("Basic") est supportée. Reportez-vous à la fonction header() pour plus d'informations.
Voici un exemple de script qui force l'authentification du client pour accéder à une page :
Exemple 17-1. Exemple d'authentification HTTP
|
Au lieu d'afficher simplement les variables globales $PHP_AUTH_USER et $PHP_AUTH_PW, vous préférerez sÛrement 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.
Méfiez-vous des navigateurs buggés, tels que Internet Explorer. Ils semblent très susceptibles concernant l'ordre des en-têtes. Envoyer l'en-tête d'authentification (WWW-Authenticate) avant le code de HTTP/1.0 401 semble lui convenir jusqu'à présent.
Pour éviter que quelqu'un écrive un script qui révèle les mots de passe d'une page, à la quelle on a accédé par une authentification traditionnelle, les variables globales PHP_AUTH ne seront pas assignées si l'authentification externe a été activée pour cette page. Dans ce cas, la variable $REMOTE_USER peut être utilisée pour identifier l'utilisateur à l'extérieur.
Notez cependant que les manipulations ci-dessus n'empêchent pas quiconque possède une page non authentifiée de voler les mots de passe des pages protégées, sur le même serveur.
Netscape et Internet Explorer effaceront le cache d'authentification client s'ils recoivent une réponse 401. Cela permet de déconnecter un utilisateur, pour le forcer à ré-entrer son nom de compte et son mot de passe. Certains programmeurs l'utilisent pour donner un délai d'expiration, ou alors, fournissent un bouton de déconnexion.
Exemple 17-2. Authentification HTTP avec nom d'utilisateur/mot de passe forcé
|
Ce comportement n'est pas nécessaire par le standard d'authentification HTTP Basic. Les tests avec Lynx ont montré qu'il n'affectait pas les informations de session lors de la réception d'un message de type 401. Ce qui fait que presser la touche "retour" (back) à un client lynx précédemment authentifié donnera l'accès direct à la ressource. Cependant, l'utilisateur peut utiliser la touche '_' pour détruire les anciennes authentifications.
Notez aussi que tout ceci ne fonctionne pas sous Microsoft IIS et que les limitations de PHP en version CGI sont dues aux limitations de IIS.
Chapitre 18. Cookies
PHP supporte les cookies 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'authentifier et de suivre les visiteurs. Vous pouvez envoyer un cookie avec la commande setcookie(). 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().
Tous les cookies qui sont envoyés au client seront automatiquement retournés au script PHP, et transformés en variable, exactement comme pour GET et POST. Si vous souhaitez affecter plusieurs valeurs à un seul cookie, ajoutez [] au nom du cookie. Pour plus détails, reportez-vous à la fonction setcookie().
Chapitre 19. Gestion des chargements de fichier
Chargements de fichiers par méthode POST
PHP est capable de recevoir des fichiers émis par un navigateur conforme à la norme RFC-1867 (c'est-à-dire Netscape Navigator 3 ou supérieur, Microsoft Internet Explorer 3 avec un patch de Microsoft, ou supérieur sans le patch). Cette fonctionnalité permet de charger des fichiers textes ou binaires. Avec l'authentification et les fonctions de manipulation des fichiers, vous avez un contrôle total sur le chargement et la gestion des fichiers chargés.
Notez bien que PHP supporte aussi le chargement par la méthode PUT comme dans le navigateur Netscape Composer et les clients Amaya du W3C. Reportez-vous au chapitre sur le support de la méthode PUT.
Un écran de chargement de fichiers peut être constitué en créant un formulaire de la manière suivante :
En PHP 3, les variables suivantes seront définies dans le script de destination, en cas de téléchargement réussi, et en supposant que register_globals est activé dans le fichier php.ini. Si track_vars est activé, elles seront aussi disponibles dans le dossier $HTTP_POST_VARS. Notez que les noms des variables suivantes supposent que nom du fichier téléchargé est 'userfile', comme présenté dans l'exemple ci-dessus.
$userfile - Le nom temporaire du fichier qui sera chargé sur la machine serveur.
$userfile_name - Le nom du fichier original sur le système de l'envoyeur.
$userfile_size - La taille du fichier envoyé en octets.
$userfile_type - Le type MIME du fichier, si le navigateur a fourni cette information. Par exemple, "image/gif".
En PHP 4, le comportement est légèrement différent, car c'est la variable d'environnement $HTTP_POST_FILES, qui contiendra les informations sur les fichiers téléchargés. Ces informations sont disponibles dans si l'option track_vars est activée, mais track_vars est toujours activée dans les versions de PHP supérieures à la version 4.0.2.
Le contenu du tableau $HTTP_POST_FILES décrit ci-dessous. Notez que l'on suppose ici que le nom du fichier téléchargé est 'userfile', comme présenté dans l'exemple ci-dessus :
- $HTTP_POST_FILES['userfile']['name']
Le nom du fichier original sur la machine source.
- $HTTP_POST_FILES['userfile']['type']
Le type MIME du fichier, si le navigateur a fourni cette information. Par exemple, "image/gif".
- $HTTP_POST_FILES['userfile']['size']
La taille du fichier envoyé, en octets.
- $HTTP_POST_FILES['userfile']['tmp_name']
Le nom temporaire du fichier qui sera chargé sur la machine serveur.
Les fichiers seront enregistrés par défaut dans le dossier des fichiers temporaires, à moins qu'un autre dossier n'ait été fourni avec la directive de configuration upload_tmp_dir du fichier php.ini. Le dossier par défaut du serveur peut être modifié grâce à la variable d'environnement TMPDIR, de l'utilisateur qui exécute PHP. Sa modification avec putenv() depuis un script PHP ne fonctionnera pas. Cette variable d'environnement peut aussi être utilisée pour s'assurer que d'autres opérations fonctionnent avec les fichiers téléchargés.
Exemple 19-2. Validation de fichiers téléchargés Les exemples suivants fonctionnent sur les versions de PHP 3 supérieures à la version 3.0.16, et supérieures à la version 4.0.2 pour PHP 4. Reportez-vous à la section des fonctions pour étudier is_uploaded_file() et move_uploaded_file().
Pour les versions plus anciennes de PHP, vous devrez faire quelque chose comme ceci :
|
Note : Cela ne fonctionnera PAS avec les versions de PHP 4 supérieure à 4.0.2. Cela repose sur des fonctionnalités internes à PHP qui ont évolué après cette version.
Le script PHP qui reçoit le fichier chargé doit pouvoir gérer le fichier de manière appropriée. Vous pouvez utiliser la variable $file_size pour recaler tous les fichiers qui sont trop gros ou trop petits. Vous pouvez utiliser la variable $file_type pour recaler les fichiers qui n'ont pas le bon type. Quelques soient les actions, ce script doit pouvoir supprimer le fichier du dossier temporaire, ou le déplacer ailleurs.
Le fichier sera automatiquement effacé du fichier temporaire à la fin du script, s'il n'a pas été déplacé ou renommé.
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 fichier php3.ini, ou par php3_upload_max_filesize dans les directives Apache. La valeur par défaut est 2 mégaoctets.
Ne pas valider les fichiers que vous manipulez peut donner l'accès aux utilisateurs à des fichiers sensibles dans d'autres dossiers!
Attention : il semble que CERN httpd supprime tout ce qui est après le premier caractère dans l'en-tête MIME. Tant que c'est le cas, CERN httpd ne pourra pas effectuer de chargement.
Chargement multiples de fichiers
Il est possible de charger plusieurs fichiers en même temps, et de recevoir les informations adéquates organisées sous forme de tableau. Pour ce faire, il faut utiliser la même syntaxe d'envoi dans le code HTML que pour les sélections ou boîtes à cocher multiples.
Note : Le support du chargement multiple de fichier a été ajouté dans la version 3.0.10.
Lorsque le formulaire ci-dessus a étéF envoyé, les tableaux $userfile, $userfile_name, et $userfile_size seront initialisés (ainsi que $HTTP_POST_VARS). Chaque tableau sera de type numérique, et contiendra les valeurs appropriées pour le chargement des fichiers.
Par exemple, supposons que les noms de fichier /home/test/review.html et /home/test/xwp.out soient envoyés. Dans ce cas, $userfile_name[0] va contenir review.html, et $userfile_name[1] contiendra xwp.out. Similairement, $userfile_size[0] contiendra la taille de review.html, etc...
$userfile['name'][0], $userfile['tmp_name'][0], $userfile['size'][0], et $userfile['type'][0] sont aussi affectés.
Chargement par méthode PUT
PHP supporte la méthode HTTP PUT utilisée par les navigateurs tels que Netscape Composer et W3C Amaya. Les requêtes de type PUT sont beaucoup plus simples que les chargements de fichiers, et elles ressemblent à :
Normalement, cela signifie que le client distant va sauver les données qui suivent dans le fichier: /path/filename.html de votre disque. 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 que vous voulez qu'un script PHP donné gère 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 place dans le bloc <Directory>, ou peut être dans le bloc <Virtualhost>. La ligne suivante fera très bien l'affaire :
Elle indique à Apache qu'il doit envoyer les requêtes de chargement par méthode PUT au script put.php3. Bien entendu, cela présuppose que vous avez activé PHP pour qu'il prenne en charge les fichiers de type .php3, et que PHP est actif.
Dans le fichier put.php3 file vous pouvez mettre ceci :
Ce script va copier le fichier chargé par le client distant à l'endroit désiré. Vous aurez probablement à effectuer quelques tests et des authentifications d'utilisateur, avant d'effectuer cette copie. Le seul piège est que lorsque PHP reçoit un chargement par méthode PUT, il va enregistrer le fichier dans le dossier temporaire, tout comme avec la méthode POST-method. A la fin de la requête, le fichier sera effacé. Ce qui fait que ce script doit placer le fichier chargé quelque part. Le nom du fichier temporaire est placé dans la variable globale $PHP_PUT_FILENAME, et la destination prévue est placée dans $REQUEST_URI (ces noms peuvent changer d'une configuration d'Apache à l'autre). Cette destination est celle qui est demandée par le client, et vous n'avez pas à obéir aveuglément au client. Vous pourriez par exemple, déplacer le fichier dans un dossier de chargement.
Chapitre 20. Utilisation des fichiers à distance
Aussi longtemps que le support de la fonction d'ouverture générique de fichiers ("URL fopen wrapper") est actif lorsque vous configurez PHP (il est inutile de passer explicitement l'option --disable-url-fopen-wrapper pour faire la configuration), vous pouvez utiliser des URLs (HTTP et FTP) avec la majorité des fonctions qui utilisent un nom de fichier comme paramètre, ceci incluant les expressions require() et include().
Note : Vous ne pouvez pas utiliser les fichiers distants dans les expressions include() et require() sous Windows.
Par exemple, vous pouvez suivre l'exemple suivant pour ouvrir un fichier sur un serveur web distant, analyser les résultats pour extraire les informations dont vous avez besoin, et ensuite l'utiliser dans une requête de base de données, ou simplement éditer les informations dans le style de votre site.
Exemple 20-1. Connaître le titre d'une page distante
|
Vous pouvez aussi écrire des fichiers sur un serveur FTP aussi longtemps que vous êtes connecté avec un utilisateur ayant les bons droits d'accès, alors que le fichier n'existait pas encore. Pour vous connecter avec un utilisateur autre qu'anonyme, vous devez spécifier un nom d'utilisateur (et certainement le mot de passe) dans l'URL, comme par exemple 'ftp://user:password@ftp.example.com/path/to/file'. (Vous pouvez utiliser le même type de syntaxe pour accéder aux fichiers via HTTP lorsqu'ils nécessitent une authentification basique).
Note : Remarque: Vous pouvez avoir l'idée,à partir de l'exemple ci-dessus, d'utiliser la même technique pour écrire sur un log distant, mais comme mentionné ci-dessus vous ne pouvez qu'écrire sur un nouveau fichier en utilisant les fonctions fopen() avec une URL. Pour faire des log distribués, nous vous conseillons de regarder la partie syslog().
Chapitre 21. Gestion des connexions
Note : Les informations suivantes ne sont valables qu'à partir de la version 3.0.7.
Le statut des connexions est conservé en interne par PHP. Il y a trois états possibles :
0 - NORMAL (normal)
1 - ABORTED (annulé)
2 - TIMEOUT (périmé)
Lorsqu'un script PHP est en cours d'exécution, son état est NORMAL. Si le client distant se déconnecte, le statut devient ABORTED. En général, une telle déconnexion provient d'un arrêt temporaire. Si la durée maximale d'exécution de PHP est dépassée, (voir set_time_limit()), le script prend le statut TIMEOUT.
Vous pouvez en outre décider si vous voulez que la déconnexion d'un client provoque l'arrêt de votre script. Il est parfois pratique de terminer le script, même si le client n'est plus là pour recevoir les informations. Cependant, par défaut, le script sera interrompu, et terminé 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 ignore_user_abort du fichier Apache httpd.conf ou avec la fonction ignore_user_abort(). Si vous ne demandez pas à PHP d'ignorer la déconnexion, et que l'utilisateur se déconnecte, le script sera terminé. La seule exception est si vous avez enregistré une fonction de fermeture, 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, vous pouvez exécutez des commandes spécifiques à la déconnexion grâce à la commande connection_aborted(). Cette fonction retournera TRUE si la connexion a été annulée.
Votre script peut aussi expirer après un laps de temps. 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 php3_max_execution_time, dans le fichier Apache .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 finalisation sera appelée. Dans cette fonction, vous pouvez savoir si c'est le délai d'expiration qui a causé la fin du script, en appelant la fonction connection_timeout(). Cette fonction retournera vrai si le délai d'expiration a été dépassé.
Une chose à noter est que les deux cas ABORTED et TIMEOUT peuvent être appelés en même temps. Ceci est possible si vous demandez à 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. A ce moment-là, les deux fonctions connection_timeout() et connection_aborted() vont retourner TRUE. Vous pouvez aussi vérifier les deux états en un seul appel avec la fonction connection_status(). Cette fonction va retourner un champs de bits, avec les états. Si les deux états sont actifs, l'état retourné prendra la valeur 3.
Chapitre 22. Connexions persistantes aux bases de données
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 s'assure qu'il n'y a pas une autre connexion identique (qui serait ouverte précédemment, avec le même nom d'hôte, d'utilisateur et le même mot de passe), et si une telle connexion existe, elle est utilisée. Sinon, elle est créée. Une connexion identique est une connexion qui a ouvert le même hôte, avec le même nom et le même mot de passe (s'ils sont nécessaires).
Ceux qui ne sont pas rompus aux techniques des serveurs web et leur distribution de la charge de travail, se font parfois une fausse idée de ces connexions persistantes. En particulier, les connexions persistantes ne permettent pas l'ouverture de plusieurs sessions avec le même lien, ne permettent pas la réalisation de transactions efficaces et ne font pas le café. En fait, pour être extrêmement clair sur le sujet, les connexions persistantes ne vous donnent aucune fonctionnalité de plus que les connexions non persistantes.
Alors pourquoi les connexions persistantes?
Cela s'explique par la manière avec laquelle les serveurs web fonctionnent. Il y a trois manières d'utiliser PHP pour générer des pages.
La première est d'utiliser PHP comme un CGI (Common Interface Gateway). 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. Etant donné que cet interpreteur est détruit après chaque requête, toutes les ressources acquises (comme une connexion à une base SQL), sont purement et simplement détruites.
La deuxième méthode, et de loin, la plus prisée, est d'exécuter PHP sous la forme d'un module sur un serveur multi-processus, ce qui revient à dire : Apache. Un tel serveur a typiquement un processus 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 client différent du premier. Les connexions persistantes vous permettent alors de ne vous connecter à une base SQL que la première fois. Lors des connexions ultérieures, les processus fils pourront réutiliser la connexion ouverte précédemment.
La dernière méthode est d'utiliser PHP sous la forme d'un module de serveur multi-threads. Actuellement, PHP 4 supporte ISAPI, WSAPI, et NSAPI (sous Windows), qui permettent tous d'utiliser PHP comme un module sur un serveur multi-threads tel que Netscape FastTrack (iPlanet), Microsoft's Internet Information Server (IIS), et O'Reilly's WebSite Pro. Le comportement est essentiellement le même que pour les serveurs multi-processus décrits précédemment. Notez que SAPI n'est pas disponible avec PHP 3.
Si les connexions persistantes n'ont aucune fonctionnalité de plus, à quoi servent-elles?
La réponse est extrêmement simple : efficacité. Les connexions persistantes sont un bon moyen d'accélérer les accès à une base SQL si le traitement de connexion à la base est long. Ce temps 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. Si vous avez 20 processus fils, il suffit d'avoir 20 connexions persistantes ouvertes, une par fils.
Notez que les connexions persistantes ont quelques inconvénients si vous hébergez une base de données, dont le nombre maximal de connexion risque d'être atteint par les connexions persistantes. Si votre base de données accepte jusqu'à 16 connexions simultanées et que, 17 processus essaient de se connecter, le dernier restera sur la touche. S'il y a des erreurs dans les scripts qui ne permettent pas de fermer la connexion (par exemple, une boucle infinie), votre serveur sera rapidement engorgé. Vérifiez la documentation de votre base de données pour savoir comment elle traite les connexions inactives ou abandonnées.
Résumons-nous : les connexions persistantes ont été définies pour avoir les mêmes fonctionnalités que les connexions non persistantes. Les deux types de connexions sont parfaitement interchangeables, et n'affecteront pas le comportement de votre script : uniquement son efficacité.
Chapitre 23. Safe mode
Le "Safe Mode" est le mode de sécurité de PHP : une solution au problème de partage de PHP sur un serveur. Ce système pêche au niveau de l'architecture car il n'est pas correct de tenter de résoudre ce problème au niveau de PHP, mais les solutions alternatives basées sur le serveur web et l'OS ne sont pas réalistes. De nombreux acteurs, notamment les fournisseurs d'hébergement, utilise le "Safe Mode".
Les directives de configuration qui contrôlent le safe mode sont :
safe_mode = Off open_basedir = safe_mode_exec_dir = safe_mode_allowed_env_vars = PHP_ safe_mode_protected_env_vars = LD_LIBRARY_PATH disable_functions = |
Lorsque safe_mode est actif, PHP vérifie que le propriétaire du script courant est le même que le propriétaire des fichiers qui seront manipulés par ce script. Par exemple, dans a la situation suivante :
-rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd |
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2 |
Si vou utilisez la directive open_basedir au lieu du safe_mode, alors les manipulations seront limitées aux fichiers situés dans les dossiers spécifiés. Par exemple :
Si vous exécutez le script script.php ci-dessus avec la configuration d'open_basedir le résultat sera l'affichage suivant :Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2 |
Vous pouvez aussi désactiver individuellement les fonctions. Par exemple, en ajoutant cette ligne dans le fichier php.ini :
toute utilisation des fonctions readfile() et system() générera l'affichage suivant :Functions désactivées par le Safe Mode
Voici une liste non-exhaustive des fonctions désactivées par le Safe Mode.
Tableau 23-1. Fonctions désactivées par le Safe Mode
| Fonction | Limitations |
|---|---|
| dbmopen() |
|
| dbase_open() |
|
| filepro() |
|
| filepro_rowcount() |
|
| filepro_retrieve() |
|
| Fonctions ifx_ | restrictions sql_safe_mode, (!= Safe Mode) |
| Fonctions ingres_ | restrictions sql_safe_mode, (!= Safe Mode) |
| Fonctions mysql_ | restrictions sql_safe_mode, (!= Safe Mode) |
| pg_loimport() |
|
| posix_mkfifo() |
|
| putenv() | Obéis aux directives safe_mode_protected_env_vars et safe_mode_allowed_env_vars. Voir aussi la documentation de putenv() |
| move_uploaded_file() |
|
| chdir() |
|
| dl() | Cette fonction est désactivée par le safe-mode |
| backtick operator | Cette fonction est désactivée par le safe-mode |
| shell_exec() (équivalent fonctionnels des guillemets oblique) | Cette fonction est désactivée par le safe-mode |
| exec() | Vous ne pouvez éxécuter que les programmes qui sont dans le dossier safe_mode_exec_dir. Pour des raisons pratiques, il n'est pas possible d'utiliser des jokers comme .. dans le chemin de ce dossier. |
| system() | Vous ne pouvez éxécuter que les programmes qui sont dans le dossier safe_mode_exec_dir. Pour des raisons pratiques, il n'est pas possible d'utiliser des jokers comme .. dans le chemin de ce dossier. |
| passthru() | Vous ne pouvez éxécuter que les programmes qui sont dans le dossier safe_mode_exec_dir. Pour des raisons pratiques, il n'est pas possible d'utiliser des jokers comme .. dans le chemin de ce dossier. |
| popen() | Vous ne pouvez éxécuter que les programmes qui sont dans le dossier safe_mode_exec_dir. Pour des raisons pratiques, il n'est pas possible d'utiliser des jokers comme .. dans le chemin de ce dossier. |
| mkdir() |
|
| rmdir() |
|
| rename() |
|
| unlink() |
|
| copy() |
|
| chgrp() |
|
| chown() |
|
| chmod() |
|
| touch() |
|
| symlink() |
|
| link() |
|
| getallheaders() | En Safe Mode, les entêtes commencants par 'authorization' (sensible à la casse) ne seront pas retournés. Attention : cette protection est mise en défaut par la fonction getallheaders() sur les serveurs AOL! |
| Toutes les fonctions qui utilisent les wrappers de fichiers. | ?? |
Chapitre 24. Using PHP from the command line
Since version 4.3, PHP supports a new SAPI type (Server Application Programming Interface) named CLI which means Command Line Interface. As the name implies, this SAPI type main focus is on developing shell (or desktop as well) applications with PHP. There are quite some differences between the CLI SAPI and other SAPIs which are further explained throughout this chapter.
The CLI SAPI was released for the first time with PHP 4.2.0, but was still experimental back then and had to be explicitely enabled with --enable-cli when running ./configure. Since PHP 4.3.0 the CLI SAPI is no longer experimental and is therefore always built and installed as the php (called php.exe on Windows) binary.
Remarkable differences of the CLI SAPI compared to other SAPIs:
Unlikely the CGI SAPI, no headers are written to the output.
Though the CGI SAPI provies a way to suppress HTTP headers, there's not equivalent switch to enable them in the CLI SAPI.
The are certain php.ini directives which are overriden by the CLI SAPI because the do not make sense in shell environments:
Tableau 24-1. Overriden php.ini directives
Directive CLI SAPI default value Comment html_errors FALSE It can be quite hard to read the error message in your shell when it's cluttered with all those meaningless HTML tags, therefore this directive defaults to FALSE. implicit_flush TRUE It is desired that any output coming from print(), echo() and friends is immidiately written to the output and not cached in any buffer. You still can use output buffering if you want to defer or manipulate standard output. max_execution_time 0 (unlimited) Due to endless possibilities of using PHP in shell environments, the maximum execution time has been set to unlimited. Whereas applications written for the web are executed within splits of a seconds, shell application tend to have a much longer execution time. register_argc_argv TRUE The global PHP variables $argc (number of arguments passed to the application) and $argv (array of the actual arguments) are always registered and filled in with the appropriate values when using the CLI SAPI. Note : These directives cannot be initialzied with another value from the configuration file php.ini or a custom one (if specified). This is a limitation because those default values are applied after all configuration files have been parsed. However, their value can be changed during runtime (which does not make sense for all of those directives, e.g. register_argc_argv).
To ease working in the shell environment, the following constants are defined:
Tableau 24-2. CLI specific Constants
Constant Description STDIN An already opened stream to stdin. This saves opening it with $stdin = fopen('php://stdin', 'r');STDOUT An already opened stream to stdout. This saves opening it with $stdout = fopen('php://stdout', 'w');STDERR An already opened stream to stdout. This saves opening it with $stderr = fopen('php://stderr', 'w');Given the above, you don't need to open e.g. a stream for stderr yourself but simply use the constant instead of the stream resource:
You do not need to explicitly close these streams, this is automatically done by PHP.php -r 'fwrite(STDERR, "stderr\n");'
The CLI SAPI does not change the current directory to the directory of the executed script !
Example showing the difference to the CGI SAPI:
<?php /* Our simple test application */ echo getcwd(), "\n"; ?>When using the CGI version, the output is
This clearly shows that PHP changes its current directory to the one of the executed script.$ pwd /tmp $ php-cgi -f another_directory/test.php /tmp/another_directory
Using the CLI SAPI yields:
This allows greater flexibility when writing shell tools in PHP.$ pwd /tmp $ php -f another_directory/test.php /tmp
Note : The CGI SAPI supports the CLI SAPI behaviour by means of the -C switch when ran from the command line.
The list of command line options provided by the PHP binary can be queried anytime by running PHP with the -h switch:
Usage: php [options] [-f] <file> [args...]
php [options] -r <code> [args...]
php [options] [-- args...]
-s Display colour syntax highlighted source.
-w Display source with stripped comments and whitespace.
-f <file> Parse <file>.
-v Version number
-c <path>|<file> Look for php.ini file in this directory
-a Run interactively
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-z <file> Load Zend extension <file>.
-l Syntax check only (lint)
-m Show compiled in modules
-i PHP information
-r <code> Run PHP <code> without using script tags <?..?>
-h This help
args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin |
The CLI SAPI has three different ways of getting the PHP code you want to execute:
Telling PHP to execute a certain file.
Both ways (using the -f switch or not) execute the given file my_script.php. You can choose any file to execute, your PHP scripts do not have to end with the .php extension but can give them any name or extension you want them to have.php my_script.php php -f my_script.php
Pass the PHP code to execute directly on the command line.
Special care has to be taken in regards of shell variable substitution and quoting usage.php -r 'print_r(get_defined_constants());'
Note : Read the example carefully, thera are no beginning or ending tags! The -r switch simply does not need them. Using them will lead to a parser error.
Provide the PHP code to execute via standard input (stdin).
This gives the powerful ability to dynamically create PHP code and feed it to the binary, as shown in this (fictional) example:
$ some_application | some_filter | php | sort -u >final_output.txt
Like every shell application, the PHP binary accepts a number of arguments but also your PHP script can receive them. The number of arguments which can be passed to your script is not limited by PHP (the shell has a certain size limit in numbers of characters which can be passed; usually you won't hit this limit). The arguments passed to your script are available in the global array $argv. The zero index always contains the script name (which is - in case the PHP code is coming from either standard input or from the command line switch -r). The second registered global variable is $argc which contains the number of elements in the $argv array (not the number of arguments passed to the script).
As long as the arguments you want to pass to your script do not start with the - character, there's nothing special to watch out for. Passing an argument to your script which starts with a - will cause trouble because PHP itself thinks it has to handle it. To prevent this use the argument list separator --. After the argument has been parsed by PHP, every argument following it is passed untoched/unparsed to your script.
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
} |
However, there's another way of using PHP for shell scripting. You can write a script where the first line starts with #!/usr/bin/php and then following the normal PHP code included within the PHP starting and end tags and set the execution attributes of the file appropriately. This way it can be executed like a normal shell or perl script:
#!/usr/bin/php
<?php
var_dump($argv);
?> |
$ chmod 755 test
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./test"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
} |
Tableau 24-3. Command line options
| Option | Description | |||
|---|---|---|---|---|
| -s |
Display colour syntax highlighted source. This option uses the internal mechanism to parse the file and produces a HTML highlighted version of it and writes it to standard output. Note that all it does it to generate a block of <code> [...] </code> HTML tags, no HTML headers.
| |||
| -w |
Display source with stripped comments and whitespace.
| |||
| -f |
Parses and executed the given filename to the -f option. This switch is optional and can be left out. Only providing the filename to execute is sufficient. | |||
| -v |
Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
| |||
| -c |
With this option one can either specify a directory where to look for php.ini or you can specify a custom INI file directly (which does not need to be named php.ini), e.g.:
| |||
| -a |
Runs PHP interactively. | |||
| -d |
This option allows to set a custom value for any of the configuration directives allowed in php.ini. The syntax is:
Examples:
| |||
| -e |
Generate extended information for debugger/profiler. | |||
| -z |
Load Zend extension. If only a filename is given, PHP tries to load this extension from the current default library path on your system (usually specified /etc/ld.so.conf on Linux systems). Passing a filename with an absolute path information will not use the systems library search path. A relative filename with a directory information will tell PHP only to try to load the extension relative to the current directory. | |||
| -l |
This option provides a convenient way to only perform a syntax check on the given PHP code. On succes, the text No syntax errors detected in <filename> is written to standard output and the shell return code is 0. On failure, the text Errors parsing <filename> in addition to the internal parser error message is written to standard output and the shell return code is set to 255. This option won't find fatal errors (like undefined functions). Use -f if you would like to test for fatal errors too.
| |||
| -m |
Using this option, PHP prints out the built in (and loaded) PHP and Zend modules:
| |||
| -i | This command line option calls phpinfo(), and prints out the results. If PHP is not working well, it is advisable to make a php -i and see if any error messages are printed out before or in place of the information tables. Beware that the output is in HTML and therefore quite huge. | |||
| -r |
This option allows execution of PHP right from within the command line. The PHP start and end tags (<?php and ?>) are not needed and will cause a parser errors.
| |||
| -h | With this option, you can get information about the actual list of command line options and some one line descriptions about what they do. |
The PHP executable can be used to run PHP scripts absolutely independent from the web server. If you are on a Unix system, you should add a special first line to your PHP script, and make it executable, so the system will know, what program should run the script. On a Windows platform you can associate php.exe with the double click option of the .php files, or you can make a batch file to run the script through PHP. The first line added to the script to work on Unix won't hurt on Windows, so you can write cross platform programs this way. A simple example of writing a command line PHP program can be found below.
Exemple 24-1. Script intended to be run from command line (script.php)
|
In the script above, we used the special first line to indicate, that this file should be run by PHP. We work with a CLI version here, so there will be no HTTP header printouts. There are two variables you can use while writing command line applications with PHP: $argc and $argv. The first is the number of arguments plus one (the name of the script running). The second is an array containing the arguments, starting with the script name as number zero ($argv[0]).
In the program above we checked if there are less or more than one arguments. Also if the argument was --help, -help, -h or -?, we printed out the help message, printing the script name dynamically. If we received some other argument we echoed that out.
If you would like to run the above script on Unix, you need to make it executable, and simply call it as script.php echothis or script.php -h. On Windows, you can make a batch file for this task:
Assuming, you named the above program as script.php, and you have your php.exe in c:\php\php.exe this batch file will run it for you with your added options: script.bat echothis or script.bat -h.
See also the Readline extension documentation for more functions you can use to enhance your command line applications in PHP.
IV. Index des fonctions
- Table des matières
- I. Apache
- II. Tableaux
- III. Aspell
- IV. Nombres de grande taille
- V. Compression Bzip2
- VI. Calendrier
- VII. Paiement CCVS
- VIII. Support COM pour Windows
- IX. Objets
- X. ClibPDF
- XI. Crack
- XII. CURL
- XIII. Paiement Cybercash
- XIV. CyberMUT : Crédit Mutuel
- XV. Administration Cyrus IMAP
- XVI. Caractères
- XVII. DBA
- XVIII. Dates et heures
- XIX. dBase
- XX. DBM
- XXI. dbx
- XXII. DB++ Functions
- XXIII. Direct IO
- XXIV. Accès aux dossiers
- XXV. DOM XML
- XXVI. .NET
- XXVII. Gestion des erreurs
- XXVIII. FrontBase
- XXIX. FilePro
- XXX. Système de fichiers
- XXXI. Forms Data Format
- XXXII. FriBiDi
- XXXIII. FTP
- XXXIV. Fonctions
- XXXV. Gettext (GNU)
- XXXVI. GMP
- XXXVII. HTTP
- XXXVIII. Hyperwave
- XXXIX. Hyperwave API functions
- XL. ICAP
- XLI. Iconv
- XLII. Images
- XLIII. IMAP
- XLIV. Informix
- XLV. InterBase
- XLVI. Ingres II
- XLVII. IRC
- XLVIII. Java
- XLIX. LDAP
- L. Email
- LI. mailparse functions
- LII. Mathématiques
- LIII. Chaînes de caractères multi-octets
- LIV. MCAL
- LV. Chiffrage mcrypt
- LVI. Hash
- LVII. Mimetype Functions
- LVIII. Microsoft SQL Server
- LIX. Ming pour Flash
- LX. Fonctions diverses
- LXI. mnoGoSearch
- LXII. mSQL
- LXIII. MySQL
- LXIV. Mohawk Software session handler functions
- LXV. Fonctions muscat
- LXVI. Réseau
- LXVII. Ncurses terminal screen control functions
- LXVIII. Lotus Notes functions
- LXIX. ODBC unifié
- LXX. Oracle 8
- LXXI. OpenSSL
- LXXII. Oracle
- LXXIII. Ovrimos SQL
- LXXIV. Entrées/sorties
- LXXV. Overload
- LXXVI. PDF
- LXXVII. Paiement par Verisign
- LXXVIII. Options PHP et informations
- LXXIX. POSIX
- LXXX. PostgreSQL
- LXXXI. Contrôle des processus
- LXXXII. Exécution de programmes externes
- LXXXIII. Printer functions
- LXXXIV. Pspell
- LXXXV. Readline (GNU)
- LXXXVI. Recode (GNU)
- LXXXVII. Expressions régulières compatibles Perl
- LXXXVIII. qtdom
- LXXXIX. Expressions régulières
- XC. Sémaphores et gestion de la mémoire partagée
- XCI. SESAM
- XCII. Sessions
- XCIII. Mémoire partagée
- XCIV. Shockwave Flash
- XCV. SNMP
- XCVI. Sockets
- XCVII. Chaîne de caractères
- XCVIII. Sybase
- XCIX. Tokenizer functions
- C. URL
- CI. Variables
- CII. vpopmail functions
- CIII. API Windows 32 bits
- CIV. WDDX
- CV. Analyseur syntaxique XML
- CVI. XMLRPC
- CVII. XSLT
- CVIII. YAZ
- CIX. NIS
- CX. Zip (décompression)
- CXI. Zlib (Compression)
I. Apache
- Table des matières
- apache_child_terminate -- Terminate apache process after this request
- apache_lookup_uri -- Effectue une requête partielle pour l'URI spécifiée et renvoie toutes les informations.
- apache_note -- Affiche ou affecte le paramètre "apache request notes".
- apache_setenv -- Set an Apache subprocess_env variable
- ascii2ebcdic -- Transforme une chaîne ASCII en EBCDIC
- ebcdic2ascii -- Transforme une chaîne EBCDIC en ASCII
- getallheaders -- Récupère toutes les en-têtes des requêtes HTTP.
- virtual -- Effectue une sous-requête Apache
apache_child_terminate
Description
bool apache_child_terminate ( void)apache_child_terminate() will register the Apache process executing the current PHP request for termination once execution of PHP code it is completed. It may be used to terminate a process after a script with high memory consumption has been run as memory will usually only be freed internally but not given back to the operating system.
Note : The availability of this feature is controlled by the php.ini directive apache.child_terminate, which is set to off by default.
This feature is also not available on multithreaded versions of apache like the win32 version.
See also exit().
apache_lookup_uri
(PHP 3>= 3.0.4, PHP 4 )
apache_lookup_uri -- Effectue une requête partielle pour l'URI spécifiée et renvoie toutes les informations.Description
object apache_lookup_uri ( string filename)apache_lookup_uri() effectue une requête partielle pour l'URI spécifiée. Cette requête permet de récupérer toutes les informations importantes à propos de la ressource concernée. Les propriétés de la classe renvoyée sont les suivantes :
| status |
| the_request |
| status_line |
| method |
| content_type |
| handler |
| uri |
| filename |
| path_info |
| args |
| boundary |
| no_cache |
| no_local_copy |
| allowed |
| send_bodyct |
| bytes_sent |
| byterange |
| clength |
| unparsed_uri |
| mtime |
| request_time |
Note : apache_lookup_uri() ne fonctionne que lorsque le PHP est installé sous la forme d'un module Apache.
apache_note
Description
string apache_note ( string note_name [, string note_value])apache_note() est une fonction spécifique au serveur Apache. Cette fonction affecte ou renvoie la valeur de la variable contenue dans la table notes d'Apache. Si la fonction est appelée avec un argument, elle renvoie la valeur courante de la variable note_name. Si apache_note() est appelée avec deux arguments, apache_note() affecte à la note note_value la valeur note_name et apache_note() retournera la valeur précédente de la variable note_name.
apache_setenv
Description
int apache_setenv ( string variable, string value [, bool walk_to_top])
| Avertissement |
This function is currently not documented, only the argument list is available. |
ascii2ebcdic
Description
int ascii2ebcdic ( string ascii_str)ascii2ebcdic() est une fonction spéficique à Apache, qui n'est disponible que sur les OS qui gèrent le format EBCDIC (OS/390, BS2000). Elle traduit la chaîne ASCII ascii_str en son équivalent EBCDIC (avec protection des données binaires) et retourne le résultat.
Voir aussi ebcdic2ascii()
ebcdic2ascii
Description
int ebcdic2ascii ( string ebcdic_str)ebcdic2ascii() est une fonction spéficique à Apache, qui n'est disponible que sur les OS qui gèrent le format EBCDIC (OS/390, BS2000). Elle traduit la chaîne EBCDIC ebcdic_str en son équivalent ASCII (avec protection des données binaires) et retourne le résultat.
Voir aussi ascii2ebcdic()
getallheaders
Description
array getallheaders ( void)getallheaders() renvoie un tableau associatif de toutes les en-têtes HTTP de la requête courante.
Note : Vous pouvez récupérer la valeur d'une variable d'une CGI en la lisant à partir des variables d'environnement, ce qui fonctionne aussi bien dans le cas d'une installation en module ou d'une installation en CGI. Utilisez la fonction phpinfo() pour avoir une liste de toutes les variables d'environnement disponibles.
Note : getallheaders() ne fonctionne que si PHP est installé comme module Apache.
virtual
Description
int virtual ( string filename)virtual() est une fonction spécifique au serveur Apache. Elle est équivalente à la directive "<!--#include virtual...-->" lorsque vous utilisez le module include d'Apache. Cette fonction effectue une sous-requête Apache. C'est très utile lorsque vous utilisez des scripts CGI, des fichiers .shtml ou n'importe quel type de fichier qui doit être analysé par le serveur Apache. Il est à noter que lors de l'utilisation avec des scripts CGI, ces derniers doivent générer une en-tête valide, c'est-à-dire, au minimum une en-tête "Content-Type". Pour les fichiers PHP, il est conseillé d'utiliser les fonctions include() et require(). virtual() ne peut pas être utilisé pour inclure un fichier qui est lui-même un fichier PHP.
II. Tableaux
Ces fonctions vous permettent de manipuler et de traiter les tableaux de nombreuses façons. Les tableaux sont très efficaces dès qu'il s'agit de stocker, gérer et traiter des données en groupe.
Les tableaux simples et multi-dimensionnels sont supportés et peuvent être créés par l'utilisateur, ou par une fonction. Il y a des fonctions spécifiques qui remplissent des tableaux à partir de résultats de requêtes, et de nombreuses fonctions retournent un tableau.
Voir aussi is_array(), explode(), implode(), split() et join().
- Table des matières
- array_change_key_case -- Retourne un tableau dont toutes les clés ont été forcées en majuscules ou minuscules.
- array_chunk -- Sépare un tableau en tableaux de taille inférieure
- array_count_values -- Compte le nombre de valeurs dans un tableau
- array_diff -- Calcule la différence entre deux tableaux
- array_fill -- Remplis un tableau avec une même valeur
- array_filter -- Filtre les éléments d'un tableau
- array_flip -- Remplace les clés par les valeurs, et les valeurs par les clés
- array_intersect -- Calcule l'intersection de tableaux
- array_key_exists -- Checks if the given key or index exists in the array
- array_keys -- Retourne toutes les clés d'un tableau
- array_map -- Applique sur fonction sur des tableaux
- array_merge_recursive -- Combine plusieurs tableaux ensembles, récursivement
- array_merge -- Rassemble plusieurs tableaux
- array_multisort -- Tri multi-dimensionnel
- array_pad -- Complète un tableau jusqu'à la longueur spécifiée, avec une valeur.
- array_pop -- Dépile un élément de la fin d'un tableau
- array_push -- Empile un ou plusieurs éléments à la fin d'un tableau
- array_rand -- Prend une ou plusieurs valeurs, au hasard dans un tableau
- array_reduce -- Réduit itérativement un tableau
- array_reverse -- Renverse l'ordre des éléments d'un tableau
- array_search -- Recherche dans un tableau la clé associée à une valeur
- array_shift -- Dépile un élément au début d'un tableau
- array_slice -- Extrait une portion de tableau
- array_splice -- Efface et remplace une portion de tableau
- array_sum -- Calcule la somme des valeurs du tableau
- array_unique -- Dédoublonne un tableau
- array_unshift -- Empile un ou plusieurs éléments au début d'un tableau
- array_values -- Retourne les valeurs d'un tableau
- array_walk -- Exécute une fonction sur chacun des membres d'un tableau.
- array -- Crée un tableau
- arsort -- Trie un tableau en ordre inverse
- asort -- Trie un tableau en ordre
- compact -- Crée un tableau contenant les variables et leur valeur
- count -- Compte le nombre d'éléments d'un tableau
- current -- Transforme une variable en tableau
- each -- Retourne chaque paire clé/valeur d'un tableau
- end -- Positionne le pointeur de tableau en fin de tableau
- extract -- Importe les variables dans la table des symboles
- in_array -- Indique si une valeur appartient à un tableau
- key -- Retourne une clé d'un tableau associatif
- krsort -- Trie un tableau en sens inverse et suivant les clés
- ksort -- Trie un tableau suivant les clés
- list -- Transforme une liste de variables en tableau
- natcasesort -- Tri d'un tableau avec l'algorithme à "ordre naturel" insensible à la casse
- natsort -- Tri d'un tableau avec l'algorithme à "ordre naturel"
- next -- Avance le pointeur interne d'un tableau
- pos -- Retourne l'élément courant d'un tableau
- prev -- Recule le pointeur courant de tableau
- range -- Crée un tableau contenant un intervalle d'éléments
- reset -- Remet le pointeur interne de tableau au début
- rsort -- Trie en ordre inverse
- shuffle -- Mélange les éléments d'un tableau
- sizeof -- Retourne le nombre d'élément d'un tableau
- sort -- Trie le tableau
- uasort -- Trie d'un tableau en utilisant une fonction de comparaison définie par l'utilisateur.
- uksort -- Trie un tableau par ses clés en utilisant une fonction de comparaison définie par l'utilisateur
- usort -- Trie un tableau en utilisant une fonction de comparaison définie par l'utilisateur
array_change_key_case
(PHP 4 >= 4.2.0)
array_change_key_case -- Retourne un tableau dont toutes les clés ont été forcées en majuscules ou minuscules.Description
array array_change_key_case ( array input [, int case])array_change_key_case() modifie les clés du tableau input, et force leur type. Le paramètre optionnel case permet de forcer les chaînes de caractères en majuscules CASE_UPPER ou minuscules CASE_LOWER. La valeur par défaut est CASE_LOWER. Cette fonction laissera les clés numériques inchangées.
array_chunk
Description
array array_chunk ( array input, int size [, bool preserve_keys])array_chunk() sépare le tableau input en plusieurs tableaux de taille size. Il est aussi possible que le dernier tableau ait moins de valeurs. Le résultat est un tableau multidimensionnel, indexé numériquement.
En passant la valeur TRUE au paramètre optionnel preserve_keys, vous pouvez forcer PHP à préserver les clés originales du tableau input. Si vous utilisez la valeur par défaut (FALSE), de nouveaux index numériques seront fournis, commencant à 0.
array_count_values
Description
array array_count_values ( array input)array_count_values() retourne un tableau contenant les valeurs du tableau input comme clés et leurs fréquence comme valeur.
Note : array_count_values() a été ajoutée en PHP 4.0.
array_diff
Description
array array_diff ( array array1, array array2 [, array ...])array_diff() retourne un tableau qui contient toutes les valeurs du tableau array1 qui sont absentes de tous les autres arguments. Notez que les clés sont préservées.
$result contient array("bleu");. Les valeurs multiples dans $array1 seront toutes traitées de la même façon.
Note : Deux éléments sont considérés comme égaux si et seulement si (string) $elem1 === (string) $elem2. En clair : lorsque la représentation en chaîne de caractères est identique.
| Avertissement |
Cette fonction était inutilisable en PHP 4.0.4! |
Voir aussi array_intersect().
array_fill
Description
array array_fill ( int start_index, int num, mixed value)array_fill() crée un tableau avec num entrées de la valeur value. Les index commecent à la valeur start_index.
array_filter
Description
array array_filter ( array input [, mixed callback])array_filter() retourne un tableau contenant les éléments du tableau input, filtrés grâce à la fonction callback. Si input est un tableau associatif, les clés sont préservées.
Exemple 1. Exemple avec array_filter()
|
Cet exemple montre comment extraire les nombres pairs dans $tableau_impair : ce dernier contient array ("a"=>1, "c"=>3, "e"=>5);, et les nombres impairs dans $tableau_pair : ce dernier contient array (6, 8, 10, 12);,
Voir aussi array_map() et array_reduce().
array_flip
Description
array array_flip ( array trans)array_flip() retourne un tableau dont les clés sont les valeurs du précédent tableau, et les valeurs sont les clés. array_flip() ne fonctionne que sur des entiers et des chaînes, et affichera une erreur s'il détecte une clé ou une valeur de type invalide (tableau, objet, booléen, nombre à virgule flottante).
Notez bien que les valeurs de trans doivent être des clés valides, c'est à dire qu'elles doivent être des entiers (integer) ou des chaînes de caractères (string). Une alerte sera émise si une valeur a un type qui ne convient pas et la paire en question ne sera pas inversée.
Si une valeur n'est pas unique, seule la dernière clé sera utilisée comme valeur, et toutes les autres seront perdues.
array_flip() retourne FALSE en cas d'échec.
Note : array_flip() a été ajoutée en PHP 4.0.
array_intersect
Description
array array_intersect ( array array1, array array2 [, array ...])array_intersect() retourne un tableau contenant toutes les valeurs de array1 qui sont présentes dans tous les autres arguments. Notez que les clés sont préservées.
Note : Deux éléments sont considérés comme égaux si et seulement si (string) $elem1 === (string) $elem2. En clair : lorsque la représentation en chaîne de caractères est identique.
| Avertissement |
Cette fonction était inutilisable en PHP 4.0.4! |
$result contient array ("a" => "vert", "rouge");.
Voir aussi array_diff().
array_key_exists
Description
bool array_key_exists ( mixed key, array search)array_key_exists() returns TRUE if the given key is set in the array. key can be any value possible for an array index.
Note : The name of this function is key_exists() in PHP version 4.0.6.
See also isset().
array_keys
Description
array array_keys ( array input [, mixed search_value])array_keys() retourne les clés numériques et litérales du tableau input.
Si l'option search_value est spécifiée, seules les clés ayant cette valeur seront retournées. Sinon, toutes les clés de input sont retournées.
Exemple 1. Exemple avec array_keys()
|
Note : array_keys() a été ajoutée en PHP 4. Ci-dessous, voici une implémentation qui fonctionnera sous PHP 3:
Voir aussi array_values().
array_map
Description
array array_map ( mixed callback, array arr1 [, array ...])array_map() retourne un tableau contenant tous les éléments du tableau arr1, après leur avoir appliqué la fonction callback. Le nombre de paramètres de la fonction callback doit être égal au nombre de tableaux passés dans la fonction array_map().
Avec cet exemple, la variable $b contiendra array (1, 8, 27, 64, 125);.
Exemple 2. array_map() - utilisation de plusieurs tableaux
|
Généralement, lorsque vous utilisez plusieurs tableaux, ils doivent être de même longueur, car la fonction de callback est appliqué à un élément de chaque tableau. Si les tableaux sont de taille inégale, les plus petits seront complétés avec des éléments vides.
Une utilisation interessante de cette fonction est de construire des tableaux de tableaux, grâce à la fonction de callback NULL.
Exemple 3. array_map() - création d'un tableau de tableaux
|
Voir aussi array_filter() et array_reduce().
array_merge_recursive
Description
array array_merge_recursive ( array array1, array array2 [, array ...])array_merge_recursive() rassemble tous les éléments de plusieurs tableaux ensembles, en ajoutant les éléments de l'un à la suite des éléments du précédent. array_merge_recursive() retourne le tableau résultant.
Si les tableaux passés en arguments ont les mêmes clés (chaînes de caractères), les valeurs sont alors rassemblées dans un tableau, de manière récursive, de façon à ce que, si l'une de ces valeurs est un tableau elle-même, la fonction la rassemblera avec les valeurs de l'entrée courante. Cependant, si deux tableaux ont la même clé numérique, la dernière valeur n'écrasera pas la précédente, mais sera ajoutée à la fin du tableau.
Le résultat sera array("couleur" => array("favorie" => array ("rouge", "vert"), "bleu"), 5, 10).
Voir aussi array_merge().
array_merge
Description
array array_merge ( array array1, array array2 [, array ...])array_merge() rassemble les éléments de plusieurs tableaux ensembles, en ajoutant les valeurs de l'un à la fin de l'autre. Le résultat est un tableau.
Si les tableaux ont des clés en commun, la dernière valeur rencontrée écrasera l'ancienne. Pour les valeurs numériques, cela n'arrive pas, car alors, les valeurs sont ajoutées en fin de tableau.
Note : array_merge() a été ajoutée dans PHP 4.0.
array_multisort
Description
boolean array_multisort ( array ar1 [, mixed arg [, mixed ... [, array ...]]])array_multisort() sert à trier simultanément plusieurs tableaux, ou bien à trier un tableau multi-dimensionnel, suivant l'une ou l'autre de ses dimensions. Les clés sont préservées.
Les tableaux passés en arguments sont traités comme les colonnes d'une table, triées par lignes (un peu comme la clause SQL ORDER BY). Le premier tableau est la clé primaire de tri. Les valeurs du premier tableau qui sont égales, sont triées grâce au tableau suivant, et ainsi de suite...
La structure des arguments de array_multisort() est un peu inhabituelle, mais elle est plus souple. Le premier argument DOIT être un tableau, mais les arguments suivants peuvent être des tableaux ou une ou deux options de tri, prises dans les valeurs suivantes :
Options de tri :
SORT_ASC - Tri en ordre ascendant
SORT_DESC - Tri en ordre descendant
Options de type de tri:
SORT_REGULAR - Comparaison normale des valeurs
SORT_NUMERIC - Comparaison numérique des valeurs
SORT_STRING - Comparaison alphabétique des valeurs
Une seule option de tri de chaque type peut être appliquée après un tableau. Une option ne s'applique qu'au tableau précédent. Tous les autres sont mis par défaut à SORT_ASC et SORT_REGULAR.
array_multisort() retourne TRUE en cas de succès, FALSE sinon.
Dans cet exemple, après le tri, le premier tableau contient 10, "a", 100, 100; Le deuxième tableau contient 1, 1, "2", 3. Les entrées du second tableau correspondant aux valeurs jumelles du premier tableau (100 et 100), sont aussi triées.
Dans cet exemple, après le tri, le premier tableau contient 10, 100, 100, "a" (tri alphabétique, ordre croissant); Le deuxième tableau contient 1, 3, "2", 1 (tri numérique, ordre décroissant).
array_pad
Description
array array_pad ( array input, int pad_size, mixed pad_value)array_pad() retourne une copie du tableau input complété jusqu'à la taille de pad_size avec la valeur pad_value. Si pad_size est positif, alors le tableau est complété à droite, s'il est négatif, il est complété à gauche. Si la valeur absolue de pad_size est plus petite que la taille du tableau input, alors le tableau n'est pas complété.
array_pop
Description
mixed array_pop ( array array)array_pop() dépile et retourne le dernier élément du tableau array, le raccourcissant d'un élément. Si array est vide, ou n'est pas un tableau, array_pop() retourne NULL.
Voir aussi array_push(), array_shift() et array_unshift().
Note : array_pop() a été ajoutée en PHP 4.0.
array_push
Description
int array_push ( array array, mixed var [, mixed ...])array_push() considère array comme une pile, et empile les variables passées en paramètres à la fin de array. La longueur du tableau array augmente d'autant. Cela a le même effet que :
<?php $array[] = $var; ?> |
array_push() retourne le nouveau nombre d'éléments du tableau.
Voir aussi array_pop(), array_shift() et array_unshift().
Note : array_push() a été ajoutée en PHP 4.0.
array_rand
Description
mixed array_rand ( array input [, int num_req])array_rand() est pratique lorsque vous voulez sélectionner une ou plusieurs valeurs au hasard dans un tableau. Le paramètre input est un tableau, et num_req spéficie le nombre de valeurs que vous voulez obtenir (par défaut, c'est 1).
Si vous ne demandez qu'une entrée, array_rand() retourne l'index de la valeur. Sinon, elle retourne un tableau d'index. Cela vous permet de faire une sélection au hasard de clés, ou bien de valeurs.
N'oubliez pas d'appeler srand() pour initialiser le générateur de nombres aléatoires.
array_reduce
Description
mixed array_reduce ( array input, mixed callback [, int initial])array_reduce() applique itérativement la fonction callback aux éléments du tableau input, de manière à réduire le tableau à une valeur simple. Si l'argument optionnel intial est disponible, il sera utilisé pour initialiser le processus, ou bien comme valeur finale si le tableau est vide.
Dans cet exemple, $b contiendra 15, $c contiendra 1200 (= 1*2*3*4*5*10), et $d contiendra 1.
Voir aussi array_filter() et array_map().
array_reverse
Description
array array_reverse ( array array [, boolean preserve_keys])array_reverse() prend le tableau array et retourne un nouveau tableau qui contient les mêmes éléments mais dans l'ordre inverse, en préservant les clés si le paramètre preserve_keys vaut TRUE.
Note : array_reverse() a été ajoutée en PHP 4.0 Beta 3.
Note : Le second paramètre preserve_keys a été ajouté en PHP 4.0.3.
array_search
Description
mixed array_search ( mixed needle, array haystack, boolean strict)array_search() recherche needle dans haystack et retourne la clé associée s'il la trouve, ou FALSE sinon.
Si le troisième paramètre strict vaut TRUE, alors array_search() s'assurera aussi que le type de needle est le même que celui de la valeur trouvée dans haystack.
Voir aussi in_array().
array_shift
Description
mixed array_shift ( array array)array_shift() extrait la première valeur d'un tableau et la retourne, en raccourcissant le tableau d'un élément, et en déplacant tous les éléments vers le bas. Si array est vide, ou n'est pas un tableau, array_shift() retourne NULL.
Voir aussi array_unshift(), array_push() et array_pop().
Note : array_shift() a été ajoutée en PHP 4.0.
array_slice
Description
array array_slice ( array array, int offset [, int length])array_slice() retourne une série d' élément du tableau array commençant à l'offset offset et représentant length éléments.
Si offset est positif, la série commencera à cet offset dans le tableau array. Si offset est négatif, cette série commencera à l'offset offset mais en commençant à la fin du tableau array.
Si length est fourni et positif, alors la série retournée aura autant d'éléments. Si length est fourni et négatif, alors la série contiendra les éléments depuis l'offset offset jusqu'à length éléments en partant de la fin. Si length est omis, la séquence lira tous les éléments du tableau, depuis l'offset précisé jusqu'à la fin du tableau.
Exemple 1. Exemple avec array_slice()
|
Voir aussi array_splice().
Note : array_slice() a été ajoutée en PHP 4.0.
array_splice
Description
array array_splice ( array input, int offset [, int length [, array replacement]])array_splice() supprime les éléments désignés par offset et length du tableau input et les remplace par les éléments du tableau replacement, si ce dernier est présent.
Si offset est positif, la série commencera à cet offset dans le tableau input. Si offset est négatif, cette série commencera à l'offset offset mais en commençant à la fin du tableau input.
Si length est donné et positif, alors la série aura autant d'éléments. Si length est donné et négatif, les éléments seront pris dans l'ordre inverse. Si length est omis, la séquence lira tous les éléments du tableau, depuis l'offset offset jusqu'à la fin du tableau. Conseil : pour supprimer tous les éléments du tableau depuis offset jusqu'à la fin, même si un tableau de remplacement replacement est spécifié, utilisez count(count($input)) à la place de length.
Si replacement est précisé, alors les éléments supprimés sont remplacés par les éléments de ce tableau. Si l'offset et length sont tels que la taille du tableau ne change pas, alors les éléments du tableau de remplacement replacement sont insérés à partir de l'offset offset.
Conseil : si le tableau de remplacement ne contient qu'un seul élément, il n'est pas obligatoire de forcer le type en tableau avec array(), à moins que cette variable ne soit elle-même un tableau.
Les codes suivants sont équivalents :
<?php array_push($input, $x, $y) array_splice($input, count($input), 0, array($x, $y)) array_pop($input) array_splice($input, -1) array_shift($input) array_splice($input, 0, 1) array_unshift($input, $x, $y) array_splice($input, 0, 0, array($x, $y)) $a[$x] = $y array_splice($input, $x, 1, $y) ?> |
array_splice() retourne le tableau des éléments supprimés.
Exemple 1. Exemples avec array_splice()
|
Voir aussi array_slice().
Note : array_splice() a été ajoutée en PHP 4.0.
array_sum
Description
mixed array_sum ( array arr)array_sum() retourne la somme des valeurs du tableau, sous forme d'un entier ou d'un nombre à virgule flottante.
array_unique
Description
array array_unique ( array array)array_unique() prend le tableau array et retourne un nouveau tableau, complètement dédoublonné.
Note : Deux éléments sont considérés comme égaux si et seulement si (string) $elem1 === (string) $elem2. En clair : lorsque la représentation en chaîne de caractères est identique.
| Avertissement |
Cette fonction était inutilisable en PHP 4.0.4! |
Notez que les clés sont préservées. array_unique() conserve la clé de la première valeur rencontrée, et ignore toutes les suivantes.
array_unshift
Description
int array_unshift ( array array, mixed var [, mixed ...])array_unshift() ajoute les éléments passés en argument au début du tableau array. Notez que les éléments sont ajoutés comme un tout, et qu'ils restent dans le même ordre.
array_unshift() retourne le nouveau nombre d'éléments du tableau array.
Voir aussi array_shift(), array_push(), et array_pop().
Note : array_unshift() a été ajoutée en PHP 4.0.
array_values
Description
array array_values ( array input)array_values()retourne les valeurs du tableau input.
Note : array_values() a été ajoutée en PHP 4. Ci-dessous, voici une implémentation pour ceux qui utilisent toujours PHP 3.
array_walk
Description
int array_walk ( array arr, string func, mixed userdata)array_walk() exécute la fonction func avec chaque élément du tableau arr. Les éléments sont passés en tant que premier argument de la fonction func. func doit être une fonction définie par l'utilisateur, et non pas une fonction native PHP. Vous ne pouvez pas utiliser array_walk() directement avec str2lower(), il faut absolument passer par une fonction utilisateur.
Si func a besoin de plus d'un argument, une alerte sera générée pour chaque appel de func. Ces alertes sont supprimées en ajoutant le suffixe '@' avant l'appel de array_walk() ou simplement en utilisant error_reporting().
Note : Si func doit travailler avec les véritables valeurs du tableau, spécifiez que le premier paramètre de func doit être passé par référence. Alors, les éléments seront directement modifiés dans le tableau.
Note : Passer les clés et userdata à func a été ajouté en PHP 4.0.
En PHP 4, reset() doit être appelé si nécessaire, car array_walk() ne réinitialise pas automatiquement le tableau.
Exemple 1. Exemple avec array_walk()
|
array
Description
array array ( [mixed ...])array() retourne un tableau créé avec les paramètres passés. On peut attribuer un index particulier à une valeur avec l'opérateur =?>.
Note : array() est un élément de langage utilisé pour représenter des tableaux litéraux, et non pas une fonction au sens strict du terme.
La syntaxe "index => valeur", séparée par des virgules, définit les index et leur valeur. Un index peut être une chaîne ou un nombre. Si l'index est omis, un index numérique sera automatiquement généré (commençant à 0). Si l'index est un entier, le prochain index généré prendra la valeur d'index la plus grande + 1. Notez que si deux index identiques sont définis, le dernier remplacera le premier.
L'exemple suivant montre comment créer un tableau à deux dimensions, comment spécifier les index d'un tableau associatif, et comment générer automatiquement des index numériques.
Notez bien que l'index '3' est défini deux fois, et conserve finalement sa dernière valeur de 13. L'index '4' est défini après l'index '8', et l'index généré suivant (valeur 19) est 9, puisque le plus grand index est alors 8.
Cet exemple crée un tableau dont les index commencent à 1.
Voir aussi list().
arsort
Description
void arsort ( array array)arsort() trie un tableau de telle manière que la corrélation entre les index et les valeurs soit conservée. L'usage principal est lors de tri de tableaux associatifs où l'ordre des éléments est important.
Voir aussi array-multisort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort() et usort().
asort
Description
void asort ( array array)asort() trie un tableau de telle manière que la corrélation entre les index et les valeurs soit conservée. L'usage principal est lors de tri de tableaux associatifs où l'ordre des éléments est important.
Voir aussi array-multisort(), arsort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort() et usort().
compact
Description
array compact ( string|array varname [, mixed ...])compact() accepte différents paramètres. Les paramètres peuvent être des variables contenant des chaînes, ou un tableau de chaînes, qui peut contenir d'autres tableaux de noms, que compact() traitera récursivement.
Pour chacun des arguments, compact() recherche une variable avec une variable de même nom dans la table courante des symboles, et l'ajoute dans le tableau, de manière à avoir la relation nom => 'valeur de variable'. En bref, c'est le contraire de la fonction extract(). compact() retourne le tableau ainsi créé.
Exemple 1. Exemple avec compact()
Après cette opération, $result sera le tableau suivant : array(("evenement" => "SIGGRAPH", "ville" => "San Francisco", "etat" => "CA"). |
Voir aussi extract().
Note : compact() a été ajoutée en PHP 4.0.
count
Description
int count ( mixed var)count() retourne le nombre d'éléments dans var, qui est généralement un tableau (et tout le reste n'aura qu'un élément).
If var n'est pas un tableau, 1 sera retourné (exception : count(NULL) égale 0).
| Avertissement |
count() peut retourner 0 pour une variable qui n'a pas été affectée, ou pour un tableau vide. Utilisez plutôt isset() pour tester si la variable existe. |
Voir aussi sizeof(), isset() et is_array().
current
Description
mixed current ( array array)Chaque tableau entretient un pointeur interne, qui est initialisé lorsque le premier élément est inséré dans le tableau.
current() ne fait que retourner l'élément courant pointé par le pointeur interne du tableau array. current() ne déplace pas le pointeur. Si le pointeur est au-delà du dernier élément de la liste, current() retourne FALSE.
| Avertissement |
Si le tableau des éléments vides ou des zéros (0 ou "", la chaîne vide) alors current() retournera FALSE pour ces éléments. Il est donc impossible de déterminer si vous êtes réellement à la fin de la liste en utilisant la fonction current(). Pour passer en revue proprement un tableau qui peut contenir des éléments vides ou des zéros, utilisez la fonction each(). |
each
Description
array each ( array array)each() retourne la paire (clé/valeur) courante du tableau array et avance le pointeur de tableau. Cette paire est retournée dans un tableau de 4 éléments, avec les clés 0, 1, key, et value. Les éléments 0 et key contiennent le nom de la clé et, et 1 et value contiennent la valeur.
Si le pointeur interne de fichier est au-delà de la fin du tableau, each() retourne FALSE.
Exemple 1. Exemples avec each()
$bar contient maintenant les paires suivantes:
$bar contient maintenant les paires suivantes:
|
each() est utilisé conjointement avec list() pour étudier tous les éléments d'un tableau; par exemple, $HTTP_POST_VARS:
Après chaque each(), le pointeur de tableau est déplacé au dernier élément, ou sur le dernier élément, lorsqu'on arrive à la fin.
Voir aussi key(), list(), current(), reset(), next() et prev().
end
Description
end ( array array)end() déplace le pointeur interne du tableau array jusqu'au dernier élément.
extract
Description
int extract ( array var_array [, int extract_type [, string prefix]])extract() sert à exporter un tableau vers la table des symboles. Elle prend un tableau associatif var_array, crée les variables dont les noms sont les index de ce tableau, et leur affecte la valeur associée. Pour chaque paire clé/valeur, extract() crée une variable, avec les paramètres extract_type et prefix.
Note : Depuis la version 4.0.5, extract() retourne le nombre de variables extraites.
extract() vérifie l'existence de la variable avant de la créer. Le traitement des collisions est déterminé par extract_type. Ce paramètre peut prendre une des valeurs suivantes :
- EXTR_OVERWRITE
Lors d'une collision, réécrire la variable existante.
- EXTR_SKIP
Lors d'une collision, ne pas réécrire la variable existante.
- EXTR_PREFIX_SAME
Lors d'une collision, ajouter le préfixe prefix, et créer une nouvelle variable.
- EXTR_PREFIX_ALL
Ajouter le préfixe prefix, et créer une nouvelle variable.
- EXTR_PREFIX_INVALID
Préfixer uniquement les variables aux noms invalides ou numériques avec le préfixe prefix. Ceci a été ajouté en PHP 4.0.5.
Si extract_type est omis, extract() utilise EXTR_OVERWRITE par défaut.
Notez que prefix n'est nécessaire que pour les valeurs de extract_type suivantes : EXTR_PREFIX_SAME, EXTR_PREFIX_ALL ou EXTR_PREFIX_INVALID. Le résultat préfixé n'est pas un nom de variable valide, il ne sera pas importé dans la table des symboles.
extract() retourne le nombre de variables réellement importées dans la table des symboles.
Une utilisation possible de la fonction extract() est l'exportation vers la table des symboles de tableaux de variables retournés par wddx_deserialize().
Exemple 1. Exemple avec extract()
|
L'exemple ci-dessus va afficher bleu, large, sphere, moyen
La variable $taille n'a pas été réécrite, car on avait spécifié le paramètre EXTR_PREFIX_SAME, qui a permis la création $wddx_size. Si EXTR_SKIP avait été utilisé, alors $wddx_size n'aurait pas été créé. Avec EXTR_OVERWRITE, $taille aurait pris la valeur "moyen", et avec EXTR_PREFIX_ALL, les variables créées seraient $wddx_couleur, $wddx_taille, et $wddx_forme.
in_array
Description
boolean in_array ( mixed needle, array haystack [, boolean strict])in_array() recherche needle dans haystack et retourne TRUE s'il s'y trouve, ou FALSE sinon.
Le troisième paramètre strict est optionnel. S'il vaut TRUE alors in_array() vérifiera aussi que le types du paramètre needle correspond à la valeur trouvée dans haystack.
L'affichage sera :
Note : in_array() a été ajoutée en PHP 4.0.
Voir aussi array_search().
key
krsort
Description
int krsort ( array array)krsort() trie un tableau en ordre inverse et suivant les clés, en maintenant la correspondance entre les clés et les valeurs. Cette fonction est pratique pour les tableaux associatifs.
Voir aussi array-multisort(), arsort(), asort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort() et usort().
ksort
Description
int ksort ( array array)ksort() trie un tableau suivant les clés, en maintenant la correspondance entre les clés et les valeurs. Cette fonction est pratique pour les tableaux associatifs.
Vous pouvez modifier le comportement du tri avec les options sort_flags. Pour plus de détails, voyez sort().
Voir aussi array-multisort(), arsort(), asort(), krsort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort() et usort().
Note : Le second paramètre a été ajouté en PHP 4.0.
list
Description
void list ( void)Tout comme array(), list() n'est pas une véritable fonction, mais une construction syntaxique, qui permet d'assigner une série de variables en une seule ligne.
Exemple 1. Exemple avec list()
|
natcasesort
Description
void natcasesort ( array array)natcasesort() implémente un algorithme de tri qui traite les chaînes alpha-numériques comme un être humain : c'est ce qui est appelé l'"ordre naturel".
natcasesort() est la version insensible à la casse de natsort(). Voir aussi natsort() pour un exemple illustré.
Pour plus de détails, rendez-vous sur le site de : Martin Pool's Natural Order String Comparison.
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), rsort(), sort(), uasort(), uksort(), usort(), strnatcmp() et strnatcasecmp().
natsort
Description
void natsort ( array array)natsort() implémente un algorithme de tri qui traite les chaînes alpha-numériques comme un être humain : c'est ce qui est appelé l'"ordre naturel". Un exemple de la différence de traitement entre un tel algorithme et un algorithme de tri de chaînes (comme lorsqu'on utilise sort()) est illustré ci-dessous :
L'exemple ci-dessous génère l'affichage suivant :
Tri Standard
Array
(
[0] => img1.png
[1] => img10.png
[2] => img12.png
[3] => img2.png
)
Tri par Ordre Naturel
Array
(
[3] => img1.png
[2] => img2.png
[1] => img10.png
[0] => img12.png
)
?> |
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort(), usort(), strnatcmp() et strnatcasecmp().
next
Description
mixed next ( array array)next() retourne l'élément suivant du tableau, ou FALSE s'il n'y a plus d'éléments. Le pointeur de interne de tableau est avancé d'un élément.
next() se comporte comme current(), mais avec une différence : il avance le pointeur interne de tableau d'un élément avant de retourner la valeur qu'il pointe. Lorsque le pointeur dépasse le dernier élément, next() retourne FALSE.
| Avertissement |
Si le tableau contient des éléments vides ou des zéros, next() retournera FALSE pour ces éléments. Pour passer proprement en revue un tableau, il faut utiliser each(). |
pos
prev
Description
mixed prev ( array array)prev() repositionne le pointeur interne de tableau à la dernière place qu'il occupait, ou bien retourne FALSE s'il ne reste plus d'éléments.
| Avertissement |
Si le tableau contient des éléments vides, prev() retournera FALSE pour ces éléments aussi. Pour passer en revue tous les éléments, utilisez plutôt each(). |
prev() se comporte exactement comme next(), mais il fait reculer le pointeur plutôt que de l'avancer.
range
Description
array range ( int low, int high)range() retourne un tableau contenant tous les entiers depuis low jusqu'à high, inclus.
Voir aussi shuffle() (pour un exemple d'utilisation).
reset
Description
mixed reset ( array array)reset() replace le pointeur de tableau array au premier élément.
reset() retourne la valeur du premier élément.
rsort
Description
void rsort ( array array)rsort() effectue un tri en ordre décroissant (du plus grand au plus petit).
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), sort(), uasort(), uksort() et usort().
shuffle
Description
void shuffle ( array array)shuffle() mélange les éléments d'un tableau.
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort(), uksort() et usort().
sizeof
Description
int sizeof ( array array)sizeof() retourne le nombre d'élément d'un tableau.
Voir aussi count().
sort
Description
void sort ( array array)sort() trie le tableau array. Les éléments seront triés du plus petit au plus grand.
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), uasort(), uksort() et usort().
uasort
(PHP 3>= 3.0.4, PHP 4 )
uasort -- Trie d'un tableau en utilisant une fonction de comparaison définie par l'utilisateur.Description
void uasort ( array array, function cmp_function)uasort() trie un tableau en conservant la correspondance entre les index et leurs valeurs. uasort() sert essentiellement lors de tri de tableaux associatifs où l'ordre des éléments est significatif. La fonction de comparaison utilisée est définie par l'utilisateur.
uksort
(PHP 3>= 3.0.4, PHP 4 )
uksort -- Trie un tableau par ses clés en utilisant une fonction de comparaison définie par l'utilisateurDescription
void uksort ( array array, function cmp_function)uksort() trie les clés du tableau en utilisant une fonction définie par l'utilisateur. Si un tableau doit être trié avec un critère complexe, il est préférable d'utiliser uksort().
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort() et usort().
usort
(PHP 3>= 3.0.3, PHP 4 )
usort -- Trie un tableau en utilisant une fonction de comparaison définie par l'utilisateurDescription
void usort ( array array, function cmp_function)usort() va trier un tableau avec ses valeurs, en utilisant une fonction définie par l'utilisateur. Si un tableau doit être trié avec un critère complexe, il est préférable d'utiliser cette méthode.
La fonction de comparaison cmp_function doit retourner un entier, qui sera inférieur, égal ou supérieur à zéro suivant que le premier argument est considéré comme plus petit, égal ou plus grand que le second argument. Si les deux arguments sont égaux, leur ordre est indéfini.
Note : Evidemment dans ce cas trivial, rsort() serait plus approprié.
| Avertissement |
Les bibliothèques de tri rapides sur lesquelles reposent PHP peuvent le conduire à un plantage, si la fonction de comparaison ne retourne pas une valeur cohérente. |
Voir aussi array-multisort(), arsort(), asort(), krsort(), ksort(), natsort(), natcasesort(), rsort(), sort(), uasort() et uksort().
III. Aspell
Les fonctions Aspell vous permettent de vérifier l'orthographe d'un mot, et d'offrir des suggestions de corrections. Plusieurs langues sont disponibles, comme le français, l'anglais, l'allemand, le suédois ou le danois.
Note : Aspell fonctionne avec de très vielles versions (jusqu'à la version .27.* ou presque) de la librairie Aspell. Ce module, et ces versions d'Aspell ne sont plus supportées. Si vous voulez exploiter des capacités de vérifications orthographiques en PHP, utilisez plutôt pspell. Ce module utilise la librairie pspell qui fonctionne avec les nouvelles versions de Aspell.
Vous avez besoin de la librairie Aspell, disponible à : http://aspell.sourceforge.net/.
- Table des matières
- aspell_check_raw -- Vérifie un mot sans en changer la casse et sans essayer de supprimer les espaces aux extrémités. [Obsolète]
- aspell_check -- Vérifie un mot [Obsolète]
- aspell_new -- Charge un nouveau dictionnaire [Obsolète]
- aspell_suggest -- Suggère l'orthographe d'un mot [Obsolète]
aspell_check_raw
(PHP 3>= 3.0.7, PHP 4 )
aspell_check_raw -- Vérifie un mot sans en changer la casse et sans essayer de supprimer les espaces aux extrémités. [Obsolète]Description
boolean aspell_check_raw ( resource dictionary_link, string word)aspell_check_raw() vérifie l'orthographe d'un mot sans en changer la casse, et sans essayer de supprimer les espaces aux extrémités. Elle retourne TRUE si l'orthographe est bonne, et FALSE sinon.
aspell_check
Description
boolean aspell_check ( resource dictionary_link, string word)aspell_check() vérifie l'orthographe d'un mot et retourne TRUE si l'orthographe est correcte, et FALSE sinon.
aspell_new
Description
resource aspell_new ( string master, string personal)aspell_new() ouvre un nouveau dictionaire, et retourne un identifiant de dictionnaire pour utilisation ultérieure dans les fonctions aspell. aspell_new() retourne FALSE en cas d'erreur.
aspell_suggest
IV. Nombres de grande taille
En PHP 4, ces fonctions ne sont disponibles que si l'option de configuration --enable-bcmath a été activée lors de la compilation. En PHP 3, ces fonctions ne sont disponibles que si l'option de configuration --disable-bcmath a été n' pas été activée lors de la compilation.
Note : Suite aux changement de licence, la librairie BCMATH est désormais distribuée séparemment. Vous pouvez télécharger l'archive à http://www.php.net/extra/number4.tar.gz. Lisez attentivement le fichier README.BCMATH de la distribution PHP.
- Table des matières
- bcadd -- Additionne deux nombres de grande taille.
- bccomp -- Compare deux nombres de grande taille.
- bcdiv -- Divise deux nombres de grande taille.
- bcmod -- Retourne le reste d'une division entre nombre de grande taille.
- bcmul -- Multiplie deux nombres de grande taille.
- bcpow -- Elève un nombre à la puissance n-ième.
- bcscale -- Détermine le nombre de décimales par défaut
- bcsqrt -- Renvoie la racine carrée d'un nombre de grande taille.
- bcsub -- Soustrait un nombre de grande taille à un autre.
bcadd
Description
string bcadd ( string left_operand, string right_operand [, int scale])bcadd() additionne left_operand avec l'opérande right_operand et renvoie la somme sous forme de chaîne de caractères. Le paramètre optionnel scale est utilisé pour définir le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcsub().
bccomp
Description
int bccomp ( string left_operand, string right_operand [, int scale])bccomp() compare l'opérande left_operand avec l'opérande right_operand et renvoie le résultat sous forme de valeur numérique (entier). Le paramètre optionnel scale est utilisé pour définir le nombre de chiffres après la virgule utilisés lors de la comparaison. Le résultat est 0 si les deux opérandes sont égales. Si l'opérande left_operand est plus grande que l'opérande right_operand, le résultat est 1. Si l'opérande left_operand est plus petite que l'opérande right_operand, le résultat est -1.
bcdiv
Description
string bcdiv ( string left_operand, string right_operand [, int scale])bcdiv() divise l'opérande left_operand par l'opérande right_operand et renvoie le résultat. Le paramètre optionnel scale définit le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcmul().
bcmod
Description
string bcmod ( string left_operand, string modulus)bcmod() retourne le reste de la division entre left_operand en utilisant modulus.
Voir aussi bcdiv().
bcmul
Description
string bcmul ( string left_operand, string right_operand [, int scale])bcmul() multiplie l'opérande left_operand par l'opérande right_operand et renvoie le résultat. Le paramètre optionnel scale définit le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcdiv().
bcpow
Description
string bcpow ( string x, string y [, int scale])bcpow() élève x à la puissance y. Le paramètre optionnel scale définit le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcsqrt().
bcscale
Description
string bcscale ( int scale)bcscale() définit la précision par défaut pour toutes les fonctions mathématiques sur des nombres de taille arbitraire qui suivent et qui omettent le paramètre scale.
bcsqrt
Description
string bcsqrt ( string operand [, int scale])bcsqrt() renvoie la racine carrée de l'opérande operand. Le paramètre optionnel scale définit le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcpow().
bcsub
Description
string bcsub ( string left_operand, string right_operand [, int scale])bcsub() soustrait l'opérande right_operand à l'opérande left_operand et renvoie le résultat sous forme de chaîne de caractères. Le paramètre optionnel scale définit le nombre de chiffres après la virgule dans le résultat.
Voir aussi bcadd().
V. Compression Bzip2
Ce module utilise les fonctions de la librairie bzip2, de Julian Seward pour écrire et lire des fichier bzip2 (.bz2) de manière transparente.
Le support bzip2 par PHP n'est pas activé par défaut. Vous devez utiliser l'option de configuration --with-bz2[=DIR] lors de la compilation de PHP pour l'activer. Ce module requiert la librairie bzip2/libbzip2, version >= 1.0.x.
Exemple de compression bzip2
Cet exemple ouvre un fichier temporaire, et écrit une ligne de test, puis il en affiche le contenu.
Exemple 1. Exemple avec bzip2
|
- Table des matières
- bzclose -- Ferme un fichier bzip2
- bzcompress -- Compresse une chaîne avec bzip2
- bzdecompress -- Décompresse une chaîne bzip2
- bzerrno -- Retourne le numéro 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 -- Force l'écriture de toutes les données compressées
- bzopen -- Ouvre un fichier compressé avec bzip2
- bzread -- Lecture binaire d'un fichier bzip2
- bzwrite -- Ecriture binaire dans un fichier bzip2
bzclose
Description
int bzclose ( resource bz)bzclose() ferme le fichier bzip2 représenté par le pointeur bz.
bzclose() retourne TRUE en cas de succès, et FALSE sinon.
Le pointeur de fichier bz doit être valide, et avoir été ouvert avec bzopen().
Voir aussi bzopen().
bzcompress
Description
string bzcompress ( string source [, int blocksize [, int workfactor]])bzcompress() compresse la chaîne source et retourne les données ainsi encodée.
Le paramètre optionnel blocksize spécifie la taille de bloc utilisé 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 ressource pour ce faire. blocksize vaut par défaut 4.
Le paramètre optionnel workfactor 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, et 30 la valeur par défaut). En dehors de workfactor, le résultat sera le même.
Voir aussi bzdecompress().
bzdecompress
Description
string bzdecompress ( string source [, int small])bzdecompress() décompresse la chaîne source, en supposant qu'elle a été compressée avec bzip2, puis la retourne. Si le paramètre optionnel small 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. Reportez-vous à la documentation bzip2 pour plus de détails sur cette fonctionnalité.
Voir aussi bzcompress().
bzerrno
Description
int bzerrno ( resource bz)bzerrno() retourne le numéro d'erreur du fichier bz2 représenté par le pointeur bz.
Voir aussi bzerror() et bzerrstr().
bzerror
Description
array bzerror ( int bz)bzerror() retourne le numéro et le message d'erreur du fichier bz2 représenté par le pointeur bz. bzerror() retourne un tableau associatif.
Voir aussi bzerrno() et bzerrstr().
bzerrstr
Description
string bzerrstr ( resource bz)bzerrstr() retourne le message d'erreur du fichier bz2 représenté par le pointeur bz.
bzflush
Description
int bzflush ( resource bz)bzflush() vide les buffers d'écriture du fichier représenté par bz.
bzflush() retourne TRUE en cas de succès, et FALSE sinon.
bzopen
Description
resource bzopen ( string filename, string mode)bzopen() ouvre un fichier bzip2 (.bz2) en écriture ou en lecture. filename est le nom du fichier à ouvrir. mode est similaire au même paramètre de la fonction fopen() (`r' pour lecture, `w' pour écriture, etc.).
Si l'ouverture échoue, bzopen() retourne FALSE, sinon, elle retourne un pointeur de fichier.
Voir aussi bzclose().
bzread
Description
string bzread ( resource bz [, int length])bzread() lit jusqu'à length octets depuis le fichier bzip2, référencé par le pointeur bz. La lecture s'arrête lorsque length octets (non compressés) ont été lus, qu'une erreur est rencontrée, ou bien que la fin du fichier a été atteinte : le premier des trois qui survient. Si le paramètre optionnel length est omis, bzread() lit 1024 octets (non compressés) en même temps.
bzwrite
Description
int bzwrite ( resource bz, string data [, int length])bzwrite() écrit le contenu de la chaîne data dans le fichier bzip2 représenté par bz. Si le paramètre optionnel length est fourni, l'écriture sera arrêtée après l'écriture de length octets (non compressés), ou la fin de la chaîne (le premier qui survient).
VI. Calendrier
Les fonctions de calendrier ne sont disponibles que si l'extension calendrier a été compilée. Elle est située dans les sous-dossiers "dl" ou "ext" de votre distribution de PHP. Lisez le fichier README pour plus de détails.
L'extension de calendrier propose une série de fonctions qui simplifient les conversions entre les différents formats de calendrier. La référence est le nombre de jours du calendrier Julien. C'est le nombre de jours depuis une date qui commence bien au-delà des dates les plus reculées dont on a besoin (située en 4000 avant J.C.). Pour convertir une date d'un calendrier à un autre, il faut d'abord la convertir dans ce calendrier, puis convertir le résultat dans le calendrier désiré. Attention, le nombre de jours du calendrier Julien est un système très différent du calendrier Julien!. Pour plus d'informations (en anglais), reportez-vous à http://genealogy.org/~scottlee/cal-overview.html. Les traductions issues de ces pages seront mises entre guillemets.
- Table des matières
- cal_days_in_month -- Return the number of days in a month for a given year and calendar
- cal_from_jd -- Converts from Julian Day Count to a supported calendar and return extended information
- cal_info -- Returns information about a particular calendar
- cal_to_jd -- Converts from a supported calendar to Julian Day Count
- easter_date -- Retourne un timestamp UNIX pour Pâques, à minuit
- 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 nombre de jours Julien en timestamp UNIX
- JewishToJD -- Convertit une date du calendrier juif en nombre de jours du calendrier Julien.
- JulianToJD -- Convertit le nombre de jours du calendrier Julien en date du calendrier Julien.
- unixtojd -- Convertit un timestamp UNIX en nombre de jours Julien
cal_days_in_month
(PHP 4 >= 4.1.0)
cal_days_in_month -- Return the number of days in a month for a given year and calendarDescription
int cal_days_in_month ( int calendar, int month, int year)This function will return the number of days in the month of year for the specified calendar.
See also jdtounix().
cal_from_jd
(PHP 4 >= 4.1.0)
cal_from_jd -- Converts from Julian Day Count to a supported calendar and return extended informationcal_info
cal_to_jd
easter_date
Description
int easter_date ( int year)easter_date() retourne un timestamp UNIX pour Pâques, à minuit, pour une année donnée. Si l'année n'est pas précisée, c'est l'année en cours qui est utilisée.
ATTENTION: easter_date() génère une alerte (Warning) si la date tombe hors de la zone de validité des timestamp UNIX (i.e. 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 date 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 corrections ont été ajoutés pour rendre le cycle plus précis.
(Ce code est basé sur le programme en C de Simon Kershaw, <webmaster@ely.anglican.org>)
Voir easter_days() pour les calculs de date de Pâques avant 1970 et après 2037.
easter_days
(PHP 3>= 3.0.9, PHP 4 )
easter_days -- Retourne le nombre de jours entre le 21 Mars et Pâques, pour une année donnée.Description
int easter_days ( int year)easter_days() 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 en cours est utilisée par défaut.
easter_days() 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 (i.e. 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 date 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 corrections ont été ajoutés pour rendre le cycle plus précis.
(Ce code est basé sur le programme en C de Simon Kershaw, <webmaster@ely.anglican.org>)
Voir aussi easter_date().
FrenchToJD
(PHP 3, PHP 4 )
FrenchToJD -- Convertit une date du calendrier français républicain en nombre de jours du calendrier Julien.Description
int frenchtojd ( int month, int day, int year)frenchtojd() convertit une date du calendrier français républicain en nombre de jours du calendrier Julien.
Ces fonctions convertissent les dates comprises entre l'an 1 et l'an 14 (22 September 1792 à 22 September 1806 en calendrier grégorien). Cela couvre plus que la durée d'existence de ce calendrier.
GregorianToJD
(PHP 3, PHP 4 )
GregorianToJD -- Convertit une date grégorienne en nombre de jours du calendrier Julien.Description
int gregoriantojd ( int month, int day, int year)Intervalle de validité pour le calendrier grégorien : 4714 avant JC à 9999 après JC.A.D.
Bien qu'il soit possible de manipuler des dates jusqu'en 4714 avant JC, une telle utilisation n'est pas significative. En effet, ce calendrier fut créé le 18 octobre 1582 après J.C. (ou 5 octobre 1582 en calendrier grec). Certains pays ne l'acceptèrent que bien plus tard. Par exemple, les britanniques n'y passèrent en 1752, les Russes en 1918 et les Grecs en 1923. La plupart des pays européens utilisaient le calendrier Julien avant le Grégorien.
JDDayOfWeek
Description
mixed jddayofweek ( int julianday, int mode)jddayofweek() retourne le numéro du jour de la semaine. Peut retourner une chaîne ou un entier, en fonction du mode.
JDMonthName
Description
string jdmonthname ( int julianday, int mode)jdmonthname() 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é.
JDToFrench
(PHP 3, PHP 4 )
JDToFrench -- Convertit le nombre de jours du calendrier Julien en date du calendrier français républicainDescription
string jdtofrench ( int juliandaycount)jdtofrench() convertit le nombre de jours du calendrier julien en date du calendrier français républicain.
JDToGregorian
(PHP 3, PHP 4 )
JDToGregorian -- Convertit le nombre de jours du calendrier Julien en date grégorienne.Description
string jdtogregorian ( int julianday)jdtogregorian() 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".
JDToJewish
(PHP 3, PHP 4 )
JDToJewish -- Convertit le nombre de jours du calendrier Julien en date du calendrier juif.Description
string jdtojewish ( int julianday)jdtojewish() convertit le nombre de jours du calendrier Julien en date du calendrier juif.
JDToJulian
(PHP 3, PHP 4 )
JDToJulian -- Convertit le nombre de jours du calendrier Julien en date du calendrier Julien.Description
string jdtojulian ( int julianday)jdtojulian() convertit le nombre de jours du calendrier Julien en une chaîne contenant la date du calendrier Julien, au format "mois/jour/année".
jdtounix
Description
int jdtounix ( int jday)jdtounix() retourne un timestamp UNIX correspondant au nombre de jours Julien jday ou FALSE si jday n'est pas dans l'intervalle de validité de l'époque UNIX. (années grégoriennes entre 1970 et 2037 ou 2440588 <= jday <= 2465342 ).
Voir aussi jdtounix().
Note : jdtounix() n'est disponible qu'à partir de la version PHP 4.0RC1.
JewishToJD
(PHP 3, PHP 4 )
JewishToJD -- Convertit une date du calendrier juif en nombre de jours du calendrier Julien.Description
int jewishtojd ( int month, int day, int year)Bien qu'il soit possible de manipuler des dates à partir de l'an 1 (3761 avant JC), 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 commencait quand une nouvelle lune était observée.
JulianToJD
(PHP 3, PHP 4 )
JulianToJD -- Convertit le nombre de jours du calendrier Julien en date du calendrier Julien.Description
int juliantojd ( int month, int day, int year)Intervalle de validité du calendrier Julien : 4713 avant JC à 9999 après J.C..
Bien qu'il soit possible de manipuler des dates jusqu'en 4713 avant JC, une telle utilisation n'est pas significative. En effet, ce calendrier fut créé en 46 avant JC, et ses détails ne furent finalisés qu'au plus tôt en 8 après JC, et probablement pas avant le 4ème siècle après JC. 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.
unixtojd
Description
int unixtojd ( [int timestamp])unixtojd() retourne le nombre de jours Juliens du timestamp UNIX timestamp (nombre de secondes depuis le 1/1/1970), ou pour le jour courant si timestamp est omis.
Voir aussi jdtounix().
unixtojd() n'est disponible qu'à partir de la version PHP 4.0RC1.
Voir aussi easter_date().
VII. Paiement CCVS
Ces fonctions font l'interface avec les API CCVS, vous permettant de travailler directement avec CCVS depuis vos scripts PHP. CCVS est la solution apportée par RedHat au problème de l'intermédiaire, lors du traitement de transactions de cartes de crédit. Il vous permet travailler directement avec les maisons de crédits, via votre boîte *nix et un modem. En utilisant le module CCVS pour PHP, vous pouvez effectuer des transactions avec les cartes de crédits, directement depuis vos scripts PHP via CCVS. La suite vous montrera comment procéder.
Pour activer le support CCVS de PHP, commencez par vérifier votre installation CCVS. Vous devez configurer PHP avec l'option --with-ccvs. Si vous utilisez cette option sans spécifier le chemin de votre installation, PHP essaiera de la trouver à sa position par défaut (/usr/local/ccvs). Si CCVS est installé dans un autre dossier, lancez la configuration avec : --with-ccvs=$ccvs_path, où $ccvs_path est le chemin de votre installation CCVS. Notez bien que CCVS requiert que $ccvs_path/lib et $ccvs_path/include existent, et qu'ils contiennent respectivement cv_api.h et libccvs.a sous include et lib.
De plus, un démon ccvsd doit être disponible sur votre configuration, et qu'il soit accessible à vos scripts PHP. Assurez-vous aussi que l'utilisateur qui exécute les scripts PHP est le même que celui qui a installé CCVS (i.e. si vous avez installé CCVS avec l'utilisateur 'ccvs', vos scripts PHP doivent tourner aussi en 'ccvs').
Plus de détails sur CCVS sont disponibles à http://www.redhat.com/products/ccvs.
Cette documentation est en chantier. Jusqu'à sa finalisation, RedHat entretient une version légèrement démodée mais bien pratique à http://www.redhat.com/products/ccvs/support/CCVS3.3docs/ProgPHP.html.
- Table des matières
- ccvs_add -- Add data to a transaction
- ccvs_auth -- Perform credit authorization test on a transaction
- ccvs_command -- Performs a command which is peculiar to a single protocol, and thus is not available in the general CCVS API
- ccvs_count -- Find out how many transactions of a given type are stored in the system
- ccvs_delete -- Delete a transaction
- ccvs_done -- Terminate CCVS engine and do cleanup work
- ccvs_init -- Initialize CCVS for use
- ccvs_lookup -- Look up an item of a particular type in the database #
- ccvs_new -- Create a new, blank transaction
- ccvs_report -- Return the status of the background communication process
- ccvs_return -- Transfer funds from the merchant to the credit card holder
- ccvs_reverse -- Perform a full reversal on an already-processed authorization
- ccvs_sale -- Transfer funds from the credit card holder to the merchant
- ccvs_status -- Check the status of an invoice
- ccvs_textvalue -- Get text return value for previous function call
- ccvs_void -- Perform a full reversal on a completed transaction
ccvs_add
Description
string ccvs_add ( string session, string invoice, string argtype, string argval)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_auth
Description
string ccvs_auth ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_command
(PHP 4 >= 4.0.2)
ccvs_command -- Performs a command which is peculiar to a single protocol, and thus is not available in the general CCVS APIDescription
string ccvs_command ( string session, string type, string argval)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_count
(PHP 4 >= 4.0.2)
ccvs_count -- Find out how many transactions of a given type are stored in the systemDescription
int ccvs_count ( string session, string type)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_delete
Description
string ccvs_delete ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_done
Description
string ccvs_done ( string sess)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_init
Description
string ccvs_init ( string name)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_lookup
Description
string ccvs_lookup ( string session, string invoice, int inum)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_new
Description
string ccvs_new ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_report
Description
string ccvs_report ( string session, string type)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_return
Description
string ccvs_return ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_reverse
Description
string ccvs_reverse ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_sale
Description
string ccvs_sale ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_status
Description
string ccvs_status ( string session, string invoice)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_textvalue
Description
string ccvs_textvalue ( string session)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ccvs_void
VIII. Support COM pour Windows
Les fonctions COM sont uniquement disponibles sur les versions Windows de PHP. Elles ont été ajoutées à partir de PHP 4.0.
- Table des matières
- COM -- Classe COM
- VARIANT -- classe VARIANT
- com_addref -- Incrémente le compteur de références
- com_get -- Lit la valeur d'un propriété d'un composant COM
- com_invoke -- Appelle une méthode d'un composant
- com_isenum -- Grabs an IEnumVariant
- com_load_typelib -- Loads a Typelib
- com_load -- Crée une référence sur un composant COM
- com_propget -- Lit la valeur d'un propriété d'un composant COM
- com_propput -- Modifie une propriété d'un composant COM
- com_propset -- Modifie une propriété d'un composant COM
- com_release -- Décrémente le compteur de références
- com_set -- Modifie une propriété d'un composant COM
COM
Description
La classe COM fournit un environnement d'intégration des composants (D)COM dans vos scripts PHP.
Methods
string com::com ( string module_name [, string server_name [, int codepage]])Constructeur de la classe COM. Paramètres :
- module_name
nom ou class-id du composant deamndé.
- server_name
nom du serveur DCOM, auprès duquel le composant doit être sollicité. Si ce paramètre est NULL, localhost sera utilisé. Pour que les objets DCOM soient accessibles; il faut que com.allow_dcom ait la valeur TRUE dans le fichier php.ini.
- codepage
spécifie le code qui est utilisé pour transformer les chaînes de caractères PHP en chaînes unicode, et vice-versa. Les valeurs possibles sont CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 et CP_UTF8.
Exemple 1. Exemple COM (1)
|
Exemple 2. Example COM (2)
|
VARIANT
Methodes
string variant::variant ( [mixed value [, int type [, int codepage]]])Constructeur VARIANT. Paramètres:
- value
valeur initiale. Si omis, un objet VT_EMPTY.
- type
spécifie le type d'objet VARIANT contenu. Les valeurs possibles VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2, VT_I4, VT_R4, VT_R8, VT_INT, VT_UINT, VT_BOOL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DECIMAL, VT_UNKNOWN, VT_DISPATCH et VT_VARIANT. Ces valeurs sont mutuellement exclusives, mais elles peuvent être combinées avec VT_BYREF pour spécifier que c'est une valeur. Si omis le type de value est utilisé. Consultez la librairy MSDN pour plus de détails.
- codepage
spécifie le code qui est utilisé pour transformer les chaînes de caractères PHP en chaînes unicode, et vice-versa. Les valeurs possibles sont CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 et CP_UTF8.
com_addref
com_get
Description
mixed com_get ( resource com_object, string property)com_get() retourne la valeur de la propriété property du composant COM com_object. com_get() retourne FALSE en cas d'erreur.
com_invoke
Description
mixed com_invoke ( resource com_object, string function_name [, mixed function parameters, ...])com_invoke() appelle la méthode function_name du composant COM com_object. com_invoke() retourne FALSE en cas d'erreur, sinon retourne le résultat de la fonction function_name en cas de succès.
com_isenum
Description
void com_isenum ( object com_module)
| Avertissement |
This function is currently not documented, only the argument list is available. |
com_load_typelib
Description
void com_load_typelib ( string typelib_name [, int case_insensitive])
| Avertissement |
This function is currently not documented, only the argument list is available. |
com_load
Description
resource com_load ( string module_name [, string server_name])com_load() crée une nouvelle référence au composant COM module_name, et retourne une référence dessus. com_load() retourne FALSE en cas d'échec.
com_propget
Description
mixed com_propget ( resource com_object, string property)com_propget() est un alias de com_get().
com_propput
Description
void com_propput ( resource com_object, string property, mixed value)com_propput() est un alias de com_set().
com_propset
Description
void com_propset ( resource com_object, string property, mixed value)com_propset() est un alias de com_propput().
com_release
com_set
IX. Objets
Introduction
About
Ces fonctions permettent de gérer les classes et les objets. Vous pouvez notamment connaître le nom de la classe d'un objet, ses membres et ses méthodes, et tous les objets parents (les classes qui sont étendues par la classe d'un objet).
Exemple d'utilisation
Dans cet exemple, on définit une classe de base, et une extension. La classe de base définit un légume, s'il est mangeable ou pas, et sa couleur. La sous-classe epinard ajoute une méthode pour le cuisiner, et une autre pour savoir s'il est cuisiné.
Exemple 1. classes.inc
|
Lorsqu'on instantie deux objets de ces classes, et qu'on affiche leurs informations, on affiche aussi leur héritage. On définit ici des utilitaires qui servent essentiellement à afficher ces informations proprement.
Exemple 2. test_script.php
|
Il est important de noter que dans les exemples ci-dessus, les objets $feuilles sont une instance de Epinard qui est une sous-classe de Legume, donc la dernière partie du script va afficher :
- Table des matières
- call_user_method_array -- Appelle une méthode utilisateur avec un tableau de paramètres
- call_user_method -- Appelle une méthode utilisateur d'un objet
- class_exists -- Vérifie qu'une classe a été définie
- get_class_methods -- Retourne les noms des méthodes d'une classe.
- get_class_vars -- Retourne les valeurs par défaut des attributs d'une classe.
- get_class -- Retourne la classe d'un objet
- get_declared_classes -- Liste toutes les classes définies
- get_object_vars -- Retourne un tableau associatif des propriétés d'un objet
- get_parent_class -- Retourne le nom de la classe d'un objet
- is_a -- Returns TRUE if the object is of this class or has this class as one of its parents
- is_subclass_of -- Détermine si un objet est une sous-classe
- method_exists -- Vérifie que la méthode existe pour une classe.
call_user_method_array
(PHP 4 >= 4.0.5)
call_user_method_array -- Appelle une méthode utilisateur avec un tableau de paramètresDescription
mixed call_user_method_array ( string method_name, object obj [, array paramarr])call_user_method_array() appelle la méthode method_name de l'object obj, en utilisant les paramètres paramarr, rassemblés sous forme de tableau.
Voir aussi call_user_func_array(), call_user_func() et call_user_method().
Note : call_user_method_array() a été ajoutée en version PHP 4.05.
call_user_method
Description
mixed call_user_method ( string method_name, object obj [, mixed parameter [, mixed ...]])Appelle la méthode method_name depuis l'objet obj. Un exemple d'utilisation de cet objet est présenté ci-dessous, où une classe est définie, puis instantiée. On utilise alors call_user_method() pour appeler indirectement les méthodes print_info.
<?php
class Pays {
var $NOM;
var $TLD;
function Pays($nom, $tld) {
$this->NOM = $nom;
$this->TLD = $tld;
}
function print_info($prestr="") {
echo $prestr."Pays: ".$this->NOM."\n";
echo $prestr."Nom de domaine: ".$this->TLD."\n";
}
}
$unPays = new Pays("Pérou","pe");
echo "* Appel de la méthode directement\n";
$unPays->print_info();
echo "\n* Appel de la méthode indirectement\n";
call_user_method ("print_info", $unPays, "\t");
?> |
Voir aussi call_user_func_array(). call_user_func() et call_user_method_array().
class_exists
Description
boolean class_exists ( string class_name)class_exists() retourne TRUE si la classe class_name a été définie, et FALSE sinon.
get_class_methods
Description
array get_class_methods ( string class_name)get_class_methods() retourne un tableau contenant les noms des méthodes de la classe class_name.
Note : A partir de PHP 4.0.6, vous pouvez spécifier l'objet lui-même, au lieu de sa classe class_name. Par exemple :
Exemple 1. Exemple avec get_class_methods()
|
Va afficher :
Voir aussi get_class_vars() et get_object_vars()
get_class_vars
Description
array get_class_vars ( string class_name)get_class_vars() retourne un tableau contenant les valeurs par défaut des attributs de la classe class_name.
Note : Les variables de classe qui ne sont pas encore initialisées ne seront pas retournées par get_class_vars().
Exemple 1. Exemple get_class_vars()
|
va afficher :
get_class
Description
string get_class ( object obj)get_class() retourne la classe de l'objet obj.
Voir aussi get_parent_class() et is_subclass_of()
get_declared_classes
Description
array get_declared_classes ( void)get_declared_classes() retourne un tableau contenant la liste des fonctions déclarées dans le script courant.
Note : En PHP 4.0.1pl2, trois classes supplémentaires sont retournées, au début de ce tableau : stdClass (définie dans Zend/zend.c), OverloadedTestClass (définie dans ext/standard/basic_functions.c) et Directory (définie dans ext/standard/dir.c).
get_object_vars
Description
array get_object_vars ( object obj)get_object_vars() retourne un tableau associatif contenant les propriétés de l'objet obj. Les clés du tableau sont les noms des propriétés de l'objet.Si des variables déclarées dans la classe de l'objet obj, n'ont pas été assignées, elles ne seront pas retournées dans le tableau.
Exemple 1. Exemple avec get_object_vars()
|
Voir aussi get_class_methods() et get_class_vars()
get_parent_class
Description
string get_parent_class ( object obj)get_parent_class() retourne le nom de la classe de l'objet obj.
Voir aussi get_class() et is_subclass_of()
is_a
(PHP 4 >= 4.2.0)
is_a -- Returns TRUE if the object is of this class or has this class as one of its parentsDescription
bool is_a ( object object, string class_name)This function returns TRUE if the object is of this class or has this class as one of its parents, FALSE otherwise.
See also get_class(), get_parent_class(), and is_subclass_of().
is_subclass_of
Description
boolean is_subclass_of ( object obj, string superclass)is_subclass_of() retourne TRUE si l'objet obj est une sous-classe de superclass, FALSE sinon.
Voir aussi get_class() et get_parent_class()
method_exists
X. ClibPDF
L'extension ClibPDF vous permet de créer des documents PDF avec PHP. Elle est disponible en téléchargement sur le site FastIO, mais requiert l'achat d'une licence pour utilisation commerciale. Les fonctionnalités et API de ClibPDF sont très similaires à PDFlib.
Cette documentation devrait être lue avec le manuel ClibPDF sous la main, car il est beaucoup plus détaillé.
Beaucoup de fonctions sont natives de ClibPDF et se retrouvent dans le module PHP, et tout comme pdflib, elles ont le même nom. Toutes les fonctions, hormis cpdf_open() utilisent un pointeur sur un document comme premier paramètre. Actuellement, ce pointeur n'est pas utilisé en interne, car ClibPDF ne supporte pas la création de plusieurs documents PDF simultanément. En fait, il ne vaut mieux pas l'envisager, car les résultats sont aléatoires. Je ne veux même pas imaginer les problèmes qui pourrait se poser avec les environnements multi-tâches. Selon l'auteur de ClibPDF, cette situation va changer dans les prochaines versions (lorsque cette documentation a été traduite, c'était la version 1.10). Si vous avez besoin de cette fonctionnalité, utilisez pdflib.
Note : La fonction cpdf_set_font() a changé depuis le PHP 3.0 pour supporter les polices asiatiques. Le paramètre d'encodage n'est plus un entier, mais une chaîne.
Une caractéristique pratique de ClibPDF (et aussi de PDFlib) est celle de créer le document PDF en mémoire, sans fichiers temporaires. ClibPDF permet aussi de passer les coordonnées avec une unité prédéfinie (ce qui peut être simulé avec pdf_translate() de la librairie PDFlib).
Un autre atout de ClibPDF est que chaque page peut être modifiée à tout moment même si une nouvelle page a été ouverte. La fonction cpdf_set_current_page() vous permet de quitter temporairement une page, et d'en modifier une autre.
La plupart des fonctions sont très simples d'emploi. Le plus difficile est probablement de créer un document PDF simple. L'exemple suivant devrait vous aider à démarrer. La page contient du texte qui utilise la police "Times-Roman" en taille 30, outlined. Le texte est souligné.
Exemple 1. Exemple simple ClibPDF
|
La distribution pdflib contient un exemple plus complet, qui crée des séries de pages avec une horloge. Voici cet exemple convertit en script PHP qui utilise l'extension ClibPDF :
Exemple 2. Exemple pdfclock de la distribution pdflib 2.0
|
- Table des matières
- cpdf_add_annotation -- Ajoute une annotation.
- cpdf_add_outline -- Ajoute un signet à la page courante.
- cpdf_arc -- Dessine un arc de cercle.
- cpdf_begin_text -- Démarre une section de texte.
- cpdf_circle -- Dessine un cercle.
- cpdf_clip -- Aligne les dessins sur le chemin courant.
- cpdf_close -- Ferme un fichier PDF.
- cpdf_closepath_fill_stroke -- Remplit le chemin, dessine le bord et ferme le chemin.
- cpdf_closepath_stroke -- Ferme le fichier et dessine une ligne le long du chemin.
- cpdf_closepath -- Ferme le chemin.
- cpdf_continue_text -- Imprime le texte à la ligne suivante.
- cpdf_curveto -- Dessine une courbe.
- cpdf_end_text -- Termine une section de texte.
- cpdf_fill_stroke -- Remplit le chemin, et dessine le bord.
- cpdf_fill -- Remplit le chemin courant.
- cpdf_finalize_page -- Termine une page.
- cpdf_finalize -- Termine un document.
- cpdf_global_set_document_limits -- Fixe les limites d'un document PDF.
- cpdf_import_jpeg -- Ouvre une image JPEG.
- cpdf_lineto -- Dessine une ligne.
- cpdf_moveto -- Fixe le point courant.
- cpdf_newpath -- Commence un nouveau chemin
- cpdf_open -- Ouvre un nouveau document PDF.
- cpdf_output_buffer -- Outputs the pdf document in memory buffer
- cpdf_page_init -- Starts new page
- cpdf_place_inline_image -- Places an image on the page
- cpdf_rect -- Draw a rectangle
- cpdf_restore -- Restaure un environnement.
- cpdf_rlineto -- Dessine une ligne, relativement.
- cpdf_rmoveto -- Fixe le point courant relativement.
- cpdf_rotate_text -- Sets text rotation angle
- cpdf_rotate -- Effectue une rotation.
- cpdf_save_to_file -- Ecrit un document PDF dans un fichier.
- cpdf_save -- Sauve l'environnement courant.
- cpdf_scale -- Modifie l'échelle.
- cpdf_set_action_url -- Sets hyperlink
- cpdf_set_char_spacing -- Fixe l'espacement des caractères.
- cpdf_set_creator -- Fixe le créateur d'un document PDF.
- cpdf_set_current_page -- Fixe la page courante.
- cpdf_set_font_directories -- Sets directories to search when using external fonts
- cpdf_set_font_map_file -- Sets fontname to filename translation map when using external fonts
- cpdf_set_font -- Sélectionne la police courante et sa taille.
- cpdf_set_horiz_scaling -- Fixe l'échelle horizontale du texte.
- cpdf_set_keywords -- Fixe les mot clés d'un document PDF.
- cpdf_set_leading -- Fixe la distance entre deux lignes.
- cpdf_set_page_animation -- Fixe l'animation de la transition entre les pages.
- cpdf_set_subject -- Fixe le sujet d'un document PDF.
- cpdf_set_text_matrix -- Fixe la matrice du texte.
- cpdf_set_text_pos -- Fixe la position du texte.
- cpdf_set_text_rendering -- Détermine le rendu du texte.
- cpdf_set_text_rise -- Fixe l'élévation du texte.
- cpdf_set_title -- Fixe le titre d'un document PDF.
- cpdf_set_viewer_preferences -- How to show the document in the viewer
- cpdf_set_word_spacing -- Fixe l'espacement des mots.
- cpdf_setdash -- Fixe le motif de pointillé.
- cpdf_setflat -- Fixe la platitude (flatness).
- cpdf_setgray_fill -- Modifie le niveau de gris comme couleur de remplissage.
- cpdf_setgray_stroke -- Choisit un niveau de gris comme couleur de dessin.
- cpdf_setgray -- Modifie un niveau de gris comme couleur de dessin et de remplissage.
- cpdf_setlinecap -- Fixe le paramètre linecap.
- cpdf_setlinejoin -- Fixe le paramètre linejoin.
- cpdf_setlinewidth -- Fixe la largeur de ligne.
- cpdf_setmiterlimit -- Fixe le paramètre miter limit.
- cpdf_setrgbcolor_fill -- Choisit une couleur rgb comme couleur de remplissage.
- cpdf_setrgbcolor_stroke -- Choisit une couleur rgb comme couleur de dessin.
- cpdf_setrgbcolor -- Choisit une couleur rgb comme couleur de dessin et de remplissage.
- cpdf_show_xy -- Affiche un texte à une position.
- cpdf_show -- Imprime un texte à la position courante.
- cpdf_stringwidth -- Retourne la taille de la chaîne.
- cpdf_stroke -- Dessine une ligne le long du chemin.
- cpdf_text -- Imprime un texte avec des options.
- cpdf_translate -- Modifie l'origine du système de coordonnées.
cpdf_add_annotation
Description
void cpdf_add_annotation ( resource pdf_document, float llx, float lly, float urx, float ury, string title, string content, int mode)cpdf_add_annotation() ajoute une note, dont le coin inférieur droit est (llx, lly) et le coin supérieur droit est (urx, ury).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou si il est omis), c'est la valeur par défaut (72) qui est utilisé.
cpdf_add_outline
Description
void cpdf_add_outline ( resource pdf_document, string text)cpdf_add_outline() ajoute un signet à la page courante, avec le texte text qui pointe sur la page courante.
cpdf_arc
Description
void cpdf_arc ( resource pdf_document, float x-koor, float y-koor, float radius, float start, float end, int mode)cpdf_arc() dessine un arc de cercle, dont le centre est au point (x-koor, y-koor) et l'angle est radius, commençant à l'angle start et finissant à l'angle end.
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_circle().
cpdf_begin_text
Description
void cpdf_begin_text ( resource pdf_document)cpdf_begin_text() démarre une section de texte. Elle doit être terminée avec cpdf_end_text().
Voir aussi cpdf_end_text().
cpdf_circle
Description
void cpdf_circle ( resource pdf_document, float x-koor, float y-koor, float radius, int mode)cpdf_circle() dessine un cercle de centre (x-koor, y-koor) et de rayon radius.
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_arc().
cpdf_clip
Description
void cpdf_clip ( resource pdf_document)cpdf_clip() aligne les dessins sur le chemin courant.
cpdf_close
Description
void cpdf_close ( resource pdf_document)cpdf_close() ferme un fichier PDF. Ce doit être la dernière fonction appelée, et elle apparaît même après cpdf_finalize(), cpdf_output_buffer() et cpdf_save_to_file().
Voir aussi cpdf_open().
cpdf_closepath_fill_stroke
(PHP 3>= 3.0.8, PHP 4 )
cpdf_closepath_fill_stroke -- Remplit le chemin, dessine le bord et ferme le chemin.Description
void cpdf_closepath_fill_stroke ( resource pdf_document)cpdf_closepath_fill_stroke() remplit le chemin, dessine le bord et ferme le chemin.
Voir aussi cpdf_closepath(), cpdf_stroke(), cpdf_fill(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill() et cpdf_setrgbcolor().
cpdf_closepath_stroke
(PHP 3>= 3.0.8, PHP 4 )
cpdf_closepath_stroke -- Ferme le fichier et dessine une ligne le long du chemin.Description
void cpdf_closepath_stroke ( resource pdf_document)cpdf_closepath_stroke() est une combinaison de cpdf_closepath() et cpdf_stroke().
Voir aussi cpdf_closepath() et cpdf_stroke().
cpdf_closepath
cpdf_continue_text
Description
void cpdf_continue_text ( resource pdf_document, string text)cpdf_continue_text() imprime le texte text à la ligne suivante.
Voir aussi cpdf_show_xy(), cpdf_text(), cpdf_set_leading() et cpdf_set_text_pos().
cpdf_curveto
Description
void cpdf_curveto ( resource pdf_document, float x1, float y1, float x2, float y2, float x3, float y3, int mode)cpdf_curveto() dessine une courbe de Bezier, entre le point courant et le point (x3, y3), en utilisant les points de contrôle (x1, y1) et (x2, y2).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_moveto(), cpdf_rmoveto(), cpdf_rlineto() et cpdf_lineto().
cpdf_end_text
Description
void cpdf_end_text ( resource pdf_document)cpdf_end_text() termine une section de texte, commencée avec cpdf_begin_text().
Voir aussi cpdf_begin_text().
cpdf_fill_stroke
Description
void cpdf_fill_stroke ( resource pdf_document)cpdf_fill_stroke() remplit l'intérieur du chemin avec la couleur courante, et dessine le chemin.
Voir aussi cpdf_closepath(), cpdf_stroke(), cpdf_fill(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill() et cpdf_setrgbcolor().
cpdf_fill
Description
void cpdf_fill ( resource pdf_document)cpdf_fill() remplit l'intérieur du chemin courant avec la couleur courante.
Voir aussi cpdf_closepath(), cpdf_stroke(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill() et cpdf_setrgbcolor().
cpdf_finalize_page
Description
void cpdf_finalize_page ( resource pdf_document, int page_number)cpdf_finalize_page() termine la page de numéro page_number. cpdf_finalize_page() ne fait qu'une sauvegarde mémoire. Les pages terminées prennent moins de place, mais ne peuvent plus être modifiées.
Voir aussi cpdf_page_init().
cpdf_finalize
Description
void cpdf_finalize ( resource pdf_document)cpdf_finalize() termine un document. Vous devez toujours appeler cpdf_close() après.
Voir aussi cpdf_close().
cpdf_global_set_document_limits
Description
void cpdf_global_set_document_limits ( int maxpages, int maxfonts, int maximages, int maxannotations, int maxobjects)cpdf_global_set_document_limits() permet de fixer plusieurs limites au document PDF. cpdf_global_set_document_limits() doit être appelé avant cpdf_open() pour être effective. Elle fixe les limites de tous les documents ouverts après.
Voir aussi cpdf_open().
cpdf_import_jpeg
Description
int cpdf_import_jpeg ( resource pdf_document, string file_name, float x-koor, float y-koor, float angle, float width, float height, float x-scale, float y-scale, int mode)cpdf_import_jpeg() ouvre une image JPG, enregistré dans le fichier file_name. Le format de l'image doit être JPEG. L'image est placée dans la page courante, aux coordonnées (x-koor, y-koor). L'image subira une rotation d'un angle de angle degrés.
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_place_inline_image().
cpdf_lineto
Description
void cpdf_lineto ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_lineto() dessine une ligne entre le point courant et le point de coordonnées (x-koor, y-koor).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_moveto(), cpdf_rmoveto() et cpdf_curveto().
cpdf_moveto
Description
void cpdf_moveto ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_moveto() fixe le point courant aux coordonnées (x-koor, y-koor).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
cpdf_newpath
Description
void cpdf_newpath ( int pdf_document)cpdf_newpath() commence un nouveau chemin dans le document pdf_document.
cpdf_open
Description
resource cpdf_open ( int compression, string filename)cpdf_open() ouvre un nouveau document PDF. Le premier paramètre compression active ou pas la compression, suivant qu'il vaut 0 ou 1. Le deuxième paramètre, optionnel, choisit le fichier de destination du document. S'il est omis, le document sera écrit en mémoire, et pourra être écrit dans un fichier avec cpdf_save_to_file() ou envoyé à l'affichage avec cpdf_output_buffer().
Note : La valeur retournée sera nécessaire pour les autres fonctions de ClibPDF comme premier paramètre.
La librairie ClibPDF prend le nom de fichier "-" comme synonyme de stdout. Si PHP est compilé comme un module apache, cela ne fonctionnera pas, car la méthode d'envoie des données de ClibPDF ne fonctionne pas avec Apache. Vous pouvez résoudre ce problème en ne fournissant pas de nom de fichier, et en utilisant la fonction cpdf_output_buffer() pour afficher le document PDF.
Voir aussi cpdf_text().
cpdf_output_buffer
Description
void cpdf_output_buffer ( int pdf document)The cpdf_output_buffer() function outputs the pdf document to stdout. The document has to be created in memory which is the case if cpdf_open() has been called with no filename parameter.
See also cpdf_open().
cpdf_page_init
Description
void cpdf_page_init ( int pdf document, int page number, int orientation, float height, float width [, float unit])The cpdf_page_init() function starts a new page with height height and width width. The page has number page number and orientation orientation. orientation can be 0 for portrait and 1 for landscape. The last optional parameter unit sets the unit for the coordinate system. The value should be the number of postscript points per unit. Since one inch is equal to 72 points, a value of 72 would set the unit to one inch. The default is also 72.
See also cpdf_set_current_page().
cpdf_place_inline_image
Description
void cpdf_place_inline_image ( int pdf document, int image, float x-coor, float y-coor, float angle, float width, float height [, int mode])The cpdf_place_inline_image() function places an image created with the php image functions on the page at position (x-coor, y-coor). The image can be scaled at the same time.
The optional parameter mode determines the unit length. If it's 0 or omitted the default unit as specified for the page is used. Otherwise the coordinates are measured in postscript points disregarding the current unit.
See also cpdf_import_jpeg().
cpdf_rect
Description
void cpdf_rect ( int pdf document, float x-coor, float y-coor, float width, float height [, int mode])The cpdf_rect() function draws a rectangle with its lower left corner at point (x-coor, y-coor). This width is set to width. This height is set to height.
The optional parameter mode determines the unit length. If it's 0 or omitted the default unit as specified for the page is used. Otherwise the coordinates are measured in postscript points disregarding the current unit.
cpdf_restore
Description
void cpdf_restore ( resource pdf_document)cpdf_restore() restaure l'environnement sauvé par cpdf_save(). Cette fonction est similaire à la commande postscript grestore. Très pratique quand vous devez faire des translations et rotations sur un objet, mais sans affecter les autres.
Voir aussi cpdf_save().
cpdf_rlineto
Description
void cpdf_rlineto ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_rlineto() dessine une ligne entre le point courant et le point de coordonnées relatives (x-koor, y-koor).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_moveto(), cpdf_rmoveto() et cpdf_curveto().
cpdf_rmoveto
Description
void cpdf_rmoveto ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_rmoveto() fixe le point courant aux coordonnées (x-koor, y-koor), relativement.
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_moveto().
cpdf_rotate_text
Description
void cpdf_rotate_text ( int pdfdoc, float angle)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cpdf_rotate
Description
void cpdf_rotate ( resource pdf_document, float angle)cpdf_rotate() effectue une rotation, d'un angle de angle degrés.
cpdf_save_to_file
Description
void cpdf_save_to_file ( resource pdf_document, string filename)cpdf_save_to_file() écrit un document PDF dans un fichier, s'il a été créé en mémoire. cpdf_save_to_file() n'est pas nécessaire si un nom de fichier a été fourni lors de l'appel à cpdf_open().
Voir aussi cpdf_output_buffer() et cpdf_open().
cpdf_save
Description
void cpdf_save ( resource pdf_document)cpdf_save() sauve l'environnement courant. cpdf_save() est similaire à la commande postscript gsave. Très pratique quand vous devez faire des translations et rotations sur un objet, mais sans affecter les autres.
Voir aussi cpdf_restore().
cpdf_scale
Description
void cpdf_scale ( resource pdf_document, float x-scale, float y-scale)cpdf_scale() modifie l'échelle dans les deux directions.
cpdf_set_action_url
Description
void cpdf_set_action_url ( int pdfdoc, float xll, float yll, float xur, float xur, string url [, int mode])
| Avertissement |
This function is currently not documented, only the argument list is available. |
cpdf_set_char_spacing
Description
void cpdf_set_text_pos ( resource pdf_document, float space)cpdf_set_char_spacing() fixe l'espacement des caractères.
Voir aussi cpdf_set_word_spacing() et cpdf_set_leading().
cpdf_set_creator
Description
void cpdf_set_creator ( string creator)cpdf_set_creator() fixe le créateur d'un document PDF.
Voir aussi cpdf_set_subject(), cpdf_set_title() et cpdf_set_keywords().
cpdf_set_current_page
Description
void cpdf_set_current_page ( resource pdf_document, int page_number)cpdf_set_current_page() fixe la page courante, où toutes les prochaines opérations vont avoir lieu. On peut changer de page jusqu'à ce qu'une page soit terminée avec cpdf_finalize_page().
Voir aussi cpdf_finalize_page().
cpdf_set_font_directories
Description
void cpdf_set_font_directories ( int pdfdoc, string pfmdir, string pfbdir)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cpdf_set_font_map_file
(PHP 4 >= 4.0.6)
cpdf_set_font_map_file -- Sets fontname to filename translation map when using external fontsDescription
void cpdf_set_font_map_file ( int pdfdoc, string filename)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cpdf_set_font
Description
void cpdf_set_font ( resource pdf_document, string font name, float size, string encoding)cpdf_set_font() selectionne la police courante, sa taille et l'encodage. Actuellement, seules les polices postscript sont supportées.
Le dernier paramètre encoding peut prendre les valeurs suivantes : "MacRomanEncoding", "MacExpertEncoding", "WinAnsiEncoding", et "NULL". "NULL" signifie qu'il faut utiliser l'encodage par défaut.
Reportez vous à la doc de ClibPDF, pour plus d'informations, notamment sur les polices asiatiques.
cpdf_set_horiz_scaling
Description
void cpdf_set_horiz_scaling ( resource pdf_document, float scale)cpdf_set_horiz_scaling() fixe l'échelle horizontale du texte à scale %.
cpdf_set_keywords
Description
void cpdf_set_keywords ( string keywords)cpdf_set_keywords() fixe les mots-clé d'un document PDF.
Voir aussi cpdf_set_title(), cpdf_set_creator() et cpdf_set_subject().
cpdf_set_leading
Description
void cpdf_set_leading ( resource pdf_document, float distance)cpdf_set_leading() fixe la distance entre deux lignes. Cela servira si le texte est affiché par cpdf_continue_text().
Voir aussi cpdf_continue_text().
cpdf_set_page_animation
(PHP 3>= 3.0.9, PHP 4 )
cpdf_set_page_animation -- Fixe l'animation de la transition entre les pages.Description
void cpdf_set_page_animation ( resource pdf_document, int transition, float duration)cpdf_set_page_animation() fixe l'animation de la transition entre les pages.
La valeur du paramètre de transition transition peut être :
| 0 pour aucune, |
| 1 pour deux lignes en travers de l'écran, qui révèlent la prochaine page, |
| 2 pour plusieurs lignes en travers de l'écran, qui révèlent la prochaine page, |
| 3 pour une boîte qui révèle la prochaine page, |
| 4 pour une seule ligne en travers de l'écran, qui révèle la prochaine page, |
| 5 pour l'ancienne page qui se dissout |
| 6 pour un effet de dissolution d'un angle à l'autre |
| 7 pour le remplacement simple (par défaut) |
La valeur de duration est le nombre de secondes avant le passage à la page suivante.
cpdf_set_subject
Description
void cpdf_set_subject ( string subject)cpdf_set_subject() fixe le sujet d'un document PDF.
Voir aussi cpdf_set_title(), cpdf_set_creator() et cpdf_set_keywords().
cpdf_set_text_matrix
Description
void cpdf_set_text_matrix ( resource pdf_document, array matrix)cpdf_set_text_matrix() fixe la matrice du texte, qui décrit la transformation appliquée à police.
cpdf_set_text_pos
Description
void cpdf_set_text_pos ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_set_text_pos() Fixe la position du texte pour le prochain appel à cpdf_show().
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisée.
Voir aussi cpdf_show() et cpdf_text().
cpdf_set_text_rendering
Description
void cpdf_set_text_rendering ( resource pdf_document, int mode)cpdf_set_text_rendering() détermines le rendu du texte.
Les valeurs possibles pour mode sont : 0=texte plein, 1=texte stroke, 2=texte plein et stroke, 3=invisible, 4=texte plein et ajouté au chemin, 5=texte stroke et ajouté au chemin, 6=texte plein et stroke et ajouté au chemin, 7=et ajouté au chemin.
cpdf_set_text_rise
Description
void cpdf_set_text_rise ( resource pdf_document, float value)cpdf_set_text_rise() fixe l'élévation du texte à value unités.
cpdf_set_title
Description
void cpdf_set_title ( string title)cpdf_set_title() fixe le titre d'un document PDF.
Voir aussi cpdf_set_subject(), cpdf_set_creator() et cpdf_set_keywords().
cpdf_set_viewer_preferences
Description
void cpdf_set_viewer_preferences ( int pdfdoc, array preferences)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cpdf_set_word_spacing
Description
void cpdf_set_word_spacing ( resource pdf_document, float space)cpdf_set_word_spacing() fixe l'espacement des caractères.
Voir aussi cpdf_set_char_spacing() et cpdf_set_leading().
cpdf_setdash
Description
void cpdf_setdash ( resource pdf_document, float white, float black)cpdf_setdash() fixe le motif de pointillé à white unité de blanc et black unités de noir. Si les deux sont à 0, une ligne pleine est affichée.
cpdf_setflat
Description
void cpdf_setflat ( resource pdf_document, float value)cpdf_setflat() fixe la platitude (flatness), entre 0 et 100.
cpdf_setgray_fill
Description
void cpdf_setgray_fill ( resource pdf_document, float value)cpdf_setgray_fill() remplace le niveau de gris, couleur de remplissage courante, par value.
Voir aussi cpdf_setrgbcolor_fill().
cpdf_setgray_stroke
Description
void cpdf_setgray_stroke ( resource pdf_document, float gray_value)cpdf_setgray_stroke() remplace le niveau de gris, couleur de dessin courante, par value.
Voir aussi cpdf_setrgbcolor_stroke().
cpdf_setgray
(PHP 3>= 3.0.8, PHP 4 )
cpdf_setgray -- Modifie un niveau de gris comme couleur de dessin et de remplissage.Description
void cpdf_setgray ( resource pdf_document, float gray_value)cpdf_setgray_stroke() remplace le niveau de gris, couleur de dessin et de remplissage, par value.
Voir aussi cpdf_setrgbcolor_stroke() et cpdf_setrgbcolor_fill().
cpdf_setlinecap
Description
void cpdf_setlinecap ( resource pdf_document, int value)cpdf_setlinecap() fixe le paramètre linecap à une valeur value entre 0 et 2. 0 = butt end, 1 = round, 2 = projecting square.
cpdf_setlinejoin
Description
void cpdf_setlinejoin ( resource pdf_document, long value)cpdf_setlinejoin() fixe le paramètre linejoin à une valeur value, entre 0 et 2. 0 = miter, 1 = round, 2 = bevel.
cpdf_setlinewidth
Description
void cpdf_setlinewidth ( resource pdf_document, float width)cpdf_setlinewidth() fixe la largeur de ligne à la valeur de width.
cpdf_setmiterlimit
Description
void cpdf_setmiterlimit ( resource pdf_document, float value)cpdf_setmiterlimit() fixe le paramètre "miter limit" à une valeur supérieure ou égale à 1.
cpdf_setrgbcolor_fill
(PHP 3>= 3.0.8, PHP 4 )
cpdf_setrgbcolor_fill -- Choisit une couleur rgb comme couleur de remplissage.Description
void cpdf_setrgbcolor_fill ( resource pdf_document, float red_value, float green_value, float blue_value)cpdf_setrgbcolor_fill() remplace la couleur de remplissage, par la couleur rgb (red_value, green_value, blue_value).
Voir aussi cpdf_setrgbcolor_stroke() et cpdf_setrgbcolor().
cpdf_setrgbcolor_stroke
Description
void cpdf_setrgbcolor_stroke ( resource pdf_document, float red_value, float green_value, float blue_value)cpdf_setrgbcolor_stroke() remplace la couleur de dessin, par la couleur rgb (red_value, green_value, blue_value).
Voir aussi cpdf_setrgbcolor_fill() et cpdf_setrgbcolor().
cpdf_setrgbcolor
(PHP 3>= 3.0.8, PHP 4 )
cpdf_setrgbcolor -- Choisit une couleur rgb comme couleur de dessin et de remplissage.Description
void cpdf_setrgbcolor ( resource pdf_document, float red_value, float green_value, float blue_value)cpdf_setrgbcolor_stroke() remplace la couleur de remplissage et de dessin, par la couleur rgb (red_value, green_value, blue_value).
Voir aussi cpdf_setrgbcolor_stroke() et cpdf_setrgbcolor_fill().
cpdf_show_xy
Description
void cpdf_show_xy ( resource pdf_document, string text, float x-coor, float y-coor [, int mode])cpdf_show_xy() imprime la chaîne text, à la position de coordonnées (x-koor, y-koor). Le dernier paramètre optionnel est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisé.
Note : The function cpdf_show_xy() est identique à cpdf_text() sans les options.
Voir aussi cpdf_text().
cpdf_show
Description
void cpdf_show ( resource pdf_document, string text)cpdf_show() imprime la chaîne text, à la position courante.
Voir aussi cpdf_text(), cpdf_begin_text() et cpdf_end_text().
cpdf_stringwidth
Description
float cpdf_stringwidth ( resource pdf_document, string text)cpdf_stringwidth() retourne la taille de la chaîne text. Une police doit avoir déjà été choisie.
Voir aussi cpdf_set_font().
cpdf_stroke
Description
void cpdf_stroke ( resource pdf_document)cpdf_stroke() dessine une ligne le long du chemin.
Voir aussi cpdf_closepath() et cpdf_closepath_stroke().
cpdf_text
Description
void cpdf_text ( resource pdf_document, string text, float x-coor, float y-coor [, int mode [, float orientation [, int alignmode]]])cpdf_text() imprime le text text à la position de coordonnées (x-koor, y-koor). Le paramètre mode est une unité de longueur. Si il prend la valeur de 0 (ou si il est omis), c'est la valeur par défaut (72) qui est utilisé.
Le paramètre optionel orientation est un angle de rotation du texte, en degrés. Le paramètre optionnel alignmode détermine l'alignement du texte. Reportez vous à la doc de ClibPDF, pour les valeurs possibles.
Voir aussi cpdf_show_xy().
cpdf_translate
Description
void cpdf_translate ( resource pdf_document, float x-koor, float y-koor, int mode)cpdf_translate() modifie l'origine du système de coordonnées en plaçant l'origine aux coordonnées (x-koor, y-koor).
Le paramètre mode est une unité de longueur. S'il prend la valeur de 0 (ou s'il est omis), c'est la valeur par défaut (72) qui est utilisé.
XI. Crack
Ces focntions vous permettent d'utiliser la librairie CrackLib, pour tester la robustesse de vos mots de passe. Pour utiliser cette fonction, vous devez compiler PHP avec l'extension Crack, en utilisant l'option de compilation --with-crack[=DIR].
Plus d'informations concernant la librairie CrackLib sont disponibles à http://www.users.dircon.co.uk/~crypto/.
Cracklib est pratique pour tester la robustesse d'un mot de passe. Elle teste la taille, les majuscules et minusculles, et effectue des recherches dans le dictionnaire CrackLib. CrackLib donne aussi des conseil pour reforcer vos mots de passe.
Cet exemple montre coment ouvrir un dictionnaire CrackLib, tester un mot de passe, lire le diagnostic et refermer le dictionnaire.
Exemple 1. Exemple avec CrackLib
|
Note : If crack_check() retourne TRUE, crack_getlastmessage() retournera le message 'strong password' (mot de passe robuste).
- Table des matières
- crack_check -- Effectue une vérification de mot de passe
- crack_closedict -- Referme le dictionnaire CrackLib
- crack_getlastmessage -- Retourne le message de diagnostic
- crack_opendict -- Ouvre un nouveau dictionnaire CrackLib dictionary
crack_check
Description
bool crack_check ( [resource dictionary, string password])crack_check() retourne TRUE si password est robuste, et FALSE sinon.
| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
crack_check() effectue d'obscures vérfications sur le mot de passe password fourni, avec le dictionnaire dictionary. Si dictionary est omis, le dernier dictionnaire ouvert sera utilisé.
crack_closedict
Description
bool crack_closedict ( [resource dictionary])Retourne TRUE en cas de succès, FALSE en cas d'échec.
| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
crack_closedict() ferme le dictionnaire dictionary. Si dictionary n'est pas spécifié, le dictionnarie courant est fermé.
crack_getlastmessage
Description
string crack_getlastmessage ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
crack_getlastmessage() retourne le diagnotic obtenu lors de la dernière vérification.
crack_opendict
Description
resource crack_opendict ( string dictionary)crack_opendict() retourne une ressource représentant un dictionnaire, en cas de succès, et FALSE sinon.
| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
crack_opendict() ouvre le dictionnarie CrackLib dictionary, afin de pouvoir l'utiliser avec crack_check().
Note : Un seul dictionnaire peut être utilisé en même temps.
Voir aussi crack_check() et crack_closedict().
XII. CURL
PHP supporte libcurl, une librairie créée par Daniel Stenberg, qui vous permet de vous connecter de communiquer avec de nombreux serveurs, grâce à de nombreux protocoles. libcurl supporte actuellement les protocoles suivants : http, https, ftp, gopher, telnet, dict, file, et ldap. libcurl supporte aussi les certificats HTTPS, les POST HTTP, PUT HTTP, le chargement par FTP (ce qui peut être fait par l'extension FTP), les chargement par formulaire HTTP, les proxies, les cookies et l'authentification par mot de passe et nom de compte.
Pour pouvoir utiliser les fonctions CURL, vous devez installer le package CURL. PHP requiert la version CURL 7.0.2-beta ou plus récente. PHP ne fonctionnera pas avec une version inférieure à la version 7.0.2-beta.
Pour utiliser CURL depuis les scripts PHP, vous devez aussi compiler PHP avec l'option --with-curl[=DIR] où DIR est le chemin jusqu'au dossier contenant les dossiers lib et include. Dans le dossier include il doit se trouver un dossier appelé curl, qui contient notamment les fichiers easy.h et curl.h. Il doit aussi se trouver un fichier nommé libcurl.a dans le dossier lib.
Une fois que vous avez compilé PHP avec le support CURL, vous pouvez commencer à l'exploiter avec vos scripts PHP. Le principe de fonctionnement est d'initialiser une session CURL avec curl_init(), puis de choisir toutes vos options de transfert avec curl_exec() et de finir votre session avec curl_close(). Voici un exemple d'utilisation des fonctions CURL, qui récupère la page principale de PHP :
- Table des matières
- curl_close -- Ferme une session CURL
- curl_errno -- Return an integer containing the last error number
- curl_error -- Return a string containing the last error for the current session
- curl_exec -- Exécute une session CURL
- curl_getinfo -- Get information regarding a specific transfer
- curl_init -- Initialise une session CURL
- curl_setopt -- Modifie une option de transfert CURL
- curl_version -- Retourne la version courante de CURL
curl_close
Description
void curl_close ( int ch)curl_close() ferme une session CURL et libère toutes les ressources réservées. L'identifiant CURL, ch, est aussi effacé.
curl_errno
Description
int curl_errno ( resource ch)
| Avertissement |
This function is currently not documented, only the argument list is available. |
curl_error
Description
string curl_error ( resource ch)
| Avertissement |
This function is currently not documented, only the argument list is available. |
curl_exec
Description
boolean curl_exec ( resource ch)Cette fonction doit être appelée après l'initialisation et le paramètrage d'une session CURL. Son but est simplement d'éxécuter la session ch.
curl_getinfo
Description
string curl_getinfo ( resource ch, int opt)
| Avertissement |
This function is currently not documented, only the argument list is available. |
curl_init
Description
resource curl_init ( [string url])curl_init() initialise une nouvelle session et retourne un identifiant de session CURL, à utiliser avec les fonctions curl_setopt(), curl_exec() et curl_close(). Si le paramètre optionnel url est fourni, alors CURLOPT_URL prendra cette valeur. Vous pouvez manuellement fixer cette valeur avec la fonction curl_setopt().
Voir aussi : curl_close(), curl_setopt().
curl_setopt
Description
boolean curl_setopt ( resource ch, string option, mixed value)curl_setopt() fixe les options de transfert de la session CURL identifiée par ch. option est le nom de l'option à fixer, et value est sa valeur.
value doit être de type "long" pour les options suivantes (spécifiée par option) :
CURLOPT_INFILESIZE: Lorsque vous téléchargez un fichier sur un site distant, cette option sert à indiquer à PHP la taille maximale du fichier attendu.
CURLOPT_VERBOSE: Choisissez une valeur non nulle pour que CURL vous affiche tous les événements.
CURLOPT_HEADER: Choisissez une valeur non nulle pour que CURL inclut l'en-tête dans la valeur de retour.
CURLOPT_NOPROGRESS: Choisissez une valeur non nulle pour que PHP n'affiche pas l'état des transferts CURL.
Note : PHP choisit automatiquement une valeur non nulle. Ne changez cette valeur que le temps du débuggage.
CURLOPT_NOBODY: Choisissez une valeur non nulle pour que le corps du transfert ne soit pas inclus dans la valeur de retour.
CURLOPT_FAILONERROR: Choisissez une valeur non nulle pour que PHP traite silencieusement les codes HTTP supérieurs à 300. Le comportement par défaut est de retourner la page normalement, en ignorant ce code.
CURLOPT_UPLOAD: Choisissez une valeur non nulle pour que PHP prépare un chargement.
CURLOPT_POST: Choisissez une valeur non nulle pour que PHP fasse un HTTP POST. Un POST est un encodage normal "application/x-www-from-url", utilisé couramment par les formulaires HTML.
CURLOPT_FTPLISTONLY: Choisissez une valeur non nulle pour que PHP ne fasse que lister les noms d'un dossier FTP.
CURLOPT_FTPAPPEND: Choisissez une valeur non nulle pour que PHP concatène le fichier distant, plutôt que de l'écraser.
CURLOPT_NETRC: Choisissez une valeur non nulle pour que PHP scanne votre fichier ~./netrc et utilise votre nom de compte et mot de passe sur le site distant que vous souhaitez contacter.
CURLOPT_FOLLOWLOCATION: Choisissez une valeur non nulle pour suivre toutes les en-têtes "Location: " que le serveur envoie dans les en-têtes HTTP (notez que cette fonction est récursive, et que PHP suivra toutes les en-têtes "Location: " qu'il trouvera).
CURLOPT_PUT: Choisissez une valeur non nulle pour que pour chargement se fasse par HTTP PUT. Le fichier à charger doit être fixé avec les options CURLOPT_INFILE et CURLOPT_INFILESIZE.
CURLOPT_MUTE: Choisissez une valeur non nulle pour que PHP soit totalement silencieux concernant toutes les fonctions CURL.
CURLOPT_TIMEOUT: Passez un entier "long" comme paramètre qui représente le temps maximum d'exécution de la fonction CURL.
CURLOPT_LOW_SPEED_LIMIT: Passez un entier long qui représente la vitesse minimale en octets par secondes en dessous de laquelle, et pendant CURLOPT_LOW_SPEED secondes, PHP considèrera qu'elle est trop lente, et annulera le transfert.
CURLOPT_LOW_SPEED_TIME: Passez un entier "long" qui représente le temps en secondes, qui, si la vitesse de transfert reste en dessous de CURLOPT_LOW_SPEED_LIMIT, PHP considèrera que la connexion est trop lente, et l'annulera.
CURLOPT_RESUME_FROM: Passez un entier "long", qui représente l'offset, en octets, à partir duquel vous voulez commencer le transfert.
CURLOPT_SSLVERSION: Passez un entier "long" qui contient la version de SSL (2 ou 3) à utiliser. Par défaut, PHP essaiera de le déterminer par lui-même, bien que dans certains cas, il vous faudra le faire manuellement.
CURLOPT_TIMECONDITION: Passez un entier "long" qui définit comment CURLOPT_TIMEVALUE est utilisé. Vous pouvez choisir entre les valeurs TIMECOND_IFMODSINCE ou TIMECOND_ISUNMODSINCE. C'est une fonctionnalité HTTP.
CURLOPT_TIMEVALUE: Passez un entier "long" qui représente le temps en secondes depuis le 1er janvier 1970. Cette valeur sera utilisée comme spécifié dans l'option CURLOPT_TIMEVALUE. Par défaut, TIMECOND_IFMODSINCE sera utilisé.
value doit être une chaîne de caractères pour les valeurs suivantes de option
CURLOPT_URL: L'URL que PHP va récupérer. Vous pouvez aussi choisir cette valeur lors de l'appel à curl_init().
CURLOPT_USERPWD: Passez une chaîne de caractères au format [nom]:[mot de passe], pour que PHP l'utilise lors de la connexion.
CURLOPT_PROXYUSERPWD: Passez une chaîne de caractères au format [nom]:[mot de passe ], pour que PHP l'utilise lors de la connexion à un proxy HTTP.
CURLOPT_RANGE: Passez une chaîne de caractères qui représente la plage de valeur que vous désirez. Elle est au format "X-Y", où les valeurs de X ou Y peuvent être omises. Le transfert HTTP supporte aussi plusieurs intervalles, séparé par des virgules : X-Y,N-M.
CURLOPT_POSTFIELDS: Passez une chaîne de caractères qui contient toutes les données à passer lors d'une opération de HTTP POST.
CURLOPT_REFERER: Passez une chaîne de caractères qui contient l'en-tête de "REFERER", utilisé lors d'une requête HTTP.
CURLOPT_USERAGENT: Passez une chaîne de caractères qui contient l'en-tête "user-agent" utilisé dans une requête HTTP.
CURLOPT_FTPPORT: Passez une chaîne de caractères qui désignera l'adresse IP utilisée pour l'instruction FTP "PORT". L'instruction POST indique au serveur distant de se connecter cette adresse IP. La chaîne peut être une adresse IP, un nom d'hôte, un nom d'interface réseau (sous UNIX), ou juste '-', pour utiliser les IP par défaut du système.
CURLOPT_COOKIE: Passez une chaîne de caractères qui contiendra le contenu du cookie, à transmettre dans l'en-tête HTTP.
CURLOPT_SSLCERT: Passez une chaîne de caractères qui contiendra le nom de fichier du certificat, au format PEM.
CURLOPT_SSLCERTPASSWD: Passez une chaîne de caractères qui contient le mot de passe nécessaire pour utiliser le certificat CURLOPT_SSLCERT.
CURLOPT_COOKIEFILE: Passez une chaîne de caractères qui contiendra le nom du fichier contenant les données de cookie. Le fichier de cookie peut être au format Netscape, ou simplement des en-têtes HTTP écrites dans un fichier.
CURLOPT_CUSTOMREQUEST: Passez une chaîne de caractères qui sera utilisé à la place de GET ou HEAD lors des requêtes HTTP. Cette commande est pratique pour effectuer un DELETE, ou une autre commande HTTP exotique.
Note : N'utilisez pas cette commande sans vous assurer que le serveur l'accepte.
Les options suivantes requièrent un pointeur de fichier, qui est obtenu avec la fonction fopen() :
CURLOPT_FILE: Le fichier de sortie de votre transfert. Par défaut, STDOUT.
CURLOPT_INFILE: Le fichier d'entrée de votre transfert.
CURLOPT_WRITEHEADER: Le fichier de destination de l'en-tête de la sortie du transfert.
CURLOPT_STDERR: Le fichier d'erreurs.
curl_version
XIII. Paiement Cybercash
Ces fonctions ne sont disponibles que si PHP a été compilé avec l'option --with-cybercash=[DIR]. Ces fonctions ont été ajoutées dans PHP 4.
- Table des matières
- cybercash_base64_decode --
- cybercash_base64_encode --
- cybercash_decr --
- cybercash_encr --
cybercash_base64_decode
cybercash_base64_encode
cybercash_decr
Description
array cybercash_decr ( string wmk, string sk, string inbuff)cybercash_decr() retourne un tableau associatif, contenant les éléments "errcode" et, si "errcode" vaut FALSE, "outbuff" (string), "outLth" (long) et "macbuff" (string).
cybercash_encr
XIV. CyberMUT : Crédit Mutuel
Cette extension vous permet de traiter des transactions de cartes de crédits, avec le système due Crédit Mutuel : CyberMUT (http://www.creditmutuel.fr/centre_commercial/vendez_sur_internet.html).
CynerMUT est un système de paiement français, proposé par le Crédit Mutuel. Si vous n'êtes pas résidants français, ces fonctions ne vous seront pas utiles.
Cette extension n'est disponible que si PHP a été compilé par l'option --with-cybermut[=DIR], où DIR est le dossier qui contient les fichiers libcm-mac.a et cm-mac.h. Vous aurez besoin du SDK approprié, qui vous est fournit après vous êtes inscrit à CyberMUT (via le web, ou à votre agence la plus proche).
L'utilisation de ces fonctions est presque identique aux fonctions originales, hormis le fait que les fonctions cybermut_creerformulairecm() et cybermut_creerreponsecm(), qui sont retournées directement par des fonctions PHP, au lieu d'être passées par référence aux fonctions originales.
Ces fonctions ont été ajoutée en 4.0.6.
Note : Ces fonctions ne font que fournis un moyen d'utiliser le SDK CyberMUT. Lisez attentivement le "CyberMUT Developers Guide" pour plus de détails sur les parmètres nécessaires.
- Table des matières
- cybermut_creerformulairecm -- Génère un formulaire HTML de paiement
- cybermut_creerreponsecm -- Génère un accusé de réception de confirmation de paiement
- cybermut_testmac -- Vérifie le message de confirmation
cybermut_creerformulairecm
Description
string cybermut_creerformulairecm ( string url_CM, string version, string TPE, string montant, string ref_commande, string texte_libre, string url_retour, string url_retour_ok, string url_retour_err, string langue, string code_societe, string texte_bouton)cynermut_creerformulairecm() génère un formulaire HTML, de demande de paiement.
Exemple 1. Première étape du paiment (équivalent à cgi1.c)
|
Voir aussi cybermut_testmac() et cybermut_creerreponsecm().
cybermut_creerreponsecm
(PHP 4 >= 4.0.5)
cybermut_creerreponsecm -- Génère un accusé de réception de confirmation de paiementDescription
string cybermut_creerreponsecm ( string phrase)cybermut_creerreponsecm() retourne une chaîne contenant le message d'accusé de reception.
Le paramètre vaut "OK" si le message de confirmation du paiement a été correctement indentifié par cybermut_testmac(). Tout autre chaîne doit être considéré comme une erreur de traitement.
Voir aussi cybermut_creerformulairecm() et cybermut_testmac().
cybermut_testmac
Description
bool cybermut_testmac ( string code_MAC, string version, string TPE, string cdate, string montant, string ref_commande, string texte_libre, string code-retour)cybermut_testmac() s'assure qu'il n'y a pas de données parasites dans le message de confirmation recu. Attention aux paramètres code-retour and texte-libre, qui ne peuvent pas être utilisés directement, car ils contienent des tirets dans leur nom. Vous devez utilisez la syntaxe suivante :
<?php $code_retour=$HTTP_GET_VARS["code-retour"]; $texte_libre=$HTTP_GET_VARS["texte-libre"]; ?> |
Exemple 1. Deuxième étape de paiement (équivalent à cgi2.c)
|
Voir aussi cybermut_creerformulairecm() et cybermut_creerreponsecm().
XV. Administration Cyrus IMAP
- Table des matières
- cyrus_authenticate -- S'identifie sur un serveur Cyrus IMAP
- cyrus_bind -- Ajoute une fonction de callback sur une connexion Cyrus IMAP
- cyrus_close -- Ferme la connexion à un serveur Cyrus IMAP
- cyrus_connect -- Se connecte à un serveur Cyrus IMAP
- cyrus_query -- Envoye une requête à un serveur Cyrus IMAP
- cyrus_unbind -- Supprime une fonction de callback sur une connexion Cyrus IMAP
cyrus_authenticate
Description
bool cyrus_authenticate ( resource connection [, string mechlist [, string service [, string user [, int minssf [, int maxssf]]]]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
cyrus_bind
Description
bool cyrus_bind ( resource connection, array callbacks)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cyrus_close
Description
bool cyrus_close ( resource connection)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cyrus_connect
Description
resource cyrus_connect ( [string host [, string port [, int flags]]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
cyrus_query
Description
bool cyrus_query ( resource connection, string query)
| Avertissement |
This function is currently not documented, only the argument list is available. |
cyrus_unbind
XVI. Caractères
Ces fonctions vérifient si un caractère ou une chaîne de caractères font partie d'une certaine classe de caractères, en fonction de la configuration locale.
Appelée avec un argument de type entier, ces fonctions se comportent exactement comme le équivalent en langage C.
Appelée avec un argument de type chaîne, elles vérifieront chaque caractère de la chaîne, et ne retourneront TRUE que si chaque caractère de la chaîne satisfait les critères requis.
Tout autre type d'argument (autre que chaîne ou entier) génère une erreur, et retourne FALSE immédiatement.
| Avertissement |
Ces fonctions ont été ajoutée en PHP 4.0.4, et leur nom peut changer dans un futur proche. Les suggestions actuelles sont : ctype_issomething() au lieu de ctype_somthing ou encore d'en faire une partie ext/standard et utiliser ainsi leur nom en langage C, même si cela peut conduire à des confusions entre isset() et is_sometype. |
- Table des matières
- ctype_alnum -- Vérifie qu'un caractère est alpha-numérique
- ctype_alpha -- Vérifie qu'un caractère est alphabétique
- ctype_cntrl -- Vérifie qu'un caractère est un caractère de contrôle
- ctype_digit -- Vérifie qu'un caractère est numérique
- ctype_graph -- Vérifie qu'un caractère est imprimable (sauf " ", espace)
- ctype_lower -- Vérifie qu'un caractère est en minuscule
- ctype_print -- Vérifie qu'un caractère est imprimable
- ctype_punct -- Vérifie qu'un caractère est imprimable, sans être ni un espace, ni un caractère alpha-numérique
- ctype_space -- Vérifie qu'un caractère est caractère blanc (espace, tabulation...)
- ctype_upper -- Vérifie qu'un caractère est en majuscule
- ctype_xdigit -- Vérifie qu'un caractère représente un nombre héxadécimal
ctype_alnum
ctype_alpha
ctype_cntrl
ctype_digit
ctype_graph
ctype_lower
ctype_print
ctype_punct
(PHP 4 >= 4.0.4)
ctype_punct -- Vérifie qu'un caractère est imprimable, sans être ni un espace, ni un caractère alpha-numériquectype_space
ctype_upper
ctype_xdigit
XVII. DBA
Ces fonctions sont l'interface avec les bases de type Berkeley.
C'est une couche générale pour plusieurs bases de données sur fichiers. En tant que tel, les fonctionnalités sont limitées à une partie des fonctionnalités des bases de données modernes, comme Sleepycat Software's DB2 (A ne pas confondre avec IBM's DB2 software, qui fonctionne avec ODBC).
Le comportement de certaines fonctions dépends de la base de données utilisée. Par exemple dba_optimize() et dba_sync() n'auront pas le même effet d'une base à l'autre.
Lors de l'utilisation de la fonction dba_open() ou de dba_popen(), une des librairies suivante doit être fournie comme argument. La liste complète des librairies supportées par votre configuration est disponible avec la fonction phpinfo(). (Pour ajouter le support de l'une de ces librairies, ajouter l'option de configuration --with-XXXX).
Tableau 1. Liste des librairies DBA
| Librairie | Notes |
|---|---|
| dbm | Dbm est la plus ancienne des base de données de type Berkeley. Il vaut mieux l'éviter si possible. Les fonctions de compatibilités codées dans DB2 et gdbm ne sont pas supportées, car elles ne sont compatibles qu'au niveau du code source, et ne peuvent pas gérer le format dbm originel. ( --with-dbm). |
| ndbm | ndbm est un nouveau type de dbm plus flexible. Il a cependant la majorité des limitations du genre. ( --with-ndbm). |
| gdbm | gdbm est la base dbm GNU. ( --with-gdbm). |
| db2 | db2 est DB2 de Sleepycat Software. Elle se décrit comme un "ensemble d'outils qui fournissent une base de données performante, tant pour les applications indépendantes que pour le client/serveur". ( --with-db2). |
| db3 | DB3 est le DB3 de Sleepycat Software. ( --with-db3). |
| cdb | cdb est "un package rapide, robuste, léger, pour créer et lire des bases de données constantes". C'est l'auteur de qmail qui l'a écrit, et elle est disponible ici. Puisque c'est une base constante, elle ne supporte que la lecture. (--with-cdb). |
DBA gère les données binaires, et n'a pas de limites arbitraires. Elle hérite de toutes les limites de la base sous-jacentes.
Toutes les bases de données sur fichiers doivent fournir un moyen de changer le mode d'accès au fichier d'une base, et si possible, de toutes les bases. Le mode d'accès est généralement passé en 4ème argument à dba_open() ou dba_popen().
Vous pouvez accéder à toutes les entrées d'une base d'une manière linéaire, avec les fonctions dba_firstkey() et dba_nextkey(). Vous ne devez pas modifier une base lorsque vous la traversez ainsi.
Exemple 2. Passer en revue une base
|
- Table des matières
- dba_close -- Ferme une base.
- dba_delete -- Efface une entrée.
- dba_exists -- Vérifie qu'une clé existe.
- dba_fetch -- Lit les données liées à une clé.
- dba_firstkey -- Lit la première clé.
- dba_insert -- Insère une entrée.
- dba_nextkey -- Lit la clé suivante.
- dba_open -- Ouvre une base de données.
- dba_optimize -- Optimise une base.
- dba_popen -- Ouvre une connexion persistante à une base de données.
- dba_replace -- Remplace ou insère une entrée.
- dba_sync -- Synchronise une base de données.
dba_close
Description
void dba_close ( resource handle)dba_close() ferme le lien établi avec la base et libère toutes les ressources de handle.
handle est un identifiant de base, retourné par dba_open().
dba_close() ne retourne aucune valeur.
Voir aussi dba_open() et dba_popen().
dba_delete
Description
bool dba_delete ( string key, resource handle)dba_delete() efface l'entrée spécifiée par la clé key, dans la base identifiée par handle.
key est la clé de l'entrée à effacer.
handle est un identifiant de lien, retourné par dba_open().
dba_delete() retourne TRUE ou FALSE, si l'entrée est effacée, ou pas effacée, respectivement.
Voir aussi dba_exists(), dba_fetch(), dba_insert() et dba_replace()
dba_exists
Description
boolean dba_exists ( string key, resource handle)dba_exists() vérifie si la clé key existe dans la base identifiée par handle.
key est la clé qui doit être vérifiée.
handle est un identifiant de base, retourné par dba_open().
dba_exists() retourne TRUE ou FALSE, si la clé est trouvée, ou pas, respectivement.
Voir aussi dba_fetch(), dba_delete(), dba_insert() et dba_replace().
dba_fetch
Description
string dba_fetch ( string key, resource handle)dba_fetch() lit les données spécifiée par la clé key dans la base identifiée par handle.
key est la clé dont on veut lire les données.
handle est un identifiant de base, retourné par dba_open().
dba_fetch() retourne la chaîne associée ou FALSE, si la paire clé/valeur n'a pas été trouvée.
Voir aussi dba_exists(), dba_delete(), dba_insert() et dba_replace().
dba_firstkey
Description
string dba_firstkey ( resource handle)dba_firstkey() retourne la première clé de la base de données spécifiée par handle et y place le pointeur interne de clé. Cela permettra de traverser la base.
handle est un identifiant de base, retourné par dba_open().
dba_firstkey() retourne la clé, ou FALSE, suivant que la première clé existe ou pas.
Voir aussi dba_nextkey() et l'exemple 2 de l'introduction DBA.
dba_insert
Description
boolean dba_insert ( string key, string value, resource handle)dba_insert() insère l'entrée décrite par la clé key et la valeur value dans la base spécifiée par handle. Si une entrée aveec la même clé key existe déjà, l'insertion échouera.
key est la clé de la valeur à insérer.
value est la valeur à insérer.
handle est un identifiant de base, retourné par dba_open().
dba_insert() retourne TRUE ou FALSE, suivant que l'insertion a réussi ou échoué.
Voir aussi dba_exists(), dba_delete(), dba_fetch() et dba_replace().
dba_nextkey
Description
string dba_nextkey ( resource handle)dba_nextkey() retourne la clé suivante, dans la base identifiée par handle et incrémente le pointeur de clé.
handle est un identifiant de base, retourné par dba_open().
dba_nextkey() retourne la clé, ou FALSE en cas d'échec.
Voir aussi dba_firstkey().
dba_open
Description
int dba_open ( string path, string mode, string handler [, mixed ...])dba_open() établit une connexion à la base repérée par path avec le mode mode et l'identifiant handler.
pathest le chemin sur votre machine.
mode 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 est le nom de l'identifiant qui sera utilisé pour accéder à path. Il est passé à dba_popen().
Voir aussi dba_popen() et dba_close().
dba_optimize
Description
boolean dba_optimize ( resource handle)dba_optimize() optimise la base de données identifiée par handle.
handle est un identifiant de base retourné par dba_open().
dba_optimize() retourne TRUE ou FALSE, suivant que l'optimisation a réussi ou échoué.
Voir aussi dba_sync().
dba_popen
Description
int dba_popen ( string path, string mode, string handler [, mixed ...])dba_popen() établit une connexion persistante à la base repérée par path avec le mode mode, en utilisant l'identifiant handler.
path est le chemin sur votre machine.
mode 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 est le nom de l'identifiant qui sera utilisé pour accéder à path. Il est passé à dba_popen().
dba_popen() retourne un identifiant positif, ou FALSE, suivant que la base a été ouverte, ou que l'accès a échoué.
Voir aussi dba_open() et dba_close().
dba_replace
Description
boolean dba_replace ( string key, string value, resource handle)dba_replace() remplaces ou insère une entrée, pour la clé key et avec la valeur value dans la base identifiée par handle.
key est la clé qui va être insérée.
value est la valeur qui va être insérée.
handle est un identifiant de base retourné par dba_open().
dba_replace() retourne TRUE ou FALSE, suivant que l'opération réussit ou échoue.
Voir aussi dba_exists(), dba_delete(), dba_fetch() et dba_insert().
dba_sync
Description
boolean dba_sync ( resource handle)dba_sync() synchronise la base de données spécifiée par handle. Si accepté, cela va probablement lancer une opération de réécriture physique du fichier.
handle est un identifiant de base retourné par dba_open().
dba_sync() retourne TRUE ou FALSE, si la synchronisation réussi, ou échoue, respectivement.
Voir aussi dba_optimize().
XVIII. Dates et heures
- Table des matières
- checkdate -- Valide une date/heure.
- date -- Formate une date/heure locale
- getdate -- Retourne la date/heure
- gettimeofday -- Retourne l'heure actuelle
- gmdate -- Formate une date/heure GMT/CUT.
- gmmktime -- Retourne le timestamp UNIX d'une date GMT.
- gmstrftime -- Formate une date/heure GMT/CUT en fonction des paramétrages locaux.
- localtime -- Lit l'heure locale
- microtime -- Retourne le timestamp UNIX actuel avec microsecondes.
- mktime -- Retourne le timestamp UNIX d'une date.
- strftime -- Formate une date/heure locale avec les options locales.
- strtotime -- Transforme un texte anglais en timestamp
- time -- Retourne le timestamp UNIX actuel.
checkdate
Description
int checkdate ( int month, int day, int year)checkdate() retourne TRUE si la date représentée par le jour day, le mois month et l'année year est valide, et sinon FALSE. Notez bien que l'ordre des arguments n'est pas l'ordre français. La date est considérée comme valide si :
L'année est comprise entre entre 1 et 32767 inclus. (pour les versions antérieures à PHP 4.0.3, les années inférieures à 1 étaient aussi valides).
Le mois est compris entre 1 et 12 inclus
Le jour est compris dans l'intervalle de dates du mois. Les années bissextiles sont prises en compte.
date
Description
string date ( string format [, int timestamp])date() retourne une date sous forme d'une chaîne, au format donné par la chaîne format. La date est fournie par le paramètre timestamp, sous la forme d'un timestamp. Par défaut, la date courante est utilisée.
Note : L'intervalle de validité d'un timestamp va généralement du Vendredi 13 Décembre 1901 20:45:54 GMT au Mardi 19 Janvier 2038 03:14:07 GMT. (Ces dates correspondent aux valeurs minimales et maximales des entiers 32 bits non-signés).
Pour générer un timestamp à partir d'une représentation de date, pour pouvez utiliser la fonction strtotime(). De plus, certaines bases de données disposent de fonctions pour convertir leurs propres formats de date en timestamps (comme par exemple, MySQL et sa fonction UNIX_TIMESTAMP()).
Les caractères suivants sont utilisés pour spécifier le format :
a - "am" (matin) ou "pm" (après-midi)
A - "AM" (matin) ou "PM" (après-midi)
B - Heure Internet Swatch
d - Jour du mois, sur deux chiffres (éventuellement avec un zéro) : "01" à "31"
D - Jour de la semaine, en trois lettres (et en anglais) : par exemple "Fri" (pour Vendredi)
F - Mois, textuel, version longue; en anglais, i.e. "January" (pour Janvier)
g - Heure, au format 12h, sans les zéros initiaux i.e. "1" à "12"
G - Heure, au format 24h, sans les zéros initiaux i.e. "0" à "23"
h - Heure, au format 12h, "01" à "12"
H - heure, au format 24h, "00" à "23"
i - Minutes; "00" à "59"
I (i majuscule) - "1" si l'heure d'été est activée, "0" si l'heure d'hiver .
j - Jour du mois sans les zéros initiaux: "1" à "31"
l - ('L' minuscule) - Jour de la semaine, textuel, version longue; en anglais, i.e. "Friday" (pour Vendredi)
L - Booléen pour savoir si l'année est bissextile ("1") ou pas ("0")
m - Mois; i.e. "01" à "12"
M - Mois, en trois lettres (et en anglais) : par exemple "Apr" (pour Avril)
n - Mois sans les zéros initiaux; i.e. "1" à "12"
O - Différence d'heures avec l'heure de Greenwich, exprimée en heures; i.e. "+0200"
r - Format de date RFC 822; i.e. "Thu, 21 Dec 2000 16:01:07 +0200" (ajouté en PHP 4.0.4)
s - Secondes; i.e. "00" à "59"
S - Suffixe ordinal d'un nombre, en anglais, sur deux lettres : i.e. "th", "nd"
t - Nombre de jours dans le mois donné, i.e. "28" à "31"
T - Fuseau horaire de la machine ; i.e. "MET"
U - Secondes depuis une époque
w - Jour de la semaine, numérique, i.e. "0" (Dimanche) to "6" (Samedi)
Y - Année, 4 chiffres; i.e. "1999"
y - Année, 2 chiffres; i.e. "99"
z - Jour de l'année; i.e. "0" à "365"
Z - Décalage horaire en secondes (i.e. "-43200" à "43200")
Vous pouvez faire afficher un caractère spécial dans la chaîne de format en le protégeant par un anti-slash. Si le caractère est lui-même une séquence incluant un anti-slash, vous devrez protéger aussi l'anti-slash.
Il est possible d'utiliser date() et mktime() ensemble pour générer des dates dans le futur ou dans le passé.
Exemple 3. Exemples avec date() et mktime()
|
Note : Cette méthode est plus sÛre que simplement ajouter ou retrancher le nombre de secondes dans une journée ou un mois à un timestamp, à cause des heures d'hivers et d'été.
Voici maintenant quelques exemples de formatage avec date(). Notez que vous devriez échapper tous les autres caractères, car s'ils ont une signification spéciale, ils risquent de produire des effets secondaires indésirables. Notez aussi que les versions futures de PHP peuvent attribuer une signification à des lettres qui sont actuellement inertes. Lorsque vous échappez les caractères, pensez à utiiser des guillemets simples, pour que les séquences \n ne deviennent pas des nouvelles lignes.
Exemple 4. Formatage avec date()
|
Pour formater des dates dans d'autres langues, utilisez les fonctions setlocale() et strftime().
Voir aussi getlastmod(), time(), strftime(), gmdate() et mktime().
getdate
Description
array getdate ( [int timestamp])getdate() retourne un tableau associatif contenant les informations de date et d'heure du timestamp timestamp (lorsqu'il est fourni), avec les champs suivants :
"seconds" - secondes
"minutes" - minutes
"hours" - heures
"mday" - jour du mois
"wday" - jour de la semaine, numérique. 0: dimanche jusqu'à 6: samedi
"mon" - mois, numérique
"year" - année, numérique
"yday" - jour de l'année, numérique; i.e. "299"
"weekday" - jour de la semaine, texte complet (en anglais); i.e. "Friday"
"month" - mois, texte complet (en anglais); i.e. "January"
gettimeofday
Description
array gettimeofday ( void)gettimeofday() est une interface vers gettimeofday(2). Elle retourne un tableau associatif qui contient les informations retournées par le système :
"sec" - secondes
"usec" - microsecondes
"minuteswest" - minutes de décalage par rapport à Greenwich, vers l'Ouest.
"dsttime" - type de correction dst
gmdate
Description
string gmdate ( string format [, int timestamp])gmdate() est identique à la fonction date(), hormis le fait que le temps retourné est GMT (Greenwich Mean Time) Par exemple, en Finlande (GMT +0200), la première ligne ci-dessous affiche "Jan 01 1998 00:00:00", tandis que la seconde "Dec 31 1997 22:00:00".
Voir aussi date(), strftime(), mktime() et gmmktime().
gmmktime
Description
int gmmktime ( int hour, int minute, int second, int month, int day, int year [, int is_dst])Identique à mktime() hormis le fait que les paramètres passés sont GMT.
gmstrftime
(PHP 3>= 3.0.12, PHP 4 )
gmstrftime -- Formate une date/heure GMT/CUT en fonction des paramétrages locaux.Description
string gmstrftime ( string format [, int timestamp])gmstrftime() se comporte exactement comme strftime() hormis le fait que l'heure utilisée est celle de Greenwich (Greenwich Mean Time (GMT)). Par exemple, dans la zone Eastern Standard Time (est des USA) (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".
Voir aussi strftime().
localtime
Description
array localtime ( [int timestamp [, boolean is_associative]])localtime() retourne un tableau identique à la structure retournée par la fonction C localtime. Le premier argument timestamp est un timestamp UNIX. S'il n'est pas fourni, l'heure courante est utilisée. Le second argument is_associative, s'il est mis à 0 ou ignoré, force localtime() à retourner un tableau à index numérique. S'il est mis à 1, localtime() retourne un tableau associatif, avec tous les éléments de la structure C, accessible avec les clés suivantes :
"tm_sec" - secondes
"tm_min" - minutes
"tm_hour" - heure
"tm_mday" - jour du mois
"tm_mon" - mois de l'année
"tm_year" - Année, incompatible an 2000
"tm_wday" - Jour de la semaine
"tm_yday" - Jour de l'année
"tm_isdst" - Est-ce que l'heure d'hiver a pris effet?
microtime
Description
string microtime ( void)microtime() retourne la chaîne "msec sec" avec sec qui est mesurée en secondes depuis le début de l'époque UNIX, (1er janvier 1970 00:00:00 GMT), et msec qui est le nombre de microsecondes de cette heure. Cette fonction est seulement disponible sur les systèmes d'exploitation qui supportent la fonction système gettimeofday().
Les deux parties de la chaîne sont exprimées en secondes.
Exemple 1. Exemple avec microtime()
|
Voir aussi time().
mktime
Description
int mktime ( int hour, int minute, int second, int month, int day, int year [, int is_dst])ATTENTION : l'ordre des arguments est différent de celui de la commande UNIX habituelle mktime(), et fournit des résultats aléatoires si on oublie cet ordre. C'est une erreur très commune que de se tromper de sens.
mktime() retourne un timestamp UNIX correspondant aux arguments fournis. Ce timestamp est un entier long, contenant le nombre de secondes entre le début de l'époque UNIX (1er Janvier 1970) et le temps spécifié.
Les arguments peuvent être omis, de gauche à droite, et tous les arguments manquants sont utilisés avec la valeur courante de l'heure et du jour.
is_dst peut être mis à 1 si l'heure d'hiver est appliquée, 0 si elle ne l'est pas, et -1 (par défaut) si on ne sait pas.
Note : is_dst a été ajouté à partir de la version 3.0.10.
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".
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 : "Le dernier jour de Février 2000 est: 29".
strftime
Description
string strftime ( string format [, int timestamp])strftime() retourne la date sous la forme d'une chaîne formatée conformément au format format, en utilisant le timestamp timestamp donné. Si le timestamp est omis, la date actuelle est utilisée. Les mois et jours de la semaine, et toutes les chaînes dépendantes de la langue sont fixées avec la commande setlocale().
Les caractères suivants sont utilisés pour spécifier le format de la date :
%a - nom abrégé du jour de la semaine (local).
%A - nom complet du jour de la semaine (local).
%b - nom abrégé du mois (local).
%B - nom complet du mois (local).
%c - représentation préférée pour les dates et heures, en local.
%C - numéro de siècle (l'année, divisée par 100 et arrondie entre 00 et 99)
%d - jour du mois en numérique (intervalle 01 à 31)
%D - identique à %m/%d/%y
%e - numéro du jour du mois. Les chiffres sont précédés d'un espace (de ' 1' à '31')
%h - identique à %b
%H - heure de la journée en numérique, et sur 24-heures (intervalle de 00 à 23)
%I - heure de la journée en numérique, et sur 12- heures (intervalle 01 à 12)
%j - jour de l'année, en numérique (intervalle 001 à 366)
%m - mois en numérique (intervalle 1 à 12)
%M - minute en numérique
%n - newline character
%p - soit `am' ou `pm' en fonction de l'heure absolue, ou en fonction des valeurs enregistrées en local.
%r - l'heure au format a.m. et p.m.
%R - l'heure au format 24h
%S - secondes en numérique
%t - tabulation
%T - l'heure actuelle (égal à %H:%M:%S)
%u - le numéro de jour dans la semaine, de 1 à 7. (1 représente Lundi)
%U - numéro de semaine dans l'année, en considérant le premier dimanche de l'année comme le premier jour de la première semaine.
%V - le numéro de semaine comme défini dans l'ISO 8601:1988, sous forme décimale, de 01 à 53. La semaine 1 est la première semaine qui a plus de 4 jours dans l'année courante, et dont Lundi est le premier jour.
%W - numéro de semaine dans l'année, en considérant le premier lundi de l'année comme le premier jour de la première semaine
%w - jour de la semaine, numérique, avec Dimanche = 0
%x - format préféré de représentation de la date sans l'heure
%X - format préféré de représentation de l'heure sans la date
%y - l'année, numérique, sur deux chiffres (de 00 à 99)
%Y - l'année, numérique, sur quatre chiffres
%Z - fuseau horaire, ou nom ou abréviation
%% - un caractère `%' littéral
Note : Tous les caractères suivants ne sont pas toujours supportés par toutes les librairies C. Dans ce cas, ils ne seront pas supportés par PHP non plus.
Voir aussi strftime(), setlocale(), mktime() et le groupe de spécifications de strftime().
strtotime
Description
int strtotime ( string time [, int now])strtotime() essaye de lire une date au format anglais dans la chaîne time, et de la transformer en timestamp UNIX.
Exemple 1. Exemple avec strtotime()
|
time
Description
int time ( void)time() retourne l'heure courante, mesurée en secondes depuis le début de l'époque UNIX, (1er janvier 1970 00:00:00 GMT).
Voir aussi date().
XIX. dBase
Ces fonctions vous permettront d'accéder aux enregistrements d'une base au format dBase (.dbf).
dBase ne permet pas l'utilisation d'index, de "memo fields", ni le blocage de la base. Deux processus de serveurs web différents modifiant le même fichier dBase risque de rendre votre base de données incohérente.
Les fichiers dBase sont de simples fichiers séquentiels d'enregistrements de longueur fixe. Les enregistrements sont ajoutés à la fin du fichier et les enregistrements supprimés sont conservés jusqu'à l'appel de dbase_pack().
Nous vous recommandons de ne pas utiliser les fichiers dBase comme base de données de production. Choisissez n'importe quel serveur SQL à la place. MySQL et PostgresSQL sont des choix classiques avec PHP. Le support de dBase ne se justifie ici que pour vous permettre d'importer et d'exporter des données depuis et vers votre base des données issues du web, car ce format de fichier est communément accepté par les feuilles et organiseurs Windows. L'import et l'export de données est l'unique chose pour laquelle l'utilisation de dBase est recommandée.
- Table des matières
- dbase_add_record -- Ajoute un enregistrement dans une base 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_record_with_names -- Lit un enregistrement dans une base, sous la forme d'un tableau associatif.
- dbase_get_record -- Lit un enregistrement dans une base dBase.
- dbase_numfields -- Compte le nombre de champs d'une base dBase.
- dbase_numrecords -- Compter le nombre d'enregistrements dans une base dBase.
- dbase_open -- Ouverture d'une base dBase.
- dbase_pack -- Compacte une base dBase.
- dbase_replace_record -- Remplace un enregistrement dans une base dBase.
dbase_add_record
Description
boolean dbase_add_record ( resource dbase_identifier, array record)dbase_add_record() ajoute les données de record dans la base spécifiée par dbase_identifier. Si le nombre de colonnes fourni n'est pas celui du nombre de champs dans la base, l'opération échouera, et FALSE sera retourné.
dbase_close
Description
boolean dbase_close ( resource dbase_identifier)dbase_close() ferme la base associée à dbase_identifier.
dbase_create
Description
int dbase_create ( string filename, array fields)fields est un tableau de tableaux. Chaque tableau décrit le format d'un fichier de la base. Chaque champs est constitué d'un nom, d'un caractère de type de champs, d'une longueur et d'une précision.
Les types de champs disponibles sont :
- L
Boolean (booléen). Pas de longueur ou de précision pour ces valeurs.
- M
Memo. (Note importante : les Memos ne sont pas supportés par PHP.) Elles n'ont pas de longueur ou de précision.
- D
Date (enregistrée au format 'YYYYMMDD'). Elles n'ont pas de longueur ou de précision.
- N
Number (nombre). Possède une longueur et un précision (le nombre de chiffres après la virgule).
- C
String (chaîne).
Si la base de données a été créée, un identifiant de base dbase_identifier est retourné, sinon, FALSE est retourné.
Exemple 1. Création d'une base dBase
|
dbase_delete_record
Description
boolean dbase_delete_record ( resource dbase_identifier, int record)dbase_delete_record() marque l'enregistrement record pour l'effacement, dans la base dbase_identifier. Pour effacer réellement l'enregistrement, il faut utiliser aussi dbase_pack().
dbase_get_record_with_names
(PHP 3>= 3.0.4, PHP 4 )
dbase_get_record_with_names -- Lit un enregistrement dans une base, sous la forme d'un tableau associatif.Description
array dbase_get_record_with_names ( resource dbase_identifier, int record)dbase_identifier retourne les données de l'enregistrement record dans un tableau associatif. Le tableau inclus un membre nommé 'deleted' (effacé), qui sera mis à 1 si l'enregistrement a été marqué pour l'effacement (voir dbase_delete_record()).
Chaque champs est converti au format approprié PHP. (Les dates sont laissées au format chaîne).
dbase_get_record
Description
array dbase_get_record ( resource dbase_identifier, int record)dbase_get_record() retourne les données de l'enregistrement record dans un tableau. Le tableau est indexé à partir de 0, et inclus un membre nommé 'deleted' (effacé), qui sera mis à 1 si l'enregistrement a été marqué pour l'effacement (voir dbase_delete_record()).
Chaque champs est converti au format approprié PHP. (Les dates sont laissées au format chaîne).
dbase_numfields
Description
int dbase_numfields ( resource dbase_identifier)dbase_numfields() retourne le nombre de champs (colonnes) de la base de données dbase_identifier. Les numéros de champs 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).
dbase_numrecords
Description
int dbase_numrecords ( resource dbase_identifier)dbase_numrecords() retourne le nombre d'enregistrements (lignes) dans la base dbase_identifier. Les numéros de champs 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).
dbase_open
Description
int dbase_open ( string filename, int flags)flags est un flag, comme pour la fonction open(). (Typiquement; 0 signifie lecture seule, 1 signifie écriture seule, et 2 écriture/lecture).
dbase_open() retourne un identifiant de base de données, ou FALSE si la base n'a pas pu être sélectionnée.
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
dbase_pack
Description
boolean dbase_pack ( resource dbase_identifier)dbase_pack() compacte la base de données dbase_identifier (effacement définitif de tous les enregistrements marqués pour l'effacement, avec la fonction dbase_delete_record()).
dbase_replace_record
Description
boolean dbase_replace_record ( resource dbase_identifier, array record, int dbase_record_number)dbase_replace_record() remplace les données associées à l'enregistrement record_number par les données enregistrées dans record. Si le nombre de colonnes fourni n'est pas celui du nombre de champs dans la base, l'opération échouera, et FALSE sera retourné.
dbase_record_number est un entier qui peut aller de 1 jusqu'au nombre maximal d'enregistrement de la base (retourné par dbase_numrecords()).
XX. DBM
Ces fonctions vous permettent d'écrire des lignes dans une base de données de type dbm. Ce type de base (supporté par Berkeley db, gdbm, et quelques librairies systèmes, ou certaines librairies du système d'exploitation) enregistre les paires clés/valeurs, (contrairement aux enregistrements par ligne, utilisé par les autres bases de données relationnelles).
- Table des matières
- dblist -- Décrit la librairie dbm utilisée.
- dbmclose -- Ferme une base de données dbm.
- dbmdelete -- Efface une valeur.
- dbmexists -- Indique si une valeur existe.
- dbmfetch -- Lit une valeur.
- dbmfirstkey -- Lit la première clé.
- dbminsert -- Insère une valeur.
- dbmnextkey -- Lit la clé suivante.
- dbmopen -- Ouvre une base de données dbm
- dbmreplace -- Remplace une valeur.
dblist
dbmclose
Description
boolean dbmclose ( resource dbm_identifier)dbmclose() déverrouille et ferme la base de données dbm_identifier.
dbmdelete
Description
boolean dbmdelete ( resource dbm_identifier, string key)dbmdelete() efface la valeur de la clé key, dans la base dbm_identifier.
dbmdelete() retourne FALSE si la clé n'existe pas dans cette base.
dbmexists
Description
boolean dbmexists ( resource dbm_identifier, string key)dbmexists() retourne TRUE s'il y a une valeur associée à la clé key.
dbmfetch
Description
string dbmfetch ( resource dbm_identifier, string key)dbmfetch() retourne la valeur associée à la clé key.
dbmfirstkey
Description
string dbmfirstkey ( resource dbm_identifier)dbmfirstkey() retourne la première clé de la base de données. Notez bien que les clés ne sont pas dans un ordre défini, étant donné que la table est construite comme un tableau associatif.
dbminsert
Description
int dbminsert ( resource dbm_identifier, string key, string value)dbminsert() ajoute la valeur value dans la base de données, avec la clé key.
dbminsert() retourne -1 si la base a été ouverte en mode lecture seule, 0 si l'insertion a été réussie, et 1 si la clé key existe déjà. (Pour remplacer la valeur, utilisez dbmreplace().)
dbmnextkey
Description
string dbmnextkey ( resource dbm_identifier, string key)dbmnextkey() retourne la clé après la clé key. En appelant dbmfirstkey(), puis successivement dbmnextkey(), il est possible de passer en revue toute les paires clé/valeur de la base de données dbm. Par exemple :
dbmopen
Description
resource dbmopen ( string filename, string flags)Le premier argument est le chemin absolu jusqu'au fichier dbm à ouvrir. Le deuxième argument est le mode d'ouverture du fichier, qui peut prendre les valeurs suivantes : "r", "n", "c" ou "w" qui représentent respectivement lecture seule, nouveau (ce qui implique lecture/écriture, et qui, probablement, va écraser une base existante), création(ce qui implique lecture/écriture, et qui, probablement, va écraser une base existante), et lecture/écriture.
dbmopen() retourne un identifiant, qui sera passé à toutes les autres fonctions dbm, en cas de succès, ou FALSE en cas d'échec.
Si ndbm est utilisé, ndbm va créer les fichiers filename.dir et filename.pag. gdbm n'utilise qu'un fichier, tout comme les librairies internes, et Berkeley db crée le fichier filename.db. Notez que PHP dispose de son propre système de verrouillage des fichiers, qui s'additionne à celui éventuellement utilisé par les librairies. PHP n'efface jamais les fichiers .lck qu'il crée. Il les utilise comme inode fixe, sur lequel faire le verrouillage. Pour plus d'informations sur les fichiers dbm, reportez-vous à vos pages de manuel Unix (man) , ou bien chargez gdbm : ftp://prep.ai.mit.edu/pub/gnu.
dbmreplace
XXI. dbx
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Le module dbx est un module d'abstraction de base de données (db pour database (base de données) et 'X' pour toutes les bases supportées). Les fonctions dbx vous permettent d'accéder à toutes les bases supportées, avec la même convention. Pour cela il vous faut avoir ces fonctions compilées avec PHP (option de configuration --enable-dbx et toutes les bases que vous souhaitez utiliser. Par exemple, si vous voulez accéder à MySQL depuis dbx, vous devez aussi configurer PHP avec --with-mysql. Les fonctions dbx n'interface pas directement les bases de données, mais utilise les modules de support de ces bases. Pour pouvoir utiliser une base avec le module dbx, il vous faut l'avoir configuré avec PHP, ou bien la charger dynamiquement. Actuellement les bases MySQL, PostgreSQL, Microsoft SQL server, FrontBase et ODBC sont supportées, mais d'autres suivront bientôt (j'espère).
La documentation complémentaire (ajout de nouvelles bases à dbx) est accessible à http://www.guidance.nl/php/dbx/doc/.
- Table des matières
- dbx_close -- Ferme une connexion à une base
- dbx_compare -- Compare two rows for sorting purposes
- dbx_connect -- Ouvre une connexion à une base de données
- dbx_error -- Rapporte le message d'erreur du dernier appel de fonction
- dbx_query -- Envoie une requête et lit tous les résultats
- dbx_sort -- Tri un résultat avec une fonction utilisateur
dbx_close
Description
boolean dbx_close ( resource link_identifier)| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
dbx_close() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Note : Reportez-vous aussi à la documentation de la base de données que vous utilisez.
Voir aussi dbx_connect().
dbx_compare
Description
int dbx_compare ( array row_a, array row_b, string column_key [, int flags])dbx_compare() returns 0 if the row_a[$column_key] is equal to row_b[$column_key], and 1 or -1 if the former is greater or is smaller than the latter one, respectively, or vice versa if the flag is set to DBX_CMP_DESC. dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.
The flags can be set to specify comparison direction:
DBX_CMP_ASC - ascending order
DBX_CMP_DESC - descending order
DBX_CMP_NATIVE - no type conversion
DBX_CMP_TEXT - compare items as strings
DBX_CMP_NUMBER - compare items numerically
Exemple 1. dbx_compare() example
|
See also dbx_sort().
dbx_connect
Description
resource dbx_connect ( string module, string host, string database, string username, string password [, int persistent])| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
dbx_connect() retourne une resource dbx_link_object en cas de succès, FALSE sinon. Si la connexion a put être établie, mais que la base de données n'a pas pu être sélectionnée, la fonction retournera quand même une ressource. Le paramètre persistent peut prendre la valeur DBX_PERSISTENT, pour créer une connexion persitante.
Le paramètre module peut être soit une chaîne, soit une constante. Les valeurs possibles de module sont listées ci-dessous (n'oubliez pas que cela fonctionnera que si le module associé est chargé):
module DBX_MYSQL : "mysql"
module DBX_ODBC : "odbc"
module DBX_PGSQL : "pgsql"
module DBX_MSSQL : "mssql"
module DBX_FBSQL : "fbsql" (CVS uniquement)
Le support de pgsql était au stade expérimental jusqu'en avril 2001, et vous devez compiler vous-même le module pgsql après avoir modifié un des fichiers sources. Sinon, vous aurez une alerte affichée à chaque requête.
La ressource dbx_link_object a trois membres : 'handle', 'module' et 'database'. Le membre 'database' contient le nom de la base de données actuellement sélectionnée. Le membre 'module' est à usage interne à dbx, et contient le numéro de module sus-cité. Le membre 'handle' est une ressource valide de connexion à la base de données, et peut être utilisé en tant que tel dans les autres fonctions spécifiques à cette base de données.
Le message d'erreur pour Microsoft SQL server est actuellement le résultat direct de la fonction mssql_get_last_message().
<?php
$link = dbx_connect("mysql", "localhost", "base de données", "utilisateur", "mot de passe");
mysql_close($link->handle);
// dbx_close($link) est beaucoup plus adapté ici
?> |
Les paramètres host, database, username et password sont attendus, mais ne sont pas toujours utiles, suivant la fonction de connexion de la base de données utilisée.
Note : Reportez-vous aussi à la documentation de la base de données que vous utilisez.
Voir aussi dbx_close().
dbx_error
Description
string dbx_error ( resource link_identifier)| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
dbx_error() retourne une chaîne contenant le message d'erreur du module sélectionné. S'il y a des connexions multiples sur le même module, seule la dernière erreur est fournie. S'il a des des connexions sur différents modules, la dernière erreur du module est retourné (le module est alors représenté par link_identifier). Notez que le module ODBC ne supporte pas encore cette fonction.
Note : Reportez-vous aussi à la documentation de la base de données que vous utilisez.
dbx_query
Description
resource dbx_query ( resource link_identifier, string sql_statement [, long flags])| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
dbx_query() retourne une ressource dbx_result_object ou 1 en cas de succès (un objet de résultat ne sera retourné que pour les requêtes SQL qui retournent un résultat), ou 0 en cas d'erreur. Le paramètre flags sert à contrôler la quantité d'informations retournée. Il peut être n'importe quelle combinaisons par OR des constantes : DBX_RESULT_INFO, DBX_RESULT_INDEX, DBX_RESULT_ASSOC. DBX_RESULT_INFO fournit des informations sur les colonnes, comme les noms des champs et leur type. DBX_RESULT_INDEX retourne le résultat dans un tableau indexé (par exemple, data[2][3], où 2 est le numéro de ligne et 3 est le numéro de colonne), dont la première colonne est indexée à 0. DBX_RESULT_ASSOC associe les noms de colonnes avec leurs indices. Notez que DBX_RESULT_INDEX est toujours retourné, indépendamment de la valeur de flags. Si DBX_RESULT_ASSOC est spécifié, DBX_RESULT_INFO est aussi retourné, même s'il n'a pas été spécifié. Ce qui signifie que les seules combinaisons envisageables sont DBX_RESULT_INDEX, DBX_RESULT_INDEX | DBX_RESULT_INFO et DBX_RESULT_INDEX | DBX_RESULT_INFO | DBX_RESULT_ASSOC. La dernière combinaison est la valeur par défaut de flags. Les résultats associés sont en fait des références, ce qui fait que modifier data[0][0], revient à modifier data[0]['fieldnameforfirstcolumn'].
Un objet dbx_result_object a 5 membres (éventuellement 4, suivants les valeurs de flags) : 'handle', 'cols', 'rows', 'info' (optionnel) et 'data'. Handle est un identifiant de résultat, qui peut être utilisé avec les fonctions spécifiques à son module. Par exemple :
Les membres cols et rows contiennent les numéros de colonne et de champs.
<?php $result = dbx_query($link, "SELECT id FROM tbl"); echo "Taille du résultat: " . $result->rows . " x " . $result->cols . "<br>\n"; ?> |
Le membre info n'est retourné que si DBX_RESULT_INFO et/ou DBX_RESULT_ASSOC sont spécifié dans le paramètre flags. C'est un deuxième tableau, qui possède deux lignes ("name" and "type"), pour connaître les informations sur les colonnes.
<?php $result = dbx_query($link, "SELECT id FROM tbl"); echo "Nom de la colonne : " . $result->info["name"][0] . "<br>\n"; echo "Type de la colonne: " . $result->info["type"][0] . "<br>\n"; ?> |
Le membre data contient les données effectivement lues, éventuellement associées à des noms de colonnes. Si DBX_RESULT_ASSOC est utilisé, il est possible d'utiliser $result->data[2]["fieldname"].
Exemple 1. Exemple avec dbx_query()
|
Note : Reportez-vous aussi à la documentation de la base de données que vous utilisez.
Voir aussi dbx_connect().
dbx_sort
Description
boolean dbx_sort ( dbx_result_object result, string user_compare_function)| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
dbx_sort() retourne TRUE en cas de succès, et FALSE sinon.
Exemple 1. Exemple avec dbx_sort()
|
Voir aussi dbx_cmp_asc() et dbx_cmp_desc().
XXII. DB++ Functions
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Introduction
db++, made by the German company Concept asa, is a relational database system with high performance and low memory and disk usage in mind. While providing SQL as an additional language interface, it is not really a SQL database in the first place but provides its own AQL query language which is much more influenced by the relational algebra then SQL is.
Concept asa always had an interest in supporting open source languages, db++ has had Perl and Tcl call interfaces for years now and uses Tcl as its internal stored procedure language.
Requirements
This extension relies on external client libraries so you have to have a db++ client installed on the system you want to use this extension on.
Concept asa provides db++ Demo versions and documentation for Linux, some other UNIX versions. There is also a Windows version of db++, but this extension doesn't support it (yet).
Installation
In order to build this extension yourself you need the db++ client libraries and header files to be installed on your system (these are included in the db++ installation archives by default). You have to run configure with option --with-dbplus to build this extension.
configure looks for the client libraries and header files under the default paths /usr/dbplus, /usr/local/dbplus and /opt/dblus. If you have installed db++ in a different place you have add the installation path to the configure option like this: --with-dbplus=/your/installation/path.
Resource Types
dbplus_relation
Most db++ functions operate on or return dbplus_relation resources. A dbplus_relation is a handle to a stored relation or a relation generated as the result of a query.
Predefined Constants
These constants are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
db++ error codes
Tableau 1. DB++ Error Codes
| PHP Constant | db++ constant | meaning |
|---|---|---|
| DBPLUS_ERR_NOERR (integer) | ERR_NOERR | Null error condition |
| DBPLUS_ERR_DUPLICATE (integer) | ERR_DUPLICATE | Tried to insert a duplicate tuple |
| DBPLUS_ERR_EOSCAN (integer) | ERR_EOSCAN | End of scan from rget() |
| DBPLUS_ERR_EMPTY (integer) | ERR_EMPTY | Relation is empty (server) |
| DBPLUS_ERR_CLOSE (integer) | ERR_CLOSE | The server can't close |
| DBPLUS_ERR_WLOCKED (integer) | ERR_WLOCKED | The record is write locked |
| DBPLUS_ERR_LOCKED (integer) | ERR_LOCKED | Relation was already locked |
| DBPLUS_ERR_NOLOCK (integer) | ERR_NOLOCK | Relation cannot be locked |
| DBPLUS_ERR_READ (integer) | ERR_READ | Read error on relation |
| DBPLUS_ERR_WRITE (integer) | ERR_WRITE | Write error on relation |
| DBPLUS_ERR_CREATE (integer) | ERR_CREATE | Create() system call failed |
| DBPLUS_ERR_LSEEK (integer) | ERR_LSEEK | Lseek() system call failed |
| DBPLUS_ERR_LENGTH (integer) | ERR_LENGTH | Tuple exceeds maximum length |
| DBPLUS_ERR_OPEN (integer) | ERR_OPEN | Open() system call failed |
| DBPLUS_ERR_WOPEN (integer) | ERR_WOPEN | Relation already opened for writing |
| DBPLUS_ERR_MAGIC (integer) | ERR_MAGIC | File is not a relation |
| DBPLUS_ERR_VERSION (integer) | ERR_VERSION | File is a very old relation |
| DBPLUS_ERR_PGSIZE (integer) | ERR_PGSIZE | Relation uses a different page size |
| DBPLUS_ERR_CRC (integer) | ERR_CRC | Invalid crc in the superpage |
| DBPLUS_ERR_PIPE (integer) | ERR_PIPE | Piped relation requires lseek() |
| DBPLUS_ERR_NIDX (integer) | ERR_NIDX | Too many secondary indices |
| DBPLUS_ERR_MALLOC (integer) | ERR_MALLOC | Malloc() call failed |
| DBPLUS_ERR_NUSERS (integer) | ERR_NUSERS | Error use of max users |
| DBPLUS_ERR_PREEXIT (integer) | ERR_PREEXIT | Caused by invalid usage |
| DBPLUS_ERR_ONTRAP (integer) | ERR_ONTRAP | Caused by a signal |
| DBPLUS_ERR_PREPROC (integer) | ERR_PREPROC | Error in the preprocessor |
| DBPLUS_ERR_DBPARSE (integer) | ERR_DBPARSE | Error in the parser |
| DBPLUS_ERR_DBRUNERR (integer) | ERR_DBRUNERR | Run error in db |
| DBPLUS_ERR_DBPREEXIT (integer) | ERR_DBPREEXIT | Exit condition caused by prexit() * procedure |
| DBPLUS_ERR_WAIT (integer) | ERR_WAIT | Wait a little (Simple only) |
| DBPLUS_ERR_CORRUPT_TUPLE (integer) | ERR_CORRUPT_TUPLE | A client sent a corrupt tuple |
| DBPLUS_ERR_WARNING0 (integer) | ERR_WARNING0 | The Simple routines encountered a non fatal error which was corrected |
| DBPLUS_ERR_PANIC (integer) | ERR_PANIC | The server should not really die but after a disaster send ERR_PANIC to all its clients |
| DBPLUS_ERR_FIFO (integer) | ERR_FIFO | Can't create a fifo |
| DBPLUS_ERR_PERM (integer) | ERR_PERM | Permission denied |
| DBPLUS_ERR_TCL (integer) | ERR_TCL | TCL_error |
| DBPLUS_ERR_RESTRICTED (integer) | ERR_RESTRICTED | Only two users |
| DBPLUS_ERR_USER (integer) | ERR_USER | An error in the use of the library by an application programmer |
| DBPLUS_ERR_UNKNOWN (integer) | ERR_UNKNOWN |
- Table des matières
- dbplus_add -- Add a tuple to a relation
- dbplus_aql -- Perform AQL query
- dbplus_chdir -- Get/Set database virtual current directory
- dbplus_close -- Close a relation
- dbplus_curr -- Get current tuple from relation
- dbplus_errcode -- Get error string for given errorcode or last error
- dbplus_errno -- Get error code for last operation
- dbplus_find -- Set a constraint on a relation
- dbplus_first -- Get first tuple from relation
- dbplus_flush -- Flush all changes made on a relation
- dbplus_freealllocks -- Free all locks held by this client
- dbplus_freelock -- Release write lock on tuple
- dbplus_freerlocks -- Free all tuple locks on given relation
- dbplus_getlock -- Get a write lock on a tuple
- dbplus_getunique -- Get a id number unique to a relation
- dbplus_info -- ???
- dbplus_last -- Get last tuple from relation
- dbplus_lockrel -- Request write lock on relation
- dbplus_next -- Get next tuple from relation
- dbplus_open -- Open relation file
- dbplus_prev -- Get previous tuple from relation
- dbplus_rchperm -- Change relation permissions
- dbplus_rcreate -- Creates a new DB++ relation
- dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indices
- dbplus_rcrtlike -- Creates an empty copy of a relation with default indices
- dbplus_resolve -- Resolve host information for relation
- dbplus_restorepos -- ???
- dbplus_rkeys -- Specify new primary key for a relation
- dbplus_ropen -- Open relation file local
- dbplus_rquery -- Perform local (raw) AQL query
- dbplus_rrename -- Rename a relation
- dbplus_rsecindex -- Create a new secondary index for a relation
- dbplus_runlink -- Remove relation from filesystem
- dbplus_rzap -- Remove all tuples from relation
- dbplus_savepos -- ???
- dbplus_setindex -- ???
- dbplus_setindexbynumber -- ???
- dbplus_sql -- Perform SQL query
- dbplus_tcl -- Execute TCL code on server side
- dbplus_tremove -- Remove tuple and return new current tuple
- dbplus_undo -- ???
- dbplus_undoprepare -- ???
- dbplus_unlockrel -- Give up write lock on relation
- dbplus_unselect -- Remove a constraint from relation
- dbplus_update -- Update specified tuple in relation
- dbplus_xlockrel -- Request exclusive lock on relation
- dbplus_xunlockrel -- Free exclusive lock on relation
dbplus_add
Description
int dbplus_add ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
This function will add a tuple to a relation. The tuple data is an array of attribute/value pairs to be inserted into the given relation. After successful execution the tuple array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
dbplus_aql
Description
resource dbplus_aql ( string query [, string server [, string dbpath]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_aql() will execute an AQL query on the given server and dbpath.
On success it will return a relation handle. The result data may be fetched from this relation by calling dbplus_next() and dbplus_current(). Other relation access functions will not work on a result relation.
Further information on the AQL A... Query Language is provided in the original db++ manual.
dbplus_chdir
Description
string dbplus_chdir ( [string newdir])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_chdir() will change the virtual current directory where relation files will be looked for by dbplus_open(). dbplus_chdir() will return the absolute path of the current directory. Calling dbplus_chdir() without giving any newdir may be used to query the current working directory.
dbplus_close
Description
int dbplus_close ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Calling dbplus_close() will close a relation previously opened by dbplus_open().
dbplus_curr
Description
int dbplus_curr ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_curr() will read the data for the current tuple for the given relation and will pass it back as an associative array in tuple.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
See also dbplus_first(), dbplus_prev(), dbplus_next(), and dbplus_last().
dbplus_errcode
Description
string dbplus_errcode ( int errno)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_errcode() returns a cleartext error string for the error code passed as errno of for the result code of the last db++ operation if no parameter is given.
dbplus_errno
Description
int dbplus_errno ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_errno() will return the error code returned by the last db++ operation.
See also dbplus_errcode().
dbplus_find
Description
int dbplus_find ( resource relation, array constraints, mixed tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_find() will place a constraint on the given relation. Further calls to functions like dbplus_curr() or dbplus_next() will only return tuples matching the given constraints.
Constraints are triplets of strings containing of a domain name, a comparison operator and a comparison value. The constraints parameter array may consist of a collection of string arrays, each of which contains a domain, an operator and a value, or of a single string array containing a multiple of three elements.
The comparison operator may be one of the following strings: '==', '>', '>=', '<', '<=', '!=', '~' for a regular expression match and 'BAND' or 'BOR' for bitwise operations.
See also dbplus_unselect().
dbplus_first
Description
int dbplus_first ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_curr() will read the data for the first tuple for the given relation, make it the current tuple and pass it back as an associative array in tuple.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
See also dbplus_curr(), dbplus_prev(), dbplus_next(), and dbplus_last().
dbplus_flush
Description
int dbplus_flush ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_flush() will write all changes applied to relation since the last flush to disk.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
dbplus_freealllocks
Description
int dbplus_freealllocks ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_freeaalllocks() will free all tuple locks held by this client.
See also dbplus_getlock(), dbplus_freelock(), and dbplus_freerlocks().
dbplus_freelock
Description
int dbplus_freelock ( resource relation, string tname)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_freelock() will release a write lock on the given tuple previously obtained by dbplus_getlock().
See also dbplus_getlock(), dbplus_freerlocks(), and dbplus_freealllocks().
dbplus_freerlocks
Description
int dbplus_freerlocks ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_freerlocks() will free all tuple locks held on the given relation.
See also dbplus_getlock(), dbplus_freelock(), and dbplus_freealllocks().
dbplus_getlock
Description
int dbplus_getlock ( resource relation, string tname)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_getlock() will request a write lock on the specified tuple. It will return zero on success or a non-zero error code, especially DBPLUS_ERR_WLOCKED, on failure.
See also dbplus_freelock(), dbplus_freerlocks(), and dbplus_freealllocks().
dbplus_getunique
Description
int dbplus_getunique ( resource relation, int uniqueid)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_getunique() will obtain a number guaranteed to be unique for the given relation and will pass it back in the variable given as uniqueid.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
dbplus_info
Description
int dbplus_info ( resource relation, string key, array )| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_last
Description
int dbplus_last ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_curr() will read the data for the last tuple for the given relation, make it the current tuple and pass it back as an associative array in tuple.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
See also dbplus_first(), dbplus_curr(), dbplus_prev(), and dbplus_next().
dbplus_lockrel
Description
int dbplus_lockrel ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_lockrel() will request a write lock on the given relation. Other clients may still query the relation, but can't alter it while it is locked.
dbplus_next
Description
int dbplus_next ( resource relation, array )| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_curr() will read the data for the next tuple for the given relation, will make it the current tuple and will pass it back as an associative array in tuple.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
See also dbplus_first(), dbplus_curr(), dbplus_prev(), and dbplus_last().
dbplus_open
Description
resource dbplus_open ( string name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The relation file name will be opened. name can be either a file name or a relative or absolute path name. This will be mapped in any case to an absolute relation file path on a specific host machine and server.
On success a relation file resource (cursor) is returned which must be used in any subsequent commands referencing the relation. Failure leads to a zero return value, the actual error code may be asked for by calling dbplus_errno().
dbplus_prev
Description
int dbplus_prev ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_curr() will read the data for the next tuple for the given relation, will make it the current tuple and will pass it back as an associative array in tuple.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.
See also dbplus_first(), dbplus_curr(), dbplus_next(), and dbplus_last().
dbplus_rchperm
Description
int dbplus_rchperm ( resource relation, int mask, string user, string group)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rchperm() will change access permissions as specified by mask, user and group. The values for these are operating system specific.
dbplus_rcreate
Description
resource dbplus_rcreate ( string name, mixed domlist [, boolean overwrite])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rcreate() will create a new relation named name. An existing relation by the same name will only be overwritten if the relation is currently not in use and overwrite is set to TRUE.
domlist should contain the domain specification for the new relation within an array of domain description strings. ( dbplus_rcreate() will also accept a string with space delimited domain description strings, but it is recommended to use an array). A domain description string consists of a domain name unique to this relation, a slash and a type specification character. See the db++ documentation, especially the dbcreate(1) manpage, for a description of available type specifiers and their meanings.
dbplus_rcrtexact
(4.1.0 - 4.2.1 only)
dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indicesDescription
resource dbplus_rcrtexact ( string name, resource relation, boolean overwrite)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rcrtexact() will create an exact but empty copy of the given relation under a new name. An existing relation by the same name will only be overwritten if overwrite is TRUE and no other process is currently using the relation.
dbplus_rcrtlike
Description
resource dbplus_rcrtlike ( string name, resource relation, int flag)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rcrtexact() will create an empty copy of the given relation under a new name, but with default indices. An existing relation by the same name will only be overwritten if overwrite is TRUE and no other process is currently using the relation.
dbplus_resolve
Description
int dbplus_resolve ( string relation_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_resolve() will try to resolve the given relation_name and find out internal server id, real hostname and the database path on this host. The function will return an array containing these values under the keys 'sid', 'host' and 'host_path' or FALSE on error.
See also dbplus_tcl().
dbplus_restorepos
Description
int dbplus_restorepos ( resource relation, array tuple)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_rkeys
Description
resource dbplus_rkeys ( resource relation, mixed domlist)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rkeys() will replace the current primary key for relation with the combination of domains specified by domlist.
domlist may be passed as a single domain name string or as an array of domain names.
dbplus_ropen
Description
resource dbplus_ropen ( string name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_ropen() will open the relation file locally for quick access without any client/server overhead. Access is read only and only dbplus_current() and dbplus_next() may be applied to the returned relation.
dbplus_rquery
Description
int dbplus_rquery ( string query, string dbpath)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rquery() performs a local (raw) AQL query using an AQL interpreter embedded into the db++ client library. dbplus_rquery() is faster than dbplus_aql() but will work on local data only.
dbplus_rrename
Description
int dbplus_rrename ( resource relation, string name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rrename() will change the name of relation to name.
dbplus_rsecindex
Description
resource dbplus_rsecindex ( resource relation, mixed domlist, int type)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rsecindex() will create a new secondary index for relation with consists of the domains specified by domlist and is of type type
domlist may be passed as a single domain name string or as an array of domain names.
dbplus_runlink
Description
int dbplus_runlink ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_unlink() will close and remove the relation.
dbplus_rzap
Description
int dbplus_rzap ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_rzap() will remove all tuples from relation.
dbplus_savepos
Description
int dbplus_savepos ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_setindex
Description
int dbplus_setindex ( resource relation, string idx_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_setindexbynumber
Description
int dbplus_setindexbynumber ( resource relation, int idx_number)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_sql
Description
resource dbplus_sql ( string query, string server, string dbpath)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_tcl
Description
int dbplus_tcl ( int sid, string script)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
A db++ server will prepare a TCL interpreter for each client connection. This interpreter will enable the server to execute TCL code provided by the client as a sort of stored procedures to improve the performance of database operations by avoiding client/server data transfers and context switches.
dbplus_tcl() needs to pass the client connection id the TCL script code should be executed by. dbplus_resolve() will provide this connection id. The function will return whatever the TCL code returns or a TCL error message if the TCL code fails.
See also dbplus_resolve().
dbplus_tremove
Description
int dbplus_tremove ( resource relation, array tuple [, array current])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_tremove() removes tuple from relation if it perfectly matches a tuple within the relation. current, if given, will contain the data of the new current tuple after calling dbplus_tremove().
dbplus_undo
Description
int dbplus_undo ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_undoprepare
Description
int dbplus_undoprepare ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Not implemented yet.
dbplus_unlockrel
Description
int dbplus_unlockrel ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_unlockrel() will release a write lock previously obtained by dbplus_lockrel().
dbplus_unselect
Description
int dbplus_unselect ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Calling dbplus_unselect() will remove a constraint previously set by dbplus_find() on relation.
dbplus_update
Description
int dbplus_update ( resource relation, array old, array new)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_update() replaces the tuple given by old with the data from new if and only if old completely matches a tuple within relation.
dbplus_xlockrel
Description
int dbplus_xlockrel ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_xlockrel() will request an exclusive lock on relation preventing even read access from other clients.
See also dbplus_xunlockrel().
dbplus_xunlockrel
Description
int dbplus_xunlockrel ( resource relation)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
dbplus_xunlockrel() will release an exclusive lock on relation previously obtained by dbplus_xlockrel().
XXIII. Direct IO
Fonctions d'entrée/sortie directes
PHP supporte les entrées/sorties directes, comme décrites dans le Standard Posixd (Section 6). Cela permet de réaliser des accès en lecture écriture à un niveau inférieur aux fonctions proposées par le langage C (fopen, fread...).
Installation
Pour faire fonctionner ces fonctions, vous devez configurer PHP avec l'option --enable-dio.
- Table des matières
- dio_close -- Ferme l'accès au fichier
- dio_fcntl -- Exécute une fonction fichier de langage C
- dio_open -- Ovre un nouveau fichier
- dio_read -- Lit des octets dans un fichier
- dio_seek -- Déplace le pointeur interne de fichier
- dio_stat -- Lit des informations sur le fichier
- dio_truncate -- Tronque le fichier
- dio_write -- Ecrit des données dans le fichier
dio_close
Description
void dio_close ( resource fd)dio_close() ferme l'accès au fichier représenté par la ressource resource.
dio_fcntl
Description
mixed dio_fcntl ( resource fd, int cmd [, mixed arg])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.
arg est un tableau associatif lorsque cmd vaut F_SETLK ou F_SETLLW, 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.
"wenth" - l_start est relatif à : can be 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)
cmd peut être l'une des 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() attent la levée du verrou.
F_GETLK - dio_fcntl() retourne un tableau associatif (comme décrit ci-dessus) si un autre utilisateur empêche la poste d'un verrou. S'il n'y a aucune 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 égales à arg et les retourne.
dio_open
Description
resource dio_open ( string filename, int flags [, int mode])dio_open() ouvre un accès à un fichier, et retourne une ressource de fichier, ou bien -1 si une erreur survient. Si flags vaut O_CREAT, le troisième paramètre optionnel mode indiquera le mode du fichier (les permissions). Le paramètre flags peut prendre l'une des valeurs suivantes :
O_RDONLY - ouvre un fichier en lecture
O_WRONLY - ouvre un fichier en écriture
O_RDWR - ouvre un 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é, dio_open() échouera si le fichier éxiste déjà.
O_TRUNC - si le fichier existe, etqu,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
dio_read
Description
string dio_read ( resource fd [, int n])dio_read() lit et retourne n octets dans le fichier représenté par la ressource fd. Si n est omis, dio_read() lira 1ko de données, et les retournera.
dio_seek
Description
int dio_seek ( resource fd, int pos, int whence)dio_seek() sert à modifier la position du pointeur de fichier dans le fichier fd. Le paramètre whence spécifie comment la position pos doit être interprétée :
SEEK_SET - pos est spécifiée en byte à partir du début du fichier.
SEEK_CUR - pos est un nombre d'octets à partir de la position courante. Ce nombre peut être positif ou négatif.
SEEK_END - pos est un nombre de caractères à partir de la fin du fichier. Un nombre négatif indique une position à l'intérieur du fichier courant; un nombre positif indique une extension du fichier. Si vous utilisez une position au delà de la fin du fichier, et que vous écrivez réellement des données, vous allez aggrandir le fichier de pos caractères.
dio_stat
Description
array dio_stat ( resource fd)dio_stat() retourne les informations sur le fichier représenté par la ressource fd. dio_stat() retourne un tableau associatif, avec les entrées suivantes :
"device" - device
"inode" - inode
"mode" - mode
"nlink" - nombre de liens
"uid" - user id
"gid" - group id
"device_type" - type de device (si inode device)
"size" - taille en octets
"blocksize" - taille de block
"blocks" - nombre de block allouée
"atime" - date de dernier accès
"mtime" - date de dernière modification
"ctime" - date de dernier changement
dio_truncate
Description
bool dio_truncate ( resource fd, int offset)dio_truncate() tronque le fichier représenté par la ressource fd à la taille maximale de offset octets. Si le fichier était plus grand, les données supplémentaires sont perdues. Si le fichier était plus petit, le comportement est non spécifié : le document peut être inchangé, ou bien aggrandi. Dans ce dernier cas, l'extension se fait avec des octets nuls. dio_truncate() retourne 0 en cas de succès, et sinon -1.
dio_write
Description
int dio_write ( resource fd, string data [, int len])dio_write() écrit jusqu'à len octets issues de la variable data, dans le fichier représenté par la ressource fd. Si len n'est pas spécifié, dio_write() utilise la totalité de la variable data. dio_write() retourne le nombre d'octsts écrits dans le fichier fd.
XXIV. Accès aux dossiers
Pour les fonctions associées telles que dirname(), is_dir(), mkdir(), et rmdir(), reportez-vous à la section sur le système de fichiers.
- Table des matières
- chdir -- Change de dossier
- chroot -- Change la racine
- dir -- directory class
- closedir -- Ferme le pointeur sur le dossier.
- getcwd -- Retourne le dossier de travail
- 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.
chdir
Description
int chdir ( string directory)chdir() change le dossier courant de PHP en directory. chdir() retourne FALSE si l'opération échoue, et TRUE sinon.
chroot
Description
int chroot ( string directory)chroot() change la racine du script en cours, et la remplace par directory. chroot() retourne FALSE s'il n'a pas pu modifier la racine, et TRUE sinon.
Note : Il n'est pas conseillé d'utiliser cette fonction sur un site web, car il n'est pas possible de restaurer la racine à sa valeur initiale à la fin de la requête. Cette fonction n'est viable que lorsque PHP est utilisé en CGI.
dir
Description
class dir {dir(string directory);string path;string read();void rewind();void close();}
A pseudo-object oriented mechanism for reading a directory. The given directory is opened. Two properties are available once the directory has been opened. The handle property can be used with other directory functions such as readdir(), rewinddir() and closedir(). The path property is set to path the directory that was opened. Three methods are available: read, rewind and close.
Please note the fashion in which dir()'s return value is checked in the example below. We are explicitly testing whether the return value is identical to (equal to and of the same type as--see Comparison Operators for more information) FALSE since otherwise, any directory entry whose name evaluates to FALSE will stop the loop.
Note : The order in which directory entries are returned by the read method is system-dependent.
Note : This defines the internal class Directory, meaning that you will not be able to define your own classes with that name. For a full list of predefined classes in PHP, please see Predefined Classes.
closedir
Description
void closedir ( resource dir_handle)closedir() ferme le pointeur de dossier dir_handle. Le dossier devait avoir été ouvert avec opendir().
getcwd
opendir
Description
int opendir ( string path)opendir() retourne un pointeur sur un dossier pour être utilisé avec les fonctions closedir(), readdir() et rewinddir().
Si le paramètre path n'est pas un dossier valide, ou si le dossier ne peut être accédé pour des raisons de permissions ou des erreurs liées au système de fichiers, opendir() retourne FALSE et génère une erreur PHP. Vous pouvez supprimer cette erreur en ajoutant @ avant le nom de la fonction.
readdir
Description
string readdir ( resource dir_handle)readdir() retourne le nom du fichier suivant dans le dossier identifié par dir_handle. Les noms sont retournés dans n'importe quel ordre.
Notez que readdir() retournera aussi les dossiers "." et "..". Si vous ne les voulez pas, supprimez les simplement :
rewinddir
XXV. DOM XML
Note importante : cette documentation est en cours de rédaction, et n'est pas encore finie. Elle souffre naturellement d'un manque de détails et de relecture. Soyez en prévenu. (Damien Seguy).
Ces fonctions ne sont disponibles que si PHP a été configuré avec l'option --with-dom=[DIR], et utilise la librairie GNOME xml library. Vous aurez aussi besoin de la librairie libxml-2.2.7 (la version beta ne fonctionne pas). Ces fonctions ont été ajoutées en PHP 4.
Cette extension vous permet de générer des documents XML avec les API DOM. Elle fournit aussi une fonction xmltree() qui transforme un fichier XML en tableau PHP. Actuellement, ce tableau est accessible uniquement en lecture. Cela ne siginifie pas que vous ne pouvez pas le modifier, mais cela n'aurait aucun sens car domxml_dumpmem() ne pourra pas prendre ces modifications en considération. Par conséquent, si vous voulez lire un fichier XML et écrire sa version modifiée, utilisez les fonctions domxml_add_node(), domxml_set_attribute(), etc... et finalement domxml_dumpmem().
Ce module définit les constantes suivantes :
Tableau 1. Constantes XML
| Constante | Valeur | Description |
|---|---|---|
| XML_ELEMENT_NODE | 1 | Le noeud est un élément |
| XML_ATTRIBUTE_NODE | 2 | Le noeud est un attribut |
| XML_TEXT_NODE | 3 | Le noeud est un texte |
| XML_CDATA_SECTION_NODE | 4 | |
| XML_ENTITY_REF_NODE | 5 | |
| XML_ENTITY_NODE | 6 | Le noeud est une entité telle que |
| XML_PI_NODE | 7 | Le noeud est une instruction |
| XML_COMMENT_NODE | 8 | Le noeud est un commentaire |
| XML_DOCUMENT_NODE | 9 | Le noeud est un document |
| XML_DOCUMENT_TYPE_NODE | 10 | |
| XML_DOCUMENT_FRAG_NODE | 11 | |
| XML_NOTATION_NODE | 12 | |
| XML_GLOBAL_NAMESPACE | 1 | |
| XML_LOCAL_NAMESPACE | 2 |
Chaque fonction de cette extension peut être utilisée de deux manières différentes. Dans un contexte procédural, il faut passer l'objet en premier argument; dans un contexte objet, vous pouvez appeler la fonction comme une méthode de cet objet. Cette documentation présente les fonctions dans leur contexte procédural. Vous pouvez connaître la méthode objet en supprimant le préfixe "domxml_". Les tables suivantes listes toutes les classes, leurs attributs et leurs méthodes.
Ce module définit un ensemble de classes, qui sont listées ci-dessous (y compris leur attributs et leur méthodes).
Tableau 2. classe DomDocument (méthodes)
| Nom de la méthode | Nom de la fonction | Description |
|---|---|---|
| root | domxml_root() | |
| children | domxml_children() | |
| add_root | domxml_add_root() | |
| dtd | domxml_intdtd() | |
| dumpmem | domxml_dumpmem() | |
| xpath_init | xpath_init | |
| xpath_new_context | xpath_new_context | |
| xptr_new_context | xptr_new_context |
Tableau 3. Classe DomDocument (attributs)
| Nom | Type | Description |
|---|---|---|
| doc | class DomDocument | L'objet lui-même |
| name | string | |
| url | string | |
| version | string | Version de XML |
| encoding | string | |
| standalone | long | 1 si le fichier est complet |
| type | long | Une des constantes de la table ... |
| compression | long | 1 si le fichier est compressé |
| charset | long |
Tableau 4. classe DomNode (méthodes)
| Nom | Nom en PHP | Description |
|---|---|---|
| lastchild | domxml_last_child() | |
| children | domxml_children() | |
| parent | domxml_parent() | |
| new_child | domxml_new_child() | |
| get_attribute | domxml_get_attribute() | |
| set_attribute | domxml_set_attribute() | |
| attributes | domxml_attributes() | |
| node | domxml_node() | |
| set_content() | domxml_set_content |
- Table des matières
- DomAttribute->name -- Returns name of attribute
- DomAttribute->specified -- Checks if attribute is specified
- DomAttribute->value -- Returns value of attribute
- DomDocument->add_root [deprecated] -- Adds a root node
- DomDocument->create_attribute -- Create new attribute
- DomDocument->create_cdata_section -- Create new cdata node
- DomDocument->create_comment -- Create new comment node
- DomDocument->create_element -- Create new element node
- DomDocument->create_entity_reference --
- DomDocument->create_processing_instruction -- Creates new PI node
- DomDocument->create_text_node -- Create new text node
- DomDocument->doctype -- Returns the document type
- DomDocument->document_element -- Returns root element node
- DomDocument->dump_file -- Dumps the internal XML tree back into a file
- DomDocument->dump_mem -- Dumps the internal XML tree back into a string
- DomDocument->get_element_by_id -- Searches for an element with a certain id
- DomDocument->get_elements_by_tagname --
- DomDocument->html_dump_mem -- Dumps the internal XML tree back into a string as HTML
- DomDocumentType->entities -- Returns list of entities
- DomDocumentType->internal_subset -- Returns internal subset
- DomDocumentType->name -- Returns name of document type
- DomDocumentType->notations -- Returns list of notations
- DomDocumentType->public_id -- Returns public id of document type
- DomDocumentType->system_id -- Returns system id of document type
- DomElement->get_attribute_node -- Returns value of attribute
- DomElement->get_attribute -- Returns value of attribute
- DomElement->get_elements_by_tagname -- Adds new attribute
- DomElement->has_attribute -- Adds new attribute
- DomElement->remove_attribute -- Adds new attribute
- DomElement->set_attribute -- Adds new attribute
- DomElement->tagname -- Returns name of element
- DomNode->append_child -- Adds new child at the end of the children
- DomNode->append_sibling -- Adds new sibling to a node
- DomNode->attributes -- Returns list of attributes
- DomNode->child_nodes -- Returns children of node
- DomNode->clone_node -- Clones a node
- DomNode->dump_node -- Dumps a single node
- DomNode->first_child -- Returns first child of node
- DomNode->get_content -- Gets content of node
- DomNode->has_attributess -- Checks if node has attributes
- DomNode->has_child_nodes -- Checks if node has children
- DomNode->insert_before -- Inserts new node as child
- DomNode->is_blank_node -- Checks if node is blank
- DomNode->last_child -- Returns last child of node
- DomNode->next_sibling -- Returns the next sibling of node
- DomNode->node_name -- Returns name of node
- DomNode->node_type -- Returns type of node
- DomNode->node_value -- Returns value of a node
- DomNode->owner_document -- Returns the document this node belongs to
- DomNode->parent_node -- Returns the parent of the node
- DomNode->prefix -- Returns name space prefix of node
- DomNode->previous_sibling -- Returns the previous sibling of node
- DomNode->remove_child -- Removes child from list of children
- DomNode->replace_child -- Replaces a child
- DomNode->replace_node -- Replaces node
- DomNode->set_content -- Sets content of node
- DomNode->set_name -- Sets name of node
- DomNode->unlink_node -- Deletes node
- DomProcessingInstruction->data -- Returns data of pi node
- DomProcessingInstruction->target -- Returns target of pi node
- domxml_new_doc -- Creates new empty XML document
- domxml_open_file -- Creates a DOM object from XML file
- domxml_open_mem -- Creates a DOM object of an XML document
- domxml_version -- Get XML library version
- domxml_xmltree -- Creates a tree of PHP objects from an XML document
- xpath_eval_expression -- Evaluates the XPath Location Path in the given string
- xpath_eval -- Evalue une expression xpath
- xpath_new_context -- Crée un nouveau contexte xpath
- xptr_eval -- Evaluate the XPtr Location Path in the given string
- xptr_new_context -- Create new XPath Context
DomAttribute->name
Description
bool DomAttribute->name ( void)This function returns the name of the attribute.
See also DomAttribute_value().
DomAttribute->specified
DomAttribute->value
Description
bool DomAttribute->value ( void)This function returns the value of the attribute.
See also DomAttribute_name().
DomDocument->add_root [deprecated]
Description
resource DomDocument->add_root ( string name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Adds a root element node to a dom document and returns the new node. The element name is given in the passed parameter.
DomDocument->create_attribute
Description
object DomDocument->create_attribute ( string name, string value)This function returns a new instance of class DomAttribute. The name of the attribute is the value of the first parameter. The value of the attribute is the value of the second parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_text(), DomDocument_create_cdata_section(), DomDocument_create_processing_instruction(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->create_cdata_section
Description
string DomDocument->create_cdata_section ( string content)This function returns a new instance of class DomCData. The content of the cdata is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_text(), DomDocument_create_attribute(), DomDocument_create_processing_instruction(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->create_comment
Description
object DomDocument->create_comment ( string content)This function returns a new instance of class DomComment. The content of the comment is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_text(), DomDocument_create_attribute(), DomDocument_create_processing_instruction(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->create_element
Description
object DomDocument->create_element ( string name)This function returns a new instance of class DomElement. The tag name of the element is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_text(), DomDocument_create_comment(), DomDocument_create_attribute(), DomDocument_create_processing_instruction(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->create_entity_reference
Description
object DomDocument->create_entity_reference ( string content)This function returns a new instance of class DomEntityReference. The content of the entity reference is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_text(), DomDocument_create_cdata_section(), DomDocument_create_processing_instruction(), DomDocument_create_attribute(), DomNode_insert_before().
DomDocument->create_processing_instruction
Description
string DomDocument->create_processing_instruction ( string content)This function returns a new instance of class DomCData. The content of the pi is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_text(), DomDocument_create_cdata_section(), DomDocument_create_attribute(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->create_text_node
Description
object DomDocument->create_text_node ( string content)This function returns a new instance of class DomText. The content of the text is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. DomNode_append_child().
The return value is false if an error occured.
See also DomNode_append_child(), DomDocument_create_element(), DomDocument_create_comment(), DomDocument_create_text(), DomDocument_create_attribute(), DomDocument_create_processing_instruction(), DomDocument_create_entity_reference(), DomNode_insert_before().
DomDocument->doctype
Description
object DomDocument->doctype ( void)This function returns an object of class DomDocumentType. In versions of PHP before 4.3 this has been the class Dtd, but the DOM Standard does not know such a class.
See also the methods of class DomDocumentType.
DomDocument->document_element
Description
object DomDocument->document_element ( void)This function returns the root element node of a document.
The following example returns just the element with name CHAPTER and prints it. The other node -- the comment -- is not returned.
DomDocument->dump_file
Description
string DomDocument->dump_file ( string filename [, bool compressionmode [, bool format]])Creates an XML document from the dom representation. This function usually is called after building a new dom document from scratch as in the example below. The format specifies whether the output should be neatly formatted, or not. The first parameter specifies the name of the filename and the second parameter, whether it should be compressed or not.
Exemple 1. Creating a simple HTML document header
|
See also DomDocument_dump_mem() DomDocument_html_dump_mem().
DomDocument->dump_mem
Description
string DomDocument->dump_mem ( [bool format])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Creates an XML document from the dom representation. This function usually is called after building a new dom document from scratch as in the example below. The format specifies whether the output should be neatly formatted, or not.
Exemple 1. Creating a simple HTML document header
|
Note : The first parameter was added in PHP 4.3.0.
See also DomDocument_dump_file(), DomDocument_html_dump_mem().
DomDocument->get_element_by_id
Description
object DomDocument->get_element_by_id ( string id)This function is similar to DomDocument_get_elements_by_tagname() but searches for an element with a given id. According to the DOM standard this requires a DTD which defines the attribute ID to be of type ID, though the current implementation simply does an xpath search for "//*[@ID = '%s']". This does not comply to the DOM standard which requires to return null if it is not known which attribute is of type id. This behaviour is likely to be fixed, so do not rely on the current behaviour.
See also DomDocument_get_elements_by_tagname()
DomDocument->get_elements_by_tagname
Description
array DomDocument->get_elements_by_tagname ( string name)
See also DomDocument_add_root()
DomDocument->html_dump_mem
Description
string DomDocument->html_dump_mem ( void)Creates an HTML document from the dom representation. This function usually is called after building a new dom document from scratch as in the example below.
Exemple 1. Creating a simple HTML document header
|
See also DomDocument_dump_file(), DomDocument_html_dump_mem().
DomDocumentType->entities
Description
array DomDocumentType->entities ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomDocumentType->internal_subset
Description
bool DomDocumentType->internal_subset ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomDocumentType->name
Description
string DomDocumentType->name ( void)This function returns the name of the document type.
DomDocumentType->notations
Description
array DomDocumentType->notations ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomDocumentType->public_id
Description
string DomDocumentType->public_id ( void)This function returns the public id of the document type.
The following example echos nothing.
DomDocumentType->system_id
Description
string DomDocumentType->system_id ( void)Returns the system id of the document type.
The following example echos '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'.
DomElement->get_attribute_node
Description
object DomElement->get_attribute_node ( object attr)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomElement->get_attribute
Description
object DomElement->get_attribute ( string name)Returns the attribute with name name of the current node.
See also DomElement_set_attribute()
DomElement->get_elements_by_tagname
Description
bool DomElement->get_elements_by_tagname ( string name)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomElement->has_attribute
Description
bool DomElement->has_attribute ( string name)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomElement->remove_attribute
Description
bool DomElement->remove_attribute ( string name)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomElement->set_attribute
Description
bool DomElement->set_attribute ( string name, string value)Sets an attribute with name name ot the given value. If the attribute does not exist, it will be created.
See also DomElement_get_attribute()
DomElement->tagname
Description
string DomElement->tagname ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomNode->append_child
Description
object DomNode->append_child ( object newnode)This functions appends a child to an existing list of children or creates a new list of children. The child can be created with e.g. DomDocument_create_element(), DomDocument_create_text() etc. or simply by using any other node.
Before a new child is appended it is first duplicated. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of a xml document. The return value is the appended child. If you plan to do further modifications on the appended child you must use the returned node.
The following example will add a new element node to a fresh document and sets the attribute "align" to "left".
Exemple 3. Adding a child
|
See also DomNode_insert_before().
DomNode->append_sibling
Description
object DomNode->append_sibling ( object newnode)This functions appends a sibling to an existing node. The child can be created with e.g. DomDocument_create_element(), DomDocument_create_text() etc. or simply by using any other node.
Before a new sibling is added it is first duplicated. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of a xml document. The return value is the added sibling. If you plan to do further modifications on the added sibling you must use the returned node.
This function has been added to provide the behaviour of DomNode_append_child() as it works till PHP 4.2.
See also DomNode_append_before().
DomNode->attributes
Description
array DomNode->attributes ( void)This function only returns an array of attributes if the node is of type XML_ELEMENT_NODE.
DomNode->child_nodes
Description
array DomNode->child_nodes ( void)Returns all children of the node.
See also DomNode_next_sibling(), DomNode_previous_sibling().
DomNode->clone_node
Description
object DomNode->clone_node ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomNode->dump_node
Description
string DomNode->dump_node ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
See also DomDocument_dump_mem().
DomNode->first_child
Description
bool DomNode->first_child ( void)Returns the first child of the node.
See also DomNode_last_child(), DomNode_next_sibling(), DomNode_previous_sibling().
DomNode->get_content
Description
string DomNode->get_content ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomNode->has_attributess
Description
bool DomNode->has_attributes ( void)This function checks if the node has attributes.
See also DomNode_has_child_nodes().
DomNode->has_child_nodes
Description
bool DomNode->has_child_nodes ( void)This function checks if the node has children.
See also DomNode_child_nodes().
DomNode->insert_before
Description
object DomNode->insert_before ( object newnode, object refnode)This function inserts the new node newnode right before the node refnode. The return value is the inserted node. If you plan to do further modifications on the appended child you must use the returned node.
DomNode_insert_before() is very similar to DomNode_append_child() as the following example shows which does the same as the example at DomNode_append_child().
Exemple 1. Adding a child
|
See also DomNode_append_child().
DomNode->is_blank_node
Description
bool DomNode->is_blank_node ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomNode->last_child
Description
object DomNode->last_child ( void)Returns the last child of the node.
See also DomNode_first_child(), DomNode_next_sibling(), DomNode_previous_sibling().
DomNode->next_sibling
Description
object DomNode->next_sibling ( void)This function returns the next sibling of the current node. If there is no next sibling it returns false. You can use this function to iterate over all children of a node as shown in the example.
Exemple 1. Iterate over children
|
See also DomNode_previous_sibling().
DomNode->node_name
Description
string DomNode->node_name ( void)Returns name of the node. The name has different meanings for the different types of nodes as illustrated in the following table.
Tableau 1. Meaning of value
| Type | Meaning |
|---|---|
| DomAttribute | value of attribute |
| DomAttribute | |
| DomCDataSection | #cdata-section |
| DomComment | #comment |
| DomDocument | #document |
| DomDocumentType | document type name |
| DomElement | tag name |
| DomEntity | name of entity |
| DomEntityReference | name of entity reference |
| DomNotation | notation name |
| DomProcessingInstruction | target |
| DomText | #text |
DomNode->node_type
Description
int DomNode->node_type ( void)Returns the type of the node. All possible types are listed in the table in the introduction.
DomNode->node_value
Description
string DomNode->node_value ( void)Returns value of the node. The value has different meanings for the different types of nodes as illustrated in the following table.
Tableau 1. Meaning of value
| Type | Meaning |
|---|---|
| DomAttribute | value of attribute |
| DomAttribute | |
| DomCDataSection | content |
| DomComment | content of comment |
| DomDocument | null |
| DomDocumentType | null |
| DomElement | null |
| DomEntity | null |
| DomEntityReference | null |
| DomNotation | null |
| DomProcessingInstruction | entire content without target |
| DomText | content of text |
DomNode->owner_document
Description
object DomNode->owner_document ( void)This function returns the document the current node belongs to.
The following example will create two identical lists of children.
See also DomNode_insert_before().
DomNode->parent_node
Description
object DomNode->parent_node ( void)This function returns the parent node.
The following example will show two identical lists of children.
DomNode->prefix
DomNode->previous_sibling
Description
object DomNode->previous_sibling ( void)This function returns the previous sibling of the current node.
See also DomNode_next_sibling().
DomNode->remove_child
Description
object DomNode->remove_child ( object oldchild)This functions removes a child from a list of children. If child cannot be removed or is not a child the function will return false. If the child could be removed the functions returns the old child.
Exemple 1. Removing a child
|
See also DomNode_append_child().
DomNode->replace_child
Description
object DomNode->replace_child ( object oldnode, object newnode)This function replaces the child oldnode with the passed new node. If the new node is already a child it will not be added a second time. If the old node cannot be found the function returns false. If the replacement succeds the old node is returned.
See also DomNode_append_child()
DomNode->replace_node
Description
object DomNode->replace_node ( object newnode)This function replaces an existing node with the passed new node. Before the replacement newnode is copied if it has a parent to make sure a node which is already in the document will not be inserted a second time. This behaviour enforces doing all modifications on the node before the replacement or to refetch the inserted node afterwards with functions like DomNode_first_child(), DomNode_child_nodes() etc..
See also DomNode_append_child()
DomNode->set_content
Description
bool DomNode->set_content ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomNode->set_name
DomNode->unlink_node
Description
object DomNode->unlink_node ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomProcessingInstruction->data
Description
string DomProcessingInstruction->data ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
DomProcessingInstruction->target
Description
string DomProcessingInstruction->target ( void)
| Avertissement |
This function is currently not documented, only the argument list is available. |
domxml_new_doc
Description
object domxml_new_doc ( string version)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Creates a new dom document from scratch and returns it.
See also DomDocument_add_root()
domxml_open_file
Description
object domxml_open_file ( string filename)The function parses the XML document in the file named filename and returns an object of class "Dom document", having the properties as listed above. The file is accessed read-only.
See also domxml_open_mem(), domxml_new_doc().
domxml_open_mem
Description
object domxml_open_mem ( string str)The function parses the XML document in str and returns an object of class "Dom document", having the properties as listed above. This function, domxml_open_file() or domxml_new_doc() must be called before any other function calls.
See also domxml_open_file(), domxml_new_doc().
domxml_version
Description
string domxml_version ( void)This function returns the version of the XML library version currently used.
domxml_xmltree
Description
object domxml_xmltree ( string str)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function parses the XML document in str and returns a tree PHP objects as the parsed document. This function is isolated from the other functions, which means you cannot access the tree with any of the other functions. Modifying it, for example by adding nodes, makes no sense since there is currently no way to dump it as an XML file. However this function may be valuable if you want to read a file and investigate the content.
xpath_eval_expression
Description
array xpath_eval_expression ( object xpath_context)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
See also xpath_eval()
xpath_eval
Description
array xpath_eval ( object xpath_context)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Pas de documentation encore (22/2/2201).
xpath_new_context
Description
object xpath_new_context ( object dom_document)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Pas de documentation encore (22/2/2201).
xptr_eval
Description
int xptr_eval ( [object xpath_context, string eval_str])
| Avertissement |
This function is currently not documented, only the argument list is available. |
xptr_new_context
dotnet_load
Description
int dotnet_load ( string assembly_name [, string datatype_name [, int codepage]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
XXVII. Gestion des erreurs
Ces fonctions permettent de gérer les erreurs, et de les enregistrer. Vous pouvez définir les règles de traitement des erreurs et choisir la manière de les enregistrer : vous pouvez adapter le rapport d'erreurs à vos besoins.
Avec les fonctions d'enregistrements, vous pouvez envoyer directement les rapports à d'autres machines (ou même les envoyer par email à un pager), à l'historique système, ou encore sélectionner les erreurs les plus importantes et ne pas enregistrer les autres.
La fonction de niveau d'erreur vous permet de personnaliser le niveau et le type d'erreur noté : depuis les inoffensives alertes jusqu'au erreurs personnalisées retournées par les fonctions.
- Table des matières
- error_log -- Envoie un message d'erreur quelque part
- error_reporting -- Fixe le niveau de rapport d'erreurs PHP
- restore_error_handler -- Réactive l'ancienne fonction de gestion des erreurs
- set_error_handler -- Choisi une fonction utilisateur comme gestionnaire d'erreurs
- trigger_error -- Déclenche une erreur utilisateur
- user_error -- Génère un message d'erreur utilisateur
error_log
Description
int error_log ( string message, int message_type [, string destination [, string extra_headers]])error_log() envoie un message d'erreur à l'historique du serveur web, à un port TCP ou un fichier. message est le message d'erreur qui doit être enregistré. message_type indique où le message doit être envoyé :
Tableau 1. Types de error_log()
| 0 | message est envoyé à l'historique PHP, qui est basé sur l'historique système ou un fichier, en fonction de la configuration de error_log. |
| 1 | message est envoyé par email à l'adresse destination. C'est le seul type qui utilise le quatrième paramètre extra_headers. Ce message utilise la même fonction interne que mail(). |
| 2 | message est envoyé par la connexion de debuggage PHP. Cette option n'est disponible que si l'option remote_debugging a été désactivée. Dans ce cas, le paramètre destination spécifie l'hôte ou l'adresse IP, et optionnellement le numéro de port, de la socket qui recevra les informations de débuggage. |
| 3 | message est ajouté au fichier destination. |
| Avertissement |
Le débuggage à distance via TCP/IP est une fonctionnalité PHP 3 qui n'est pas disponible en PHP 4. |
Exemple 1. Exemples avec error_log()
|
error_reporting
Description
int error_reporting ( [int level])error_reporting() fixe le niveau de rapport d'erreur PHP et retourne l'ancienne valeur. Le niveau d'erreur peut être un champs de bits, ou une constante. 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, l'intervalle de validité des niveaux évolue, et les anciennes valeurs n'ont plus les mêmes significations.
Exemple 1. Exemple de modification de niveau d'erreur
|
Tableau 1. Constantes avec error_reporting()
| constante | valeur |
|---|---|
| 1 | E_ERROR |
| 2 | E_WARNING |
| 4 | E_PARSE |
| 8 | E_NOTICE |
| 16 | E_CORE_ERROR |
| 32 | E_CORE_WARNING |
| 64 | E_COMPILE_ERROR |
| 128 | E_COMPILE_WARNING |
| 256 | E_USER_ERROR |
| 512 | E_USER_WARNING |
| 1024 | E_USER_NOTICE |
Exemple 2. Exemples avec error_reporting()
|
restore_error_handler
Description
void restore_error_handler ( void)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).
Voir aussi error_reporting(), set_error_handler(), trigger_error() et user_error()
set_error_handler
Description
string set_error_handler ( string error_handler)set_error_handler() choisit la fonction utilisateur error_handler pour gérer les erreurs dans un script. Retourne un pointeur sur l'ancienne fonction de gestion des erreurs (si il y en avait une), ou FALSE, en cas d'erreur. set_error_handler() sert à définir votre propre gestionnaire d'erreurs, qui prendra en charge leur traitement durant l'exécution d'un script. Cela peut être utile lorsque vous devez repérer des erreurs critiques lors d'un nettoyage de bases, ou bien si vous souhaitez générer une erreur dans certaines conditions (avec trigger_error()).
La fonction utilisateur doit accepter deux arguments : le code de l'erreur, et une chaîne décrivant l'erreur. L'exemple ci dessous montre le traitement d'exceptions en déclenchant des erreurs, et en les gérant avec une fonction utilisateur :
Exemple 1. Traitement des erreurs avec set_error_handler() et trigger_error()
|
vector a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vector b - une alerte (b = log(PI) * a)
<B>WARNING</B> [1024] La valeur à la position 2 n'est pas un nombre. On utilise 0 (zéro) à la place<br>
Array
(
[0] => 2.2894597716988
[1] => 3.4341896575482
[2] => 0
[3] => 6.2960143721717
[4] => 49.566804057279
[5] => 24.165247890281
)
----
vector c - an error
<B>ERROR</B> [512] Vecteur d'entrée incorrect : un tableau de valeur est attendu<br>
NULL
----
vector d - fatal error
<B>FATAL</B> [256] log(x) de x <= 0 est indéfini : scale = -2.5<br>
Erreur fatale à la ligne 16 du fichier trigger_error.php, PHP 4.0.1pl2 (Linux)<br>
Annulation du script....<br> |
Il faut se rappeler que la fonction standard de traitement des erreurs de PHP est alors complètement ignorée. error_reporting() n'aura plus d'effet, et votre fonction de gestion des erreurs sera toujours appelée. Vous pourrez toujours lire la valeur de l'erreur courante de error_reporting() et faire réagir la fonction de gestion des erreurs en fonction. Cette remarque est notamment valable si la commande a été préfixée par @ (0 sera retourné).
Notez aussi qu'il est alors confié à cette fonction de terminer le script (die()) si nécessaire. Si la fonction de gestion des erreurs se termine normalement, l'exécution du script se poursuivra avec l'exécution de la prochaine commande.
Voir aussi error_reporting(), restore_error_handler(), trigger_error() et user_error()
trigger_error
Description
void trigger_error ( string error_msg [, int error_type])trigger_error() est utilisé pour déclencher une erreur utilisateur. Elle peut aussi être utilisée en conjonction avec un gestionnaire d'erreur interne, ou un gestionnaire d'erreurs utilisateur qui a été choisi comme gestionnaire d'erreur avec set_error_handler().
trigger_error() est pratique lorsque vous devez générer une réponse particulière lors de l'exécution. Par exemple :
<?php
if (assert ($divisor == 0))
trigger_error ("Impossible de diviser par zéro", E_USER_ERROR);
?> |
Note : Voir aussi set_error_handler() pour illustration.
Voir aussi error_reporting(), set_error_handler(), restore_error_handler() et user_error()
user_error
Description
void user_error ( string error_msg [, int error_type])user_error() est un alias de la fonction trigger_error().
Voir aussi error_reporting(), set_error_handler(), restore_error_handler() et trigger_error().
XXVIII. FrontBase
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Ces fonctions vous permettent d'accéder aux serveurs SQL FrontBase. Pour pouvoir les utiliser, vous devez compiler PHP avec le support fbsql en utilisant l'option --with-fbsql. Si vous utilisez cette option sans spécifier le chemin jusqu'à l'installation fbsql, PHP recherchera les librairies du client fbsql dans les dossiers habituels, sur votre système. Les utilisateurs qui ont installé FrontBase dans un dossier non standard doivent spécifier le chemin comme ceci : --with-fbsql=/path/to/fbsql. Cela va indiquer à PHP le bon emplacement des librairies de FrontBase, et éviter les conflits.
Plus d'informations sur FrontBase sont disponibles à http://www.frontbase.com/.
La documentation complète de FrontBase est disponible à http://www.frontbase.com/cgi-bin/WebObjects/FrontBase.woa/wa/productsPage?currentPage=Documentation.
Le support de Frontbase a été ajouté en PHP 4.0.6.
- Table des matières
- fbsql_affected_rows -- Lit le nombre de ligne affectées par la dernière requête
- fbsql_autocommit -- Active ou désactive la validation automatique.
- fbsql_change_user -- Change le nom d'utilisateur de la session active
- fbsql_close -- Ferme la connexion FrontBase
- fbsql_commit -- Valide une transaction
- fbsql_connect -- Ouvre une connexion à un serveur FrontBase
- fbsql_create_blob -- Crée un BLOB
- fbsql_create_clob -- Crée un CLOB
- fbsql_create_db -- Crée une base de données
- fbsql_data_seek -- Déplace le pointeur interne de résultat
- fbsql_database_password -- Modifie/lit le mot de passe dans une base FBSQL
- fbsql_database -- Get or set the database name used with a connection
- fbsql_db_query -- Envoie une requête à la base FrontBase
- fbsql_db_status -- Lit le statut courant d'une base de données
- fbsql_drop_db -- Supprime une base de données FrontBase
- fbsql_errno -- Retourne le code d'erreur FrontBase
- fbsql_error -- Retourne le message d'erreur FrontBase
- fbsql_fetch_array -- Lit toute une ligne de résultat dans un tableau.
- fbsql_fetch_assoc -- Lit toute une ligne de résultat dans un tableau associatif
- fbsql_fetch_field -- Lit des informations sur une colonne dans un résultat, et retourne un objet
- fbsql_fetch_lengths -- Lit la taille de chaque colonne d'un résultat
- fbsql_fetch_object -- Lit une ligne de résultat sous forme d'objet
- fbsql_fetch_row -- Lit une ligne de résultat sous forme de tableau numérique
- fbsql_field_flags -- Lit les options associé à une colonne de résultat
- fbsql_field_len -- Retourne la taille d'un champs
- fbsql_field_name -- Lit le nom d'un champs
- fbsql_field_seek -- Déplace le pointeur de résultat
- fbsql_field_table -- Lit le nom de la table d'origine d'un champs
- fbsql_field_type -- Lit le type d'une colonne
- fbsql_free_result -- Libère le résultat de la mémoire
- fbsql_get_autostart_info -- No description given yet
- fbsql_hostname -- Get or set the host name used with a connection
- fbsql_insert_id -- Lit le dernier identifiant généré par une requête INSERT
- fbsql_list_dbs -- Liste les bases de données
- fbsql_list_fields -- Liste les champs d'un résultat FrontBase
- fbsql_list_tables -- Liste les tables dans une base de données FrontBase
- fbsql_next_result -- Déplace le pointeur interne vers le résultat suivant
- fbsql_num_fields -- Lit le nombre de champs dans un résultat
- fbsql_num_rows -- Lit le nombre de lignes dans un résultat
- fbsql_password -- Get or set the user password used with a connection
- fbsql_pconnect -- Ouvre une connexion persistante à un serveur FrontBase
- fbsql_query -- Exécute une requête sur un serveur FrontBase
- fbsql_read_blob -- Lit un BLOB dans une base de données
- fbsql_read_clob -- Lit un CLOB dans une base de données
- fbsql_result -- Lit des données dans un résultat
- fbsql_rollback -- Annule une transaction
- fbsql_select_db -- Sélectionne une base de données FrontBase
- fbsql_set_lob_mode -- Modifie le mode de lecture des LOB
- fbsql_set_transaction -- Set the transaction locking and isolation
- fbsql_start_db -- Démarre une base de données
- fbsql_stop_db -- Stoppe une base de données
- fbsql_tablename -- Lit le nom de la table d'un champs
- fbsql_username -- Get or set the host user used with a connection
- fbsql_warnings -- Active ou désactive les alertes FrontBase
fbsql_affected_rows
Description
int fbsql_affected_rows ( [resource link_identifier])fbsql_affected_rows() retourne le nombre de lignes affectées par la dernière requête INSERT, UPDATE ou DELETE, effectuée avec la connexion représentée par link_identifier. Si ce dernier n'est pas spécifié, c'est la dernière connexion ouverte par fbsql_connect() qui sera utilisée.
Note : Si vous utilisez les transactions, vous devez appeler fbsql_affected_rows() après votre requête INSERT, UPDATE ou DELETE, mais pas après la validation.
Si la dernière requête DELETE ne contenait pas de clause WHERE, toutes les lignes seront effacées, mais fbsql_affected_rows() retournera 0.
Note : Lors d'une requête UPDATE, FrontBase ne modifie pas les lignes dont les anciennes valeurs sont égales aux nouvelles. Cela fait que fbsql_affected_rows() ne retournera pas le nombre de ligne traitées, mais le nombre de lignes affectées (modifiées) par la requête.
Si la dernière requête échoue, fbsql_affected_rows() retourne -1.
Voir aussi fbsql_num_rows().
fbsql_autocommit
Description
boolean fbsql_autocommit ( resource link_identifier [, boolean OnOff])fbsql_autocommit() retourne l'état courant de la validation automatique, pour la connexion link_identifier. Si le paramètre OnOff est fourni, et vaut TRUE, FBSQL va se mettre en mode d'auto-validation, et les requêtes seront validées automatiquement si aucune erreur n'est trouveé. Si le paramètre OnOff est fourni, et vaut FALSE, FBSQL va se mettre en mode de validation manuelle, et les requêtes seront validées par l'appel de la fonction fbsql_commit() ou annulées par fbsql_rollback().
Voir aussi fbsql_commit() et fbsql_rollback()
fbsql_change_user
Description
resource fbsql_change_user ( string user, string password [, string database [, resource link_identifier]])fbsql_change_user() change le nom de l'utilisateur courant sur la session active courante, ou sur link_identifier. Si une base de données est spécifiée avec le paramètre database, elle deviendra la base par défaut du nouvel utilisateur. Le nouvel utilisateur doit être spécifié par son login (user), et son mot de passe (password). Si l'authentification échoue, la session courante restera ouverte.
fbsql_close
Description
boolean fbsql_close ( [resource link_identifier])fbsql_close() retourne TRUE en cas de succès et FALSE en cas d'erreur.
fbsql_close() ferme la connexion au serveur FrontBase associé à la ressource link_identifier. Si link_identifier est omis, c'est la dernière connexion ouverte qui sera fermée.
Utiliser fbsql_close() n'est pas nécessaire, car les liens non persistants seront automatiquement fermé à la fin du script.
Voir aussi fbsql_connect() et fbsql_pconnect().
fbsql_commit
Description
bool fbsql_commit ( [resource link_identifier])fbsql_commit() retourne TRUE en cas de succès, et FALSE sinon.
fbsql_commit() termine la transaction courante en sauvant toutes les insertions, modifications et effacements sur le serveur, puis en relachant tous les verrous qui ont étés posés sur les tables. Cette commande n'est nécessaire que si FBSQL est en mode de validation manuelle.
Voir aussi fbsql_autocommit() et fbsql_rollback()
fbsql_connect
Description
resource fbsql_connect ( [string hostname [, string username [, string password]]])fbsql_connect() retourne une ressource de connexion positive en cas de succès, ou un message d'erreur en cas d'échec.
fbsql_connect() établit une connexion avec un serveur FrontBase. Les valeur suivantes sont utilisées, en cas d'omission : hostname = 'NULL', username = '_SYSTEM' et password = "" (pas de mot de passe).
Si un deuxième appel est fait à fbsql_connect() avec les mêmes arguments, une nouvelle connexion ne sera pas générée, mais la connexion déjà ouverte sera reutilisée, et retournée.
La connexion au serveur sera fermée dès la fin du scrpit, à moins qu'elle ne soit explicitement terminée plus tôt, avec la fonction fbsql_close().
Voir aussi fbsql_pconnect() et fbsql_close().
fbsql_create_blob
Description
string fbsql_create_blob ( string blob_data [, resource link_identifier])fbsql_create_blob() retourne une ressource qui représente le nouveau BLOB.
fbsql_create_blob() crée un blob à partir des données fournies par blob_data. La ressource retournée est nécessaire aux commandes de modification et d'insertion, pour sauver le BLOB dans la base de données.
Exemple 1. Exemple avec fbsql_create_blob()
|
Voir aussi fbsql_create_clob(), fbsql_read_blob(), fbsql_read_clob() et fbsql_set_lob_mode().
fbsql_create_clob
Description
string fbsql_create_clob ( string clob_data [, resource link_identifier])fbsql_create_clob() retourne une ressource qui représente le nouveau CLOB.
fbsql_create_clob() crée un clob à partir des données fournies par clob_data. La ressource retournée est nécessaire aux commandes de modification et d'insertion, pour sauver le BLOB dans la base de données. creates a clob from
Exemple 1. Exemple avec fbsql_create_clob()
|
Voir aussi fbsql_create_blob(), fbsql_read_blob(), fbsql_read_clob() et fbsql_set_lob_mode().
fbsql_create_db
Description
boolean fbsql_create_db ( string database_name [, resource link_identifier])fbsql_create_db() crée une nouvelle base de données, nommée database_name, sur le serveur repéré par la ressource link_identifier.
Voir aussi fbsql_drop_db().
fbsql_data_seek
Description
int fbsql_data_seek ( int result_identifier, int row_number)fbsql_data_seek() retourne TRUE en cas de succès et FALSE en cas d'erreur.
fbsql_data_seek() déplace le pointeur interne de ligne dans le résultat de requête result_identifier jusqu'à la ligne row_number. Le prochain appel à fbsql_fetch_row() retournera cette ligne.
Les lignes sont numérotées à partir de 0.
Exemple 1. Exemple avec fbsql_data_seek()
|
fbsql_database_password
Description
string fbsql_database_password ( resource link_identifier [, string database_password])fbsql_database_password() retourne le mot de passe du serveur représenté par link_identifier.
fbsql_database_password() modifie et lit le mot de passe de la base de données courante. Si le second paramètre database_password est fourni, fbsql_database_password() remplacera le mot de passe courant par celui-ci. Si aucun serveur n'est précisé car le paramètre link_identifier n'est pas fourni, la dernière connexion ouverte sera utilisée. Si aucune connexion n'a été ouvertem PHP essaiera d'en ouvrir une en appelant la fonction fbsql_connect(), et en utilisant la connexion qui en résultera (si elle réussit).
Voir aussi fbsql_connect() et fbsql_pconnect().
fbsql_database
Description
string fbsql_database ( resource link_identifier [, string database])
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_db_query
Description
resource fbsql_db_query ( string database, string query [, resource link_identifier])fbsql_db_query() retourne une ressource positive représentant un résultat de requête en cas de succès, et FALSE en cas d'erreur.
fbsql_db_query() sélectionne la base database et y exécute la requête query. Si le paramètre optionnel link_identifier est spécifié, fbsql_db_query() travaillera sur cette connexion. S'il est omis, fbsql_db_query() essaiera d'utiliser la dernière connexion ouverte. Si aucune connexion n'a été ouverte, fbsql_db_query() essaiera de se connecter automatiquement en appelant la fonction fbsql_connect(), sans arguments.
Voir aussi fbsql_connect().
fbsql_db_status
Description
int fbsql_db_status ( string database_name [, resource link_identifier])fbsql_db_status() retourne un entier représentant le statut courant.
fbsql_db_status() demande le statut de la base de données nommée database_name. Si le paramètre link_identifier est omis, la connexion par défaut sera utilisée.
La valeur de l'entier peut être l'une des suivantes :
FALSE - Le gestion de cet hôte était invalide. Cette erreur survient lorsque PHP se connecter directement à une base de données en utilisant un numéro de port. FBExec peut être disponible sur un serveur, mais aucune connexion n'a été faite.
FBSQL_UNKNOWN - Le statut est inconnu.
FBSQL_STOPPED - La base de données ne fonctionne pas. Utilisez fbsql_start_db() pour démarrer la base.
FBSQL_STARTING - La base de données démarre.
FBSQL_RUNNING - La base de données fonctionne, et est disponible pour recevoir des requêtes SQL.
FBSQL_STOPPING - La base de données s'arrête.
FBSQL_NOEXEC - FBExec ne fonctionne par sur le serveur, et il n'est pas possible d'obtenir le statut de la base de données.
Voir aussi fbsql_start_db() et fbsql_stop_db().
fbsql_drop_db
Description
boolean fbsql_drop_db ( string database_name [, resource link_identifier])fbsql_drop_db() retourne TRUE en cas de succès et FALSE en cas d'erreur.
fbsql_drop_db() essaie de supprimer la base de données database_name, sur la connexion représentée par link_identifier.
fbsql_errno
Description
int fbsql_errno ( [resource link_identifier])fbsql_errno() retourne le code d'erreur de la dernière connexion FrontBase, ou bien 0 (zéro) si aucune erreur n'est survenue.
Les erreurs générées par FrontBase ne sont pas automatiquement affichées comme alertes. Il faut utiliser la fonction fbsql_errno() pour connaître leur code d'erreur. Notez que cette fonction ne retourne que le code d'erreur généré par la dernière fonction FrontBase (hormis fbsql_error() et fbsql_errno()) : si vous voulez repérer les erreurs, faites le dès que les fonctions ont été appelées.
<?php
fbsql_connect("marliesle");
echo fbsql_errno().": ".fbsql_error()."<br>";
fbsql_select_db("nonexistentdb");
echo fbsql_errno().": ".fbsql_error()."<br>";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno().": ".fbsql_error()."<br>";
?> |
Voir aussi fbsql_error() et fbsql_warnings()
fbsql_error
Description
string fbsql_error ( [resource link_identifier])fbsql_error() retourne le dernier message d'erreur généré par le serveur FrontBase, ou bien '' (chaîne vide) si aucune erreur n'est survenue.
Les erreurs générées par FrontBase ne sont pas automatiquement affichées comme alertes. Il faut utiliser la fonction fbsql_errno() pour connaître leur code d'erreur. Notez que cette fonction ne retourne que le code d'erreur généré par la dernière fonction FrontBase (hormis fbsql_error() et fbsql_errno()) : si vous voulez repérer les erreurs, faites le dès que les fonctions ont été appelées.
<?php
fbsql_connect("marliesle");
echo fbsql_errno().": ".fbsql_error()."<br>";
fbsql_select_db("nonexistentdb");
echo fbsql_errno().": ".fbsql_error()."<br>";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno().": ".fbsql_error()."<br>";
?> |
Voir aussi fbsql_errno() et fbsql_warnings()
fbsql_fetch_array
Description
array fbsql_fetch_array ( resource result [, int result_type])fbsql_fetch_array() retourne un tableau contenant la ligne courante du résultat result, ou FALSE s'il n'y a plus de lignes.
fbsql_fetch_array() est une version améliorée de fbsql_fetch_row(). En plus de stocker les données dans un tableau à indice numérique, elle les stocke aussi sous forme de tableau associatif, dont les indices sont les noms des colonnes.
SI deux colonnes (ou plus) on le même nom, la dernière colonne sera utilisée. Pour accéder aux autres colonnes de même nom, vous devez absolument utiliser les indices numériques.
Il est important de noter que fbsql_fetch_array() n'est pas significativement plus lent que fbsql_fetch_row(), tandis qu'elle apporte un confort d'utilisation notable.
Le second argument optionnel result_type de fbsql_fetch_array() est une constante qui peut prendre l'une des valeurs suivantes : FBSQL_ASSOC, FBSQL_NUM et FBSQL_BOTH.
Pour plus de détails, reportez-vous à fbsql_fetch_row() et fbsql_fetch_assoc().
Exemple 1. Exemple avec fbsql_fetch_array()
|
fbsql_fetch_assoc
Description
array fbsql_fetch_assoc ( resource result)fbsql_fetch_assoc() retourne un tableau associatif contenant la ligne courante du résultat result, ou FALSE s'il n'y a plus de lignes.
fbsql_fetch_assoc() est équivalent à fbsql_fetch_array() avec l'option FBSQL_ASSOC. Elle ne retourne qu'un tableau associatif. C'est le comportement initial de fbsql_fetch_array(). Si vous avez aussi besoin des indices numériques, utilisez fbsql_fetch_array().
SI deux colonnes (ou plus) on le même nom, la dernière colonne sera utilisée. Pour accéder aux autres colonnes de même nom, vous devez absolument utiliser la fonction fbsql_fetch_array().
Il est important de noter que fbsql_fetch_assoc() n'est pas significativement plus lent que fbsql_fetch_row(), tandis qu'elle apporte un confort d'utilisation notable.
Pour plus de détails, reportez-vous à fbsql_fetch_row() et fbsql_fetch_array().
fbsql_fetch_field
(PHP 4 >= 4.0.6)
fbsql_fetch_field -- Lit des informations sur une colonne dans un résultat, et retourne un objetDescription
object fbsql_fetch_field ( resource result [, int field_offset])fbsql_fetch_field() retourne une objet contenant les informations sur un champs, dans le résultat result.
fbsql_fetch_field() sert à lire des informations sur les champs dans le résultat result. Si le second paramètre field_offset n'est pas spécifié, le champs suivant est lu.
Les propriétés de l'objet sont :
name - Nom de colonne
table - Nom de la table d'origine
max_length - Taille maximale de la colonne
not_null - 1 si la colonne ne peut être nulle
type - Type de la colonne
Exemple 1. Exemple avec fbsql_fetch_field()
|
Voir aussi fbsql_field_seek().
fbsql_fetch_lengths
Description
array fbsql_fetch_lengths ( [resource result])fbsql_fetch_lengths() retourne un tableau contenant les tailles maximales de chaque champs, dans la dernière ligne lue par fbsql_fetch_row() ou FALSE en cas d'erreur.
fbsql_fetch_lengths() stocke les tailles de chaque ligne de résultat retourné par fbsql_fetch_row(), fbsql_fetch_array() et fbsql_fetch_object() dans un tableau à indices numériques, commençant à 0.
Voir aussi fbsql_fetch_row().
fbsql_fetch_object
Description
object fbsql_fetch_object ( resource result [, int result_type])fbsql_fetch_object() retourne un objet dont les propriétés représentent les colonnes de la ligne à lire, dans le résultat result, ou FALSE s'il n'y a pas de ligne à lire.
fbsql_fetch_object() est similaire à fbsql_fetch_array(), à la différence qu'elle retourne un objet. Nous ne pouvez alors accéder aux données qu'avec les noms des colonnes, et sous la forme de membre d'objets, et non plus avec leurs offset (les nombres ne peuvent représenter un membre d'objet).
Le second argument optionnel result_type de fbsql_fetch_array() est une constante qui peut prendre l'une des valeurs suivantes : FBSQL_ASSOC, FBSQL_NUM et FBSQL_BOTH.
En terme de vitesse, cette fonction est identique à fbsql_fetch_array() et presque aussi rapide que fbsql_fetch_row() (la différence n'est pas significative).
Voir aussi fbsql_fetch_array() et fbsql_fetch_row().
fbsql_fetch_row
Description
array fbsql_fetch_row ( resource result)fbsql_fetch_row() retourne un tableau représentant la ligne courant dans le résultat result, ou bien FALSE s'il n'y a plus de lignes à lire.
fbsql_fetch_row() lit une ligne de données dans le résultat result, et crée un tableau numérique. Chaque colonne est stockés dans un élément du tableau, dans le même ordre que dans le résultat. Les indices commencent à 0.
Le prochain appel à fbsql_fetch_row() va lire la prochaine ligne, ou bien retourner FALSE s'il n'y a plus de lignes à lire.
Voir aussi fbsql_fetch_array(), fbsql_fetch_object(), fbsql_data_seek(), fbsql_fetch_lengths() et fbsql_result().
fbsql_field_flags
Description
string fbsql_field_flags ( resource result, int field_offset)fbsql_field_flags() retourne les options du champs field_offset, dans le résultat field_offset. Les options sont retournées sous la forme d'un seul mot par option, séparées par des espaces, de façons à faciliter la manipulation avec explode().
fbsql_field_len
Description
int fbsql_field_len ( resource result, int field_offset)fbsql_field_len() retourne la taille du champs field_offset dans le résultat result.
fbsql_field_name
Description
string fbsql_field_name ( int result, int field_index)fbsql_field_name() retourne le nom du champs numéro field_index dans le résultat result. field_index est le résultat de fbsql_query() et field_index est l'offset numérique du champs.
Note : field_index commence à 0.
e.g. L'index du troisème champs est 2, et l'index du quatrième champs est 3...
L'exemple ci-dessus va afficher :
fbsql_field_seek
Description
boolean fbsql_field_seek ( int result, int field_offset)fbsql_field_seek() place le pointeur de colonne à la colonne field_offset. Si ce paramètre est omis, fbsql_fetch_field() retourne le numéro de colonne courant.
Voir aussi fbsql_fetch_field().
fbsql_field_table
Description
string fbsql_field_table ( resource result, int field_offset)fbsql_field_table() retourn le nom de la table d'où est issue le champs d'offset field_offset. Les numéros de colonne commencent à 0.
fbsql_field_type
Description
string fbsql_field_type ( resource result, int field_offset)fbsql_field_type() est similaire à la fonction fbsql_field_name(). Les arguments sont identiques, mais le type du champs est retourné. Il peut valoir "int", "real", "string", "blob" ou d'autres valeurs, comme décrit dans la documentation FrontBase.
Exemple 1. Exemple avec fbsql_field_type()
|
fbsql_free_result
Description
bool fbsql_free_result ( resource result)fbsql_free_result() va libérer toute la mémoire utilisée par le résultat associé à la ressource result.
fbsql_free_result() n'a besoin d'être appelé que si vous craignez que votre script ne va consommer trop de mémoire, lorsqu'une requête retourne de très grand résultats. Toutes les ressources mémoire utilisées par le script sont de toutes manières libérées à la fin du script.
fbsql_get_autostart_info
Description
array fbsql_get_autostart_info ( [resource link_identifier])
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_hostname
Description
string fbsql_hostname ( resource link_identifier [, string host_name])
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_insert_id
Description
int fbsql_insert_id ( [resource link_identifier])fbsql_insert_id() retourne l'identifiant généré par la colonne de type DEFAULT UNIQUE, lors de la dernière requête INSERT, avec la connexion link_identifier. Si link_identifier est omis, la dernière connexion ouverte est utilisée.
fbsql_insert_id() retournera 0 si la dernière requête n'a pas généré de valeur dans la colonne DEFAULT UNIQUE Si vous devez sauver cette valeur pour plus tard, n'oubliez pas d'appeler fbsql_insert_id() tout de suite après la requête qui a généré cette valeur.
Note : La valeur de la fonction FrontBase SQL "LAST_INSERT_ID()" retourne toujours la dernière valeur générée par DEFAULT UNIQUE et n'est jamais annulée entre les requêtes.
fbsql_list_dbs
Description
resource fbsql_list_dbs ( [resource link_identifier])fbsql_list_dbs() retourne un résultat contenant la liste des bases de données disponibles sur le serveur [link_identifier]. Utilisez la fonction fbsql_tablename() pour passer en revue ce résultat.
L'exemple ci-dessus va afficher ceci :
Note : L'exemple ci-dessus peut aussi bien fonctionner avec la fonction fbsql_fetch_row() ou toute autre similaire.
fbsql_list_fields
Description
resource fbsql_list_fields ( string database_name, string table_name [, resource link_identifier])fbsql_list_fields() lit les informations à propos de la table table_name, dans la base de données table_name, sur la connexion link_identifier. Un résultat de requête est retourné, et pourra être utilisé avec les fonctions fbsql_field_flags(), fbsql_field_len(), fbsql_field_name() et fbsql_field_type().
Un identifiant de résultat est une ressource PHP, représentée par un entier positif. fbsql_list_fields() retourne -1 en cas d'erreur. Une chaîne décrivant l'erreur sera alors placée dans la variable $phperrmsg. Un message d'erreur sera aussi affiché, à moins que la fonction n'ai été appelée avec l'opérateur de suppression des erreurs @.
L'exemple ci-dessus va afficher :
fbsql_list_tables
Description
resource fbsql_list_tables ( string database [, resource link_identifier])fbsql_list_tables() liste les tables dans la base de données database, et retourne un résultat, tout comme fbsql_db_query(). fbsql_tablename() sert à extraire la liste des tables dans ce résultat.
fbsql_next_result
Description
bool fbsql_next_result ( resource result_id)Lorsque vous envoyez plus d'une commande SQL au serveur, ou que vous exécutez une procédure stockée avec de multiple résultats, cela va conduire le serveur à retourner plusieurs jeu de lignes. fbsql_next_result() va vérifier l'existence de plusieurs résultats disponibles sur le serveur. Si un autre jeu de résultat existe, fbsql_next_result() va détruire de résultat précédent, et préparer la lecture dans les nouvelles lignes.
fbsql_next_result() retourne TRUE si un autre résultat est disponbile, ou FALSE sinon.
Exemple 1. Exemple avec fbsql_next_result()
|
fbsql_num_fields
Description
int fbsql_num_fields ( resource result)fbsql_num_fields() retourne le nombre de champs dans le résultat result.
Voir aussi fbsql_db_query(), fbsql_query(), fbsql_fetch_field() et fbsql_num_rows().
fbsql_num_rows
Description
int fbsql_num_rows ( resource result)fbsql_num_rows() retourne le nombre de lignes dans le résultat result. Cette fonction n'est valable qu'avec les commandes SELECT. Pour connaître le nombre de lignes dans une requête INSERT, UPDATE ou DELETE, utilisez fbsql_affected_rows().
Voir aussi fbsql_affected_rows(), fbsql_connect(), fbsql_select_db() et fbsql_query().
fbsql_password
Description
string fbsql_password ( resource link_identifier [, string password])
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_pconnect
Description
resource fbsql_pconnect ( [string hostname [, string username [, string password]]])fbsql_pconnect() retourne une ressource représentant la connection au serveur FrontBase en cas de succès, ou bien FALSE en cas d'erreur.
fbsql_pconnect() établit une connexion persistante à un serveur FrontBase. En cas d'omission, les valeurs suivantes sont utilisées par défaut : host ='localhost', username = nom de l'utilisateur qui possède le processus, et password = pas de mot de passe.
Pour choisir le port d'accès au serveur FrontBase, voyez fbsql_select_db().
fbsql_pconnect() se comporte comme fbsql_connect() avec deux différences majeures.
Premièrement, lors de la connexion, fbsql_pconnect() essaie de trouver une connexion permanante déjà ouverte sur cet hote, 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 (fbsql_close() ne terminera pas une connexion persistante établie par fbsql_pconnect()).
C'est pourquoi ce type de connexion est dite 'persistante'.
fbsql_query
Description
resource fbsql_query ( string query [, resource link_identifier])fbsql_query() envoie la requête query à la base de données courante, sur le serveur représenté par sa connexion link_identifier. Si link_identifier est omis, la dernière connexion ouverte est utilisée. Si aucune connexion n'a été ouverte, fbsql_query() essaie d'établir une connexion en appelant la fonction fbsql_connect() sans aucun argument.
Note : La requête doit être terminée par un point-virgule!
fbsql_query() retourne une ressource en cas de succès, ou FALSE, en cas d'échec.
La requête suivante est invalide, et fbsql_query() échouera puis retournera FALSE:
La requête suivante est invalide si my_col n'est pas une colonne dans la table my_tbl : fbsql_query() échouera puis retournera FALSE :
fbsql_query() échouera si vous n'avez pas les droits d'accès sur l'une des bases de données utilisée dans la requête.
Lorsque la requête réussit, vous pouvez utilisez fbsql_num_rows() pour savoir combien de lignes ont été retournée par une requête SELECT, ou bien fbsql_affected_rows() pour les autres requêtes (DELETE, INSERT, REPLACE et UPDATE).
Pour les requêtes SELECT, fbsql_query() retourne une ressource de résultat, que vous pouvez passer à fbsql_result(). Lors vous avez fini de lire le résultat, vous pouvez libérer les ressources utilisées en appelant fbsql_free_result(). Cependant, la mémoire sera automatiquement libérée à la fin du script.
Voir aussi fbsql_affected_rows(), fbsql_db_query(), fbsql_free_result(), fbsql_result(), fbsql_select_db() et fbsql_connect().
fbsql_read_blob
Description
string fbsql_read_blob ( string blob_handle [, resource link_identifier])fbsql_read_blob() retourne une chaîne de caractères contenant le BLOB blob_handle.
fbsql_read_blob() lit les données du BLOB dans la base de données. Si une sélection contient un BLOB et/ou une colonne de type BLOB, FrontBase retournera directement les données lors de la lecture. Ce comportement par défaut peut être modifié avec la fonction fbsql_set_lob_mode() pour que les fonctions de lectures ne retournent qu'un identifiant de BLOB ou CLOB. Si un identifiant est lu, il faut utiliser la fonction fbsql_read_blob() pour obtenir la valeur du BLOB.
Exemple 1. Exemple avec fbsql_read_blob()
|
Voir aussi fbsql_create_blob(), fbsql_read_blob(), fbsql_read_clob() et fbsql_set_lob_mode().
fbsql_read_clob
Description
string fbsql_read_clob ( string clob_handle [, resource link_identifier])fbsql_read_clob() retourne une chaîne de caractères contenant le CLOB clob_handle.
fbsql_read_clob() lit les données du CLOB dans la base de données. Si une sélection contient un CLOB et/ou une colonne de type CLOB, FrontBase retournera directement les données lors de la lecture. Ce comportement par défaut peut être modifié avec la fonction fbsql_set_lob_mode() pour que les fonctions de lectures ne retournent qu'un identifiant de BLOB ou CLOB. Si un identifiant est lu, il faut utiliser la fonction fbsql_read_clob() pour obtenir la valeur du CLOB.
Exemple 1. Exemple avec fbsql_read_blob()
|
Voir aussi fbsql_create_blob(), fbsql_read_blob(), fbsql_read_clob() et fbsql_set_lob_mode().
fbsql_result
Description
mixed fbsql_result ( resource result, int row [, mixed field])fbsql_result() lit le contenu du champs field, dans la ligne row, du résultat result. L'argument field peut être l'offset du champs, ou bien son nom, ou bien le nom de sa table plus point plus son nom. Si la colonne a été aliasée, utilisez de préférence l'alias.
Lorsque vous travaillez sur de grands résultats, il est vivement recommandé d'utiliser les fonctions qui lisent toute une ligne d'un coup, plutôt que fbsql_result() qui travaille ligne par ligne. Elles sont beaucoup plus rapides. Notez aussi que les offset numériques sont plus rapides que les offset nominaux.
L'utilisation de fbsql_result() ne doivent pas être mélangé avec d'autres fonctions qui utilisent aussi le résultat result.
Alternative vivement recommandées : fbsql_fetch_row(), fbsql_fetch_array() et fbsql_fetch_object().
fbsql_rollback
Description
bool fbsql_rollback ( [resource link_identifier])fbsql_rollback() retourne TRUE en cas de succès et FALSE sinon.
fbsql_rollback() termine la transaction courante en annulant toutes les requêtes émises depuis la dernière validation. Cette commande n'est utile que si FrontBase est en mode de validation manuelle.
Voir aussi fbsql_autocommit() et fbsql_commit()
fbsql_select_db
Description
resource fbsql_select_db ( string database_name [, resource link_identifier])fbsql_select_db() retourne TRUE en cas de succès et FALSE en cas d'erreur.
fbsql_select_db() remplace la base de données active courante par database_name, sur la connexion ouverte et représentée par link_identifier. Si link_identifier est omis, la dernière connexion ouverte sera utilisée. Si aucune connexion n'a été ouverte, fbsql_select_db() essaiera de se connecter en appelant fbsql_connect() sans argument.
Le client contacte FBExec pour connaître le numéro de port à utiliser pour la connexion à la base de données. Si le nom de la base est un numéro, le système l'utilisera comme numéro de port, et ne le demandera pas à FBExec. Le serveur Frontbase peut être démarré avec la commande : FRontBase -FBExec=No -port=<port number> <database name>.
Tous les prochains appel à fbsql_query() se feront dans la base database_name.
Voir aussi fbsql_connect(), fbsql_pconnect() et fbsql_query().
fbsql_set_lob_mode
Description
bool fbsql_set_lob_mode ( resource result, string database_name)fbsql_set_lob_mode() retourne TRUE en cas de succès et FALSE sinon.
fbsql_set_lob_mode() modifie le mode de lecture des LOB. Lorsque des données BLOB ou CLOB sont stockées dans une base de données FrontBase, elles peuvent l'être de manière directe ou indirecte. Si les données sont stockées directement, elles seront automatiquement lues, quelque soit le mode choisi. Si un LOB fait moins de 512 octets, il sera aussi stocké directement.
FBSQL_LOB_DIRECT - les données LOB sont lues directements. Lorsque les données sont lues dans la base avec fbsql_fetch_row() ou d'autres fonctions de lectures, toutes les colonnes de type CLOB et BLOB seront retournées comme des colonnes habituelles. C'est le comportement par défaut de FrontBase.
FBSQL_LOB_HANDLE - Les données LOB sont lues sous forme d'identifiant. Lorsque les données sont lues dans la base avec fbsql_fetch_row() ou d'autres fonctions de lectures, toutes les colonnes de type CLOB et BLOB seront retournées sous la forme d'un identifiant. Ce identifiant sera une chaîne de 27 caractères de long, formatée comme ceci : "@'000000000000000000000000'".
Voir aussi fbsql_create_blob(), fbsql_create_clob(), fbsql_read_blob() et fbsql_read_clob().
fbsql_set_transaction
Description
void fbsql_set_transaction ( resource link_identifier, int Locking, int Isolation)
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_start_db
Description
bool fbsql_start_db ( string database_name [, resource link_identifier])fbsql_start_db() retourne TRUE en cas de succès et FALSE sinon.
fbsql_start_db() démarre la base de données database_name sur la connexion link_identifier.
Voir aussi fbsql_db_status() et fbsql_stop_db().
fbsql_stop_db
Description
bool fbsql_stop_db ( string database_name [, resource link_identifier])fbsql_stop_db() retourne TRUE en cas de succès et FALSE sinon.
fbsql_stop_db() stoppe la base de données database_name sur la connexion link_identifier.
Voir aussi fbsql_db_status() et fbsql_start_db().
fbsql_tablename
Description
string fbsql_tablename ( resource result, int i)fbsql_tablename() retourne le nom de la table d'origine du champs i, dans le résultat result. La fonction fbsql_num_rows() peut être utilisée pour connaître le nombre de tables dans un résultat.
fbsql_username
Description
string fbsql_username ( resource link_identifier [, string username])
| Avertissement |
This function is currently not documented, only the argument list is available. |
fbsql_warnings
XXIX. FilePro
Ces fonctions permettent de lire des données enregistrées dans des bases non modifiables, sur des serveurs filePro.
filePro est une marque de fP Technologies, Inc. Vous pouvez avoir plus de détails sur filePro à http://www.fptech.com/.
- Table des matières
- filepro_fieldcount -- Retourne le nombre de champs dans une base filePro.
- filepro_fieldname -- Retourne le nom d'un champs.
- filepro_fieldtype -- Retourne le type d'un champs.
- filepro_fieldwidth -- Retourne la taille d'un champs.
- filepro_retrieve -- Retourne la valeur d'un champs.
- filepro_rowcount -- Retourne le nombre de champs dans une base filePro.
- filepro -- Lit et vérifie un fichier.
filepro_fieldcount
Description
int filepro_fieldcount ( void)filepro_fieldcount() retourne le nombre de champs (ou colonnes) d'une base filePro.
Voir aussi filepro().
filepro_fieldname
Description
string filepro_fieldname ( int field_number)filepro_fieldname() retourne le nom du champs d'index field_number.
filepro_fieldtype
Description
string filepro_fieldtype ( int field_number)filepro_fieldtype() retourne le type du champs d'index field_number.
filepro_fieldwidth
Description
int filepro_fieldwidth ( int field_number)filepro_fieldwidth() retourne la taille du champs d'index field_number.
filepro_retrieve
Description
string filepro_retrieve ( int row_number, int field_number)filepro_retrieve() retourne la valeur du champs d'index row_number, et à la ligne field_number.
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
filepro_rowcount
Description
int filepro_rowcount ( void)filepro_rowcount() retourne le nombre de lignes dans une base filePro.
Voir aussi filepro().
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
filepro
Description
boolean filepro ( string directory)filepro() lit et vérifie un fichier, puis enregistre le nombre de champs et de lignes.
Aucun verrouillage n'est pratiqué : il vaut alors mieux ne pas modifier la base filePro lorsqu'elle est ouverte par PHP.
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
XXX. Système de fichiers
- Table des matières
- basename -- Sépare le nom du fichier et le nom du dossier.
- chgrp -- Change le groupe possesseur du fichier.
- chmod -- Change le mode du fichier.
- chown -- Change le groupe propriétaire du fichier.
- clearstatcache -- Efface le cache de stat()
- copy -- Copie un fichier.
- delete -- Effacer
- dirname -- Renvoie le nom du dossier.
- disk_free_space -- Renvoie l'espace disque disponible dans le répertoire.
- disk_total_space -- Retourne la taille d'un dossier
- diskfreespace -- Alias de disk_free_space()
- fclose -- Ferme un fichier.
- feof -- Teste la fin du fichier.
- fflush -- Envoi tout le contenu généré dans un fichier
- fgetc -- Renvoie le caractère que pointe le pointeur du fichier.
- fgetcsv -- Renvoie la ligne courante et cherche les champs CSV
- fgets -- Renvoie la ligne courante sur laquelle se trouve le pointeur du fichier.
- fgetss -- Renvoie la ligne courante sur laquelle se trouve le pointeur du fichier et élimine les balises HTML
- file_exists -- Vérifie si un fichier existe.
- file_get_contents -- Reads entire file into a string
- file_get_wrapper_data -- Retrieves header/meta data from "wrapped" file pointers
- file_register_wrapper -- Register a URL wrapper implemented as a PHP class
- file -- Lit le fichier et renvoie le résultat dans un tableau.
- fileatime -- Renvoie la date à laquelle le fichier a été accédé pour la dernière fois.
- filectime -- Renvoie l'heure à laquelle l'inode a été accédé pour la dernière fois.
- filegroup -- Lire le nom du groupe
- fileinode -- Renvoie le numéro d'inode du fichier.
- filemtime -- Renvoie la date de dernière modification du fichier.
- fileowner -- Renvoie le nom du propriétaire du fichier.
- fileperms -- Renvoie les permissions affectées au fichier.
- filesize -- Renvoie la taille du fichier.
- filetype -- Retourne le type de fichier
- flock -- Verrouille le fichier.
- fopen -- Ouverture d'un fichier ou d'une URL.
- fpassthru -- Affiche la partie du fichier située après le pointeur du fichier.
- fputs -- Ecrit dans un fichier.
- fread -- Lecture du fichier en mode binaire.
- fscanf -- Analyse un fichier en fonction d'un format
- fseek -- Modifie le pointeur de fichier.
- fstat -- Lit les informations sur un fichier à partir d'un pointeur de fichier
- ftell -- Renvoie la position du pointeur du fichier.
- ftruncate -- Tronque un fichier.
- fwrite -- Ecriture du fichier en mode binaire.
- glob -- Find pathnames matching a pattern
- is_dir -- Indique si le nom de 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 un fichier est autorisé en lecture
- is_uploaded_file -- Indique si le fichier a été téléchargé par HTTP POST
- is_writable -- Indique si un fichier est autorisé en écriture.
- is_writeable -- Indique si un fichier est autorisé en écriture.
- link -- Crée un lien.
- linkinfo -- Renvoie les informations à propos d'un lien.
- lstat -- Renvoie les informations à propos d'un fichier ou d'un lien symbolique.
- mkdir -- Crée un dossier.
- move_uploaded_file -- Déplace un fichier téléchargé.
- parse_ini_file -- Traite un fichier de configuration
- pathinfo -- Retourne des informations sur un chemin système
- pclose -- Ferme un processus de pointeur de fichier.
- popen -- Crée un processus de pointeur de fichier.
- readfile -- Affiche un fichier.
- readlink -- Renvoie le nom du fichier vers lequel pointe un lien symbolique.
- realpath -- Retourne le chemin canonique absolu.
- rename -- Renomme un fichier.
- rewind -- Replace le pointeur de fichier au début.
- rmdir -- Efface un dossier.
- set_file_buffer -- Fixe la bufferisation de fichier
- 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 -- Affecte une nouvelle date de modification à un fichier.
- umask -- Change le "umask" courant.
- unlink -- Efface un fichier.
basename
Description
string basename ( string path [, string suffix])basename() prend en paramètre le chemin complet d'un fichier et en extrait le nom du fichier. Si [suffix] est fourni, le suffixe sera aussi supprimé.
Sous Windows, les caractères (/) et antislash (\) sont utilisés comme séparateurs de dossier. Sous les autres OS, seul le caractère slash (/) est utilisé.
Voir aussi dirname().
Note : suffix a été ajouté en PHP 4.1.0.
chgrp
Description
int chgrp ( string filename, mixed group)chgrp() essaie de changer le groupe propriétaire du fichier. 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.
chgrp() renvoie TRUE en cas de succès, sinon renvoie FALSE.
Voir aussi chown() et chmod().
Note : chgrp() ne fonctionne pas sous Windows.
chmod
Description
int chmod ( string filename, int mode)chmod() remplace le mode du fichier filename par le mode mode.
Il est à noter que le mode mode est considéré comme un nombre en notation octale. Afin de vous en assurer, vous pouvez préfixer cette valeur par un zéro (mode):
<?php chmod( "/somedir/somefile", 755 ); // notation décimale; probablement FALSE chmod( "/somedir/somefile", 0755 ); // notation octale; valeur du mode correcte ?> |
chmod() renvoie TRUE en cas de succès, FALSE sinon.
Voir aussi chown() et chgrp().
Note : chmod() ne fonctionne pas sous Windows.
chown
Description
int chown ( string filename, mixed user)chown() change le groupe propriétaire du fichier. Seul le super-utilisateur (root) peut changer le propriétaire arbitrairement d'un fichier.
chown() renvoie TRUE en cas de succès, "FALSE" sinon.
Note : Sous Windows, chown() ne fait rien et retourne TRUE.
Voir aussi chown() et chmod().
Note : chown() est inopérante sous Windows.
clearstatcache
Description
void clearstatcache ( void)L'appel à la fonction stat ou lstat est relativement coÛteux en terme 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. Si vous voulez forcer la vérification du statut d'un fichier, dans le cas où le fichier aurait pu être modifié ou aurait disparu, vous devez utiliser la fonction clearstatcache() afin d'effacer de la mémoire les résultats du dernier appel à la fonction.
La valeur du cache n'est valable que pour la durée d'une requête.
Les fonctions affectées sont : 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().
copy
Description
int copy ( string source, string dest)copy() fait une copie du fichier. Elle renvoie TRUE en cas de succès, FALSE sinon.
Voir aussi rename().
delete
Description
void delete ( string file)Ceci est une fausse entrée du manuel pour ceux qui recherchent en fait la fonction unlink() ou unset().
Voir aussi unlink() pour effacer des fichiers et unset() pour effacer des variables.
dirname
Description
string dirname ( string path)Si path contient le chemin d'un fichier ou dossier, dirname() retournera le nom du dossier qui le contient.
Sous Windows, les slash (/) et anti-slash (\) sont utilisés comme séparateurs de dossier. Dans les autres environnements, seul le slash (/) est utilisé.
Voir aussi basename().
disk_free_space
Description
float disk_free_space ( string directory)disk_free_space() retournera le nombre d'octets disponibles sur le disque correspondant contenant le dossier directory.
disk_total_space
Description
float disk_total_space ( string directory)disk_total_space() lit récursivement toutes les tailles du dossier directory et retourne la somme. directory peut être aussi une partition de disque.
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
diskfreespace
Description
float diskfreespace ( string directory)diskfreespace() est l'ancien nom de la fonction disk_free_space(). Elle est obsolète, et il est vivement recommandé d'utiliser disk_free_space().
fclose
Description
bool fclose ( resource fp)fclose() ferme le fichier fp.
fclose() retourne TRUE en cas de succès, et FALSE en cas d'échec.
Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen() ou fsockopen().
feof
Description
int feof ( resource fp)feof() retourne TRUE si le pointeur fp est à la fin du fichier, ou si une erreur survient, sinon, retourne FALSE.
Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen(), popen(), ou fsockopen().
fflush
Description
int fflush ( resource fp)fflush() force l'écriture de toutes les données bufferisées dans le fichier désigné par fp. fflush() retourne TRUE en cas de succès, et FALSE sinon.
fp est un pointeur de fichier ouvert avec fopen(), popen(), ou fsockopen().
fgetc
Description
string fgetc ( resource fp)fgetc() retourne une chaîne contenant un seul caractère, lu depuis le fichier pointé par fp. fgetc() retourne FALSE à la fin du fichier (tout comme feof()).
Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen(), popen(), ou fsockopen().
Voir aussi fread(), fopen(), popen(), fsockopen() et fgets().
fgetcsv
Description
array fgetcsv ( resource fp, int length [, string delimiter])Identique à fgets() mais fgetcsv() analyse la ligne qu'il lit et recherche les champs CSV, qu'il va retourner dans un tableau les contenant. Le délimiteur de champs delimiter est la virgule, à moins que vous ne fournissiez un troisième argument.
fp doit être un pointeur valide, et avoir été correctement ouvert par fopen(), popen(), ou fsockopen().
length doit être plus grand que la plus grande ligne trouvée dans un fichier CSV (en comptant les caractères de fin de ligne).
fgetcsv() retourne FALSE en cas d'erreur, ou en cas de fin du fichier.
Note : une ligne vide dans un fichier CSV sera retournée dans le tableau comme une chaîne vide, et ne sera pas traitée comme une erreur.
fgets
Description
string fgets ( int fp, int length)fgets() retourne la chaîne lue jusqu'à la longueur length - 1 octet, ou bien la fin du fichier, ou encore un retour chariot (le premier des trois qui sera rencontré).
Si une erreur survient, fgets() retourne FALSE.
Erreur courante :
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.
fp doit être valide, et avoir été correctement ouvert par fopen(), popen(), ou fsockopen().
Un exemple simple :
Voir aussi fread(), fopen(), popen(), fgetc(), fsockopen() et socket_set_timeout().
fgetss
(PHP 3, PHP 4 )
fgetss -- Renvoie la ligne courante sur laquelle se trouve le pointeur du fichier et élimine les balises HTMLDescription
string fgetss ( int fp, int length [, string allowable_tags])Identique à fgets(), mais fgetss() supprime toutes les balises HTML et PHP qu'il trouve dans le texte lu.
Vous pouvez aussi préciser les balises qui seront ignorées dans le troisième paramètre, optionnel.
Note : allowable_tags a été ajouté dans PHP 3.0.13, PHP 4B3.
Voir aussi fgets(), fopen(), fsockopen(), popen() et strip_tags().
file_exists
Description
int file_exists ( string filename)file_exists() retourne TRUE si le fichier filename existe, et FALSE sinon.
file_exists() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de file_exists() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
file_get_contents
Description
string file_get_contents ( string filename [, int use_include_path])Identical to readfile(), except that file_get_contents() returns the file in a string.
Note : This function was introduced in PHP 4.3.0.
Note : Cette fonction gère les chaînes binaires
Tuyau : You can use a URL as a filename with this function if the "fopen wrappers" have been enabled. See fopen() for more details.
See also: fgets(), file(), fread(), include(), and readfile().
file_get_wrapper_data
Description
mixed file_get_wrapper_data ( int fp)This function returns header or meta data from files opened with fopen(). This is useful to return the response headers for HTTP connections, or some other statistics for other resources.
The format of the returned data is deliberately undocumented at this time, and depends on which wrapper(s) were used to open the file.
Note : This function was introduced in PHP 4.3.0.
file_register_wrapper
Description
boolean file_register_wrapper ( string protocol, string classname)This function is currently only documented by the example below:
Exemple 1. Implementing a base64 encoding protocol
|
file_register_wrapper() will return false if the protocol already has a handler, or if "fopen wrappers" are disabled.
Note : This function was introduced in PHP 4.3.0.
file
Description
array file ( string filename [, int use_include_path])Identique à readfile(), hormis le fait que file() retourne le fichier dans un tableau. Chaque élément du tableau correspond à une ligne du fichier, et les retour-chariots sont placés en fin de ligne.
Vous pouvez utiliser l'option use_include_path : en la mettant à "1", vous rechercherez aussi dans le dossier include_path.
<?php
// Lire une page web dans un tableau, et l'afficher
$fcontents = file( 'http://www.php.net' );
while ( list( $numero_ligne, $ligne ) = each( $fcontents ) ) {
echo "<B>Ligne $numero_ligne:</B> ".htmlspecialchars( $ligne ) . "<br>\n";
}
// lire une page web dans une chaîne
$fcontents = join( '', file( 'http://www.php.net' ) );
?> |
Voir aussi readfile(), fopen(), fsockopen() et popen().
fileatime
(PHP 3, PHP 4 )
fileatime -- Renvoie la date à laquelle le fichier a été accédé pour la dernière fois.Description
int fileatime ( string filename)fileatime() renvoie la date à laquelle le fichier a été accédé pour la dernière fois, ou FALSE en cas d'erreur.
fileatime() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de fileatime() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
filectime
Description
int filectime ( string filename)filectime() renvoie l'heure à laquelle l'inode filename a été accédé pour la dernière fois, ou FALSE en cas d'erreur.
filectime() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Note: Sur la plupart des serveurs UNIX, un fichier est considéré comme modifié si les données de son inode sont modifiées. C'est-à-dire lorsque les permissions (utilisateur, groupe ou autre) ont été modifiées. Voyez aussi filemtime() (que vous pourrez utiliser lorsque vous créerez des indications telles que "Dernière modification : " sur les pages web) et fileatime().
Notez aussi que sur certains systèmes UNIX, le ctime d'un fichier texte 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.
Le résultat de filectime() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
filegroup
Description
int filegroup ( string filename)filegroup() renvoie le groupe qui possède le fichier filename, ou FALSE en cas d'erreur. L'identifiant de groupe est retourné au format numérique, utilisez posix_getgrgid() pour retrouver le nom du groupe.
filegroup() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de filegroup() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
Note : filegroup() est inopérante sous Windows.
fileinode
Description
int fileinode ( string filename)fileinode() renvoie le numéro d'inode du fichier filename, ou FALSE en cas d'erreur.
Le résultat de fileinode() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
fileinode() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Note : fileinode() est inopérante sous Windows.
filemtime
Description
int filemtime ( string filename)filemtime() renvoie la date de dernière modification du fichier filename, ou FALSE en cas d'erreur.
Le résultat de filemtime() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
filemtime() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
filemtime() retourne l'heure d'écriture des blocs données d'un fichier. Utilisez date() sur ce résultat pour obtenir une date de modification humainement lisible.
fileowner
Description
int fileowner ( string filename)fileowner() renvoie le nom du possesseur du fichier filename, ou FALSE en cas d'erreur. L'identification du possesseur de fichier est numérique : il faut utiliser posix_getpwuid() pour retrouver le nom d'utilisateur.
fileowner() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de fileowner() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
Note : fileowner() est inopérante sous Windows.
fileperms
Description
int fileperms ( string filename)fileperms() renvoie les permissions affectées au fichier filename, ou FALSE en cas d'erreur.
fileperms() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de fileperms() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
filesize
Description
int filesize ( string filename)filesize() renvoie la taille du fichier filename, ou FALSE en cas d'erreur.
filesize() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de filesize() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
filetype
Description
string filetype ( string filename)filetype() renvoie le type du fichier filename. Les réponses possibles sont : fifo, char, dir, block, link, file, et unknown.
filetype() retourne FALSE en cas d'erreur.
filetype() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de filetype() est mis en cache. Reportez-vous à clearstatcache() pour plus de détails.
flock
Description
boolean flock ( int fp, int operation)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.
flock() agit sur le fichier fp qui doit avoir été ouvert au préalable. operation est une des valeurs suivantes :
Acquisition d'un verrou : operation = 1.
Acquisition d'un verrou exclusif (écriture), operation = 2.
Libération d'un verrou (partagé ou exclusif), operation = 3.
Si vous voulez que flock() ne se bloque pas durant le verrouillage, ajoutez 4 à operation.
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).
flock() retourne TRUE en cas de succès, et FALSE sinon. (le verrou n'a pas pu être obtenu).
| Avertissement |
Sur la plupart des OS, flock() est implémenté au niveau processus. Lors de l'utilisation des API d'un serveur multi-thread, comme ISAPI, vous ne pouvez pas vous fier à flock() pour protéger vos fichiers contre des accès concurrents du même serveur. |
fopen
Description
int fopen ( string filename, string mode [, int use_include_path])Si filename commence par "http://" (insensible à la casse), une connexion HTTP 1.x est ouverte avec le serveur spécifié, et un pointeur sur la réponse fournie est retourné. Une en-tête 'Host:' est envoyé avec la requête, afin de gérer les virtual hosts basés sur les noms.
Notez que le pointeur de fichier retourné représente le corps de la réponse, et qu'il n'est pas possible d'accéder aux en-têtes HTTP avec cette fonction.
Les versions antérieures à PHP 4.0.6, ne gère pas les redirections automatiques, ce qui oblige à ajouter les slash finaux "/" pour indiquer un dossier.
Si filename commence par "ftp://" (insensible à la casse), une connexion FTP est ouverte avec le serveur spécifié, et un pointeur sur la réponse fournie est retourné. Si le serveur ne supporte par le mode FTP passif, fopen() échouera. Vous pouvez ouvrir des fichiers en lecture seulement, ou en écriture seulement (le full duplex n'est pas supporté).
Si filename commence par "php://stdin", "php://stdout", ou "php://stderr", le flot correspondant sera ouvert. (Cela a été introduit en PHP 3.0.13; dans les anciennes versions, les fichiers "/dev/stdin" ou "/dev/fd/0" devaient être utilisés pour accéder à ces flots).
Si filename commence par n'importe quoi d'autre, PHP tentera de lire ce fichier dans le système local, et un pointeur sur le fichier ouvert sera retourné.
Si l'ouverture échoue, fopen() retourne FALSE.
mode peut prendre les valeurs suivantes :
'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; 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.
'a' - Ouvre en écriture seule; place le pointeur de fichier à la fin du fichier file. Si le fichier n'existe pas, on tente de le créer.
'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.
Vous pouvez utiliser le troisième paramètre optionnel pour explorer le dossier include_path, en le mettant à 1.
Si vous rencontrez des problèmes en lecture ou écriture de fichier et que vous utilisez PHP en version module de serveur, n'oubliez pas que les fichiers auxquels vous accédez ne sont pas nécessairement accessibles au processus serveur.
Sous Windows, assurez-vous de bien échapper les anti-slash utilisés dans le chemin du fichier, ou bien utilisez des slash.
Voir aussi fclose(), fsockopen(), socket_set_timeout() et popen().
fpassthru
Description
int fpassthru ( int fp)fpassthru() lit tout le reste d'un fichier jusqu'à la fin, et dirige le résultat vers la sortie standard.
Si une erreur survient, fpassthru() retourne FALSE.
Le pointeur de fichier doit être valide, et doit avoir été correctement ouvert par fopen(), popen(), ou fsockopen(). Après lecture, fpassthru() va fermer le fichier (le pointeur fp sera alors invalide).
Si vous voulez simplement afficher le contenu d'un fichier, il suffit d'utiliser readfile(), ce qui épargnera l'appel à fopen().
Voir aussi readfile(), fopen(), popen() et fsockopen().
fputs
Description
int fputs ( int fp, string str [, int length])fputs() est un alias de fwrite(), et lui est identique en tous points. Notez que length est un paramètre optionnel, et s'il n'est pas spécifié, toute la chaîne est écrite.
fread
Description
string fread ( int fp, int length)fread() lit jusqu'à length octets dans le fichier reférencé par fp. La lecture s'arrête lorsque length octets ont été lus, ou que l'on a atteint la fin du fichier, ou qu'une erreur survient (le premier des trois).
<?php // Lit un fichier, et le place dans une chaîne $filename = "/usr/local/quelquechose.txt"; $fd = fopen($filename, "r"); $contents = fread($fd, filesize ($filename)); fclose($fd); ?> |
Note : Sur les systèmes qui différencient les fichiers textes et binaires (i.e. Windows) le fichier doit être ouvert avec la lettre 'b' ajoutée au paramètre de mode de la fonction fopen().
Note :
Voir aussi fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), file() et fpassthru().
fscanf
Description
mixed fscanf ( int handle, string format [, string var1])fscanf() est similaire à sscanf(), mais elle prend comme entrée un fichier, associé à handle et l'interprète en fonction du format format. Si seulement deux paramètres sont passés à la fonction, les valeurs analysées seront retournées sous forme de tableau. Si des arguments optionnels sont passés, la fonction retournera le nombre de valeurs assignées. Les options doivent être passées par référence.
Voir aussi fread(), fgets(), fgetss(), sscanf(), printf() et sprintf().
fseek
Description
int fseek ( int fp, int offset)fseek() modifie le curseur de position dans le fichier fp. La nouvelle position mesurée en octets à partir du début du fichier, est obtenue en additionnant la distance offset à la position whence. Ce paramètre peut prendre les valeurs suivantes :
| SEEK_SET - La position finale vaut offset octets. |
| SEEK_CUR - La position finale vaut la position courante ajoutée à offset octets. |
| SEEK_END - La position finale vaut la position courante par rapport à la fin du fichier, ajoutée de offset. |
Si whence n'est pas spécifiée, il vaut par défaut SEEK_SET.
fseek() retourne TRUE en cas de succès, et sinon -1. Notez que positionner le pointeur au delà de la fin du fichier n'est pas une erreur.
fseek() ne peut pas être utilisé sur les pointeurs retournés par fopen() s'ils sont au format HTTP ou FTP.
fstat
Description
array fstat ( int fp)fstat() rassemble les informations sur le fichier dont on connaît le pointeur fp. fstat() est similaire à la fonction stat(), hormis le fait qu'elle utilise un pointeur de fichier, au lieu d'un nom de fichier.
fstat() retourne un tableau avec les éléments suivants :
1 : volume
2 : inode
3 : mode de protection du inode
4 : nombre de liens
5 : id de l'utilisateur propriétaire
6 : id du groupe propriétaire
7 : type du volume de l'inode *
8 : taille en octets
9 : date du dernier accès
10 : date de la dernière modification
11 : date du dernier changement
12 : taille de bloc du système pour les entrées/sorties(*)
13 : Nombre de blocs alloués
Les résultats de fstat() sont mis en cache. Reportez-vous à la fonction clearstatcache() pour plus de détails.
ftell
Description
int ftell ( int fp)ftell() retourne la position courante du pointeur dans le fichier repéré par le pointeur fp, i.e., son offset.
Si une erreur survient, retourne FALSE.
Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen() ou popen().
ftruncate
Description
int ftruncate ( int fp, int size)ftruncate() prend le pointeur de fichier fp et le tronque à la taille de size.ftruncate() retourne TRUE en cas de succès, et FALSE sinon.
fwrite
Description
int fwrite ( int fp, string string [, int length])fwrite() écrit le contenu de la chaîne string dans le fichier pointé par fp. 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).
Notez que si length est fourni, alors l'option de configuration magic_quotes_runtime sera ignorée, et les slash seront conservés.
Note : De plus, mode peut contenir la lettre 'b'. Cette option n'est utile que sur les systèmes qui font la différence entre les fichiers binaires et les fichiers textes (en bref, c'est une fonctionnalité Windows, totalement inutile sous Unix). S'il n'est pas nécessaire, il sera ignoré.
Voir aussi fread(), fopen(), fsockopen(), popen() et fputs().
glob
Description
array glob ( string pattern [, int flags])The glob() function searches for all the pathnames matching pattern according to the rules used by the shell. No tilde expansion or parameter substitution is done.
Returns an array containing the matched files/directories or FALSE on error.
Exemple 1. Convenient way how glob() can replace opendir() and friends.
This could result in the following output:
|
See also opendir(), readdir() and closedir().
is_dir
Description
boolean is_dir ( string filename)is_dir() retourne TRUE si filename existe et est un dossier.
Le résultat de is_dir() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
is_dir() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
is_executable
Description
boolean is_executable ( string filename)is_executable() retourne TRUE si filename existe et est exécutable.
Le résultat de is_executable() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
is_executable() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
is_file
Description
boolean is_file ( string filename)is_file() retourne TRUE si filename existe et est un fichier (et pas un dossier).
Le résultat de is_file() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
is_file() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
is_link
Description
boolean is_link ( string filename)is_link() retourne TRUE si filename existe et est un lien symbolique.
Le résultat de is_link() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
is_link() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Voir aussi is_dir() et is_file().
Note : is_link() est inopérante sous Windows.
is_readable
Description
boolean is_readable ( string filename)is_readable() retourne TRUE si filename existe et est accessible en lecture.
N'oubliez pas 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).
Le résultat de is_readable() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
is_readable() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Voir aussi is_writable().
is_uploaded_file
(PHP 3>= 3.0.17, PHP 4 >= 4.0.3)
is_uploaded_file -- Indique si le fichier a été téléchargé par HTTP POSTDescription
boolean is_uploaded_file ( string filename)is_uploaded_file() est disponible à partir des versions PHP 3.0.16 et 4.0.2.
is_uploaded_file() retourne TRUE si le fichier filename a été téléchargé par HTTP POST. Cela est très utile pour vous assurer qu'un utilisateur n'essaie pas d'accéder intentionnellement à un fichier auquel il n'a pas droit (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.
Voir aussi move_uploaded_file(), et la section Chargement de fichier pour un exemple simple.
is_writable
Description
boolean is_writable ( string filename)is_writable() retourne TRUE si filename existe et est accessible en écriture.
N'oubliez pas 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).
is_writable() ne fonctionne pas sur les fichiers distants. Les fichiers doivent être accessibles par le système de fichier du serveur.
Le résultat de is_writable() est mis en cache. Voir la fonction clearstatcache() pour plus de détails.
Voir aussi is_readable().
is_writeable
link
Description
int link ( string target, string link)link() crée un lien.
Voir aussi symlink() pour créer des liens symboliques et readlink() avec linkinfo().
Note : link() est inopérante sous Windows.
linkinfo
Description
int linkinfo ( string path)linkinfo() renvoie les informations à propos d'un lien, c'est-à-dire le champs st_dev de la structure d'information UNIX (comme en langage C). linkinfo() sert à vérifier si un lien (repéré par path) existe (en utilisant la même méthode que la macro S_ISLNK de stat.h). linkinfo() retourne FALSE en cas d'erreur.
Voir aussi symlink(), link() et readlink().
Note : linkinfo() est inopérante sous Windows.
lstat
(PHP 3>= 3.0.4, PHP 4 )
lstat -- Renvoie les informations à propos d'un fichier ou d'un lien symbolique.Description
array lstat ( string filename)lstat() est identique à stat() mais elle accepte aussi un lien symbolique comme argument.
lstat() retourne un tableau avec les éléments suivants :
0 : volume
1 : inode
2 : droits d'accès au fichier (mode de protection du inode). A convertir en octal. Voir aussi fileperms().
3 : nombre de liens
4 : id de l'utilisateur propriétaire
5 : id du groupe propriétaire
6 : type du volume de l'inode *
7 : taille en octets
8 : date du dernier accès
9 : date de la dernière modification
10 : date du dernier changement
11 : taille de bloc du système pour les entrées/sorties *
12 : nombre de blocs alloués
Les résultats de lstat() sont mis en cache. Reportez-vous à la fonction clearstatcache() pour plus de détails.
mkdir
Description
int mkdir ( string pathname, int mode)mkdir() tente de créer un dossier dans le chemin pathname.
Notez que vous aurez à préciser le mode en base octale, ce qui signifie que vous aurez probablement un 0 comme premier chiffre. Le mode sera aussi modifié par le umask courant, que vous pouvez modifier avec la fonction umask().
mkdir() retourne TRUE en cas de succès, et FALSE en cas d'échec.
Voir aussi rmdir().
move_uploaded_file
Description
boolean move_uploaded_file ( string filename, string destination)move_uploaded_file() est disponible à partir des versions PHP 3.0.16 et 4.0.2.
move_uploaded_file() s'assure que le fichier filename est un fichier téléchargé par HTTP POST. Si le fichier est valide, il est déplacé jusqu'à destination.
Si filename n'est pas valide, rien ne se passe, et move_uploaded_file() retournera FALSE.
Si filename 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 sera affichée.
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.
Voir aussi move_uploaded_file() et la section Chargement de fichier pour un exemple simple.
parse_ini_file
Description
array parse_ini_file ( string filename [, bool process_sections])parse_ini_file() charge le fichier filename et retourne les configuration qui s'y trouve sous forme d'un tableau associatif. En passant le deuxième paramètre optionnel à process_sections, vous obtiendrez un tableau multi-dimensionnel, avec les noms des sections. La valeur par défaut de ce paramètre est FALSE
Note : Cette fonction n'a rien a voir avec le fichier php.ini. Ce dernier a déjà était traité lorsque vous commencez a exécuter votre script. Cette fonction peut vous permettre de lire vos propres fichiers de configuration.
La structure des fichiers de configuration lus est similaire à celle de php.ini.
Cet exemple va produire :
pathinfo
Description
array pathinfo ( string path)pathinfo() retourne un tableau associatif, contenant les informations sur le chemin path. Les éléments suivants sont retournés : dirname, basename et extension.
Va afficher :
Voir aussi dirname(), parse_url(), basename() et realpath().
pclose
Description
int pclose ( int fp)pclose() ferme un processus de pointeur de fichier ouvert par popen().
Le pointeur de fichier doit être valide, et avoir été ouvert correctement par popen().
pclose() retourne le statut final du processus exécuté.
Voir aussi popen().
popen
Description
int popen ( string commet, string mode)popen() ouvre un processus fils en faisant un fork de la commande.
popen() 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 fputs().
Si une erreur survient, retourne FALSE.
Voir aussi pclose().
readfile
Description
int readfile ( string filename [, int use_include_path])readfile() lit le fichier filename et l'envoit à la sortie standard.
readfile() retourne le nombre d'octets lus depuis le fichier. Si une erreur survient, retourne FALSE.
Si filename commence par "http://" (insensible à la casse), une connexion HTTP 1.0 sera ouverte avec le serveur spécifié, et le texte de la réponse sera affiché sur la sortie standard.
Les versions antérieures à PHP 4.0.6, ne gère pas les redirections automatiques, ce qui oblige à ajouter les slash finaux "/" pour indiquer un dossier.
Si filename commence par "ftp://" (insensible à la casse), une connexion FTP est ouverte avec l'hôte spécifié et la réponse du serveur est affichée. Si le serveur ne supporte les connexions passives, la requête échouera.
Si filename ne commence par aucun des cas précédents, le fichier sera ouvert sur l'hôte local, et envoyé à la sortie standard.
Vous pouvez utiliser le deuxième paramètre optionnel pour explorer le dossier include_path, en passant la valeur de 1.
Voir aussi fpassthru(), file(), fopen(), include(), require() et virtual().
readlink
Description
string readlink ( string path)readlink() fait la même chose que la fonction readlink en C : elle retourne le contenu du lien symbolique repéré par path, ou FALSE en cas d'erreur.
Voir aussi symlink(), readlink() et linkinfo().
Note : readlink() est inopérante sous Windows.
realpath
Description
string realpath ( string path)realpath() résoud tous les liens symboliques, et remplace toutes les références '/./', '/../' et '/' de path puis retourne le chemin canonique absolu ainsi trouvé. Le résultat ne contient aucun lien symbolique, '/./' ou '/../'.
rename
Description
int rename ( string oldname, string newname)rename() rente de renommer le fichier oldname en newname.
rename() retourne TRUE en cas de succès et FALSE sinon.
rewind
Description
int rewind ( int fp)rewind() replace le pointeur du fichier fp au début.
Si une erreur survient, retourne FALSE.
Le pointeur de fichier doit être valide, et avoir été correctement ouvert par fopen().
rmdir
Description
int rmdir ( string dirname)rmdir() tente d'effacer le dossier dont le chemin est dirname. Le dossier doit être vide, et le script doit avoir les autorisations adéquates.
Si une erreur survient, rmdir() retourne FALSE.
Voir aussi mkdir().
set_file_buffer
Description
int set_file_buffer ( int fp, int buffer)L'écriture de fichier avec fwrite() utilise normalement un buffer de 8K. Cela signifie que si deux processus essaient d'écrire dans le même fichier, ils font une pause tous les 8ko pour laisser le temps à l'autre d'écrire à son tour. set_file_buffer() permet de modifier la taille du buffer de sortie pour le pointeur de fichier fp à buffer octets. Si buffer vaut 0, l'écriture se fera sans buffer. Cela force un processus à écrire toutes ses données dans un fichier avant que les autres puissent y accéder.
set_file_buffer() retourne 0 en cas de succès, ou EOF si la requête ne peut pas être honorée.
L'exemple suivant montre comment utiliser la fonction set_file_buffer() pour créer un fichier sans buffer.
stat
Description
array stat ( string filename)stat() renvoie les informations à propos du fichier filename.
stat() retourne un tableau avec les éléments suivants :
0 : volume
1 : inode
2 : droits d'accès au fichier (mode de protection du inode). A convertir en octal. Voir aussi fileperms().
3 : nombre de liens
4 : id de l'utilisateur propriétaire
5 : id du groupe propriétaire
6 : type du volume de l'inode *
7 : taille en octets
8 : date du dernier accès
9 : date de la dernière modification
10 : date du dernier changement
11 : taille de bloc du système pour les entrées/sorties *
12 : nombre de blocs alloués
stat() retourne FALSE en cas d'erreur.
stat() ne gère pas les URL comme peut le faire fopen().
Les résultats de stat() sont mis en cache. Reportez-vous à la fonction clearstatcache() pour plus de détails.
symlink
Description
int symlink ( string target, string link)symlink() crée un lien symbolique pour l'objet target avec le nom de link.
Voir aussi link() pour créer des liens durs et readlink() ainsi que linkinfo().
Note : symlink() est inopérante sous Windows.
tempnam
Description
string tempnam ( string dir, string prefix)tempnam() crée un fichier temporaire unique dans le dossier dir. Si le dossier n'existe pas, tempnam() va générer un nom de fichier dans le dossier temporaire du système.
Avant PHP 4.0.6, le comportement de tempnam() dépendait de l'OS sous-jacent. Sous Windows, la variable d'environnement TMP remplace le paramètre dir; sous Linux, la variable d'environnement TMPDIR a la priorité, tandis que pour les OS en système V R4, le paramètre dir sera toujours utilisé, si le dossier qu'il représente existe. Consultez votre documentation pour plus de détails.
tempnam() retourne le nom du fichier temporaire, ou la chaîne NULL en cas d'échec.
tmpfile
Description
int tmpfile ( void)tmpfile() crée un fichier temporaire avec un nom unique, ouvert en écriture, et retourne un pointeur de fichier, identique à ceux retournés par fopen(). Ce fichier sera automatiquement effacé lorsqu'il sera fermé (avec fclose()), ou lorsque le script sera terminé.
Pour plus de détails, consultez votre documentation système sur la fonction tmpfile(3), et sur stdio.h.
Voir aussi tempnam().
touch
Description
int touch ( string filename, int time)touch() tente de forcer la date de modification du fichier nommé filename à la date de time. Si time est omis, c'est l'heure courante qui est utilisée.
Si le fichier n'existe pas, il est créé.
touch() retourne TRUE en cas de succès, et FALSE sinon.
umask
Description
int umask ( int mask)umask() change le umask de PHP : mask & 0777 et retourne le vieux umask. Lorsque PHP est utilisé comme module de serveur, le umask reprend sa valeur à la fin de chaque script.
umask() appelé sans argument retourne simplement le umask courant.
unlink
Description
int unlink ( string filename)unlink() efface filename. Identique à la fonction Unix C unlink().
unlink() retourne FALSE en cas d'échec.
Voir aussi rmdir() pour supprimer des dossiers.
Note : unlink() ne fonctionne pas sous Windows.
XXXI. Forms Data Format
Forms Data Format (FDF) est un format de fomulaire pour les documents PDF. Vous pouvez lire la documentation (en anglais) à http://partners.adobe.com/asn/developer/acrosdk/forms.html pour plus de détails sur les tenants et les aboutissants.
Note : Si vous rencontrez des problèmes de configuration de PHP avec le support fdftk, vérifiez bien que le fichier d'en-têtes FdfTk.h et la librairie libFdfTk.so sont bien situés. Elle devrait être dans les dossiers fdftk-dir/include et fdftk-dir/lib. Cela ne sera pas le cas si vous avez simplement décompressé la distribution FdfTk.
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. Vous pouvez aussi 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" de votre navigateur va reconnaître ce type MIME, et lire le fichier PDF, puis le remplis avec FDF.
Si vous éditez un fichier FDF avec un éditeur de texte, vous trouverez un catalogue d'objet 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 a qui 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..
Les exemples suivants montre comme évaluer les données du formulaire.
Exemple 1. Evaluer un document FDF
|
- Table des matières
- fdf_add_template -- Adds a template into the FDF document
- fdf_close -- Ferme un document FDF.
- fdf_create -- Crée un nouveau document FDF.
- fdf_get_file -- Lit la valeur de la clé /F.
- fdf_get_status -- Lit la valeur de la clé /STATUS.
- fdf_get_value -- Mot la valeur d'un champs.
- fdf_next_field_name -- Lit le nom du champs suivant.
- fdf_open -- Ouvre un document FDF.
- fdf_save -- Sauver un document FDF.
- fdf_set_ap -- Fixe l'apparence d'un champs.
- fdf_set_encoding -- Modifie l'encodage des caractères
- fdf_set_file -- Fixe la valeur de la clé /F.
- fdf_set_flags -- Modifie une option d'un champs
- fdf_set_javascript_action -- Modifie l'action javascript d'un champs
- fdf_set_opt -- Modifie une option d'un champs
- fdf_set_status -- Fixe la valeur de la clé /STATUS.
- fdf_set_submit_form_action -- Modifie l'action d'un formulaire
- fdf_set_value -- Fixe la valeur d'un champs.
fdf_add_template
Description
bool fdf_add_template ( int fdfdoc, int newpage, string filename, string template, int rename)
| Avertissement |
This function is currently not documented, only the argument list is available. |
fdf_close
Description
boolean fdf_close ( resource fdf_document)fdf_close() ferme le document FDF.
Voir aussi fdf_open().
fdf_create
Description
int fdf_create ( void )fdf_create() crée un nouveau document FDF. Cette fonction est nécessaire pour ceux qui veulent pré remplir les champs d'un formulaire dans un fichier PDF.
Exemple 1. Pré remplir un formulaire PDF
|
Voir aussi fdf_close(), fdf_save() et fdf_open().
fdf_get_file
Description
string fdf_get_file ( int fdf_document)fdf_set_file() lit la valeur de la clé /F.
Voir aussi fdf_set_file().
fdf_get_status
Description
string fdf_get_status ( int fdf_document)fdf_get_status() retourne la valeur de la clé /STATUS.
Voir aussi fdf_set_status().
fdf_get_value
Description
string fdf_get_value ( int fdf_document, string fieldname)fdf_get_value() retourne la valeur d'un champs.
Voir aussi fdf_set_value().
fdf_next_field_name
Description
string fdf_next_field_name ( int fdf_document, string fieldname)fdf_next_field_name() retourne le nom du champs après le champs fieldname ou le nom du premier champs, si le second paramètre est NULL.
Voir aussi fdf_set_value() et fdf_get_value().
fdf_open
Description
resource fdf_open ( string filename)fdf_open() ouvre un fichier avec formulaire. Le fichier doit contenir les données retournées par le formulaire PDF. Actuellement, le fichier doit être créée 'manuellement', en utilisant la fonction fopen() et en y écrivant le contenu du tableau HTTP_FDF_DATA avec la fonction fwrite(). Un mécanisme comparable aux formulaires HTML qui créent une variable pour chaque champs entrant, n'existe pas.
Exemple 1. Accéder aux données du formulaire
|
Voir aussi fdf_close().
fdf_save
Description
int fdf_save ( string filename)fdf_save() sauve un document FDF. Le FDF Toolkit fournit un moyen d'envoyer le contenu d'un document FDF à au fichier de sortie stdout si le paramètre filename vaut '.'. Ceci ne fonctionne pas si PHP est sous la forme d'un module Apache. Dans ce cas, il faudra écrire le résultat dans un fichier, et utiliser fpassthru() pour l'afficher au client.
Voir aussi fdf_close() et pour avoir un exemple fdf_create().
fdf_set_ap
Description
boolean fdf_set_ap ( int fdf_document, string field_name, int face, string filename, int page_number)fdf_set_ap() fixe l'apparence d'un champs (i.e. la valeur de la clé /AP). Les valeurs possibles de face sont sont 1=FDFNormalAP, 2=FDFRolloverAP, 3=FDFDownAP.
fdf_set_encoding
Description
bool fdf_set_encoding ( int fdf_document, string encoding)fdf_set_encoding() modifie l'encodage des caractères du document FDF fdf_document. Le paramètre encoding doit être un nom d'encodage valide. Pour Acrobat 5.0, un nom valide peut notamment être "Shift-JIS", "UHC", "GBK" ou "BigFive".
fdf_set_encoding() a été ajoutée en PHP 4.1.0.
fdf_set_file
Description
boolean fdf_set_file ( int fdf_document, string filename)fdf_set_file() Fixe la valeur de la clé /F. la clé /F est simplement une référence sur un formulaire PDF qui doit être pré-remplis. Dans un environnement web, c'est une URL (e.g. http:/testfdf/resultlabel.pdf).
Voir aussi fdf_get_file() et pour un exemple, fdf_create().
fdf_set_flags
Description
boolean fdf_set_flags ( int fdf_document, string fieldname, int whichFlags, int newFlags)fdf_set_flags() modifie certaines options du champs fieldname.
Voir aussi fdf_set_opt().
fdf_set_javascript_action
Description
boolean fdf_set_javascript_action ( int fdf_document, string fieldname, int trigger, string script)fdf_set_javascript_action() affecte un javascript au champs fieldname, exécuté lors de la validation d'un formulaire.
Voir aussi fdf_set_submit_form_action().
fdf_set_opt
Description
boolean fdf_set_opt ( int fdf_document, string fieldname, int element, string str1, string str2)fdf_set_opt() modifie les options du champs fieldname.
Voir aussi fdf_set_flags().
fdf_set_status
Description
boolean fdf_set_status ( int fdf_document, string status)fdf_set_status() fixe la valeur de la clé /STATUS.
Voir aussi fdf_get_status().
fdf_set_submit_form_action
Description
boolean fdf_set_submit_form_action ( int fdf_document, string fieldname, int trigger, string script, int flags)fdf_set_submit_form_action() affecte un javascript au champs fieldname, exécuté lors de la validation d'un formulaire.
Voir aussi fdf_set_javascript_action().
fdf_set_value
Description
boolean fdf_set_value ( int fdf_document, string fieldname, string value, int isName)fdf_set_value() fixe la valeur d'un champs. Le dernier paramètre détermine si la valeur doit être convertie en nom PDF (isName = 1) ou affecter une chaîne PDF à un contrôle (isName = 0).
Voir aussi fdf_get_value().
fribidi_log2vis
Description
string fribidi_log2vis ( string str, string direction, int charset)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
XXXIII. FTP
FTP : File Transfer Protocol (Protocole de transfert de fichiers). Ces fonctions implémentent un client pour accéder aux serveurs FTP, comme défini dans http://www.faqs.org/rfcs/rfc959.html.
Les constantes suivantes sont définies dans le module FTP : FTP_ASCII et FTP_BINARY.
Pour activer le module FTP de votre configuration PHP, il faut utiliser l'option --enable-ftp en PHP 4, et l'option --with-ftp en PHP 3 avec le script de configuration.
Exemple 1. Exemple de connexion FTP
|
- Table des matières
- ftp_cdup -- Change de dossier, et passe au dossier parent.
- ftp_chdir -- Change le dossier courant.
- ftp_close -- Closes an FTP connection
- ftp_connect -- Ouvre une connexion FTP
- ftp_delete -- Efface un fichier sur un serveur FTP.
- ftp_exec -- Request execution of a program on the FTP server
- ftp_fget -- Télécharge un fichier depuis un serveur FTP et le sauve dans un fichier déjà ouvert.
- ftp_fput -- Charge un fichier ouvert sur un serveur FTP.
- ftp_get_option -- Retrieves various runtime behaviours of the current FTP stream
- ftp_get -- Télécharge un fichier depuis un serveur FTP.
- ftp_login -- Authentification d'une connexion FTP
- ftp_mdtm -- Retourne la date de dernière modification d'un fichier sur un serveur FTP.
- ftp_mkdir -- Crée un dossier.
- ftp_nlist -- Retourne la liste des fichiers dans un dossier.
- ftp_pasv -- Active ou désactive le mode passif.
- ftp_put -- Charge un fichier sur un serveur FTP.
- ftp_pwd -- Retourne le nom du dossier courant.
- ftp_quit -- Ferme une connexion FTP.
- ftp_rawlist -- Fait une liste détaillée de fichiers dans un dossier.
- ftp_rename -- Renomme un fichier sur un serveur FTP.
- ftp_rmdir -- Efface un dossier.
- ftp_set_option -- Set miscellaneous runtime FTP options
- ftp_site -- Envoie la commande SITE au serveur.
- ftp_size -- Retourne la taille d'un fichier.
- ftp_systype -- Retourne un identifiant de type de serveur FTP.
ftp_cdup
Description
bool ftp_cdup ( resource ftp_stream)ftp_cdup() retourne TRUE en cas de succès, et FALSE sinon.
ftp_cdup() change de dossier, et passe au dossier parent.
ftp_chdir
Description
bool ftp_chdir ( resource ftp_stream, string directory)ftp_chdir() retourne TRUE en cas de succès, et FALSE sinon.
ftp_chdir() change le dossier courant en directory.
ftp_close
Description
void ftp_close ( resource ftp_stream)Note : This function is only available in CVS.
ftp_close() closes ftp_stream and releases the resource. You can't reuse this resource but have to create a new one with ftp_connect().
ftp_connect
Description
resource ftp_connect ( string host [, int port])ftp_connect() retourne un flot FTP en cas de succès, et FALSE sinon.
ftp_connect() ouvre une connexion FTP avec l'hôte host. Le paramètre port spécifie le port de connexion. S'il est omis, le port 21 sera utilisé.
ftp_delete
Description
bool ftp_delete ( resource ftp_stream, string path)ftp_delete() retourne TRUE en cas de succès, et FALSE sinon.
ftp_delete() efface le fichier path sur un serveur FTP.
ftp_exec
Description
bool ftp_exec ( resource ftp_stream, string command)Sends a SITE EXEC command request to the FTP server. Returns FALSE if the request fails, returns the output of the command otherwise.
ftp_fget
(PHP 3>= 3.0.13, PHP 4 )
ftp_fget -- Télécharge un fichier depuis un serveur FTP et le sauve dans un fichier déjà ouvert.Description
bool ftp_fget ( resource ftp_stream, int fp, string remote_file, int mode)ftp_fget() retourne TRUE en cas de succès, et FALSE sinon.
ftp_fget() télécharge le fichier remote_file depuis le serveur FTP, et l'écrit dans le fichier identifié par fp. Le mode de transfert mode spécifié doit être FTP_ASCII ou FTP_BINARY.
ftp_fput
Description
bool ftp_fput ( resource ftp_stream, string remote_file, int fp, int mode)ftp_fput() retourne TRUE en cas de succès, et FALSE sinon.
ftp_fput() charge les données issues du fichier identifié par fp jusqu'à la fin du fichier. Le résultat est stocké dans le fichier remote_file sur le serveur FTP. Le mode de transfert mode spécifié doit être FTP_ASCII ou FTP_BINARY.
ftp_get_option
Description
mixed ftp_get_option ( resource ftp_stream, int option)Note : This function is only available in CVS.
Returns the value on success, or FALSE if the given option is not supported. In the latter case, a warning message is also thrown.
This function returns the value for the requested option from the specified ftp_stream . Currently, the following options are supported:
Tableau 1. Supported runtime FTP options
| FTP_TIMEOUT_SEC | Returns the current timeout used for network related operations. |
ftp_get
Description
bool ftp_get ( resource ftp_stream, string local_file, string remote_file, int mode)ftp_get() retourne TRUE en cas de succès, et FALSE sinon.
ftp_get() télécharge le fichier remote_file depuis le serveur FTP, et le sauve dans le fichier local local_file. Le mode de transfert mode spécifié doit être soit FTP_ASCII ou FTP_BINARY.
ftp_login
Description
bool ftp_login ( resource ftp_stream, string username, string password)ftp_login() retourne TRUE en cas de succès, et FALSE sinon.
ftp_login() authentifie le flot FTP.
ftp_mdtm
(PHP 3>= 3.0.13, PHP 4 )
ftp_mdtm -- Retourne la date de dernière modification d'un fichier sur un serveur FTP.Description
int ftp_mdtm ( resource ftp_stream, string remote_file)ftp_mdtm() retourne un UNIX timestamp en cas de succès, et FALSE sinon.
ftp_mdtm() lit la date de dernière modification d'un fichier et retourne le UNIX timestamp. Si une erreur survient, ou si le fichier n'existe pas,la valeur -1 est retournée. Certains serveurs FTP ne supportent pas cette fonction.
ftp_mkdir
Description
string ftp_mkdir ( resource ftp_stream, string directory)ftp_mkdir() retourne le nom du dossier ainsi créé en cas de succès, et FALSE sinon.
ftp_mkdir() crée le dossier nommé directory.
ftp_nlist
Description
array ftp_nlist ( resource ftp_stream, string directory)ftp_nlist() retourne un tableau de nom de fichiers en cas de succès, et FALSE sinon.
ftp_pasv
Description
bool ftp_pasv ( resource ftp_stream, int pasv)ftp_pasv() retourne TRUE en cas de succès, et FALSE sinon.
ftp_pasv() active le mode passif si pasv est à TRUE (et le désactive si pasv est à FALSE). En mode passif, les données de connexion sont initiées par le client, plutôt que par le serveur.
ftp_put
Description
bool ftp_put ( resource ftp_stream, string remote_file, string local_file, int mode)ftp_put() retourne TRUE en cas de succès, et FALSE sinon.
ftp_put() enregistre le fichier local_file sur le serveur FTP, sous le nom de remote_file. Le mode de transfert mode spécifié doit être FTP_ASCII ou FTP_BINARY.
ftp_pwd
Description
string ftp_pwd ( resource ftp_stream)ftp_pwd() retourne le nom du dossier courant, ou FALSE en cas d'erreur.
ftp_quit
ftp_rawlist
Description
array ftp_rawlist ( resource ftp_stream, string directory)ftp_rawlist() exécute la commande FTP LIST, et retourne le résultat dans un tableau. Chaque élément du tableau correspond à une ligne du résultat de la commande. Le résultat n'est pas analysé, et est retourné brut. L'identifiant de système retourné par ftp_systype() sera utile pour déterminer la façon d'interpréter le résultat.
ftp_rename
Description
bool ftp_rename ( resource ftp_stream, string from, string to)ftp_rename() retourne TRUE en cas de succès, et FALSE sinon.
ftp_rename() renomme le fichier ou dossier from en to, sur le serveur ftp_stream.
ftp_rmdir
Description
bool ftp_rmdir ( resource ftp_stream, string directory)ftp_rmdir() retourne TRUE en cas de succès, et FALSE sinon.
ftp_rmdir() efface le dossier directory.
ftp_set_option
Description
bool ftp_set_option ( resource ftp_stream, int option, mixed value)Note : This function is only available in CVS.
Returns TRUE if the option could be set; FALSE if not. A warning message will be thrown if the option is not supported or the passed value doesn't match the expected value for the given option.
This function controls various runtime options for the specified FTP stream. The value parameter depends on which option parameter is chosen to be altered. Currently, the following options are supported:
Tableau 1. Supported runtime FTP options
| FTP_TIMEOUT_SEC | Changes the timeout in seconds used for all network related functions. Parameter value has be to of type int and must be greater than 0. The default timeout is 90 seconds. |
ftp_site
Description
bool ftp_site ( resource ftp_stream, string cmd)ftp_site() retourne TRUE en cas de succès, et FALSE sinon.
ftp_site() envoie la commande cmd au serveur FTP. Les commandes SITE ne sont pas normalisées, et peuvent varier d'un serveur à l'autre. Elles permettent de gérer notamment les permissions de fichier, et les groupes.
ftp_size
Description
int ftp_size ( resource ftp_stream, string remote_file)ftp_size() retourne la taille du fichier en cas de succès, et FALSE sinon.
ftp_size() retourne la taille d'un fichier sur un serveur FTP. Si une erreur survient, ou que le fichier n'existe pas, la valeur -1 est retournée. Certains serveurs FTP ne supportent pas cette fonction.
ftp_systype
XXXIV. Fonctions
- Table des matières
- call_user_func_array -- Appelle une fonction utilisateur avec les paramètres rassemblés en tableau
- call_user_func -- Appelle une fonction utilisateur
- create_function -- Crée une fonction anonyme (style lambda)
- func_get_arg -- Retourne un élément de la liste des arguments
- func_get_args -- Retourne les arguments d'une fonction sous forme de tableau
- func_num_args -- Retourne le nombre d'arguments passé à la fonction
- function_exists -- Indique si une fonction est définie.
- get_defined_functions -- Liste toutes les fonctions définies
- register_shutdown_function -- Enregistre une fonction pour exécution à l'extinction
- register_tick_function -- Enregistre une fonction exécutée à chaque tick
- unregister_tick_function -- Annule la fonction exécutée à chaque tick
call_user_func_array
(PHP 4 >= 4.0.4)
call_user_func_array -- Appelle une fonction utilisateur avec les paramètres rassemblés en tableauDescription
mixed call_user_func_array ( string function_name [, array paramarr])call_user_func_array() appelle la fonction utilisateur function_name avec les paramètres paramarr, rassemblés dans un tableau. Par exemple:
<?php
function debug($var, $val)
echo "***DEBUGGING\nVARIABLE: $var\nVALUE:";
if (is_array($val) || is_object($val) || is_resource($val))
print_r($val);
else
echo "\n$val\n";
echo "***\n";
}
$c = mysql_connect();
$host = $HTTP_SERVER_VARS["SERVER_NAME"];
call_user_func_array ('debug', array("host", $host));
call_user_func_array ('debug', array("c", $c));
call_user_func_array ('debug', array("HTTP_POST_VARS", $HTTP_POST_VARS));
?> |
Voir aussi call_user_func(), call_user_method() et call_user_method_array().
Note : call_user_func_array() a été ajouté en version PHP 4.05.
call_user_func
Description
mixed call_user_func ( string function_name [, mixed parameter [, mixed ...]])call_user_func() appelle la fonction utilisateur function_name, et lui passe les paramètres parameter. Par exemple :
<?php
function barbier ($type) {
print "Vous vouliez une coupe $type, pas de problème";
}
call_user_func('barbier', "iroquois");
call_user_func('barbier', "militaire");
call_user_func('barbier', "au bol");
?> |
Voir aussi call_user_func_array(), call_user_method() et call_user_method_array().
create_function
Description
string create_function ( string args, string code)create_function() crée une fonction anonyme, à partir des paramètres passés, et retourne un nom de fonction unique. Généralement, les arguments args sont présentés sous la forme d'une chaîne à guillemets simples, et la même recommandation vaut pour code. La raison de l'utilisation des guillemets simples est de proteger les noms de variables du remplacement par leur valeur. Si vous utilisez les guillemets doubles, n'oubliez pas d'échapper les noms de variables (i.e. \$avar).
Vous pouvez utiliser cette fonction pour (par exemple) créer une fonction à partir d'informations récoltés durant l'éxécution.
Exemple 1. Création d'une fonction anonyme avec create_function()
|
Exemple 2. Traitement générique par fonction avec create_function()
|
Utilisation de la première liste de fonctions anonymes paramétres: 2.3445, M_PI Un peu de trigo: -1.6291725057799 Une hypoténuse: 3.9199852871011 b*a^2 = 4.8103313314525 min(b^2+a, a^2,b) = 8.6382729035898 ln(a/b) = 0.27122299212594 Utilisation de la seconde liste de fonctions anonymes ** "Twas the night" et "Twas brilling and the slithy toves" ** Ces chaînes de ressemblent!! (regarde les trois premiers caractères) CRCs: -725381282 , 1908338681 similarité(a,b) = 11(45.833333333333%) |
Exemple 3. Utilisation de fonctions anonymes comme fonction de callback
|
func_get_arg
Description
mixed func_get_arg ( int arg_num)func_get_arg() retourne l'argument à la position arg_num dans la liste d'argument d'une fonction utilisateur. Les arguments sont comptés en commençant à zéro. func_get_arg() générera une alerte si elle est appelée hors d'une fonction.
Si arg_num est plus grand que le nombre d'arguments passés, une alerte est générée et la fonction retourne FALSE.
<?php
function foo() {
$numargs = func_num_args();
echo "Nombre d'arguments: $numargs<br>\n";
if ($numargs >= 2) {
echo "Le second argument est: " . func_get_arg (1) . "<br>\n";
}
}
foo(1, 2, 3);
?> |
func_get_arg() peut être utilisé conjointement à func_num_args() et func_get_args() pour permettre aux fonctions utilisateurs d'accepter un nombre variable d'arguments.
Note : func_get_arg() a été ajoutée en PHP 4.
func_get_args
Description
array func_get_args ( void )func_get_args() retourne un tableau dont les éléments correspondent aux éléments de la liste d'arguments de la fonction. func_get_args() générera une alerte si elle est appelée hors d'une fonction.
<?php
function foo() {
$numargs = func_num_args();
echo "Nombre d'arguments: $numargs<br>\n";
if ($numargs >= 2) {
echo "Le second argument est: " . func_get_arg (1) . "<br>\n";
}
$arg_list = func_get_args();
for ($i = 0; $i < $numargs; $i++) {
echo "L'argument $i est: " . $arg_list[$i] . "<br>\n";
}
}
foo(1, 2, 3);
?> |
func_get_arg() peut être utilisé conjointement à func_num_args() et func_get_args() pour permettre aux fonctions utilisateurs d'accepter un nombre variable d'arguments.
Note : func_get_arg() a été ajoutée en PHP 4.
func_num_args
Description
int func_num_args ( void )func_num_args() retourne le nombre d'arguments passé à la fonction utilisateur courante. func_num_args() générera une alerte si elle est appelée hors d'une fonction.
<?php
function foo() {
$numargs = func_num_args();
echo "Nombre d'arguments: $numargs\n";
}
foo (1, 2, 3); // affiche 'Nombre d'arguments: 3'
?> |
func_get_arg() peut être utilisé conjointement à func_num_args() et func_get_args() pour permettre aux fonctions utilisateurs d'accepter un nombre variable d'arguments.
Note : func_get_arg() a été ajoutée en PHP 4.
function_exists
Description
boolean function_exists ( string function_name)function_exists() vérifie la liste des fonctions définies par l'utilisateur, et retourne TRUE si function_name y est trouvé, FALSE sinon.
<?php
if (function_exists('imap_open')) {
echo "Les fonctions IMAP sont disponibles.<br>\n";
} else {
echo "Les fonctions IMAP ne sont pas disponibles.<br>\n";
}
?> |
Voir aussi method_exists().
get_defined_functions
Description
array get_defined_functions ( void )get_defined_functions() retourne un tableau multi- dimensionnel, contenant la liste de toutes les fonctions définies, aussi bien les fonctions internes à PHP que celle déjà définie par l'utilisateur. Les noms des fonctions internes sont accessibles via $arr["internal"], et les fonctions utilisateur sont accessibles via $arr["user"].
<?php
function maligne($id, $data) {
return "<tr><th>$id</th><td>$data</td></tr>\n";
}
$arr = get_defined_functions();
print_r($arr);
?> |
Ce script va afficher :
Array
(
[internal] => Array
(
[0] => zend_version
[1] => func_num_args
[2] => func_get_arg
[3] => func_get_args
[4] => strlen
[5] => strcmp
[6] => strncmp
...
[750] => bcscale
[751] => bccomp
)
[user] => Array
(
[0] => maligne
)
) |
Voir aussi get_defined_vars().
register_shutdown_function
(PHP 3>= 3.0.4, PHP 4 )
register_shutdown_function -- Enregistre une fonction pour exécution à l'extinctionDescription
int register_shutdown_function ( string func)register_shutdown_function() enregistre la fonction func pour exécution à l'extinction du script.
Erreur courante :
Etant donné qu'aucun affichage n'est possible depuis la fonction func, vous ne pouvez pas y mettre d'informations de débuggage par print() ou echo()!
register_tick_function
Description
void register_tick_function ( string func [, mixed arg])register_tick_function() enregistre la fonction func pour être exécutée à chaque fois qu'un tick est appelé.
unregister_tick_function
Description
void unregister_tick_function ( string func [, mixed arg])unregister_tick_function() annule l'exécution automatique de func à chaque tick.
XXXV. Gettext (GNU)
Les fonctions gettext implémentent l'API NLS (Native Language Support) qui peut servir à internationaliser vos scripts PHP. Lisez la documentation GNU pour plus d'explications sur ces fonctions.
- Table des matières
- bind_textdomain_codeset -- Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
- bindtextdomain -- Fixe le chemin d'un domaine.
- dcgettext -- Remplace le domaine lors d'une recherche.
- dcngettext -- Plural version of dcgettext
- dgettext -- Remplace le domaine courant.
- dngettext -- Plural version of dgettext
- gettext -- Recherche un message dans le domaine courant.
- ngettext -- Plural version of gettext
- textdomain -- Fixe le domaine par défaut.
bind_textdomain_codeset
(PHP 4 >= 4.2.0)
bind_textdomain_codeset -- Specify the character encoding in which the messages from the DOMAIN message catalog will be returnedDescription
string bind_textdomain_codeset ( string domain, string codeset)
| Avertissement |
This function is currently not documented, only the argument list is available. |
bindtextdomain
Description
string bindtextdomain ( string domain, string directory)bindtextdomain() fixe le chemin du domaine domain à directory.
dcgettext
Description
string dcgettext ( string domain, string message, int category)dcgettext() permet de remplacer le domaine courant lors de la recherche d'un message. Elle permet aussi de spécifier une catégorie.
dcngettext
Description
string dcngettext ( string domain, string msgid1, string msgid2, int n, int category)
| Avertissement |
This function is currently not documented, only the argument list is available. |
dgettext
dngettext
Description
string dngettext ( string domain, string msgid1, string msgid2, int n)
| Avertissement |
This function is currently not documented, only the argument list is available. |
gettext
Description
string gettext ( string message)gettext() 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é. Vous pouvez utiliser le caractère souligné (_) comme alias de cette fonction.
Exemple 1. Vérification gettext()
|
ngettext
Description
string ngettext ( string msgid1, string msgid2, int n)
| Avertissement |
This function is currently not documented, only the argument list is available. |
textdomain
Description
string textdomain ( string text_domain)textdomain() fixe le domaine à utiliser lors de recherche avec gettext(). Ce domaine dépend généralement de l'application. Le domaine par défaut précédent est retourné. Appelez cette fonction avec with NULL comme paramètre pour avoir la valeur courante, sans la modifier.
XXXVI. GMP
Ces fonctions vous permettent de travailler avec des nombres de taille arbitraire, en utilisant la librairie GNU MP. Pour pouvoir y accéder, vous devez compiler PHP avec le support GMP en utilisant l'option --with-gmp.
Vous pouvez télécharger GMP sur le site de http://www.swox.com/gmp/. Ce site propose aussi un manuel GMP.
Vous devez utiliser GMP version 2 ou plus récent pour utiliser ces fonctions. Certaines d'entre elles peuvent requérir une version encore plus récente de GMP.
Ces fonctions ont été ajoutées en PHP 4.0.4.
Note : La majorité des fonctions GMP acceptent des nombres GMP comme arguments, définis ci-dessous comme resource. Cependant, la plupart de ces fonctions acceptent aussi des nombres et des chaînes à partir du moment où on peut les convertir en nombre. Si une fonction utilisant les entiers est plus rapide, elle sera automatiquement appelée si les arguments fournis sont des entiers. Cela se fait de manière transparente : vous pouvez donc utiliser des entiers avec les fonctions GMP sans perte de vitesse.
Voir aussi gmp_init().
- Table des matières
- gmp_abs -- Valeur absolue GMP
- gmp_add -- Addition de 2 nombres GMP
- gmp_and -- ET logique
- gmp_clrbit -- Annule un bit
- gmp_cmp -- Compare des nombres GMP
- gmp_com -- Calculates one's complement of a
- 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_div -- Divise deux nombres GMP
- gmp_divexact -- Division exacte de nombres GMP
- gmp_fact -- Factorielle GMP
- gmp_gcd -- PGCD
- gmp_gcdext -- PGCD étendu
- gmp_hamdist -- Distance de Hamming
- gmp_init -- Crée un nombre GMP
- gmp_intval -- Convertit un nombre GMP en entier.
- gmp_invert -- Inverse modulo
- gmp_jacobi -- Symbole de Jacobi
- gmp_legendre -- Symbole de Legendre
- gmp_mod -- Modulo GMP
- gmp_mul -- Multiplication de 2 nombres GMP
- gmp_neg -- Opposé de nombre GMP
- gmp_or -- OU logique
- gmp_perfect_square -- Carré parfait GMP
- gmp_popcount -- Compte de population
- gmp_pow -- Puissance
- gmp_powm -- Puissance et modulo
- gmp_prob_prime -- Nombre GMP probablement premier
- gmp_random -- Nombre GMP aléatoire
- 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_sqrtrm -- Racine carrée avec reste GMP
- gmp_strval -- Convertit un nombre GMP en chaîne
- gmp_sub -- Soustraction de 2 nombres GMP
- gmp_xor -- OU exclusif logique
gmp_abs
gmp_add
Description
resource gmp_add ( resource a, resource b)gmp_add() additionne les nombres GMP a et b. Le résultat est un nombre GMP.
gmp_and
gmp_clrbit
Description
resource gmp_clrbit ( resource &a, int index)gmp_clrbit() met le bit index à 0 dans le nombre GMP a.
gmp_cmp
Description
int gmp_cmp ( resource a, resource b)gmp_cmp() retourne une valeur positive si a > b, zéro si a = b et négative si a < b.
gmp_com
Description
resource gmp_com ( resource a)
| Avertissement |
This function is currently not documented, only the argument list is available. |
gmp_div_q
Description
resource gmp_div_q ( resource a, resource b [, int round])gmp_div_q() divise le nombre GMP b par a. Le résultat est un entier. L'arrondi du résultat est défini par round, 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
gmp_div_q() peut aussi être appelée gmp_div().
Voir aussi gmp_div_r() et gmp_div_qr().
gmp_div_qr
Description
array gmp_div_qr ( resource n, resource d [, int round])gmp_div_qr() divise n par d 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).
Voir gmp_div_q() pour une description du paramètre round.
Voir aussi gmp_div_q() et gmp_div_r().
gmp_div_r
Description
resource gmp_div_r ( resource n, resource d [, int round])gmp_div_r() le reste de la division entière de n par d. Le reste a le même signe que n, s'il est non nul.
Voir gmp_div_q() pour une description du paramètre round.
Voir aussi gmp_div_q() et gmp_div_qr().
gmp_div
gmp_divexact
Description
resource gmp_divexact ( resource n, resource d)gmp_divexact() divis n par d, en utilisant les algorithmes de "division exacte". Cette fonction ne fournit de résultats cohérents que s'il est su par avance que d divise n.
gmp_fact
gmp_gcd
Description
resource gmp_gcd ( resource a, resource b)gmp_gcd() calcule de PGCD (plus grand commun diviseur) de a et b. Le résultat est toujours positif, même si l'un des deux (ou les deux) nombres est négatif.
gmp_gcdext
Description
array gmp_gcdext ( resource a, resource b)gmp_gcdext() calcule les entiers g, s, et t, tels que a*s + b*t = g = gcd(a,b), où gcd est le pgcd de a et b. La fonction retourne un tableau avec les éléments g, s et t.
gmp_hamdist
Description
int gmp_hamdist ( resource a, resource b)gmp_hamdist() retourne la distance de Hamming entre a et b. Les deux paramètres doivent être strictement positifs.
gmp_init
Description
resource gmp_init ( mixed number)gmp_init() crée un nombre GMP, à partir d'un entier ou d'une chaîne. Les chaînes peuvent être en décimal ou en hexadécimal. Dans ce dernier cas, la chaîne doit commencer par0x.
| Avertissement |
Si vous devez explicitement spécifier un entier de grande taille, faites le avec une chaîne. Sinon, PHP va interpréter l'entier littéralement, et vous y perdrez en précision avant que les fonctions GMP n'entre en jeu. |
Note : Il n'est pas nécessaire d'appeler gmp_init() si vous voulez utiliser des entiers ou des chaînes à la place de nombre GMP dans les fonctions GMP, comme par exemple 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().
gmp_intval
Description
int gmp_intval ( resource gmpnumber)gmp_intval() convertit un nombre GMP en entier.
| Avertissement |
gmp_intval() retourne un résultat cohérent uniquement si le nombre GMP peut être représenté par un entier PHP (i.e. type long signé). Si vous vous voulez simplement afficher un nombre GMP, utilisez plutôt gmp_strval(). |
gmp_invert
Description
resource gmp_invert ( resource a, resource b)gmp_invert() calcule l'inverse de a modulo b. gmp_invert() retourne FALSE si un tel inverse n'existe pas.
gmp_jacobi
Description
int gmp_jacobi ( resource a, resource p)gmp_jacobi() calcule le symbole de Jacobi de a et p. p doit être positif et impair.
gmp_legendre
Description
int gmp_legendre ( resource a, resource p)gmp_legendre() calcule le symbole de Legendre de a et p. p doit être positif et impair.
gmp_mod
Description
resource gmp_mod ( resource n, resource d)gmp_mod() calcule n modulo d. Le résultat est toujours positif ou nul, car le signe de d est ignoré.
gmp_mul
Description
resource gmp_mul ( resource a, resource b)gmp_mul() multiplie les nombres GMP a et b. Le résultat est un nombre GMP.
gmp_neg
gmp_or
gmp_perfect_square
Description
boolean gmp_perfect_square ( resource a)gmp_perfect_square() retourn TRUE si a est un carré parfait, et FALSE sinon.
Voir aussi gmp_sqrt() et gmp_sqrtrm().
gmp_popcount
gmp_pow
Description
resource gmp_pow ( resource base, int exp)gmp_pow() élève base à la puissance exp. Dans le cas de 0^0, gmp_pow() retourne 1.exp ne doit pas être négatif.
gmp_powm
Description
resource gmp_powm ( resource base, resource exp, resource mod)gmp_powm() calcule (base puissnace exp) modulo mod. Si exp est négatif, le résultat est indéfini.
gmp_prob_prime
Description
int gmp_prob_prime ( resource a [, int reps])Si gmp_prob_prime() retourne 0, a est défini comme non premier. Si gmp_prob_prime() retourne 1, alors a est "probablement" premier. Si gmp_prob_prime() retourne 2, alors a est sÛrement premier. reps 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.
gmp_prob_prime() utilise le test de probabilité Miller-Rabin.
gmp_random
Description
resource gmp_random ( int limiter)gmp_random() génère un nombre aléatoire. Ce nombre est limité par limiter. Si limiter est négatif, un nombre négatif est généré.
gmp_scan0
Description
int gmp_scan0 ( resource a, int start)gmp_scan0() recherche dans a, en commençant à la position start, vers les bits de poids lourd, jusqu'à ce qu'elle rencontre un bit à 0. Sa position est alors retournée.
gmp_scan1
Description
int gmp_scan1 ( resource a, int start)gmp_scan1() recherche dans a, en commençant à la position start, vers les bits de poids lourd, jusqu'à ce qu'elle rencontre un bit à 1. Sa position est alors retournée.
gmp_setbit
Description
resource gmp_setbit ( resource &a, int index [, boolean set_clear])gmp_setbit() modifie le bit index dans a. set_clear indique si le bit est mis à 0 ou 1. Par défaut, il est mis à 1.
gmp_sign
Description
int gmp_sign ( resource a)gmp_sign() retourne le signe de a : 1 si a est positif et -1 s'il est négatif.
gmp_sqrt
gmp_sqrtrm
Description
array gmp_sqrtrm ( resource a)gmp_sqrtrm() retourne un tableau dont le premier élément est la racine carrée entière de a (voir aussi gmp_sqrt()), et le second est le reste de (i.e., la différence entre a et le carré du premier élément).
gmp_strval
Description
string gmp_strval ( resource gmpnumber [, int base])gmp_strval() convertit un nombre GMP en chaîne de caractères, dans la base base. La base par défaut est 10. Les valeurs possibles vont de 2 à 36.
gmp_sub
Description
resource gmp_sub ( resource a, resource b)gmp_sub() soustrait le nombre GMP b de a. Le résultat est un nombre GMP.
gmp_xor
Description
resource gmp_xor ( resource a, resource b)gmp_or() calcule le OU exclusif logique de a et b.
XXXVII. HTTP
Ces fonctions permettent de travailler sur les informations transmises au navigateur, via le protocole HTTP.
- Table des matières
- header -- Envoie une en-tête HTTP.
- headers_sent -- Indique si les entêtes HTTP ont déjà été envoyés
- setcookie -- Envoie un cookie
header
Description
int header ( string string)header() permet de spécifier une en-tête HTTP lors de l'envoi des fichiers HTML. Reportez-vous à HTTP 1.1 Specification pour plus d'informations sur les en-têtes HTTP.
Note : La fonction header() doit être appelée avant la première balise HTML, et avant n'importe quel envoi de commande PHP. C'est une erreur très courante que de lire du code avec la fonction include() ou avec auto_prepend et d'avoir des espaces ou des lignes vides dans ce code qui produisent un début de sortie avant que header() n'ait été appelé.
Il y a cependant deux en-têtes spéciales. Le premier est "Location". Non seulement il renvoie une en-tête au client, mais en plus, il envoie un statut de redirection à Apache. Du point de vue de l'auteur de script, cela importe peu, mais pour ceux qui connaissent les rouages internes d'Apache, c'est primordial.
<?php
header("Location: http://www.php.net/");
/* Redirige le client vers le site PHP */
exit();
/* Garantit que le code ci-dessous n'est jamais exécuté. */
?> |
Note : HTTP/1.1 demande une URI absolue comme argument de Location:, y compris le protocole, hôte et chemin absolu. Mais certains navigateurs acceptent les URI relatives. Vous pouvez généralement utiliser les variables globales $HTTP_SERVER_VARS['HTTP_HOST'], $HTTP_SERVER_VARS['PHP_SELF'] et dirname() pour construire vous-même une URI absolue :
Le deuxième type d'appel spécial regroupe toutes les en-têtes qui commencent par "HTTP/" (la casse n'est pas importante). Par exemple, si vous avez votre page d'erreur 404 Apache qui pointe sur un script PHP, c'est une bonne idée que de vous assurer que le script PHP génère une erreur 404. La première chose à faire dans votre script est :
Note : En PHP 3, cela ne fonctionne que si PHP est compilé comme module Apache. Vous pouvez arriver au même au résultat en utilisant l'entête Status.
Les scripts PHP génèrent souvent du HTML dynamiquement, qui ne doit pas être mis en cache, ni par le client, ni par les proxy intermédiaires. On peut forcer la désactivation du cache de nombreux clients et proxy avec
<?php
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date du passé
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT"); // toujours modifié
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Pragma: no-cache"); // HTTP/1.0
?> |
Note : Vous pouvez vous rendre compte que vos pages ne sont jamais mises en cache même si vous utilisez toutes les entêtes ci-dessus. Il existe toute une collection de paramètres que les utilisateurs peuvent modifier sur leur navigateur pour modifier le comportement par défaut du cache. En envoyant les entêtes ci-dessus, vous pouvez imposer vos propres valeurs.
De plus, les paramètres session_cache_limiter() et session.cache_limiter peuvent être utilisé pour générer les entêtes de caches corrects, lorsque les sessions sont utilisées.
N'oubliez jamais que header() doit être appelée avant que le moindre contenu ne soit envoyé, soit par des lignes HTML habituelles dans le fichier, soit par des affichges PHP. Une erreur très classique est de lire un fichier avec include() ou require(), et de laisser des espaces ou des lignes vides, qui génèreront un affichage avant que la fonction header() ne soit appelée. Le même problème existe avec les fichiers PHP/HTML standards.
<?php
require("user_logging.inc")
?>
<?php
header("Content-Type: audio/x-pn-realaudio");
?>
// Erreur : Notez la ligne blanche ci-dessus |
Note : En PHP 4, vous pouvez utiliser le système de cache (output buffering) pour contourner ce problème. Tous vos textes générés seront mis en buffer sur le serveur jusqu'à ce que vous les envoyiez. Vous pouvez utiliser les fonctions ob_start() et ob_end_flush() dans vos scripts, ou en modifiant la directive de configuration output_buffering dans votre fichier php.ini ou vos fichiers de configuration du serveur.
Si vous voulez que vos utilisateur recoivent une alerte pour sauver les fichiers générés, comme par exemple si vous générez un fichier PDF, vous pouvez utiliser l'entête Content-Disposition pour fournir un nom de fichier par défaut, à afficher dans le dialogue de sauvegarde.
<?php
header("Content-type: application/pdf");
header("Content-Disposition: attachment; filename=downloaded.pdf");
/* ... output pdf file ... */ |
Note : Il y a un bug sous Microsoft Internet Explorer 4.01 qui empêche cet entête de fonctionner. Il n'y a pas d'autre solution. Il y a aussi un bug dans Microsoft Internet Explorer 5.5 qui interfère avec ceci, mais qui peut être résolu en utilisant le Service Pack 2 ou plus récent.
Voir aussi headers_sent(), setcookie(), et la section sur l'authentification HTTP .
headers_sent
Description
boolean headers_sent ( void)headers_sent() retourne TRUE si les entêtes HTTP ont déjà été envoyés, et FALSE sinon.
Voir aussi header().
setcookie
Description
int setcookie ( string name [, string value [, int expire [, string path [, string domain [, int secure]]]]])setcookie() définit un cookie qui sera envoyé avec le reste des en-têtes. Les cookies doivent passer avant toute autre en-tête (c'est une restriction des cookies, pas de PHP). Cela vous impose d'appeler cette fonction avant toute balise <HTML> ou <HEAD>.
Tous les arguments sauf name (nom) sont optionnels. Si seul le nom est présent, le cookie portant ce nom sera supprimé du navigateur de l'internaute. Vous pouvez aussi utiliser une chaîne vide comme valeur, pour ignorer un argument. Le paramètre expire est un timestamp UNIX, du même genre que celui retourné par time() ou mktime(). Le paramètre secure indique que le cookie doit être uniquement transmis à travers une connexion HTTPS sécurisée.
Erreurs communes :
Les cookies ne seront accessibles qu'au chargement de la prochaine page, ou au rechargement de la page courante.
Les cookies doivent être effacés avec les mêmes paramètres que ceux utilisés lors de leur création.
En PHP 3, les appels multiples à setcookie() dans le même script seront effectués dans l'ordre inverse. Si vous essayez d'effacer un cookie avant d'insérer une nouvelle valeur, vous devez placer l'insertion avant l'effacement. En PHP 4, les appels multiples à setcookie() sont effectués dan un ordre naturel.
Les appels multiples à setcookie() dans la même page seront réalisés dans l'ordre inverse. Si vous essayez d'effacer un cookie avant d'insérer une autre valeur, il faut placer l'insertion avant l'effacement.
Quelques exemples :
Notez que la partie "valeur" du cookie sera automatiquement encodée URL lorsque vous envoyez le cookie, et lorsque vous le recevez, il sera automatiquement décodé, et affecté à la variable du même nom que le cookie. Pour voir le résultat, essayez les scripts suivants :
Vous pouvez aussi utiliser les cookies avec des tableaux, en utilisant la notation des tableaux. Cela a pour effet de créer autant de cookies que votre tableau a d'éléments, mais lorsque les cookies seront reçus par PHP, les valeurs seront placées dans un tableau :
<?php
setcookie( "cookie[three]", "cookiethree" );
setcookie( "cookie[two]", "cookietwo" );
setcookie( "cookie[one]", "cookieone" );
if ( isset( $cookie ) ) {
while( list( $name, $value ) = each( $cookie ) ) {
echo "$name == $value<br>\n";
}
}
?> |
Pour d'autres informations sur les cookies, jetez un oeil sur http://www.netscape.com/newsref/std/cookie_spec.html.
Microsoft Internet Explorer 4 utilisé avec le Service Pack 1 ne gère pas bien les cookies qui possèdent un paramètre path.
Netscape Communicator 4.05 et Microsoft Internet Explorer 3.x semblent ne pas gérer correctement les cookies lorsque path et time> ne sont pas fournis.
XXXVIII. Hyperwave
Introduction
Hyperwave a été développé par IICM à Graz. Son nom original était Hyper-G et il a pris le nom de Hyperwave lors de sa commercialisation (en 1996, si mes souvenirs sont bons).
Hyperwave n'est pas gratuit. La version actuelle est la 4.1, disponible à http://www.hyperwave.com/. Une version limitée à 30 jours peut être demandée.
HIS est un système d'information similaire à une base de données, (HIS, Hyperwave Information Server). HIS se concentre sur l'enregistrement et la gestion des documents. Un document peut être n'importe quelle donnée, qui peut être stockée dans un fichier. Chaque document est accompagné par un enregistrement. Cet enregistrement contient des méta données à propos du document. Ces méta données sont des listes d'attributs qui peuvent être étendues par l'utilisateur. Un attribut est une paire clé/valeur de la forme : clé =valeur. L'enregistrement complet contient autant de paire que le désire l'utilisateur. Le nom d'un attribut n'a pas besoin d'être unique, c'est-à-dire qu'une même clé peut apparaître plusieurs fois dans un enregistrement. Cela peut être utile si vous devez donner un titre à votre document en plusieurs langues, par exemple. Dans un cas pareil, la convention est que chaque valeur de titre est précédée par deux lettres et deux points, tel que : 'fr:Titre en français' ou 'ge:Titel in deutsch'. D'autres attributs comme une description ou des mots clés sont aussi susceptibles de recourir à ce genre de procédé. Vous pouvez aussi remplacer l'abréviation de langage par une autre chaîne, tant qu'elle est séparée de la valeur par les deux points.
Chaque enregistrement a une représentation native qui contient toutes les paires clé/valeur, séparées par un retour à la ligne. L'extension Hyperwave reconnaît une autre représentation qui est un tableau associatif, où les attributs servent de clés. Les attributs multilingues étant géré sous la forme d'un autre tableau associatif, dont les clés sont les chaînes de langue. En fait, tous les attributs multiformes sont gérés sous la forme de tableau associatif. (Cela n'est pas encore complètement codé. Uniquement les attributs de titre, description et mot clés sont traités correctement).
En dehors des documents, tous les hyper liens contenus dans un documents sont enregistrés dans un autre enregistrement. Les hyperliens qui sont à l'intérieur d'un document en seront supprimés, et enregistrés dans des objets particuliers, au moment de l'insertion dans la base de données. L'enregistrement des hyper-liens contient les informations d'origine et d'objectif. Afin d'accéder au document original, vous devrez lire le document sans les liens, puis lire les liens, et les réinsérer (les hw_pipedocument() et hw_gettext() le font pour vous. L'avantage de séparer les liens du document est évident : une fois qu'un document, cible d'un hyperlien, a été renommé, le liens peut facilement être modifié. Le document contenant le lien n'est pas modifié pour autant. Vous pouvez même ajouter un lien à un document sans le modifier.
Dire que hw_pipedocument() et hw_gettext() font l'insertion automatiquement n'est pas aussi simple qu'il n'y paraît. L'insertion implique une certaine hiérarchie de documents. Sur un serveur web, la hiérarchie est fournie par le système de fichiers, mais Hyperwave dispose de sa propre hiérarchie et les noms de fichiers ne reflètent pas la position d'un objet dans cette hiérarchie. Ainsi, la création de liens requiert en premier lieu la construction de la hiérarchie et de l'espace des noms dans une hiérarchie web et un espace de nom web. La différence fondamentale entre Hyperwave et le web est qu'il y a une distinction claire en les noms et la hiérarchie dans Hyperwave. Le nom ne contient aucune information à propos de la position de l'objet dans la hiérarchie. Sur le web, le nom contient les informations de localisation dans la hiérarchie. Cela conduit à deux méthodes de d'accès : soit la hiérarchie Hyperwave et le nom de l'objet sont inscrits dans l'URL. Pour simplifier les choses, une deuxième approche est pratiquée. L'objet Hyperwave de nom 'mon_objet' correspond à l'URL 'http://hote/mon_objet', peu importe alors où il est rangé dans la hiérarchie. Un objet dont le nom est 'parent/mon_objet' peut être le fils de l'objet 'mon_objet' dans la hiérarchie Hyperwave, bien que ce soit le contraire en convention web, et cela risque de perturber l'utilisateur.
Ayant pris cette décision, un deuxième problème surgit : comment faire l'interface avec PHP ? L'URL http://hote/mon_objet n'appellera aucun script PHP à moins que vous ne demandiez à votre serveur web de le remplacer par autre chose, comme par exemple : 'http://host/php3_script/mon_objet' et le script 'php3_script' utilise la variable $PATH_INFO pour rechercher l'objet 'mon_objet' sur le serveur Hyperwave. Il y a juste un petit inconvénient , qui peut facilement être corrigé. Réécrire une URL ne vous permettra aucun accès aux autres documents du serveur web. Un script de recherche dans le serveur Hyperwave serait impossible. Il vous faudra donc au moins une autre règle pour exclure certaines URL, comme par exemple celles qui commencent par http://host/Hyperwave. Voici, de manière simple, la manière de partager un espace de nom entre un serveur web et un serveur Hyperwave serveur.
Basé sur le mécanisme précédent, on trouve l'insertion dans les documents.
Il est plus compliqué d'avoir PHP ne fonctionne pas comme un module de serveur, ou un script CGI, mais comme une application indépendante. Dans ce cas, il est utile d'inscrire la hiérarchie et le nom de fichier Hyperwave dans le système de fichier. Mais comme cela risque d'entrer en conflit avec le séparateur de dossier ('/'), il faut le remplacer par un autre caractère,. '_'.
Le protocole réseau pour communiquer avec un serveur Hyperwave est appelé HG-CSP (Hyper-G Client/Server Protocol). Il est basé sur des messages qui initie des actions, comme par exemple, lire l'en-tête de fichier. Dans les premières versions de Hyperwave Server deux clients natifs (Harmony, Amadeus) étaient fournis pour permettre la communication avec le serveur. Ils ont disparu lors de la commercialisation de Hyperwave. En tant qu'ersatz, un client appelé wavemaster est désormais fourni. wavemaster est un espèce ce convertisseur de protocole de HTTP en HG-CSP. L'idée est de faire toute l'administration de la base et la visualisation des documents par une interface web. Le wavemaster implémente un jeu d'emplacement pour certaines actions de personnalisation de l'interface. Ce jeu est appelé PLACE language. PLACE pêche encore par le manque de nombreuses fonctions de programmation, et le manque d'évolutivité. Cela a conduit à l'utilisation de JavaScript ce qui ne rend pas la vie facile.
Que PHP supporte Hyperwave permet de combler ces manques. PHP implémente tous les messages définis par HG-CSP mais fourni d'autres commandes puissantes, comme par exemple, celle de lire des documents complets.
Hyperwave dispose de sa propre terminologie pour localiser certaines informations. Cette terminologie a été largement étendue. Presque toutes les fonctions utilisent l'un des types de données suivants :
object ID: un entier, unique pour chaque objet sur le serveur Hyperwave. C'est aussi un des attributs de l'enregistrement de l'objet (ObjectID).Les object ids sont souvent utilisées comme paramètre d'entrée pour spécifier un objet.
object record: Une chaîne contenant des paires clé=valeur. Les paires sont séparées par un retour à la ligne. Un enregistrement d'objet peut facilement être converti en tableau, avec la fonction hw_objrec2array(). De nombreuses fonctions retournent un object records. Ces fonctions ont leur nom qui finit par obj.
object array: Un tableau associatif qui contient tous les attributs d'un objet. La clé est l'attribut. Si un attribut apparaît plusieurs fois, il sera représenté sous la forme d'un tableau associatif ou indexé. Les attributs qui dépendent des langues (comme title, keyword ou description) seront représentés sous la forme d'un tableau associatif, dont les clés seront les abréviations de langues. Tous les autres attributs à valeur multiple prendront la forme d'un tableau indexé.
hw_document: Ce type est un nouveau type de données, qui contient le document lui-même, comme par exemple HTML, PDF etc. Il est optimisé pour les documents HTML mais peut s'utiliser avec n'importe quel format.
De nombreuses fonctions qui retournent un tableau d'enregistrements, retournent aussi un tableau associé, avec des informations statistiques. Ce tableau est le dernier élément du tableau d'enregistrements. Les statistiques contiennent les entrées suivantes :
- Hidden
Nombre d'objets dont l'attribut PresentationHints est Hidden.
- CollectionHead
Nombre d'objet dont l'attribut PresentationHints est CollectionHead.
- FullCollectionHead
Nombre d'objet dont l'attribut PresentationHints est FullCollectionHead.
- CollectionHeadNr
Index du premier objet du tableau d'enregistrement avec l'attribut PresentationHints à CollectionHead.
- FullCollectionHeadNr
Index du premier objet du tableau d'enregistrement avec l'attribut PresentationHints est FullCollectionHead.
- Total
Total: Nombre d'enregistrements.
Intégration avec Apache
L'extension Hyperwave est utilisée de manière optimale lorsque PHP est compilé comme module Apache. Dans ce cas, le serveur Hyperwave sous jacent peut être caché quasiment totalement aux utilisateurs, si Apache utilise son moteur d'écriture. Les explications suivantes vous éclaireront :
Etant donné que PHP avec l'extension Hyperwave et Apache tend à remplacer la solution native basée sur Wavemaster, je vais supposer que le serveur Apache servira seulement d'interface Hyperwave. Ce n'est pas nécessaire, mais cela simplifie grandment la configuration. Le concept est très simple. Premièrement, vous avez besoin d'un script PHP qui évalue la variable PATH_INFO et considère que cette valeur est un objet Hyperwave. Appelons ce script 'Hyperwave'. L'URL http://votre.hote/Hyperwave/nom_objet retourne alors l'objet Hyperwave dont le nom est 'nom_objet'. Le script doit alors réagir suivant le type de l'objet. Si c'est un groupe, il devra probablement retourner une liste de fils. Si c'est un document, il pourra retourner son type MIME et son contenu. Une amélioration peut être obtenue en utilisant le moteur de réécriture d'Apache. D'un point de vue utilisateur, il est plus direct si l'URL http://votre.hote/nom_objet retourne l'objet. La règle de réécriture est simple :
Maintenant toutes les URL pointent sur un objet Hyperwave. Cela conduit à un problème simple. Il n'y a pas d'autre façon d'exécuter, c'est-à-dire rechercher, un autre script que ce script 'Hyperwave'. Cela pourra être corrigé avec une autre règle telle que: Le dossier /usr/local/apache/htdocs/hw sera ainsi réservé pour d'autres scripts et fichiers. Assurez-vous que cette règle est évaluée avant la première règle que nous avons définie. Il y a juste un léger inconvénient : tous les objets Hyperwave qui commencent par 'hw/' seront cachés. Alors, assurez-vous que vous n'utilisez pas de tels noms. Si vous avez besoin d'autres dossiers, par exemple, un dossier d'images, ajoutez simplement d'autres règles. N'oubliez pas de lancer le moteur de réécriture avec Mon expérience m'a montré que vous aurez besoin des scripts suivants :Retourne l'objet lui-même
Pour autoriser la recherche
S'identifier
Choisir une configuration
Un script pour chaque fonction supplémentaire, comme afficher un objet, afficher des informations sur les utilisateurs, afficher le statut du serveur, etc...
A faire
Il reste encore beaucoup à faire :
La fonction hw_InsertDocument doit être séparée en deux : hw_insertobject() et hw_putdocument().
Les noms de nombreuses fonctions ne sont pas encore fixés.
La majorité des fonctions requièrent la connexion courante comme premier paramètre. Cela conduit à beaucoup de frappe clavier, même s'il n'y a souvent qu'une seule connexion en jeu. Une connexion par défaut améliorerait ceci.
- Table des matières
- hw_Array2Objrec -- Convertit un tableau en un objet.
- hw_changeobject -- Changes attributes of an object (obsolete)
- hw_Children -- Liste des object ids des objets fils.
- hw_ChildrenObj -- Liste des object records des objets fils.
- hw_Close -- Ferme la connexion Hyperwave.
- hw_Connect -- Ouvre une connexion Hyperwave.
- hw_connection_info -- Prints information about the connection to Hyperwave server
- hw_Cp -- Copie des objets.
- hw_Deleteobject -- Efface des objets.
- hw_DocByAnchor -- Identifiant d'objet de l'objet dans l'ancrage.
- hw_DocByAnchorObj -- Attributs de l'objet dans l'ancrage.
- hw_Document_Attributes -- object record of hw_document
- hw_Document_BodyTag -- body tag of hw_document
- hw_Document_Content -- returns content of hw_document
- hw_Document_SetContent -- sets/replaces content of hw_document
- hw_Document_Size -- size of hw_document
- hw_dummy -- Hyperwave dummy function
- hw_EditText -- Retourne un document texte.
- hw_Error -- Retourne le code d'erreur.
- hw_ErrorMsg -- Retourne un message d'erreur.
- hw_Free_Document -- Détruit un document.
- hw_GetAnchors -- Identifiants des ancrages d'un document.
- hw_GetAnchorsObj -- Attributs des ancrages d'un document.
- hw_GetAndLock -- Retourne les attributs, et verrouille l'objet.
- hw_GetChildColl -- Identifiant d'objet des groupes fils.
- hw_GetChildCollObj -- object records d'un groupe d'enfants.
- hw_GetChildDocColl -- ids des documents fils d'un groupe.
- hw_GetChildDocCollObj -- Attributs des documents fils d'un groupe.
- hw_GetObject -- Attributs d'un objet.
- hw_GetObjectByQuery -- Recherche un objet.
- hw_GetObjectByQueryColl -- Recherche un objet dans un groupe.
- hw_GetObjectByQueryCollObj -- Recherche un objet dans un groupe.
- hw_GetObjectByQueryObj -- Recherche un objet.
- hw_GetParents -- Identifiant d'objet des parents.
- hw_GetParentsObj -- Attributs des parents.
- hw_getrellink -- Get link from source to dest relative to rootid
- hw_GetRemote -- Retourne un document distant.
- hw_GetRemoteChildren -- Retourne les fils d'un document distant.
- hw_GetSrcByDestObj -- Retourne les ancrages qui pointent sur un objet.
- hw_GetText -- Retourne un document texte.
- hw_Username -- Nom de l'utilisateur actuellement identifié.
- hw_Identify -- Identifie un utilisateur.
- hw_InCollections -- Vérifie qu'un identifiant d'objet est dans un groupe.
- hw_Info -- Informations à propos d'une connexion.
- hw_InsColl -- Insère un groupe.
- hw_InsDoc -- Insère un document.
- hw_insertanchors -- Inserts only anchors into text
- hw_InsertDocument -- Insère un document dans un groupe.
- hw_InsertObject -- Insère un object record.
- hw_mapid -- Représente un id globale en un id virtuel local.
- hw_Modifyobject -- Modifie les attributs d'objet record.
- hw_Mv -- Déplace un objet.
- hw_New_Document -- Crée un nouveau document.
- hw_Objrec2Array -- Convertit les attributs d'un objet en tableau.
- hw_Output_Document -- prints hw_document
- hw_pConnect -- Crée une connexion persistante.
- hw_PipeDocument -- Retourne un document.
- hw_Root -- Object id de la racine.
- hw_setlinkroot -- Set the id to which links are calculated
- hw_stat -- Returns status string
- hw_Unlock -- Déverrouille un objet.
- hw_Who -- Liste des utilisateurs actuellement identifiés.
hw_Array2Objrec
Description
string hw_array2objrec ( array object_array)hw_array2objrec() convertit un object_array en un objet. Les attributs multiples tels que 'Title' en différentes langues seront traités correctement.
Voir aussi hw_objrec2array().
hw_changeobject
Description
void hw_changeobject ( int link, int objid, array attributes)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_Children
Description
array hw_children ( resource connection, resource objectID)hw_children() retourne un tableau avec des object ids. Chaque object id est celui d'un des fils du groupe dont l'id est objectID. Ce tableau contient tous les fils, documents et groupes.
hw_ChildrenObj
Description
array hw_childrenobj ( resource connection, resource objectID)hw_childrenobj() retourne un tableau avec des object records. Chaque object records est celui d'un des fils du groupe dont l'id est objectID. Ce tableau contient tous les fils, documents et groupes
hw_Close
Description
int hw_close ( resource connection)hw_close() retourne FALSE si la connexion n'est pas valide, et sinon, TRUE. Ferme la connexion connection à un serveur Hyperwave.
hw_Connect
Description
resource hw_connect ( string host, int port, string username, string password)hw_connect() ouvre une connexion Hyperwave et retourne un identifiant de connexion, en cas de succès, ou FALSE, si la connexion n'a pas pu être créée. Chaque argument doit être entouré de guillemets, sauf le numéro de port. Les arguments username et password sont optionnels, et peuvent être ignorés. Dans ce cas, aucune identification ne sera faite au niveau du serveur. Cela revient à s'identifier en tant qu'utilisateur anonyme. Cette fonction retourne un identifiant de connexion qui sera nécessaire aux autres fonctions Hyperwave. Vous pouvez avoir plusieurs connexions simultanées. N'oubliez pas que les mots de passe ne sont pas cryptés.
Voir aussi hw_pconnect().
hw_connection_info
(PHP 3>= 3.0.3, PHP 4 )
hw_connection_info -- Prints information about the connection to Hyperwave serverDescription
void hw_connection_info ( int link)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_Cp
Description
resource hw_cp ( resource connection, array object_id_array, int destination_id)hw_cp() copie les objets ayant les identifiants object_id_array, et crée un groupe ayant l'object id destination_id.
La valeur retournée est le nombre d'objets copiés.
Voir aussi hw_mv().
hw_Deleteobject
Description
int hw_deleteobject ( resource connection, int object_to_delete)hw_deleteobject() efface l'objet dont l'identifiant est object_to_delete. Toutes les instances de l'objet object_to_delete seront effacées.
hw_deleteobject() retourne TRUE si aucune erreur ne survient, et sinon, FALSE.
Voir aussi hw_mv().
hw_DocByAnchor
Description
resource hw_docbyanchor ( resource connection, int anchorID)hw_docbyanchor() retourne l'dentifiant d'objet de l'objet dans l'ancrage anchorID.
hw_DocByAnchorObj
Description
string hw_docbyanchorobj ( resource connection, int anchorID)hw_docbyanchorobj() retourne les attributs du document qui correspond à anchorID.
hw_Document_Attributes
Description
string hw_document_attributes ( int hw_document)Returns the object record of the document.
For backward compatibility, hw_documentattributes() is also accepted. This is deprecated, however.
See also hw_document_bodytag(), and hw_document_size().
hw_Document_BodyTag
Description
string hw_document_bodytag ( int hw_document)Returns the BODY tag of the document. If the document is an HTML document the BODY tag should be printed before the document.
See also hw_document_attributes(), and hw_document_size().
For backward compatibility, hw_documentbodytag() is also accepted. This is deprecated, however.
hw_Document_Content
Description
string hw_document_content ( int hw_document)Returns the content of the document. If the document is an HTML document the content is everything after the BODY tag. Information from the HEAD and BODY tag is in the stored in the object record.
See also hw_document_attributes(), hw_document_size(), and hw_document_setcontent().
hw_Document_SetContent
Description
string hw_document_setcontent ( int hw_document, string content)Sets or replaces the content of the document. If the document is an HTML document the content is everything after the BODY tag. Information from the HEAD and BODY tag is in the stored in the object record. If you provide this information in the content of the document too, the Hyperwave server will change the object record accordingly when the document is inserted. Probably not a very good idea. If this functions fails the document will retain its old content.
See also hw_document_attributes(), hw_document_size(), and hw_document_content().
hw_Document_Size
Description
int hw_document_size ( int hw_document)Returns the size in bytes of the document.
See also hw_document_bodytag(), and hw_document_attributes().
For backward compatibility, hw_documentsize() is also accepted. This is deprecated, however.
hw_dummy
Description
string hw_dummy ( int link, int id, int msgid)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_EditText
Description
int hw_edittext ( resource connection, int hw_document)hw_edittext() charge le texte du document sur le serveur. Les attributs du document ne doivent pas être modifiés tant que le document est en train d'être édité. Cette fonction n'est disponible que sur les documents texte. Elle n'ouvrira pas de canal de transfert, et donc, bloquera le script durant le transfert.
Voir aussi hw_pipedocument(), hw_free_document(), hw_documentbodytag(), hw_documentsize(), hw_outputdocument() et hw_gettext().
hw_Error
Description
int hw_error ( resource connection)hw_error() retourne le code d'erreur de la dernière erreur. Si la valeur 0 est retournée, c'est qu'il n'y avait pas d'erreur. L'erreur se rapporte à la dernière commande.
hw_ErrorMsg
Description
string hw_errormsg ( resource connection)hw_errormsg() retourne une chaîne contenant le dernier message d'erreur, ou 'No Error' (pas d'erreur). Si FALSE est retourné, cette fonction a échoué. Ce message est relatif à la dernière commande exécutée.
hw_Free_Document
Description
int hw_free_document ( resource hw_document)hw_free_document() détruit un document Hyperwave.
hw_GetAnchors
Description
array hw_getanchors ( resource connection, resource objectID)hw_getanchors() retourne un tableau contenant les identifiants des ancrages du document objectID.
hw_GetAnchorsObj
Description
array hw_getanchorsobj ( resource connection, resource objectID)hw_getanchorsobj() retourne un tableau d'attributs des ancrages du document objectID.
hw_GetAndLock
Description
string hw_getandlock ( resource connection, resource objectID)hw_getandlock() retourne les attributs, et verrouille l'objet objectID. Le verrouillage empêchera les autres utilisateurs d'y accéder, jusqu'à ce qu'il soit deverrouillé.
Voir aussi hw_unlock() et hw_getobject().
hw_GetChildColl
Description
array hw_getchildcoll ( resource connection, resource objectID)hw_getchildcoll() retourne un tableau contenant les identifiants d'objets des groupes fils du groupe objectID. Cette fonction ne retournera pas d'identifiants d'objets des documents fils.
Voir aussi hw_getchilddoccoll().
hw_GetChildCollObj
Description
array hw_getchildcollobj ( resource connection, resource objectID)hw_getchildcollobj() retourne un tableau d'object record. Chaque object records appartient à un groupe d'enfants de la collection objectID. La fonction ne retournera pas de documents enfants.
Voir aussi hw_childrenobj() et hw_getchilddoccollobj().
hw_GetChildDocColl
Description
array hw_getchilddoccoll ( resource connection, resource objectID)hw_getchilddoccoll() retourne un tableau avec les id des documents fils d'une collection.
Voir aussi hw_getchildcoll().
hw_GetChildDocCollObj
Description
array hw_getchilddoccollobj ( resource connection, resource objectID)hw_getchilddoccollobj() retourne un tableau contenant les attributs des documents fils du groupe objectID.
Voir aussi hw_childrenobj() et hw_getchildcollobj().
hw_GetObject
Description
array hw_getobject ( resource connection, int|array objectID, string query)hw_getobject() retourne les attributs de l'objet dont l'identifiant est objectID, si le second paramètre est un entier. Si le second paramètre est un tableau, la fonction retournera un tableau d'attributs. Dans ce cas, le dernier paramètre est aussi évalué.
query a la syntaxe suivante :
<expression> ::= "(" <expression> ")" |
"!" <expression> | /* NOT */
<expression> "||" <expression> | /* OR */
<expression> "&&" <expression> | /* AND */
<attribute> <operator> <value>
<attribute> ::= /* * n'importe quel attribut (Title, Author, DocumentType ...) */
<operator> ::= "=" | /* égal */
"<" | /* moins que (comparaison de type chaîne) */
">" | /* plus que (comparaison de type chaîne) */
"~" /* recherche par expression régulière */
query permet de sélectionner une nouvelle fois certains objets dans la liste des objets donnés. Contrairement aux autres requêtes, celle-ci peut utiliser des attributs non indexés. Le nombre d'attributs retourné dépend de la requête de la requête, et des autorisations d'accès aux objets.
Voir aussi hw_getandlock() et hw_getobjectbyquery().
hw_GetObjectByQuery
Description
array hw_getobjectbyquery ( resource connection, string query, int max_hits)hw_getobjectbyquery() recherche un objet sur tout le serveur et retourne un tableau d' object ids. Le nombre maximum d'objet est limité par max_hits. Si max_hits vaut -1 il n'y a pas de limite.
La requête ne fonctionnera qu'avec des attributs indexés.
Voir aussi hw_getobjectbyqueryobj().
hw_GetObjectByQueryColl
Description
array hw_getobjectbyquerycoll ( resource connection, resource objectID, string query, int max_hits)hw_getobjectbyquerycoll() recherche un objet sur tout le groupe objectID et retourne un tableau d' object records. Le nombre maximum d'objet est limité par objectID. Si objectID vaut -1 il n'y a pas de limite.
La requête ne fonctionnera qu'avec des attributs indexés.
Voir aussi hw_getobjectbyquerycollobj().
hw_GetObjectByQueryCollObj
Description
array hw_getobjectbyquerycollobj ( resource connection, resource objectID, string query, int max_hits)hw_getobjectbyquerycollobj() recherche un objet sur tout le groupe objectID et retourne un tableau d' object records. Le nombre maximum d'objet est limité par objectID. Si objectID vaut -1 il n'y a pas de limite.
La requête ne fonctionnera qu'avec des attributs indexés.
Voir aussi hw_getobjectbyquerycoll().
hw_GetObjectByQueryObj
Description
array hw_getobjectbyqueryobj ( resource connection, string query, int max_hits)hw_getobjectbyqueryobj() recherche un objet sur tout le serveur et retourne un tableau d' object records. Le nombre maximum d'objet est limité par max_hits. Si max_hits vaut -1 il n'y a pas de limite.
La requête ne fonctionnera qu'avec des attributs indexés.
Voir aussi hw_getobjectbyquery().
hw_GetParents
Description
array hw_getparents ( resource connection, resource objectID)hw_getparents() retourne un tableau indexé avec les identifiants des objets parents de objectID.
hw_GetParentsObj
Description
array hw_getparentsobj ( resource connection, resource objectID)hw_getparentsobj() retourne un tableau indexé, avec les attributs et un tableau associé, d'informations statistiques à propos des attributs. Ce tableau associé est le dernier élément du tableau retourné. Chaque attribut appartient au père de l'objet objectID.
hw_getrellink
Description
string hw_getrellink ( int link, int rootid, int sourceid, int destid)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_GetRemote
Description
resource hw_getremote ( resource connection, resource objectID)hw_getremote() retourne un document distant. Les documents distants sont , en Hyperwave, des documents lus depuis une source externe. La plupart des documents éloignés sont des pages web externes, ou des requêtes sur une base de données. Afin de pouvoir accéder à des sources externes, grâce aux documents distants, Hyperwave introduit l'interface HGI (Hyperwave Gateway Interface) qui est similaire à CGI. Actuellement, seuls les protocoles de FTP, HTTP et certaines bases de données sont accessibles avec HGI. hw_getremote() retourne le document de la source distante. Si vous voulez utiliser cette fonction, il vous faut vous familiariser avec HGIs. Il est aussi préférable d'utiliser PHP plutôt que Hyperwave pour accéder aux sources externes. Le support des bases de données sera plus difficile avec Hyperwave que PHP.
Voir aussi hw_getremotechildren().
hw_GetRemoteChildren
Description
resource hw_getremotechildren ( resource connection, string object_record)hw_getremotechildren() retourne les fils d'un document distant. Les fils d'un document distant sont des documents distants eux mêmes. Cela est cohérent si une requête sur une base de données doit être rendu plus sélective, comme expliqué dans Hyperwave Programmers' Guide. Si le nombre de fils est 1 la fonction va retourner le document lui-même, la fonction retournera le document lui-même, formaté Hyperwave Gateway Interface (HGI). Si le nombre de fils est supérieur 1 la fonction retournera un tableau d'attributs, qui pourra servir à une nouvelle requête avec hw_getremotechildren(). Ces attributs sont virtuels et n'existent pas sur le serveur Hyperwave, et ainsi, n'ont pas d'identifiant d'objet valide. L'ordre exact de ces objets est du ressort de HGI. Si vous voulez utiliser cette fonction, vous devez être très familier HGIs. Il vaut mieux PHP plutôt que Hyperwave pour accéder aux fichiers distants. Le support de base de données y est bien meilleur.
Voir aussi hw_getremote().
hw_GetSrcByDestObj
Description
array hw_getsrcbydestobj ( resource connection, resource objectID)hw_getsrcbydestobj() retourne les attributs de tous les ancrages qui pointent sur objectID. L'objet peut être un document ou un autre ancrage, de type destination.
Voir aussi hw_getanchors().
hw_GetText
Description
int hw_gettext ( resource connection, resource objectID [, mixed rootID/prefix])hw_gettext() retourne le document de l'objet objectID. Si le document possède des ancrages qui peuvent être insérés, ils seront déjà insérés. L'option rootID/prefix peut être une chaîne ou un entier. Si c'est un entier, il détermine la méthode d'insertion des liens dans le document. Par défaut, il vaut 0 et les liens seront construits en fonction du nom de l'objet cible. Cela sert beaucoup dans les applications web. Si un lien pointe sur un objet avec le nom 'film_internet' le lien HTML sera <A HREF="/internet_movie">. La position réelle de la source et de la cible dans la hiérarchie seront ignorés. Vous devrez modificer votre site web pour qu'il réécrive les URL, comme par exemple '/mon_script.php3/film_internet'. 'mon_script.php3' devra analyser $PATH_INFO et savoir recherche le document '/mon_script.php3/film_internet'. Si vous ne voulez pas de ce comportement, vous pouvez affecter à rootID/prefix n'importe quel prefixe. Dans ce cas, ce sera une chaîne.
Si rootID/prefix est un entier différent de 0 le lien sera construit avec tous les noms de la hiérarchie, en commençant à l'objet d'identifiant rootID/prefix, et séparé par des slash. Si, par exemple, le document 'film_internet' est situé à 'a-b-c-internet_movie' et '-' qui sert de séparateur hiérarchique de niveau sur le serveur Hyperwave et le document source est situé dans 'a-b-d-source' alors, le lien HTML serait: <A HREF="../c/internet_movie">. Cela est très pratique si vous voulez télécharger tout le contenu d'un serveur sur un disque, et faire une carte du système sur votre disque.
hw_gettext() n'est opérationnelle qu'avec des documents de pur texte. Elle n'ouvrira pas de canal spécial de transfert, et ainsi, bloquera le script le temps du transfert.
Voir aussi hw_pipedocument(), hw_free_document(), hw_documentbodytag(), hw_documentsize() et hw_outputdocument().
hw_Username
Description
string hw_getusername ( resource connection)hw_getusername() retourne le nom d'utilisateur utilisé par la connexion.
hw_Identify
Description
int hw_identify ( string username, string password)hw_identify() identifie un utilisateur, dont le nom d'utilisateur est username et le mot de passe password. L'identification n'est valide que pour la session en cours. Je ne pense pas que cette fonction serve souvent. Dans la plupart des cas, il est plus simple de s'identifier lors de l'ouverture de la connexion.
Voir aussi hw_connect().
hw_InCollections
Description
array hw_incollections ( resource connection, array object_id_array, array collection_id_array, int return_collections)hw_incollections() vérifie qu'un ensemble d'objets (documents ou groupes) donnés par object_id_array fait partie des groupe listés par object_id_array. Lorsque le quatrième paramètre return_collections vaut 0, le sous ensemble d'identifiants qui font partie d'un groupe (i.e. les documents ou groupes qui sont fils d'un ou plusieurs groupe, ou leurs fils, récursivement) est retourné sous la forme d'un tableau. Cette option permet de mettre en valeur la partie de l'arborescence qui contient le résultat d'une requête, dans un sens graphique.
hw_Info
Description
string hw_info ( resource connection)hw_info() retourne les informations de la connexion courante. La chaîne retournée a le format suivant : <Serverstring>, <Host>, <Port>, <Username>, <Port of Client>, <Byte swapping>
hw_InsColl
Description
int hw_inscoll ( resource connection, resource objectID, array object_array)hw_inscoll() insère un nouveau groupe, avec les attributs object_array dans le groupe objectID.
hw_InsDoc
Description
int hw_insdoc ( resource connection, int parentID, string object_record, string text)hw_insdoc() insère un nouveau document avec les attributs object_record, dans le groupe parentID. Cette fonction insère soit un objet avec ses seuls attributs, soit pur objet ascii, avec text s'il est fourni. Si vous voulez insérer un document de type général, utilisez plutôt hw_insertdocument().
Voir aussi hw_insertdocument() et hw_inscoll().
hw_insertanchors
Description
string hw_insertanchors ( int hwdoc, array anchorecs, array dest [, array urlprefixes])
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_InsertDocument
Description
int hw_insertdocument ( resource connection, int parent_id, int hw_document)hw_insertdocument() insère un document dans le groupe parent_id. Le document doit avoir été créé auparavant avec hw_new_document(). Assurez-vous que les attributs du nouveau document contiennent au moins les attributs suivants : Type, DocumentType, Title et Name. Vous aurez aussi parfois besoin de MimeType. La fonction retourne l'identifiant de l'objet inséré, ou bien FALSE.
Voir aussi hw_pipedocument().
hw_InsertObject
Description
int hw_insertobject ( resource connection, string object_rec, string parameter)hw_insertobject() insère un objet dans le serveur. L'objet peut être n'importe quel objet Hyperwave valide. Reportez-vous à la documentation HG-CSP pour plus de détails sur les paramètres.
Note: Si vous voulez insérer un ancre, l'attribut Position doit être mis à la valeur start/end (début ou fin) ou encore 'invisible'. Les positions invisibles sont nécessaire si l'annotation n'a pas de liens correspondant dans le texte de l'annotation.
Voir aussi hw_pipedocument(), hw_insertdocument(), hw_insdoc() et hw_inscoll().
hw_mapid
Description
int hw_mapid ( resource connection, int server_id, int object_id)hw_mapid() représente l'id d'un objet global de n'importe quel serveur Hyperwave, même si vous ne vous y êtes pas connecté avec hw_connect(), avec un id d'objet local virtuel. Cet id d'objet local peut alors être utilisé comme n'importe quel id d'objet : par exemple on peut obtenir l'enregistrement d'objet avec la fonction hw_getobject(). L'id du serveur est la première partie de l'id global (GOid) de l'objet, qui est en fait une adresse IP.
Note: Afin d'utiliser cette fonction, vous devez lever le flag F_DISTRIBUTED, ce qui ne peut être fait qu'à la compilation. Par défaut, il n'est pas levé. Lisez les commentaires dans le fichier hg_comm.c
hw_Modifyobject
Description
int hw_modifyobject ( resource connection, int object_to_change, array remove, array add, int mode)hw_modifyobject() permet d'effacer, d'ajouter ou de modifier les attributs d'un objet. L'objet est reperé par son identifiant object_to_change. Le premier tableau, remove, est la liste des attributs à effacer. Le deuxième tableau add est la liste des attributs à ajouter. Afin de modifier un attribut, il vous faudra dont l'effacer, puis l'ajouter à nouveau. hw_modifyobject() effacera toujours les attributs avant de les ajouter, à moins que la valeur de l'attribut à effacer ne soit pas une chaîne, ou un tableau.
Le dernier paramètre détermine si la modification est récursive ou pas. 1 signifie que la modification est récursive. Si un objet ne peut pas être modifié, il sera ignoré. hw_error() n'indiquera alors pas toujours d'erreur, même si certains objets n'ont pas pu être modifié.
Les clés des deux tableaux sont les noms des attributs. La valeur de chaque élément peut être un tableau, ou une chaîne ou n'importe quoi d'autre. Dans le cas du tableau, la valeur de l'attribut est construite en séparant chaque élément par un point virgule. Dans le cas de la chaîne, elle sert directement de valeur. Une chaîne vide provoquera un effacement de l'attribut. Dans le cas où la valeur n'est ni un tableau, ni une chaîne, aucune opération ne sera effectuée. Cela est nécessaire si vous voulez ajouter un attribut complètement une nouvelle valeur pour un attribut existant. Si le tableau d'effacement contenait une chaîne vide comme attribut, le serveur tenterait d'effacer l'attribut, ce qui échouerai de toute manière, car cet attribut n'existe pas. L'ajout de cet attribut échouerai aussi. Affecter la valeur de 0 à cet attribut ne l'effacerait pas, et l'ajout fonctionnerait.
Si vous voulez changer l'attribut 'Nom' de valeur courante 'livres' en 'articles' vous devrez faire deux tableaux, et appeler hw_modifyobject().
Note : Les attributs multilingues, (tels que 'Title'), peuvent être modifiés de deux manières : soit en fournissant la valeur de ces attributs de manière native (langue :valeur), soit en fournissant un tableau avec les éléments de chaque langue, comme décrit ci-dessus. L'exemple deviendrai alors :
Note : Cet exemple va effacer tous les attributs avec le nom 'Title' et ajouter un nouvel attribut 'Title'. Cela peut être pratique pour effacer des attributs récursivement.
Note : Si vous devez effacer tous les attributs avec un certains nom, vous devez passer une chaîne vide comme valeur.
Note : Seuls les attributs 'Title', 'Description' et 'Keyword' gère correctement le préfixe de langue. Pour les autres attributs qui ne portent pas de préfixe de language, le préfixe 'xx' sera assigné.
Note : L'attribut 'Name' est un peu particuluer. Dans certains cas, il ne peut pas être complétement effacé. Vous aurez alors le message 'Change of base attribute' (l'apparition de cette erreur n'est pas très claire). Ainsi, vous aurez à ajouter une nouvelle entrée pour Name puis, effacer l'ancien.
Note : Il ne faut pas encadrer cette fonction par des appels à hw_getandlock() et hw_unlock(). hw_modifyobject() le fait de manière interne.
Retourne TRUE si aucune erreur ne survient, et FALSE sinon.
hw_Mv
Description
int hw_mv ( resource connection, array object_id_array, int source_id, int destination_id)hw_mv() déplaces les objets dont les identifiants sont passés dans le tableau source_id, depuis le source_id dans le destination_id. Si destination id vaut 0, les objets ne seront plus insérés dans le groupe (ni dans le serveur). Dans ce cas, si une instance était la dernière instance d'un objet, l'objet sera effacé. Si vous voulez effacer toutes les instances d'un coup, utilisez hw_deleteobject().
La valeur retournée est le nombre d'objet déplacés.
Voir aussi hw_cp() et hw_deleteobject().
hw_New_Document
Description
int hw_new_document ( string object_record, string document_data, int document_size)hw_new_document() retourne un nouveau document Hyperwave avec comme données document_data et comme attributs object_record. La longueur de document_data doit être données dans document_size. Cette fonction n'insère pas l'objet dans le serveur Hyperwave.
Voir aussi hw_free_document(), hw_documentsize(), hw_documentbodytag(), hw_outputdocument() et hw_insertdocument().
hw_Objrec2Array
Description
array hw_objrec2array ( string object_record)hw_objrec2array() convertit les attributs object_record d'un objet en un tableau. Les clés du tableau seront les noms des attributs. Les attributs multiples comme par exemple 'Title', dans différentes langues, seront rassemblées dans un autre tableau. Une clé est la partie gauche d'un attribut. Actuellement, seuls les attributs 'Title', 'Description' et 'Keyword' sont traités correctement.
Voir aussi hw_array2objrec().
hw_Output_Document
Description
int hw_output_document ( int hw_document)Prints the document without the BODY tag.
For backward compatibility, hw_outputdocument() is also accepted. This is deprecated, however.
hw_pConnect
Description
int hw_pconnect ( string host, int port, string username, string password)hw_pconnect() retourne un index de connexion en cas de succès, et FALSE si la connexion n'a pas pu être créée. hw_pconnect() ouvre une connexion persistante à un serveur Hyperwave. Tous les arguments doivent être entre guillemets, hormis le numéro de port port. Les arguments username et password sont optionnels, et peuvent être ignorés. Dans ce cas, aucune authentification ne sera faite, (connexion anonyme). Cette fonction retourne un index de connexion qui sera utilisée par les autres fonctions Hyperwave. Vous pouvez ouvrir plusieurs connexions simultanées.
Voir aussi hw_connect().
hw_PipeDocument
Description
int hw_pipedocument ( resource connection, resource objectID)hw_pipedocument() retourne le document Hyperwave d'objet id objectID. Si le document a des ancrages, ils seront insérés. Le document sera transmis via une connexion de données spéciale, qui ne bloque pas la connexion de contrôle (ie, le serveur n'attend pas la fin du transfert pour rendre la main).
Voir aussi hw_gettext() (insertions), hw_free_document(), hw_documentsize(), hw_documentbodytag() et hw_outputdocument().
hw_Root
Description
int hw_root ( void)hw_root() retourne l'object id de la racine. Actuellement, cette identifiant est toujours 0. L'ensemble des fils de la racine est celui du serveur courant.
hw_setlinkroot
Description
void hw_setlinkroot ( int link, int rootid)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_stat
Description
string hw_stat ( int link)
| Avertissement |
This function is currently not documented, only the argument list is available. |
hw_Unlock
Description
int hw_unlock ( resource connection, resource objectID)hw_unlock() déverrouille un document, et laisse l'accès aux autres utilisateurs.
Voir aussi hw_getandlock().
hw_Who
Description
int hw_who ( resource connection)hw_who() retourne un tableau contenant la liste des utilisateurs actuellement connectés au serveur Hyperwave. Chaque élément du tableau est lui-même un tableau, qui contient l'identifiant de l'élément, le nom, le système, la date de connexion (onSinceDate), l'heure de connexion (onSinceTime), la durée de connexion (TotalTime ) et self. 'self' contient l'élément est l'utilisateur qui a appelé la fonction.
XXXIX. Hyperwave API functions
Introduction
Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (If I remember properly it was in 1996).
Hyperwave is not free software. The current version, 5.5, is available at www.hyperwave.com. A time limited version can be ordered for free (30 days).
Hyperwave is an information system similar to a database (HIS, Hyperwave Information Server). Its focus is the storage and management of documents. A document can be any possible piece of data that may as well be stored in file. Each document is accompanied by its object record. The object record contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by the user.
Requirements
Since 2001 there is a Hyperwave SDK available. It supports Java, JavaScript and C++. This PHP Extension is based on the C++ interface. In order to activate the hwapi support in PHP you will have to install the Hyperwave SDK first and configure PHP with --with-hwapi=<dir$gt;.
Classes
The API provided by the HW_API extension is fully object oriented. It is very similar to the C++ interface of the Hyperwave SDK. It consist of the following classes.
HW_API
HW_API_Object
HW_API_Attribute
HW_API_Error
HW_API_Content
HW_API_Reason
Each class has certain method, whose names are identical to its counterparts in the Hyperwave SDK. Passing arguments to this function differs from all the other PHP Extension but is close to the C++ API of the HW SDK. Instead of passing serval parameters they are all put into an associated array and passed as one paramter. The names of the keys are identical to those documented in the HW SDK. The common parameters are listed below. If other parameters are required they will be documented if needed.
objectIdentifier The name or id of an object, e.g. "rootcollection", "0x873A8768 0x00000002".
parentIdentifier The name or id of an object which is considered to be a parent.
object An instance of class HW_API_Object.
parameters An instance of class HW_API_Object.
version The version of an object.
mode An integer value determine the way an operation is executed.
attributeSelector Any array of strings, each containing a name of an attribute. This is used if you retrieve the object record and want to include certain attributes.
objectQuery A query to select certain object out of a list of objects. This is used to reduce the number of objects which was delivered by a function like hw_api->children() or hw_api->find().
Integration with Apache
The integration with Apache and possible other servers is already described in the Hyperwave Modul which has been the first extension to connect a Hyperwave Server.
- Table des matières
- hw_api_attribute->key -- Returns key of the attribute
- hw_api_attribute->langdepvalue -- Returns value for a given language
- hw_api_attribute->value -- Returns value of the attribute
- hw_api_attribute->values -- Returns all values of the attribute
- hw_api_attribute -- Creates instance of class hw_api_attribute
- hw_api->checkin -- Checks in an object
- hw_api->checkout -- Checks out an object
- hw_api->children -- Returns children of an object
- hw_api_content->mimetype -- Returns mimetype
- hw_api_content->read -- Read content
- hw_api->content -- Returns content of an object
- hw_api->copy -- Copies physically
- hw_api->dbstat -- Returns statistics about database server
- hw_api->dcstat -- Returns statistics about document cache server
- hw_api->dstanchors -- Returns a list of all destination anchors
- hw_api->dstofsrcanchors -- Returns destination of a source anchor
- hw_api_error->count -- Returns number of reasons
- hw_api_error->reason -- Returns reason of error
- hw_api->find -- Search for objects
- hw_api->ftstat -- Returns statistics about fulltext server
- hwapi_hgcsp -- Returns object of class hw_api
- hw_api->hwstat -- Returns statistics about Hyperwave server
- hw_api->identify -- Log into Hyperwave Server
- hw_api->info -- Returns information about server configuration
- hw_api->insert -- Inserts a new object
- hw_api->insertanchor -- Inserts a new object of type anchor
- hw_api->insertcollection -- Inserts a new object of type collection
- hw_api->insertdocument -- Inserts a new object of type document
- hw_api->link -- Creates a link to an object
- hw_api->lock -- Locks an object
- hw_api->move -- Moves object between collections
- hw_api_content -- Create new instance of class hw_api_content
- hw_api_object->assign -- Clones object
- hw_api_object->attreditable -- Checks whether an attribute is editable
- hw_api_object->count -- Returns number of attributes
- hw_api_object->insert -- Inserts new attribute
- hw_api_object -- Creates a new instance of class hw_api_object
- hw_api_object->remove -- Removes attribute
- hw_api_object->title -- Returns the title attribute
- hw_api_object->value -- Returns value of attribute
- hw_api->object -- Retrieve attribute information
- hw_api->objectbyanchor -- Returns the object an anchor belongs to
- hw_api->parents -- Returns parents of an object
- hw_api_reason->description -- Returns description of reason
- hw_api_reason->type -- Returns type of reason
- hw_api->remove -- Delete an object
- hw_api->replace -- Replaces an object
- hw_api->setcommitedversion -- Commits version other than last version
- hw_api->srcanchors -- Returns a list of all source anchors
- hw_api->srcsofdst -- Returns source of a destination object
- hw_api->unlock -- Unlocks a locked object
- hw_api->user -- Returns the own user object
- hw_api->userlist -- Returns a list of all logged in users
hw_api_attribute->key
hw_api_attribute->langdepvalue
Description
string langdepvalue ( string language)Returns the value in the given language of the attribute.
See also hwapi_attribute_value().
hw_api_attribute->value
Description
string value ( void )Returns the value of the attribute.
See also hwapi_attribute_key(), hwapi_attribute_values().
hw_api_attribute->values
Description
array values ( void )Returns all values of the attribute as an array of strings.
See also hwapi_attribute_value().
hw_api_attribute
Description
object attribute ( [string name [, string value]])Creates a new instance of hw_api_attribute with the given name and value.
hw_api->checkin
Description
object checkin ( array parameter)This function checks in an object or a whole hiearchie of objects. The parameters array contains the required element 'objectIdentifier' and the optional element 'version', 'comment', 'mode' and 'objectQuery'. 'version' sets the version of the object. It consists of the major and minor version separated by a period. If the version is not set, the minor version is incremented. 'mode' can be one of the following values:
- HW_API_CHECKIN_NORMAL
Checks in and commits the object. The object must be a document.
- HW_API_CHECKIN_RECURSIVE
If the object to check in is a collection, all children will be checked in recursively if they are documents. Trying to check in a collection would result in an error.
- HW_API_CHECKIN_FORCE_VERSION_CONTROL
Checks in an object even if it is not under version control.
- HW_API_CHECKIN_REVERT_IF_NOT_CHANGED
Check if the new version is different from the last version. Unless this is the case the object will be checked in.
- HW_API_CHECKIN_KEEP_TIME_MODIFIED
Keeps the time modified from the most recent object.
- HW_API_CHECKIN_NO_AUTO_COMMIT
The object is not automatically commited on checkin.
See also hwapi_checkout().
hw_api->checkout
Description
object checkout ( array parameter)This function checks out an object or a whole hiearchie of objects. The parameters array contains the required element 'objectIdentifier' and the optional element 'version', 'mode' and 'objectQuery'. 'mode' can be one of the following values:
- HW_API_CHECKIN_NORMAL
Checks out an object. The object must be a document.
- HW_API_CHECKIN_RECURSIVE
If the object to check out is a collection, all children will be checked out recursively if they are documents. Trying to check out a collection would result in an error.
See also hwapi_checkin().
hw_api->children
Description
array children ( array parameter)Retrieves the children of a collection or the attributes of a document. The children can be further filtered by specifying an object query. The parameter array contains the required elements 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
The return value is an array of objects of type HW_API_Object or HW_API_Error.
See also hwapi_parents().
hw_api_content->mimetype
hw_api_content->read
Description
string read ( string buffer, integer len)Reads len bytes from the content into the given buffer.
hw_api->content
Description
object content ( array parameter)This function returns the content of a document as an object of type hw_api_content. The parameter array contains the required elements 'objectidentifier' and the optional element 'mode'. The mode can be one of the constants HW_API_CONTENT_ALLLINKS, HW_API_CONTENT_REACHABLELINKS or HW_API_CONTENT_PLAIN. HW_API_CONTENT_ALLLINKS means to insert all anchors even if the destination is not reachable. HW_API_CONTENT_REACHABLELINKS tells hw_api_content() to insert only reachable links and HW_API_CONTENT_PLAIN will lead to document without any links.
hw_api->copy
Description
object copy ( array parameter)This function will make a physical copy including the content if it exists and returns the new object or an error object. The parameter array contains the required elements 'objectIdentifier' and 'destinationParentIdentifier'. The optional parameter is 'attributeSelector'`
See also hwapi_move(), hwapi_link().
hw_api->dbstat
Description
object dbstat ( array parameter)
See also hwapi_dcstat(), hwapi_hwstat(), hwapi_ftstat().
hw_api->dcstat
Description
object dcstat ( array parameter)
See also hwapi_hwstat(), hwapi_dbstat(), hwapi_ftstat().
hw_api->dstanchors
Description
object dstanchors ( array parameter)Retrieves all destination anchors of an object. The parameter array contains the required element 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
See also hwapi_srcanchors().
hw_api->dstofsrcanchors
Description
object dstofsrcanchors ( array parameter)Retrieves the destination object pointed by the specified source anchors. The destination object can either be a destination anchor or a whole document. The parameters array contains the required element 'objectIdentifier' and the optional element 'attributeSelector'.
See also hwapi_srcanchors(), hwapi_dstanchors(), hwapi_objectbyanchor().
hw_api_error->count
hw_api_error->reason
hw_api->find
Description
array find ( array parameter)This functions searches for objects either by executing a key or/and full text query. The found objects can further be filtered by an optional object query. They are sorted by their importance. The second search operation is relatively slow and its result can be limited to a certain number of hits. This allows to perform an incremental search, each returning just a subset of all found documents, starting at a given index. The parameter array contains the 'keyquery' or/and 'fulltextquery' depending on who you would like to search. Optional parameters are 'objectquery', 'scope', 'lanugages' and 'attributeselector'. In case of an incremental search the optional parameters 'startIndex', numberOfObjectsToGet' and 'exactMatchUnit' can be passed.
hw_api->ftstat
Description
object ftstat ( array parameter)
See also hwapi_dcstat(), hwapi_dbstat(), hwapi_hwstat().
hwapi_hgcsp
Description
object hwapi_hgcsp ( string hostname [, int port])Opens a connection to the Hyperwave server on host hostname. The protocol used is HGCSP. If you do not pass a port number, 418 is used.
See also hwapi_hwtp().
hw_api->hwstat
Description
object hwstat ( array parameter)
See also hwapi_dcstat(), hwapi_dbstat(), hwapi_ftstat().
hw_api->identify
Description
object identify ( array parameter)Logs into the Hyperwave Server. The parameter array must contain the elements 'username' und 'password'.
The return value will be an object of type HW_API_Error if identification failed or TRUE if it was successful.
hw_api->info
Description
object info ( array parameter)
See also hwapi_dcstat(), hwapi_dbstat(), hwapi_ftstat(), hwapi_hwstat().
hw_api->insert
Description
object insert ( array parameter)Insert a new object. The object type can be user, group, document or anchor. Depending on the type other object attributes has to be set. The parameter array contains the required elements 'object' and 'content' (if the object is a document) and the optional parameters 'parameters', 'mode' and 'attributeSelector'. The 'object' must contain all attributes of the object. 'parameters' is an object as well holding futher attributes like the destination (attribute key is 'Parent'). 'content' is the content of the document. 'mode' can be a combination of the following flags:
- HW_API_INSERT_NORMAL
The object in inserted into the server.
- HW_API_INSERT_FORCE-VERSION-CONTROL
- HW_API_INSERT_AUTOMATIC-CHECKOUT
- HW_API_INSERT_PLAIN
- HW_API_INSERT_KEEP_TIME_MODIFIED
- HW_API_INSERT_DELAY_INDEXING
See also hwapi_replace().
hw_api->insertanchor
Description
object insertanchor ( array parameter)This function is a shortcut for hwapi_insert(). It inserts an object of type anchor and sets some of the attributes required for an anchor. The parameter array contains the required elements 'object' and 'documentIdentifier' and the optional elements 'destinationIdentifier', 'parameter', 'hint' and 'attributeSelector'. The 'documentIdentifier' specifies the document where the anchor shall be inserted. The target of the anchor is set in 'destinationIdentifier' if it already exists. If the target does not exists the element 'hint' has to be set to the name of object which is supposed to be inserted later. Once it is inserted the anchor target is resolved automatically.
See also hwapi_insertdocument(), hwapi_insertcollection(), hwapi_insert().
hw_api->insertcollection
Description
object insertcollection ( array parameter)This function is a shortcut for hwapi_insert(). It inserts an object of type collection and sets some of the attributes required for a collection. The parameter array contains the required elements 'object' and 'parentIdentifier' and the optional elements 'parameter' and 'attributeSelector'. See hwapi_insert() for the meaning of each element.
See also hwapi_insertdocument(), hwapi_insertanchor(), hwapi_insert().
hw_api->insertdocument
Description
object insertdocument ( array parameter)This function is a shortcut for hwapi_insert(). It inserts an object with content and sets some of the attributes required for a document. The parameter array contains the required elements 'object', 'parentIdentifier' and 'content' and the optional elements 'mode', 'parameter' and 'attributeSelector'. See hwapi_insert() for the meaning of each element.
See also hwapi_insert() hwapi_insertanchor(), hwapi_insertcollection().
hw_api->link
Description
object link ( array parameter)Creates a link to an object. Accessing this link is like accessing the object to links points to. The parameter array contains the required elements 'objectIdentifier' and 'destinationParentIdentifier'. 'destinationParentIdentifier' is the target collection.
The function returns true on success or an error object.
See also hwapi_copy().
hw_api->lock
Description
object lock ( array parameter)Locks an object for exclusive editing by the user calling this function. The object can be only unlocked by this user or the sytem user. The parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'. 'mode' determines how an object is locked. HW_API_LOCK_NORMAL means, an object is locked until it is unlocked. HW_API_LOCK_RECURSIVE is only valid for collection and locks all objects within th collection und possible subcollections. HW_API_LOCK_SESSION means, an object is locked only as long as the session is valid.
See also hwapi_unlock().
hw_api->move
hw_api_content
Description
string content ( string content, string mimetype)Creates a new content object from the string content. The mimetype is set to mimetype.
hw_api_object->assign
hw_api_object->attreditable
hw_api_object->count
hw_api_object->insert
Description
bool insert ( object attribute)Adds an attribute to the object. Returns true on success and otherwise false.
See also hwapi_object_remove().
hw_api_object
hw_api_object->remove
Description
bool remove ( string name)Removes the attribute with the given name. Returns true on success and otherwise false.
See also hwapi_object_insert().
hw_api_object->title
hw_api_object->value
Description
string value ( string name)Returns the value of the attribute with the given name or false if an error occured.
hw_api->object
Description
object hw_api->object ( array parameter)This function retrieves the attribute information of an object of any version. It will not return the document content. The parameter array contains the required elements 'objectIdentifier' and the optional elements 'attributeSelector' and 'version'.
The returned object is an instance of class HW_API_Object on success or HW_API_Error if an error occured.
This simple example retrieves an object and checks for errors.
Exemple 1. Retrieve an object
|
See also hwapi_content().
hw_api->objectbyanchor
Description
object objectbyanchor ( array parameter)This function retrieves an object the specified anchor belongs to. The parameter array contains the required element 'objectIdentifier' and the optional element 'attributeSelector'.
See also hwapi_dstofsrcanchor(), hwapi_srcanchors(), hwapi_dstanchors().
hw_api->parents
Description
array parents ( array parameter)Retrieves the parents of an object. The parents can be further filtered by specifying an object query. The parameter array contains the required elements 'objectidentifier' and the optional elements 'attributeselector' and 'objectquery'.
The return value is an array of objects of type HW_API_Object or HW_API_Error.
See also hwapi_children().
hw_api_reason->description
hw_api_reason->type
hw_api->remove
Description
object remove ( array parameter)This function removes an object from the specified parent. Collections will be removed recursively. You can pass an optional object query to remove only those objects which match the query. An object will be deleted physically if it is the last instance. The parameter array contains the required elements 'objectidentifier' and 'parentidentifier'. If you want to remove a user or group 'parentidentifier' can be skiped. The optional parameter 'mode' determines how the deletion is performed. In normal mode the object will not be removed physically until all instances are removed. In physical mode all instances of the object will be deleted imediately. In removelinks mode all references to and from the objects will be deleted as well. In nonrecursive the deletion is not performed recursive. Removing a collection which is not empty will cause an error.
See also hwapi_move().
hw_api->replace
Description
object replace ( array parameter)Replaces the attributes and the content of an object The parameter array contains the required elements 'objectIdentifier' and 'object' and the optional parameters 'content', 'parameters', 'mode' and 'attributeSelector'. 'objectIdentifier' contains the object to be replaced. 'object' contains the new object. 'content' contains the new content. 'parameters' contain extra information for HTML documents. HTML_Language is the letter abbreviation of the language of the title. HTML_Base sets the base attribute of the HTML document. 'mode' can be a combination of the following flags:
- HW_API_REPLACE_NORMAL
The object on the server is replace with the object passed.
- HW_API_REPLACE_FORCE_VERSION_CONTROL
- HW_API_REPLACE_AUTOMATIC_CHECKOUT
- HW_API_REPLACE_AUTOMATIC_CHECKIN
- HW_API_REPLACE_PLAIN
- HW_API_REPLACE_REVERT_IF_NOT_CHANGED
- HW_API_REPLACE_KEEP_TIME_MODIFIED
See also hwapi_insert().
hw_api->setcommitedversion
Description
object setcommitedversion ( array parameter)Commits a version of a docuemnt. The commited version is the one which is visible to users with read access. By default the last version is the commited version.
See also hwapi_checkin(), hwapi_checkout(), hwapi_revert().
hw_api->srcanchors
Description
object srcanchors ( array parameter)Retrieves all source anchors of an object. The parameter array contains the required element 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
See also hwapi_dstanchors().
hw_api->srcsofdst
Description
object srcsofdst ( array parameter)Retrieves all the source anchors pointing to the specified destination. The destination object can either be a destination anchor or a whole document. The parameters array contains the required element 'objectIdentifier' and the optional element 'attributeSelector' and 'objectQuery'. The function returns an array of objects or an error.
See also hwapi_dstofsrcanchor().
hw_api->unlock
Description
object unlock ( array parameter)Unlocks a locked object. Only the user who has locked the object and the system user may unlock an object. The parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'. The meaning of 'mode' is the same as in function hwapi_lock().
Returns true on success or an object of class HW_API_Error.
See also hwapi_lock().
hw_api->user
hw_api->userlist
XL. ICAP
Pour faire fonctionner ces fonctions, vous devez compiler PHP avec l'option --with-icap. Il vous faudra aussi la librairie icap. Récupérez la dernière version à http://icap.chek.com/ et décompilez-la, puis installez la.
- Table des matières
- icap_close -- Ferme le flot ICAP.
- icap_create_calendar -- Create a new calendar
- icap_delete_calendar -- Delete a calendar
- icap_delete_event -- Efface un événement dans un agenda ICAP.
- icap_fetch_event -- Recherche un événement dans le calendrier.
- icap_list_alarms -- Retourne une liste d'événements qui ont une alarme prévue à une date.
- icap_list_events -- Retourne une liste d'événement entre deux dates.
- icap_open -- Ouvre une connexion ICAP.
- icap_rename_calendar -- Rename a calendar
- icap_reopen -- Reopen ICAP stream to new calendar
- icap_snooze -- Eteind l'alarme d'un événement.
- icap_store_event -- Enregistre un événement dans un agenda ICAP.
icap_close
Description
int icap_close ( resource icap_stream [, int flags])icap_close() ferme le flot ICAP icap_stream.
icap_create_calendar
Description
string icap_create_calendar ( int stream_id, string calendar)
| Avertissement |
This function is currently not documented, only the argument list is available. |
icap_delete_calendar
Description
string icap_delete_calendar ( int stream_id, string calendar)
| Avertissement |
This function is currently not documented, only the argument list is available. |
icap_delete_event
Description
string icap_delete_event ( resource stream_id, int uid)icap_delete_event() efface l'événement d'identifiant uid.
icap_delete_event() retourne TRUE.
icap_fetch_event
Description
int icap_fetch_event ( resource stream_id, int event_id [, int options])icap_fetch_event() recherche un évenement dans le calendrier spécifié par id.
icap_fetch_event() retourne un objet événement dont les attributs sont :
int id - ID de l'événement.
int public - TRUE si l'événement est public, FALSE si il est privé.
string category - Catégorie de l'événement.
string title - Titre de l'événement.
string description - Description de l'événement.
int alarm - Nombre de minutes avant d'envoyer une alerte pour cet événement.
object start - Objet contenant une date et une heure.
object end - Objet contenant une date et une heure.
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
icap_list_alarms
Description
int icap_list_alarms ( resource stream_id, array date, array time)icap_list_alarms() retourne un tableau d'identifiants, qui ont une alarme de prévue à la date alarm_date.
icap_list_alarms() prend une date, et retourne un tableau d'identifiants.
Tous les objets de date et heure sont construits comme suit :
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
icap_list_events
Description
array icap_list_events ( resource stream_id, int begin_date [, int end_date])icap_list_events() retourne un tableau d'identificants d'événéments, compris entre deux dates.
icap_list_events() prend une date de début et une date de fin. Un tableau d'identifiants est retourné.
Tous les objets de date et heure sont construits comme suit :
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
icap_open
Description
resource icap_open ( string calendar, string username, string password, string options)icap_open() retourne un flot ICAP en cas de succès, FALSE en cas d'erreur.
icap_open() ouvre une connexion ICAP au serveur de calendrier calendar. Si le paramètre options est spécifié, passe options à la boîte aux lettres(????).
icap_rename_calendar
Description
string icap_rename_calendar ( int stream_id, string old_name, string new_name)
| Avertissement |
This function is currently not documented, only the argument list is available. |
icap_reopen
Description
int icap_reopen ( int stream_id, string calendar [, int options])
| Avertissement |
This function is currently not documented, only the argument list is available. |
icap_snooze
Description
string icap_snooze ( resource stream_id, int uid)icap_snooze() éteind l'alarme de l'événement identifié par l'UID uid.
icap_snooze() retourne TRUE.
icap_store_event
Description
string icap_store_event ( resource stream_id, object event)icap_store_event() enregistre un événement dans un calendrier ICAP.
Un événement est un objet avec les attributs suivants :
int id - ID de l'événement.
int public - TRUE si l'événement est public, FALSE si il est privé.
string category - Catégorie de l'événement.
string title - Titre de l'événement.
string description - Description de l'événement.
int alarm - Nombre de minutes avant d'envoyer une alerte pour cet événement.
object start - Objet contenant une date et une heure.
object end - Objet contenant une date et une heure.
Tous les objets de date et heure sont construits comme suit :
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
icap_store_event() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
XLI. Iconv
Ce module est une interface vers la librairie iconv. Pour pouvoir l'utiliser, vous devez compiler PHP avec l'option --with-iconv. Pour cela, vous devez avoir la fonction iconv() dans votre librairie standard C, ou bien la librairie libiconv installée sur votre système. La librairie libiconv est disponible à http://www.gnu.org/software/libiconv/.
L'extension iconv convertit des fichiers entre divers jeux de caractères. Les jeux supportés dépendent de l'implémentation de iconv() sur votre système. Notez que cette fonction ne fonctionne pas toujours bien sur tous les systèmes. Dans ce cas, vous devez installer la librairie tout de même.
- Table des matières
- iconv_get_encoding -- Lit le jeu de caractères courant
- iconv_set_encoding -- Modifie le jeu courant de caractères courant
- iconv -- Convertit une chaîne dans un jeu de caractères
- ob_iconv_handler -- Gestionnaire de sortie pour maitriser le jeu de caractères de sortie
iconv_get_encoding
Description
array iconv_get_encoding ( [string type])iconv_get_encoding() retourne le paramètrage courant du gestionnaire ob_iconv_handler(), sous la forme d'un tableau, ou bien FALSE, en cas d'échec.
Voir aussi iconv_set_encoding() et ob_iconv_handler().
iconv_set_encoding
Description
array iconv_set_encoding ( string type, string charset)iconv_set_encoding() modifie le jeu de caractères courant, et remplace la valeur courante du paramétre type par charset et TRUE en cas de succès et FALSE, en cas d'échec.
Voir aussi iconv_get_encoding() et ob_iconv_handler().
iconv
Description
string iconv ( string in_charset, string out_charset, string str)iconv() convertit la chaîne string depuis le jeu de caractères in_charset vers le jeu de caractères out_charset. Elle retourne la chaîne ainsi convertie, ou bien FALSE, en cas d'échec.
ob_iconv_handler
(PHP 4 >= 4.0.5)
ob_iconv_handler -- Gestionnaire de sortie pour maitriser le jeu de caractères de sortieDescription
array ob_iconv_handler ( string contents, int status)ob_iconv_handler() convertit la chaîne utilisant le jeu de caractères internal_encoding en une chaîne utilisant le jeu de caractères output_encoding.
internal_encoding et output_encoding doivent être définis par iconv_set_encoding() ou dans le fichier de configuration.
Voir aussi iconv_get_encoding() et iconv_set_encoding().
XLII. Images
Vous pouvez utiliser les fonctions PHP pour obtenir les tailles des images aux formats JPEG, GIF, PNG et SWF, et si vous avez la librairie GD (disponible à http://www.boutell.com/gd/) vous pourrez aussi créer et manipuler ces images.
Les formats des images que vous pourrez manipuler dépendent de la version de GD que vous installerez, et de toute autre librairie dont GD a besoin pour traiter à ces images. Les versions antérieures à la version 1.6 supportent le GIF, mais pas le PNG. Pour les versions plus récentes, c'est le contraire.
Pour accéder aux images en JPEG, vous devez installer la librairie jpeg-6b (disponible à ftp://ftp.uu.net/graphics/jpeg/), puis, recompiler GD pour qu'elle utilise jpeg-6b. Vous devrez aussi compiler PHP avec --with-jpeg-dir=/path/to/jpeg-6b.
Pour ajouter le support des polices Type 1, vous devez installer t1lib (disponible à ftp://sunsite.unc.edu/pub/Linux/libs/graphics/), puis ajouter l'option --with-t1lib[=dir].
- Table des matières
- exif_imagetype -- Determine the type of an image
- exif_read_data -- Read the EXIF headers from JPEG or TIFF
- exif_thumbnail -- Retrieve the embedded thumbnail of a TIFF or JPEG image
- getimagesize -- Retourne la taille d'une image.
- image_type_to_mime_type -- Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- image2wbmp -- Crée une image WBMP
- ImageAlphaBlending -- Modifie le mode de blending d'une image
- ImageArc -- Dessine une ellipse partielle.
- ImageChar -- Dessine un caractère horizontalement.
- ImageCharUp -- Dessine un caractère verticalement.
- ImageColorAllocate -- Alloue une couleur pour 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 -- Get the index of the color which has the hue, white and blackness nearest to the given color
- ImageColorDeAllocate -- Désalloue une couleur pour une image
- ImageColorExact -- Retourne l'index de la couleur donnée.
- ImageColorExactAlpha -- Retourne l'index d'une couleur avec son canal alpha
- 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.
- 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.
- imagecreatefromgd2 -- Create a new image from GD2 file or URL
- imagecreatefromgd2part -- Create a new image from a given part of GD2 file or URL
- imagecreatefromgd -- Create a new image from GD file or URL
- imagecreatefromgif -- Crée une nouvelle image à partir d'un fichier ou d'une URL.
- ImageCreateFromJPEG -- Crée une nouvelle image JPEG à partir d'un fichier ou d'une URL
- ImageCreateFromPNG -- Crée une nouvelle image PNG à partir d'un fichier ou d'une URL
- ImageCreateFromString -- Crée une image à partir d'une chaîne
- ImageCreateFromWBMP -- Crée une image depuis un fichier WBMP
- ImageCreateFromXBM -- Crée une image à partir d'un fichier XBM
- ImageCreateFromXPM -- Crée une image à partir d'un fichier XPM
- ImageCreateTrueColor -- Crée une nouvelle image en vraies couleurs
- ImageDashedLine -- Dessine une ligne pointillée.
- ImageDestroy -- détruit une image.
- ImageEllipse -- Dessine une ellipse
- ImageFill -- Remplit.
- imagefilledarc -- Dessine une ellipse partielle et la remplit
- ImageFilledEllipse -- Dessine une ellipse pleine
- ImageFilledPolygon -- Dessine un polygone rempli.
- ImageFilledRectangle -- Dessine un rectangle rempli.
- ImageFillToBorder -- Remplit avec une région avec une couleur spécifique.
- ImageFontHeight -- Retourne la hauteur de la police.
- ImageFontWidth -- Retourne la largeur de la police.
- imageftbbox -- Give the bounding box of a text using fonts via freetype2
- imagefttext -- Write text to the image using fonts using FreeType 2
- ImageGammaCorrect -- Applique une correction gamma à l'image
- imagegd2 -- Output GD2 image to browser or file
- imagegd -- Output GD image to browser or file
- ImageGif -- Envoie une image GIF vers un navigateur ou un fichier.
- ImageInterlace -- Active ou désactive l'entrelacement.
- ImageJPEG -- Envoie une image JPEG vers un navigateur ou un fichier.
- ImageLine -- Dessine une ligne.
- ImageLoadFont -- Charge une nouvelle police.
- ImagePaletteCopy -- Copie la palette d'une image à l'autre
- ImagePNG -- Envoie une image PNG vers un navigateur ou un fichier.
- ImagePolygon -- Dessine un polygone.
- ImagePSBBox -- Retourne le rectangle entourant un texte et dessiné avec une police PostScript Type1.
- imagepscopyfont -- Fait une copie d'une police chargée pour modification ultérieure.
- ImagePSEncodeFont -- Change le codage vectoriel d'un caractère dans une police.
- ImagePsExtendFont -- Etend ou condense une police de caractères
- ImagePSFreeFont -- Libère la mémoire occupée par une police PostScript Type 1.
- ImagePSLoadFont -- Charge une police PostScript Type 1 depuis un fichier.
- ImagePsSlantFont -- Incline une police de caractères
- ImagePSText -- Dessine un texte sur une image avec une police PostScript Type1.
- ImageRectangle -- Dessine un rectangle.
- imagesetbrush -- Modifie la brosse pour le dessin des lignes
- ImageSetPixel -- Dessine un pixel.
- imagesetstyle -- Set the style for line drawing
- 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 vraies couleurs 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 -- Affiche une image WBMP
- iptcembed -- Embed binary IPTC data into a JPEG image
- iptcparse -- Parse a binary IPTC http://www.iptc.org/ block into single tags.
- JPEG2WBMP -- Convertit une image JPEG en image WBMP
- PNG2WBMP -- Convertit une image PNG en image WBMP
- read_exif_data -- Lit les en-têtes EXIF d'une image JPEG
exif_imagetype
Description
int|false exif_imagetype ( string filename)exif_imagetype() reads the first bytes of an image and checks its signature. When a correct signature is found a constant will be returned otherwise the return value is FALSE. The return value is the same value that getimagesize() returns in index 2 but this function is much faster.
The following constants are defined: 1 = IMAGETYPE_GIF, 2 = IMAGETYPE_JPG, 3 = IMAGETYPE_PNG, 4 = IMAGETYPE_SWF, 5 = IMAGETYPE_PSD, 6 = IMAGETYPE_BMP, 7 = IMAGETYPE_TIFF_II (intel byte order), 8 = IMAGETYPE_TIFF_MM (motorola byte order), 9 = IMAGETYPE_JPC, 10 = IMAGETYPE_JP2, 11 = IMAGETYPE_JPX, 12 = IMAGETYPE_SWC.
This function can be used to avoid calls to other exif functions with unsupported file teypes or in conjunction with $_SERVER['HTTP_ACCEPT'] to check whether or not the viewer is able to see a specific image in his browser.
Note : This function is only available in PHP 4 compiled using --enable-exif.
This function does not require the GD image library.
See also getimagesize().
exif_read_data
Description
array exif_read_data ( string filename [, string sections [, bool arrays [, bool thumbnail]]])The exif_read_data() function reads the EXIF headers from a JPEG or TIFF image file. It returns an associative array where the indexes are the header names and the values are the values associated with those headers. If no data can be returned the result is FALSE.
filename is the name of the file to read. This cannot be a url.
sections a comma separated list of sections that need to be present in file to produce a result array.
| FILE | FileName, FileSize, FileDateTime, SectionsFound |
| COMPUTED | html, Width, Height, IsColor and some more if available. |
| ANY_TAG | Any information that has a Tag e.g. IFD0, EXIF, ... |
| IFD0 | All tagged data of IFD0. In normal imagefiles this contains image size and so forth. |
| THUMBNAIL | A file is supposed to contain a thumbnail if it has a second IFD. All tagged information about the embedded thumbnail is stored in this section. |
| COMMENT | Comment headers of JPEG images. |
| EXIF | The EXIF section is a sub section of IFD0. It contains more detailed information about an image. Most of these entries are digital camera related. |
arrays specifies whether or not each section becomes an array. The sections FILE, COMPUTED and THUMBNAIL allways become arrays as they may contain values whose names are conflict with other sections.
thumbnail whether or not to read the thumbnail itself and not only its tagged data.
Note : Exif headers tend to be present in JPEG/TIFF images generated by digital cameras, but unfortunately each digital camera maker has a different idea of how to actually tag their images, so you can't always rely on a specific Exif header being present.
Exemple 1. exif_read_data() example
The first call fails because the image has no header information.
|
Note : If the image contains any IFD0 data then COMPUTED contains the entry ByteOrderMotorola which is 0 for little-endian (intel) and 1 for big-endian (motorola) byte order. This was added in PHP 4.3.
When an Exif header contains a Copyright note this itself can contain two values. As the solution is inconsitent in the Exif 2.10 standard the COMPUTED section will return both entries Copyright.Photographer and Copyright.Editor while the IFD0 sections contains the byte array with the NULL character that splits both entries. Or just the first entry if the datatype was wrong (normal behaviour of Exif). The COMPUTED will contain also an entry Copyright Which is either the original copyright string or it is a comma separated list of photo and editor copyright.
Note : The tag UserComment has the same problem as the Copyright tag. It can store two values first the encoding used and second the value itself. If so the IFD section only contains the encoding or a byte array. The COMPUTED section will store both in the entries UserCommentEncoding and UserComment. The entry UserComment is available in both cases so it should be used in preference to the value in IFD0 section.
If the user comment uses Unicode or JIS encoding and the module mbstring is available this encoding will automatically changed according to the exif ini settings. This was added in PHP 4.3.
Note : Height and Width are computed the same way getimagesize() does so their values must not be part of any header returned. Also html is a height/width text string to be used inside normal HTML.
Note : Starting from PHP 4.3 the function can read all embedded IFD data including arrays (returned as such). Also the size of an embedded thumbnail is returned in THUMBNAIL subarray and the function exif_read_data() can return thumbnails in TIFF format. Last but not least there is no longer a maximum legth for returned values (not until memory limit is reached).
Note : This function is only available in PHP 4 compiled using --enable-exif. Its functionality and behaviour has changed in PHP 4.2. Earlier versions are very unstable.
Since PHP 4.3 user comment can automatically change encoding if PHP 4 was compiled using --enable-mbstring.
This function does not require the GD image library.
See also exif_thumbnail() and getimagesize().
exif_thumbnail
Description
string exif_thumbnail ( string filename [, int &width [, int &height]])exif_thumbnail() reads the embedded thumbnail of a TIFF or JPEG image. If the image contains no thumbnail FALSE will be returned.
Both parameters width and height are available since PHP 4.3 and return the size of the thumbnail. It is possible that exif_thumbnail() cannot create an image but determine its size. In this case the return value is FALSE but width and height are set.
Starting from version PHP 4.3 the function exif_thumbnail() can return thumbnails in TIFF format.
Note : This function is only available in PHP 4 compiled using --enable-exif. Its functionality and behaviour has changed in PHP 4.2
This function does not require the GD image library.
See also exif_read_data().
getimagesize
Description
array getimagesize ( string filename [, array imageinfo])getimagesize() va déterminer la taille des images de type GIF, JPG, PNG, SWF, PSD ou BMP et en retourner les dimensions, le type d'image, et une chaîne type "height/width", à placer dans une balise HTML ou IMG normale.
getimagesize() retourne un tableau de 4 éléments. L'index 0 contient la largeur. L'index 1 contient la longueur. L'index 2 contient le type de l'image : 1 = GIF, 2 = JPG, 3 = PNG, 5 = PSD, 6 = BMP. L'index 3 contient la chaîne à placer dans les balises HTML : "height=xxx width=xxx".
Avec les images JPEG, deux en-têtes supplémentaires sont retournés : channel et bits. channel vaudra 3 avec les images RGB, et 4 avec les images CMYK. bits est le nombre de bits de chaque couleur.
Si l'accès à filename est impossible, ou si ce n'est pas une image valide, getimagesize() retournera NULL et générera une alerte.
Le paramètre optionnel imageinfo 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 marqueur APP pour préciser les informations dans les balises HTML. Un marqueur commun est le marqueur APP13, décrit à http://www.iptc.org/. Vous pouvez utiliser la fonction iptcparse() pour analyser ce marqueur, et obtenir des informations intelligibles.
Note : getimagesize() ne requiert pas la bibliothèque GD.
Note : Le support URL a été ajouté en PHP 4.0.5.
image_type_to_mime_type
(unknown)
image_type_to_mime_type -- Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeDescription
string image_type_to_mime_type ( int imagetype)The image_type_to_mime_type() function will determine the Mime-Type for an IMAGETYPE constant.
Note : This function does not require the GD image library.
See also getimagesize(), exif_imagetype(), exif_read_data() and exif_thumbnail().
image2wbmp
Description
int image2wbmp ( int im [, string filename [, int threshold]])image2wbmp() crée une image WBMP à partir de l'image im. Si le paramètre filename est fourni, l'image sera créée dans ce fichier, et sinon, elle sera envoyée au navigateur. im est une image valide, créée avec la fonction imagecreate().
Le nom de fichier filename est optionnel, et si il est omis, l'image sera renvoyée directement au navigateur. En retournant un entête HTTP Content-Type : image/vnd.wap.wbmp avec la fonction header(), vous pouvez creer des images WBMP avec vos scripts PHP.
Note : Le support WBMP n'est disponible qu'avec GD-1.8 ou plus récent.
Voir aussi imagewbmp().
ImageAlphaBlending
Description
int imagealphablending ( resource im, boolean blendmode)imagealphablending() fournit deux modes de dessins des images en vraies couleurs (truecolors). En mode "blending", le canal alpha de chaque couleur est fournie à chaque fonction de dessin, tel que imagesetpixel() peut déterminer sa transparence. GD va alors automatiquement mixer la couleur à ce point, et stocker le résultat dans l'image. Le pixel résultant est alors opaque. En mode non-mixant, la couleur est copiée littéralement avec ses informations de canal alpha, et remplace le pixel de destination. Le mixage n'est pas disponible avec les images à palette. Si blendmode vaut TRUE, alors le mode de mixage sera activé, sinon il sera désactivé.
Note : imagealphablending() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageArc
Description
int imagearc ( resource im, int cx, int cy, int w, int h, int s, int e, int col)imagearc() dessine une ellipse partielle, centrée sur cx, cy (le coin en haut à gauche est l'origine (0,0)) dans l'image référencée par im. w et h spécifient la largeur et la hauteur de l'ellipse, tandis que le début et la fin de l'arc sont donnés en degrés, par les arguments s et e.
ImageChar
Description
int imagechar ( resource im, resource font, int x, int y, string c, int col)imagechar() dessine le premier caractère de la chaîne c dans l'image id avec le coin supérieur gauche placé à la position x,y (le coin en haut à gauche est l'origine (0,0)) avec la couleur col. Si la police est 1, 2, 3, 4 ou 5, une police intégrée sera utilisée (plus le chiffre est grand, plus grande est la police).
Voir aussi imageloadfont().
ImageCharUp
Description
int imagecharup ( resource im, resource font, int x, int y, string c, int col)imagecharup() dessine le premier caractère de la chaîne c dans l'image id avec le coin supérieur gauche placé à la position (x,y) (le coin en haut à gauche est l'origine (0,0)), avec la couleur col. Si la police est 1, 2, 3, 4 ou 5, une police intégrée sera utilisée (plus le chiffre est grand, plus grande est la police).
Voir aussi imageloadfont().
ImageColorAllocate
Description
int imagecolorallocate ( resource im, int red, int green, int blue)imagecolorallocate() retourne un identifiant de couleur, représentant la couleur composée avec les couleurs RGB (red, green, blue). L'argument im est le résultat de la fonction imagecreate(). imagecolorallocate() doit être appelée pour créer chaque couleur qui sera représentée par im.
ImageColorAt
Description
int imagecolorat ( resource im, int x, int y)imagecolorat() retourne l'index de la couleur du pixel situé aux coordonnées (x, y), dans l'image im.
Voir aussi imagecolorset() et imagecolorsforindex().
ImageColorClosest
(PHP 3, PHP 4 )
ImageColorClosest -- Retourne l'index de la couleur la plus proche d'une couleur donnée.Description
int imagecolorclosest ( resource im, int red, int green, int blue)imagecolorclosest() 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.
Voir aussi imagecolorexact().
ImageColorClosestAlpha
(PHP 4 >= 4.0.6)
ImageColorClosestAlpha -- Retourne la couleur la plus proche, en tenant compte du canal alphaDescription
int imagecolorclosestalpha ( resource im, int red, int green, int blue, int alpha)imagecolorclosestalpha() retourne l'index de la couleur, dans la palette de l'image im, la plus proche de la couleur spécifiée par les autres paramètres, au format RGB et de canal alpha alpha.
Voir aussi imagecolorexactalpha().
Note : imagecolorclosestalpha() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
imagecolorclosesthwb
(PHP 4 >= 4.0.1)
imagecolorclosesthwb -- Get the index of the color which has the hue, white and blackness nearest to the given colorDescription
int imagecolorclosesthwb ( resource image, int red, int green, int blue)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ImageColorDeAllocate
Description
int imagecolordeallocate ( resource im, int index)imagecolordeallocate() désalloue une couleur précédemment allouée avec la fonction imagecolorallocate().
ImageColorExact
Description
int imagecolorexact ( resource im, int red, int green, int blue)imagecolorexact() retourne l'index de la couleur spécifiée dans la palette de l'image im.
Si la couleur n'existe pas dans cette palette, imagecolorexact() retourne -1.
Voir aussi imagecolorclosest().
ImageColorExactAlpha
Description
int imagecolorexactalpha ( resource im, int red, int green, int blue, int alpha)imagecolorexactalpha() retourne l'index de la couleur fournie au format RGB et son canal alpha alpha, dans l'image im.
Si la couleur n'existe pas dans la palette de l'image, imagecolorexactalpha() retourne -1.
Voir aussi imagecolorclosestalpha().
Note : imagecolorexactalpha() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageColorResolve
(PHP 3>= 3.0.2, PHP 4 )
ImageColorResolve -- Retourne l'index de la couleur donnée, ou la plus proche possible.Description
int imagecolorresolve ( resource im, int red, int green, int blue)imagecolorresolve() retourne un index de couleur à tous les coups. Soit il arrive à trouver la couleur demandée dans la palette, soit il recherche la couleur la plus proche.
Voir aussi imagecolorclosest().
ImageColorResolveAlpha
(PHP 4 >= 4.0.6)
ImageColorResolveAlpha -- Retourne un index de couleur ou son alternative la plus proche, y compris le canal alphaDescription
int imagecolorresolvealpha ( resource im, int red, int green, int blue, int alpha)imagecolorresolvealpha() retourne toujours un index de couleur, disponible dans la palette de l'image im : soit c'est la couleur exacte, soit c'est la meilleure approximation.
Voir aussi imagecolorclosestalpha().
Note : imagecolorresolvealpha() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageColorSet
Description
boolean imagecolorset ( resource im, int index, int red, int green, int blue)imagecolorset() permet d'attribuer à un index d'une palette une couleur spécifique. C'est une fonction très pratique pour effectuer du remplissage de couleur sans le faire réellement.
Voir aussi imagecolorat().
ImageColorsForIndex
Description
array imagecolorsforindex ( resource im, int index)imagecolorsforindex() retourne un tableau associatif avec les couleurs rouge (red) , vert (green), bleu (blue) qui contiennent les valeurs de la couleur correspondante.
Voir aussi imagecolorat() et imagecolorexact().
ImageColorsTotal
Description
int imagecolorstotal ( resource im)imagecolorstotal() retourne le nombre de couleurs de la palette.
Voir aussi imagecolorat() et imagecolorsforindex().
ImageColorTransparent
Description
int imagecolortransparent ( resource im [, int col])imagecolortransparent() permet de choisir la couleur transparente d'une image, et de lui donner la valeur de col. im est un identifiant d'image, retourné par imagecreate() et col est un identifiant de couleur retourné par imagecolorallocate().
L'identifiant de la nouvelle (ou courante) couleur transparente est retourné.
ImageCopy
Description
int imagecopy ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h)Copie une partie de l'image src_im sur l'image de destination dst_im, en commençant aux coordonnées src_x, src_y et sur la largeur de src_w et la hauteur de src_h. La portion ainsi définie sera copiée et placée aux coordonnées dst_x et dst_y.
ImageCopyMerge
Description
int imagecopymerge ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h, int pct)imagecopymerge() copie une partie de l'image src_im dans l'image de destination dst_im en commençant aux coordonnées (src_x, src_y), avec la largeur src_w et la hauteur src_h. La zone de l'image ainsi définie sera copiée aux coordonnées (dst_x, dst_y), dans l'image de destination. 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 exactement comme imagecopy().
Note : imagecopymerge() a été ajoutée en PHP 4.0.6.
ImageCopyMergeGray
Description
int imagecopymergegray ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h, int pct)imagecopymergegray() copie une partie de l'image src_im dans l'image de destination dst_im commençant aux coordonnées (src_x, src_y), avec la largeur src_w et la hauteur src_h. La zone de l'image ainsi définie sera copiée aux coordonnées (dst_x, dst_y), dans l'image de destination. 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 exactement comme imagecopy().
imagecopymergegray() est identique à la fonction imagecopymerge(), hormis le fait que lors de la fusion, le "hue" de l'image sera conservé grâce à la conversion de la zone dans l'image de destination en gris, avant l'opération de copie.
Note : imagecopymergegray() a été ajoutée en PHP 4.0.6.
ImageCopyResampled
Description
int imagecopyresampled ( resource dst_im, resource src_im, int dstX, int dstY, int srcX, int srcY, int dstW, int dstH, int srcW, int srcH)imagecopyresampled() copie une zone rectangulaire de l'image src_im vers l'image src_im. Durant la copie, la zone est rééchantillonnée de manière à conserver la clarté de l'image durant une réduction. Dst_im est l'image de destination, src_im est l'image source. Si les hauteurs et largeur 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, mais si les régions se chevauchent, les résultats sont imprévisibles.
Voir aussi imagecopyresized().
Note : imagecopyresampled() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageCopyResized
Description
int imagecopyresized ( resource dst_im, resource src_im, int dstX, int dstY, int srcX, int srcY, int dstW, int dstH, int srcW, int srcH)imagecopyresized() copie une partie rectangulaire d'une image dans une autre image de destination. dst_im est l'image de destination, src_im est l'image source. Si les dimensions de la source et de la destination ne sont pas égales, un étirement adéquat est effectué pour faire correspondre les deux. Les coordonnées fournies sont définies par rapport au coin supérieur gauche. Cette fonction peut être utilisée pour recopier des régions à l'intérieur d'une même image, si dst_im et src_im sont identiques : mais si les régions se chevauchent, le résultat risque d'être incohérent.
Voir aussi imagecopyresampled().
ImageCreate
Description
resource imagecreate ( int x_size, int y_size)imagecreate() retourne un identifiant d'image représentant une image vide, de largeur x_size et longueur y_size.
imagecreatefromgd2
Description
resource imagecreatefromgd2 ( string filename)
| Avertissement |
This function is currently not documented, only the argument list is available. |
imagecreatefromgd2part
Description
resource imagecreatefromgd2part ( string filename, int srcX, int srcY, int width, int height)
| Avertissement |
This function is currently not documented, only the argument list is available. |
imagecreatefromgd
Description
resource imagecreatefromgd ( string filename)
| Avertissement |
This function is currently not documented, only the argument list is available. |
imagecreatefromgif
Description
resource imagecreatefromgif ( string filename)imagecreatefromgif() retourne un identifiant d'image qui représente l'image obtenue à partir du fichier dont le nom est donné.
imagecreatefromgif() retourne une chaîne vide en cas d'échec. Il va aussi retourner une erreur qui va afficher un lien brisé dans un navigateur. Pour simplifier le débuggage, utilisez le code suivant, qui retourne une erreur GIF :
Exemple 1. Exemple de gestion des erreurs durant la création d'image (gracieusement offert par vic@zymsys.com )
|
Note : Etant donné que toutes les fonctions de gestion des GIF ont été supprimées de la bibliothèque GD version 1.6, cette fonction n'est pas disponible si vous utilisez cette version de la librairie.
ImageCreateFromJPEG
(PHP 3>= 3.0.16, PHP 4 )
ImageCreateFromJPEG -- Crée une nouvelle image JPEG à partir d'un fichier ou d'une URLDescription
resource imagecreatefromjpeg ( string filename)imagecreatefromjpeg() retourne un identifiant d'image représentant une image obtenue à partir du fichier filename.
imagecreatefromjpeg() retourne une chaîne vide en cas d'échec. Elle affiche aussi un message d'erreur, qui s'affiche comme un lien brisé dans un navigateur web. Pour faciliter le débuggage, voici une erreur JPEG:
Exemple 1. Exemple de gestion d'erreur lors de la création d'image (gracieusement offert par vic@zymsys.com )
|
ImageCreateFromPNG
(PHP 3>= 3.0.13, PHP 4 )
ImageCreateFromPNG -- Crée une nouvelle image PNG à partir d'un fichier ou d'une URLDescription
resource imagecreatefrompng ( string filename)imagecreatefrompng() retourne un identifiant d'image représentant une image obtenue à partir du fichier filename.
imagecreatefromjpeg() retourne une chaîne vide en cas d'échec. Elle affiche aussi un message d'erreur, qui s'affiche comme un lien brisé dans un navigateur web. Pour faciliter le débuggage, voici une erreur PNG:
Exemple 1. Exemple de gestion d'erreur lors de la création d'image (gracieusement offert par vic@zymsys.com )
|
ImageCreateFromString
Description
resource imagecreatefromstring ( string string)imagecreatefromstring() retourne un identifiant d'image représentant la chaîne string.
ImageCreateFromWBMP
Description
resource imagecreatefromwbmp ( string filename)imagecreatefromwbmp() retourne une ressource d'image PHP, représentant l'image filename.
imagecreatefromwbmp() retourne une chaîne vide en cas d'erreur. Il retourne aussi un message d'erreur qui s'affiche comme un lien mort dans un navigateur. Pour aider au débuggage, l'exemple suivant va produire une erreur WBMP:
Exemple 1. Exemple de gestion des erreurs durant la création d'une image WBMP (gracieusement proposé par vic@zymsys.com)
|
Note : Le support WBMP n'est disponible qu'avec GD-1.8 ou plus récent.
ImageCreateFromXBM
Description
int imagecreatefromxbm ( string filename)imagecreatefromxbm() retourne un identifiant d'image représentant l'image obtenue à partir du fichier filename.
ImageCreateFromXPM
Description
int imagecreatefromxpm ( string filename)imagecreatefromxpm() retourne un identifiant d'image représentant l'image obtenue à partir du fichier filename.
ImageCreateTrueColor
Description
resource imagecreatetruecolor ( int x_size, int y_size)imagecreatetruecolor() retourne une ressource représentant une image noire de largeur x_size, et de hauteur y_size.
Note : imagecreatetruecolor() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageDashedLine
Description
int imagedashedline ( resource im, int x1, int y1, int x2, int y2, int col)imagedashedline() dessine une ligne pointillée entre les points (x1,y1) et (x2,y2) (le coin supérieur droit est l'origine (0,0)) dans l'image im, avec la couleur col.
Voir aussi imageline().
ImageDestroy
Description
int imagedestroy ( resource im)imagedestroy() libère toute la mémoire associée à l'image im. im est un identifiant d'image valide retourné par imagecreate().
ImageEllipse
Description
int imageellipse ( resource im, int cx, int cy, int w, int h, int col)imageellipse() dessine une ellipse centrée sur le point (cx, cy). Le coin supérieur gauche est aux coordonnées (0,0). L'image de dessin est im. w et h spécifient respectivement la largeur et la hauteur de l'ellipse. La couleur de dessin de l'ellipse est color.
Note : imageellipse() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageFill
Description
int imagefill ( resource im, int x, int y, int col)imagefill() effectue un remplissage avec la couleur col, dans l'image im, à partir du point de coordonnées (x, y) (le coin supérieur gauche est l'origine (0,0)).
imagefilledarc
Description
int imagefilledarc ( int im, int cx, int cy, int w, int h, int s, int e, int col, int style)imagefilledarc() dessine une ellipse partielle, centrée sur le point (cx, cy). Le coin supérieur gauche est (0, 0), dans l'image im. w et h spécifient respectivement la largeur et la hauteur de l'ellipse, tandis que les points de début et de fin sont représentés par s et e, en degrés. L'argument style est un champ de bits, combiné avec l'opérateur OR :
IMG_ARC_PIE
IMG_ARC_CHORD
IMG_ARC_NOFILL
IMG_ARC_EDGED
Note : imagefilledarc() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageFilledEllipse
Description
int imagefilledellipse ( resource im, int cx, int cy, int w, int h, int col)imagefilledellipse() dessine une ellipse centrée sur le point (cx, cy). Le coin supérieur gauche est aux coordonnées (0,0). L'image de dessin est im. w et h spécifient respectivement la largeur et la hauteur de l'ellipse. La couleur de remplissage de l'ellipse est color.
Note : imagefilledellipse() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageFilledPolygon
Description
int imagefilledpolygon ( resource im, array points, int num_points, int col)imagefilledpolygon() dessine un polygone rempli dans l'image im. points est un tableau PHP qui contient les sommets des polygones sous la forme :. points[0] = x0, points[1] = y0, points[2] = x1, points[3] = y1, etc. num_points est le nombre total de sommets.
ImageFilledRectangle
Description
int imagefilledrectangle ( resource im, int x1, int y1, int x2, int y2, int col)imagefilledrectangle() dessine un rectangle de couleur col dans l'image im, en commençant par le sommet supérieur gauche (x1, y1) et finissant au sommet inférieur droit (x2, y2). Le coin supérieur gauche est l'origine (0, 0).
ImageFillToBorder
Description
int imagefilltoborder ( resource im, int x, int y, int border, int col)imagefilltoborder() remplit avec la couleur col toute la région à l'intérieur de la région limitée par la couleur border. Le point de départ est (x,y) (le coin supérieur gauche est l'origine (0,0)).
ImageFontHeight
Description
int imagefontheight ( resource font)imagefontheight() retourne la hauteur de la police font en pixels.
Voir aussi imagefontwidth() et imageloadfont().
ImageFontWidth
Description
int imagefontwidth ( resource font)imagefontwidth() retourne la largeur de la police font en pixels.
Voir aussi imagefontheight() et imageloadfont().
imageftbbox
Description
array imageftbbox ( int size, int angle, string font_file, string text [, array extrainfo])
| Avertissement |
This function is currently not documented, only the argument list is available. |
imagefttext
Description
array imagefttext ( resource image, int size, int angle, int x, int y, int col, string font_file, string text [, array extrainfo])
| Avertissement |
This function is currently not documented, only the argument list is available. |
ImageGammaCorrect
Description
int imagegammacorrect ( resource im, float inputgamma, float outputgamma)imagegammacorrect() applique une correction gamma à l'image GD im. Le facteur d'entrée est inputgamma, et le facteur de sortie est outputgamma.
imagegd2
Description
int imagegd2 ( resource image [, string filename])
| Avertissement |
This function is currently not documented, only the argument list is available. |
imagegd
Description
int imagegd ( resource image [, string filename])
| Avertissement |
This function is currently not documented, only the argument list is available. |
ImageGif
Description
int imagegif ( resource im, string filename)imagegif() crée un fichier image GIF avec le nom filename d'après l'image im. L'argument im est un identifiant valide retourné par la fonction imagecreate().
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.
Le nom du fichier est optionnel, et dans ce cas, l'image sera transmise directement à la sortie standard. En envoyant une en-tête de type image/gifcontent-type , (grâce à la fonction header()), vous pouvez créer des images avec des scripts PHP.
Note : Etant donné que toutes les fonctions GIF ont été supprimées de la bibliothèque GD version 1.6, cette fonction ne sera pas accessible si vous avez cette version de la librairie.
Le code suivant vous 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 if (function_exists("imagegif")) { header("Content-type: image/gif"); imagegif($im); } elseif (function_exists("imagejpeg")) { header("Content-type: image/jpeg"); imagejpeg($im, "", 0.5); } elseif (function_exists("imagepng")) { header("Content-type: image/png"); imagepng($im); } elseif (function_exists("imagewbmp")) { header("Content-type: image/vnd.wap.wbmp"); imagewbmp($im); } else { die("Pas de support graphique avec PHP sur ce serveur"); } ?>
Note : En PHP 4, à partir de la version 4.0.2, vous pouvez utiliser la fonction imagetypes() à la place de function_exists() pour vérifier que certains formats d'images sont supportés :
<?php if (function_exists("imagegif")) { header("Content-type: image/gif"); imagegif($im); } elseif (function_exists("imagejpeg")) { header("Content-type: image/jpeg"); imagejpeg($im, "", 0.5); } elseif (function_exists("imagepng")) { header("Content-type: image/png"); imagepng($im); } elseif (function_exists("imagewbmp")) { header("Content-type: image/vnd.wap.wbmp"); imagewbmp($im); } else { die("Pas de support graphique avec PHP sur ce serveur"); } ?>
Voir aussi imagejpeg(), imagewbmp(), imagepng(), imageinterlace(), imagegif() et imagetypes().
ImageInterlace
Description
int imageinterlace ( resource im [, int interlace])imageinterlace() active ou désactive le bit d'entrelacement.
Si l'entrelacement est à 1, l'image im sera interlacée, et sinon, elle ne le sera pas. Si le format d'affichage de l'image est JPEG, l'image créée sera un JPEG progressif.
imageinterlace() retourne l'état courant d'entrelacement de l'image.
ImageJPEG
Description
int imagejpeg ( resource im [, string filename [, int quality]])imagejpeg() envoie l'image GD (im) au format JPEG sur la sortie standard (typiquement, le navigateur web), ou si filename est fourni, l'envoie dans un fichier. im a été créé par imagecreate().
Le nom du fichier est optionnel, et dans ce cas, l'image sera transmise directement à la sortie standard. En envoyant une image de type image/jpeg content-type (grâce à la fonction header()), vous pouvez créer des images JPEG avec des scripts PHP.
Note : Le support JPEG n'est disponible que si PHP est compilé avec GD-1.8 ou plus récent.
quality est optionnel, et prend des valeurs entières de 0 (pire qualité, petit fichier) et 100 (meilleure qualité, gros fichier). Par défaut, la valeur est à 100.
Si vous voulez générer des images JPEG progressive, vous devez choisir l'entrelacement à l'aide de la fonction imageinterlace().
Voir aussi imagepng(), imagewbmp(), imagegif(), imageinterlace(), imagegif() et imagetypes().
ImageLine
Description
int imageline ( resource im, int x1, int y1, int x2, int y2, int col)imageline() dessine une ligne depuis le point (x1,y1) jusqu'au point (x2,y2) (le coin supérieur gauche est l'origine (0,0)) dans l'image im et avec la couleur col.
Voir aussi imagecreate() et imagecolorallocate().
ImageLoadFont
Description
resource imageloadfont ( string file)imageloadfont() charge une nouvelle police utilisateur et retourne un identifiant sur cette police. Cet identifiant sera toujours supérieur à 5, pour éviter les conflits avec les polices standard PHP.
Le format des polices dépend actuellement du système d'exploitation. Ce qui signifie qu'il vous faut générer des fichiers de polices pour la machine qui fait tourner PHP.
Tableau 1. 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_caractères*largeur*hauteur) octets. |
Voir aussi imagefontwidth() et imagefontheight().
ImagePaletteCopy
Description
int imagepalettecopy ( resource destination, resource source)imagepalettecopy() copie la palette de l'image source dans l'image destination.
ImagePNG
Description
int imagepng ( resource im [, string filename])imagepng() envoie l'image GD (im) au format PNG sur la sortie standard (typiquement, le navigateur web), ou si filename est fourni, l'envoie dans un fichier.
Le nom du fichier est optionnel, et dans ce cas, l'image sera transmise directement à la sortie standard. En envoyant une image de type image/png content-type (grâce à la fonction header()), vous pouvez créer des images PNG avec des scripts PHP.
Voir aussi imagejpeg(), imagewbmp(), imagegif(), imageinterlace(), imagegif() et imagetypes().
ImagePolygon
Description
int imagepolygon ( resource im, array points, int num_points, int col)imagepolygon() dessine un polygone dans l'image im. points est un tableau PHP qui contient les sommets du polygone sous la forme : points[0] = x0, points[1] = y0, points[2] = x1, points[3] = y1, etc. num_points est le nombre de sommets.
Voir aussi imagecreate().
ImagePSBBox
(PHP 3>= 3.0.9, PHP 4 )
ImagePSBBox -- Retourne le rectangle entourant un texte et dessiné avec une police PostScript Type1.Description
array imagepsbbox ( string text, resource font, int size, int space, int width, float angle)size est exprimé en pixels.
space permet de changer la valeur par défaut du charactère espace. Cette valeur est ajoutée lors des dessins, et donc, peut être négative.
tightness permet de contrôler la quantité d'espace entre les caractères. Cette quantité est ajoutée lors des dessins, et peut donc être négative.
angle est en degrés.
Les paramètres space et tightness sont exprimés en unité d'espacement de caractères, avec 1 unité vaut 1/1000 d'un em carré (NDT : kesako?).
Les paramètres space, tightness et angle sont optionnels.
Le rectangle entourant est calculé en utilisant les informations disponibles sur les tailles de caractères, et, malheureusement, il a tendance à être légèrement différent du résultat réel final. Si l'angle est de 0 degré, vous pouvez-vous attendre à avoir besoin d'un rectangle d'au moins un pixel plus grand dans toutes les directions.
imagepsbbox() retourne un tableau contenant les éléments suivants :
| 0 | Abscisse inférieure gauche |
| 1 | Ordonnée inférieure gauche |
| 2 | Abscisse supérieure droite |
| 3 | Ordonnée supérieure droite |
Voir aussi imagepstext().
imagepscopyfont
(PHP 3>= 3.0.9, PHP 4 )
imagepscopyfont -- Fait une copie d'une police chargée pour modification ultérieure.Description
int imagepscopyfont ( int fontindex)Utilisez cette fonction si vous devez faire des modifications dans une polie, comme par exemple l'extension ou la condensation, ou encore, modifier son vecteur d'encodage, tout en conservant l'original. Notez que la police que vous copiez doit être obtenue par imagepsloadfont(), et non pas une police qui a elle-même été copiée. Vous pouvez aussi faire des modifications avant de la copier.
Si vous utilisez cette fonction, vous DEVEZ libérer les polices obtenues vous même, et dans l'ordre inverse. Sinon, votre script sera suspendu.
Si tout a bien été fait, un index valide de police sera retourné, et pourra être utilisé ultérieurement. Sinon, la fonction retournera FALSE, et affichera un message décrivant l'erreur.
Voir aussi imageploadpsfont().
ImagePSEncodeFont
(PHP 3>= 3.0.9, PHP 4 )
ImagePSEncodeFont -- Change le codage vectoriel d'un caractère dans une police.Description
int imagepsencodefont ( resource font, string encodingfile)imagepsencodefont() charge le codage vectoriel d'un caractère depuis un fichier et change le codage vectoriel de la police correspondante. Etant donné que les polices PostScript ne disposent pas des caractères au-delà de 127, vous aurez sÛrement besoin de les changer si vous utilisez une autre langue que l'anglais. Le format exact est décrit dans la documentation T1libs. T1lib est disponible en deux formes : IsoLatin1.enc et IsoLatin2.enc.
Si vous commencez à utiliser cette fonction régulièrement, une meilleure solution est de définir un encodage, et de l'utiliser avec set ps.default_encoding dans le fichier de configuration pour utiliser par défaut l'encodage correct.
ImagePsExtendFont
Description
boolean imagepsextendfont ( resource font, float extend)imagepsextendfont() étend ou condense la police de caractères font. Si la valeur de extend est inférieure à 1, ce sera une condensation.
ImagePSFreeFont
(PHP 3>= 3.0.9, PHP 4 )
ImagePSFreeFont -- Libère la mémoire occupée par une police PostScript Type 1.ImagePSLoadFont
Description
resource imagepsloadfont ( string filename)Au cas où tout a bien marché, un index de police va être retourné, et pourra être utilisé pour des opérations ultérieures. Sinon, la fonction retourne FALSE et affiche un message décrivant ce qui est erroné.
<?php
header("Content-type: image/jpeg");
$im = imagecreate(350, 45);
$noir = imagecolorallocate($im, 0, 0, 0);
$Blanc = imagecolorallocate($im, 255, 255, 255);
$font = imagepsloadfont("bchbi.pfb");
imagepstext($im, "Test ... Ca marche!", $font, 32, $white, $black, 32, 32);
imagepsfreefont($font);
imagejpeg($im, "");
imagedestroy ($im);
?< |
Voir aussi imagepsfreefont().
ImagePsSlantFont
Description
boolean imagepsslantfont ( resource font, float slant)imagepsslantfont() met en italique la police de caractères font avec le coefficient slant.
ImagePSText
(PHP 3>= 3.0.9, PHP 4 )
ImagePSText -- Dessine un texte sur une image avec une police PostScript Type1.Description
array imagepstext ( resource im, string text, resource font, int size, int foreground, int background, int x, int y [, int space [, int tightness [, float angle [, int antialias_steps]]]])size est exprimé en pixels.
foreground est la couleur dans laquelle le texte va être dessiné. background est la couleur d'anti aliasing. Aucun pixel avec la couleur background n'est dessiné, ce qui fait que l'arrière-plan n'a pas besoin d'être dans une couleur fixe.
Les coordonnées données (x, y) définissent l'origine du premier caractère (grossièrement, le coin inférieur gauche du caractère). Ceci est différent de la fonction imagestring(), où (x, y) définissait le coin supérieur gauche du premier caractère. Reportez-vous à la documentation PostScript pour avoir des détails à propos des polices et de leurs tailles.
space permet de changer la taille par défaut du caractère d'espacement. Cette valeur peut être négative.
tightness permet de contrôler la quantité d'espace entre deux caractères. Cette valeur peut être négative.
angle est en degrés.
antialias_steps permet de contrôler le nombre de couleurs du texte anti-aliasé. Les valeurs autorisées sont 4 et 16. 16 est recommandé pour les polices de moins de 20 pixels, car l'effet est alors visible. Avec les tailles plus grandes, utilisez de préférence 4, qui est moins gourmande en ressources.
Les paramètres space et tightness sont exprimés en unité d'espaces caractère, ce qui vaut 1/1000ème d'un em-carré ( ? ? ?).
Les paramètres space, tightness, angle et antialias sont optionnels.
imagepstext() retourne un tableau contenant les éléments suivants :
| 0 | Abscisse inférieure gauche |
| 1 | Ordonnée inférieure gauche |
| 2 | Abscisse supérieure droite |
| 3 | Ordonnée supérieure droite |
Voir aussi imagepsbbox().
ImageRectangle
Description
int imagerectangle ( resource im, int x1, int y1, int x2, int y2, int col)imagerectangle() dessine un rectangle dans la couleur col, dans l'image im, et en commençant au point supérieur gauche (x1, y1), et en finissant au point inférieur droit (x2,y2). Le coin supérieur gauche est l'origine (0,0).
imagesetbrush
Description
int imagesetbrush ( resource im, resource brush)imagesetbrush() remplace la brosse courante pour le dessin des lignes par brush. Cette brosse sera alors utilisée avec les fonctions imageline() et imagepolygon().
Note : Vous n'avez rien à faire lorsque vous en avez terminé avec une brosse, mais si vous détruisez l'image de brosse, vous ne DEVEZ plus utiliser les options IMG_COLOR_BRUSHED et IMG_COLOR_STYLEDBRUSHED des fonctions imageline() et imagepolygon(), avant d'avoir créé une nouvelle brosse.
Note : imagesetbrush() a été ajoutée en PHP 4.0.6.
ImageSetPixel
Description
int imagesetpixel ( resource im, int x, int y, int col)imagesetpixel() dessine un pixel au point (x,y) (le coin supérieur gauche est l'origine (0,0)) dans l'image im, et avec la couleur col.
Voir aussi imagecreate() et imagecolorallocate().
imagesetstyle
Description
int imagesetstyle ( resource image, array style)imagesetstyle() sets the style to be used by all line drawing functions (such as imageline() and imagepolygon()) when drawing with the special color IMG_COLOR_STYLED or lines of images with color IMG_COLOR_STYLEDBRUSHED.
The style parameter is an array of pixels. Following example script draws a dashed line from upper left to lower right corner of the canvas:
Exemple 1. imagesetstyle
|
See also imagesetbrush(), imageline().
Note : This function was added in PHP 4.0.6
ImageSetThickness
Description
void imagesetthickness ( resource im, int thickness)imagesetthickness() modifie l'épaisseur du trait des lignes de l'image im. Cette épaisseur intervient dans les dessins de polygones, ellipses, cercles, rectangles, etc... thickness est en pixels.
Note : imagesetthickness() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageSetTile
Description
int imagesettile ( resource im, resource tile)imagesettile() remplace l'image de carrelage 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.
Note : Vous n'avez rien à faire lorsque vous en avez terminé avec une brosse, mais si vous détruisez l'image de brosse, vous ne DEVEZ plus utiliser l'option IMG_COLOR_TILED des fonctions imagefill() et imagefilledpolygon(), avant d'avoir créé une nouvelle brosse.
Note : imagesettile() a été ajoutée en PHP 4.0.6.
ImageString
Description
int imagestring ( resource im, int font, int x, int y, string s, int col)imagestring() dessine une la chaîne sur une ligne horizontale, dans l'image im, aux coordonnées (x,y) (le coin supérieur gauche est l'origine (0,0)) dans la couleur col. Si l'argument de police vaut 1, 2, 3, 4 ou 5, une des polices par défaut sera utilisée).
Voir aussi imageloadfont().
ImageStringUp
Description
int imagestringup ( resource im, int font, int x, int y, string s, int col)imagestringup() dessine une chaîne sur une ligne verticale dans l'image im aux coordonnées (x, y) (l'origine est le coin supérieur gauche (0,0)) dans la couleur col. Si la police utilisée est 1, 2, 3, 4 ou 5, une police par défaut sera utilisée.
Voir aussi imageloadfont().
ImageSX
Description
int imagesx ( resource im)imagesx() retourne la largeur de l'image référencée par im.
Voir aussi imagecreate() et imagesy().
ImageSY
Description
int imagesy ( resource im)imagesy() retourne la hauteur de l'image référencée par im.
Voir aussi imagecreate() et imagesx().
ImageTrueColorToPalette
(PHP 4 >= 4.0.6)
ImageTrueColorToPalette -- Convertit une image en vraies couleurs en image à paletteDescription
void imagetruecolortopalette ( resource im, boolean dither, int ncolors)imagetruecolortopalette() convertit l'image en vraies couleurs im en image à palette. Le code de cette fonction est directement tiré de la librairie du "Independent JPEG Group", qui est tout simplement génial. Le code a été modifié pour préserver l'essentiel du canal alph 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 a toujours le meilleur rendu.
Si dither vaut TRUE, cela indique que l'image doit être ditherée : l'image sera un peu plus granuleuse, mais l'approximation des couleurs sera meilleure.
ncolors est le nombre maximal de couleurs dans la palette finale.
Note : imagetruecolortopalette() a été ajoutée en PHP 4.0.6 et nécessite GD 2.0.1.
ImageTTFBBox
(PHP 3>= 3.0.1, PHP 4 )
ImageTTFBBox -- Retourne le rectangle entourant un texte et dessiné avec une police TrueType.Description
array imagettfbbox ( int size, int angle, string fontfile, string text)imagettfbbox() calcule et retourne le rectangle entourant le texte text, écrit avec une police truetype.
- text
La chaîne à mesurer.
- size
La taille de la police en pixel.
- fontfile
Le nom de la police TrueType (peut aussi être une URL.)
- angle
Angle en degré dans lequel le texte text va être mesuré.
| 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 |
imagettfbbox() requiert les bibliothèques GD et Freetype.
Voir aussi imagettftext().
ImageTTFText
Description
array imagettftext ( resource im, int size, int angle, int x, int y, int col, string fontfile, string text)imagettftext() dessine la chaîne text dans l'image im, en commençant aux coordonnées (x,y) (le coin supérieur gauche est l'origine (0,0)), avec un angle de angle, et dans la couleur col, en utilisant la police TrueType identifiée par fontfile.
Les coordonnées (x,y) serviront de référence pour le premier caractère (en gros, le coin inférieur gauche du caractère). C'est différent de imagestring(), qui utilise le coin supérieur droit.
angle est donné en degrés, avec degré 0 pour un texte horizontal, et en comptant les angles dans le sens inverse des aiguilles d'une montre (sens direct).
fontfile est le chemin jusqu'à la police TrueType à utiliser.
text est le texte à dessiner, incluant aussi des séquences de caractères UTF-8 (de la forme: { ) pour générer des caractères au-delà de 255.
col est l'index de la couleur dans la palette. Utiliser des index négatifs, revient à supprimer l'anti-aliasing.
imagettftext() retourne un tableau de 8 éléments représentant les 4 points marquants les limites du texte. L'ordre des points est :supérieur gauche, supérieur droit, inférieur droit, inférieur gauche. Les points sont nommés relativement au texte à l'horizontaleimagecolorexact().
Cet exemple va générer une image GIF noire de 400x30 pixels, avec les mots "Test en cours...Oméga: Ω" en police blanche, type Arial.
Exemple 1. Exemple avec imagettftext()
|
imagettftext() requiert les bibliothèques GD ainsi que FreeType.
Voir aussi imagettfbbox().
ImageTypes
(PHP 3 CVS only, PHP 4 >= 4.0.2)
ImageTypes -- Retourne les types d'images supportés par la version courante de PHPDescription
int imagetypes ( void)imagetypes() retourne un champs de bits correspondant aux formats d'images supportés par la version de GD utilisée. Les valeurs suivantes sont valables : IMG_GIF | IMG_JPG | IMG_PNG | IMG_WBMP. Pour vous assurer du support PNG, faites ceci :
ImageWBMP
Description
int imagewbmp ( resource im [, string filename [, int foreground]])imagewbmp() crée l'image WBMP dans le fichier filename, à partir de l'image im. Le paramètre im a été créé avec la fonction imagecreate().
filename est optionnel, et s'il est omis, l'image sera envoyée directement au client. En plaçant l'en-tête image/vnd.wap.wbmp, dans le champs "content-type", vous pourrez afficher une image WBMP.
Note : Le support WBMP n'est disponible que si PHP a été compilé avec GD-1.8 ou plus récent.
En passant le paramètre optionnel foreground, vous pouvez choisir la couleur de fond. Utilisez l'identifiant retourné par imagecolorallocate() comme valeur de ce paramètre. La couleur de fond par défaut est noir.
Voir aussi image2wbmp(), imagepng(), imagegif(), imagejpeg() et imagetypes().
iptcembed
Description
array iptcembed ( string iptcdata, string jpeg_file_name [, int spool])
| Avertissement |
This function is currently not documented, only the argument list is available. |
iptcparse
(PHP 3>= 3.0.6, PHP 4 )
iptcparse -- Parse a binary IPTC http://www.iptc.org/ block into single tags.Description
array iptcparse ( string iptcblock)This function parses a binary IPTC block into its single tags. It returns an array using the tagmarker as an index and the value as the value. It returns FALSE on error or if no IPTC data was found. See getimagesize() for a sample.
JPEG2WBMP
Description
int jpeg2wbmp ( string jpegname, string wbmpname, int d_height, int d_width)jpeg2wbmp() convertit l'image JPEG du fichier jpegname au format WBMP, et la sauve dans le fichier wbmpname. Les paramètres d_height et d_width vous permettent de spécifier la hauteur et la largeur (respectivement) de l'image de destination.
Note : Le support WBMP n'est disponible que si PHP a été compilé avec GD-1.8 ou plus récent.
Voir aussi png2wbmp().
PNG2WBMP
Description
int png2wbmp ( string pngname, string wbmpname, int d_height, int d_width)png2wbmp() convertit l'image PNG du fichier pngname au format WBMP, et la sauve dans le fichier wbmpname. Les paramètres d_height et d_width vous permettent de spécifier la hauteur et la largeur (respectivement) de l'image de destination.
Note : Le support WBMP n'est disponible que si PHP a été compilé avec GD-1.8 ou plus récent.
Voir aussi jpeg2wbmp().
read_exif_data
Description
array read_exif_data ( string filename)read_exif_data() lit les en-têtes EXIF de l'image JPEG nommée filename. Elle retourne un tableau associatif où les index sont les noms d'en-têtes EXIF, et les valeurs sont leur valeur associée. Les en-têtes EXIF sont souvent disponibles dans les images générées par les appareils photos numériques, mais chaque constructeur marque ses images d'une manière qui lui est propre : il est impossible de savoir quelles en-têtes seront présents.
Exemple 1. Exemple avec read_exif_data()
Cet exemple va afficher :
|
Note : read_exif_data() n'est disponible que sous PHP 4 , compilé avec --enable-exif.
read_exif_data() ne requiert pas la librairie GD.
XLIII. IMAP
Pour avoir accès à ces fonctions, vous devez compiler PHP avec l'option --with-imap. Il faut avoir installé la librairie C-client. Chargez sa dernière version sur le serveur ftp://ftp.cac.washington.edu/imap/ et compilez la. Puis, copiez le fichier c-client/c-client.a dans /usr/local/lib ou n'importe quel autre dossier qui soit dans le chemin de link. Enfin, copiez les fichiers c-client/rfc822.h, mail.h et linkage.h dans /usr/local/include ou n'importe quel autre dossier qui soit dans le chemin d'inclusion.
Ces fonctions ne sont pas limitées au protocole IMAP, malgré leur nom. La librairie sur laquelle elles sont développées supporte aussi NNTP, POP3 et les méthodes d'accès aux boîtes aux lettres locales. Reportez-vous à la fonction imap_open() pour plus d'informations.
Ce document ne peut entrer dans les détails de toutes les sujets abordés. Plus d'informations sont disponibles avec la documentation de la librairie C (docs/internal.txt) ainsi que les RFC suivantes :
RFC821: Simple Mail Transfer Protocol (SMTP).
RFC822: 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 & RFC2049: Multipurpose Internet Mail Extensions (MIME).
- Table des matières
- imap_8bit -- Convertit une chaîne à 8 bits en une chaîne à guillemets.
- imap_alerts -- Retourne toutes les alertes
- imap_append -- Ajoute une chaîne 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 -- Read the structure of a specified body section of a specific message
- imap_check -- Vérifie le courrier de la boîte aux lettres courante.
- imap_clearflag_full -- Supprime un flag sur un message.
- imap_close -- Termine un flot IMAP.
- imap_createmailbox -- Crée une nouvelle boîte aux lettres.
- imap_delete -- Marque le fichier 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_expunge -- Efface tous les messages marqués pour l'effacement.
- imap_fetch_overview -- Lit un 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_fetchstructure -- Lit la structure d'un message.
- imap_get_quota -- Lit les quotas des boîtes aux lettres
- imap_getmailboxes -- Liste les boîtes aux lettres, et retourne le détail pour chacune.
- imap_getsubscribed -- Liste toutes les boîtes aux lettres souscrites.
- imap_header -- Lit l'en-tête d'un message.
- 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_last_error -- Retourne la dernière erreur (si elle existe) qui est survenu lors de la dernière requête.
- imap_listmailbox -- Liste les boîtes aux lettres.
- imap_listsubscribed -- Liste les boîtes aux lettres souscrites.
- 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 les messages spécifiés dans une boîte aux lettres.
- imap_mail -- Envoie un message mail
- imap_mailboxmsginfo -- Lit les informations à propos de la boîte aux lettres courante.
- imap_mime_header_decode -- Décode les éléments MIME d'une en-tête
- imap_msgno -- Retourne le numéro de séquence de message pour un UID donné.
- imap_num_msg -- Retourne le nombre de message 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 flot IMAP vers une boîte aux lettres.
- imap_ping -- Vérifie que le flot IMAP est toujours actif.
- imap_popen -- Open a persistant IMAP stream to a mailbox
- imap_qprint -- Convertit une chaîne à guillemets en une chaîne à 8 bits.
- imap_renamemailbox -- Renomme une boîte aux lettres.
- imap_reopen -- Ouvre un flot IMAP vers une nouvelle boîte aux lettres.
- imap_rfc822_parse_adrlist -- Analyse une chaîne d'adresse.
- imap_rfc822_parse_headers -- Analyse une en-tête mail
- imap_rfc822_write_address -- Retourne une adresse email proprement formatée
- imap_scanmailbox -- Lit la liste des boîtes aux lettres, et y recherche une chaîne.
- imap_search -- Retourne un tableau de message après recherche.
- imap_set_quota -- Modifie le quota d'une boîte aux lettres
- imap_setacl -- Sets the ACL for a giving mailbox
- imap_setflag_full -- Positionne un flag sur un message.
- imap_sort -- Trie des messages.
- imap_status -- Retourne les informations de statut sur une boîte aux lettres autres que la boîte courante.
- imap_subscribe -- Souscrit à une boîte aux lettres.
- imap_thread -- Return threaded by REFERENCES tree
- 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 modifiée UTF-7.
- imap_utf7_encode -- Convertit des données 8bit en texte UTF-7.
- imap_utf8 -- Convertit du texte en UTF8
imap_8bit
Description
string imap_8bit ( string string)imap_8bit() convertit la chaîne à 8 bits en une chaîne à guillemets.
imap_8bit() retourne une chaîne à guillemets.
Voir aussi imap_qprint().
imap_alerts
Description
array imap_alerts ( void)imap_alerts() retourne 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é, la pile d'alertes est vidée.
imap_append
Description
int imap_append ( resource imap_stream, string mbox, string message, string flags)imap_append() ajoute un message dans la boîte aux lettres mbox. Si l'option flags est utilisée, flags sera aussi écrit dans la boîte aux lettres.
imap_append() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Lors des échanges avec le serveur Cyrus IMAP, vous devrez utiliser "\r\n" comme terminaison de ligne, à la place de "\n" ou l'opération échouera.
Exemple 1. Exemple avec imap_append()
|
imap_base64
Description
string imap_base64 ( string text)imap_base64() décode un texte encodé en BASE64. Le texte décodé est retourné sous la forme d'une chaîne.
imap_binary
Description
string imap_binary ( string string)imap_binary() convertit la chaîne à 8 bits string en une chaîne à base64.
imap_binary() retourne la chaîne codée.
Voir aussi imap_base64().
imap_body
Description
string imap_body ( resource imap_stream, int msg_number, int flags)imap_body() retourne le corps du message numéro msg_number de la boîte aux lettres courante. L'option flags est un masque qui peut contenir les valeurs suivantes :
FT_UID - msgno est un UID
FT_PEEK - Ne pas lever le drapeaux \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.
imap_body() va retourner une copie brute du corps du message. Pour extraire les sous parties MIME du message, utilisez imap_fetchstructure() pour analyser la structure, et imap_fetchbody() pour extraire une copie d'une des sous-partie.
imap_bodystruct
(PHP 3>= 3.0.4, PHP 4 )
imap_bodystruct -- Read the structure of a specified body section of a specific messageDescription
object imap_bodystruct ( int stream_id, int msg_no, int section)
| Avertissement |
This function is currently not documented, only the argument list is available. |
imap_check
Description
object imap_check ( resource imap_stream)imap_check() retourne les informations à propos de la boîte aux lettres courante. imap_check() retourne FALSE en cas d'échec.
imap_check() vérifie le statut de la boîte aux lettres courante, sur le serveur imap_stream, et retourne les informations dans un objet avec les membres suivants :
Date - Date de dernière modification du contenu de la boîte aux lettres
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
imap_clearflag_full
Description
string imap_clearflag_full ( resource stream, string sequence, string flag, string options)imap_clearflag_full() efface le flag flag dans les messages de la séquence sequence, du flot imap stream.
Les options sont un masque de bit, qui accepte les valeurs suivantes :
imap_close
Description
int imap_close ( resource imap_stream, int flags)imap_close() termine un flot IMAP. imap_close() prend un argument optionnel flag, CL_EXPUNGE, qui va retirer automatiquement de la liste la boîte aux lettres.
imap_createmailbox
Description
int imap_createmailbox ( resource imap_stream, string mbox)imap_createmailbox() crée une nouvelle boîte aux lettres nommée mbox. Les noms contenant des caractères spéciaux doivent être encodés.
imap_createmailbox() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Exemple 1. Exemple avec imap_createmailbox()
|
Voir aussi imap_renamemailbox(), imap_deletemailbox() et imap_open() pour connaître le format des noms de mbox.
imap_delete
(PHP 3, PHP 4 )
imap_delete -- Marque le fichier pour l'effacement, dans la boîte aux lettres courante.Description
int imap_delete ( resource imap_stream, int msg_number [, int flags])imap_delete() retourne TRUE.
imap_delete() marque le fichier msg_number pour l'effacement, dans la boîte aux lettres courante. Le paramètre optionnel flags ne prend qu'une seule valeur, FT_UID, qui indique à PHP qu'il faut traiter msg_number comme un UID. L'effacement réel n'interviendra que lors de l'appel de la fonction imap_expunge().
Exemple 1. Exemple imap_delete()
|
imap_deletemailbox
Description
int imap_deletemailbox ( resource imap_stream, string mbox)imap_deletemailbox() efface la boîte aux lettres (voir imap_open() pour connaître le format des noms de mbox).
imap_deletemailbox() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Voir aussi imap_createmailbox(), imap_renamemailbox() et imap_open() pour le format du paramètre mbox.
imap_errors
Description
array imap_errors ( void)imap_errors() retourne 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és, la pile d'erreur est vidée.
imap_expunge
Description
int imap_expunge ( resource imap_stream)imap_expunge() efface tous les messages marqués pour l'effacement par imap_delete().
imap_expunge() retourne TRUE.
imap_fetch_overview
Description
array imap_fetch_overview ( resource imap_stream, string sequence [, int flags])imap_fetch_overview() lit les en-têtes des courriers électroniques de la séquence sequence et retourne un sommaire de leur contenu. sequence va contenir une séquence d'indice de message ou d'UIDs, si flags cotient FT_UID. La valeur retournée est un tableau d'objets, un par message d'en-tête décrit :
subject - Le sujet du message
from - Expéditeur
date - Date d'expédition
message_id - Identification du message
references - est une référence sur l'id de ce message
size - taille en octets
uid - UID du message dans la boîte aux lettres
msgno - 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
Exemple 1. Exemple avec imap_fetch_overview()
|
Voir aussi imap_fetchstructure().
imap_fetchbody
Description
string imap_fetchbody ( resource imap_stream, int msg_number, string part_number [, flags flags])imap_fetchbody() va rechercher une section du corps du message, et la retourne sous la forme d'une chaîne. La section est une chaîne d'entiers, séparés par des virgules, qui servent d'index dans le corps du message, comme spécifié dans la norme IMAP4. Le texte n'est alors pas décodé par imap_fetchbody().
L'option imap_fetchbody () est un masque qui peut contenir les valeurs suivantes :
FT_UID - msgono 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.
imap_fetchheader
Description
string imap_fetchheader ( resource imap_stream, int msgno, int flags)imap_fetchheader() retourne l'en-tête brute et complète RFC 822 du message msgno, et le retourne sous la forme d'une chaîne.
Les options sont :
FT_UID L'argument msgno 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é. (e.g. dans une opération
de sauvegarde dans un fichier).
imap_fetchstructure
Description
object imap_fetchstructure ( resource imap_stream, int msg_number [, int flags])imap_fetchstructure() la structure du message msg_number. imap_fetchstructure() dispose d'une option [flags], qui une seule valeur, FT_UID, pour indiquer que l'argument msg_number est un UID. imap_fetchstructure() retourne un objet avec des propriétés d'enveloppe, de date interne, de taille, de structure de flags et de corps, ainsi qu'un objet pour chaque attachement. La structure est la suivante :
Tableau 1. Objets retournés 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 typeMIME |
| ifdescription | TRUE s'il y au ne 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 de disposition |
| ifparameters | TRUE si le tableau de paramètres existe |
| parameters | Tableau de paramètres MIME |
| parts | Tableau d'objet décrivant chaque partie du message |
dparameters est un tableau d'objet où chaque objet à un "attribut" et une "valeur".
parameter est un tableau d'objet où chaque objet à un "attribut" et une "valeur".
parts est un tableau d'objets de même structure que l'objet supérieur, mais qui ne contient pas d'autres objets de même sorte.
Voir aussi imap_fetchstructure().
imap_get_quota
Description
array imap_get_quota ( resource imap_stream, string quota_root)imap_get_quota() 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 votre boîte aux lettres. La valeur courante est l'espace actuellement utilisé par votre boîte aux lettres. imap_get_quota() retournera FALSE en cas d'échec.
imap_get_quota() ne fonctionne actuellement qu'avec les librairies c-client2000.
imap_stream doit avoir été créé avec la fonction imap_open(). Ce flot est nécessairement ouvert en tant qu'administrateur du serveur, pour que les droits nécessaires lui soit alloué. quota_root doit être de la forme : "user.nom", où "nom" est le nom de la boîte aux lettres que vous souhaitez analyser.
Exemple 1. Exemple avec imap_get_quota()
|
Voir aussi imap_open() et imap_set_quota().
imap_getmailboxes
(PHP 3>= 3.0.12, PHP 4 )
imap_getmailboxes -- Liste les boîtes aux lettres, et retourne le détail pour chacune.Description
array imap_getmailboxes ( resource imap_stream, string ref, string pat)imap_getmailboxes() retourne un tableau d'objets contenant les informations sur les boîtes aux lettres. Chaque objet a les attributs 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 (vous ne pouvez pas 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.
ref ne devrait être que le serveur IMAP sous la forme {imap_server:imap_port}, et pattern spécifie la position dans la hiérarchie des boîtes aux lettres, où il faut commencer à charcher. Si vous voulez passer en revue toute la hiérarchier, passez '*' comme pattern.
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'interesse 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.
Exemple 1. Exemple avec imap_getmailboxes()
|
Voir aussi imap_getsubscribed().
imap_getsubscribed
Description
array imap_getsubscribed ( resource imap_stream, string ref, string pattern)imap_getsubscribed() est identique à imap_getmailboxes(), mais ne retourne que les boîtes aux lettres auxquelles l'utilisateur est inscrit.
imap_header
Description
object imap_header ( resource imap_stream, int msg_number [, int fromlength [, int subjectlength [, string defaulthost]]])imap_header() est un alias de imap_headerinfo() et lui est identique en tous points.
imap_headerinfo
Description
object imap_headerinfo ( resource imap_stream, int msg_number [, int fromlength [, int subjectlength [, string defaulthost]]])imap_headerinfo() retourne un objet contenant divers éléments d'en-tête.
remail, date, Date, subject, Subject, in_reply_to, message_id,
newsgroups, followup_to, references
éléments d'en-tête :
Recent - 'R' si récent et lu
'N' si récent et non lu
' ' si non récent
Unseen - 'U' si non lu ET non récent
' ' si lu OU non lu et récent
Answered -'A' si répondu,
' ' si non répondu
Deleted - 'D' si effacé,
' ' si non effacé
Draft - 'X' si brouillon,
' ' si non brouillon
Flagged - 'F' si marqué,
' ' si non marqué
Notez bien que le comportement récent/non lu est un peu particulier :
si vous voulez savor si un message est non lu, vous devez le vérifier
avec
Unseen == 'U' || Recent == 'N'
toaddress (toute la ligne d'en-tête To: jusqu'à 1024 caractères)
to[] (retourne un objet avec tout l'en-tête To, contenant):
personal
adl
mailbox
host
fromaddress (toute la ligne d'en-tête from: jusqu'à 1024 caractères)
from[] (retourne un objet avec tout l'en-tête From, contenant):
personal
adl
mailbox
host
ccaddress (toute la ligne d'en-tête CC: jusqu'à 1024 caractères)
cc[] (retourne un objet avec tout l'en-tête CC, contenant):
personal
adl
mailbox
host
bccaddress (toute la ligne d'en-tête BCC: jusqu'à 1024 caractères)
bcc[] (retourne un objet avec tout l'en-tête BCC, contenant):
personal
adl
mailbox
host
reply_toaddress (oute la ligne d'en-tête Reply_to: jusqu'à 1024 caractères)
reply_to[] (retourne un objet avec tout l'en-tête Reply_to, contenant)
personal
adl
mailbox
host
senderaddress (toute la ligne d'en-tête Sender: jusqu'à 1024 caractères)
sender[] (retourne un objet avec tout l'en-tête Sender, contenant)
personal
adl
mailbox
host
return_path (toute la ligne d'en-tête Return-path: jusqu'à 1024 caractères)
return_path[] (retourne un objet avec tout l'en-tête Return-path, contenant)
personal
adl
mailbox
host
udate (Date du mail, au format UNIX)
fetchfrom (Ligne d'en-tête from formatée pour tenir dans fromlength
caractères)
fetchsubject (Ligne d'en-tête subject formatée pour tenir dans subjectlength caractères)
imap_headers
Description
array imap_headers ( resource imap_stream)imap_headers() retourne un tableau de chaîne contenant les en-tête des messages. Une chaîne par message.
imap_last_error
(PHP 3>= 3.0.12, PHP 4 )
imap_last_error -- Retourne la dernière erreur (si elle existe) qui est survenu lors de la dernière requête.Description
string imap_last_error ( void)imap_last_error() retourne le texte complet de la dernière erreur IMAP (si elle existe) qui est survenu lors de la dernière requête. La pile d'erreur n'est pas touchée. Appeler imap_last_error() successivement dans nouvelles erreurs retournera la même erreur.
imap_listmailbox
Description
array imap_listmailbox ( resource imap_stream, string ref, string pat)imap_listmailbox() retourne un tableau contenant les noms des boîtes aux lettres.
Exemple 1. Exemple avec imap_listmailbox()
|
imap_listsubscribed
Description
array imap_listsubscribed ( resource imap_stream, string ref, string pattern)imap_listsubscribed() retourne un tableau avec toutes les boîtes aux lettres auxquelles vous avez souscrit. Les arguments ref et pattern indiquent respectivement, le dossier où chercher et le nom des boîtes recherchées, sous la forme d'un masque.
imap_mail_compose
Description
string imap_mail_compose ( array envelope, array body)
Exemple 1. Exemple imap_mail_compose()
|
imap_mail_copy
Description
int imap_mail_copy ( resource imap_stream, string msglist, string mbox, int flags)imap_mail_copy() copie les messages email spécifiés par msglist dans la boîte aux lettres nommée mbox. msglist est un intervalle, et pas seulement une liste numéros de message.
imap_mail_copy() retourne TRUE en cas de succès et FALSE en cas d'erreur.
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.
imap_mail_move
Description
int imap_mail_move ( resource imap_stream, string msglist, string mbox [, int flags])imap_mail_move() déplace les messages spécifiés par msglist dans la boîte aux lettres mbox. msglist est un intervalle, et pas seulement une liste de messages.
flags est un champs de bit et peut contenir une seule valeur :
CP_UID - La séquence de nombrs contient UIDS
imap_mail_move() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
imap_mail
Description
string imap_mail ( string to, string subject, string message [, string additional_headers [, string cc [, string bcc [, string rpath]]]])imap_mail() est uniquement disponible sous PHP 3.
imap_mailboxmsginfo
(PHP 3>= 3.0.2, PHP 4 )
imap_mailboxmsginfo -- Lit les informations à propos de la boîte aux lettres courante.Description
object imap_mailboxmsginfo ( resource imap_stream)imap_mailboxmsginfo() retourne les informations à propos de la boîte aux lettres courante. imap_mailboxmsginfo() retourne FALSE en cas d'échec.
imap_mailboxmsginfo() vérifie le statut courant de la boîte aux lettres sur le serveur, et retourne un objet avec les propriétés suivantes :
Tableau 1. Propriétés de boîte aux lettres
| Date | Date de dernière modification du contenu de la boîte aux lettres |
| 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 |
Exemple 1. Exemple avec imap_mailboxmsginfo()
|
imap_mime_header_decode
Description
array imap_mime_header_decode ( string text)imap_mime_header_decode() décode un message MIME qui contient des données non ASCII (Voir RFC2047) Les éléments décodés sont retournés dans un tableau d'objets. Chacun de ces objets a deux propriétés : "charset" & "text". Si l'élément n'a pas été encodé, ou, en d'autres termes, sil il est en clair (plain US_ASCII), la propriété "charset" est mise à "default".
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.
imap_msgno
Description
int imap_msgno ( resource imap_stream, int uid)imap_msgno() retourne le numéro de séquence de message pour l'UID uid. C'est la fonction contraire de imap_uid().
imap_num_msg
Description
int imap_num_msg ( resource imap_stream)imap_num_msg() retourne le nombre de message dans la boîte aux lettres courante.
Voir aussi imap_num_recent() et imap_status().
imap_num_recent
(PHP 3, PHP 4 )
imap_num_recent -- Retourne le nombre de messages récents dans la boîte aux lettres courante.Description
int imap_num_recent ( resource imap_stream)imap_num_recent() retourne le nombre de message récents dans la boîte aux lettres courante.
Voir aussi imap_num_msg() et imap_status().
imap_open
Description
int imap_open ( string mailbox, string username, string password [, int flags])imap_open() retourne un flot IMAP en cas de succès, et FALSE en cas d'erreur. imap_open() peut aussi être utilisée pour ouvrir des flots sur des serveurs POP3 et NNTP.
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. L'adresse du serveur, mise entre accolades '{' et '}', est constitué 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. 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().
Les options sont 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.
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 flot.
Pour se connecter à un serveur IMAP, on peut utiliser la commande suivante :
Pour se connecter à un serveur POP3 qui fonctionne sur le port 110 de la machine locale on peut utiliser la commande suivante : Pour se connecter à un serveur IMAP SSL ou POP3 SSL, ajoutez /ssl après le protocole : Pour se connecter à un serveur SSL IMAP ou POP3 avec un certificat ajoutez /ssl/novalidate-cert après le protocole : Pour se connecter à un serveur NNTP qui fonctionne sur le port 119 de la machine locale on peut utiliser la commande: Pour se connecter à un serveur distant, remplacez "localhost" par le nom ou l'adresse IP de la machine.
Exemple 1. Exemple avec imap_open()
|
imap_ping
Description
int imap_ping ( resource imap_stream)imap_ping() retourne TRUE si le flot imap_stream existe toujours, et FALSE sinon.
imap_ping() vérifie que le flot IMAP est toujours actif, en lui envoyant un ping. Cette fonction permet de se rendre compte que du 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.
imap_popen
Description
int imap_popen ( string mailbox, string user, string password [, int options])
| Avertissement |
This function is currently not documented, only the argument list is available. |
imap_qprint
Description
string imap_qprint ( string string)imap_qprint() convertit la chaîne à guillemets string en une chaîne à 8 bits.
imap_qprint() retourne une chaîne 8 bits (binaire).
Voir aussi imap_8bit().
imap_renamemailbox
Description
int imap_renamemailbox ( resource imap_stream, string old_mbox, string new_mbox)imap_renamemailbox() renomme la boîte aux lettres old_mbox en new_mbox.
imap_renamemailbox() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Voir aussi imap_createmailbox(), imap_deletemailbox() et imap_open() pour le format de mbox.
imap_reopen
Description
int imap_reopen ( resource imap_stream, string mailbox [, string flags])imap_reopen() réouvre la connexion spécifiée au serveur IMAP ou NNTP, avec une nouvelle boîtes aux lettres.
Les options sont des masques de bit, qui peuvent 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
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 flot. (voir imap_delete() et imap_expunge()).
imap_rfc822_parse_adrlist
Description
string imap_rfc822_parse_adrlist ( string address, string default_host)address analyse la chaîne address et essaie, pour chaque adresse, de retourner un tableau d'objets. Les 4 objets sont :
mailbox - Le nom de la boîte aux lettres
host - le nom de l'hôte
personal - Le nom personnel
adl - at domain source route (NDT : ???).
Exemple 1. Exemple avec imap_rfc822_parse_adrlist()
|
imap_rfc822_parse_headers
Description
object imap_rfc822_parse_headers ( string headers [, string defaulthost])imap_rfc822_parse_headers() analyse la chaîne headers, et retourne un objet contenant differents éléments, similaires à la fonction imap_header(), hormis les flags, et autres éléments liés au serveur IMAP.
imap_rfc822_write_address
Description
string imap_rfc822_write_address ( string mailbox, string host, string personal)mailbox retourne une adresse email proprement formatée, à partir du nom de la boîte aux lettres de l'hôte host, et des informations personnelles personal.
imap_scanmailbox
Description
array imap_scanmailbox ( resource imap_stream, string string)imap_scanmailbox() retourne un tableau contenant les noms des boîtes aux lettres qui contiennent la chaîne string. imap_scanmailbox() est simialaire à imap_listmailbox(), mais va aussi rechercher la chaîne string dans dans les données de la boîte aux lettres. Reportez-vous à imap_getmailboxes() pour une description des paramètres ref et pattern.
imap_search
Description
array imap_search ( resource imap_stream, string criteria, int flags)imap_search() effectue une recherche dans la boîte aux lettres courante, sur le flot IMAP courant. criteria est une chaîne, délimitée par des espaces, dans laquelle les mots-clés suivants sont acceptés. Tous les arguments multi-mots doivent être entre guillemets :
ALL - retourne tous les message qui vérifie 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 champs 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 champs 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" dan le champs From:
KEYWORD "string" - tous les messags 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 champs Date:
RECENT - tous les messages avec le flag \\RECENT
SEEN - tous les messages lus (avec le flag\\SEEN flag)
SINCE "date" - tous les messages avec la date Date: après "date"
SUBJECT "string" - tous les messages avec la chaîne "string" dans le champs Subject:
TEXT "string" - tous les messages avec le texte "string"
TO "string" - tous les messages avec la chaîne "string" dans le champs To:
UNANSWERED - tous les messages non répondus
UNDELETED - tous les messages non effacés
UNFLAGGED - tous les messages non flaggés
UNKEYWORD "string" - tous les messages dans le mot clés "string"
UNSEEN - tous les messages non lus
Par exemple, pour rechercher les messages non répondus, envoyés par maman, vous pouvez 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 inprécise. (voir aussi RFC2060, section 6.4.4).
Les valeurs pour les flags sont SE_UID, qui fait que le tableau réponse contient les UIDs plutôt que les numéros de séquence.
imap_set_quota
Description
int imap_set_quota ( resource imap_stream, string quota_root, int quota_limit)imap_set_quota() modifie le quota de la boîte aux lettres quota_root, en la fixant à quota_limit. imap_set_quota() requiert que imap_stream ait été ouvert avec un compte d'administrateur, pour avoir les droits nécessaires : elle ne fonctionnera avec aucun autre utilisateur.
imap_get_quota() ne fonctionne actuellement qu'avec les librairies c-client2000.
imap_stream doit avoir été créé avec la fonction imap_open(). Ce flot est nécessairement ouvert en tant qu'administrateur du serveur, pour que les droits nécessaires lui soit alloué. quota_root doit être de la forme : "user.nom", où "nom" est le nom de la boîte aux lettres que vous souhaitez analyser. quota_limit est la nouvelle taille maximum (en ko) de la boîte quota_root.
imap_set_quota() retourne TRUE en cas de succès, et FALSE sinon.
Voir aussi imap_open() et imap_set_quota().
imap_setacl
Description
int imap_setacl ( int stream_id, string mailbox, string id, string rights)
| Avertissement |
This function is currently not documented, only the argument list is available. |
imap_setflag_full
Description
string imap_setflag_full ( int stream, string sequence, string flag, string options)imap_setflag_full() affecte le flag spécifié aux messages de la sequence donné.
Les flags que vous pouvez modifier sont "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", "\\Draft" et "\\Recent" (comme défini dans la RFC2060).
Les options sont un masque de bits, et peuvent contenir les valeurs suivantes :
imap_sort
Description
string imap_sort ( int stream, int criteria, int reverse, int options)imap_sort() retourne un tableau de nombre de message, triés suivant les paramètres suivants :
reverse vaut 1 pour signifier : tri inverse.
Les critères 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 cachée (cc address)
SORTSIZE Taille du message en octets
Les flags dont des masques de bits, d'un ou plusieurs des éléments suivants :
imap_status
(PHP 3>= 3.0.4, PHP 4 )
imap_status -- Retourne les informations de statut sur une boîte aux lettres autres que la boîte courante.Description
object imap_status ( resource imap_stream, string mailbox, int options)imap_status() retourne un objet contenant les informations de statut. Les options valables sont :
SA_MESSAGES - met la valeur de status->messages au nombre de messages dans la boîtes aux lettres.
SA_RECENT - met la valeur destatus->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 les valeurs de de toutes les précédents.
status->flags est aussi fixé : c'est un masque de bit qui peut contenir tous les flags ci-dessus.
Exemple 1. Exemple imap_status()
|
imap_subscribe
Description
int imap_subscribe ( resource imap_stream, string mbox)imap_subscribe() souscrit à la boîte aux lettres mbox.
imap_subscribe() retourne TRUE en cas de succès, et FALSE en cas d'échec.
imap_thread
Description
int imap_thread ( int stream_id [, int flags])
| Avertissement |
This function is currently not documented, only the argument list is available. |
imap_uid
Description
int imap_uid ( resource imap_stream, int msgno)imap_uid() retourne l'UID pour le message msgno. Un UID est un identifant unique que ne change jamais, alors que le numéro du message dans la lsite des messages peut changer à toute modification de la boîte aux lettres. C'est la fonction contraire de imap_msgno().
Note : Cette fonctionnalité n'est pas supportées par les boîtes aux lettres POP3.
imap_undelete
Description
int imap_undelete ( resource imap_stream, int msg_number)imap_undelete() enlève la marque d'effacement du message msg_number, placée avec imap_delete().
imap_subscribe() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
imap_unsubscribe
Description
int imap_unsubscribe ( resource imap_stream, string mbox)imap_unsubscribe() termine la souscription à la boîte aux lettres mbox.
imap_unsubscribe() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
imap_utf7_decode
Description
string imap_utf7_decode ( string text)imap_utf7_decode() décode la chaîne UTF-7 text en données 8 bits.
imap_utf7_decode() retourne les données 8bits décodées, ou FALSE si la chaîne text n'est pas au format UTF-7. Cette fonction sert à décoder des noms de boîtes aux lettres qui contiennent des caractères internationaux hors de l'espace ASCII. Le standard UTF-7 est défini dans la RFC 2060, section 5.1.3 (l'original UTF-7 a été défini dans RFC1642).
imap_utf7_encode
Description
string imap_utf7_encode ( string data)imap_utf7_encode() retourne les données data 8bits encodées, ou FALSE si une erreur est survenue. Cette fonction sert à encoder des noms de boîtes aux lettres qui contiennent des caractères internationaux hors de l'espace ASCII. Le standard UTF-7 est défini dans la RFC 2060, section 5.1.3 (l'original UTF-7 a été défini dans RFC1642).
imap_utf7_encode() retourne un texte UTF-7.
imap_utf8
Description
string imap_utf8 ( string text)imap_utf8() convertit le texte text en UTF8 (comme défini dans RFC2044).
XLIV. Informix
Les pilotes d'accès à Informix pour Online (ODS) 7.x, SE 7.x, Universal Server (IUS) 9.x et IDS 2000 sont implémentés dans "functions/ifx.ec" et "functions/php3_ifx.h". Le support ODS 7.x est plutôt complet, et accepte les colonnes de type BYTE et TEXT. Le support IUS 9.x est partiellement fini, de nouveaux types sont disponibles, mais SLOB et CLOB sont toujours en cours de développement.
Notes de configuration : Vous avez besoin d'une version de ESQL/C pour compiler le pilote PHP d'Informix. Les versions ESQL/C 7.2x sont utilisables. ESQL/C fait partie du SDK Informix Client.
Avant que vous ne lanciez le script "configure", assurez-vous que la variable d'environnement "INFORMIXDIR" a été correctement paramétrée, et que $INFORMIXDIR/bin est dans votre PATH.
Le script de configuration va détecter automatiquement les librairies disponibles, et inclure les dossiers si vous lancer le script avec l'option --with-informix=yes. Vous pouvez ignorer cette détection en spécifiant "IFX_LIBDIR", "IFX_LIBS" et "IFX_INCDIR" dans votre environnement. Le script de configuration va aussi essayer de détecter la version de votre serveur Informix. Il modifiera alors la condition de compilation "HAVE_IFX_IUS" si votre serveur Informix est d'une version plus récente que 9.00.
Notes d'exécutions : Assurez-vous que les variables d'environnement INFORMIXDIR et INFORMIXSERVER sont accessibles au pilote PHP, et que le dossier bin INFORMIX est aussi dans la variable PATH. Vous pouvez le voir en lançant un script qui contient un appel à phpinfo() avant que vous ne commenciez à tester. La fonction phpinfo() affiche une liste des variables d'environnement. Cela fonctionne aussi bien en mode mod_php, qu'en mode CGI. Il vous faudra fixer les valeurs dans le script de démarrage d'Apache.
Les "Informix shared libraries" doivent aussi être accessibles au chargement (vérifiez LD_LINBRARY_PATH ou ld.so.conf/ldconfig).
Notes sur l'utilisation des BLOBs (TEXT et BYTE) : Les objets de type BLOBs sont normalement gérés par des identifiants de BLOB. Les requêtes de sélection retournent un identifiant de BLOB pour chaque colonne de type BYTE et TEXT. Vous pouvez en lire le contenu, avec des commandes de types "string_var = ifx_get_blob($BLOB_id);" ; si vous souhaitez ramener le BLOB en mémoire (avec: "ifx_blobinfile_mode(0);"). Si vous préférez recevoir le contenu d'une colonne BLOB dans un fichier, utilisez ifx_blobinfile_mode(), et ifx_get_blob($BLOB_id) vous retournera le nom du fichier. Utilisez les fonctions habituelles d'accès aux fichiers pour lire son contenu.
Pour les requêtes INSERT/UPDATE, vous devez créer les identifiants de BLOB par vous même, avec la fonction ifx_create_blob(). Puis, vous placez l'identifiant de BLOB dans un tableau, et remplacez la colonne par un point d'interrogation. Pour les UPDATE/INSERT, vous êtes responsable du contenu du BLOB, avec la fonction ifx_update_blob().
Le comportement par défaut des colonnes de type BLOB peut être modifié en affectant de nouvelles valeurs aux variables de configuration (même à la volée) :
Variable de configuration : ifx.textasvarchar
Variable de configuration : ifx.byteasvarchar
Fonctions à utiliser lors de l'exécution :
ifx_textasvarchar(0) : Utilise l'identifiant de BLOB avec des colonnes de type TEXT, dans les requêtes SELECT
ifx_byteasvarchar(0) : Utilise l'identifiant de BLOB avec des colonnes de type BYTE, dans les requêtes SELECT
ifx_textasvarchar(1) : Retourne les colonnes de type TEXT sous la forme de VARCHAR, sans utiliser les identifiants de BLOB dans les requêtes SELECT.
ifx_byteasvarchar(1) : Retourne les colonnes de type BYTE sous la forme de VARCHAR, sans utiliser les identifiants de BLOB dans les requêtes SELECT.
Variable de configuration : ifx.BLOBinfile
Fonctions à utiliser lors de l'exécution :
ifx_blobinfile_mode(0) : Retourne les colonnes de type BYTE en mémoire, l'identifiant de BLOB vous donnera accès au contenu.
ifx_blobinfile_mode(1) : Retourne les colonnes de type BYTE dans un fichier, l'identifiant de BLOB vous donnera accès au nom de ce fichier.
En affectant la valeur de 1 à ifx_text/byteasvarchar, vous pouvez utiliser les colonnes de type TEXT et BYTE dans les requêtes SELECT comme des champs VARCHAR (mais plus long). Etant donné la gestion des chaînes par PHP, cette technique conserve les données binaires. Les données retournées peuvent contenir n'importe quoi, et vous êtes responsable de la bonne manipulation de ces valeurs.
En affectant la valeur de 1 à ifx_blobinfile_mode(), utilisez le nom de fichier retourné par ifx_get_blob() pour accéder au contenu du BLOB. Notez bien que vous êtes tenu responsable de l'effacement des fichiers temporaires, créés par Informix. Chaque nouvelle ligne lue sur le serveur va créer un nouveau fichier temporaire, pour chaque colonne de type BYTE.
L'emplacement des fichiers temporaire peut être modifié, grâce à la variable "blobdir", (par défaut, ".", c'est-à-dire, le dossier courant). Une valeur telle que BLOBdir="tmpBLOB" simplifiera le nettoyage des fichiers temporaires, accidentellement oubliés (les noms commencent tous par "blb").
Suppression automatique des espaces (SQLCHAR et SQLNCHAR) : Elle peut être mise en place avec la variable de configuration.
ifx.charasvarchar : avec la valeur 1, les espaces de fin de champs seront automatiquement supprimés.
NULL values : Lorsque la variable de configuration ifx.nullformat (ou que la fonction ifx_nullformat()) est à un, les colonnes contenant la valeur NULL retourneront la chaîne "NULL", et sinon, retourneront une chaîne vide. Cela vous permet de faire la différence entre les colonnes vides et celles qui contiennent la valeur NULL.
- Table des matières
- ifx_affected_rows -- Retourne le nombre de lignes affectées par une requête.
- ifx_blobinfile_mode -- Choisit le mode par défaut des objets BLOB pour toutes les requêtes SELECT.
- ifx_byteasvarchar -- Choisit le mode par défaut des objets BYTE.
- ifx_close -- Ferme une connexion à un serveur Informix.
- ifx_connect -- Ouvre une connexion à un serveur Informix.
- ifx_copy_blob -- Duplique un objet BLOB.
- ifx_create_blob -- Crée un objet BLOB.
- ifx_create_char -- Crée un objet char.
- ifx_do -- Exécute une requête SQL déjà préparée.
- ifx_error -- Retourne le code d'erreur de la dernière requête Informix.
- ifx_errormsg -- Retourne le message d'erreur de la dernière requête Informix.
- ifx_fetch_row -- Retourne une ligne sous la forme d'un tableau énuméré.
- ifx_fieldproperties -- Liste les propriétés des champs SQL.
- ifx_fieldtypes -- Liste les champs Informix SQL.
- ifx_free_blob -- Supprime un objet BLOB.
- ifx_free_char -- Supprime un objet char.
- ifx_free_result -- Libère les ressources prises par un résultat.
- ifx_get_blob -- Retourne le contenu d'un objet BLOB.
- ifx_get_char -- Retourne le contenu d'un objet char.
- ifx_getsqlca -- Retourne le contenu de la variable sqlca.sqlerrd[0..5] après une requête.
- ifx_htmltbl_result -- Lit toutes les lignes d'un tableau, et la met sous la forme d'un tableau HTML.
- ifx_nullformat -- Modifie le mode par défaut de lecture des valeurs.
- ifx_num_fields -- Retourne le nombre de colonnes dans une requête.
- ifx_num_rows -- Compte le nombre de ligne déjà lues dans un résultat.
- ifx_pconnect -- Ouvre une connexion persistante à un serveur Informix.
- ifx_prepare -- Prépare une requête SQL pour l'exécution.
- ifx_query -- Envoie une requête Informix.
- ifx_textasvarchar -- Choisit le mode par défaut des objets text.
- ifx_update_blob -- Modifie le contenu d'un objet BLOB.
- ifx_update_char -- Modifie le contenu d'un objet char.
- ifxus_close_slob -- Ferme un objet SLOB.
- ifxus_create_slob -- Crée un objet SLOB et l'ouvre.
- ifx_free_slob -- Supprime un objet SLOB.
- ifxus_open_slob -- Ouvre un objet SLOB.
- ifxus_read_slob -- Lit n bytes d'un objet SLOB.
- ifxus_seek_slob -- Fixe le fichier courant, ou la position courante.
- ifxus_tell_slob -- Retourne le fichier courant, ou la position courante.
- ifxus_write_slob -- Ecrit une chaîne dans un objet SLOB.
ifx_affected_rows
Description
int ifx_affected_rows ( int result_id)ifx_affected_rows() retourne le nombre de lignes affectées par la requête associée à result_id.
result_id est un identifiant valide de résultat retourné par ifx_query() ou ifx_prepare().
Pour les INSERT, UPDATE et DELETE, ce nombre est le nombre exact de lignes affectées (sqlerrd[2]). Pour les SELECT, ce n'est qu'une estimation (sqlerrd[0]). Ne vous y fiez pas.
ifx_affected_rows() est très pratique après ifx_prepare() pour limiter la taille des résultats.
Voir aussi ifx_num_rows().
Exemple 1. Nombre de lignes affectées
|
ifx_blobinfile_mode
(PHP 3>= 3.0.4, PHP 4 )
ifx_blobinfile_mode -- Choisit le mode par défaut des objets BLOB pour toutes les requêtes SELECT.Description
void ifx_blobinfile_mode ( int mode)ifx_blobinfile_mode() modifie le mode par défaut des objets BLOB pour toutes les requêtes SELECT. Mode "0" chargera les BLOB de type Byte en mémoire ; Mode "1" sauvera les BLOB de type Byte dans un fichier.
ifx_byteasvarchar
Description
void ifx_byteasvarchar ( int mode)ifx_byteasvarchar() modifie le mode par défaut des objets BYTE. Le mode "0" retournera l'identifiant de BLOB, et le mode "1" retourenra le contenu du TEXT sous la forme d'un VARCHAR.
ifx_close
Description
int ifx_close ( [int link_identifier])ifx_close() retourne toujours TRUE.
ifx_close() ferme le lien au serveur de données Informix associé à l'identifant de connexion link_identifier. Si l'identifiant du lien n'est pas spécifié, la dernière connexion est utilisée.
Notez qu'il n'est généralement pas besoin d'appeler cette fonction, car les connexions non persistantes seront automatiquement fermées.
ifx_close() ne peut pas fermer une connexion ouverte avec ifx_pconnect().
Voir aussi ifx_connect() et ifx_pconnect().
ifx_connect
Description
int ifx_connect ( [string database [, string userid [, string password]]])ifx_connect() retourne un identifiant de connexion, en cas de succès, et FALSE sinon.
ifx_connect() établit une connexion à un serveur Informix. Tous les arguments sont optionnels, et, s'ils viennent à manquer, les valeurs par défaut seront prises dans le fichier de configuration . (ifx.default_host pour l'hôte par défaut) (Les librairies Informix utiliseront la variable d'environnement $INFORMIXSERVER si ifx.default_host n'est pas définie). ifx.default_user pour l'utilisateur, et ifx.default_password comme mot de passe (si aucun n'a été défini).
Si un deuxième appel à ifx_connect() est fait avec les mêmes arguments, l'identifiant de connexion déjà ouvert sera retourné.
Le lien avec le serveur sera fermé dès que le script se termine, ce qui fait qu'il n'est pas nécessaire de terminer les connexions avec ifx_close().
Voir aussi ifx_pconnect() et ifx_close().
ifx_copy_blob
Description
int ifx_copy_blob ( int bid)ifx_copy_blob() retourne FALSE en cas d'erreur, et sinon, l'identifiant du nouvel objet.
ifx_create_blob
Description
int ifx_create_blob ( int type, int mode, string param)ifx_create_blob() crée un objet BLOB.
type: 1 = TEXT, 0 = BYTE
mode: 0 = L'objet BLOB place le contenu en mémoire ; 1 = L'objet BLOB place le contenu dans un fichier.
param: Si mode = 0: pointeur du contenu, si mode = 1: pointeur vers un fichier.
ifx_create_blob() retourne FALSE en cas d'erreur, et sinon, un identifiant de BLOB.
ifx_create_char
Description
int ifx_create_char ( string param)ifx_create_char() crée un objet char. param sera le contenu de l'objet.
ifx_do
Description
int ifx_do ( int result_id)ifx_do() retourne TRUE en cas de succès, FALSE en cas d'erreur.
Exécute une requête qui a déjà été préparée, ou crée un pointeur pour cela.
Ne libère pas result_id en cas d'erreur.
De plus, elle fixe la valeur de result_id pour accès ultérieur par ifx_affected_rows().
Voir aussi ifx_prepare() (Pour un exemple).
ifx_error
Description
string ifx_error ( void)ifx_error() retourne le code d'erreur de la dernière requête Informix. Les codes d'erreur Informix (SQLSTATE et SQLCODE) formaté comme suit :
x [SQLSTATE = aa bbb SQLCODE=cccc]
avec x = space : aucune erreur
E : erreur
N : il n'y a plus d'informations
W : Alerte
? : Indéfinie
Si le caractère vaut autre chose qu'un espace, SQLSTATE et SQLCODE décrit l'erreur avec plus de détails.
Reportez-vous au manuel Informix pour trouver la description de SQLSTATE et SQLCODE
ifx_error() retourne une chaîne avec un caractères, décrivant le résultat général de la commande, et aussi SQLSTATE et SQLCODE associé à la plus récente requête SQL exécutée. Le format de la chaîne est "(char) [SQLSTATE=(deux chiffres) (trois chiffres) SQLCODE=(un chiffre)]". Le premier caractère peut être ' ' (espace) (succès), 'W' (Alerte), 'E' (une erreur est survenue durant le traitement ) ou 'N' (aucune donnée de retour).
Voir aussi ifx_errormsg().
ifx_errormsg
(PHP 3>= 3.0.4, PHP 4 )
ifx_errormsg -- Retourne le message d'erreur de la dernière requête Informix.Description
string ifx_errormsg ( [int errorcode])ifx_errormsg() retourne le plus récent message d'erreur ou, lorsque l'option errorcode est présent, le message d'erreur associé à errorcode.
Voir aussi ifx_error().
ifx_fetch_row
Description
array ifx_fetch_row ( int result_id [, mixed position])ifx_fetch_row() retourne un tableau associatif qui contient la ligne retournée, ou FALSE s'il ne reste plus de lignes à lire, ou s'il a eu une erreur.
Les colonnes de types BLOB sont retournées sous la forme d'un identifiant à utiliser avec ifx_get_blob() à moins que vous n'ayez utilisé la fonction ifx_textasvarchar() ou ifx_byteasvarchar(), et dans ce cas, les BLOBs seront retournés sous forme de chaîne. ifx_fetch_row() retourne FALSE en cas d'erreur.
result_id est un identifiant valide de résultat, retourné par ifx_query() ou ifx_prepare() (Requêtes SELECT seulement !).
position est un paramètre optionnel, pour une opération de lecture d'informations sur un pointeur de type "scroll": "NEXT", "PREVIOUS", "CURRENT", "FIRST", "LAST" ou encore un nombre. Si vous spécifiez un nombre, la ligne d'index absolu sera retournée. Ce paramètre est optionnel, et ne fonctionne qu'avec les pointeurs de type "scroll".
ifx_fetch_row() retourne une ligne de données d'un résultat associé à l'identifiant de résultat result_id. La ligne est retournée sous la forme d'un tableau associatif.
Les appels ultérieurs à ifx_fetch_row() retourneront la ligne suivante, ou FALSE s'il n'y a plus de ligne.
Exemple 1. Exemple avec ifx_fetch_row()
|
ifx_fieldproperties
Description
array ifx_fieldproperties ( int result_id)ifx_fieldproperties() retourne un tableau associatif avec les nom des champs comme clé, et les données de propriétés des champs comme valeur. ifx_fieldproperties() retourne FALSE en cas d'erreur.
ifx_fieldproperties() retourne les propriétés Informix SQL pour tous les champs d'une requête, sous la forme d'un tableau associatif. Les propriétés sont présentées sous la forme : "SQLTYPE;longueur ;précision;échelle;ISNULLABLE" avec SQLTYPE qui représente le type de données Informix tel que "SQLVCHAR" et ISNULLABLE = "Y" ou "N" (le champs peut contenir NULL ou pas : Oui ou Non).
ifx_fieldtypes
Description
array ifx_fieldtypes ( int result_id)ifx_fieldtypes() retourne un tableau associatif avec les noms des champs comme clés, et les types SQL comme valeur. En cas d'erreur, retourne FALSE.
ifx_free_blob
Description
int ifx_free_blob ( int bid)ifx_free_blob() supprime l'objet BLOB bid. ifx_free_blob() retourne FALSE en cas d'erreur, et sinon TRUE.
ifx_free_char
Description
int ifx_free_char ( int bid)ifx_free_char() supprime l'objet char bid. ifx_free_char() retourne FALSE en cas d'erreur, et sinon TRUE.
ifx_free_result
Description
int ifx_free_result ( int result_id)ifx_free_result() libère les ressources prises par le résultat result_id. ifx_free_result() retourne FALSE en cas d'erreur.
ifx_get_blob
Description
int ifx_get_blob ( int bid)ifx_get_blob() retourne le contenu de l'objet BLOB associé à bid.
ifx_get_char
Description
int ifx_get_char ( int bid)ifx_get_char() retourne le contenu de l'objet associé à l'identifiant bid.
ifx_getsqlca
(PHP 3>= 3.0.8, PHP 4 )
ifx_getsqlca -- Retourne le contenu de la variable sqlca.sqlerrd[0..5] après une requête.Description
array ifx_getsqlca ( int result_id)ifx_getsqlca() retourne une pseudo-ligne (tableau associatif) avec sqlca.sqlerrd[0] à sqlca.sqlerrd[5] après la requête associée result_id.
result_id est un identifiant valide de résultat retourné par ifx_query() ou ifx_prepare().
Pour les requêtes INSERT, UPDATE et DELETE, les valeurs retournées sont celles fixées par le serveur après avoir exécuté la requête. Cela donne accès au nombre de ligne affectées, ainsi qu'au numéro de série d'insertion. Pour les requêtes de type SELECT, les valeurs retournées sont celles qui ont été préparées. Utiliser cette fonction économise l'exécution d'une requête "select dbinfo('sqlca.sqlerrdx')", étant donné qu'elle retourne les valeurs qui ont été sauvées par le pilote ifx au moment approprié.
Exemple 1. Lire les valeurs de sqlca.sqlerrd[x]
|
ifx_htmltbl_result
(PHP 3>= 3.0.3, PHP 4 )
ifx_htmltbl_result -- Lit toutes les lignes d'un tableau, et la met sous la forme d'un tableau HTML.Description
int ifx_htmltbl_result ( int result_id [, string html_table_options])ifx_htmltbl_result() lit toutes les lignes d'un tableau, et la met sous la forme d'un tableau HTML, ou FALSE en cas d'erreur.
Affiche les lignes avec des balises HTML. Le second argument permet de modifier les options de table.
Exemple 1. Affichage sous la forme d'une table HTML
|
ifx_nullformat
Description
void ifx_nullformat ( int mode)ifx_nullformat() modifie le mode par défaut de lecture des valeurs. Le mode "0" retourne "", et le mode "1" retourne "NULL".
ifx_num_fields
Description
int ifx_num_fields ( int result_id)ifx_num_fields() retourne le nombre de colonnes dans la requête result_id ou FALSE en cas d'erreur.
Après avoir préparé ou exécuté une requête, cette fonction retourne le nombre de colonne dans la requête.
ifx_num_rows
Description
int ifx_num_rows ( int result_id)ifx_num_rows() compte le nombre de ligne déjà lues dans le résultat result_id après ifx_query() ou ifx_do().
ifx_pconnect
Description
int ifx_pconnect ( [string database [, string userid [, string password]]])ifx_pconnect() retourne un identifiant positif de connexion Informix, ou FALSE, en cas d'erreur.
ifx_pconnect() se comporte de manière très similaire à ifx_connect() avec deux différences importantes :
ifx_pconnect() se comporte exactement comme ifx_connect() lorsque PHP n'est pas un module Apache. Lors de la connexion, la fonction va chercher une connexion déjà ouverte avec le même hôte, le même nom d'utilisateur, et le même mot de passe. Si elle en trouve une, elle retournera un identifiant de cette connexion, au lieu d'en ouvrir une nouvelle.
Deuxièmement, la connexion au serveur SQL ne sera pas automatiquement refermée à la fin de l'exécution du script. Au contraire, le lien va rester ouvert (ifx_close() ne fermera pas les connexions établies avec ifx_pconnect()).
Ainsi, ce type de lien est appelé 'persistant'.
Voir aussi ifx_connect().
ifx_prepare
Description
int ifx_prepare ( string query, int conn_id [, int cursor_def, mixed blobidarray])ifx_prepare() retourne un entier identifiant de résultat result_id à utiliser avec ifx_do(). Modifie la valeur de affected_rows, pour accès ultérieur avec ifx_affected_rows().
ifx_prepare() prépare la requête query sur la connexion conn_id. Pour les requêtes de type "select-type" un pointeur de résultat est déclaré et ouvert. L'option cursor_type permet de choisir le type de pointeur : "scroll" et/ou "hold". Les valeurs peuvent être combinées ensemble (IFX_SCROLL, IFX_HOLD).
Le nombre de ligne affectées (estimé ou exact) est enregistré, pour être lu avec la fonction ifx_affected_rows().
Si vous avez une colonne de type BLOB (BYTE ou TEXT) dans une requête de modification, vous pouvez passer un paramètre BLOBidarray qui contiendra les identifiants des BLOB à modifier, et vous devrez remplacer cette colonne par un point d'interrogation (?) dans la requête.
Si le contenu d'une colonne de type TEXT (ou BYTE) vous pouvez aussi utiliser les fonctions ifx_textasvarchar() et ifx_byteasvarchar(). Cela vous permettra d'utiliser les colonnes TEXT (ou BYTE) comme des colonnes de type VARCHAR (mais plus long, tout de même), et vous n'aurez pas besoin de l'identifiant de BLOB.
Avec les fonctions ifx_textasvarchar() et ifx_byteasvarchar() (valeurs par défaut), les requêtes SELECT retourneront des identifiants de BLOB. Cet identifiant peut être une chaîne ou un fichier, suivant la configuration (voir plus loin).
Voir aussi ifx_do().
ifx_query
Description
int ifx_query ( string query [, int link_identifier [, int cursor_type [, mixed blobidarray]]])ifx_query() retourne un identifiant positif de résultat Informix en cas de succès, et FALSE en cas d'erreur.
L'entier de type "identifiant de résultat" est utilisé par4 d'autres fonctions pour lire les résultats. Pour un exemple, reportez-vous à ifx_affected_rows() pour connaître le nombre de lignes affectées.
ifx_query() envoie une requête au serveur actif courant, associé à l'identifiant de connexion link_identifier. Si link_identifier n'est pas fourni, la dernière connexion ouverte sera utilisée. Si aucune connexion n'a été ouverte, ifx_query() va essayer d'en créer une, en appelant ifx_connect().
Exécute la requête query sur la connexion conn_id. Pour les requêtes de type SELECT, un pointeur est déclaré, et ouvert. L'option cursor_type permet de choisir le type de pointeur, "scroll" et/ou "hold". cursor_type accepte les deux valeurs séparées, et leur combinaison. Les requêtes d'autre type sont à exécution immédiate.
Le nombre de lignes affectées (estimé ou exact) est enregistré pour être lu avec ifx_affected_rows().
Si vous avez une colonne de type BLOB (BYTE ou TEXT) dans une requête de modification, vous pouvez passer un paramètre BLOBidarray qui contiendra les identifiants des BLOB à modifier, et vous devrez remplacer cette colonne par un point d'interrogation (?) dans la requête.
Si le contenu d'une colonne de type TEXT (ou BYTE) vous pouvez aussi utiliser les fonctions ifx_textasvarchar() et ifx_byteasvarchar(). Cela vous permettra d'utiliser les colonnes TEXT ( ou BYTE ) comme des colonnes de type VARCHAR (mais plus long, tout de même), et vous n'aurez pas besoin de l'identifiant de BLOB.
Avec les fonctions ifx_textasvarchar() et ifx_byteasvarchar() (valeurs par défaut), les requêtes SELECT retourneront des identifiants de BLOB. Cet identifiant peut être une chaîne ou un fichier, suivant la configuration (voir plus loin).
Voir aussi ifx_connect().
Exemple 1. Afficher toutes les lignes de la table "ordres" sous la forme html
|
Exemple 2. Insertion de valeurs dans la table "catalogue"
|
ifx_textasvarchar
Description
void ifx_textasvarchar ( int mode)ifx_textasvarchar() modifie le mode par défaut des objets TEXT. Le mode "0" retournera un identifiant de BLOB et le mode "1" retourne le BLOB sous la forme d'un (gros) varchar.
ifx_update_blob
Description
boolean ifx_update_blob ( int bid, string content)ifx_update_blob() modifie le contenu de l'objet BLOB repéré par sont identifiant bid. content est une chaîne contenant les nouvelles données. ifx_update_blob() retourne FALSE en cas d'erreur, et sinon, TRUE.
ifx_update_char
Description
int ifx_update_char ( int bid, string content)ifx_update_char() modifie le contenu de l'objet char repéré par son identifiantbid. content est une chaîne avec les nouvelles données. ifx_update_char() retourne FALSE en cas d'erreur, et sinon, TRUE.
ifxus_close_slob
Description
int ifxus_close_slob ( int bid)ifxus_close_slob() ferme l'objet SLOB représenté par son identifiant bid. ifxus_close_slob() retourne FALSE en cas d'erreur, et sinon, TRUE.
ifxus_create_slob
Description
int ifxus_create_slob ( int mode)ifxus_create_slob() crée un objet SLOB et l'ouvre. Les modes valides sont : 1 = LO_RDONLY, 2 = LO_WRONLY, 4 = LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 = LO_NOBUFFER -> ou une combinaison des précédents. Vous pouvez aussi utiliser les constantes suivantes : IFX_LO_RDONLY, IFX_LO_WRONLY etc. ifxus_create_slob() retourne FALSE en cas d'erreur, et sinon, l'identifiant de l'objet SLOB.
ifx_free_slob
Description
int ifxus_free_slob ( int bid)ifxus_free_slob() supprime un objet SLOB. bid est l'identifiant de l'objet SLOB. ifxus_free_slob() retourne FALSE en cas d'erreur, et sinon TRUE.
ifxus_open_slob
Description
int ifxus_open_slob ( long bid, int mode)ifxus_open_slob() ouvre un objet SLOB. bid est un identifiant d'objet SLOB. Les modes valides sont : 1 = LO_RDONLY, 2 = LO_WRONLY, 4 = LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 = LO_NOBUFFER -> ou une combinaison des valeurs précédentes. ifxus_open_slob() retourne FALSE en cas d'erreur, et sinon, l'identifiant du nouvel objet.
ifxus_read_slob
Description
int ifxus_read_slob ( long bid, long nbytes)ifxus_read_slob() lit nbytes octets de l'objet SLOB bid. bid est un identifiant d'objet SLOB existant, et nbytes est le nombre d'octets à lire. ifxus_read_slob() retourne FALSE en cas d'erreur, et sinon, une chaîne de caractères.
ifxus_seek_slob
Description
int ifxus_seek_slob ( long bid, int mode, long offset)ifxus_seek_slob() modifie le fichier courant, ou la position du pointeur de fichier, pour un objet SLOB ouvert. bid est un identifiant d'objet SLOB. Les modes valides sont : 0 = LO_SEEK_SET, 1 = LO_SEEK_CUR, 2 = LO_SEEK_END et offset est un octet d'offset. ifxus_seek_slob() retourne FALSE en cas d'erreur, et sinon, la position du pointeur de fichier.
ifxus_tell_slob
Description
int ifxus_tell_slob ( long bid)ifxus_tell_slob() retourne le fichier courant, ou la position courante d'un objet SLOB ouvert. bid est un identifiant d'objet SLOB. ifxus_tell_slob() retourne FALSE en cas d'erreur, et sinon, la position du pointeur de fichier.
ifxus_write_slob
XLV. InterBase
Interbase est une base de données populaire, créée par Borland/Inprise. Pour plus d'informations sur Interbase, allez à http://www.interbase.com/. Par ailleurs, Interbase vient de rejoindre le mouvement Open Source!
- Table des matières
- ibase_blob_add -- Add data into created blob
- ibase_blob_cancel -- Cancel creating blob
- ibase_blob_close -- Close blob
- ibase_blob_create -- Create blob for adding data
- ibase_blob_echo -- Output blob contents to browser
- ibase_blob_get -- Get len bytes data from open blob
- ibase_blob_import -- Create blob, copy file in it, and close it
- ibase_blob_info -- Return blob length and other useful info
- ibase_blob_open -- Open blob for retrieving data parts
- ibase_close -- Ferme une connexion à une base de données Interbase.
- ibase_commit -- Valide une transaction
- ibase_connect -- Ouvre une connexion à une base de données Interbase.
- ibase_errmsg -- Retourne un message d'erreur
- ibase_execute -- Exécute une requête préparée.
- ibase_fetch_object -- Lit une ligne dans une base Interbase dans un objet.
- ibase_fetch_row -- Lit une ligne dans une base Interbase
- ibase_field_info -- Lit les informations sur un champs
- 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_num_fields -- Retourne le nombre de colonnes dans un résultat.
- ibase_pconnect -- Ouvre une connexion persistante à une base de données Interbase.
- ibase_prepare -- Prépare une requête pour lier les paramètres et l'éxécuter ultérieurement.
- ibase_query -- Exécute une requête sur une base Interbase
- ibase_rollback -- Annule une transaction
- ibase_timefmt -- Fixe le format de date pour les prochaines requêtes.
- ibase_trans -- Prépare une transaction
ibase_blob_add
Description
int ibase_blob_add ( int blob_id, string data)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_cancel
Description
int ibase_blob_cancel ( int blob_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_close
Description
int ibase_blob_close ( int blob_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_create
Description
int ibase_blob_create ( [int link_identifier])
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_echo
Description
int ibase_blob_echo ( string blob_id_str)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_get
Description
string ibase_blob_get ( int blob_id, int len)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_import
Description
string ibase_blob_import ( [int link_identifier, int file_id])
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_info
Description
object ibase_blob_info ( string blob_id_str)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_blob_open
Description
int ibase_blob_open ( string blob_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ibase_close
Description
int ibase_close ( [resource connection_id])ibase_close() ferme une connexion à une base de données Interbase. Cette fonction prend comme argument l'identifiant de connexion connection_id retourné par ibase_connect(). Si connection_id est omis, la dernière connexion ibase est fermée. Les transactions par défaut sont validées et les autres sont annulées.
ibase_commit
Description
int ibase_commit ( [resource link_identifier, resource trans_number])ibase_commit() valide la transaction trans_number, qui a été préparée avec ibase_trans().
ibase_connect
Description
resource ibase_connect ( string database [, string username [, string password [, string charset [, int buffers [, int dialect [, string role]]]]]])ibase_connect() établit une connexin avec un serveur InterBase. database doit être un chemin valide jusqu'à un fichier de base de donnés sur le serveur sur lequel il résde. Si le serveur est distant, il faut le préfixer avec un nom d'hôte 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) ou 'hostname@' (IPX/SPX), en fonction du protocole de communication utilisé. username et password peuvent être spécifié dans les directives de configuration du PHP ibase.default_user et ibase.default_password. charset est le jeu de caractère par défaut de la base. buffers est le nombre de buffer de base à allouer pour le cache serveur. S'il est passé à 0 ou omis, le serveur choisira de lui-même. 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.
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.
Note : buffers a été ajouté en PHP 4-RC2.
Note : dialect a été ajouté en PHP 4-RC2. Il n'est opérationnel qu'avec les versions InterBase 6 et plus récentes.
Note : role a été ajouté en PHP 4-RC2. Il n'est opérationnel qu'avec les versions InterBase 5 et plus récentes.
Voir aussi ibase_pconnect().
ibase_errmsg
Description
string ibase_errmsg ( void)ibase_errmsg() retourne une chaîne contenant les messages d'erreurs.
ibase_execute
Description
resource ibase_execute ( int query [, int bind_args])ibase_execute() exécute une requête préparée (et éventuellement liée) par ibase_prepare(). ibase_execute() est beaucoup plus efficace que ibase_query(), si vous effectuez plusieurs fois la même requête, en ne changeant que quelques paramètres.
ibase_fetch_object
Description
object ibase_fetch_object ( resource result_id)ibase_fetch_object() lit une ligne dans une base Interbase et la place dans un pseudo objet. ibase_fetch_object() prend comme argument l'identifiant de résultat result_id obtenu de ibase_query() ou ibase_execute().
<php
$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
print $row->email . "\n";
}
ibase_close($dbh);
?> |
Voir aussi ibase_fetch_row().
ibase_fetch_row
Description
array ibase_fetch_row ( resource result_identifier)ibase_fetch_row() retourne la prochaine ligne spécifiée dans le résultat obtenu de ibase_query().
ibase_field_info
Description
array ibase_field_info ( resource result, int field_number)ibase_field_info() retourne un tableau contenant les informations sur le champs numéro field_number après une requête de SELECT. Le tableau contient les index name (nom), alias, relation, length (taille), type.
<?php
// helio@helio.com.br 08-Dec-2000 02:53
$rs=ibase_query("Select * from unetable");
$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";
}
?> |
ibase_free_query
Description
int ibase_free_query ( resource query)ibase_free_query() libère la mémoire réservée par une requête préparée par ibase_prepare().
ibase_free_result
Description
int ibase_free_result ( resource result_identifier)ibase_free_result() libère les ressources liées au résultat result_identifier.
ibase_num_fields
Description
int ibase_num_fields ( resource result_id)ibase_num_fields() retourne le nombre de colonnes dans un résultat.
<?php
$dbh = ibase_connect ($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
if (ibase_num_fields($sth) > 0) {
while ($row = ibase_fetch_object ($sth)) {
print $row->email . "\n";
}
} else {
die ("Aucun résultat dans votre requête");
}
ibase_close ($dbh);
?> |
Note : ibase_timefmt() ne fonctionne pas encore sous PHP4.
ibase_pconnect
(PHP 3>= 3.0.6, PHP 4 )
ibase_pconnect -- Ouvre une connexion persistante à une base de données Interbase.Description
resource ibase_pconnect ( string database [, string username [, string password [, string charset [, int buffers [, int dialect [, string role]]]]]])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 (peristante) 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'.
Note : buffers a été ajouté en PHP 4-RC2.
Note : dialect a été ajouté en PHP 4-RC2. Il n'est opérationnel qu'avec les versions InterBase 6 et plus récentes.
Note : role a été ajouté en PHP 4-RC2. Il n'est opérationnel qu'avec les versions InterBase 5 et plus récentes.
Voir aussi ibase_connect() pour plus de détails sur les arguments de cette fonction.
ibase_prepare
(PHP 3>= 3.0.6, PHP 4 )
ibase_prepare -- Prépare une requête pour lier les paramètres et l'éxécuter ultérieurement.Description
int ibase_prepare ( [resource link_identifier, string query])ibase_prepare() prépare une requête pour l'éxécuter
ibase_query
Description
resource ibase_query ( [resource link_identifier, string query [, int bind_args]])ibase_query() exécute une requête sur une base Interbase, et retourne un identifiant de résultat, à utiliser avec ibase_fetch_row(), ibase_free_result() et/ou ibase_free_query().
Note : Bien que ces fonctions supportent la liaison de variables avec des paramètres de requêtes, il n'y a pas d'intérêt spécial à les utiliser. Pour des exemples grandeur réelle, voyez ibase_prepare() et ibase_execute().
ibase_rollback
Description
int ibase_rollback ( [resource link_identifier, resource trans_number])ibase_rollback() annule la transaction trans_number qui a été préparée avec ibase_trans().
ibase_timefmt
Description
int ibase_timefmt ( string format [, int columntype])ibase_timefmt() fixe le format des colonnes de type dates, heure et timestamp, retournées par les requêtes. En interne, les colonnes sont formatées par la fonction C strftime() : reportez-vous à sa documentation pour connaître la structure de la chaîne de format. columntype est une des constantes suivantes : IBASE_TIMESTAMP, IBASE_DATE ou IBASE_TIME. Si elle est omise, la valeur par défaut est IBASE_TIMESTAMP, pour compatibilité ascendante.
<?php
// Les colonnes TIME de InterBase 6 seront retournées avec
// la forme '05 heures 37 minutes'.
ibase_timefmt("%H heures %M minutes", IBASE_TIME);
?> |
Vous pouvez aussi modifier les formats par défaut avec les directives PHP ibase.timestampformat, ibase.dateformat et ibase.timeformat.
Note : columntype a été ajouté en PHP 4.0. Il n'a aucun sens jusqu'à InterBase version 6 et plus récent.
Note : Une modification incompatible avec l'existant est apparue en PHP 4.0 lorsque la directive PHP ibase.timeformat a été renommée en ibase.timestampformat et les directives ibase.dateformat et ibase.timeformat ont été ajoutée, de manière à les adapter à leur fonction.
ibase_trans
XLVI. Ingres II
Ces fonctions permettent l'accès à un serveur de base de données Ingres II.
Pour pouvoir utiliser ces fonctions, vous devez compiler PHP avec le support Ingres, en utilisant l'option --with-ingres. Ceci nécessite les fichiers de bibliothèque de l'en-tête d'Open API qui sont inclus dans Ingres II. Si la variable d'environnement II_SYSTEM n'est pas correctement initialisée, vous devrez utiliser --with-ingres=REP pour spécifier le répertoire où a été installé Ingres.
Lorsque cette extension est utilisée avec Apache, si Apache ne démarre pas et émet l'erreur "PHP Fatal error: Unable to start ingres_ii module in Unknown on line 0", assurez-vous que la variable d'environnement II_SYSTEM est correctement initialisée. Il suffit souvent d'ajouter "export II_SYSTEM="/home/ingres/II" dans le script qui démarre Apache, juste avant le lancement de httpd.
Note : Si vous avez déjà utilisé des extensions PHP permettant l'accès à d'autres serveurs de bases de données, notez qu'Ingres n'accepte pas de requêtes et/ou de transactions concurrentes sur la même connexion, et donc vous ne trouverez aucun identifiant de résultat ou de transaction dans cette extension. Le résultat d'une requête doit être traité avant d'envoyer une autre requête, et une transaction doit être validée ("commit") ou annulée ("roll back") avant de pouvoir en ouvrir une nouvelle (l'ouverture de transaction est fait automatiquement à l'envoi de la première requête).
- Table des matières
- ingres_autocommit -- Active ou désactive le mode autocommit.
- ingres_close -- Ferme une connexion à un serveur Ingres.
- ingres_commit -- Valide une transaction.
- ingres_connect -- Ouvre une connexion à un serveur Ingres.
- ingres_fetch_array -- Récupère une ligne de résultat dans un tableau.
- ingres_fetch_object -- Récupère une ligne de résultat dans un objet.
- ingres_fetch_row -- Récupère une ligne de résultat dans un tableau énuméré.
- ingres_field_length -- Retourne la taille d'un champ.
- ingres_field_name -- Retourne le nom d'un champ dans le résultat d'une requête.
- ingres_field_nullable -- Teste si un champ est annulable.
- ingres_field_precision -- Retourne la précision d'un champ.
- ingres_field_scale -- Retourne l'échelle d'un champ.
- ingres_field_type -- Retourne le type d'un champ dans le résultat d'une requête.
- ingres_num_fields -- Retourne le nombre de champs renvoyés par la dernière requête.
- ingres_num_rows -- Retourne le nombre de lignes affectées ou retournées par la dernière requête.
- ingres_pconnect -- Ouvre une connexion persistante à un serveur Ingres.
- ingres_query -- Envoie une requête SQL à un serveur Ingres II.
- ingres_rollback -- Annule une transaction.
ingres_autocommit
Description
boolean ingres_autocommit ( [resource link])ingres_autocommit() est appelée juste avant l'ouverture d'une transaction (avant le premier appel à ingres_query() ou juste après un appel à ingres_rollback() ou ingres_autocommit()) pour changer l'état du mode "autocommit" (ce mode fonctionne comme une bascule). Lorsque le script débute le mode autocommit est toujours désactivé.
Lorsque le mode autocommit est activé, chaque requête est automatiquement commise (validée) par le serveur, comme si ingres_commit() était appelée après chaque appel à ingres_query().
Voir aussi ingres_query(), ingres_rollback() et ingres_commit().
ingres_close
Description
boolean ingres_close ( [resource link])ingres_close() retourne TRUE en cas de succès, et FALSE sinon.
ingres_close() ferme la connexion au serveur Ingres associée au lien spécifié. Si le paramètre link n'est pas spécifié, le dernier lien ouvert est utilisé.
Habituellement l'appel à ingres_close() n'est pas nécessaire, car il ne ferme pas les connexions persistantes, et toutes les connexions non-persistantes sont automatiquement fermées à la fin du script.
Voir aussi ingres_connect() et ingres_pconnect().
ingres_commit
Description
boolean ingres_commit ( [resource link])ingres_commit() valide la transaction ouverte, ce qui rend permanentes toutes les modifications faites sur la base de données au cours de cette transaction
Ceci ferme la transaction. Une nouvelle transaction peut être ouverte en envoyant une requête à l'aide de ingres_query().
Vous pouvez aussi faire en sorte que le serveur valide automatiquement les changements après chaque requête en appelant ingres_autocommit() avant l'ouverture d'une transaction.
Voir aussi ingres_query(), ingres_rollback() et ingres_autocommit().
ingres_connect
Description
resource ingres_connect ( [string database [, string username [, string password]]])ingres_connect() retourne une ressource représentant un lien Ingres II en cas de succès, et FALSE sinon.
ingres_connect() établit une connexion avec la base de données Ingres désignée par database, qui suit la syntaxe [node_id::]dbname[/svr_class].
Si certains paramétres sont manquants, ingres_connect() utilise les valeurs de ingres.default_database, ingres.default_user et ingres.default_password indiquées dans php.ini.
La connexion est fermée lorsque le script se termine ou en cas d'appel à ingres_close().
Toutes les autres fonctions Ingres utilisent le dernier lien ouvert comme lien par défaut, il n'est donc nécessaire de conserver la valeur de retour qu'en cas d'utilisation de plus d'un lien en même temps.
Voir aussi ingres_pconnect() et ingres_close().
ingres_fetch_array
Description
array ingres_fetch_array ( [int result_type [, resource link]])ingres_fetch_array() renvoie un tableau correspondant à la ligne récupérée, ou FALSE s'il n'y a plus de ligne à récupérer.
Cette fonction est une version améliorée de ingres_fetch_row(). En plus de stocker les données dans un tableau à indices numériques, elle peut aussi les enregistrer dans un tableau associatif, en utilisant les noms des champs comme indices.
Si plusieurs colonnes ont le même nom, la dernière colonne aura la priorité. Pour accéder aux autres colonnes du même nom, vous devez utiliser l'index numérique, ou faire un alias pour chaque colonne.
<?php ingres_query(select t1.f1 as foo t2.f1 as bar from t1, t2); $result = ingres_fetch_array(); $foo = $result["foo"]; $bar = $result["bar"]; ?> |
result_type peut valoir II_NUM pour un tableau à indices numériques, II_ASSOC pour un tableau associatif, ou II_BOTH (défaut) pour un tableau mixte (accessible selon les 2 méthodes).
Du point de vue de la rapidité, cette fonction est identique à ingres_fetch_object(), et presque aussi rapide que ingres_fetch_row() (la différence est insignifiante).
Exemple 1. Exemple pour ingres_fetch_array()
|
Voir aussi ingres_query(), ingres_num_fields(), ingres_field_name(), ingres_fetch_object() et ingres_fetch_row().
ingres_fetch_object
Description
object ingres_fetch_object ( [int result_type [, resource link]])ingres_fetch_object() renvoie un objet correspondant à la ligne (tuple) récupérée, ou FALSE s'il n'y a plus de ligne à récupérer.
ingres_fetch_object() est similaire à ingres_fetch_array(), avec une différence : la valeur de retour est un objet et non un tableau. Indirectement, cela signifie qu'il n'est possible d'accéder aux données qu'avec les noms des champs, et pas avec leur numéro (les nombres ne sont pas des noms valides de propriété).
Le paramètre optionnel result_type est une constante qui peut prendre les valeurs II_ASSOC, II_NUM, et II_BOTH (par défaut).
Du point de vue de la rapidité, cette fonction est identique à ingres_fetch_array(), et presque aussi rapide que ingres_fetch_row() (la différence est insignifiante).
Voir aussi ingres_query(), ingres_num_fields(), ingres_field_name(), ingres_fetch_array() et ingres_fetch_row().
ingres_fetch_row
Description
array ingres_fetch_row ( [resource link])ingres_fetch_row() renvoie un tableau correspondant à la ligne récupérée, ou FALSE s'il n'y a plus de ligne à récupérer. La ligne est stockée dans un tableau à indices numériques, le premier champs étant à l'indice 1.
Les appels successifs à ingres_fetch_row() retournent les lignes suivantes du résultat, ou FALSE s'il n'y a plus de lignes.
Voir aussi ingres_num_fields(), ingres_query(), ingres_fetch_array() et ingres_fetch_object().
ingres_field_length
Description
int ingres_field_length ( int index [, resource link])ingres_field_length() retourne la taille d'un champ. Il s'agit du nombre d'octets utilisés par le serveur pour stocker ce champ. Pour plus d'informations, voir le Guide de l'utilisateur d'Ingres/OpenAPI - Annexe C.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_field_name
Description
string ingres_field_name ( int index [, resource link])ingres_field_name() retourne le nom d'un champ dans le résultat d'une requête, ou FALSE en cas d'échec.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_field_nullable
Description
boolean ingres_field_nullable ( int index [, resource link])ingres_field_nullable() retourne TRUE si le champ peut recevoir la valeur NULL et FALSE dans le cas contraire.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_field_precision
Description
int ingres_field_precision ( int index [, resource link])ingres_field_precision() retourne la précision d'un champ. Cette valeur est utilisée uniquement pour les types de données SQL décimal, float et money. Pour plus d'informations, voir le Guide de l'utilisateur d'Ingres/OpenAPI - Annexe C.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_field_scale
Description
int ingres_field_scale ( int index [, resource link])ingres_field_scale() retourne l'échelle (scale) d'un champ. Cette valeur n'est utilisée que pour le type de données SQL décimal. Pour plus d'informations, voir le Guide de l'utilisateur d'Ingres/OpenAPI - Annexe C.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_field_type
Description
string ingres_field_type ( int index [, resource link])ingres_field_type() retourne le type d'un champ dans le résultat d'une requête, ou FALSE en cas d'échec. Exemples de types renvoyés par cette fonction : "IIAPI_BYTE_TYPE", "IIAPI_CHA_TYPE", "IIAPI_DTE_TYPE", "IIAPI_FLT_TYPE", "IIAPI_INT_TYPE", "IIAPI_VCH_TYPE". Certains de ces types correspondent à plus d'un type SQL, selon la taille du champ (voir ingres_field_length()). Par exemple "IIAPI_FLT_TYPE" peut être un float4 ou un float8. Pour plus d'informations, voir le Guide de l'utilisateur d'Ingres/OpenAPI - Annexe C.
index est le numéro du champ et doit être compris entre 1 et la valeur donnée par ingres_num_fields().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_num_fields
Description
int ingres_num_fields ( [resource link])ingres_num_fields() retourne le nombre de champs du résultat renvoyé par le serveur Ingres après un appel à ingres_query().
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_num_rows
(PHP 4 >= 4.0.2)
ingres_num_rows -- Retourne le nombre de lignes affectées ou retournées par la dernière requête.Description
int ingres_num_rows ( [resource link])Pour les requêtes DELETE, INSERT, UPDATE ingres_num_rows() retourne le nombre de lignes (tuples) affectées par la requête. Pour les autres requêtes, ingres_num_rows() retourne le nombre de lignes du résultat de la requête.
Note : Cette fonction est conçue principalement pour obtenir le nombre de tuples modifiés dans la base de données. Si cette fonction est appelée avant d'utiliser ingres_fetch_array(), ingres_fetch_object() ou ingres_fetch_row(), le serveur efface les données du résultat et le script ne pourra plus les obtenir.
Il faut dans ce cas récupérer les données du résultat en utilisant une de ces 3 fonctions dans une boucle jusqu'à ce qu'elle renvoie FALSE, ce qui indique qu'il n'y a plus de résultats à récupérer.
Voir aussi ingres_query(), ingres_fetch_array(), ingres_fetch_object() et ingres_fetch_row().
ingres_pconnect
Description
resource ingres_pconnect ( [string database [, string username [, string password]]])ingres_pconnect() retourne une ressource représentant un lien (link) Ingres II en cas de succès, et FALSE sinon.
Voir ingres_connect() pour le détail des paramètres et des exemples. Il n'y a que 2 différences entre ingres_pconnect() et ingres_connect() : Tout d'abord, à la connexion, la fonction cherche un lien persistant déjà ouvert avec les mêmes paramètres. Si un tel lien est trouvé, un identificateur pour ce lien est retourné au lieu d'établir une nouvelle connexion. Ensuite, la connexion vers le serveur Ingres n'est pas fermée lorsque le script se termine. En fait, le lien reste ouvert pour pouvoir être réutilisé (ingres_close() ne ferme pas les liens établis avec ingres_pconnect()). C'est pourquoi ce type de lien est dit 'persistant'.
Voir aussi ingres_connect() et ingres_close().
ingres_query
Description
boolean ingres_query ( string query [, resource link])ingres_query() retourne TRUE en cas de succès, et FALSE sinon.
ingres_query() envoie la requête query au serveur Ingres. La requête doit être valide (voir le guide de référence SQL pour Ingres).
La requête s'ajoute à la transaction en cours. S'il n'y a pas de transaction ouverte, ingres_query() en ouvre une nouvelle. Pour fermer une transaction, vous pouvez soit appeler ingres_commit() pour valider les changements effectués sur la base de données ou ingres_rollback() pour les annuler. Lorsque le script se termine, toute transaction ouverte est annulée (par appel à ingres_rollback()). Vous pouvez aussi utiliser ingres_autocommit() avant d'ouvrir une transaction pour que chaque requête SQL soit validée immédiatement et automatiquement.
Certains types de requêtes SQL ne peuvent pas être envoyés par ingres_query() :
CLOSE (voir ingres_close()).
COMMIT (voir ingres_commit()).
CONNECT (voir ingres_connect()).
DISCONNECT (voir ingres_close()).
get dbevent
PREPARE TO COMMIT
ROLLBACK (voir ingres_rollback()).
savepoint
SET AUTOCOMMIT (voir ingres_autocommit()).
Les requêtes relatives aux curseurs ne sont pas supportées.
Voir aussi ingres_fetch_array(), ingres_fetch_object(), ingres_fetch_row(), ingres_commit(), ingres_rollback() et ingres_autocommit().
ingres_rollback
Description
boolean ingres_rollback ( [resource link])ingres_rollback() annule (roll back) la transaction ouverte, ce qui annule les modifications faites sur la base de données au cours de cette transaction.
Ceci ferme la transaction. Une nouvelle transaction peut être ouverte en envoyant une requête à l'aide de ingres_query().
Voir aussi ingres_query(), ingres_commit() et ingres_autocommit().
XLVII. IRC
- Table des matières
- ircg_channel_mode -- Modifie les flags du canal
- ircg_disconnect -- Ferme la connexion avec un serveur
- ircg_fetch_error_msg -- Returns the error from previous ircg operation
- ircg_get_username -- Get username for connection
- ircg_html_encode -- Prépare l'affichage pour le HTML
- ircg_ignore_add -- Ajoute un utilisateur sur la liste des utilisateurs indésirables
- ircg_ignore_del -- Supprime un utilisateur de la liste des utilisateurs indésirables
- ircg_is_conn_alive -- Vérifie l'état de la connexion
- ircg_join -- Rejoint un canal IRC
- ircg_kick -- Expulse un utilisateur d'un canal
- ircg_lookup_format_messages -- Sélectionne un format d'affichage pour les messages IRC
- ircg_msg -- Envoie un message à un canal ou un utilisateur
- ircg_nick -- Change de nom sur le serveur
- ircg_nickname_escape -- Encode special characters in nickname to be IRC-compliant
- ircg_nickname_unescape -- Decodes encoded nickname
- ircg_notice -- Envoie une note (notice) à un utilisateur
- ircg_part -- Quitte le canal
- ircg_pconnect -- Connecte à un serveur IRC
- ircg_register_format_messages -- Enregistre un nouveau format d'affichage des messages IRC
- ircg_set_current -- Prépare la connexion courante pour l'affichage
- ircg_set_file -- Set logfile for connection
- ircg_set_on_die -- Set hostaction to be execute when connection dies
- ircg_topic -- Modifie le sujet (topic) d'un canal
- ircg_whois -- Requiert les informations sur un utilisateur
ircg_channel_mode
Description
boolean ircg_channel_mode ( resource connection, string channel, string mode_spec, string nick)ircg_channel_mode() modifie les flags du canal channel, sur le serveur channel. Les nouveaux flags sont passés dans le paramètre mode_spec et sont appliqués à l'utilisateur nick.
Les flags sont activés ou désactivés en spécifiant un caractère de mode et en le préfixant par un caractère plus (+) ou un caractère moins (-). Par exemple, le mode opérateur est donné à un utilisateur avec la syntaxe '+o' et retiré au même utilisateur avec la syntaxe '-o', passé dans le paramètre mode_spec.
ircg_disconnect
Description
boolean ircg_disconnect ( resource connection, string reason)ircg_disconnect() ferme la connexion ouverter précédemment avec un serveur grâce à la fonction ircg-pconnect(), et représentée par connection.
Voir aussi ircg_pconnect().
ircg_fetch_error_msg
Description
array ircg_fetch_error_msg ( resource connection)ircg_fetch_error_msg() returns the error from the last called ircg function.
Note : Errorcode is stored in first array element, errortext in second.
ircg_get_username
Description
string ircg_get_username ( int connection)Function ircg_get_username() returns the username for specified connection connection. Returns FALSE if connection died or is not valid.
ircg_html_encode
ircg_ignore_add
Description
boolean ircg_ignore_add ( resource connection, string nick)ircg_ignore_add() ajoute l'utilisateur nick dans votre liste d'utilisateurs indésirables, sur le serveur connection. Tous les messages qui vous sont envoyés par cet utilisateur seront ignorés.
Voir aussi ircg_ignore_del().
ircg_ignore_del
(PHP 4 >= 4.0.5)
ircg_ignore_del -- Supprime un utilisateur de la liste des utilisateurs indésirablesDescription
boolean ircg_ignore_del ( resource connection, string nick)ircg_ignore_del() supprime l'utilisateur nick de la liste des utilisateurs indésirables, sur le serveur connection.
Voir aussi ircg_ignore_add().
ircg_is_conn_alive
Description
boolean ircg_is_conn_alive ( resource connection)ircg_is_conn_alive() retourne TRUE si la connexion connection est toujours active et fonctionnelle, et FALSE si la connexion n'est plus disponible.
ircg_join
Description
boolean ircg_join ( resource connection, string channel)ircg_join() rejoint le canal channel sur le serveur sur le serveur représenté par connection.
ircg_kick
Description
boolean ircg_kick ( resource connection, string channel, string nick, string reason)ircg_kick() expulse l'utilisateur nick du canal channel sur le serveur connection. Le paramètre reason doit contenir une brève explication de la raison de cette expulsion.
ircg_lookup_format_messages
(PHP 4 >= 4.0.5)
ircg_lookup_format_messages -- Sélectionne un format d'affichage pour les messages IRCDescription
boolean ircg_lookup_format_messages ( string name)ircg_lookup_format_messages() sélectionne un format d'affichage pour les messages et les événements. Les formats peuvent être prédéfinis avec la fonction ircg_register_format_messages(). Un format par défaut, appelé ircg est toujours disponible.
Voir aussi ircg_register_format_messages().
ircg_msg
Description
boolean ircg_msg ( resource connection, string recipient, string message [, boolean suppress])ircg_msg() envoie le message message à l'utilisateur ou au canal recipient, sur le serveur connection. Un destinataire recipient commençant par # ou & représente un canal IRC, et sinon, un utilisateur.
En donnant la valeur TRUE au paramètre suppress, vous éviterez que vos propres messages soient affichés sur votre connexion connection.
ircg_nick
Description
boolean ircg_nick ( resource connection, string nick)ircg_nick() change le nom (nick) que vous portez sur la connexion connection, si ce nom n'est pas pris.
ircg_nick() retourne TRUE en cas de succès, et FALSE
ircg_nickname_escape
Description
string ircg_nickname_escape ( string nick)Function ircg_nickname_escape() returns a decoded nickname specified by nick wich is IRC-compliant.
See also: ircg_nickname_unescape()
ircg_nickname_unescape
Description
string ircg_nickname_unescape ( string nick)Function ircg_nickname_unescape() returns a decoded nickname, which is specified in nick.
See also: ircg_nickname_escape()
ircg_notice
Description
boolean ircg_notice ( resource connection, string , string message)ircg_notice() envoie le message message à l'utilisateur nick sur le serveur connection. Consultez votre documentation IRC pour connaître la différence exacte entre un message MSG et une note NOTICE.
ircg_part
Description
boolean ircg_part ( resource connection, string channel)ircg_part() quitte le canal channel sur le serveur sur le serveur représenté par connection.
ircg_pconnect
Description
resource ircg_pconnect ( string username [, string server_ip [, int server_port [, string msg_format [, array ctcp_messages [, array user_settings]]]]])ircg_pconnect() essaie d'établir une connexion avec le serveur IRC server_ip, et retourne une ressource de connexion pour utilisation ultérieure.
Le seul paramètre obligatoire est username, qui représente le nick (nom d'utilisateur en IRC) initial. server_ip et server_port sont optionnels, et par défaut, valent respectivement 127.0.0.1 (hôte local) et 6667.
Note : Actuellement, le paramètre server_ip n'effectue aucune résolution de nom, et n'accepte que les IP au format numérique.
Vous pouvez personnaliser l'affichage des messages IRC et les événements qui s'y rattachent avec les formats de messages, générés par la fonction ircg_register_format_messages(), en spécifiant le format dans msg_format.
ctcp_messages
user_settings
Voir aussi ircg_disconnect(), ircg_is_conn_alive() et ircg_register_format_messages().
ircg_register_format_messages
(PHP 4 >= 4.0.5)
ircg_register_format_messages -- Enregistre un nouveau format d'affichage des messages IRCDescription
boolean ircg_register_format_messages ( string name, array messages)ircg_register_format_messages() vous permet de personnaliser l'affichage de vos messages IRC. Vous pouvez même enregistrer plusieurs formats et passer de l'un à l'autre à la volée avec ircg_lookup_format_messages().
Message public brut
Message privé reçu
Message privé envoyé
Un utilisateur quitte le canal
Un utilisateur rejoint le canal
Un utilisateur est expulsé du canal
Le sujet du canal est modifié
Erreur
Erreur fatale
Rejoint la fin de la liste (??? : Join list end)
Se quitte soi-même (??? : Self part)
Un utilisateur s'expulse lui-même
Un utilisateur quitte sa connexion
Début de regroupement en masse
Elément de regroupement en masse
Fin de regroupement en masse
Whois utilisateur
Whois serveur
Whois inactif
Whois canal
Fin de whois
Changement de statut Voice pour un utilisateur
Changement de statu d'opérateur pour un utilisateur
Liste d'utilisateurs indésirables
Fin de liste d'utilisateurs indésirables
%f - origine
%t - destination
%c - canal
%r - message brut
%m - message encodé
%j - message encodé js
1 - encodage mod
2 - nickname decode
Voir aussi ircg_lookup_format_messages().
ircg_set_current
Description
boolean ircg_set_current ( resource connection)ircg_set_current() sélectionne la connexion courante pour l'affichage dans le contexte d'exécution courant. Tous les messages envoyés par le serveur représenté par connection seront recopiés et envoyés à la sortie standard, avec le format standard, ou bien la chaîne de format spécifiée par la fonction ircg_register_format_messages() et créée par ircg_lookup_format_messages().
Voir aussi ircg_register_format_messages() et ircg_lookup_format_messages().
ircg_set_file
Description
bool ircg_set_file ( int connection, string path)Function ircg_set_file() specifies a logfile path in which all output from connection connection will be logged. Returns TRUE on success, otherwise FALSE.
ircg_set_on_die
Description
bool ircg_set_on_die ( int connection, string host, int port, string data)In case of the termination of connection connection IRCG will connect to host at port (Note: host must be an IPv4 address, IRCG does not resolve host-names due to blocking issues), send data to the new host connection and will wait until the remote part closes connection. This can be used to trigger a php script for example.
ircg_topic
Description
boolean ircg_topic ( resource connection, string channel, string new_topic)ircg_topic() change le sujet du canal de channel en new_topic, sur le serveur connection.
ircg_whois
XLVIII. Java
Il y a deux moyens de connecter PHP et Java : soit en intégrant Java directement dans PHP, ce qui est la solution la plus stable et la plus efficace, ou en intégrant PHP dans un environnement de Servlet Java. La première solution est fournie par cette extension Java, et la dernière par le module SAPI qui s'interface avec un serveur de Servlet.
PHP 4 ext/java fournit un moyen simple mais efficace pour invoquer et créer des objets Java, depuis PHP. Une machine virtuelle est créée via JNI, et le tout fonctionne avec des processus fils. Les instructions d'installation pour cette extension sont sont disponibles dans le fichier : php4/ext/java/README.
Exemple 1. Exemple avec Java
|
Exemple 2. Exemple AWT
|
new Java() crée une nouvelle instance d'une classe, si un constructeur valable est disponible. Si aucun paramètre n'est passé, et le constructeur par défaut est utile pour accéder à ces classes telles que "java.lang.System", qui fournissent leur fonctionnalités via des méthodes statiques.
Lors de l'accès aux membres d'une instance, PHP commencera par rechercher les membres Bean, puis les champs publics. En d'autres termes, "print $date.time" sera d'abord résolu par "$date.getTime()", puis par "$date.time";
Les membres statiques et d'instance sont accessibles avec la même syntaxe. De plus, si un objet est de type "java.lang.Class", les membres statiques de la classe (champs et méthodes) sont accessibles.
Les exceptions sont transformées en alertes PHP, et résultat NULL. Les alertes peuvent être supprimées en préfixant l'appel par l'opérateur >. Les fonctions suivantes peuvent être utilisées pour lire et effacer la dernière erreur remontée :
Les surchargements de fonctions sont des problèmes épineux, étant donné les différences de type de valeurs entre les deux langages. L'extension Java de PHP utilise une métrique simple mais efficace pour déterminer la meilleur fonction à utiliser.
De plus, les noms de méthodes ne sont pas sensibles à la casse en PHP, ce qui augmente le nombre de conflits potentiels.
Une fois qu'une méthode est sélectionnée, les paramètres sont transtypés, avec une perte d'information potentielle non négligeable (par exemple, les nombres à virgules flottante en double précisions seront convertis en booléen).
Traditionnellement en PHP, les tableaux et les tables de hashage peuvent être interchangées, et fonctionnent de la même façon. Notez que les tables de hashage de PHP ne peuvent être indexées qu'avec des entiers ou des chaînes, et que le type primitif de tableau de Java ne peut comporter de trous dans les index. Notez aussi que les valeurs sont passées par valeur, ce qui peut être coÛteux en mémoire et en temps.
L'interface PHP4 sapi/servlet est construite sur un mécanisme défini par l'extension Java, qui permet à PHP d'être exécuté comme une servlet. L'avantage immédiat d'un point de vue PHP est que les serveurs web qui supportent les servlets gèrent rigoureusement les machines virtuelles. Les instructions d'installation du module Servlet SAPI sont disponibles dans le fichier php4/sapi/README. Notes:
Bien que ce code soit prévu pour fonctionner sur n'importe quel serveur à Servlet, il n'a été testé qu'avec le module Apache Jakarta/tomcat (jusqu'à aujourd'hui). Les remontées de bugs, les réussites et les patches nécessaires pour faire fonctionner ce code sur d'autres serveurs sont fortement encouragés!
PHP a l'habitude de changer le dossier de travail. Le serveur SAPI/Servlet le changera à nouveau, mais tant que PHP fonctionnera, le moteur de servlet ne pourra pas charger de classes dans le CLASSPATH, si le dossier est spécifié avec un chemin relatif, ou ne pourra pas trouver le dossier d'administration et de compilation des tâches JSP.
- Table des matières
- java_last_exception_clear -- Efface la dernière exception Java
- java_last_exception_get -- Lit la dernière exception Java
java_last_exception_clear
java_last_exception_get
Description
exception java_last_exception_get ( void)L'exemple ci-dessous montre l'utilisation du gestionnaire d'exceptions java :
Exemple 1. Gestionnaire d'exception Java
|
XLIX. LDAP
Introduction à LDAP
LDAP est l'acronyme de Lightweight Directory Access Protocol, c'est à dire Protocole Léger d'Accès aux Dossiers. C'est un protocole utilisé pour accéder à des "serveurs de dossiers", des serveurs qui gèrent les informations de manière hiérarchique.
Le concept est similaire à la structure de votre disque dur, hormis le fait que la racine s'appelle ici : "The world" (le monde), et que les dossiers du premier niveau sont assimilés à des pays. Les niveaux inférieurs de la structure contiennent des entrées de sociétés, d'organisations ou de lieux tandis que les niveaux encore inférieurs sont des gens, voire des équipements ou des documents.
Pour accéder à un fichier sur votre disque, vous devez utiliser la syntaxe suivante :
/usr/local/myapp/docs
Le slash indique une division de la référence, et la séquence est lue de gauche à droite.
Avec tous les détails, une référence LDAP s'appelle un "nom distingué" ("distinguished name"), appelé aussi "nd" ("dn" en anglais). Par exemple :
cn=Jean Dupont,ou=Comptes,o=Ma Société,c=Fr
La virgule marque une division de la référénce, et la séquence est lue de droite à gauche. Vous pouvez la lire comme ceci :
country = Fr
organization = Ma Société
organizationalUnit = Comptes
commonName = Jean Dupont
De la même façon qu'il n'y a pas de règle universelle d'organisation d'un disque dur, un serveur de dossier peut supporter n'importe quelle structure du moment qu'elle a un sens pour ce qu'on en fait. Cependant, il existe quelques conventions : il est impossible d'écrire un code d'accès à un dossier sans en connaître sa structure, de la même façon que vous ne pouvez pas utiliser une base de données sans en connaître les tables.
Exemple complet
Recupérer toutes les entrées dont le nom commence par "S" dans un serveur, et afficher le nom et l'adresse email.
Exemple 1. Recherche LDAP
|
Utilisation des fonctions PHP LDAP
Il faut d'abord que les bibliothèques client LDAP soient compilées avec PHP. Vous pouvez vous procurer ces bibliothèques University of Michigan (ldap-3.3 package) ou chez Netscape (Netscape Directory SDK).
Avant d'utiliser les fonctions LDAP il faut savoir :
Le nom ou l'adresse du serveur à utiliser
Le "nd" dans le serveur (la partie du monde qui est sur ce serveur, ce qui peut correspondre à "o=Ma société,c=Fr")
Eventuellement, un mot de passe pour accéder au serveur (de nombreux serveusr fournissent un accès anonyme ("anonymous bind") mais requièrent un mot de passe pour tous les autres).
Une séquence habituelle LDAP suivra le schéma suivant :
ldap_connect() // établit une connexion à un serveur
|
ldap_bind() // nom de compte "login" ou anonyme
|
éxécution de commandes sur le serveur, comme un listage, ou
une modification de données avec affichage
|
ldap_close() // "déconnexion"
Plus d'informations
Vous pouvez en apprendre encore plus, mais en anglais, aux adresses suivantes :
Le SDK Netscape contient un guide du programmeur au format HTML particulièrement pratique (en anglais).
- Table des matières
- ldap_8859_to_t61 -- Translate 8859 characters to t61 characters
- ldap_add -- Ajoute une entrée à un dossier LDAP.
- ldap_bind -- Se lie à un serveur LDAP.
- ldap_close -- Déconnecte d'un serveur LDAP.
- ldap_compare -- Compare les valeurs des attributs trouvés dans un ND
- ldap_connect -- Se connecte à un serveur LDAP.
- ldap_count_entries -- Compte le nombre d'entrées d'une recherche.
- ldap_delete -- Efface une entrée dans un dossier.
- ldap_dn2ufn -- Convertit un ND dans un format plus accessible.
- ldap_err2str -- Convertit un numéro d'erreur LDAP en message d'erreur.
- ldap_errno -- Retourne le numéro d'erreur LDAP de la dernière commande exécutée.
- ldap_error -- Retourne le message LDAP de la dernière commande LDAP.
- ldap_explode_dn -- Scinde un ND en plusieurs composants.
- ldap_first_attribute -- Retourne le premier attribut.
- ldap_first_entry -- Retourne l'identifiant du premier attribut.
- ldap_first_reference -- Return first reference
- ldap_free_result -- Libère la mémoire prise par un résultat.
- ldap_get_attributes -- Retourne les attributs d'une entrée d'un résultat.
- ldap_get_dn -- Retourne un ND d'une entrée d'un résultat.
- ldap_get_entries -- Retourne toutes les entrées.
- ldap_get_option -- Lit la valeur courante d'une option
- ldap_get_values_len -- Retourne toutes les valeurs binaires à partir d'un identifiant de résultat.
- ldap_get_values -- Retourne toutes les entrées d'un résultat.
- ldap_list -- Recherche dans un seul niveau.
- ldap_mod_add -- Ajoute un attribut
- ldap_mod_del -- Efface un attribut
- ldap_mod_replace -- Remplace un attribut
- ldap_modify -- Modifie une entrée LDAP.
- ldap_next_attribute -- Lit l'attribut suivant.
- ldap_next_entry -- Lit l'attribut suivant.
- ldap_next_reference -- Get next reference
- ldap_parse_reference -- Extract information from reference entry
- ldap_parse_result -- Extract information from result
- ldap_read -- Lit une entrée.
- ldap_rename -- Modifie le nom d'une entrée
- ldap_search -- Recherche dans tout l'arbre LDAP.
- ldap_set_option -- Modifie une option LDAP
- ldap_set_rebind_proc -- Set a callback function to do re-binds on referral chasing.
- ldap_sort -- Sort LDAP result entries
- ldap_start_tls -- Start TLS
- ldap_t61_to_8859 -- Translate t61 characters to 8859 characters
- ldap_unbind -- Termine la liaison avec un serveur LDAP.
ldap_8859_to_t61
Description
string ldap_8859_to_t61 ( string value)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_add
Description
int ldap_add ( resource link_identifier, string dn, array entry)ldap_add() retourne TRUE en cas de succès, ou TRUE en cas d'erreur.
ldap_add() sert à ajouter une entrée dans un dossier LDAP. Le ND de l'entrée sera ajouté à la dn du dossier spécifié. Le tableau entry spécifie les informations de la nouvelle entrée. Les valeurs de l'entrée sont indexées dans les attributs de l'entrée. Si un attribut a de multiples valeurs, elles seront indexées dans un tableau, à partir de l'index 0.
Exemple 1. Exemple complet avec lien authentifié
|
ldap_bind
Description
int ldap_bind ( resource link_identifier [, string bind_rdn [, string bind_password]])ldap_bind() lie un serveur LDAP avec le RDN bind_rdn et mot de passe bind_password. ldap_bind() retourne TRUE en cas de succès, et TRUE sinon.
ldap_bind() effectue une opération de liaison sur le serveur. bind_rdn et bind_password sont optionnels. S'ils manquent, la liaison se fera en mode anonyme.
ldap_close
Description
int ldap_close ( resource link_identifier)ldap_close() retourne TRUE en cas de succès, et TRUE sinon.
ldap_close() ferme le lien au serveur LDAP associé à l'identifiant link_identifier.
Cet appel est identique à ldap_unbind(), en interne. Les API LDAP utilisent la fonction ldap_unbind() : il est probablement mieux que vous utilisiez cette fonction là plutôt que ldap_close().
ldap_compare
Description
int ldap_compare ( resource link_identifier, string dn, string attribute, string value)ldap_compare() retournr TRUE si value un fichier correspond à la recherche; retourne -1 si une erreur survient.
ldap_compare() sert à comparer la valeur value de l'attribut attribute aux valeurs du même atribut dans l'annuaire LDAP dn.
L'exemple suivant montre comment vérifier qu'un mot de passe correspond bien à celui qui est stocké dans l'annuaire.
Exemple 1. Vérification d'un mot de passe avec LDAP
|
Note : ldap_compare() ne peut pas comparer des données binaires.
Note : Cette fonction a été ajoutée en 4.0.2.
ldap_connect
Description
resource ldap_connect ( [string hostname [, int port]])ldap_connect() retourne un identifiant positif de serveur LDAP en cas de succès, ou bien TRUE en cas d'erreur.
ldap_connect() établit une connexion avec un serveur. Le serveur LDAP situé sur l'hôte hostname et port. Les deux arguments sont optionnels. Sans argument, l'identifiant de la dernière connexion ouverte sera retournée. Si seul hostname est spécifié, le port par défaut est 389.
Si vous utilisez OpenLDAP 2.x.x, vous pouvez spécifier une URL au lieu d'un nom d'hôte. Pour utiliser LDAP avec SSL, compilez OpenLDAP 2.x.x avec le support SSL, configurez PHP avec SSL, et utilisez ldaps://hostname/ comme nom d'hôte. Le paramètre de port port n'est pas utile lorsqu'utilisé avec des URL. Le support des URL et SSL a été ajouté en PHP 4.0.4.
ldap_count_entries
Description
int ldap_count_entries ( resource link_identifier, resource result_identifier)ldap_count_entries() retourne le nombre d'entrées en cas de succès, et TRUE sinon.
ldap_count_entries() retourne le nombre d'entrées placées dans le résultat par les recherches précédentes. result_identifier identifie un résultat LDAP interne.
ldap_delete
Description
int ldap_delete ( resource link_identifier, string dn)ldap_delete() retourne TRUE en cas de succès, et TRUE sinon.
ldap_delete() efface une entrée dans un dossier LDAP spécifié par le nd dn.
ldap_dn2ufn
Description
string ldap_dn2ufn ( string dn)ldap_dn2ufn() sert à mettre le nd dn dans un format plus agréable, notamment en supprimant les noms des types.
ldap_err2str
Description
string ldap_err2str ( int errno)ldap_err2str() retourne un message d'erreur.
ldap_err2str() retourne le message d'erreur lié au numér d'erreur errno. Même si les numéros d'erreur LDAP sont standardisés, différentes librairies retournent différents messages, ou parfois, des messages en langue locale. Ne vous fiez pas au message d'erreur, mais bien au numéro d'erreur.
Voir aussi ldap_errno() et ldap_error().
ldap_errno
(PHP 3>= 3.0.12, PHP 4 )
ldap_errno -- Retourne le numéro d'erreur LDAP de la dernière commande exécutée.Description
int ldap_errno ( resource link_id)ldap_errno() retourne le numéro d'erreur LDAP généré par la dernière commande.
ldap_errno() retourne le numéro d'erreur standard, généré par la dernière commande LDAP, pour la connexion link_id. Ce numéro peut être converti en message textuel avec ldap_err2str().
A moins que vous n'abaissiez suffisamment le niveau d'erreur dans php.ini (ou php3.ini), ou que vous ne préfixiez vos commandes LDAP avec @ (at) pour supprimer les affichages, les erreurs LDAP s'afficheront aussi dans le code PHP.
Exemple 1. Genérer et intercepter une erreur
|
Voir aussi ldap_err2str() et ldap_error().
ldap_error
Description
string ldap_error ( resource link_id)ldap_error() retourne un message d'erreur.
ldap_error() retourne le message d'erreur lié à la connexion link_id. Même si les numéros d'erreur LDAP sont standardisés, différentes librairies retournent différents messages, ou parfois, des messages en langue locale. Ne vous fiez pas au message d'erreur, mais bien au numéro d'erreur.
A moins que vous n'abaissiez suffisamment le niveau d'erreur dans php.ini (ou php3.ini), ou que vous ne préfixiez vos commandes LDAP avec @ pour supprimer les affichages, les erreurs LDAP s'afficheront aussi dans le code PHP.
Voir aussi ldap_err2str() et ldap_errno().
ldap_explode_dn
Description
array ldap_explode_dn ( string dn, int with_attrib)ldap_explode_dn() sert à scinder le nd dn retourné par ldap_get_dn() en plusieurs composants. Chaque composant est reconnu sous le nom Nom Distinct Relatif (ou RDN, en anglais). ldap_explode_dn() retourne un tableau qui contient ces composants. with_attrib sert à préciser si le RDN est retourné avec ses attributs, ou seul. Pour obtenir le RDN et ses attributs, mettez with_attrib à 0 et pour n'avoir que les valeurs, mettez le à 1.
ldap_first_attribute
Description
string ldap_first_attribute ( resource link_identifier, resource result_entry_identifier, int ber_identifier)ldap_first_attribute() retourne le premier attribut en cas de succès, et TRUE sinon.
Le comportement est similaire pour les entrées. Les attributs sont lus séquentiellement dans une entrée particulière. ldap_first_attribute() retourne le premier attribut de l'entrée désignée par l'identifiant d'entrée. Les attributs suivants sont accessibles avec ldap_next_attribute(). ber_identifier est un identifiant de pointeur de mémoire interne. Il est passé par référence. Le même identifiant ber_identifier est passé à ldap_next_attribute(), qui modifie ce pointeur.
Voir aussi ldap_get_attributes().
ldap_first_entry
Description
int ldap_first_entry ( resource link_identifier, resource result_identifier)ldap_first_entry() retourne un identifiant sur la première entrée en cas de succès, et TRUE sinon.
Les entrées d'un résultat sont lues séquentiellement, en utilisant ldap_first_entry() et ldap_next_entry(). ldap_first_entry() retourne l'identifiant de la première entrée du résultat. Cet identifiant sera fourni à ldap_next_entry() pour accéder à la prochaine entrée.
Voir aussi ldap_get_entries().
ldap_first_reference
Description
resource ldap_first_reference ( resource link, resource result)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_free_result
Description
int ldap_free_result ( resource result_identifier)ldap_free_result() retourne TRUE en cas de succès, et TRUE sinon.
ldap_free_result() libère la mémoire allouée en interne pour enregistrer le résultat pointé par result_identifier. A la fin de chaque script, la mémoire sera de toute manière libérée.
Généralement, il n'y a pas besoin de libérer la mémoire, et le mécanisme automatique de fin de script est suffisant. Cependant, dans les cas où le script effectue plusieurs recherches successives, où que les résultats retournés sont très grands, ldap_free_result() permet de réduire la consommation de mémoire.
ldap_get_attributes
Description
array ldap_get_attributes ( resource link_identifier, resource result_entry_identifier)ldap_get_attributes() retourne un tableau multi-dimensionel en cas de succès, et TRUE sinon.
ldap_get_attributes() sert à simplifier la lecture des attributs et des valeurs d'une entrée dans un résultat. Le résultat est un tableau multi-dimensionnel, avec les attributs en clé, et les valeurs des attributs en valeurs.
Une fois que vous avez repéré une entré dans un dossier, vous pouvez lire les informations de cette entrée avec cette fonction. Vous pouvez utiliser cette fonction pour créer une application qui se déplace dans les dossiers, sans en connaître la structure au préalable. Dans de nombreux cas, vous ne chercherez qu'un attribut particulier (le email, par exemple) et vous ne vous intéresserez pas aux autres valeurs.
Exemple 1. Affichage de la liste des attributs d'une entrée
|
Voir aussi ldap_first_attribute() et ldap_next_attribute().
ldap_get_dn
Description
string ldap_get_dn ( resource link_identifier, resource result_entry_identifier)ldap_get_dn() retourne le DN de l'entrée en cas de succès, et TRUE sinon.
ldap_get_dn() sert à obtenir le ND d'une entrée d'un résultat.
ldap_get_entries
Description
array ldap_get_entries ( resource link_identifier, resource result_identifier)ldap_get_entries() retourne un tableau multi-dimensionnel en cas de succès, et TRUE sinon.
ldap_get_entries() sert à simplifier la lecture d'un résultat à plusieurs entrées. Toutes les informations sont retournées sous la forme d'un tableau multi-dimensionnel. La structure de ce tableau est la suivante :
Les attributs servent d'index et sont mis en minuscules (les attributs sont insensibles à la casse sur les serveurs, mais peuvent ne pas l'être quand ils sont utilisés comme index)
résultat ["compte"] = nombre d'entrées du résultat
résultat [0] : correspond aux détails de la première entrée :
résultat [i]["nd"] = ND de la i-ième entrée
résultat [i][" compte "] = nombre d'attributs de la i-ième entrée
résultat [i][j] = j-ième attribut de la i-ième entrée
résultat [i]["attribut"]["count"] = nombre de valeur pour l'attribut
résultat [i]["attribut"][j] = j-ième valeur de l'attribut
Voir aussi ldap_first_entry() et ldap_next_entry().
ldap_get_option
Description
boolean ldap_get_option ( resource link_identifier, int option, mixed retval)ldap_get_option() remplace la valeur courante de l'option option par retval, et retourne TRUE en cas de succès, TRUE sinon.
Le paramètre option peut prendre l'une des valeurs : LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, LDAP_OPT_REFERRALS, LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, LDAP_OPT_MATCHED_DN. Elles sont décrites dans draft-ietf-ldapext-ldap-c-api-xx.txt
ldap_get_option() n'est disponible que si vous utilisez OpenLDAP 2.x.x ou Netscape Directory SDK x.x. Elle a été ajoutée dans PHP 4.0.4.
Voir aussi ldap_set_option().
ldap_get_values_len
(PHP 3>= 3.0.13, PHP 4 )
ldap_get_values_len -- Retourne toutes les valeurs binaires à partir d'un identifiant de résultat.Description
array ldap_get_values_len ( resource link_identifier, resource result_entry_identifier, string attribute)ldap_get_values_len() retourne un tableau de valeurs pour l'attribut, ou bien TRUE en cas d'erreur.
ldap_get_values_len() sert à lire toutes les valeurs d'un attribut d'une entrée dans un résultat. L'entrée est spécifiée par result_entry_identifier. Le nombre de valeurs trouvées peut être retrouvé en indexant "count" dans le tableau résultat. On peut accéder aux valeurs individuelles avec un index numérique, commençant à 0.
ldap_get_values_len() est utilisée exactement comme ldap_get_values() mais elle gère les données binaires, et non pas les chaînes.
ldap_get_values
Description
array ldap_get_values ( resource link_identifier, resource result_entry_identifier, string attribute)ldap_get_option() retourne un tableau de valeurs en cas de succès, et TRUE sinon.
ldap_get_values() sert à lire toutes les valeurs d'un attribut dans une entrée. L'entrée est référencée par result_entry_identifier. Le nombre de valeurs peut être trouvé à l'index "count" dans le résultat. Les valeurs sont accessibles par un index entier, qui commence à 0.
ldap_get_values() nécessite un pointeur de résultat result_entry_identifier, ce qui implique qu'il ait été précédé d'une recherche sur le serveur, et de l'obtention d'une entrée.
Votre application pourra utiliser des noms d'attributs en dur dans le code, ou bien, utiliser la fonction ldap_get_attributes() pour y accéder dynamiquement.
LDAP autorise plus d'une entrée par attribut, ce qui permet, par exemple, d'étiqueter tous les adresses email d'un utilisateur avec l'attribut "mail"
return_value["count"] = nombre de valeurs de l'attribut
return_value[0] = première valeur de l'attribut
return_value[i] = n-ième valeur de attribut
Exemple 1. Liste toutes les valeurs avec l'attribut "mail"
|
ldap_list
Description
boolean ldap_list ( resource link_identifier, string base_dn, string filter [, array attributes [, int attrsonly [, int sizelimit [, int timelimit [, int deref]]]]])ldap_list() retourne TRUE en cas de succès, et TRUE sinon.
ldap_list() effecture une recherche avec le filtre7 donnée, et limité un dossier.
LDAP_SCOPE_ONELEVEL indique que la recherche ne doit s'étendre que dans le dossier immédiatement sous le nd base_dn. (Equivalent à taper "ls" et obtenir la liste des fichiers et dossiers du dossier courant).
Cette appel prend un quatrième argument optionnel : un tableau contenant les attributs recherchés. Reportez-vous à ldap_search() pour plus de détails.
Exemple 1. Affiche une liste d'unités organisationnelle
|
ldap_mod_add
Description
resource ldap_mod_add ( int link_identifier, string dn, array entry)ldap_mod_add() retourne TRUE en cas de succès, et TRUE sinon.
ldap_mod_add() ajoute les attributs entry à l'entrée dn. La modification s'applique au niveau local (par opposition au niveau objet). Les ajouts au niveau de l'objet sont pris en charge par ldap_add().
ldap_mod_del
Description
int ldap_mod_del ( resource link_identifier, string dn, array entry)ldap_mod_del() retourne TRUE en cas de succès, et TRUE sinon.
ldap_mod_del() efface les attributs entry à l'entrée dn. La modification s'applique au niveau local (par opposition au niveau objet). Les ajouts au niveau de l'objet sont pris en charge par ldap_delete().
ldap_mod_replace
Description
int ldap_mod_replace ( resource link_identifier, string dn, array entry)ldap_mod_replace() retourne TRUE en cas de succès, et TRUE sinon.
ldap_mod_replace() remplace les attributs entry à l'entrée dn. La modification s'applique au niveau local (par opposition au niveau objet). Les ajouts au niveau de l'objet sont pris en charge par ldap_modify() .
ldap_modify
Description
int ldap_modify ( resource link_identifier, string dn, array entry)ldap_modify() retourne TRUE en cas de succès, et TRUE sinon.
ldap_modify() sert à modifier les entrées existantes dans un dossier LDAP. La structure de l'entrée est la même que décrite dans ldap_add().
ldap_next_attribute
Description
string ldap_next_attribute ( resource link_identifier, resource result_entry_identifier, int ber_identifier)ldap_next_attribute() retourne l'attribut suivant en cas de succès, et sinon, une erreur.
ldap_next_attribute() sert à lire tous les attributs d'une entrée. Le pointeur interne est géré par ber_identifier. Il est passé par référence à la fonction. Le premier appel à ldap_next_attribute() est fait avec le result_entry_identifier retourné par ldap_first_attribute().
Voir aussi ldap_get_attributes().
ldap_next_entry
Description
int ldap_next_entry ( resource link_identifier, resource result_entry_identifier)ldap_next_entry() retourne l'identifiant de l'entrée suivante, dans le résultat qui a été initialisé par ldap_first_entry(). S'il n'y a plus d'entrée, retourne TRUE.
ldap_next_entry() sert à retrouver toutes les entrées qui sont stockées dans un résultat. Les appels successifs à ldap_next_entry() retourneront les entrées une à une. Le premier appel à ldap_next_entry() est fait après un appel à ldap_first_entry() avec result_entry_identifier retourné par ldap_first_entry().
Voir aussi ldap_get_entries().
ldap_next_reference
Description
resource ldap_next_reference ( resource link, resource entry)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_parse_reference
Description
bool ldap_parse_reference ( resource link, resource entry, array referrals)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_parse_result
Description
bool ldap_parse_result ( resource link, resource result, int errcode, string matcheddn, string errmsg, array referrals)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_read
Description
resource ldap_read ( resource link_identifier, string base_dn, string filter [, array attributes [, int attrsonly [, int sizelimit [, int timelimit [, int deref]]]]])ldap_read() retourne un identifiant de résultat en cas de succès, et TRUE sinon.
ldap_read() effectue une recherche avec le filter filter dans le dossier base_dn et avec l'option LDAP_SCOPE_BASE (recherche limitée au dossier, ou récursive). Cela revient à lire une entrée dans un dossier.
Les filtres vides ne sont pas autorisés. Si vous souhaitez lire toutes les informations d'un dossier, utiliser le filtre suivant : "objectClass=*". Si vous savez quel est le type des entrées dans le dossier que vous fouillez, vous pouvez aussi adapter ce filter de la façon suivante "objectClass=inetOrgPerson".
ldap_read() dispose de 5 arguments optionnels. Reportez-vous à ldap_search().
Note : Ces paramètres optionnels ont été ajoutés à partir de la version 4.0.2: attrsonly, sizelimit, timelimit, deref.
ldap_rename
Description
boolean ldap_rename ( int link_identifier, string dn, string newrdn, string newparent, boolean deleteoldrdn)ldap_rename() renomme (ou déplace) l'entrée dn. Le nouveau RDN est spécifié par newrdn et le nouveau père est spécifié par newparent. Si le paramètre deleteoldrdn est TRUE, l'ancienne valeur sera supprimée et la nouvelle valeur sera retenue. ldap_rename() retourne TRUE en cas de succès, et TRUE sinon.
ldap_rename() ne fonctionne qu'avec LDAPv3. Pour les anciennes versions, utilisez plutôt la fonction ldap_set_option().
ldap_rename() n'est disponible qu'avec les serveurs OpenLDAP 2.x.x ou Netscape Directory SDK x.x, et a été ajoutée en PHP 4.0.5.
ldap_search
Description
resource ldap_search ( resource link_identifier, string base_dn, string filter [, array attributes [, int attrsonly [, int sizelimit [, int timelimit [, int deref]]]]])ldap_search() retourne un identifiant de résultat en cas de succès, et FALSE sinon.
ldap_search() effectue une recherche avec le filtre filter dans le dossier base_dn, et avec l'option de récursivité LDAP_SCOPE_SUBTREE. Cela revient à rechercher dans toute la base sous le dossier base_dn.
Le quatrième paramètre est optionnel, et peut être ajouté pour restreindre les attributs et les valeurs retournées. Il est beaucoup plus efficace que la méthode qui consiste à lire tous les attributs et leur valeurs associées. L'utilisation de ce quatrième paramètre est encouragé.
Le quatrième paramètre est un tableau de chaînes, qui contient les attributs désirés, array("mail","sn","cn"). Notez que le nd base_dn est toujours retourné, quelques que soient les attributs demandés.
Notez que certains serveurs sont configurés pour limiter le nombre de résultats. Si cela arrive, le serveur indiquera qu'il n'a transféré qu'une partie du résultat. Cela arrivera aussi si le sixième paramètre sizelimit a été utilisé pour limiter le nombre de lignes lues.
Le cinquième paramètre attrsonly doit être mis à 1 si seuls les types d'attributs sont demandés. S'il est mis à 0, les types des attributs et leur valeur seront lue (comportement par défaut).
Le sixième paramètre sizelimit permet de limiter le nombre de lignes lues. 0 indique qu'il n'y a pas de limite. NOTE : ce paramètre ne peut PAS annuler la configuration du serveur. Il peut seulement la réduire.
Le septième paramètre timelimit fixe la durée de la recherche en seconde. 0 indique qu'il n'y a pas de limite. NOTE : ce paramètre ne peut PAS annuler la configuration du serveur. Il peut seulement la réduire.
Le huitième paramètre deref indique le comportement à suivre avec les alias durant une recherche. Sa valeur peut être l'une de celles-ci :
LDAP_DEREF_NEVER - (par défaut) les alias ne sont pas déréférencés.
LDAP_DEREF_SEARCHING - aliases sont déréférencés durant la recherche mais pas lors de leur localisation.
LDAP_DEREF_FINDING - aliases sont déréférencés durant leur localisation mais pas lors de la recherche.
LDAP_DEREF_ALWAYS - les alias sont toujours déréférencés.
Ces paramètres optionnels ont été ajoutés à partir de la version 4.0.2: attrsonly, sizelimit, timelimit, deref.
La chaîne de filtre peut être simple ou complexe. Elle utilise les opérateurs booléens au même format que celui décrit dans les documentations LDAP (Allez voir celle de Netscape Directory SDK pour plus d'informations sur les filtres).
L'exemple suivant récupère toutes les unités organisationnelles, le nom, prénom et email, dans la société "Ma Société" où le nom et prénom contiennent la sous-chaîne $person. Cet exemple utilise un filtre booléen pour indiquer au serveur qu'il doit rechercher des informations dans plusieurs attributs.
Exemple 1. Recherche LDAP
|
ldap_set_option
Description
boolean ldap_set_option ( resource link_identifier, int option, mixed newval)ldap_set_option() remplace la valeur de l'option option par newval, et retourn TRUE en cas de succès, TRUE sinon.
Le paramètre option peut prendre l'une des valeurs suivantes : LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, LDAP_OPT_REFERRALS, LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, LDAP_OPT_MATCHED_DN, LDAP_OPT_SERVER_CONTROLS, LDAP_OPT_CLIENT_CONTROLS. Pour une brève description, reportez-vous au fichier draft-ietf-ldapext-ldap-c-api-xx.txt.
Les options LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION et LDAP_OPT_ERROR_NUMBER ont une valeur entière, LDAP_OPT_REFERRALS et LDAP_OPT_RESTART sont des booléens, et LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING et LDAP_OPT_MATCHED_DN sont des chaînes de caractères. Le premier exemple illustre leur utilisation. LDAP_OPT_SERVER_CONTROLS et LDAP_OPT_CLIENT_CONTROLS requiert une liste de contrôles, ce qui signifie que la valeur peut être un tableau de contrôles. Un contrôle est constitué d'un oid identifiant le contrôle, d'une valeur value optionnelle, et d'un flag optionnel de criticalité. En PHP un contrôle est un tableau ayant la clé oid et une valeur sous forme de chaîne, ainsi que deux éléments optionnels. Ces éléments ont pour clé value, sous forme de chaîne, et une clé iscritical contenant un booléen. Par défaut, iscritical vaut TRUE Voyez aussi l'exemple ci-dessous.
Cette fonction n'est disponible que lorsque vous utilisez OpenLDAP 2.x.x OU Netscape Directory SDK x.x. Elle a été ajoutée en PHP 4.0.4.
Exemple 2. Modifier les contrôles du serveur LDAP
|
Voir aussi ldap_get_option().
ldap_set_rebind_proc
Description
bool ldap_set_rebind_proc ( resource link, string callback)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_sort
Description
bool ldap_sort ( resource link, resource result, string sortfilter)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_start_tls
Description
bool ldap_start_tls ( resource link)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_t61_to_8859
Description
string ldap_t61_to_8859 ( string value)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ldap_unbind
L. Email
mail() envoie du courrier éléctronique.
Directive de configuration du courrier éléctronique
- SMTP string
Nom de serveur ou adresse IP du serveur SMTP que PHP sous Windows doit utiliser pour envoyer le mail avec la fonction mail().
- sendmail_from string
Entête MIME "From:" qui doit être utilisé dans les mail, pour PHP sous Windows.
- sendmail_path string
Localisation du programme sendmail (généralement /usr/sbin/sendmail ou /usr/lib/sendmail). La commande configure effectue une recherche automatique plutôt efficace pour vous, et choisit une des valeurs par défaut. Si cette recherche échoue, vous pouvez indiquer les informations ici.
Les systèmes qui n'utilisentp as sendmail doivent utiliser cette directive pour indiquer le programme de mail de remplacement. Par exemple, pour Qmail, vous pouvez utiliser la valeur suivante : /var/qmail/bin/sendmail.
- Table des matières
- ezmlm_hash -- Calcule la valeur de hash demandée par EZMLM
- mail -- Envoi de mail
ezmlm_hash
Description
int ezmlm_hash ( string addr)ezmlm_hash() calcule la valeur de hash, nécessaire lors de la gestion de liste de diffusions EZMLM dans une base de données MySQL.
Description
boolean mail ( string to, string subject, string message [, string additional_headers [, string additional_parameters]])mail() poste automatiquement le message message à destination de to. Les destinataires multiples doivent être séparés par des virgules. Les emails avec pièces jointes ou contenus particuliers (comme les emails en HTML, par exemple), peuvent être réalisés avec cette fonction. Il faut respecter l'encodage MIME. Pour plus de détails, voyez http://www.zend.com/zend/spotlight/sendmimeemailpart1.php et la RFC 1896 (Visit http://www.rfc-editor.org/).
mail() retourne TRUE si le mail est envoyé, et FALSE sinon.
Le quatrième argument passé sera inséré à la fin de l'en-tête. Typiquement, cela permet d'insérer des en-têtes supplémentaires. Les en-têtes multiples doivent être séparés par des virgules.
Note : Sous Windows 32bits, vous devez utiliser \r\n pour séparer les en-têtes. Notez aussi que les en-têtes cc: et bcc: sont sensibles à la casse et doivent être écrits Cc: et Bcc: sous Win32.
Si le cinquième argument additional_parameters est fourni, PHP l'utilisera dans son appel du programme d'envoi de courrier électronique. Ceci est pratique pour passer une valeur correcte à l'en-tête Return-Path, avec sendmail.
Note : Le cinquième paramètre a été ajouté en PHP 4.0.5.
Exemple 4. Envoi de mail complexe.
|
Note : Assurez-vous qu'il n'y a aucune nouvelle ligne (ou d'autre espace ou caractère blanc) dans les paramètres to ou subject, car cela peut avoir des effets secondaires irrationnels.
LI. mailparse functions
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
- Table des matières
- mailparse_determine_best_xfer_encoding -- Figures out the best way of encoding the content read from the file pointer fp, which must be seek-able
- mailparse_msg_create -- Returns a handle that can be used to parse a message
- mailparse_msg_extract_part_file -- Extracts/decodes a message section, decoding the transfer encoding
- mailparse_msg_extract_part -- Extracts/decodes a message section. If callbackfunc is not specified, the contents will be sent to "stdout"
- mailparse_msg_free -- Frees a handle allocated by mailparse_msg_crea
- mailparse_msg_get_part_data -- Returns an associative array of info about the message
- mailparse_msg_get_part -- Returns a handle on a given section in a mimemessage
- mailparse_msg_get_structure -- Returns an array of mime section names in the supplied message
- mailparse_msg_parse_file -- Parse file and return a resource representing the structure
- mailparse_msg_parse -- Incrementally parse data into buffer
- mailparse_rfc822_parse_addresses -- Parse addresses and returns a hash containing that data
- mailparse_stream_encode -- Streams data from source file pointer, apply encoding and write to destfp
- mailparse_uudecode_all -- Scans the data from fp and extract each embedded uuencoded file. Returns an array listing filename information
mailparse_determine_best_xfer_encoding
(4.1.0 - 4.1.2 only)
mailparse_determine_best_xfer_encoding -- Figures out the best way of encoding the content read from the file pointer fp, which must be seek-ableDescription
int mailparse_determine_best_xfer_encoding ( resource fp)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_create
Description
int mailparse_msg_create ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_extract_part_file
(4.1.0 - 4.1.2 only)
mailparse_msg_extract_part_file -- Extracts/decodes a message section, decoding the transfer encodingDescription
string mailparse_msg_extract_part_file ( resource rfc2045, string filename [, string callbackfunc])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_extract_part
(4.1.0 - 4.1.2 only)
mailparse_msg_extract_part -- Extracts/decodes a message section. If callbackfunc is not specified, the contents will be sent to "stdout"Description
void mailparse_msg_extract_part ( resource rfc2045, string msgbody [, string callbackfunc])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_free
Description
void mailparse_msg_free ( resource rfc2045buf)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_get_part_data
(4.1.0 - 4.1.2 only)
mailparse_msg_get_part_data -- Returns an associative array of info about the messageDescription
array mailparse_msg_get_part_data ( resource rfc2045)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_get_part
Description
int mailparse_msg_get_part ( resource rfc2045, string mimesection)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_get_structure
(4.1.0 - 4.1.2 only)
mailparse_msg_get_structure -- Returns an array of mime section names in the supplied messageDescription
array mailparse_msg_get_structure ( resource rfc2045)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_parse_file
(4.1.0 - 4.1.2 only)
mailparse_msg_parse_file -- Parse file and return a resource representing the structureDescription
resource mailparse_msg_parse_file ( string filename)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_msg_parse
Description
void mailparse_msg_parse ( resource rfc2045buf, string data)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_rfc822_parse_addresses
(4.1.0 - 4.1.2 only)
mailparse_rfc822_parse_addresses -- Parse addresses and returns a hash containing that dataDescription
array mailparse_rfc822_parse_addresses ( string addresses)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_stream_encode
(4.1.0 - 4.1.2 only)
mailparse_stream_encode -- Streams data from source file pointer, apply encoding and write to destfpDescription
bool mailparse_stream_encode ( resource sourcefp, resource destfp, string encoding)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
mailparse_uudecode_all
(unknown)
mailparse_uudecode_all -- Scans the data from fp and extract each embedded uuencoded file. Returns an array listing filename informationDescription
array mailparse_uudecode_all ( resource fp)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
LII. Mathématiques
Introduction
Ces fonctions ne sont capables de manipuler que des entiers integer, ou nombres à virgule flottante (float). Si vous avez besoin de manipuler des nombres plus grands, reportez-vous aux fonctions mathématiques sur des nombres de grande taille.
Constantes mathématiques
Les valeurs suivantes sont définies comme des constantes en PHP :
Tableau 1. Constantes mathématiques
| Constante | Valeur | Description |
|---|---|---|
| M_PI | 3.14159265358979323846 | Pi |
| M_E | 2.7182818284590452354 | e |
| M_LOG2E | 1.4426950408889634074 | log_2 e |
| M_LOG10E | 0.43429448190325182765 | log_10 e |
| M_LN2 | 0.69314718055994530942 | log_e 2 |
| M_LN10 | 2.30258509299404568402 | log_e 10 |
| M_PI_2 | 1.57079632679489661923 | pi/2 |
| M_PI_4 | 0.78539816339744830962 | pi/4 |
| M_1_PI | 0.31830988618379067154 | 1/pi |
| M_2_PI | 0.63661977236758134308 | 2/pi |
| M_SQRTPI | 1.77245385090551602729 | sqrt(pi) [4.0.2] |
| M_2_SQRTPI | 1.12837916709551257390 | 2/sqrt(pi) |
| M_SQRT2 | 1.41421356237309504880 | sqrt(2) |
| M_SQRT3 | 1.73205080756887729352 | sqrt(3) [4.0.2] |
| M_SQRT1_2 | 0.70710678118654752440 | 1/sqrt(2) |
| M_LNPI | 1.14472988584940017414 | log_e(pi) [4.0.2] |
| M_EULER | 0.57721566490153286061 | Euler constant [4.0.2] |
- Table des matières
- Abs -- Valeur absolue
- Acos -- arc cosinus
- acosh -- Arc cosinus hyperbolique
- Asin -- arc sinus
- asinh -- Arc sinus hyperbolique
- Atan2 -- arc tangent de deux variables
- Atan -- arc tangent
- atanh -- Arc tangeant 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 hyperbolic
- 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 -- exponentielle
- expm1 -- Returns exp(number) - 1, computed in a way that accurate even when the value of number is close to zero
- Floor -- Arrondi à l'entier inférieur
- getrandmax -- Plus grande valeur aléatoire possible.
- hexdec -- Convertit de hexadécimal en décimal
- hypot -- Returns sqrt( num1*num1 + num2*num2)
- is_finite --
- is_infinite --
- is_nan --
- lcg_value -- Générateur de congruence combinée linéaire
- Log10 -- logarithme en base 10.
- log1p -- Returns log(1 + number), computed in a way that accurate even when the val ue of number is close to zero
- Log -- Logarithme naturel (népérien)
- max -- La plus grande valeur.
- min -- La plus petite valeur.
- mt_getrandmax -- La plus grand valeur aléatoire possible.
- mt_rand -- Génère une meilleure valeur aléatoire.
- mt_srand -- Initialise une meilleure valeur aléatoire
- number_format -- Formate un nombre pour l'affichage.
- OctDec -- Convertit d'octal en décimal.
- pi -- Retourne la valeur de pi
- pow -- Puissance
- rad2deg -- Convertit de radians en degrés
- rand -- Génère une valeur aléatoire.
- round -- Arrondi.
- Sin -- Sinus
- sinh -- Sinyus hyperbolique
- Sqrt -- Racine carrée.
- srand -- Initialise le générateur de nombres aléatoires
- Tan -- Tangente
- tanh -- Tangente hyperbolique
Abs
Description
mixed abs ( mixed number)abs() retourne la valeur absolue du nombre number. Si le nombre est un nombre à virgule flottante (float), le type retourné est aussi un nombre à virgule flottante (float), sinon, c'est un entier (integer).
Acos
acosh
Description
float acosh ( float arg)acosh() retourne l'arc cosinus hyperbolique de arg, c'est à dire la valeur dont le cosinus hyperbolique est arg.
Note : Cette fonction n'est pas implémentée sous Windows
Asin
asinh
Description
float asinh ( float arg)asinh() retourne l'arc sinus hyperbolique de arg, c'est à dire la valeur dont le sinus hyperbolique est arg.
Note : Cette fonction n'est pas implémentée sous Windows
Atan2
Description
float atan2 ( float y, float x)atan2() retourne l'arc tangent 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.
atan2() retourne un résultat en radians, entre -PI et PI (inclus).
Atan
Description
float atan ( float arg)atan() retourne l'arc tangent de arg (arg en radians).
Voir aussi acos() et atan().
atanh
Description
float atanh ( float arg)atanh() retourne l'arc tangente hyperbolique de arg, c'est à dire la valeur dont la tangente hyperbolique est arg.
Note : Cette fonction n'est pas implémentée sous Windows
base_convert
Description
string base_convert ( string number, int frombase, int tobase)base_convert() retourne une chaîne contenant l'argument number représenté dans la base tobase. La base de représentation de number est donnée par frombase. frombase et tobase 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 de A à Z, avec A = 10 et Z = 36.
BinDec
Description
int bindec ( string binary_string)bindec() retourne la conversion d'un nombre binaire représenté par la chaîne binary_string en décimal.
bindec() convertit un nombre binaire en décimal. Le plus grand nombre convertible a 31 bits à 1, soit 2147483647 en décimal.
Voir aussi decbin().
Ceil
Description
float ceil ( float number)ceil() retourne l'entier supérieur du nombre number. Utiliser ceil() sur un entier ne sert à rien. La valeur retournée est un nombre à virgule flottante (float), car ces nombres peuvent être plus grands que les entiers.
NOTE: ceil() sous PHP/FI 2 retournait un nombre à virgule flottante. Utilisez: $new = (float)ceil($number); pour retrouver le comportement traditionnel.
Cos
cosh
Description
float cosh ( float arg)cosh() retourne le cosinus hyperbolique de arg, définit comme (exp(arg) + exp(-arg))/2.
DecBin
Description
string decbin ( int number)decbin() retourne une chaîne contenant la représentation binaire de l'entier donné en argument. Le plus grand nombre pouvant être converti est 2147483647 en décimal, ce qui donne une série de 31 uns (1).
Voir aussi bindec().
DecHex
Description
string dechex ( int number)dechex() retourne une chaîne contenant la représentation hexadécimale du nombre number. Le nombre le plus grand qui puisse être converti est 2147483647 en décimal, ce qui donnera "7fffffff".
Voir aussi hexdec().
DecOct
Description
string decoct ( int number)decoct() retourne une chaîne contenant la représentation octale du nombre donné number. Le nombre le plus grand qui puisse être converti est 2147483647 en décimal, ce qui donnera "17777777777".
Voir aussi octdec().
deg2rad
Description
float deg2rad ( float number)deg2rad() convertit number de degrés en radians.
Voir aussi rad2deg().
Exp
Description
float exp ( float arg)exp() retourne l'exponentielle de arg, c'est-à-dire e élevé à la puissance arg.
Voir aussi pow().
expm1
(PHP 4 >= 4.1.0)
expm1 -- Returns exp(number) - 1, computed in a way that accurate even when the value of number is close to zeroDescription
float expm1 ( float number)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
Floor
Description
floats floor ( float number)floor() retourne l'entier inférieur du nombre number. La valeur retournée est un nombre à virgule flottante, (float) car ces nombres peuvent être plus grands que les entiers.
NOTE: floor() sous PHP/FI retournait un float. Utilisez: $new = (float)floor($number); pour retrouver le comportement traditionnel.
getrandmax
Description
int getrandmax ( void)getrandmax() retourne la plus grande valeur aléatoire possible retournée par rand().
Voir aussi rand(), srand() mt_rand(), mt_srand() et mt_getrandmax().
hexdec
Description
int hexdec ( string hex_string)hexdec() retourne une chaîne contenant la représentation décimale du nombre hex_string. Le nombre le plus grand qui puisse être converti est 7fffffff en décimal, ce qui donne "2147483647".
hexdec() remplace tous les caractères non-héxadecimal par des 0. Et si les zéros de gauche sont ignorés, ceux de droite prennent le propre valeur.
Voir aussi dechex().
hypot
Description
float hypot ( float num1, float num2)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
is_finite
Description
bool is_finite ( float val)Returns TRUE if val is a legal finite number within the allowed range for a PHP float on this platform.
is_infinite
Description
bool is_infinite ( float val)Returns TRUE if val is infinite (positive or negative), like the result of log(0) or any value too big to fit into a float on this platform.
is_nan
Description
bool is_nan ( float val)Returns TRUE if val is 'not a number', like the result of acos(1.01).
lcg_value
Description
float lcg_value ( void)lcg_value() retourne un nombre pseudo-aléatoire, compris entre 0 et 1. lcg_value() combine deux générateurs de congruence, de périodes respectives 2^31 - 85 et 2^31 - 249. La période de cette fonction est le produit de ces deux nombres premiers (soit (2^31 - 85)*(2^31 - 249)).
Log10
log1p
(PHP 4 >= 4.1.0)
log1p -- Returns log(1 + number), computed in a way that accurate even when the val ue of number is close to zeroDescription
float log1p ( float number)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
Log
max
Description
number max ( number arg1, number arg2, number argn)max() retourne la plus grande valeur numérique parmi les valeurs passées en paramètre.
Si le premier paramètre est un tableau, max() retourne la plus grande valeur de ce tableau. Si le premier paramètre est un entier, une chaîne ou un nombre à virgule flottante (float), max() requiert au moins deux paramètres, et retournera alors le plus grand d'entre eux. Le nombre d'arguments est alors illimité.
Si au moins une valeur est un nombre à virgule flottante, elles seront toutes traitées comme des nombres à virgule flottante, et un nombre à virgule flottante sera retourné. Si aucune valeur n'est un nombre à virgule flottante, elles seront traitées comme des entiers, et un entier sera retourné.
min
Description
number min ( number arg1, number arg2, number argn)min() retourne la plus petite valeur numérique parmi les valeurs passées en paramètres.
Si le premier paramètre est un tableau, min() retourne la plus petite valeur de ce tableau. Si le premier paramètre est un entier, une chaîne ou un nombre à virgule flottante, min() requiert au moins deux paramètres, et retournera alors le plus petit d'entre eux. Le nombre d'arguments est alors illimité.
Si au moins une valeur est un nombre à virgule flottante, elles seront toutes traitées comme des nombres à virgule flottante, et un nombre à virgule flottante sera retourné. Si aucune valeur n'est un nombre à virgule flottante, elles seront traitées comme des entiers, et un entier sera retourné.
mt_getrandmax
Description
int mt_getrandmax ( void)mt_getrandmax() retourne la plus grand valeur aléatoire possible que peut retourner mt_rand().
Voir aussi mt_rand(), mt_srand() rand(), srand() et getrandmax().
mt_rand
Description
int mt_rand ( int min, int max)De nombreux générateurs de nombres aléatoires provenant de vieilles bibliothèques libcs ont des comportement douteux et sont très lents. Par défaut, PHP utilise le générateur de nombres aléatoires de libc avec la fonction rand(). mt_rand() est une fonction de remplacement, pour cette dernière. Elle utilise un générateur de nombres aléatoire de caractéristique connue, le " Mersenne Twister ", qui va produire des nombres utilisables en cryptographie, et qui est 4 fois plus rapide que la fonction standard libc. La "Homepage of the Mersenne Twister " est http://www.math.keio.ac.jp/~matumoto/emt.html. Une version optimisée des sources de MT est disponible à http://www.scp.syr.edu/~marc/hawk/twister.html.
Appelée sans les arguments optionnels min et max, mt_rand() retourne un nombre pseudo-aléatoire, entre 0 et RAND_MAX. Pour obtenir un nombre entre 5 et 15 inclus, il faut utiliser mt_rand(5,15).
N'oubliez pas d'initialiser le générateur de nombres aléatoires avec mt_srand().
Note : Dans les versions antérieures à la 3.0.7, la signification du paramètre max était "longueur". Pour avoir le même résultat, il faut utiliser mt_rand (5, 11) pour obtenir un nombre aléatoire entre 5 et 15.
Voir aussi mt_srand(), mt_getrandmax(), srand(), rand() et getrandmax().
mt_srand
Description
void mt_srand ( int seed)mt_srand() initialise une meilleure valeur aléatoire avec seed.
<?php // initialise avec les microsecondes depuis la dernière seconde entière mt_srand((float) microtime()*1000000); $randval = mt_rand(); ?> |
Voir aussi mt_rand(), mt_getrandmax(), srand(), rand() et getrandmax().
number_format
Description
string number_format ( float number [, int decimals [, string dec_point [, string thousands_sep]]])number_format() retourne une chaîne représentant number formaté. number_format() accepte un, deux ou 4 paramètres (mais pas trois).
Si le seul paramètre number est donné, il sera formaté sans partie décimale, mais avec une virgule entre chaque millier.
Si les deux paramètres number et decimals sont fournis, number sera formaté avec decimals décimales, un point (".") comme séparateur décimal et une virgule entre chaque millier.
Avec quatre paramètres, number sera formaté avec decimals décimales, dec_point comme séparateur décimal, et thousands_sep comme séparateur de milliers.
Note : Seul le premier caractère du paramètre thousands_sep est utilisé. Par exemple, si vous utilisez foo comme séparateur de milliers, sur le nombre 1000, number_format() retournera 1f000.
En notation française, on utilise généralement deux chiffres après la virgule, une virgule comme séparateur décimal, et un espace comme séparateur de milliers. Cela donne :
OctDec
Description
int octdec ( string octal_string)octdec() retourne une chaîne contenant la représentation décimale du nombre octal_tring. Le nombre le plus grand qui puisse être converti est 17777777777 en décimal, ce qui donnera "2147483647".
Voir aussi decoct().
pi
pow
Description
number pow ( number base, number exp)pow() retourne base élevé à la puissance exp. Si possible, pow() retourne un integer.
Si le calcul ne peut être fait, une alerte sera affichée et pow() retournera FALSE.
| Avertissement |
En PHP 4.0.6 plus ancien, pow() retournait toujours un nombre à virgule flottante (float), et n'affichait pas d'alerte. Si le calcul est impossible (racine d'un nombre négatif, par exemple), pow() retournait NAN. |
Voir aussi exp().
rad2deg
Description
float rad2deg ( float number)rad2deg() convertit number (supposé en radians) en degrés.
Voir aussi deg2rad().
rand
Description
int rand ( int min, int max)Appelée sans les options min et max, rand() retourne un nombre pseudo-aléatoire entre 0 et RAND_MAX. Si vous voulez un nombre aléatoire entre 5 et 15 (inclus), par exemple, utilisez rand (5, 15).
N'oubliez pas d'initialiser le générateur de nombres aléatoires avec srand().
Note : Dans les versions antérieures à la 3.0.7 la signification du paramètre max était longueur. Pour avoir le même résultat, il faut utiliser mt_rand (5, 11) pour obtenir un nombre aléatoire entre 5 et 15.
Voir aussi srand(), getrandmax(), mt_rand(), mt_srand() et mt_getrandmax().
round
Description
float round ( float val [, int precision])round() retourne la valeur arrondie de val à la précision precision (nombre de chiffres après la virgule). Le paramètre precision peut être négatif ou null (sa valeur par défaut).
| Attention |
PHP ne gère par correctement les chaînes telles que "12 300,2", par défaut. Reportez-vous à la conversion de chaînes. |
<?php $foo = round( 3.4 ); // $foo == 3.0 $foo = round( 3.5 ); // $foo == 4.0 $foo = round( 3.6 ); // $foo == 4.0 ?> |
Note : Le paramètre precision est disponible uniquement en PHP 4.
Sin
sinh
Description
float sinh ( float arg)sinh() retourne le sinus hyperbolique de arg, défini comme (exp(arg) - exp(-arg))/2.
Sqrt
srand
Description
void srand ( int seed)srand() initialise le générateur de nombres aléatoires avec seed.
<?php // initialise avec les microsecondes depuis la dernière seconde entière srand((float) microtime()*1000000); $randval = rand(); ?> |
Voir aussi rand(), getrandmax(), mt_rand(), mt_srand() et mt_getrandmax().
Tan
tanh
LIII. Chaînes de caractères multi-octets
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Introduction
| Avertissement |
Ce module est expérimental. Les noms des fonctions sont sujets à des changaments probables. Actuellement, les conversions ne supportent que le Japonais. |
De nombreuses langues dont les signes ne peuvent pas être exprimés sur un seul octet. Des codes multi-octets sont utilisés pour pallier à cette insuffisance. mbstring est développé pour supporter les caractères japonais. Cependant, de nombreuses fonctions mbstring peuvent supporter d'autres jeux de caractères.
Les jeux de caractères multi-octets représentent les caractères sur plusieurs octets consécutifs (d'où leur nom). Certains systèmes d'encodages ont des caractères d'échappement dédiés, pour démarrer/finir une séquence de caractères multi-octets. De ce fait, certains caractères peuvent être détruit lorsqu'une chaîne est coupée en plusieurs morceaux, ou bien conduire à des résultats erronnés lorsque le nombre de caractère est compté. Il faut utiliser des fonctions qui supportent ces encodages. Les fonctions mbstring supportent les jeux de caractères multi-octets, ainsi que les conversions.
Etant donné que PHP supporte essentiellement le jeu de caractères ISO-8859-1, certains jeux de caractères ne fonctionnent pas bien avec PHP. Par conséquent, il est important de donner une valeur à l'option de configuration mbstring.internal_encoding qui permettent à PHP de travailler correctement.
Pré-requis PHP 4
Encodage par octet
Les caractères d'un octet dans l'intervalle 00h-7fh doivent être compatibles avec le code ASCII
Jeux de caractères multi-octets, qui n'utilisent pas l'intervalle 00h-7fh.
Voici des exemples d'encodage internes :
Jeu de caractères qui fonctionnent avec PHP : ISO-8859-*, EUC-JP, UTF-8 Jeu de caractères qui NE fonctionnent PAS avec PHP : JIS, SJIS |
Les jeux de caractères qui ne fonctionnent pas comme encodage interne à PHP, peuvent toutefois être utilisé avec les fonctions de conversion de mbstring.
Note : SJIS ne doit pas être utilisé comme encodage interne, à moins que vous ne soyez familier de l'analyseur/compilateur, et des problèmes liés aux jeux de caractères.
Note : SI vous utilisez une base de données avec PHP, il est recommandé que vous utilisiez le même jeu de caractère pour la base de données et le jeu de caractère interne de PHP, pour améliorer les performances.
Si vous utilisez PostgreSQL, il supporte des jeux de caractères qui peuvent être différents de ceux du client. Reportez vous au manuel de PostgreSQL pour plus de détails.
Comment activer mbstring
mbstring est un module PHP. Vous devez activer le module avec le script de configuration configure. Reportez vous à la section installation pour plus de détails.
Les options de configurations suivantes sont liées au module mbstring.
--enable-mbstring : Active les fonctions mbstring. Cette option est nécessaire pour utiliser les fonctions mbstring.
--enable-mbstr-enc-trans : Active la conversion automatique des données par HTTP, avec le moteur de conversion de mbstring. Si cette option est activée, les données venants du web via HTTP seront converties dans le jeu de caractères mbstring.internal_encoding, automatiquement.
Entrées/Sorties HTTP
La conversion automatiques des entrées/sorties HTTP peuvent aussi convertir des données binaires. Les utilisateurs doivent contrôler les conversions, si des données binaires doivent être utilisées via HTTP.
Si l'option enctype d'un formulaire HTML vaut multipart/form-data, mbstring ne convertira pas les données du POST. Dans ce cas, les chaînes de caractères doivent être convertis manuellement.
Entrée HTTP
Il n'y a pas de moyen 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.
Lorsque vous utilisez 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. Reportez vous à 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 call-back.
Note : Pour les utilisateurs PHP3-i18n, le système de conversion de mbstring diffère de celui de PHP3-i18n. Le jeu de caractère est converti avec un buffer de sortie.
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, UCS-2LE, UTF-16, UTF-16BE, UTF-16LE, UTF-8, UTF-7, ASCII, EUC-JP, SJIS, eucJP-win, SJIS-win, ISO-2022-JP, 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, byte2be, byte2le, byte4be, byte4le, BASE64, 7bit, 8bit et UTF7-IMAP.
Les entrées du fichiers php.ini, qui acceptent des noms de jeux de caractères, acceptent aussi les valeurs "auto" et "pass". Les fonctions mbstring,qui acceptent des noms de jeux de caractères, acceptent aussi la valeur "auto"/
Si "pass" est utilisée, aucune conversion n'est effectuée.
Si "auto" est utilisée, elle est remplacée par "ASCII,JIS,UTF-8,EUC-JP,SJIS".
Voir aussi mb_detect_order().
Note : Un jeu de caractère supporté n'est pas forcément un bon choix comme jeu de caractères interne.
Configuration php.ini
mbstring.internal_encoding définit le jeu de caractères interne par défaut.
mbstring.http_input définit le jeu de caractères d'entrée HTTP par défaut.
mbstring.http_output defines définit le jeu de caractères d'affichage HTTP par défaut.
mbstring.detect_order définit l'ordre de détection des jeux de caractères (lors de la lecture sur une source externe. Voir aussi la fonction mb_detect_order().
mbstring.substitute_character définit le caractère de substitution pour les codes invalides.
Les navigateurs web utilisent tout le temps le même encodage lorsqu'ils émettent les données d'un formulaire. Cependant, les navigateurs peuvent ne pas tous utiliser le même encodage. Voyez la fonction mb_http_input() pour détecter les jeux de caractères utilisés par les navigateurs.
Si enctype vaut multipart/form-data dans un formulaire HTML, mbstring n'effectue aucune conversion des données. Il faut les faire manuellement, dans le script.
Bien que les navigateurs soivent généralement assez intelligents pour détecter les jeux de caractères automatiquement, il est recommandé de l'indiquer dans l'en-tête charset. Modifiez default_charset en fonction du jeu de caractères.
Exemple 4. Exemple de configuration php.ini pour mbstring
|
Exemple 5. Exemple de configuration php.ini pour mbstring pour utiliser EUC-JP
|
Exemple 6. Exemple de configuration php.ini pour mbstring pour utiliser SJIS
|
Cas des caractères japonais
La plupart des caractères japonais demandent plus d'un octet pour être représentés. De plus, plusieurs jeux de caractères japonais existent : il y a notamment EUC-JP, Shift_JIS et ISO-2022-JP. Unicode devient de plus en plus populaire, et UTF-8 aussi. Pour développer des applications Web en environnement japonais, il faut savoir que les encodages ci-dessus dépendent de l'application qu'on en fait : entrée/sortie HTTP, bases de données ou courrier électronique.
La taille nécessaire à un caractère peut aller jusqu'à 4 octets.
Un caractère multi-octets occupe généralement deux octets, à comparer avec les caractères simple-octet traditionnellement utilisé. Les caractères les plus gros sont appelés "zen-kaku" (i.e. grande largeur) et les plus petits sont appelés "han-kaku" (i.e. demi-largeur). Les caractères "zen-kaku" sont généralement de taille constante.
Certains encodage de caractères définissent des séquences de début/fin pour les sections multi-octets.
Les bases de données allouent des tailles de stockages différentes de celles utilisées par PHP, même si le même encodage de caractère est utilisé (par exemple, PostGreSQL).
Le courrier électronique utilise généralement ISO-2022-JP.
Les sites web en "i-mode" utilisent Shift_JIS.
Références
Les jeux de caractères multi-octets et leurs techniques sont très complexes. Il n'est pas possible de couvrir tous les aspects en détails ici. Reportez-vous aux URL suivantes, pour d'autres ressouces complémentaires :
Unicode/UTF/UCS/etc
http://www.unicode.org/
Japanais/coréen/Chinois
ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf
- Table des matières
- mb_convert_encoding -- Conversion d'encodage
- mb_convert_kana -- Convertit entre les différents "kana"
- mb_convert_variables -- Convertit l'encodage de variables
- mb_decode_mimeheader -- Décode une 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 une en-tête MIME
- mb_encode_numericentity -- Encode des entités HTML
- mb_ereg_match -- Regular expression match for multibyte string
- mb_ereg_replace -- Replace regular expression with multibyte support
- mb_ereg_search_getpos -- Returns start point for next regular expression match
- mb_ereg_search_getregs -- Retrive the result from the last multibyte regular expression match
- mb_ereg_search_init -- Setup string and regular expression for multibyte regular expression match
- mb_ereg_search_pos -- Return position and length of matched part of multibyte regular expression for predefined multibyte string
- mb_ereg_search_regs -- Returns the matched part of multibyte regular expression
- mb_ereg_search_setpos -- Set start point of next regular expression match
- mb_ereg_search -- Multibyte regular expression match for predefined multibyte string
- mb_ereg -- Regular expression match with multibyte support
- mb_eregi_replace -- Replace regular expression with multibyte support ignoring case
- mb_eregi -- Regular expression match ignoring case with multibyte support
- mb_get_info -- Get internal settings of 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 -- Lit/modifie le langage courant
- mb_output_handler -- Fonction de traitement des affichages web
- 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 -- Returns current encoding for multibyte regex as string
- mb_send_mail -- Envoie un mail encodé ISO-2022-JP (mail japonais)
- mb_split -- Split multibyte string using regular expression
- mb_strcut -- Coupe une partie de chaîne
- mb_strimwidth -- Tronque une chaîne
- mb_strlen -- Retourne la taille d'une chaîne
- mb_strpos -- Repère la première occurence d'un caractère dans une chaîne
- mb_strrpos -- Repère la dernière occurence d'un caractère dans une chaîne
- mb_strwidth -- Retourne la largeur d'une chaîne
- mb_substitute_character -- Lit/modifie les caractères de substitution
- mb_substr -- Lit une sous-chaîne
mb_convert_encoding
Description
string mb_convert_encoding ( string str, string to-encoding [, mixed from-encoding])mb_convert_encoding() convertit la chaîne str depuis l'encodage from-encoding vers l'encodage to-encoding.
str à convertir.
from-encoding est l'encodage de la chaîne str à l'origine. Il sera détecté parmi plusieurs encodage fournis sous forme d'un tableau, ou d'une liste d'encodages séparés par des virgules.
Exemple 1. Exemple avec mb_convert_encoding()
|
Voir aussi mb_detect_order().
mb_convert_kana
Description
string mb_convert_kana ( string str, string option [, mixed encoding])mb_convert_kana() effectue une conversion "han-kaku" - "zen-kaku" sur la chaîne str. Elle retourne la chaîne convertie. Cette fonction n'est utile que pour le japonais.
option est l'option de conversion. La valeur par défaut est "KV".
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Options de conversions possibles :
"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 alphabets "zen-kaku" en "han-kaku"
"A" : Convertit les nombres et alphabets "zen-kaku" en "han-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 les espaces "zen-kaku" en "han-kaku" (U+3000 -> U+0020)
"S" : Convertit les espaces "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. A utiliser avec "K","H" |
mb_convert_variables
Description
string mb_convert_variables ( string to-encoding, mixed from-encoding, mixed vars)mb_convert_variables() convertit l'encodage des variables vars depuis l'encodage from-encoding vers l'encodage to-encoding, puis retourne le nom de l'encodage détecté, en cas de succès, ou FALSE en cas d'échec.
from-encoding est une liste d'encodages possibles pour les variables vars, fourni sous forme d'un tableau ou d'une liste d'encodage, séparés par des virgules. Si from-coding est omis, les encodages fournit dans mb_detect_order() sont utilisés.
vars est une référence sur une variables à convertir. Les chaînes, tableaux et objets sont aussi supportés.
mb_decode_mimeheader
Description
string mb_decode_mimeheader ( string str)mb_decode_mimeheader() décode l'en-tête MIME str, obtenue dans un courrier électronique.
mb_decode_mimeheader() retourne la chaîne décodée, encodée au format interne.
Voir aussi mb_encode_mimeheader().
mb_decode_numericentity
Description
string mb_decode_numericentity ( string str, array convmap [, string encoding])mb_decode_numericentity() la chaîne d'entités HTML str en chaîne, et retourne cette chaîne.
array est un tableau qui spécifie les codes à convertir.
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Exemple 1. Exemple avec le paramètre convmap
|
Voir aussi mb_encode_numericentity().
mb_detect_encoding
Description
string mb_detect_encoding ( string str [, mixed encoding-list])mb_detect_encoding() détecte l'encodage utilisé par la chaîne str. mb_detect_encoding() retourne le nom de l'encodage détecté.
encoding-list est une liste d'encodage, sous forme de tableau, ou bien de chaîne, les valeurs étant séparés par des virgules.
Si encoding_list est omis, l'ordre spécifié par mb_detect_order() est utilisé.
Exemple 1. Exemple avec mb_detect_encoding()
|
Voir aussi mb_detect_order().
mb_detect_order
Description
array mb_detect_order ( [mixed encoding-list])mb_detect_order() remplace l'ordre de détection des encodages courant par encoding-list. mb_detect_order() retourne TRUE en cas de succès, et FALSE en cas d'erreur failure.
encoding-list est un tableau, ou une liste d'encodages séparés par une virgule. La valeur "auto" est automatiquement remplacé par "ASCII, JIS, UTF-8, EUC-JP, SJIS".
SI encoding-list est omis, mb_detect_order() retourne l'ordre de détection courant des encodages.
Ce paramétrage affected les fonctions mb_detect_encoding() et mb_send_mail().
Exemple 1. Exemple avec mb_detect_order()
|
Voir aussi mb_internal_encoding(), mb_http_input(), mb_http_output() et mb_send_mail()
mb_encode_mimeheader
Description
string mb_encode_mimeheader ( string str [, string charset [, string transfer-encoding [, string linefeed]]])mb_encode_mimeheader() convertit la chaîne str en en-tête MIME, et retourne la chaîne encodée.
charset est le nom de l'encodage. Par défaut, c'est ISO-2022-JP.
transfer-encoding est l'encodage de transfert. Il peut être "B" (Base64) ou "Q" (Quoted-Printable). Par défaut, c'est "B".
linefeed est le marqueur de fin de ligne. Par défaut, c'est "\r\n" (CRLF).
Exemple 1. Exemple avec mb_convert_kana()
|
Voir aussi mb_decode_mimeheader().
mb_encode_numericentity
Description
string mb_encode_numericentity ( string str, array convmap [, string encoding])mb_encode_numericentity() convertit la chaîne str depuis encodage interne en les codes numériques HTML, puis retourne cette chaîne.
array est un tableau qui spécifie les codes à convertir.
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Exemple 1. Exemple de paramètre convmap
|
Exemple 2. Exemple avec mb_encode_numericentity()
|
Voir aussi mb_decode_numericentity().
mb_ereg_match
Description
bool mb_ereg_match ( string pattern, string string [, string option])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_match() returns TRUE if string matches regular expression pattern, FALSE if not.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg().
mb_ereg_replace
Description
string mb_ereg_replace ( string pattern, string replacement, string string [, array option])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_replace() scans string for matches to pattern, then replaces the matched text with replacement and returns the result string or FALSE on error. Multibyte character can be used in pattern.
Matching condition can be set by option parameter. If i is specified for this parameter, the case will be ignored. If x is specified, white space will be ignored. If m is specified, match will be executed in multiline mode and line break will be included in '.'. If p is specified, match will be executed in POSIX mode, line break will be considered as normal character. If e is specified, replacement string will be evaluated as PHP expression.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_eregi_replace().
mb_ereg_search_getpos
Description
array mb_ereg_search_getpos ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_getpos() returns the point to start regular expression match for mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). The position is represented by bytes from the head of string.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_setpos().
mb_ereg_search_getregs
(PHP 4 >= 4.2.0)
mb_ereg_search_getregs -- Retrive the result from the last multibyte regular expression matchDescription
array mb_ereg_search_getregs ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_getregs() returns an array including the sub-string of matched part by last mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). If there are some maches, the first element will have the matched sub-string, the second element will have the first part grouped with brackets, the third element will have the second part grouped with brackets, and so on. It returns FALSE on error;
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_init().
mb_ereg_search_init
(PHP 4 >= 4.2.0)
mb_ereg_search_init -- Setup string and regular expression for multibyte regular expression matchDescription
array mb_ereg_search_init ( string string [, string pattern [, string option]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_init() sets string and pattern for multibyte regular expression. These values are used for mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). It returns TRUE for success, FALSE for error.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_regs().
mb_ereg_search_pos
(PHP 4 >= 4.2.0)
mb_ereg_search_pos -- Return position and length of matched part of multibyte regular expression for predefined multibyte stringDescription
array mb_ereg_search_pos ( [string pattern [, string option]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_pos() returns an array including position of matched part for multibyte regular expression. The first element of the array will be the beggining of matched part, the second element will be length (bytes) of matched part. It returns FALSE on error.
The string for match is specified by mb_ereg_search_init(). It it is not specified, the previous one will be used.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_init().
mb_ereg_search_regs
Description
array mb_ereg_search_regs ( [string pattern [, string option]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_regs() executes the multibyte regular expression match, and if there are some matched part, it returns an array including substring of matched part as first element, the first grouped part with brackets as second element, the second grouped part as third element, and so on. It returns FALSE on error.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_init().
mb_ereg_search_setpos
Description
array mb_ereg_search_setpos ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search_setpos() sets the starting point of match for mb_ereg_search().
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_init().
mb_ereg_search
(PHP 4 >= 4.2.0)
mb_ereg_search -- Multibyte regular expression match for predefined multibyte stringDescription
bool mb_ereg_search ( [string pattern [, string option]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_search() returns TRUE if the multibyte string matches with the regular expression, FALSE for otherwise. The string for matching is set by mb_ereg_search_init(). If pattern is not specified, the previous one is used.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_search_init().
mb_ereg
Description
int mb_ereg ( string pattern, string string [, array regs])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg() executes the regular expression match with multibyte support, and returns 1 if matches are found. If the optional third parameter was specified, the function returns the byte length of matched part, and therarray regs will contain the substring of matched string. The functions returns 1 if it matches with the empty string. It no matche found or error happend, FALSE will be returned.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_eregi()
mb_eregi_replace
Description
string mb_eregi_replace ( string pattern, string replace, string string)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_ereg_replace() scans string for matches to pattern, then replaces the matched text with replacement and returns the result string or FALSE on error. Multibyte character can be used in pattern. The case will be ignored.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg_replace().
mb_eregi
Description
int mb_eregi ( string pattern, string string [, array regs])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_eregi() executes the regular expression match with multibyte support, and returns 1 if matches are found. This function ignore case. If the optional third parameter was specified, the function returns the byte length of matched part, and therarray regs will contain the substring of matched string. The functions returns 1 if it matches with the empty string. It no matche found or error happend, FALSE will be returned.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg().
mb_get_info
Description
string mb_get_info ( [string type])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_get_info() returns internal setting parameter of mbstring.
If type isn't specified or is specified to "all", an array having the elements "internal_encoding", "http_output", "http_input", "func_overload" will be returned.
If type is specified for "http_output", "http_input", "internal_encoding", "func_overload", the specified setting parameter will be returned.
See also mb_internal_encoding(), mb_http_output().
mb_http_input
Description
string mb_http_input ( [string type])mb_http_input() retourne le type d'encodage utilisé par une requête HTTP.
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. Si type est omis, il prend la valeur du dernier type utilisé.
Valeur retournée : nom de l'encodage utilisé. Si mb_http_input() ne peut traiter ce type d'encodage, elle retourne FALSE.
Voir aussi mb_internal_encoding(), mb_http_output() et mb_detect_order()
mb_http_output
Description
string mb_http_output ( [string 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. mb_http_output() retourne TRUE en cas de succès, et FALSE en cas d'échec.
Si encoding est omis, mb_http_output() retourne l'encodage d'affichage courant.
Voir aussi mb_internal_encoding(), mb_http_input() et mb_detect_order()
mb_internal_encoding
Description
string mb_internal_encoding ( [string encoding])mb_internal_encoding() modifie l'encodage interne courant en le remplacant par encoding. Si ce paramètre est omis, l'encodage interne courant est retourné.
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.
encoding: Nom d'encodage.
Valeur retournée : si encoding est fourni, mb_internal_encoding() retourne TRUE en cas de succès, et FALSE sinon. Si encoding est omis, mb_internal_encoding() retourne le nom de l'encodage courant.
Voir aussi mb_http_input(), mb_http_output() et mb_detect_order()
mb_language
Description
string mb_language ( [string language])mb_language() remplace le langage courant par language. Si language est omis, mb_language() retourne le langage courant.
Le paramètre language sert à encoder les messages électroniques. Les langages valies sont : "Japanese" (japonais), "ja" (japonais), "English" (anglais), "en" (anglais) and "uni" (UTF-8). mb_send_mail() utilise cette option pour encoder les emails.
Le langage et sa configuration valle ISO-2022-JP/Base64 poru le japonais, UTF-8/Base64 pour l'UTF-8 et ISO-8859-1/quoted printable pour l'anglais.
Si language est fourni et valide, mb_language() retourne TRUE. Sinon, elle retourne FALSE. Lorsque le paramètre language est omis, mb_language() retourne le nom du langage courant, sous forme de chaîne. Si aucun langage n'avait été configuré, mb_language() retourne FALSE.
Voir aussi mb_send_mail().
mb_output_handler
Description
string mb_output_handler ( string contents, int status)mb_output_handler() est la fonction à fournir à ob_start(). mb_output_handler() convertit les caractères envoyés au client Web, dans l'encodage paramétré avec mb_http_output().
contents : Le contenu à traiter
status : L'état du contenu
mb_output_handler() retourne la chaîne convertie.
Note : Si vous souhaitez envoyer des données binaires telles que des images issues d'un script PHP, vous devez spécifier l'encodage spécial "pass", avec la fonction mb_http_output().
Voir aussi ob_start().
mb_parse_str
(PHP 4 >= 4.0.6)
mb_parse_str -- Analyse les données HTTP GET/POST/COOKIE et assigne les variables globalesDescription
string mb_parse_str ( string encoded_string [, array result])mb_parse_str() analyse les données d'entrées HTTP GET/POST/COOKIE et assigne les variables globales. Etant 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, converti les données en jeu de caractères interne, et affecte les valeurs au tableau de variables globales.
encoded_string: Les données encodées de l'URL.
result: Un tableau contenant les valeurs décodées, et les noms des jeux de caractères.
mb_parse_str() retourne TRUE en cas de succès, et FALSE sinon.
Voir aussi mb_detect_order() et mb_internal_encoding().
mb_preferred_mime_name
Description
string mb_preferred_mime_name ( string encoding)mb_preferred_mime_name() retourne le type d'encodage MIME utilisé dans le mail encoding. Le nom de l'encodage est retourné sous forme de chaîne.
mb_regex_encoding
Description
string mb_regex_encoding ( [string encoding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_regex_encoding() returns the character encoding used by multibyte regex functions.
If the optional parameter encoding is specified, it is set to the character encoding for multibyte regex. The default value is the internal character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_internal_encoding(), mb_ereg()
mb_send_mail
Description
boolean mb_send_mail ( string to, string subject, string message [, string additional_headers [, string additional_parameter]])mb_send_mail() envoie un courrier électronique. Les en-têtes et le corps du mesage sont convertis et encodés en ISO-2022-JP. mb_send_mail() est une version adaptée de mail().
to est l'adresse de destination du mail. Les adresses multiples peuvent être spécifiées en les séparant par des virgules.
subject est le sujet du mail.
message est le message du mail.
La chaîne additional_headers est insérée à la fin de l'en-tête mail. Elle sert à ajouter d'autres en-têtes email. N'oubliez pas de les séparer par des nouvelles lignes (\n).
mb_send_mail() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
Voir aussi mail().
mb_split
Description
array mb_split ( string pattern, string string [, int limit])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
mb_split() split multibyte string using regular expression pattern and returns the result as an array.
If optional parameter limit is specified, it will be split in limit elements as maximum.
The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.
Note : This function is supported in PHP 4.2.0 or higher.
See also: mb_regex_encoding(), mb_ereg().
mb_strcut
Description
string mb_strcut ( string str, int start [, int length [, string encoding]])mb_strcut() retourne la portion de la chaîne str qui commence au caractère start et a la longueur de length caractères.
mb_strcut() effectue une recherche de type strpos(), en tenant compte des caractères multi-octets. La position de needle est comptée à partir du début de la chaîne haystack : les positions commencent à 0.
mb_strcut() soustrait la partie de la chaîne str qui compte length caractères.
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_substr() et mb_internal_encoding().
mb_strimwidth
Description
string mb_strimwidth ( string str, int start, int width, string trimmarker [, string encoding])mb_strimwidth() tronque la chaîne str à la longueur width. Elle retourne la chaîne tronquée.
SI trimmarker est fourni, trimmarker est ajoutée à la fin de la chaîne retournée.
start est l'offet de départ, en nombre de caractères depuis le début de la chaîne (cela commence à 0).
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_strwidth() et mb_internal_encoding().
mb_strlen
Description
string mb_strlen ( string str [, string encoding])mb_strlen() retourne le nombre de caractères dans la chaîne str, avec l'encodage encoding. Un caractère multi-octets est alors compté pour 1.
Voir aussi mb_internal_encoding(), strlen().
mb_strpos
Description
string mb_strpos ( string haystack, string needle [, int offset [, string encoding]])mb_strpos() retourne la position numérique de la première occurence du caractère needle dans la chaîne haystack. Si needle est introuvable, mb_strpos() retourne FALSE.
mb_strpos() effectue une recherche de type strpos(), en tenant compte des caractères multi-octets. La position de needle est comptée à partir du début de la chaîne haystack : les positions commencent à 0.
Si encoding est omis, l'encodage interne par défaut est utilisé. mb_strrpos() accepte des chaînes comme argument needle, alors que strrpos() n'accepte que des caractères.
offset est l'offset de début de recherche. S'il est omis, il sera utilisé à 0 (début de la chaîne).
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_strpos(), mb_internal_encoding() et strpos()
mb_strrpos
Description
string mb_strrpos ( string haystack, string needle [, string encoding])mb_strrpos() retourne la position numérique de la première occurence du caractère needle dans la chaîne haystack. Si needle est introuvable, mb_strrpos() retourne FALSE.
mb_strrpos() effectue une recherche de type strpos(), en tenant compte des caractères multi-octets. La position de needle est comptée à partir du début de la chaîne haystack : les positions commencent à 0.
Si encoding est omis, l'encodage interne par défaut est utilisé. mb_strrpos() accepte des chaînes comme argument needle, alors que strrpos() n'accepte que des caractères.
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_strpos(), mb_internal_encoding() et strrpos().
mb_strwidth
Description
int mb_strwidth ( string str [, string encoding])mb_strwidth() retourne la largeur de la chaîne str.
Les chaînes à encodage multi-octet sont généralement deux fois plus grandes que les chaînes à simple-octet.
Largeur de caractères :
U+0000 - U+0019 0
U+0020 - U+1FFF 1
U+2000 - U+FF60 2
U+FF61 - U+FF9F 1
U+FFA0 - 2 |
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_strimwidth() et mb_internal_encoding().
mb_substitute_character
Description
mixed mb_substitute_character ( [mixed substrchar])mb_substitute_character() spécifie le caractère de substitution des caractères invalides, ou des encodages invalides. Les caractères invalides peuvent être remplacés par NULL (pas d'affichage, ils sont supprimés), une chaîne ou un code héxadécimal.
Ce paramétrage affecte mb_detect_encoding() et mb_send_mail().
substchar spécifie une valeur Unicode sous la forme d'un entier, ou bien une chaîne sous ces formes :
"none" : pas d'affichage
"long" : affiche la valeur hexadécimale (Par exemple : U+3000,JIS+7E7E)
SI substchar est fourni, mb_substitute_character() retourne TRUE en cas de succès, et FALSE en cas d'erreur. Si substchar est omis, mb_substitute_character() retourne une valeur Unicode, ou bien "none"/"long".
Exemple 1. Exemple avec mb_substitute_character()
|
mb_substr
Description
string mb_substr ( string str, int start [, int length [, string encoding]])mb_substr() retourne la portion de la chaîne str qui commence au caractère start et a la longueur de length caractères.
mb_substr() effectue une recherche de type strpos(), en tenant compte des caractères multi-octets. La position de needle est comptée à partir du début de la chaîne haystack : les positions commencent à 0.
encoding est un nom d'encodage de caractères. S'il n'est pas spécifié, l'encodage interne est utilisé.
Voir aussi mb_strcut() et mb_internal_encoding().
LIV. MCAL
MCAL signifie Modular Calendar Access Library (librairie calendaire modulaire).
Libmcal est une librairie C de calendriers. Elle est écrite pour être très modulaire, et dispose de nombreux modules. MCAL est l'équivalent de IMAP pour les calendriers.
Avec mcal, un calendrier peut être ouvert comme une boîte aux lettres. Les calendriers peuvent être des fichiers locaux, ou bien être sur des serveurs ICAP distants, ou encore tout autre format supporté par la librairie.
Les événements peuvent être lus, sélectionnés et enregistrés. Il y a aussi la possibilité d'ajouter des alarmes, et de placer des événéments récurents.
Avec libmcal, les serveurs centralisés peuvent être accédés et utilisés, et remplacent avantageusement tout développement spécifique de base de données.
Pour faire fonctionner cette librairie, vous devez compiler PHP avec l'option --with-mcal. Il vous faudra alors avoir installé la librairie mcal. Téléchargez la dernière version à http://mcal.chek.com/ et compilez-la, puis installez-la.
Les constantes suivantes sont définies avec l'extension mcal. Pour les jours de la semaine :
MCAL_SUNDAY (Dimanche)
MCAL_MONDAY (Lundi)
MCAL_TUESDAY (Mardi)
MCAL_WEDNESDAY (Mercredi)
MCAL_THURSDAY (Jeudi)
MCAL_FRIDAY (Vendredi)
MCAL_SATURDAY (Samedi)
MCAL_RECUR_NONE (Aucune)
MCAL_RECUR_DAILY (Quotidienne)
MCAL_RECUR_WEEKLY (Hebdomadaire)
MCAL_RECUR_MONTHLY_MDAY (Mensuelle, date fixe)
MCAL_RECUR_MONTHLY_WDAY (Mensuelle, jour fixe )
MCAL_RECUR_YEARLY (Annuelle)
MCAL_JANUARY (Janvier)
MCAL_FEBRUARY (Février)
MCAL_MARCH (Mars)
MCAL_APRIL (Avril)
MCAL_MAY (Mai)
MCAL_JUNE (Juin)
MCAL_JULY (Juillet)
MCAL_AUGUST (AoÛt)
MCAL_SEPTEMBER (Septembre)
MCAL_OCTOBER (Octobre)
MCAL_NOVEMBER (Novembre)
MCAL_DECEMBER (Décembre)
- Table des matières
- mcal_append_event -- Enregistre un nouvel événement dans un calendrier MCAL.
- mcal_close -- Ferme une connexion MCAL.
- mcal_create_calendar -- Crée un nouveau calendrier
- mcal_date_compare -- Compare deux dates.
- mcal_date_valid -- Valide une date.
- mcal_day_of_week -- Le jour de la semaine.
- mcal_day_of_year -- Le jour de l'année.
- mcal_days_in_month -- Retourne le nombre de jour d'un mois.
- mcal_delete_calendar -- Efface un calendrier
- mcal_delete_event -- Efface un événement dans un calendrier MCAL.
- mcal_event_add_attribute -- Ajoute un attribut et une valeur à la structure globale
- mcal_event_init -- Initialise la structure globale d'un flot.
- mcal_event_set_alarm -- Fixe l'alarme de la structure globale.
- mcal_event_set_category -- Fixe la catégorie de la structure globale.
- mcal_event_set_class -- Fixe la classe de la structure globale.
- mcal_event_set_description -- Fixe la description de la structure globale.
- mcal_event_set_end -- Fixe la date de fin de la structure globale.
- mcal_event_set_recur_daily -- Fixe la récurrence quotidienne.
- mcal_event_set_recur_monthly_mday -- Fixe la récurrence.
- mcal_event_set_recur_monthly_wday -- Fixe la récurrence mensuelle.
- mcal_event_set_recur_none -- Supprime la récurrence de la structure globale.
- mcal_event_set_recur_weekly -- Fixe la récurrence hebdomadaire.
- mcal_event_set_recur_yearly -- Fixe la récurrence annuelle.
- mcal_event_set_start -- Fixe les dates de début et de fin de la structure globale.
- mcal_event_set_title -- Fixe le titre de la structure globale.
- mcal_expunge -- Supprime tous les événements marqués pour l'effacement
- mcal_fetch_current_stream_event -- Retourne un objet contenant la structure de date pour le flot courant.
- mcal_fetch_event -- Recherche un événement dans le calendrier.
- mcal_is_leap_year -- Vérifie que l'année est bissextile.
- mcal_list_alarms -- Retourne une liste d'événements qui ont une alarme prévue à une date.
- mcal_list_events -- Retourne une liste d'événement entre deux dates.
- mcal_next_recurrence -- Retourne la prochaine occurrence d'un événement.
- mcal_open -- Ouvre une connexion MCAL.
- mcal_popen -- Ouvre une connexion persistante MCAL.
- mcal_rename_calendar -- Renomme un calendrier
- mcal_reopen -- Réouvre une connexion MCAL
- mcal_snooze -- Eteint l'alarme d'un événement.
- mcal_store_event -- Modifie un événement dans un calendrier MCAL.
- mcal_time_valid -- Valide une heure.
- mcal_week_of_year -- Returns the week number of the given date
mcal_append_event
Description
int mcal_append_event ( resource mcal_stream)mcal_append_event() enregistre l'événement global dans le calendrier MCAL mcal_stream.
mcal_append_event() retourne l'uid de l'enregistement ainsi inséré.
mcal_close
Description
int mcal_close ( resource mcal_stream, int flags)mcal_close() ferme la connexion mcal_stream.
mcal_create_calendar
Description
string mcal_create_calendar ( resource mcal_stream, string calendar)mcal_create_calendar() crée un nouveau calendrier nommé calendar.
mcal_date_compare
Description
int mcal_date_compare ( int a_year, int a_month, int a_day, int b_year, int b_month, int b_day)mcal_date_compare() compares les deux dates données, et retourne <0, 0, > 0 si a<b, a==b, a>b respectivement.
mcal_date_valid
Description
int mcal_date_valid ( int year, int month, int day)mcal_date_valid() retourne TRUE si la date (constituée par l'année year, le mois month et la date day) est valide, et FALSE sinon.
mcal_day_of_week
Description
int mcal_day_of_week ( int year, int month, int day)mcal_day_of_week() retourne le jour de la semaine, pour la date constituée par l'année year, le mois month et la date day.
mcal_day_of_year
Description
int mcal_day_of_year ( int year, int month, int day)mcal_day_of_year() retourne le numéro de jour dans l'année pour la date constituée par l'année year, le mois month et la date day.
mcal_days_in_month
Description
int mcal_days_in_month ( int month, int leap_year)mcal_days_in_month() retourne le nombre de jour du mois month, et prend en compte le fait que l'année est bissextile avec le paramètre leap_year.
mcal_delete_calendar
Description
string mcal_delete_calendar ( resource mcal_stream, string calendar)mcal_delete_calendar() efface le calendrier calendar.
mcal_delete_event
Description
int mcal_delete_event ( resource mcal_stream [, int event_id])mcal_delete_event() efface l'événement d'identifiant uid.
Retourne TRUE.
mcal_event_add_attribute
(PHP 3>= 3.0.15, PHP 4 )
mcal_event_add_attribute -- Ajoute un attribut et une valeur à la structure globaleDescription
void mcal_event_add_attribute ( resource mcal_stream, string attribute, string value)mcal_event_add_attribute() ajoute l'attribut attribute à la structure globale, avec la valeur value.
mcal_event_init
Description
int mcal_event_init ( resource mcal_stream)mcal_event_init() initialise la structure globale d'un flot. Cela remet tous les éléments de la structure à 0, ou à leur valeur par défaut.
mcal_event_init() retourne TRUE.
mcal_event_set_alarm
Description
int mcal_event_set_alarm ( resource mcal_stream, int alarm)mcal_event_set_alarm() fixe l'alarme de la structure globale,à un nombre de minutes avant déclenchement.
mcal_event_set_alarm() retourne TRUE.
mcal_event_set_category
Description
int mcal_event_set_category ( resource mcal_stream, string category)mcal_event_set_category() fixe la catégorie de la structure globale à la valeur de category.
mcal_event_set_category() retourne TRUE.
mcal_event_set_class
Description
int mcal_event_set_class ( resource mcal_stream, int class)mcal_event_set_class() fixe la classe de la structure globale. La classe vaut 0 pour si elle est publique, et 1 si elle est privée.
mcal_event_set_class() retourne TRUE.
mcal_event_set_description
Description
int mcal_event_set_description ( resource mcal_stream, string description)mcal_event_set_description() fixe la catégorie de la structure globale à la valeur de description.
mcal_event_set_description() retourne TRUE.
mcal_event_set_end
Description
int mcal_event_set_end ( resource mcal_stream, int year, int month [, int day [, int hour [, int min [, int sec]]]])mcal_event_set_end() fixe la date de fin de la structure globale.
mcal_event_set_end() retourne TRUE.
mcal_event_set_recur_daily
Description
int mcal_event_set_recur_daily ( resource mcal_stream, int year, int month, int day, int interval)mcal_event_set_recur_daily() fixe la récurrence quotidienne de la structure globale, jusqu'à la date passée en paramètre. (la date de début est celle de la structure).
mcal_event_set_recur_monthly_mday
Description
int mcal_event_set_recur_monthly_mday ( resource mcal_stream, int year, int month, int day, int interval)mcal_event_set_recur_monthly_mday() fixe la récurrence de la structure globale, jusqu'à la date passée en paramètre. (la date de début est celle de la structure).
mcal_event_set_recur_monthly_wday
Description
int mcal_event_set_recur_monthly_wday ( resource mcal_stream, int year, int month, int day, int interval)mcal_event_set_recur_monthly_wday() fixe la récurrence mensuelle de la structure globale, jusqu'à la date passée en paramètre. (la date de début est celle de la structure).
mcal_event_set_recur_none
(PHP 3>= 3.0.15, PHP 4 )
mcal_event_set_recur_none -- Supprime la récurrence de la structure globale.Description
int mcal_event_set_recur_none ( resource mcal_stream)mcal_event_set_recur_none() supprime la récurrence de la structure globale (event->recur_type est mis à MCAL_RECUR_NONE).
mcal_event_set_recur_weekly
Description
int mcal_event_set_recur_weekly ( resource mcal_stream, int year, int month, int day, int interval, int weekdays)mcal_event_set_recur_weekly() fixe la récurrence hebdomadaire de la structure globale, jusqu'à la date passée en paramètre. (la date de début est celle de la structure).
mcal_event_set_recur_yearly
Description
int mcal_event_set_recur_yearly ( resource mcal_stream, int year, int month, int day, int interval)mcal_event_set_recur_yearly() fixe la récurrence annuelle de la structure globale, jusqu'à la date passée en paramètre. (la date de début est celle de la structure).
mcal_event_set_start
(PHP 3>= 3.0.13, PHP 4 )
mcal_event_set_start -- Fixe les dates de début et de fin de la structure globale.Description
int mcal_event_set_start ( resource mcal_stream, int year, int month [, int day [, int hour [, int min [, int sec]]]])mcal_event_set_start() fixe la date de début de la structure globale.
mcal_event_set_start() retourne TRUE.
mcal_event_set_title
Description
int mcal_event_set_title ( resource mcal_stream, string title)mcal_event_set_title() fixe le titre de la structure globale à la valeur de title.
mcal_event_set_title() retourne TRUE.
mcal_expunge
Description
int mcal_expunge ( resource mcal_stream)mcal_expunge() supprime tous les événements marqués pour l'effacement.
mcal_fetch_current_stream_event
(PHP 3>= 3.0.13, PHP 4 )
mcal_fetch_current_stream_event -- Retourne un objet contenant la structure de date pour le flot courant.Description
object mcal_fetch_current_stream_event ( resource mcal_stream)mcal_fetch_current_stream_event() retourne la structure de la date du flot courant sous la forme d'un objet, qui contient :
int id - ID de l'événement.
int public - TRUE si l'événement est public, FALSE si il est privé.
string category - Catégorie de l'événement.
string title - Titre de l'événement.
string description - Description de l'événement.
int alarm - Nombre de minutes avant d'envoyer une alerte pour cet événement.
object start - Objet contenant une date et une heure.
object end - Objet contenant une date et une heure.
int recur_type - type de récurrence
int recur_interval - intervalle de récurrence
datetime recur_endate - date de fin de récurrence
int recur_data - données de récurrence
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
int alarm - nombre de minutes avant de déclencher l'alarme
0 - Indique que l'événement ne se répète jamais
1 - Indique que l'événement se répète tous les jours
2 - Indique que l'événement se répète toutes les semaines
3 - Indique que l'événement se répète tous les mois, à la même date (le 10 du mois)
4 - Indique que l'événement se répète tous les mois, un certain jours (i.e., le troisième samedi du mois)
5 - Indique que l'événement se répète tous les ans
mcal_fetch_event
Description
object mcal_fetch_event ( resource mcal_stream, int event_id [, int options])mcal_fetch_event() recherche un évenement dans le calendrier spécifié par id.
mcal_fetch_event() retourne un objet événement dont les attributs sont :
int id - ID de l'événement.
int public - TRUE si l'événement est public, FALSE si il est privé.
string category - Catégorie de l'événement.
string title - Titre de l'événement.
string description - Description de l'événement.
int alarm - Nombre de minutes avant d'envoyer une alerte pour cet événement.
object start - Objet contenant une date et une heure.
object end - Objet contenant une date et une heure.
int recur_type - type de récurrence
int recur_interval - intervalle de récurrence
datetime recur_endate - date de fin de récurrence
int recur_data - données de récurrence
int year - année
int month - mois
int mday - jour du mois
int hour - heure
int min - minutes
int sec - secondes
int alarm - nombre de minutes avant de déclencher l'alarme
0 - Indique que l'événement ne se répète jamais
1 - Indique que l'événement se répète tous les jours
2 - Indique que l'événement se répète toutes les semaines
3 - Indique que l'événement se répète tous les mois, à la même date (le 10 du mois)
4 - Indique que l'événement se répète tous les mois, un certain jours (i.e., le troisième samedi du mois)
5 - Indique que l'événement se répète tous les ans
mcal_is_leap_year
Description
int mcal_is_leap_year ( int year)mcal_is_leap_year() retoune 1 si l'année year est bissextile, et 0 sinon.
mcal_list_alarms
(PHP 3>= 3.0.13, PHP 4 )
mcal_list_alarms -- Retourne une liste d'événements qui ont une alarme prévue à une date.Description
array mcal_list_alarms ( resource mcal_stream [, int begin_year [, int begin_month [, int begin_day [, int end_year [, int end_month [, int end_day]]]]]])mcal_list_events() retourne un tableau d'identifiants, qui ont une alarme de prévue à la date alarm_date. Si seul le flot MCAL est donné, la date de début et de fin de la structure globale sera utilisée.
mcal_list_events() prend une date, et retourne un tableau d'identifiants.
mcal_list_events
Description
array mcal_list_events ( resource mcal_stream, object begin_date [, object end_date])mcal_list_events() retourne un tableau d'identifiants d'événéments, compris entre deux dates.
mcal_list_events() prend une date de début et une date de fin. Un tableau d'identifiants est retourné.
mcal_next_recurrence
Description
int mcal_next_recurrence ( resource mcal_stream, int weekstart, array next)mcal_next_recurrence() retourne un objet contenant la prochaine date de l'événement, ou la date de l'événement suivant la date. mcal_next_recurrence() retourne un objet date vide si l'événement n'a pas de réoccurrence, ou si quelquechose est invalide. Utilisez weekstart pour déterminer le premier jour.
mcal_open
Description
resource mcal_open ( string calendar, string username, string password [, int options])mcal_open() retourne un flot MCAL en cas de succès, et FALSE en cas d'erreur.
mcal_open() ouvre une connexion MCAL au serveur calendar. Si options est spécifié, passe aussi options à la boîte aux lettres (???). La structure interne du flot MCAL est initialisée à la connexion.
mcal_popen
Description
resource mcal_popen ( string calendar, string username, string password [, int options])mcal_popen() retourne un flot MCAL en cas de succès, et FALSE sinon.
mcal_popen() ouvre une connexion MCAL au serveur de calendrier calendar. Si les options options sont spécifiées, elles sont aussi passé à cette boîte au lettre. La structure interne du flot est aussi initialisée.
mcal_rename_calendar
Description
string mcal_rename_calendar ( resource mcal_stream, string old_name, string new_name)mcal_rename_calendar() renomme le calendrier old_name en new_name.
mcal_reopen
Description
resource mcal_reopen ( string calendar [, int options])mcal_reopen() réouvre une connexion MCAL.
mcal_reopen() réouvre une connexion MCAL avec le serveur calendar. Si les options options sont spécifiées, elles sont aussi passé à cette boîte aux lettres.
mcal_snooze
Description
int mcal_snooze ( int id)mcal_snooze() éteint l'alarme de l'événement identifié par l'UID uid.
mcal_snooze() retourne TRUE.
mcal_store_event
Description
int mcal_store_event ( resource mcal_stream)mcal_store_event() enregistre l'événement global dans le calendrier MCAL mcal_stream.
mcal_store_event() retourne l'identifiant de l'événement modifié en cas de succès, et FALSE en cas d'erreur.
mcal_time_valid
Description
int mcal_time_valid ( int hour, int minutes, int seconds)mcal_time_valid() retourne TRUE si l'heure (constituée par l'heure hour, les minutes minutes et les secondes seconds) est une heure valide, et FALSE sinon.
mcal_week_of_year
LV. Chiffrage mcrypt
Ces fonctions utilisent mcrypt.
Ces fonctions permettent d'accéder à la librairie mcrypt, qui dispose d'une grande variété d'algorithmes de chiffrage, tels que 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, elle accepte aussi RC6 et IDEA qui sont considérés comme "non libre".
Si vous compilez PHP avec la librairie libmcrypt 2.4.x, les algorithmes suivants sont supportés : CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT ainsi que les chiffrements suivants : ENIGMA (chiffrage), PANAMA, RC4 et WAKE. Avec libmcrypt 2.4.x un autre mode de chiffrement est disponible : nOFB.
Pour l'utiliser, téléchargez la librairie libmcrypt-x.x.tar.gz par ici et suivez les instructions d'installations incluses. Vous aurez aussi besoin de compiler PHP avec le paramètre --with-mcrypt pour activer cette extension.
Mcrypt permet de chiffrer et de déchiffrer, en utilisant les méthodes mentionnées ci-dessus. Les 4 commandes importantes mcrypt_cfb(), mcrypt_cbc(), mcrypt_ecb() et mcrypt_ofb()) peuvent toutes opérer en mode MCRYPT_ENCRYPT et MCRYPT_DECRYPT.
Si vous avez compilé PHP avec libmcrypt 2.4.x, ces fonctions sont toujours disponibles, mais il est vivement conseillé d'utiliser les nouvelles fonctions avancées.
Exemple 2. Encryption d'une valeur avec TripleDES sous 2.4.x en mode ECB
|
Mcrypt peut opérer en 4 modes de chiffrage (CBC, OFB, CFB, et ECB). Nous allons présenter la technique d'utilisation de ces modes. Pour plus de références et de détails, reportez-vous au livre suivant : Applied Cryptography par Schneier (ISBN 0-471-11709-9).
ECB (electronic codebook) ECB (electronic codebook) est prévu pour des données aléatoires, telles que des clés. Etant donné que les données sont peu nombreuses et aléatoires, les inconvénients de l'ECB ont ici un effet négatif favorable.
CBC (cipher block chaining) est spécialement pratique avec les fichiers dont la sécurité ECB n'est pas suffisante.
CFB (cipher feedback) est la meilleure méthode pour chiffrer des flots d'octets, quand les octets doivent être encryptés un par un.
OFB (output feedback) est comparable à CFB, mais peut être utilisé lorsque des erreurs ne doivent pas être propagées.
nOFB (output feedback, in nbit) est comparable à OFB, mais plus sÛr, car il opère avec la taille de blocs de l'algorithme.
STREAM est un mode supplémentaire, pour permettre l'utilisation d' algorithmes tels que WAKE ou RC4.
PHP ne supporte par encore le chiffrage des flots d'octets. Pour l'instant, PHP n'accepte que le chiffrage de chaîne.
Pour obtenir la liste complète des modes de chiffrement, reportez vous aux derniers #define, dans le fichier mcrypt.h. En règle générale, vous pouvez accéder à une méthode de chiffrement avec l'option MCRYPT_nomDuChiffrement.
Voici une liste non exhaustive des modes de chiffrement de l'extension mcrypt. Si un chiffrement n'est pas dans cette liste, mais disponible dans la librairie, vous pouvez supposer que cette documentation est hors d'âge.
MCRYPT_3DES
MCRYPT_ARCFOUR_IV (libmcrypt 2.4.x seulement)
MCRYPT_ARCFOUR (libmcrypt 2.4.x seulement)
MCRYPT_BLOWFISH
MCRYPT_CAST_128
MCRYPT_CAST_256
MCRYPT_CRYPT
MCRYPT_DES
MCRYPT_DES_COMPAT (libmcrypt 2.2.x seulement)
MCRYPT_ENIGMA (libmcrypt 2.4.x seulement, alias de MCRYPT_CRYPT)
MCRYPT_GOST
MCRYPT_IDEA (payant)
MCRYPT_LOKI97 (libmcrypt 2.4.x seulement)
MCRYPT_MARS (libmcrypt 2.4.x seulement, payant)
MCRYPT_PANAMA (libmcrypt 2.4.x seulement)
MCRYPT_RIJNDAEL_128 (libmcrypt 2.4.x seulement)
MCRYPT_RIJNDAEL_192 (libmcrypt 2.4.x seulement)
MCRYPT_RIJNDAEL_256 (libmcrypt 2.4.x seulement)
MCRYPT_RC2
MCRYPT_RC4 (libmcrypt 2.2.x seulement)
MCRYPT_RC6 (libmcrypt 2.4.x seulement)
MCRYPT_RC6_128 (libmcrypt 2.2.x seulement)
MCRYPT_RC6_192 (libmcrypt 2.2.x seulement)
MCRYPT_RC6_256 (libmcrypt 2.2.x seulement)
MCRYPT_SAFER64
MCRYPT_SAFER128
MCRYPT_SAFERPLUS (libmcrypt 2.4.x seulement)
MCRYPT_SERPENT (libmcrypt 2.4.x seulement)
MCRYPT_SERPENT_128 (libmcrypt 2.2.x seulement)
MCRYPT_SERPENT_192 (libmcrypt 2.2.x seulement)
MCRYPT_SERPENT_256 (libmcrypt 2.2.x seulement)
MCRYPT_SKIPJACK (libmcrypt 2.4.x seulement)
MCRYPT_TEAN (libmcrypt 2.2.x seulement)
MCRYPT_THREEWAY
MCRYPT_TRIPLEDES (libmcrypt 2.4.x seulement)
MCRYPT_TWOFISH (Pour les anciennes versions de mcrypt 2.x versions, ou mcrypt 2.4.x )
MCRYPT_TWOFISH128 (TWOFISHxxx sont disponibles avec les nouvelles versions de 2.x, mais pas dans les versions 2.4.x)
MCRYPT_TWOFISH192
MCRYPT_TWOFISH256
MCRYPT_WAKE (libmcrypt 2.4.x seulement)
MCRYPT_XTEA (libmcrypt 2.4.x seulement)
Vous devez (mode CFB et OFB) ou pouvez (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, vous pouvez prendre le résultat d'une fonction telle que MD5, appliquée sur le nom du fichier. Sinon, vous pouvez envoyer IV avec les données chiffrées, (reportez-vous au chapitre 9.3 de Applied Cryptography by Schneier (ISBN 0-471-11709-9) pour plus de détails sur le sujet).
- Table des matières
- mcrypt_cbc -- Chiffre/déchriffre des données en mode CBC
- mcrypt_cfb -- Chiffre/déchiffre des données en mode CFB
- mcrypt_create_iv -- Crée un vecteur d'initialisation à partir d'une source aléatoire.
- mcrypt_decrypt -- Déchiffre un texte
- mcrypt_ecb -- Chiffre/déchiffre des données en mode ECB
- mcrypt_enc_get_algorithms_name -- Retourne le nom de l'algorithme
- mcrypt_enc_get_block_size -- Retourne la taille de blocs 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_mode -- Teste le chiffrage par blocs d'un mode
- mcrypt_enc_is_block_algorithm -- Teste le chiffrage par blocs d'un algorithme
- 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_deinit -- This function deinitializes an encryption module
- mcrypt_generic_end -- Termine un chiffrage
- mcrypt_generic_init -- Initialise tous les buffers nécessaires
- mcrypt_generic -- Chiffre
- 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é d'un 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 -- Close the mcrypt module
- 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 -- Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm_mode -- Indique si un mode fonctionne par blocs
- mcrypt_module_is_block_algorithm -- Indique si un algorithme 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 le mode à utiliser
- mcrypt_module_self_test -- Teste un mode
- mcrypt_ofb -- Chiffre/déchiffre des données en mode OFB
- mdecrypt_generic -- Déchiffre
mcrypt_cbc
Description
string mcrypt_cbc ( int cipher, string key, string data, int mode [, string iv])string mcrypt_cbc ( string cipher, string key, string data, int mode [, string iv])
La première syntaxe utilise libmcrypt 2.2.x, et la seconde utilise libmcrypt 2.4.x.
mcrypt_cbc() chiffre ou déchiffre (suivant le mode sélectionné) les données data avec le chiffrement cipher et la clé key en mode CBC et retourne la chaîne résultant.
Cipher est une des constantes MCRYPT_ciphername
Key est la clé fournie à l'algorithme. Elle doit être tenue secrète.
Data sont les données à traiter.
Mode vaut MCRYPT_ENCRYPT ou MCRYPT_DECRYPT.
IV est le vecteur d'initialisation (optionnel).
Voir aussi: mcrypt_cfb(), mcrypt_ecb(), et mcrypt_ofb().
mcrypt_cfb
Description
string mcrypt_cfb ( int cipher, string key, string data, int mode, string iv)string mcrypt_cfb ( string cipher, string key, string data, int mode [, string iv])
La première syntaxe utilise libmcrypt 2.2.x, et la seconde utilise libmcrypt 2.4.x.
mcrypt_cfb() chiffre ou déchiffre (suivant le mode sélectionné) les données data avec le chiffrement cipher et la clé key en mode CFB et retourne la chaîne résultant.
Cipher est une des constantes MCRYPT_ciphername
Key est la clé fournie à l'algorithme. Elle doit être tenue secrète.
Data sont les données à traiter.
Mode vaut MCRYPT_ENCRYPT ou MCRYPT_DECRYPT.
IV est le vecteur d'initialisation (optionnel).
Voir aussi: mcrypt_cbc(), mcrypt_ecb(), et mcrypt_ofb().
mcrypt_create_iv
(PHP 3>= 3.0.8, PHP 4 )
mcrypt_create_iv -- Crée un vecteur d'initialisation à partir d'une source aléatoire.Description
string mcrypt_create_iv ( int size, int source)mcrypt_create_iv() sert à créer un IV (vecteur d'initialisation).
mcrypt_create_iv() prend deux arguments, size détermine la taille de IV, source spécifie la source de IV.
La source peut être MCRYPT_RAND (générateur de nombres aléatoires système), MCRYPT_DEV_RANDOM (lecture des données depuis le fichier /dev/random) et MCRYPT_DEV_URANDOM (lecture des données depuis le fichier /dev/urandom). Si vous utilisez MCRYPT_RAND, assurez-vous de bien appeler srand() pour initialiser le générateur de nombres aléatoires.
mcrypt_decrypt
Description
string mcrypt_decrypt ( string cipher, string key, string data, string mode [, string iv])Cipher est une constante MCRYPT_ciphername qui indique le nom de l'algorithme sous forme de chaîne.
Key est la clé utilisée pour chiffrer les données. Si elle est plus petite que nécessaire, elle sera complétée avec des '\0'.
Data sont les données qui doivent être encryptées. Si la taille des données n'est pas de la forme n * taille_de_bloc, elles seront complétées avec des '\0'. La valeur retournée peut être plus grande que la valeur d'origine.
Mode est une constante MCRYPT_MODE_modename qui peut valoir : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
IV (Vecteur d'initialisation) est utilisé pour les modes CBC, CFB, OFB, et dans certains algorithmes de mode STREAM. Si vous le fournissez par le VI, alors qu'il est nécessaire, la fonction affichera une alerte, et utilise un VI composé de caractères '\0'.
mcrypt_ecb
Description
string mcrypt_ecb ( int cipher, string key, string data, int mode)string mcrypt_ecb ( string cipher, string key, string data, int mode [, string iv])
La première syntaxe utilise libmcrypt 2.2.x, et la seconde utilise libmcrypt 2.4.x.
mcrypt_ecb() chiffre ou déchiffre (suivant le mode sélectionné) les données data avec le chiffrement cipher et la clé key en mode CFB et retourne la chaîne résultant.
Cipher est une des constantes MCRYPT_ciphername
Key est la clé fournie à l'algorithme. Elle doit être tenue secrète.
Data sont les données à traiter.
Mode vaut MCRYPT_ENCRYPT ou MCRYPT_DECRYPT.
IV est le vecteur d'initialisation (optionnel).
Voir aussi: mcrypt_cbc(), mcrypt_cfb(), et mcrypt_ofb().
mcrypt_enc_get_algorithms_name
Description
string mcrypt_enc_get_algorithms_name ( resource td)mcrypt_enc_get_algorithms_name() retourne le nom de l'algorithme désigné par td.
mcrypt_enc_get_block_size
Description
int mcrypt_enc_get_block_size ( resource td)mcrypt_enc_get_block_size() retourne la taille de blocs d'un algorithme, en octets.
mcrypt_enc_get_iv_size
Description
int mcrypt_enc_get_iv_size ( resource td)mcrypt_enc_get_iv_size() 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.
mcrypt_enc_get_key_size
Description
int mcrypt_enc_get_key_size ( resource td)mcrypt_enc_get_key_size() retourne la taille maximale de clé acceptée par le mode désigné par td, en octets.
mcrypt_enc_get_modes_name
Description
string mcrypt_enc_get_modes_name ( resource td)mcrypt_enc_get_modes_name() retourne le nom du mode désigné par td.
mcrypt_enc_get_supported_key_sizes
(PHP 4 >= 4.0.2)
mcrypt_enc_get_supported_key_sizes -- Retourne un tableau contenant les tailles de clés acceptées par un algorithmeDescription
array mcrypt_enc_get_supported_key_sizes ( resource td)mcrypt_enc_get_supported_key_sizes() 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.
mcrypt_enc_is_block_algorithm_mode
Description
int mcrypt_enc_is_block_algorithm_mode ( resource td)mcrypt_enc_is_block_algorithm_mode() retourne 1 si ce mode utilise des algorithmes par blocs, et 0 sinon. (i.e. 0 pour stream, et 1 pour cbc, cfb, ofb).
mcrypt_enc_is_block_algorithm
Description
int mcrypt_enc_is_block_algorithm ( resource td)mcrypt_enc_is_block_algorithm() retourne 1 si l'algorithme utilisé est un algorithme par blocs, et 0 si c'est un algorithme par flot.
mcrypt_enc_is_block_mode
Description
int mcrypt_enc_is_block_mode ( resource td)mcrypt_enc_is_block_mode() retourne 1 si le mode retourne des blocs d'octets, ou bien 0 s'il retourne des octets (par flot). (i.e. 1 pour cbc et ecb, et 0 pour cfb et stream).
mcrypt_enc_self_test
Description
int mcrypt_enc_self_test ( resource td)mcrypt_enc_self_test() effectue un test du module ouvert et désigné par td. Si le test est concluant, elle retourne 0, sinon, 1.
mcrypt_encrypt
Description
string mcrypt_encrypt ( string cipher, string key, string data, string mode [, string iv])mcrypt_encrypt() chiffre les données, et retourne les données cryptées.
Cipher est une constante MCRYPT_ciphername qui indique le nom de l'algorithme sous forme de chaîne.
Key est la clé utilisée pour chiffrer les données. Si elle est plus petite que nécessaire, elle sera complétée avec des '\0'.
Data sont les données qui doivent être encryptées. Si la taille des données n'est pas de la forme n * taille_de_bloc, elles seront complétées avec des '\0'. La valeur retournée peut être plus grande que la valeur d'origine.
Mode est une constante MCRYPT_MODE_modename qui peut valoir : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
IV (Vecteur d'initialisation) est utilisé pour les modes CBC, CFB, OFB, et dans certains algorithmes de mode STREAM. Si vous le fournissez par le VI, alors qu'il est nécessaire, la fonction affichera une alerte, et utilisera un vecteur d'initialisation composé de caractères '\0'.
Exemple 1. Exemple avec mcrypt_encrypt()
|
mcrypt_generic_deinit
Description
bool mcrypt_generic_deinit ( resource td)This function terminates encryption specified by the encryption descriptor (td). It clears all buffers, but does not close the module. You need to call mcrypt_module_close() yourself. (But PHP does this for you at the end of the script. Returns FALSE on error, or TRUE on succes.
See for an example mcrypt_module_open() and the entry on mcrypt_generic_init().
mcrypt_generic_end
Description
boolean mcrypt_generic_end ( resource td)mcrypt_generic_end() termine le chiffrage désigné par le pointeur td. En fait, elle supprime tous les buffers, et ferme les modules utilisés. Elle retourne FALSE en cas d'erreur, et TRUE sinon.
mcrypt_generic_init
Description
int mcrypt_generic_init ( resource td, string key, string iv)La taille maximale de la clé doit être cette retournée par mcrypt_enc_get_key_size() et toutes les valeurs inférieures seront aussi valides. Le vecteur d'initialisation (VI) doit avoir la taille d'un bloc, mais vous devez 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 chiffrage et le déchiffrage. Si vous ne voulez pas l'utiliser, remplissez le de zéros, mais ce n'est pas recommandé. La fonction retourne (-1) en cas d'erreur.
Vous devez appeler mcrypt_generic_init() avant chaque appel à mcrypt_generic() ou mdecrypt_generic().
mcrypt_generic
Description
string mcrypt_generic ( resource td, string data)mcrypt_generic() chiffre des données. Les données sont complétées par des "\0" pour obtenir une taille de n fois la taille d'un bloc. Elle retourne les données encryptées. Notez que la longueur de la chaîne retournée peut être plus longue que celle passée en argument, à cause du complément.
mcrypt_get_block_size
Description
int mcrypt_get_block_size ( int cipher)int mcrypt_get_block_size ( string cipher, string module)
mcrypt_get_block_size() sert à lire la taille de blocs du chiffrement cipher.
mcrypt_get_block_size() prend comme argument le chiffrement cipher et retourne une taille en octets.
Voir aussi : mcrypt_get_key_size().
mcrypt_get_cipher_name
Description
string mcrypt_get_cipher_name ( int cipher)string mcrypt_get_cipher_name ( string cipher)
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, si ce chiffrement n'existe pas.
L'exemple ci-dessus va donner : TripleDES
mcrypt_get_iv_size
(PHP 4 >= 4.0.2)
mcrypt_get_iv_size -- Retourne la taille du VI utilisé par un couple chiffrement/modeDescription
int mcrypt_get_iv_size ( string cipher, string mode)int mcrypt_get_iv_size ( resource td)
La première syntaxe utilise libmcrypt 2.2.x, et la seconde utilise libmcrypt 2.4.x.
mcrypt_get_iv_size() retourne la taille du Vecteur d'initialisation (VI). En cas d'erreur, la fonction retourne FALSE. Si le VI est ignoré dans le couple chiffrement/mode demandé, zéro est retourné.
Cipher est une constante MCRYPT_ciphername qui indique le nom de l'algorithme sous forme de chaîne.
Mode est une constante MCRYPT_MODE_modename qui peut valoir : "ecb", "cbc", "cfb", "ofb", "nofb" ou "stream".
mcrypt_get_key_size
Description
int mcrypt_get_key_size ( int cipher)int mcrypt_get_key_size ( string cipher, string module)
mcrypt_get_key_size() sert à lire la taille de clé du chiffrement cipher.
mcrypt_get_block_size() prend comme argument le chiffrement cipher et retourne une taille en octets.
Voir aussi: mcrypt_get_block_size().
mcrypt_list_algorithms
Description
array mcrypt_list_algorithms ( [string lib_dir])mcrypt_list_algorithms() sert à lister tous les algorithmes de chiffrement de lib_dir. mcrypt_list_algorithms() prend un argument optionnel, qui spécifie le dossier qui contient tous les algorithmes. S'il est omis, la valeur de mcrypt.algorithms_dir dans php.ini est utilisée.
L'exemple ci-dessus va afficher tous les algorithmes supportés dans le dossier "/usr/local/lib/libmcrypt".
mcrypt_list_modes
Description
array mcrypt_list_modes ( [string lib_dir])mcrypt_list_algorithms() sert à lister tous les modes de chiffrement de lib_dir. mcrypt_list_algorithms() prend un argument optionnel, qui spécifie le dossier qui contient tous les algorithmes. S'il est omis, la valeur de mcrypt.algorithms_dir dans php.ini est utilisée.
L'exemple ci-dessus va afficher tous les modes supportés dans le dossier "/usr/local/lib/libmcrypt".
mcrypt_module_close
Description
bool mcrypt_module_close ( resource td)This function closes the specified encryption handle.
See mcrypt_module_open() for an example.
mcrypt_module_get_algo_block_size
Description
int mcrypt_module_get_algo_block_size ( string algorithm [, string lib_dir])mcrypt_module_get_algo_block_size() retourne la taille de blocs d'un algorithme, en octets. Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_get_algo_key_size
Description
int mcrypt_module_get_algo_key_size ( string algorithm [, string lib_dir])mcrypt_module_get_algo_key_size() retourne la taille maximale de la clé supportée par l'algorithme algorithm. Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_get_supported_key_sizes
(PHP 4 >= 4.0.2)
mcrypt_module_get_supported_key_sizes -- Returns an array with the supported keysizes of the opened algorithmDescription
array mcrypt_module_get_supported_key_sizes ( string algorithm [, string lib_dir])Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm. The optional lib_dir parameter can contain the location where the mode module is on the system.
See also mcrypt_enc_get_supported_key_sizes() which is used on open encryption modules.
mcrypt_module_is_block_algorithm_mode
Description
boolean mcrypt_module_is_block_algorithm_mode ( string mode [, string lib_dir])mcrypt_module_is_block_algorithm_mode() retourne TRUE si le mode doit être utilisé avec un algorithme par bloc, sinon retourne 0 (i.e. 0 pour stream, et 1 pour cbc, cfb, ofb). Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_is_block_algorithm
Description
boolean mcrypt_module_is_block_algorithm ( string algorithm [, string lib_dir])mcrypt_module_is_block_algorithm() retourne TRUE si algorithm est un algorithme par bloc, sinon retourne 0. Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_is_block_mode
Description
boolean mcrypt_module_is_block_mode ( string mode [, string lib_dir])mcrypt_module_is_block_mode() retourne TRUE si ce mode fournit des blocs d'octets, ou bien un flot d'octets. (i.e. 1 pour cbc et ecb, et 0 pour cfb et stream). Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_open
Description
resource mcrypt_module_open ( string algorithm, string algorithm_directory, string mode, string mode_directory)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 librairie est refermée en appelant mcrypt_module_close, mais il n'est pas nécessaire d'appeler cette fonction si mcrypt_generic_end() est utilisé. Normalement, mcrypt_module_open() retourne un pointeur d'encryption, ou bien FALSE en cas d'erreur.
algorithm_directory et mode_directory servent à repérer les modules d'encryption. Si vous fournissez un nom de dossier, il sera utilisé. Si vous passez une chaîne vide (""), la valeur utilisé par mcrypt.algorithms_dir ou mcrypt.modes_dir sera celle indiquée dans les directives de configuration. Lorsque ces paramètres ne sont pas fournis les valeurs par défaut, compilées avec la librairie sont utilisées. (généralement /usr/local/lib/libmcrypt).
mcrypt_module_self_test
Description
boolean mcrypt_module_self_test ( string algorithm [, string lib_dir])mcrypt_module_self_test() effectue un test sur l'algorithme spécifié. Le paramètre optionnel lib_dir contient le chemin jusqu'au module de l'algorithme sur le système.
mcrypt_module_self_test() retourne TRUE si le test fonctionne, et FALSE sinon.
mcrypt_ofb
Description
string mcrypt_ofb ( int cipher, string key, string data, int mode, string iv)string mcrypt_ofb ( string cipher, string key, string data, int mode [, string iv])
La première syntaxe utilise libmcrypt 2.2.x, et la seconde utilise libmcrypt 2.4.x.
mcrypt_ofb() chiffre ou déchiffre (suivant le mode sélectionné) les données data avec le chiffrement cipher et la clé key en mode OFB et retourne la chaîne résultant.
Cipher est une des constantes MCRYPT_ciphername
Key est la clé fournie à l'algorithme. Elle doit être tenue secrète.
Data sont les données à traiter.
Mode vaut MCRYPT_ENCRYPT ou MCRYPT_DECRYPT.
IV est le vecteur d'initialisation (optionnel).
Voir aussi: mcrypt_cbc(), mcrypt_cfb(), et mcrypt_ecb().
mdecrypt_generic
Description
string mdecrypt_generic ( resource td, string data)mdecrypt_generic() déchiffre les données data. Notez que la longueur de la chaîne décryptée peut être plus longue que la chaîne originale, car elle peut avoir été complétée par des "\0".
Exemple 1. Exemple avec mdecrypt_generic()
|
LVI. Hash
Ces fonctions ont été prévues pour fonctionner avec mhash.
Cet ensemble de fonctions représente une interface avec la librairie mhash. mhash accepte un grand nombre d'algorithmes différents, tels que MD5, SHA1, GOST, bien d'autres.
Pour l'utiliser, téléchargez les distributions de mhash depuis le site web ici et suivez les instructions d'installation incluses. Vous aurez besoin de recompiler PHP avec l'option --with-mhash pour activer cette extension.
mhash sert à calculer des sommes de vérification, des signatures de message, etc...
Voici une liste de hash qui sont actuellement supportés par mhash. Si un hash n'est pas dans la liste, mais qu'il est disponible avec mhash, c'est que ce document a pris de l'âge.
MHASH_MD5
MHASH_SHA1
MHASH_HAVAL
MHASH_RIPEMD160
MHASH_RIPEMD128
MHASH_SNEFRU
MHASH_TIGER
MHASH_GOST
MHASH_CRC32
MHASH_CRC32B
- Table des matières
- mhash_count -- retourne 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é
- mhash -- Calcule un hash.
mhash_count
Description
int mhash_count ( void)mhash_count() retourne l'identifiant de hash maximal. Les hash sont numérotés de 0 jusqu'à cet identifiant.
mhash_get_block_size
Description
int mhash_get_block_size ( int hash)mhash_get_block_size() sert à connaître la taille de bloc du hash spécifié hash.
mhash_get_block_size() prend un seul argument : le hash et retourne la taille en octets, ou bien FALSE si le hash n'existe pas.
mhash_get_hash_name
Description
string mhash_get_hash_name ( int hash)mhash_get_hash_name() sert à connaître le nom d'un hash.
mhash_get_hash_name() prend un numero d'identifiant de hash, et retourne son nom, ou bien FALSE si le hash n'existe pas, ou si une erreur est survenue.
mhash_keygen_s2k
Description
string mhash_keygen_s2k ( int hash, string password, string salt, int bytes)mhash_keygen_s2k() génère une clé de bytes octets de long, à partir d'un mot de passe. Cette fonction utilise l'algorithme Salted S2K, spécifié dans OpenPGP (RFC 2440). Cet algorithme va utiliser l'algorithme de hashage hash pour créer la clé. Le paramètre salt doit être différent et suffisamment aléatoire pour chaque clé que vous génèrez, afin de créer des clés différentes. Ce grain de sel réservira lorsque vous vérifierez les clés : c'est alors une bonne idée que de l'ajouter à la fin de la clé générée. salt doit avoir la longueur de 8 octets, et sera complété par des 0 si vous ne fournissez par suffisamment de données. N'oubliez pas que les mots de passe fournis par les utilisateurs ne sont pas conseillé pour faire des clés cryptographique, étant donné que les utilisateurs normaux retiennent des mots de passe qu'ils peuvent saisir au clavier. Ces mots de passe utilisent uniquement 6 à 7 des 8 bits d'un caractère (voir moins). Il est vivement recommandé d'appliquer une fonction de transformation (comme celle-ci), à un mot de passe utilisateur.
mhash
LVII. Mimetype Functions
Introduction
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
This extension is derivated from Apache mod_mime_magic, which is itself based on the file command maintaind by Ian F. Darwin. See the source code for further historic and copyright information.
Requirements
These functions are available as part of the standard module, which is always available.
Installation
The extension needs a copy of the magic.mime as distributed with the file command. This file also part of most recent Linux distributions and usually stored in the /usr/share/misc directory.
- Table des matières
- mime_content_type -- Detect MIME Content-type for a file
mime_content_type
LVIII. Microsoft SQL Server
L'extension MSSQL n'est disponible que sous Windows 32 bits. Vous pouvez utiliser l'extension Sybase pour vous connecter à un serveur MSSQL, depuis d'autres plate-formes.
Ces fonctions vous permettent d'accéder aux serveurs de données MS SQL. Vous avez besoin d'un client MS SQL Client Tools sur votre système, accessible à PHP. Les Client Tools peuvent être installé depuis le CD MS SQL Server CD ou en copiant ntwdblib.dll depuis le dossier \winnt\system32 du serveur MS SQL vers \winnt\system32 sur le serveur PHP. Copier ntwdblib.dll ne fera que fournir le moyen d'accès. La configuration du client requiert l'installation des autres outils.
L'extension MSSQL est activée par la ligne extension=php_mssql.dll dans le fichier php.ini.
- Table des matières
- mssql_bind -- Adds a parameter to a stored procedure or a remote stored procedure
- mssql_close -- Ferme une connexion MS SQL Server.
- mssql_connect -- Ouvre une connexion à un serveur MS SQL server.
- mssql_data_seek -- Déplace le pointeur interne de ligne.
- mssql_execute -- Executes a stored procedure on a MS SQL server database
- mssql_fetch_array -- Lit une ligne dans un tableau.
- mssql_fetch_assoc -- Returns an associative array of the current row in the result set specified by result_id
- mssql_fetch_batch -- Returns the next batch of records
- mssql_fetch_field -- Lit les inforamtions sur le champs.
- mssql_fetch_object -- Retourne une ligne sous la forme d'un objet.
- mssql_fetch_row -- Lit une ligne comme un tableau.
- mssql_field_length -- Lit la longueur d'un champs.
- mssql_field_name -- Lit le nom d'un champs.
- mssql_field_seek -- Fixe l'offset du pointeur de champs.
- mssql_field_type -- Lit le nom d'un champs.
- mssql_free_result -- Libère la mémoire.
- mssql_get_last_message -- Retourne le dernier message d'erreur du serveur ( min_message_severity?).
- mssql_guid_string -- Converts a 16 byte binary GUID to a string
- mssql_init -- Initializes a stored procedure or a remote stored procedure
- mssql_min_error_severity -- Fixe le niveau de sévérité des erreurs.
- mssql_min_message_severity -- Fixe le niveau de sévérité des messages d'erreurs.
- fbsql_next_result -- Déplace le pointeur interne vers le résultat suivant
- mssql_num_fields -- Retourne le nombre de champs dans un résultat.
- mssql_num_rows -- Retourne le nombre de lignes dans un résultat.
- mssql_pconnect -- Ouvre une connexion persistante à un serveur MS SQL.
- mssql_query -- Envoie une requête SQL.
- mssql_result -- Lit les données d'un résultat.
- mssql_rows_affected -- Returns the number of records affected by the query
- mssql_select_db -- Sélectionne la base de données MS SQL.
mssql_bind
Description
int mssql_bind ( int stmt, string param_name, mixed var, int type [, int is_output [, int is_null [, int maxlen]]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_close
Description
boolean mssql_close ( [resource link_identifier])mssql_close() retourne TRUE en cas de succès, ou FALSE sinon.
mssql_close() ferme la connexion à la base MS SQL Server, qui était associé à l'identifiant link_identifier. Si ce dernier n'est pas précisé, la dernière connexion ouverte sera fermée.
Notez qu'il n'est pas nécessaire de fermer les connexions non persistantes aux bases de données, car elles seront fermées automatiquement à la fin du script.
mssql_close() ne peut pas fermer les liens persistants, générés par mssql_pconnect().
Voir aussi mssql_connect() et mssql_pconnect().
mssql_connect
Description
resource mssql_connect ( [string servername [, string username [, string password]]])mssql_connect()r etourne un identifiant positif de lien en cas de succès, et FALSE sinon.
mssql_connect() établit une connexion à un serveur MS SQL. Le nom du serveur servername doit être valide, comme défini dans les fichiers d'interface.
Si un deuxième appel est fait à mssql_connect() avec les mêmes arguments, un nouveau lien ne sera pas retourné, mais le lien déjà ouvert sera retourné.
Le lien avec le serveur sera fermé dès la fin du script, ce qui fait qu'on n'est pas obligé de fermer explicitement la connexion à la fin du script avec mssql_close().
Voir aussi mssql_pconnect() et mssql_close().
mssql_data_seek
Description
int mssql_data_seek ( resource result_identifier, int row_number)mssql_data_seek() retourne TRUE en cas de succès, FALSE en cas d'échec.
mssql_data_seek() déplace le pointeur interne de ligne, dans le résultat result_identifier, jusqu'à la ligne row_number. Le prochain appel à mssql_fetch_row() retournera cette ligne.
Voir aussi mssql_data_seek().
mssql_execute
Description
int mssql_execute ( int stmt)
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_fetch_array
Description
int mssql_fetch_array ( resource result)mssql_fetch_array() retourne un tableau qui contient les valeurs de la ligne lues, en cas de succès, et FALSE en cas d'échec.
mssql_fetch_array() est une version améliorée de mssql_fetch_row(). En plus de stocker les données dans un tableau à index numérique, elle les stocke aussi dans un tableau associatif, en utilisant les noms de colonnes comme clé.
Une chose importante à noter est que mssql_fetch_array() n'est PAS significativement plus lente que mssql_fetch_row(), tandis qu'elle apporte un confort apréciable.
Pour plus de détails, voyez mssql_fetch_row().
mssql_fetch_assoc
(PHP 4 >= 4.2.0)
mssql_fetch_assoc -- Returns an associative array of the current row in the result set specified by result_idDescription
array mssql_fetch_assoc ( int result_id [, int result_type])
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_fetch_batch
Description
int mssql_fetch_batch ( string result_index)
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_fetch_field
Description
object mssql_fetch_field ( resource result [, int field_offset])mssql_fetch_field() retourne un objet contenant les informations sur un champs.
mssql_fetch_field() sert à lire des informations spécifiques à un champs, dans un résultat de requête. Si l'offset du champs field_offset n'est pas précisé, le prochain champs sera analysé.
Les propriétés de l'objet sont :
name - nom de la colonne. Si la colonne est le résultat d'une fonction, le nom de la colonne sera computed#N, où #N est un numéro de série.
column_source - le nom de la table d'où la colonne est originaire.
max_length - taille maximale de la colonne
numeric - 1 si la colonne est numérique
Voir aussi mssql_field_seek().
mssql_fetch_object
Description
object mssql_fetch_object ( resource result)mssql_fetch_object() retourne un objet dont les propriétés contiennent les valeurs de la ligne, ou FALSE si il n'y a plus de ligne.
mssql_fetch_object() est similaire à mssql_fetch_array(), avec un différence : un objet est retourné, au lieu d'un tableau. Indirectement, cela signifie que vous ne pouvez accéder aux données que par leur nom de champs, et pas par leur offset (les nombres sont illégaux comme nom de propriété).
En terme de vitesse, cette fonction est identique à mssql_fetch_array(), quasiment aussi rapide que mssql_fetch_row() (la différence est non significative).
Voir aussi mssql_fetch_array() et mssql_fetch_row().
mssql_fetch_row
Description
array mssql_fetch_row ( resource result)mssql_fetch_row() retourne un tableau qui contient les valeurs de la ligne à lire, ou bien FALSE si il n'y a plus de lignes à lire.
mssql_fetch_row() lit une ligne dans le résultat result et place les valeurs dans un tableau. Chaque valeur est enregistré dans un élément du tableau, et les indices commencent à 0.
Les appels suivants à mssql_fetch_row() retourneront la ligne suivante, ou bien FALSE s'il ne reste plus de lignes.
Voir aussi mssql_fetch_array(), mssql_fetch_object(), mssql_data_seek() et mssql_result().
mssql_field_length
mssql_field_name
mssql_field_seek
Description
int mssql_field_seek ( resource result, int field_offset)mssql_field_seek() modifie la valeur du pointeur de champs. Le prochain appel à mssql_fetch_field() qui ne précisera pas de numéro de champs, le champs fixé par mssql_field_seek() sera retournée.
Voir aussi mssql_fetch_field().
mssql_field_type
mssql_free_result
Description
int mssql_free_result ( resource result)mssql_free_result() n'a besoin d'être appelé que si on craint d'utiliser trop de mémoire durant une opération. Toutes les ressources liées à un résultat seront libérés par mssql_free_result().
mssql_get_last_message
(PHP 3, PHP 4 )
mssql_get_last_message -- Retourne le dernier message d'erreur du serveur ( min_message_severity?).mssql_guid_string
Description
string mssql_guid_string ( string binary [, int short_format])
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_init
Description
int mssql_init ( string sp_name [, int conn_id])
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_min_error_severity
mssql_min_message_severity
fbsql_next_result
Description
bool mssql_next_result ( resource result_id)Lorsque vous envoyez plus d'une commande SQL au serveur, ou que vous exécutez une procédure stockée avec de multiple résultats, cela va conduire le serveur à retourner plusieurs jeu de lignes. mssql_next_result() va vérifier l'existence de plusieurs résultats disponibles sur le serveur. Si un autre jeu de résultat existe, mssql_next_result() va détruire de résultat précédent, et préparer la lecture dans les nouvelles lignes.
mssql_next_result() retourne TRUE si un autre résultat est disponbile, ou FALSE sinon.
Exemple 1. Exemple avec mssql_next_result()
|
mssql_num_fields
Description
int mssql_num_fields ( resource result)mssql_num_fields() retourne le nombre de champs dans un résultat.
Voir aussi mssql_query(), mssql_fetch_field() et mssql_num_rows().
mssql_num_rows
Description
int mssql_num_rows ( resource result)mssql_num_rows() retourne le nombre de lignes dans un résultat.
Voir aussi mssql_query() et mssql_fetch_row().
mssql_pconnect
Description
resource mssql_pconnect ( [string servername [, string username [, string password]]])mssql_pconnect() retourne un identifiant positif de lien MS SQL en cas de succès, et FALSE en cas d'erreur.
mssql_pconnect() se comporte comme mssql_connect() mais avec deux différences :
Premièrement, lors de la connexion, la fonction va commencer par rechercher un lien persistant déjà ouvert avec le même hôte, le même nom d'utilisateur, username et le même mot de passe password. Si un tel lien est trouvé, cet identifiant sera retourné, au lieux d'en ouvrir une autre connexion.
Deuxièmement, la connexion au serveur SQL ne sera pas fermée à la fin du script, mais restera ouverte, pour d'autres utilisations ultérieures (mssql_close() ne fermera pas un lien établi avec mssql_pconnect()).
C'est pourquoi ce type de lien est dit 'persistant'.
mssql_query
Description
resource mssql_query ( string query [, resource link_identifier])mssql_query() retourne un identifiant positif de résultat en cas de succès, ou FALSE sinon.
mssql_query() envoie la requête au serveur courant, associé à l'identifiant link_identifier (ou la base par défaut, s'il est omis). Si aucun lien n'est ouvert, mssql_query() essaiera d'en ouvrir une, en appelant mssql_connect().
Voir aussi mssql_select_db() et mssql_connect().
mssql_result
Description
int mssql_result ( mssql_query result, int i, mixed field)mssql_result() retourne la valeur de la colonne, à la ligne donnée, dans le résultat MS SQL, ou FALSE en cas d'erreur.
mssql_result() retourne le contenu d'une des cellules d'un résultat MS SQL. Le nom du champs peut être son nom littéral ou son offet, ou encore, le nom de la table + "." + le nom du champs, ou encore la même chose avec le nom de la base de données. Si la colonne a été aliasée, utilisez le nom de l'alias plutôt que celui de la colonne.
Lorsque vous travaillez sur des résultats de grande taille, il vaut mieux utiliser les fonctions qui récupèrent toute une ligne (voir ci après). Comme ces fonctions lisent toutes les valeurs en une passe, elles sont EXTREMEMENT PLUS RAPIDES que mssql_result(). De plus, pensez que l'utilisation de l'offset numérique est beaucoup plus rapide que l'utilisation du nom de la colonne.
Alternatives recommandées : mssql_fetch_row(), mssql_fetch_array() et mssql_fetch_object().
mssql_rows_affected
Description
int mssql_rows_affected ( int conn_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
mssql_select_db
Description
int mssql_select_db ( string database_name [, resource link_identifier])mssql_select_db() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
mssql_select_db() sélectionne la base de données active. Si aucun identifiant de connexion n'est fourni, la fonction utilisera la dernière connexion ouverte. Si aucune connexion n'a été ouverte, la fonction essaiera d'en ouvrir une avec mssql_connect(), et de l'utiliser.
Tous les appels à mssql_query() seront faits dans cette base.
Voir aussi mssql_connect(), mssql_pconnect() et mssql_query().
LIX. Ming pour Flash
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Introduction
Ming est une librairie open-source (LGPL) qui vous permet de créer des animations au format Flash. Ming supporte toutes les fonctionnalités de Flash 4 : les formes (shapes), les gradients, les images bitmaps (JPEG et PNG), les morphing (transformations d'une forme en une autre), les textes, actions, sprites (mini animations), le streaming MP3 et les transformations de couleurs. Le seul ajout futur est celui des événements sons.
Ming n'est pas un acronyme.
Notez que toutes les distances spécifiées (longueurs, distances, tailles...) sont en "twips", c'est-à-dire 20 unités par pixels. C'est plus ou moins arbitraire, car le lecteur Flash fait une mise à l'échelle avec les valeurs qui lui sont fournis dans la balise embed, ou la frame courante si la balise embed n'est pas utilisée.
Ming propose de nombreux avantages par rapport à l'extension swf. Vous pouvez utiliser Ming sur tous les OS où vous pouvez compiler le code, tandis que swf est limité à Windows. Ming vous évite la déconcertante complexité du format SWF, en transformant les éléments des animations en objets PHP. Enfin, Ming est toujours en cours de développement et surveillé par son auteur : si vous souhaitez une nouvelle fonctionnalité, dites le lui : ming@opaque.net.
Ming et tous les objets cités ont été ajouté en PHP 4.0.5.
Installation
Pour utiliser Ming avec PHP, vous devez d'abord installer la librairy Ming. Le code source et les instructions d'installation sont disponible sur la page d'accueil de Ming : http://www.opaque.net/ming/, avec des exemples un tutorial et l'actualité Ming.
Téléchargez l'archive Ming. Décompressez la et allez dans le dossier Ming. Faites "make", puis "make install".
Cela va compiler le fichier libming.so et l'installer dans /usr/lib/, et copier ming.h into /usr/include/. Editez la ligne PREFIX= dans le fichier Makefile pour indiquer votre dossier d'installation.
Compilation CGI avec PHP (Unix)
mkdir <phpdir>/ext/ming
cp php_ext/* <phpdir>/ext/ming
cd <phpdir>
./buildconf
./configure --with-ming <other config options>
Compilez et installez PHP comme d'habitude.
Redémarrez votre serveur web si nécessaire.
Compilation en module avec PHP (Unix)
téléchargez php_ming.so.gz. Décompressez le et copiez le dans votre dossier de modules PHP (vous pouvez trouver votre dossier de module PHP en utilisant la commande php-config --extension-dir). Ensuite, ajoutez la ligne extension=php_ming.so dans votre fichier php.ini, ou bien ajoutez dl('php_ming.so'); en haut de tous vos scripts Ming.
Comment utiliser Ming
Ming introduit 13 objet en PHP. Pour les utilisez, vous devez être familier avec les objets.
- Table des matières
- ming_setcubicthreshold -- Set cubic threshold (?)
- ming_setscale -- Set scale (?)
- ming_useswfversion -- Use SWF version (?)
- SWFAction -- Crée une nouvelle action.
- SWFBitmap->getHeight -- Retourne la hauteur d'une bitmap.
- SWFBitmap->getWidth -- Retourne la largeur d'une bitmap.
- SWFBitmap -- Crée un objet bitmap
- swfbutton_keypress -- Returns the action flag for keyPress(char)
- SWFbutton->addAction -- Ajoute une action au bouton
- SWFbutton->addShape -- Ajoute une forme à un bouton
- SWFbutton->setAction -- Assigne l'action du bouton
- SWFbutton->setDown -- Alias de addShape(shape, SWFBUTTON_DOWN)
- SWFbutton->setHit -- Alias de addShape(shape, SWFBUTTON_HIT)
- SWFbutton->setOver -- Alias de addShape(shape, SWFBUTTON_OVER)
- SWFbutton->setUp -- Alias de SWFbutton->addShape(shape, SWFBUTTON_UP)
- SWFbutton -- Crée un nouveau bouton.
- SWFDisplayItem->addColor -- Ajoute une couleur à une transoformation.
- SWFDisplayItem->move -- Déplace un objet en coordonnées relatives.
- SWFDisplayItem->moveTo -- Déplace un objet en coordonnées globales.
- SWFDisplayItem->multColor -- Multiplie la couleur de transformation.
- SWFDisplayItem->remove -- Supprime un objet d'une animation
- SWFDisplayItem->Rotate -- Fait tourner une forme relativement.
- SWFDisplayItem->rotateTo -- Tourne un objet en angle absolu.
- SWFDisplayItem->scale -- Etire un objet relativement.
- SWFDisplayItem->scaleTo -- Etire un objet en coordonnées globales.
- SWFDisplayItem->setDepth -- Modifie la place en profondeur (z-order)
- SWFDisplayItem->setName -- Nomme un objet
- SWFDisplayItem->setRatio -- Modifie le ratio de l'objet.
- SWFDisplayItem->skewX -- Incline suivant les X relativement.
- SWFDisplayItem->skewXTo -- Incline suivant les X.
- SWFDisplayItem->skewY -- Incline suivant les Y relativement.
- SWFDisplayItem->skewYTo -- Incline suivant les Y.
- SWFDisplayItem -- Crée un nouvel objet d'affichage displayitem.
- SWFFill->moveTo -- Déplace l'origine de l'objet SWFFill
- SWFFill->rotateTo -- Tourne la forme
- SWFFill->scaleTo -- Modifie l'échelle de la forme
- SWFFill->skewXTo -- Incline (abscisses)
- SWFFill->skewYTo -- Incline (ordonnées)
- SWFFill -- Crée un objet de remplissage
- swffont->getwidth -- Retourne la taille de la chaîne
- SWFFont -- Charge une police
- SWFGradient->addEntry -- Ajoute une couleur à la liste du gradient.
- SWFGradient -- Crée un objet gradient
- SWFMorph->getshape1 -- Sélectionne la forme de départ
- SWFMorph->getshape2 -- Sélectionne la forme de fin
- SWFMorph -- Crée un morphing.
- SWFMovie->add -- Ajoute un objet dans une animation.
- SWFMovie->nextframe -- Passe à l'image suivante.
- SWFMovie->output -- Envoie votre animation au navigateur.
- SWFMovie->remove -- Supprime un objet d'une animation.
- SWFMovie->save -- Sauve dans un fichier.
- SWFMovie->setbackground -- Modifie la couleur de fond.
- SWFMovie->setdimension -- Modifie les dimensions de l'animation.
- SWFMovie->setframes -- Modifie le nombre total d'images dans l'animation.
- SWFMovie->setrate -- Modifie la vitesse de l'animation.
- SWFMovie->streammp3 -- Envoie un fichier MP3 en streaming.
- SWFMovie -- Crée un objet 'animation'.
- SWFShape->addFill -- Ajoute un remplissage plein à la forme.
- SWFShape->drawCurve -- Dessine une courbe relativement.
- SWFShape->drawCurveTo -- Dessine une courbe.
- SWFShape->drawLine -- Dessine une ligne relativement.
- SWFShape->drawLineTo -- Dessine une ligne.
- SWFShape->movePen -- Déplace le stylo relativement.
- SWFShape->movePenTo -- Déplace le stylo.
- SWFShape->setLeftFill -- Modifie la couleur de rastérisation de gauche.
- SWFShape->setLine -- Modifie le style de ligne de la forme.
- SWFShape->setRightFill -- Modifie la couleur de rastériation de droite.
- SWFShape -- Crée une nouvelle forme.
- SWFSprite->add -- Ajoute un objet à un sprite
- SWFSprite->nextframe -- Va à la prochaine image du sprite.
- SWFSprite->remove -- Supprime un objet dans un sprite
- SWFSprite->setframes -- Fixe le nombre maximum d'image dans le sprite.
- SWFSprite -- Crée un sprite
- SWFText->addString -- Ajoute du texte
- SWFText->getWidth -- Calcule la longueur d'une chaîne
- SWFText->moveTo -- Déplace le stylo de texte
- SWFText->setColor -- Modifie la couleur de la police
- SWFText->setFont -- Sélectionne la police courante
- SWFText->setHeight -- Modifie la hauteur de la police courante
- SWFText->setSpacing -- Modifie l'espacement de police
- SWFText -- Crée un nouvel objet texte.
- SWFTextField->addstring -- Ajoute au texte
- SWFTextField->align -- Modifie l'alignement du texte
- SWFTextField->setbounds -- Sélectionne la largeur et hauteur du champs
- SWFTextField->setcolor -- Modifie la couleur du champs texte
- SWFTextField->setFont -- Modifie la police du champs
- SWFTextField->setHeight -- Modifie la hauteur de la police du champs texte.
- SWFTextField->setindentation -- Modifie l'indentation de la première ligne.
- SWFTextField->setLeftMargin -- Modifie la marge de gauche.
- SWFTextField->setLineSpacing -- Modifie l'espacement de lignes.
- SWFTextField->setMargins -- Modifie les marges du champs texte.
- SWFTextField->setname -- Nomme le champs texte
- SWFTextField->setrightMargin -- Modifie la marge de droite.
- SWFTextField -- Crée un nouveau champs texte
ming_setcubicthreshold
Description
void ming_setcubicthreshold ( int threshold)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ming_setscale
Description
void ming_setscale ( int scale)
| Avertissement |
This function is currently not documented, only the argument list is available. |
ming_useswfversion
Description
void ming_useswfversion ( int version)
| Avertissement |
This function is currently not documented, only the argument list is available. |
SWFAction
Description
new swfaction ( string script)swfaction() crée une nouvelle action, et compile le script script.
La syntaxe du script est basée sur le langage C, mais il utilise aussi beaucoup de notions propres à SWF : le bytecode SWF est trop simpliste pour faire l'essentiel de ce que l'on veut. Par exemple, il n'est pas possible de faire des fonctions sans descendre profondément dans les entrailles de la machine, car le bytecode de saut est écrit en dur. Pas moyen de pousser une adresse dans la pile, ou de dépiler - Chaque fonction doit savoir exactement où elle retourne.
Alors, que reste-t-il? Le compilateur reconnaît les mots suivants :
break
for
continue
if
else
do
while
Il n'y a pas de type de données : toutes les valeurs de SWF sont stockées comme des chaînes de caractères. Les fonctions suivantes peuvent être utilisées dans les expressions :
- time()
Retourne le nombre de milli-secondes depuis le début de l'animation.
- random(seed)
Retourne un nombre pseudo-aléatoire, entre 0 et seed.
- length(expr)
Retourne la taille de l'expression donnée.
- int(number)
Retourne le nombre number, arrondi à l'entier inférieur le plus proche.
- concat(expr, expr)
Retourne la concaténation des deux expressions.
- ord(expr)
Retourne le code ASCII du caractère expr.
- chr(num)
Retourne le caractère pour le code ASCII num.
- substr(string, location, length)
Retourne la sous-chaîne, extraite de string, de longueur length et commençant au caractère location.
De plus, les commandes suivantes sont accessibles :
- duplicateClip(clip, name, depth)
Duplique le sprite nommé clip. La nouvelle animation a le nouveau nom name et la profondeur depth.
- removeClip(expr)
Supprime l'animation nommée expr.
- trace(expr)
Ecrit l'expression expr dans le fichier de d'historique. Il est peut probable que le navigateur ou le lecteur ne fasse quoi que ce soit avec.
- startDrag(target, lock, [left, top, right, bottom])
Comment à déplacer l'animation target. L'argument lock indique si le déplacement verrouille la souris (utilisez 0, FALSE) ou 1 (TRUE)). Les paramètres optionnels délimitent la zone de déplacement.
- stopDrag()
Cesse le déplacement de l'animation.
- callFrame(expr)
Appelle l'image expr comme une fonction.
- getURL(url, target, [method])
Charge l'URL url dans l'objet target. target peut être l'image courante (je pense) ou une des valeurs magiques "_level0" (remplace l'animation courante) ou "_level1" (charge une nouvelle animation à la place de la courante). L'argument optionnel method peut être post ou get, si vous voulez envoyer des variables au serveur.
- loadMovie(url, target)
La même chose que ci-dessus, plus ou moins. En fait, je ne sais pas trop quelle est la différence.
- nextFrame()
Va à l'image suivante.
- prevFrame()
Va à l'image précédente.
- play()
Joue l'animation.
- stop()
Cesse de jouer l'animation.
- toggleQuality()
Passe de haute en basse qualité (et vice-versa).
- stopSounds()
Cesse de jouer les sons.
- gotoFrame(num)
Va à l'image numéro num. Les images sont numérotées à partir de 0.
- gotoFrame(name)
Va à l'image nommée name. Ce qui est carrément cool, car les labels ne sont pas encore supportés pour les images.
- setTarget(expr)
Modifie le contexte de l'action. C'est ce qu'ils disent, mais je n'ai pas trop d'idées là-dessus.
Les sprites ont des propriétés. Vous pouvez les lire toutes (vraiment?), en modifier quelques unes. Les voici :
x
y
xScale
yScale
currentFrame - (lecture seule)
totalFrames - (lecture seule)
alpha - Niveau de transparence
visible - 1=on, 0=off (?)
width - (lecture seule)
height - (lecture seule)
rotation
target - (lecture seule) (???)
framesLoaded - (lecture seule)
name
dropTarget - (lecture seule) (???)
url - (lecture seule) (???)
highQuality - 1=high, 0=low (?)
focusRect - (???)
soundBufTime - (???)
Cet exemple simple va déplacer le gros carré rouge dans la fenêtre.
Exemple 1. Exemple avec swfaction()
|
Cet exemple suit votre souris sur l'écran.
Exemple 2. Exemple avec swfaction()
|
La même chose que ci-dessus, mais en couleurs.
Exemple 3. Exemple avec swfaction()
|
Cet exemple simple gère le clavier (vous devrez cependant cliquer dans la fenêtre pour lui donner le focus, et vous devrez aussi laisser votre souris dans la fenêtre. Si vous savez comment faire cela automatiquement, dites-le moi!).
Exemple 4. Exemple avec swfaction()
|
SWFBitmap->getHeight
Description
int swfbitmap->getheight ( void)swfbitmap->getheight() retourne la hauteur d'une bitmap, en pixels.
Voir aussi swfbitmap->getwidth().
SWFBitmap->getWidth
Description
int swfbitmap->getwidth ( void)swfbitmap->getwidth() retourne la largeur d'une bitmap, en pixels.
Voir aussi swfbitmap->getheight().
SWFBitmap
Description
new swfbitmap ( string filename [, int alphafilename])swfbitmap() crée un objet bitmap à partir d'un fichier JPEG ou DBL, nommé filename. alphafilename indique un fichier de masque à utiliser comme canal alpha sur une image JPEG.
Note : Seule les JPEG baseline (frame 0) sont supportés. Les baseline optimisée ou les JPEG progressives ne sont pas supportées.
SWFBitmap a les méthodes suivantes : swfbitmap->getwidth() et swfbitmap->getheight().
Il n'est pas possible d'importer directement des images PNG, il faut utiliser l'utilitaire de conversion png2dbl pour en faire un fichier .dbl ("define bits lossless"). La raison est que l'auteur ne souhaite pas de dépendance avec la librairie PNG. Le fichier d'autoconfiguration devrait régler ce problème, mais il n'est pas encore fait.
Exemple 1. Importation de fichiers PNG sous Ming
|
Et vous pouvez ajouter un masque alpha sur une image JPEG.
Exemple 2. Exemple avec swfbitmap()
|
swfbutton_keypress
Description
int swfbutton_keypress ( string str)
| Avertissement |
This function is currently not documented, only the argument list is available. |
SWFbutton->addAction
Description
void swfbutton->addaction ( ressource action, int flags)swfbutton->setaction() ajoute l'action action (créée par swfaction()) au bouton courant, dans les conditions précisées par flags. Les valeurs valides de flags sont : SWFBUTTON_MOUSEOVER, SWFBUTTON_MOUSEOUT, SWFBUTTON_MOUSEUP, SWFBUTTON_MOUSEUPOUTSIDE, SWFBUTTON_MOUSEDOWN, SWFBUTTON_DRAGOUT et SWFBUTTON_DRAGOVER
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton->addShape
Description
void swfbutton->addshape ( ressource shape, int flags)swfbutton->addshape() ajoute la forme shape au bouton. Les valeurs possibles de flags sont : SWFBUTTON_UP, SWFBUTTON_OVER, SWFBUTTON_DOWN ou SWFBUTTON_HIT. SWFBUTTON_HIT n'est même pas affiché, elle désigne la région du clic d'un bouton. C'est-à-dire que tous points où le bouton est déssiné est considéré comme accessible.
SWFbutton->setAction
Description
void swfbutton->setaction ( ressource action)swfbutton->setaction() assigne l'action qui sera exécutée lorsque le bouton sera cliqué. C'est un alias de addAction(shape, SWFBUTTON_MOUSEUP). action est une swfaction().
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton->setDown
Description
void swfbutton->setdown ( ressource shape)swfbutton->setdown() est un alias pour addShape(shape, SWFBUTTON_DOWN).
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton->setHit
Description
void swfbutton->sethit ( ressource shape)swfbutton->sethit() est un alias pour addShape(shape, SWFBUTTON_HIT).
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton->setOver
Description
void swfbutton->setover ( ressource shape)swfbutton->setover() est un alias pour addShape(shape, SWFBUTTON_OVER).
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton->setUp
Description
void swfbutton->setup ( ressource shape)swfbutton->setup() est un alias pour SWFbutton->addShape(shape, SWFBUTTON_UP).
Voir aussi : swfbutton->addshape() et swfaction().
SWFbutton
Description
new swfbutton ( void)swfbutton() crée un nouveau bouton. Cliquez-le, passez la souris dessus, et appelez des actions. Facile!
SWFButton a les méthodes suivantes : swfbutton->addshape(), swfbutton->setup(), swfbutton->setover() swfbutton->setdown(), swfbutton->sethit() swfbutton->setaction() et swfbutton->addaction().
Cet exemple simplissime vous montre comme faire un roll-over, un roll-on, un clic, un relaché de souris, et rien du tout (pas d'action).
Exemple 1. Exemple avec swfbutton()
|
Cet exemple simple illustre le déplacement d'un gros bouton rouge dans la fenêtre. Ce n'est pas du tirer-déposer, mais juste du tirer.
Exemple 2. Exemple avec swfbutton->addaction()
|
SWFDisplayItem->addColor
Description
void swfdisplayitem->addcolor ( [int red [, int green [, int blue [, int a]]]])swfdisplayitem->addcolor() ajoute une couleur à la transformations courante. La couleur est donnée sous la forme RGB.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
SWFDisplayItem->move
Description
void swfdisplayitem->move ( int dx, int dy)swfdisplayitem->move() déplace la forme courante de dx et dy unités, depuis sa position courante.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->moveto().
SWFDisplayItem->moveTo
Description
void swfdisplayitem->moveto ( int x, int y)swfdisplayitem->moveto() déplace la forme courante jusqu'au point de coordonnées globales (x,y).
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->move().
SWFDisplayItem->multColor
Description
void swfdisplayitem->multcolor ( [int red [, int green [, int blue [, int a]]]])swfdisplayitem->multcolor() multiplie la couleur de transformation par les valeurs données.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Cet exemple simple modifie l'atmosphère de votre image, et en fait une scène d'Halloween (utilisez un paysage ou une image claire pour un meilleur effet)
Exemple 1. Exemple avec swfdisplayitem->multcolor()
|
SWFDisplayItem->remove
Description
void swfdisplayitem->remove ( void)swfdisplayitem->remove() supprime cet objet de la liste d'affichage.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfmovie->add().
SWFDisplayItem->Rotate
Description
void swfdisplayitem->rotate ( double ddegrees)swfdisplayitem->rotate() fait tourner la forme de ddegrees degrés, en plus de sa rotation courante.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->rotateto().
SWFDisplayItem->rotateTo
Description
void swfdisplayitem->rotateto ( double degrees)swfdisplayitem->rotateto() tourne l'objet jusqu'à l'angle absoludegrees, en degrés.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Cet exemple amène trois chaînes tournoyantes depuis le fond de l'écran. Plutôt sympa.
Exemple 1. Exemple avec swfdisplayitem->rotateto()
|
Voir aussi swfdisplayitem->rotate().
SWFDisplayItem->scale
Description
void swfdisplayitem->scale ( int dx, int dy)swfdisplayitem->scale() étire un objet de (dx,dy), à partir de sa taille courante.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->scaleto().
SWFDisplayItem->scaleTo
Description
void swfdisplayitem->scaleto ( int x, int y)swfdisplayitem->scaleto() étire un objet jusqu'au dimensions (x,y).
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->scale().
SWFDisplayItem->setDepth
Description
void swfdisplayitem->setdepth ( double depth)swfdisplayitem->rotate() place l'objet à la profondeur depth. Par défaut, l'objet est placé au niveau où il a été ajouté dans l'animation. Les objets les plus anciens sont placés tout en bas, et les nouveaux sont superposés.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
SWFDisplayItem->setName
Description
void swfdisplayitem->setname ( string name)swfdisplayitem->setname() donne à l'objet courant le nom de name. Cela servira à repérer les acteurs d'un script d'action. Cela ne sert qu'avec les sprites.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
SWFDisplayItem->setRatio
Description
void swfdisplayitem->setratio ( double ratio)swfdisplayitem->setratio() modifie le ratio de l'objet, et le fixe à ratio. Uniquement utile pour les morphings.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Cet exemple simple effectue un morphing délicat de trois cercles concentriques.
Exemple 1. Exemple swfdisplayitem->setname()
|
SWFDisplayItem->skewX
Description
void swfdisplayitem->skewx ( double ddegrees)swfdisplayitem->skewx() ajoute ddegrees à l'inclinaison courante (x-skew).
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->skewx(), swfdisplayitem->skewy() and swfdisplayitem->skewyto().
SWFDisplayItem->skewXTo
Description
void swfdisplayitem->skewxto ( double degrees)swfdisplayitem->skewxto() modifie l'inclinaison (x-skew) à degrees. Si degrees vaut 1.0, l'angle sera de 45¡, en avant. S'il vaut plus, ce sera plus penché, et s'il vaut moins, ce sera plus droit.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->skewx(), swfdisplayitem->skewy() and swfdisplayitem->skewyto().
SWFDisplayItem->skewY
Description
void swfdisplayitem->skewy ( double ddegrees)swfdisplayitem->skewy() ajoute ddegrees à l'inclinaison courante (y-skew).
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->skewyto(), swfdisplayitem->skewx() and swfdisplayitem->skewxto().
SWFDisplayItem->skewYTo
Description
void swfdisplayitem->skewyto ( double degrees)swfdisplayitem->skewyto() modifie l'inclinaison (y-skew) à degrees. Si degrees vaut 1.0, l'angle sera de 45¡, en haut. S'il vaut plus, ce sera plus penché, et s'il vaut moins, ce sera plus droit.
L'objet peut être swfshape(), swfbutton(), swftext() ou swfsprite(). Il doit avoir été ajouté à une animation avec la fonction swfmovie->add().
Voir aussi swfdisplayitem->skewy(), swfdisplayitem->skewx() and swfdisplayitem->skewxto().
SWFDisplayItem
Description
new swfdisplayitem ( void)swfdisplayitem() crée un nouvel objet d'affichage displayitem.
C'est là que toute l'animation prend vie. Une fois que vous avez défini une forme, un texte, un sprite ou un bouton, vous l'ajoutez à une animation, puis vous utilisez la ressource retournée pour déplacer, étirer, contracter, faire tourner ou incliner la forme.
SWFDisplayItem a les méthodes suivantes : swfdisplayitem->move(), swfdisplayitem->moveto(), swfdisplayitem->scaleto(), swfdisplayitem->scale(), swfdisplayitem->rotate(), swfdisplayitem->rotateto(), swfdisplayitem->skewxto(), swfdisplayitem->skewx(), swfdisplayitem->skewyto() swfdisplayitem->skewyto(), swfdisplayitem->setdepth() swfdisplayitem->remove(), swfdisplayitem->setname() swfdisplayitem->setratio(), swfdisplayitem->addcolor() et swfdisplayitem->multcolor().
SWFFill->moveTo
Description
void swffill->moveto ( int x, int y)swffill->moveto() déplace l'origine de la forme jusqu'au point de coordonnées globales (x,y).
SWFFill->rotateTo
Description
void swffill->rotateto ( double degrees)swffill->rotateto() tourne la forme depuis sont orientation initiale jusqu'à un angle de degrees degrés.
SWFFill->scaleTo
Description
void swffill->scaleto ( int x, int y)swffill->scaleto() modifie l'échelle de la forme de x dans le sens des abscisses et y dans le sens des ordonnées.
SWFFill->skewXTo
Description
void swffill->skewxto ( double x)swffill->skewxto() incline la forme de x suivant l'axe des abscisses. Si x vaut 1.0, l'inclinaison sera de 45¡ degrés, en avant. Si x vaut plus, l'inclinaison sera plus forte, et sinon, la forme sera plus droite.
SWFFill->skewYTo
Description
void swffill->skewyto ( double y)swffill->skewyto() incline la forme de y suivant l'axe des abscisses. Si y vaut 1.0, l'inclinaison sera de 45¡ degrés, en avant. Si x vaut plus, l'inclinaison sera plus forte, et sinon, la forme sera plus droite.
SWFFill
Description
swffill() vous permet de transformer une image bitmap ou un gradient. Les objets swffill() sont créé par swfshape->addfill().
SWFFill a les méthodes suivantes : swffill->moveto(),swffill->scaleto(), swffill->rotateto(), swffill->skewxto() et swffill->skewyto().
swffont->getwidth
Description
int swffont->getwidth ( string string)swffont->getwidth() retourne la taille de la chaîne string, avec la police courante. Vous utiliserez plutôt la même méthode de l'objet swftext(), qui utilise les paramètres de l'objet.
SWFFont
Description
new swffont ( string filename)si filename est le nom d'un fichier FDB (i.e., si le nom de fichier se termine par ".fdb"), charge la police.
FDB ("font definition block") est un petit utilitaire pour Flash DefineFont2 qui contient une description complète de la police. Vous pouvez créer des fichiers FDB à partir du "SWT Generator", qui est inclus avec les utilitaires makefdb - regardez dans le dossier utilitaire de Ming.
Les polices utilisateurs ne contiennent aucune information autre que le nom de la police. On suppose que la police sera elle-même accessible au lecteur. Les polices "_serif", "_sans", et "_typewriter" doivent être universellement disponibles. Par exemple :
<?php
$f = newSWFFont("_sans");
?> |
swffont() retourne une ressource de police, à utiliser avec les méthodes swftext->setfont() et swftextfield->setfont().
SWFFont a les méthodes suivantes : swffont->getwidth().
SWFGradient->addEntry
Description
void swfgradient->addentry ( double ratio, int red, int green, int blue [, int a])swfgradient->addentry() ajoute une couleur à la liste des couleurs du gradient. ratio est un nombre de 0 à 1, qui indique l'ordre d'apparition des couleurs. Vous devez ajouter les couleurs dans l'ordre croissant de ratio.
red, green, blue représente une couleur, au format RGB. Le dernier paramètre a est optionnel.
SWFGradient
Description
new swfgradient ( void)swfgradient() crée un nouvel objet gradient.
Une fois que vous avez ajouté les couleurs à votre gradient, vous pouvez l'utiliser dans des formes, avec la fonction swfshape->addfill().
SWFGradient a la méthode suivante : swfgradient->addentry().
Cet exemple simple affiche un gradient noir-blanc comme fond, et un gradient concentrique au centre.
Exemple 1. Exemple avec swfgradient()
|
SWFMorph->getshape1
Description
mixed swfmorph->getshape1 ( void)swfmorph->getshape1() sélectionne la forme de début de morphing. swfmorph->getshape1() retourne un objet swfshape().
SWFMorph->getshape2
Description
mixed swfmorph->getshape2 ( void)swfmorph->getshape2() sélectionne la forme de début de morphing. swfmorph->getshape2() retourne un objet swfshape().
SWFMorph
Description
new swfmorph ( void)swfmorph() crée un morphing.
swfmorph() s'appelle aussi "shape tween". C'est cet objet qui permet toutes ces superbes animations qui mettent à genou votre ordinateur. Joie!
Les méthodes ici sont plutôt bizarres. Il serait tellement plus logique d'avoir seulement new SWFMorph(shape1, shape2);, mais, telles que sont les choses aujourd'hui, la deuxième forme a besoin de savoir qu'elle est l'aboutissement d'un morphing. (Tout cela, parceque Flash commence à dessiner aussitôt qu'il a les commandes de dessins. S'il conservait les descriptions de ses propres formes, et attendait leur totalité avant d'écrire, ceci et bien d'autres choses serait tellement plus simple).
SWFMorph a les méthodes suivantes : swfmorph->getshape1() et swfmorph->getshape1().
Cet exemple simple effectue le morphing d'une gros carré rouge en un carré plus petit, bleu et bordé de noir.
Exemple 1. Exemple avec swfmorph()
|
SWFMovie->add
Description
void swfmovie->add ( ressource instance)swfmovie->add() ajoute l'objet instance dans l'animation courante. instance peut être de n'importe quel type : forme (shape), texte (text), police (font), etc... Ils doivent être ajouté à une animation pour être utilisé.
Pour les objets affichables (formes, textes, boutons, sprites), swfmovie->add() retourne un objet swfdisplayitem() de la liste d'affichage. Ainsi, vous pouvez ajouter la même forme plusieurs fois dans la même animation, et obtenir des ressources différentes pour chaque instance.
Voir aussi tous les autres objets et swfmovie->remove()
Des exemples d'utilisation dans : swfdisplayitem->rotateto() et swfshape->addfill().
SWFMovie->nextframe
Description
void swfmovie->nextframe ( void)swfmovie->setframes() passe à l'image suivante de l'animation.
SWFMovie->output
Description
void swfmovie->output ( void)swfmovie->output() envoie votre animation au navigateur. En PHP, faîte le précéder de la fonction header().
<?php
header('Content-type: application/x-shockwave-flash');
?> |
Voir aussi swfmovie->save().
Des exemples d'utilisation dans : swfmovie->streammp3(), swfdisplayitem->rotateto(), swfaction()... En fait, tous les exemples utilisent cette méthode.
SWFMovie->remove
Description
void swfmovie->remove ( ressource instance)swfmovie->remove() supprime l'objet instance de la liste d'affichage, pour l'animation courante. L'objet ne sera plus disponible pour être affiché ou utilisé.
Voir aussi swfmovie->add().
SWFMovie->save
Description
void swfmovie->save ( string filename)swfmovie->save() sauve votre animation dans le fichier filename.
Voir aussi swfmovie->output().
SWFMovie->setbackground
Description
void swfmovie->setbackground ( int red, int green, int blue)swfmovie->setbackground() modifie la couleur de fond. Pourquoi est-ce que cette fonction n'accepte pas de canal alpha? (réflechissez quelques instants :-) ). En fait, cela ne serait pas si stupide : vous pouvez laisser apercevoir le fond HTML à travers l'animation. Il y a un moyen de faire cela, mais cela ne fonctionne qu'avec IE 4. Recherchez sur le site de http://www.macromedia.com/ pour plus de détails.
SWFMovie->setdimension
Description
void swfmovie->setdimension ( int width, int height)swfmovie->setdimension() modifie les dimensions de l'animation : width est la largeur et height la hauteur.
SWFMovie->setframes
Description
void swfmovie->setframes ( string numberofframes)swfmovie->setframes() modifie le nombre total d'images dans l'animation, et le fixe à numberofframes.
SWFMovie->setrate
Description
void swfmovie->setrate ( int rate)swfmovie->setrate() fixe la vitesse de l'animation à rate images par secondes. L'animation ralentira d'elle-même si le lecteur Flash ne peut pas afficher suffisamment rapidement, à moins qu'il n'y ait du son en stream, auquel cas les images sont sacrifiées pour garder un son fluide.
SWFMovie->streammp3
Description
void swfmovie->streammp3 ( string mp3FileName)swfmovie->streammp3() envoie le fichier MP3mp3FileName en stream audio. swfmovie->streammp3() n'est pas très robuste, et se prend facilement les pieds dans le tapis (elle peut éviter la balise initiale ID3, mais c'est bien tout). Tout comme swfshape->addjpegfill(), ce n'est pas une fonction stable. Il faudra sÛrement faire un objet séparé, pour gérer les types de son.
Notez que l'animation n'est pas suffisamment intelligente pour ajouter un nombre suffisant d'images, afin de correspondre à la durée totale du stream MP3. Il vous faudra ajouter des images jusqu'à durée de la musique multiplié par le nombre d'images par secondes.
Oui, vous pouvez utiliser Ming pour mettre un rock-'n-roll endiablé dans vos animation. Evitez d'en parler à l'RIAA ou la SACEM.
Exemple 1. Exemple avec swfmovie->streammp3()
|
SWFMovie
Description
new swfmovie ( void)swfmovie() Crée un objet 'animation', représentant une animation Flash version 4.
SWFMovie a les méthodes suivantes : swfmovie->output(),swfmovie->save(), swfmovie->add(), swfmovie->remove(), swfmovie->nextframe(), swfmovie->setbackground(), swfmovie->setrate(), swfmovie->setdimension(), swfmovie->setframes() et swfmovie->streammp3().
Des exemples d'utilisation dans : swfdisplayitem->rotateto(), swfshape->setline(), swfshape->addfill()... En fait, tous les exemples utilisent cet objet.
SWFShape->addFill
Description
void swfshape->addfill ( int red, int green, int blue [, int a])void swfshape->addfill ( SWFbitmap bitmap [, int flags])
void swfshape->addfill ( SWFGradient gradient [, int flags])
swfshape->addfill() ajoute un remplissage plein à la forme. swfshape->addfill() accepte trois différents types d'arguments.
red, green, blue est une couleur (format RGB). Le dernier paramètre a est optionnel.
L'argument bitmap est un objet swfbitmap(). Le paramètre flags peut être l'un des suivants : SWFFILL_CLIPPED_BITMAP ou SWFFILL_TILED_BITMAP. Par défault, c'est SWFFILL_TILED_BITMAP. Je crois.
L'argument gradient est un objet swfgradient(). L'argument flags peut alors prendre l'une des valeurs suivantes : SWFFILL_RADIAL_GRADIENT ou SWFFILL_LINEAR_GRADIENT. Par défaut, c'est SWFFILL_LINEAR_GRADIENT. Cette fois ci, j'en suis sÛr.
swfshape->addfill() retourne un objet swffill() à utiliser avec swfshape->setleftfill(), et swfshape->setrightfill() décrite un peu plus loin.
Voir aussi swfshape->setleftfill() et swfshape->setrightfill().
Ceci est un exemple simple qui affiche un cadre sur une bitmap. Ah, il y a un petit bug dans le lecteur Flash : il ne semble pas faire grand cas de la transformation de la seconde forme en morphing. Suivant les specs, la bitmap devrait s'étirer avec la forme dans cet exemple...
Exemple 1. Exemple avec swfshape->addfill()
|
SWFShape->drawCurve
Description
void swfshape->drawcurve ( int controldx, int controldy, int anchordx, int anchordy)swfshape->drawcurve() dessine une courbe quadratique (avec le style courant de ligne, modifié par swfshape->setline()) depuis le point courant jusqu'au point (anchordx,anchordy) relativement au point courant, et en utilisant le point de contrôle (controldx,controldy). C'est-à-dire qu'il commence en allant vers le point de contrôle, puis se dirigie sur le point d'ancrrage.
Voir aussi swfshape->drawlineto(), swfshape->drawline(), swfshape->movepento() et swfshape->movepen().
SWFShape->drawCurveTo
Description
void swfshape->drawcurveto ( int controlx, int controly, int anchorx, int anchory)swfshape->drawcurveto() dessine une courbe quadratique (avec le style courant de ligne, modifié par swfshape->setline()) depuis le point courant jusqu'au point (anchorx,anchory) en utilisant (controlx,controly) comme point de contrôle. C'est-à-dire qu'il commence en allant vers le point de contrôle, puis se dirigie sur le point d'ancrrage.
Voir aussi swfshape->drawlineto(), swfshape->drawline(), swfshape->movepento() et swfshape->movepen().
SWFShape->drawLine
Description
void swfshape->drawline ( int dx, int dy)swfshape->drawline() dessine une ligne (avec le style courant de ligne, modifié par swfshape->setline()) depuis le point courant, et sur le déplacement de (dx,dy).
Voir aussi swfshape->movepento(), swfshape->drawcurveto(), swfshape->movepen() et swfshape->drawlineto().
SWFShape->drawLineTo
Description
void swfshape->drawlineto ( int x, int y)swfshape->drawlineto() dessine une ligne (avec le style courant de ligne, modifié par swfshape->setline()) depuis le point courant jusqu'au point (x,y) dans l'espace de coordonnées de la forme.
Voir aussi swfshape->movepento(), swfshape->drawcurveto(), swfshape->movepen() et swfshape->drawline().
SWFShape->movePen
Description
void swfshape->movepen ( int dx, int dy)swfshape->movepen() déplace le stylo dans la forme depuis les coordonnées (current x,current y) jusqu'au coordonnées (current x + dx, current y + dy), dans l'espace de coordonnées de la forme.
Voir aussi swfshape->movepento(), swfshape->drawcurveto(), swfshape->drawlineto() et swfshape->drawline().
SWFShape->movePenTo
Description
void swfshape->movepento ( int x, int y)swfshape->movepento() déplace le stylo dans la forme jusqu'au coordonnées globales (x,y).
Voir aussi swfshape->movepen(), swfshape->drawcurveto(), swfshape->drawlineto() et swfshape->drawline().
SWFShape->setLeftFill
Description
void swfshape->setleftfill ( swfgradient fill)void swfshape->setleftfill ( int red, int green, int blue [, int a])
Tout ce sac de noeud fait qu'il y a deux couleurs de remplissage des lignes. Lorsque l'objet est rasterisé, il est pratique de savoir à l'avance quelle sont les remplissages, et le format SWF les demande.
swfshape->setleftfill() affecte à la couleur de rastérisation de gauche, c'est-à-dire l'intérieur d'un objet, si vous définissez les contours d'un objet dans le sens inverse des aiguilles d'une montre. L'objet de remplissage est un objet swffill(), retourné par la fonction swfshape->addfill() ci-dessus.
Cela semble être le contraire lorsque vous défnissez une forme dans un morphing. Si votre navigateur crashe, essayez de placer le remplissage sur l'autre côté.
Raccourci pour swfshape->setleftfill($s->addfill($r, $g, $b [, $a]));.
Voir aussi swfshape->setrightfill().
SWFShape->setLine
Description
void swfshape->setline ( int width [, int red [, int green [, int blue [, int a]]]])swfshape->setline() modifie le style de ligne de la forme. width est la largeur de la ligne. Si width vaut 0, le style est supprimé (et tous les autres arguments sont ignorés). Si width > 0, alors la couleur de la ligne devient (red, green, blue). Les couleurs sont représentées en RGB. Le dernier paramètre a est optionnel.
swfshape->setline() accepte 1, 4 ou 5 arguments (mais jamais 3 ou 2).
Vous devez déclarer un style avant de l'utiliser (voir exemple).
Cet exemple enfantin dessine une chaîne "!#%*@", dans des couleurs marrantes et un style rigolo.
Exemple 1. Exemple swfshape->setline()
|
SWFShape->setRightFill
Description
void swfshape->setrightfill ( swfgradient fill)void swfshape->setrightfill ( int red, int green, int blue [, int a])
Voir aussi swfshape->setleftfill().
Raccourci pour swfshape->setrightfill($s->addfill($r, $g, $b [, $a]));.
SWFShape
Description
new swfshape ( void)swfshape() crée une nouvelle forme.
SWFShape a les méthodes suivantes : swfshape->setline(), swfshape->addfill(), swfshape->setleftfill(), swfshape->setrightfill(), swfshape->movepento(), swfshape->movepen(), swfshape->drawlineto(), swfshape->drawline(), swfshape->drawcurveto() et swfshape->drawcurve().
Ce exemple simple dessine un quadrant d'ellipse rouge.
Exemple 1. Exemple avec swfshape()
|
SWFSprite->add
Description
mixed swfsprite->add ( ressource object)swfsprite->add() ajoute une swfshape(), un swfbutton(), un swftext(), une swfaction() ou une autre animation swfsprite().
Pour les objets affichables (swfshape(), swfbutton(), swftext(), swfaction() or swfsprite()), cela retourne une ressource sur l'objet dans la liste d'affichage.
SWFSprite->nextframe
Description
void swfsprite->nextframe ( void)swfsprite->setframes() se déplace à la prochaine image du sprite.
SWFSprite->remove
Description
void swfsprite->remove ( ressource object)swfsprite->remove() supprime une swfshape(), un swfbutton(), un swftext(), une swfaction() ou un swfsprite() du sprite courant.
SWFSprite->setframes
Description
void swfsprite->setframes ( int numberofframes)swfsprite->setframes() fixe le nombre total d'images de l'animation à numberofframes.
SWFSprite
Description
new swfsprite ( void)swfsprite() sont aussi connue sous le nom de "clip" : ils permettent la création d'objet animé dans une animation, avec un scénario propre. De ce fait, un sprite a les mêmes méthodes qu'une animation.
swfsprite() a les méthodes suivantes : swfsprite->add(), swfsprite->remove(), swfsprite->nextframe() et swfsprite->setframes().
Ce exemple pratique fait tourner un superbe carré rouge.
Exemple 1. Exemple de swfsprite()
|
SWFText->addString
Description
void swftext->addstring ( string string)swftext->addstring() ajoute le texte string au texte courant, et le dessine. Le stylo est situé sur la ligne de base du texte, c'est-à-dire que le texte sera écrit horizontalement.
SWFText->getWidth
Description
void swftext->addstring ( string string)swftext->addstring() retourne la taille de la chaîne string, une fois qu'elle est dessinée avec la police et l'espaceement courant.
SWFText->moveTo
Description
void swftext->moveto ( int x, int y)swftext->moveto() déplace le style (ou le curseur, si ça a un sens) jusqu'au coordonnées (x,y) dans l'espace de coordonnées du texte. Si x ou y vaut 0, la valeur de coordonnées de la dimension reste la même. C'est ennuyeux, et cela devrait être corrigé.
SWFText->setColor
Description
void swftext->setcolor ( int red, int green, int blue [, int a])swftext->setspacing() change la couleur de la police courante. Par défaut, c'est noir. La couleur est représentée avec la convention RGB.
SWFText->setFont
Description
void swftext->setfont ( string font)swftext->setfont() remplace la police courante par font.
SWFText->setHeight
Description
void swftext->setheight ( int height)swftext->setheight() fixe la hauteur courante de la police courante à height. Par défaut, c'est 240.
SWFText->setSpacing
Description
void swftext->setspacing ( double spacing)swftext->setspacing() fixe l'espacement de police à spacingspacing. Par défaut, c'est 1.0. 0 signifie que toutes les lettres seront écrites au même point. Cela fonctionne pas terrible, car l'avance des lettres augmente, et l'espacement entre lettre n'est pas toujours le même. Il faudra que je l'explique plus clairement. Ou bien que je corrige les erreurs.
SWFText
Description
new swftext ( void)swftext() crée un nouvel objet texte, prêt à être manipulé.
SWFText a les méthodes suivantes : swftext->setfont(), swftext->setheight(), swftext->setspacing(), swftext->setcolor(), swftext->moveto(), swftext->addstring() et swftext->getwidth().
Cet exemple simple va afficher la phrase "PHP fait du Flash avec Ming" sur un fond blanc.
Exemple 1. Exemle avec swftext()
|
SWFTextField->addstring
Description
void swftextfield->addstring ( string string)swftextfield->setname() concatène la chaîne string avec la chaîne courante.
SWFTextField->align
Description
void swftextfield->align ( int alignement)swftextfield->align() change l'alignement du texte par alignement. Les valeurs valides pour alignement sont : SWFTEXTFIELD_ALIGN_LEFT, SWFTEXTFIELD_ALIGN_RIGHT, SWFTEXTFIELD_ALIGN_CENTER et SWFTEXTFIELD_ALIGN_JUSTIFY.
SWFTextField->setbounds
Description
void swftextfield->setbounds ( int width, int height)swftextfield->setbounds() fixe la longueu du champs à width et sa hauteur à height. Si vous ne fixez pas les bords vous-mêmes, Ming tentera de les deviner lui-même (mais ne le laissez pas faire!!).
SWFTextField->setcolor
Description
void swftextfield->setcolor ( int red, int green, int blue [, int a])swftextfield->setcolor() modifie la couleur du champs texte, en la remplaçant par la couleur fournie. Par défaut, c'est noir opaque. Les couleurs sont représentées en convention RGB.
SWFTextField->setFont
Description
void swftextfield->setfont ( string font)swftextfield->setfont() remplace la police courante par la police font (police client?).
SWFTextField->setHeight
Description
void swftextfield->setheight ( int height)swftextfield->setheight() modifie la hauteur de la police du champs texte par height. Par défaut, c'est 240.
SWFTextField->setindentation
Description
void swftextfield->setindentation ( int width)swftextfield->setindentation() modifie l'indentation de la première ligne du champs texte, en la fixant à width.
SWFTextField->setLeftMargin
Description
void swftextfield->setleftmargin ( int width)swftextfield->setleftmargin() modifie la marge de gauche du champs texte à width. Par défaut, c'est 0.
SWFTextField->setLineSpacing
Description
void swftextfield->setlinespacing ( int height)swftextfield->setlinespacing() modifie l'espacement de lignes, en le fixant à height. Par défaut, c'est 40.
SWFTextField->setMargins
Description
void swftextfield->setmargins ( int left, int right)swftextfield->setmargins() modifie les deux marges du champs texte : left sera la nouvelle largeur de la marge de gauche, et right, celle de gauche. Par défaut, elles sont toutes les deux à 0.
SWFTextField->setname
Description
void swftextfield->setname ( string name)swftextfield->setname() baptise le champs texte name. Cela servira pour les formulaires et les actions.
SWFTextField->setrightMargin
Description
void swftextfield->setrightmargin ( int width)swftextfield->setrightmargin() modifie la marge de gauche du champs texte à width. Par défaut, c'est
SWFTextField
Description
new swftextfield ( [int flags])swftextfield() crée un nouveau champs texte. Les champs textes sont moins souples que les swftext(), car ils ne peuvent être tournés, mis à l'échelle ou incliné, mais ils peuvent être utilisés sous forme de champs de formulaire, et ils peuvent utiliser des polices navigateur.
Les flags optionnels modifient les comportements du champs. Ils peuvent prendre les valeurs suivantes :
SWFTEXTFIELD_NOEDIT : indique que le champs ne doit pas être éditable.
SWFTEXTFIELD_PASSWORD : indique que c'est un champs mot de passe
SWFTEXTFIELD_DRAWBOX : dessine le contour du champs
SWFTEXTFIELD_MULTILINE : autorise les lignes multiples
SWFTEXTFIELD_WORDWRAP : autorise la mise en forme du texte
SWFTEXTFIELD_NOSELECT : rend le champs non-sélectionnable
<?php $t = newSWFTextField(SWFTEXTFIELD_PASSWORD | SWFTEXTFIELD_NOEDIT); ?> |
SWFTextField a les méthodes suivantes : swftextfield->setfont(), swftextfield->setbounds(), swftextfield->align(), swftextfield->setheight(), swftextfield->setleftmargin(), swftextfield->setrightmargin(), swftextfield->setmargins(), swftextfield->setindentation(), swftextfield->setlinespacing(), swftextfield->setcolor(), swftextfield->setname() et swftextfield->addstring().
LX. Fonctions diverses
- Table des matières
- connection_aborted -- Indique si le client a abandonné la connexion.
- connection_status -- Retourne les bits de status de la connexion.
- connection_timeout -- Indique si le script a expiré.
- constant -- Retourne la valeur d'une constante
- define -- Définit une constante.
- defined -- Vérifie qu'une constante existe.
- die -- Alias de la fonction exit()
- eval -- Evalue une chaîne comme un script PHP.
- exit -- Termine le script courant.
- get_browser -- Indique de quoi est capable le navigateur client.
- highlight_file -- Colorisation de la syntaxe d'un fichier
- highlight_string -- Colorisation d'une chaîne
- ignore_user_abort -- Active l'option décidant si, lors de la déconnexion du client, le script doit poursuivre son exécution ou non.
- leak -- Fuite de mémoire.
- pack -- Compacte des données dans une chaîne binaire.
- show_source -- Colorisation de la syntaxe d'un fichier
- sleep -- Retarde l'exécution.
- uniqid -- Génère un identifiant unique.
- unpack -- Déconditionne des données depuis une chaîne binaire.
- usleep -- Retarde l'exécution en micro-secondes
connection_aborted
Description
int connection_aborted ( void )connection_aborted() retourne TRUE si le client a abandonné la connexion. Reportez-vous à Gestion des connexions du chapitre Caractéristiques.
connection_status
Description
int connection_status ( void )connection_status() retourne les bits de statut de la connexion. Reportez-vous à la section gestion des connexions pour plus de détails.
connection_timeout
Description
bool connection_timeout ( void )connection_timeout() retourne TRUE si le script a expiré. Reportez-vous à la section gestion des connexions pour plus de détails.
constant
Description
mixed constant ( string name)constant() retourne la valeur de la constante name.
constant() est pratique lorsque vous devez lire la valeur d'une constante, mais que vous ne savez son nom que durant l'exécution du script. Par exemple, ce nom peut être le résultat d'une fonction.
Voir aussi define(), defined() et la section sur les constantes.
define
Description
int define ( string name, mixed value [, int case_insensitive])define() définit une constante, de la même façon qu'une variable, sauf que :
Les constantes ne commencent pas par le signe '$'
Les constantes sont accessibles partout, de manière globale.
Les constantes ne peuvent pas être redéfinies, ou indéfinies, une fois qu'elles ont été définies.
Les constantes ne représentent que des valeurs scalaires : il n'est pas possible de définir des tableaux ou des objets.
Le nom de la constante est donné par le paramètre name; sa valeur est donnée par value.
Le troisième paramètre optionnel case_insensitive est une valeur booléenne. S'il vaut TRUE, le nom de la constante sera insensible à la casse : CONSTANT et Constant représentent des valeurs identiques. Par défaut, ces constantes représenteront des valeurs différentes.
define() retoune TRUE en cas de succès et FALSE sinon.
Voir aussi defined() et la section sur les constantes.
defined
Description
int defined ( string name)defined() retourne TRUE si la constante nommée name a été définie, et FALSE sinon.
Voir aussi define() et la section sur les constantes.
die
eval
Description
void eval ( string code_str)eval() évalue la chaîne code_str comme un script PHP. Parmi les utilisations possibles, cette fonction permet de stocker du code dans une base de données, pour utilisation ultérieure.
Il faut bien garder en tête que le code passé à eval() doit être valide, y compris les points virgules de fin de ligne et les séquences d'échappement, sinon l'exécution se terminera.
N'oubliez pas que les variables utilisées dans la fonction eval() resteront accessibles dans le script principal.
L'exemple ci-dessus devrait afficher : Ceci est une $string avec mon $name dedans. Ceci est une tasse avec mon café dedans.
exit
Description
void exit ( string status)void exit ( int status)
Note : exit() n'est pas une véritable fonction, mais un élément de langage.
exit() termine l'éxécution du script courant. Elle n'a pas de valeur de retour (et pour cause!), mais elle utilisera le message status comme message de fin d'exécution.
Note : La fonction die() est un alias de la fonction exit().
get_browser
Description
object get_browser ( [string user_agent])get_browser() essaie de déterminer les capacités du navigateur client. Cela se fait en lisant les informations dans le fichier browscap.ini. Par défaut, la valeur de $HTTP_USER_AGENT est utilisée. Cependant, vous pouvez passer n'importe quelle valeur avec le paramètre optionnel user_agent à get_browser().
Les informations sont retournées sous forme d'un objet, dont les différents membres contiendront des informations, telles que les versions majeures et mineures et des chaînes d'identification; des booléens pour des caractéristiques telles que frames, JavaScript, et cookies; et ainsi de suite.
Même si browscap.ini contient des informations sur de nombreux clients, il compte sur les utilisateurs pour être mis à jour. Le format du fichier est facilement compréhensible.
L'exemple suivant montre comment on peut lister les informations disponibles :
L'affichage devrait ressembler à ceci :
Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr>
<B>browser_name_pattern:</B> Mozilla/4\.5.*<br>
<B>parent:</B> Netscape 4.0<br>
<B>platform:</B> Unknown<br>
<B>majorver:</B> 4<br>
<B>minorver:</B> 5<br>
<B>browser:</B> Netscape<br>
<B>version:</B> 4<br>
<B>frames:</B> 1<br>
<B>tables:</B> 1<br>
<B>cookies:</B> 1<br>
<B>backgroundsounds:</B> <br>
<B>vbscript:</B> <br>
<B>javascript:</B> 1<br>
<B>javaapplets:</B> 1<br>
<B>activexcontrols:</B> <br>
<B>beta:</B> <br>
<B>crawler:</B> <br>
<B>authenticodeupdate:</B> <br>
<B>msn:</B> <br>
Pour fonctionner, votre configuration browscap doit mener au fichier browscap.ini.
Pour plus d'informations, (y compris pour les endroits où charger le fichier browscap.ini), suivez la FAQ PHP à http://www.php.net/FAQ.html.
Note : Browscap a été ajouté en PHP 3.0b2.
highlight_file
Description
boolean highlight_file ( string filename)highlight_file() affiche la syntaxe colorisée du fichier filename, en utilisant les couleurs définies dans le moteur interne de PHP.
Exemple 1. Colorisation d'URL Pour configurer une URL qui peut coloriser n'importe quel script que vous lui passez, nous avons besoin d'utiliser la directive Apache "ForceType", pour générer une URL exploitable, puis utiliser la fonction highlight_file() pour afficher un code propre. Dans votre configuration HTTP httpd.conf, vous pouvez ajouter le code suivant :
Puis, faire un fichier appelé "source", que vous placez dans votre racine de site web.
Alors, vous pourrez utiliser une URL telle que celle ci-dessous pour afficher une version colorisée de votre script "/path/to/script.php".
|
Voir aussi highlight_string() et show_source().
highlight_string
Description
void highlight_string ( string str)highlight_string() affiche la version colorisée de la chaîne str, en utilisant les couleurs définies dans le moteur interne de PHP.
Voir aussi highlight_file() et show_source().
ignore_user_abort
(PHP 3>= 3.0.7, PHP 4 )
ignore_user_abort -- Active l'option décidant si, lors de la déconnexion du client, le script doit poursuivre son exécution ou non.Description
int ignore_user_abort ( [int setting])ignore_user_abort() active l'option décidant si, lors de la déconnexion du client, le script doit poursuivre son exécution ou non. La fonction renvoie le paramétrage précédent et elle peut être appelée sans argument pour ne pas changer le paramétrage courant. Voir le paragraphe gestion des connexions dans le chapitre caractéristiques pour une description plus complète des manipulations de connexion en PHP.
leak
Description
void leak ( int bytes)leak() crée une fuite de mémoire.
leak() est pratique pour débugger le gestionnaire de mémoire, qui doit nettoyer automatiquement les fuites de mémoire après chaque requête.
pack
Description
string pack ( string format [, mixed args])pack() compacte les arguments dans une chaîne binaire, suivant le format format. pack() retourne la chaîne binaire.
L'idée vient du Perl et tout le formatage fonctionne de la même façon qu'en Perl, mais quelques formats manquent encore (comme, "u" ). La chaîne de format est composée d'une série de codes de formats, suivis par un quantificateur optionnel. Le quantificateur peut être un entier, ou * pour la répétition indéfinie. Pour les formats a, A, h et H, le quantificateur spécifie combien de caractères d'un argument sont pris; pour @, c'est la position absolue où placer les données, et pour le reste, c'est le nombre de répétitions. Actuellement, les formats suivants sont implémentés :
Une chaîne complétée avec NULL
Une chaîne complétée avec espace (SPACE)
Chaîne hexadécimale h, bit de poids faible en premier.
Chaîne hexadécimale H, bit de poids fort en premier.
c caractère signé
C caractère non signé
s entier court signé (toujours sur 16 bits, ordre des bits dépendant de la machine).
S entier court non signé (toujours 16 bits, ordre des bits dépendant de la machine).
n entier court signé (toujours 16 bits, ordre des bits big endian)
v entier cours non signé (toujours 16 bits, ordre des bits little endian)
i entier signé (taille et ordre des bits dépendants de la machine)
I entier non signé (taille et ordre des bits dépendants de la machine)
l entier long signé (toujours 32 bits, ordre des bits dépendant de la machine)
L entier long non signé (toujours 32 bits, ordre des bits dépendant de la machine)
N entier long non signé (toujours 16 bits, ordre des bits big endian)
V entier long non signé (toujours 16 bits, ordre des bits little endian)
f nombre à virgule flottante (taille et représentation dépendantes de la machine)
d nombre à virgule flottante double (taille et représentation dépendantes de la machine)
x bit NULL
X recule d'un octet
@ rempli avec NULL, jusqu'à une position absolue
Notez que la distinction entre signé et non signé n'affecte que la fonction unpack(), tandis que la fonction pack() fournira le même résultat pour les deux formats.
De plus, notez que PHP enregistre de manière interne et intégrale les valeurs : cette représentation dépend de la machine. Si vous essayez d'enregistrer une valeur trop grande, elle risque d'être convertie et de donner lieu à des effets de bords vicieux.
show_source
Description
void show_source ( string filename)show_source() affiche la syntaxe colorisée du fichier filename, en utilisant les couleurs définies dans le moteur interne de PHP.
Note : show_source() est un alias de highlight_file()
Voir aussi highlight_string() et highlight_file().
sleep
Description
void sleep ( int seconds)sleep() retarde l'exécution du programme pendant seconds secondes.
Voir aussi usleep().
uniqid
Description
int uniqid ( string prefix [, boolean lcg])uniqid() retourne un identifiant préfixé unique, basé sur l'heure courante, en micro-secondes. Le préfixe peut servir à identifier facilement différents hôtes, si vous générez simultanément des fichiers depuis plusieurs hôtes, à la même micro-seconde. prefix peut prendre jusqu'à 114 caractères.
Si le paramètre optionnel lcg est TRUE, uniqid() ajoutera une entropie "combined LCG" à la fin de la valeur retournée, ce qui renforcera encore l'unicité de l'identifiant.
Sans prefix (préfixe vide), la chaîne retournée fera 13 caractères. Si lcg est à TRUE, elle fera 23 caractères.
Note : Le paramètre lcg est utilisé à partir de PHP 4 et PHP 3.0.13 et ultérieurs.
Si vous voulez utiliser un identifiant unique, ou bien gérer des cookies, il est recommandé d'utiliser un code tel que celui-ci :
<?php
$token = md5 (uniqid ("")); // pas de section aléatoire.
$better_token = md5 (uniqid (rand())); // mieux, difficile à deviner
?> |
Ceci va créer un identifiant de 32 caractères (un nombre hexadécimal de 128 ) qui sera très difficile à prédire.
unpack
Description
array unpack ( string format, string data)unpack() déconditionne des données depuis une chaîne binaire avec le format format. unpack() retourne un tableau contenant les éléments déconditionnés.
unpack() se comporte légèrement différemment de la version Perl car les données déconditionnées sont stockées dans un tableau. Pour cela, il faut donner un nom à chaque format utilisé et les séparer par des slash (/).
Pour plus de détails, reportez-vous à: pack()
Il faut noter que PHP gère les valeurs en interne sous forme signée. Si vous déconditionnez une valeur qui est aussi grande que la taille utilisée en interne par PHP, le résultat se trouvera être un nombre négatif, même s'il a été déconditionné avec l'option " non signé ".
usleep
LXI. mnoGoSearch
Ces fonctions donnent l'accès à mnoGoSearch (anciennement UdmSearch), moteur de recherche du monde libre. Pour pouvoir les utiliser, vous devez inclure le support en ajoutant l'option --with-mnogosearch. Si vous utilisez cette option sans indiquer le chemin jusqu'à mnogosearch, PHP essaiera de le trouver dans le dossier /usr/local/mnogosearch. Si vous avez installé mnogosearch dans un autre endroit, vous devez l'indiquer comme ceci : --with-mnogosearch=DIR.
mnoGoSearch est une moteur de recherche complet, destinés aux intranet et serveurs web, distribué sous licence GNU. mnoGoSearch offre des fonctionnalités unique, qui en font un excellent outil pour un grand nombre d'applications de recherche dans votre site : recherche de recettes de cuisines ou dans les journaux, recherche dans un site FTP, dans les groupes de news, etc... Il offre un système d'indexation de textes pour les fichiers HTML, PDF et documents textes. mnoGoSearch est constitué de deux parties : l'indexeur, qui effectue les recherches et le moteur de recherche. L'indexeur passe en revue récursivement les sites HTTP, FTP, NEWS ou encore les fichiers locaux, et enregistre des méta-données dans les bases MySQL, pour optimiser les recherches ultérieures. Une fois que tous les documents ont été référéncés, ils sont accessibles au moteur de recherche. Celui-ci est utilisable par interface web. Les langages C CGI, Perl et PHP sont supportés pour effectuer les recherches.
Note : PHP supporte naturellement MySQL. Il faut savoir que mnoGoSearch n'est pas compatible avec la librairie interne de PHP, et ne peut fonctionner qu'avec les librairies génériques MySQL. Par conséquent, si vous utilisez mnoGoSearch avec MySQL, indiquez le dossier d'installation de MySQL durant la configuration avec l'option : --with-mnogosearch --with-mysql=/usr.
Pour utiliser ces fonctions, vous devez installer les versions 3.1.10 ou plus récente de mnoGoSearch.
Plus de détails sur le site officiel de mnoGoSearch : http://www.mnogosearch.ru/.
- Table des matières
- udm_add_search_limit -- Ajoute différentes limitations de recherche
- Udm_Alloc_Agent -- Alloue une session mnoGoSearch
- udm_api_version -- Lit la version des API mnoGoSearch.
- udm_cat_list -- Liste toutes les catégories soeurs d'une catégorie.
- udm_cat_path -- Lit le chemin de la catégorie courante.
- udm_check_charset -- Check if the given charset is known to mnogosearch
- udm_check_stored -- Check connection to stored
- udm_clear_search_limits -- Annule toutes les limitations de recherche
- udm_close_stored -- Close connection to stored
- udm_crc32 -- Return CRC32 checksum of gived string
- Udm_Errno -- Numéro d'erreur mnoGoSearch
- Udm_Error -- Message d'erreur mnoGoSearch
- Udm_Find -- Effectue une recherche
- Udm_Free_Agent -- Détruit une session mnoGoSearch
- udm_free_ispell_data -- Libère la mémoire allouée pour ispell
- Udm_Free_Res -- Libère un résultat mnoGoSearch
- udm_get_doc_count -- Lit le nombre total de documents dans les bases.
- Udm_Get_Res_Field -- Lit un champs de résultat mnoGoSearch
- Udm_Get_Res_Param -- Lit les paramètres de résultats mnoGoSearch
- udm_load_ispell_data -- Charge les données ispell
- udm_open_stored -- Open connection to stored
- udm_set_agent_param -- Modifie les paramètres de l'agent mnoGoSearch
udm_add_search_limit
Description
int udm_add_search_limit ( int agent, int var, string val)udm_add_search_limit() retourne TRUE en cas de succès, FALSE en cas d'erreur. udm_add_search_limit() ajoute différentes limitations de recherche.
agent - un identifiant d'Agent, obtenu après un appel à udm_alloc_agent().
var - nom du paramètre de limitation.
val - Valeur du paramètre sus-cité.
var peut prendre les valeurs suivantes :
UDM_LIMIT_URL - Définit les limitations sur les URL, pour limiter les recherches à une partie de la base. Ce paramètre supporte les jokers SQL '%' et '_' : '%' remplace n'importe quel nombre de caractères, même zéro caractères, et '_' remplace exactement un caractère. Par exemple, 'http://my.domain.__/catalog' peut remplacer http://my.domain.ru/catalog ou http://my.domain.ua/catalog.
UDM_LIMIT_TAG - Définit les limitations par étiquettes. Lors de l'indexation, vous pouvez assigner des étiquettes sur différentes parties d'un site. Les étiquettes de mnoGoSearch 3.1.x sont des lignes, qui peuvent contenir les jokers '%' et '_' : '%' remplace n'importe quel nombre de caractères, même zéro caractères, et '_' remplace exactement un caractère. Par exemple, si vous avez les étiquettes ABCD et ABCE, la limitation de recherche ABC_ limitera la recherche à ces deux étiquettes;
UDM_LIMIT_LANG - Définit les limitations par langue.
UDM_LIMIT_CAT - Définit les limitations par catégorie. Les catégories sont similaires aux étiquettes, mais elles peuvent être imbriquées. Vous pouvez donc placer des catégories dans d'autres cattégories. Vous devez utiliser deux caractères pour chaque niveau. Vous pouvez utiliser des nombres héxadécimaux allant de 0 à F ou bien sÛr une base de 36, allant de 0 à Z. Par exemple la catégorie supérieure 'Auto' vaut 01. Si elle a une sous catégorie 'Renault', cette dernière sera repérée par 01 (catégorie mère) suivie de 01 (dans sa catégorie), ce qui donne "0101". Si 'Auto' a une autre sous-catégorie 'Peugeot', cette dernière aura le numéro 02, et sera identifiée par 0102. Si 'Peugeot' a elle-même une autre sous-catégorie, 'Moteur', elle sera numéroté 01, et identifiée uniquement par 010201. Si vous voulez restreindre les recherches à cette catégorie uniquement, passez cat=010201.
UDM_LIMIT_DATE - Définit les limitations par date de modification du document.
Format de la valeur : une chaîne de caractères, dont le premier caractère est < ou >, puis une date au format unixtimestamp. Par exemple :
Udm_Add_Search_Limit($udm,UDM_LIMIT_DATE,"<908012006");
Si > est utilisé, la recherche sera limitée aux documents dont la date de modification est plus grande que celle qui a été entrée. Avec <, c'est le contraire.
Udm_Alloc_Agent
Description
int udm_alloc_agent ( string dbaddr [, string dbmode])udm_alloc_agent() retourne un agent mnogosearch en cas de succès, FALSE en cas d'erreur. udm_alloc_agent() crée une session avec les paramètres de base de données.
dbaddr est une description de base de données formaté comme une URL. Les options (type, hôte, nom de base de données, port, utilisateur ou mot de passe) servent à se connecter à la base de données SQL. Ne passez aucune valeur si vous souhaitez utiliser le support des fichiers texte intégré. Sinon, utilisez le format : DBAddr DBType:[//[DBUser[:DBPass]@]DBHost[:DBPort]]/DBName/. Actuellement, les valeurs de DBType possibles sont : mysql, pgsql, msql, solid, mssql, oracle, ibase. En fait, si vous avez ajouté un support natif, cette option est inutile. Mais les utilisateurs ODBC doivent spécifier une des valeurs supportées. Si votre type de base de données n'est pas supporté, utilisez le terme "unknown".
dbmode - Vous pouvez sélectionner le mode de stockage des mots dans la base de données. Si vous indiquez "single", tous les mots seront sotckés dans la même table. Si vous indiquez "multi", les mots seront situés dans différentes tables, suivant leur taille. Le mode "multi" est généralement plus rapide, mais requiert plus de tables. Si le mode "crc" est sélectionné, mnoGoSearch enregistrera un entier de 32 bits, calculé avec l'algorithme CRC32, plutot que des des mots. Ce mode requiert moins d'espace disque, et il est beaucoup plus rapide que les modes "single" et "multi". "crc-multi" utilise la même technique de stockage que le mode "crc", mais il stocke aussi les mots dans différentes tables suivant leur taille. Format: DBMode single/multi/crc/crc-multi.
Note : dbaddr et dbmode doit correspondre à ceux qui sont utilisés lors de l'indexation.
Note : En réalité, udm_alloc_agent() n'ouvre pas de connexion, et donc, ne vérifie ni le nom d'utilisateur, ni le mot de passe.
udm_api_version
Description
int udm_api_version ( void)udm_api_version() retourne le numéro de version des API mnoGoSearch. Par exemple, si mnoGosearch 3.1.10 est utilisé, udm_api_version() retournera 30110.
udm_api_version() permet aux utilisateurs d'identifier quelles sont les API disponibles. Par exemple, udm_get_doc_count() n'est disponible qu'à partir de mnoGoSearch 3.1.11.
Exemple avec udm_api_version()
udm_cat_list
Description
array udm_cat_list ( int agent, string category)udm_cat_list() retourne un tableau contenant la liste de toutes les catégories de même niveau que la catégorie courante.
Cette fonction est pratique pour réaliser des arbres à partir des catégories.
udm_cat_list() retourne un tableau avec le format suivant :
Le tableau est constitué de paires. Les index pairs contiennent les chemins de catégories, les index impairs contiennent les noms des catégories correspondantes.
$array[0] contiendra '020300'
$array[1] contiendra 'Marseille'
$array[2] contiendra '020301'
$array[3] contiendra 'Lille'
$array[4] contiendra '020302'
$array[5] contiendra 'Lyon'
...
etc.
Ce qui peut être affiché comme ceci :
Marseille
Lille
Lyon
...
udm_cat_path
Description
array udm_cat_path ( int agent, string category)udm_cat_path() retourne un tableau listant les catégories depuis la racine jusqu'à la catégorie courante.
Le paramètre agent est un identifiant de résultat, obtenu après un appel à Udm_Alloc_Agent.
category - La catégorie courante : celle dont on veut le chemin.
udm_cat_path() retourne un tableau avec le format suivant :
Le tableau est constitué de paires. Les index pairs contiennent les chemins de catégories, les index impairs contiennent les noms des catégories correspondantes.
Par exemple, l'appel $array=udm_cat_path($agent, '02031D'); peut retourner le tableau suivant :
$array[0] contiendra ''
$array[1] contiendra 'Root'
$array[2] contiendra '02'
$array[3] contiendra 'Sport'
$array[4] contiendra '0203'
$array[5] contiendra 'Foot'
$array[4] contiendra '02031D'
$array[5] contiendra 'PSG'
Exemple 1. Spécifier le chemin de la catégorie courante avec le format suivant : '> Root > Sport > Foot > PSG'
|
udm_check_charset
Description
int udm_check_charset ( int agent, string charset)
| Avertissement |
This function is currently not documented, only the argument list is available. |
udm_check_stored
Description
int udm_check_stored ( int agent, int link, string doc_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
udm_clear_search_limits
Description
int udm_clear_search_limits ( int agent)udm_clear_search_limits() annule toutes les limitations de recherche imposées, et retourne TRUE.
udm_close_stored
Description
int udm_close_stored ( int agent, int link)
| Avertissement |
This function is currently not documented, only the argument list is available. |
udm_crc32
Description
int udm_crc32 ( int agent, string str)
| Avertissement |
This function is currently not documented, only the argument list is available. |
Udm_Errno
Description
int udm_errno ( int agent)udm_errno() retourne le numéro d'erreur mnoGoSearch, ou bien 0 sinon.
Le paramètre agent est un identifiant de résultat, obtenu après un appel à Udm_Alloc_Agent.
udm_errno() retourne le numéro de l'erreur généré par l'agent agent.
Udm_Error
Description
string udm_error ( int agent)udm_errno() retourne le message d'erreur mnoGoSearch, ou bien une chaîne vide sinon.
Le paramètre agent est un identifiant de résultat, obtenu après un appel à Udm_Alloc_Agent.
udm_error() retourne le numéro de l'erreur généré par l'agent agent.
Udm_Find
Description
int udm_find ( int agent, string query)udm_add_search_limit() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
La recherche en elle-même. Le premier argument agent est la session, le second est la query. Pour rechercher, entrez les mots avec lesquels que vous voulez faire une recherche, puis cliquez sur le bouton d'envoi. Par exemple, "mysql odbc". Vous ne devez pas utiliser de guillemets doubles ", car ils sont utilisés par mnoGoSearch pour séparer une requête en mots. Avec l'exemple ci-dessus, mnoGoSearch va rechercher les pages contenant "mysql" et/ou "odbc". Les meilleures réponses seront classées en premier, et affichées en tête de liste. Si vous sélectionnez le mode de recherche "tous" ("ALL"), la recherche va retourner les documents qui contiennent l'un ou l'autre des mots que vous avez entré. Dans le cas où vous utilisez le mode "ANY", la recheche retourne la lsite des documents qui contiennent l'un ou l'autre des mots. Si vous voulez accéder aux fonctions avancées de recherche, vous pouvez utiliser le mode "BOOL", qui vous permet d'entrer directement des requêtes.
mnoGoSearch utilise les opérateurs booléean suivants :
& - AND, ET logique. Par exemple, "mysql & odbc". mnoGoSearch recherche toutes les URL qui contiennent à la fois les mots "mysql" et "odbc".
| - OR, OU logique. Par exemple, "mysql | odbc". mnoGoSearch recherche toutes les URL qui contiennent soit "mysql", soit "odbc".
~ - NOT, NON logique. Par exemple, "mysql & ~odbc". mnoGoSearch recherche toutes les URL qui contiennent le mot "mysql" mais ne contiennent pas le mot "odbc". Attention : la requête "~odbc" ne trouvera rien!
() - Groupage de commandes pour les requêtes complexes : par exemple, "(mysql | msql) & ~postgres". Le mode par requête est simple et puissant à la fois. Vous pouvez utiliser les commandes booléennes habituelles avec ce mode.
Udm_Free_Agent
Description
int udm_free_agent ( int agent)udm_free_res() retourne TRUE en cas de succès, FALSE sinon.
Le paramètre res est un identifiant de résultat, obtenu après un appel à Udm-Find.
udm_free_agent() détruit l'agent de recherche créé par udm_alloc_agent().
udm_free_ispell_data
Description
int udm_free_ispell_data ( int agent)udm_free_ispell_data() retourne toujours TRUE.
agent - Agent mnoGoSearch obtenu après un appel à udm_alloc_agent().
Note : udm_free_ispell_data() est supportée à partir de la version 3.1.12 de mnoGoSearch et elle ne fait strictement rien avec les versions précédentes.
Udm_Free_Res
Description
int udm_free_res ( int res)udm_free_res() retourne TRUE en cas de succès, FALSE sinon.
Le paramètre res est un identifiant de résultat, obtenu après un appel à Udm-Find.
udm_free_res() libère la mémoire de tous les résultats générés.
udm_get_doc_count
Description
int udm_get_doc_count ( int agent)udm_get_doc_count() retourne le nombre de document dans les bases de données.
agent - Agent mnoGoSearch obtenu après un appel à udm_alloc_agent().
Note : udm_get_doc_count() est supporté à partir de la version mnoGoSearch 3.1.11 ou plus récent.
Udm_Get_Res_Field
Description
int udm_get_res_field ( int res, int row, int field)udm_alloc_agent() retourne la valeur du champs field dans la ligne row, du résultat res, et FALSE sinon.
Le paramètre res est un identifiant de résultat, obtenu après un appel à Udm-Find.
Le paramètre row est le numéro du lien dans la page courante. Il peut valoir de 0 jusqu'à UDM_PARAM_NUM_ROWS.
Le paramètre field est l'identifiant de champs, et peut prendre l'une des valeurs suivantes :
UDM_FIELD_URL - Champs URL
UDM_FIELD_CONTENT - Champs "Content-type" (par exemple, "text/html").
UDM_FIELD_TITLE - Titre du document.
UDM_FIELD_KEYWORDS - Mots clés du document (balise META KEYWORDS).
UDM_FIELD_DESC - Description du document (balise META DESCRIPTION).
UDM_FIELD_TEXT - Corps du document (balise body, les premières lignes pour donner une idée du document).
UDM_FIELD_SIZE - Taille du document.
UDM_FIELD_URLID - Identifiant unique de l'URL.
UDM_FIELD_RATING - Score de la page (calculé par mnoGoSearch).
UDM_FIELD_MODIFIED - Date de modification au format unixtimestamp.
UDM_FIELD_ORDER - Le nombre de documents trouvés.
UDM_FIELD_CRC - La valeur CRC du document.
Udm_Get_Res_Param
Description
int udm_get_res_param ( int res, int param)udm_get_res_param() retourne les paramètres de résultat en cas de succès, FALSE en cas d'erreur.
Le paramètre res est un identifiant de résultat, obtenu après un appel à Udm-Find.
Le paramètre param peut prendre les valeurs suivantes :
UDM_PARAM_NUM_ROWS - nombre de liens trouvés dans le groupe de résultat courant. C'est la valeur de UDM_PARAM_PAGE_SIZE pour tous les groupes, sauf le dernier.
UDM_PARAM_FOUND - Nombre total de résultats trouvés.
UDM_PARAM_WORDINFO - Informations sur les mots trouvés, c'est-à-dire que la recherche "un bon libre" retournera "un: stopword, bon:5637, livre: 120"
UDM_PARAM_SEARCHTIME - Temps de recherche en secondes
UDM_PARAM_FIRST_DOC - le numéro du premier document affiché dans le groupe.
UDM_PARAM_LAST_DOC - le numéro du dernier document affiché dans le groupe.
udm_load_ispell_data
Description
int udm_load_ispell_data ( int agent, int var, string val1, string val2, int flag)udm_load_ispell_data() charge des données ispell. udm_load_ispell_data() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
agent - Agent mnoGoSearch obtenu après un appel à udm_alloc_agent().
var - paramètre indiquant la source des données ispell.
Après avoir utilisé cette fonction, pensez à libérer les données de la mémoire avec udm_free_ispell_data(), même si vous utilisez le mode UDM_ISPELL_TYPE_SERVER.
Le mode de plus rapide est UDM_ISPELL_TYPE_SERVER. UDM_ISPELL_TYPE_TEXT est plus lent, et UDM_ISPELL_TYPE_DB est le plus lent. Ce classement est vrai pour mnoGoSearch 3.1.10 - 3.1.11. Il est prévu d'accélérer le mode DB dans les versions futures, et cela sera plus rapide que le mode TEXT.
UDM_ISPELL_TYPE_DB indique que les données ispell doivent être chargée depuis la base SQL. Dans ce cas, les paramètres val1 et val2 sont ignorés et doivent être laissés vides. flag doit valoir 1.
Note : flag indique qu'après le chargement des données ispell à partir de la source, elles doivent être triées (c'est nécessaire au bon fonctionnement d'ispell). Dans le cas où vous chargez les données depuis un fichier, il peut y avoir plusieurs appels à udm_load_ispell_data(), et il ne vaut pas la peine de trier les valeurs après chaque appel, mais uniquement à la fin. Etant donné qu'en mode DB, toutes les données sont chargées en une seule fois, ce paramètre doit avoir la valeur de 1. Dans ce mode, en cas d'erreur, par exemple si la table ispell est absente, la fonction retournera FALSE et le code d'erreur, avec son message, seront accessibles avec udm_error() et udm_errno().
Exemple avec udm_load_ispell_data()
UDM_ISPELL_TYPE_AFFIX indique que les données ispell doivent être chargée depuis un fichier et initie le chargement. Dans ce cas, val1 définit le code de langue en deux lettre, et val2 est le chemin jusqu'aux fichiers. Notez que si vous utilisez un chemin relatif, le module recherche les fichiers non pas dans UDM_CONF_DIR, mais directement avec le chemin courant, où le script est exécuté. En cas d'erreur avec ce mode, si le fichier est absent, la fonction retourne FALSE, et un message d'erreur sera affiché. Les messages d'erreur ne sont pas accessibles avec udm_error() et udm_errno(), puisque ces fonctions ne traitent que les messages SQL. Reportez-vous à la description du paramètre flag.
Exemple avec udm_load_ispell_data()
if ((! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_AFFIX,'en','/opt/ispell/en.aff',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_AFFIX,'ru','/opt/ispell/ru.aff',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_SPELL,'en','/opt/ispell/en.dict',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_SPELL,'ru','/opt/ispell/ru.dict',1))) { exit; }Note : flag prend la valeur 1 si c'est le dernier appel à cette fonction.
UDM_ISPELL_TYPE_SPELL indique que les données ispell doivent être chargées depuis un fichier, et initie le chargement du dictionnaire. Dans ce cas, val1 définit le code langue sur deux lettres, et val2 le chemin du fichier. Notez que si vous utilisez un chemin relatif, le module recherche les fichiers non pas dans UDM_CONF_DIR, mais directement avec le chemin courant, où le script est exécuté. En cas d'erreur avec ce mode, si le fichier est absent, la fonction retourne FALSE, et un message d'erreur sera affiché. Les messages d'erreur ne sont pas accessibles avec udm_error() et udm_errno(), puisque ces fonctions ne traitent que les messages SQL. Reportez-vous à la description du paramètre flag.
Exemple avec udm_load_ispell_data()
if ((! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_AFFIX,'en','/opt/ispell/en.aff',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_AFFIX,'ru','/opt/ispell/ru.aff',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_SPELL,'en','/opt/ispell/en.dict',0)) || (! Udm_Load_Ispell_Data($udm,UDM_ISPELL_TYPE_SPELL,'ru','/opt/ispell/ru.dict',1))) { exit; }Note : flag prend la valeur 1 si c'est le dernier appel à cette fonction.
UDM_ISPELL_TYPE_SERVER active le support des serveurs ispell. val1 indique alors l'adresse de l'hôte qui supporte le serveur ispall. val2 n'est pas encore utilisé, mais dans les cas futurs, il indiquera le numéro de port utilisé par le serveur ispell. flag n'est pas utile, car les données sont déjà triées.
Les serveurs Spelld lisent les données d'orthographe dans une configuration séparée (par défaut /usr/local/mnogosearch/etc/spelld.conf), les trie et les stockes en mémoire. Avec les clients, le serveur communique de deux façons : vers les indexeurs, tout le contenu de la mémoire est transféré pour que l'indexeur travaille plus vite; vers le moteur de recherche, il reçoit les mots à normaliser, et les rend au client corrigés. Cela permet une plus grande rapidité d'éxécution, en comparaison des modes db et text (notamment, les tris et les chargements sont beaucoup plus rapides).
udm_load_ispell_data() en mode UDM_ISPELL_TYPE_SERVER ne charge pas vraiment les données ispell, mais définit simplement l'adresse du serveur. En fait, le serveur sera automatiquement utilisé par udm_find() lors des recherches. En cas d'erreur, (par exemple si le serveur ispell ne fonctionne pas ou que l'hôte indiqué est invalide), la conversion sera annulée, mais aucun message d'erreur ne sera affiché.
Note : Cette fonction est disponible à partir de mnoGoSearch 3.1.12.
Exemple avec udm_load_ispell_data()
udm_open_stored
Description
int udm_open_stored ( int agent, string storedaddr)
| Avertissement |
This function is currently not documented, only the argument list is available. |
udm_set_agent_param
Description
int udm_set_agent_param ( int agent, int var, string val)udm_set_agent_param() retourne TRUE en cas de succès et FALSE sinon. udm_set_agent_param() définit les paramètres de l'agent mnoGoSearch.
Les paramètres suivants et leurs valeurs sont disponibles :
UDM_PARAM_PAGE_NUM - Utilisé pour choisir le numéro de groupe de résultat (les résultats sont retournés par groupe, commençant à 0, avec UDM_PARAM_PAGE_SIZE résultats par page).
UDM_PARAM_PAGE_SIZE - Nombre de résultats affichés par page.
UDM_PARAM_SEARCH_MODE - Mode de recherche. Les valeurs suivantes sont disponibles : UDM_MODE_ALL - recherche tous les mots; UDM_MODE_ANY - recherche l'un des mots; UDM_MODE_PHRASE - recherche une phrase; UDM_MODE_BOOL - recherche booléenne. Voir udm_find() pour plus de détails sur les recherches booléennes.
UDM_PARAM_CACHE_MODE - Active/désactive le cache. Lorsque le cache est activé, le moteur de recherche va stocker les résultats sur le disque. Lorque deux requête seront similaires, il pourra retourner les résultats plus rapidement, sans recherche. Valeurs disponibles : UDM_CACHE_ENABLED, UDM_CACHE_DISABLED.
UDM_PARAM_TRACK_MODE - Active le mode de suivi de requête. Depuis la version 3.1.2, mnoGoSearch dispose d'un suivi de requête. Notez que ce suivi n'est implémenté qu'avec les versions SQL et n'est pas disponible avec les bases de données intégrées. Pour utiliser ce suivi, vous devez créer des tables de suivi. Pour mysql, utilisez le script create/mysql/track.txt. Lorsque vous effectuez une recherche avec l'interface, ces tables stockeront les mots recherchés ainsi que le nombre de mots trouvés, et la date. Valeurs disponibles : UDM_TRACK_ENABLED, UDM_TRACK_DISABLED.
UDM_PARAM_PHRASE_MODE - indique si les index des bases de données utilise des phrases( paramètre "phrase" dans indexer.conf). Valeurs disponibles : UDM_PHRASE_ENABLED and UDM_PHRASE_DISABLED. Notez bien que si la recherche par phrase est activé (UDM_PHRASE_ENABLED), il est toujours possible de faire des recherches dans d'autres modes, (ANY, ALL, BOOL ou PHRASE). En version 3.1.10 de mnoGoSearch, la recherche par phrase n'est supportée que pour les modes SQL et intégré, tandis qu'en 3.1.11, la recherche par phrase est supporté par le mode cache.
Exemple de recherche par phrase :
"Arizona desert" - Cette requete retourne tous les documents qui contiennent les mots "Arizona desert" comme une phrase. Notez que vous devez mettre des guillemets doubles autour des phrases.
UDM_PARAM_CHARSET - Définit le jeu de caractères local. Valeurs disponibles : Tous les jeux supportés par mnoGoSearch. koi8-r, cp1251, ...
UDM_PARAM_STOPFILE - Définit le nom et le chemin du fichier de mots ignorés. Il y a une petite différence avec mnoGoSearch : Avec mnoGoSearch, si le chemin est NULL ou relatif, il est utilisé à partir de UDM_CONF_DIR, alors qu'en PHP, le module va rechercher à partir du chemin courant, c'est-à-dire celui du script courant.
UDM_PARAM_STOPTABLE - Charge la liste des mots ignorés depuis une table SQL. Vous pouvez utiliser plusieurs tables SQL. Cette commande n'a aucun effet si mnoGoSearch n'a pas été compilé avec le support de base de données.
UDM_PARAM_WEIGHT_FACTOR - Représente le poids relatif des différentes parties d'un document. Actuellement, le corps, titre, mots clés, descriptions et url sont supportés. Pour activer cette fonctionnalité, utilisez le degré 2 de *Weight commands, dans le fichier indexer.conf. Imaginons que vous avez choisi les poids suivants :
URLWeight 1
BodyWeight 2
TitleWeight 4
KeywordWeight 8
DescWeight 16
Comme l'indexeur utiliser l'opérateur de bits OR pour mesurer le poids des mots, il est possible que le même mot soit trouvé plusieurs fois dans le même document lors des recherches. Un mot qui n'apparaît qu'une fois dans le corps sera défini par 00000010 (notation binaire). Un mot qui apparaîtra dans plusieurs parties pourra avoir la notation 00011111.
La valeur de ce paramètre est une chaîne de chiffres héxadécimaux, sous la forme ABCDE. Chaque chiffre est un facteur correspondant à un poids affecté à une partie du document. Por la situation décrite ci-dessus,
est le facteur de poids 1 (URL)
est le facteur de poids 2 (Corps)
est le facteur de poids 4 (Titre)
est le facteur de poids 8 (Mots clés)
est le facteur de poids 16 (Description)
Exemples:
UDM_PARAM_WEIGHT_FACTOR=00001 ne recherche que dans les URL.
UDM_PARAM_WEIGHT_FACTOR=00100 ne recherche que dans les Titres.
UDM_PARAM_WEIGHT_FACTOR=11100 recherche dans les Titres,Mots-clés,Description mais pas dans le corps ou les URL.
UDM_PARAM_WEIGHT_FACTOR=F9421 recherche dans :
Description avec un poids de 15 (F hex)
Keywords avec un poids de 9
Title avec un poids de 4
Body avec un poids de 2
URL avec un poids de 1
Si UDM_PARAM_WEIGHT_FACTOR est omis, la valeur par défaut est utilisée.
UDM_PARAM_WORD_MATCH - Recherche des mots. Vous pouvez utiliser ce paramètre pour choisir le type de recherche de mots. Cette fonctionnalité n'est valable qu'en mode "single" et "multi", avec les bases SQL ou intégrée. Elle ne fonctionne pas en mode intégré, ni avec d'autres modes, car les CRC ne supportent pas les recherches de sous-chaînes. Les valeurs disponibles sont :
UDM_MATCH_BEGIN - début de mot;
UDM_MATCH_END - fin de mot;
UDM_MATCH_WORD - tout le mot;
UDM_MATCH_SUBSTR - une sous-partie de mots.
UDM_PARAM_MIN_WORD_LEN - définit les tailles extrêmes de mots. Tout mot plus court que la limite inférieur est ignoré. Notez que ce paramètre est inclusif, c'est-à-dire que si UDM_PARAM_MIN_WORD_LEN=3, un mot de 3 caractères ne sera pas ignoré, alors qu'un mot de 2 caractères sera ignoré. Par défaut, la valeur est de 1.
UDM_PARAM_ISPELL_PREFIXES - Valeurs possibles : UDM_PREFIXES_ENABLED et UDM_PREFIXES_DISABLED. Ces valeurs activent et désactivent le support des préfixes. Par exemple, si le mot "testé" est placé dans la requête de recherche, les mots tels que "test", "tester", etc.. seront aussi recherchés. Les suffixes sont supportés par défaut. Les préfixes modifie généralement le sens des mots. Par exemple, si vous cherchez "testé", vous ne souhaitez pas trouver "protesté" ou "contesté". Le support des préfixes peut cependant être utilisé pour des raisons d'orthographe. Pour activer ispell, vous devez charger les données ispell avec la fonction udm_load_ispell_data().
UDM_PARAM_CROSS_WORDS - Active ou désactive le support "CROSS_WORDS". Valeurs possibles : UDM_CROSS_WORDS_ENABLED et UDM_CROSS_WORDS_DISABLED.
La fonctionnalité "CROSS_WORDS" vous permet d'effectuer des recherches dans les balises (entre <a href="xxx"> </a>), pour utiliser le nom du lien. Ce mode fonctionne avec les bases de données SQL et n'est pas supporté par les modes intégrés ou le cache.
Note : CROSS_WORDS est supporté à partir de mnoGoSearch 3.1.11.
UDM_PARAM_VARDIR - spécifie un chemin spécifique sur le disque où l'indexeur enregistre les données lorsqu'il utilise le cache et les bases de données internes. Par défaut, le dossier /var de l'installation de mnoGoSearch est utilisé. Ce paramètre est disponible en PHP 4.1.0 et plus récent.
LXII. mSQL
Ces fonctions vous permettent d'accéder aux bases de données mSQL. Pour cela, vous devez compiler PHP avec le support msql, en utilisant l'option de configuration --with-msql[=dir]. Par défaut, le chemin est '/usr/local/Hughes'.
Plus d'informations sur mSQL à http://www.hughes.com.au/.
- Table des matières
- msql_affected_rows -- Retourne le nombre de ligne affectées.
- msql_close -- Ferme une connexion mSQL.
- msql_connect -- Ouvre une connexion mSQL.
- msql_create_db -- Crée une base de données mSQL.
- msql_createdb -- Crée une base de données mSQL.
- msql_data_seek -- Déplace le pointeur interne.
- msql_dbname -- Lit le nom de la base de données courante.
- msql_drop_db -- Efface une base de données mSQL.
- msql_dropdb -- Efface une base de données mSQL.
- msql_error -- Retourne le message d'erreur
- msql_fetch_array -- Lit une ligne sous la forme d'un tableau.
- msql_fetch_field -- Lit la valeur d'un champs.
- msql_fetch_object -- Lit une ligne sous la forme d'un objet.
- msql_fetch_row -- Retourne une ligne sous la forme d'un objet.
- msql_field_seek -- Fixe d'offset d'un champs.
- msql_fieldflags -- Retourne le flag d'un champs.
- msql_fieldlen -- Retourne la longueur d'un champs.
- msql_fieldname -- Lit le nom d'un champs.
- msql_fieldtable -- Retourne le nom d'une table à partir d'un nom de champs.
- msql_fieldtype -- Retourne le type de champs.
- msql_free_result -- Libère le résultat de la mémoire.
- msql_freeresult -- Libère le résultat de la mémoire.
- msql_list_dbs -- Liste les bases de données mSQL sur un serveur.
- msql_list_fields -- Liste les champs d'une table.
- msql_list_tables -- Liste les tables mSQL sur une base de données
- msql_listdbs -- Liste les bases de données mSQL sur un serveur.
- msql_listfields -- Liste les champs d'une table.
- msql_listtables -- Liste les tables mSQL sur une base de données.
- msql_num_fields -- Retourne le nombre de champs dans un résultat.
- msql_num_rows -- Retourne le nombre de lignes dans un résultat.
- msql_numfields -- Retourne le nombre de champs dans un résultat.
- msql_numrows -- Retourne le nombre de lignes dans un résultat.
- msql_pconnect -- Ouvre une connexion persistante à un serveur mSQL.
- msql_query -- Envoie une requête mSQL
- msql_regcase -- Prépare une chaîne pour une recherche par expression régulière insensible à la casse.
- msql_result -- Retourne les données de résultat.
- msql_select_db -- Sélectionne une base de données mSQL.
- msql_selectdb -- Sélectionne une base de données mSQL.
- msql_tablename -- Retourne le nom d'une table à partir d'un nom de champs.
- msql -- Exécute une requête mSQL.
msql_affected_rows
Description
int msql_affected_rows ( resource query_identifier)msql_affected_rows() retourne le nombre de lignes affectées par la dernière commande INSERT, UPDATE ou DELETE sur le serveur associé au link_identifier. Si ce dernier n'est pas précisé, la dernière connexion est utilisée.
Voir aussi msql_query().
msql_close
Description
int msql_close ( resource link_identifier)msql_close() retourne TRUE en cas de succès, FALSE en cas d'erreur.
msql_close() ferme la connexion au serveur de base de données mSQL référencé par l'identifiant fourni. Si aucun identifiant n'est fourni, la dernière connexion sera utilisée.
Notez bien qu'il n'est pas toujours nécessaire d'appeler cette fonction, car les connexions non persistantes seront automatiquement fermées à la fin du script.
msql_close() ne peut pas fermer les connexions persistantes, générées par msql_pconnect().
Voir aussi msql_connect() et msql_pconnect().
msql_connect
Description
resource msql_connect ( [string hostname [, string hostname:port [, string username [, string password]]]])msql_connect() retourne un identifiant de connexion positif en cas de succès, et FALSE sinon.
msql_connect() établit une connexion à un serveur mSQL. Le nom d'hôte est optionnel, et lorsqu'il manque, localhost est utilisé.
Si un deuxième appel est fait à msql_connect(), avec les mêmes arguments, ce ne sera pas une nouvelle connexion qui va être ouverte, mais l'ancienne connexion qui sera utilisée, et son identifiant sera retourné.
Le lien au serveur sera fermé dès la fin du script, ou bien, manuellement, lors de l'appel de msql_close().
Voir aussi msql_pconnect() et msql_close().
msql_create_db
Description
int msql_create_db ( string database_name [, resource link_identifier])msql_create_db() essaie de créer une nouvelle base de données nommée database_name sur le serveur référencé par l'identifiant link_identifier.
Voir aussi msql_drop_db().
msql_createdb
Description
int msql_createdb ( string database_name [, resource link_identifier])Identique à msql_create_db().
msql_data_seek
Description
bool msql_data_seek ( resource query_identifier, int row_number)msql_data_seek() retourne TRUE en cas de succès, et FALSE en cas d'échec.
msql_data_seek() déplace le pointeur interne de résultat mSQL, et le place à l'offset donné. Le prochain appel à la fonction to msql_fetch_row() retournera cette ligne.
Voir aussi msql_fetch_row().
msql_dbname
Description
string msql_dbname ( resource query_identifier, int i)msql_dbname() retourne le nom de la base de données enregistré en position i du pointeur de résultat retourné par la fonction msql_listdbs(). La fonction msql_numrows() peut être utilisée pour déterminer le nombre de bases disponibles.
msql_drop_db
Description
int msql_drop_db ( string database_name, int link_identifier)msql_drop_db() retourne TRUE en cas de succès, et FALSE en cas d'échec.
msql_drop_db() essaie d'effacer une base de données entière sur le serveur référencé par l'identifiant fourni.
Voir aussi msql_create_db().
msql_dropdb
msql_error
Description
string msql_error ( void)Les erreurs générées par mSQL ne sont plus traitées comme des alertes. Au lieu de cela, elles sont stockées, et accessibles à partir de cette fonction.
msql_fetch_array
Description
int msql_fetch_array ( resource query_identifier [, int result_type])msql_fetch_array() retourne un tableau qui contient la ligne demandée, ou FALSE, si il n'y a pas d'autres lignes.
msql_fetch_array() est une version évoluée de msql_fetch_row(). En plus d'enregistrer les données dans un tableau à indice numérique, il peut enregistrer les données dans un tableau associatif, en utilisant les noms des champs comme clés.
Le deuxième argument result_type de msql_fetch_array() est une constante, et peut prendre les valeurs suivantes : MSQL_ASSOC, MSQL_NUM, et MSQL_BOTH.
Méfiez vous des requêtes qui retournent une ligne qui ne contient qu'un champs de valeur 0 (ou NULL, ou chaîne vide).
Il est important de noter que msql_fetch_array() est marginalement plus lent que msql_fetch_row(), alors qu'elle apporte un confort d'utilisation appréciable.
Voir aussi msql_fetch_row().
msql_fetch_field
Description
object msql_fetch_field ( resource query_identifier, int field_offset)msql_fetch_field() retourne un objet contenant les informations sur un champs.
msql_fetch_field() sert à lire les informations sur les champs, dans certaines requêtes. Si l'offset du champs n'est pas spécifié, le prochain champs sera retourné.
Les propriétés de l'objet sont :
name - nom de la colonne
table - nom de la table à qui appartient la colonne.
not_null - 1 si la colonne ne peut être NULL
primary_key - 1 si la colonne est une clé primaire
unique - 1 la colonne est une clé unique
type - le type de la colonne
Voir aussi msql_field_seek().
msql_fetch_object
Description
int msql_fetch_object ( resource query_identifier [, int result_type])msql_fetch_object() retourne un objet, dont les propriétés seront affectées suivant les champs de la ligne lue, ou FALSE si il ne reste plus de lignes.
msql_fetch_object() est identique à msql_fetch_array(), avec une différence : c'est un objet qui est retourné, à la place d'un tableau. Par conséquent, cela signifie que vous ne pouvez accéder aux valeurs que par les noms des champs, et non plus avec leur offset. (les nombres sont interdits dans les noms de propriétés)
L'argument optionnel result_type de msql_fetch_array() est une constante qui peut prendre les valeurs suivantes : MSQL_ASSOC, MSQL_NUM, et MSQL_BOTH.
msql_fetch_object() est aussi rapide que msql_fetch_array(), et marginalement plus lente que msql_fetch_row() (la différence est non significative).
Voir aussi msql_fetch_array() et msql_fetch_row().
msql_fetch_row
Description
array msql_fetch_row ( int query_identifier)msql_fetch_row() retourne un tableau qui contient la ligne demandée, ou FALSE, si il n'y a plus de lignes à lire.
msql_fetch_row() retourne une ligne, extraite du résultat associé à l'identifiant de résultat query_identifier. La ligne est retournée sous la forme d'un tableau. Chaque résultat est enregistré dans un champs, indexé numériquement, à partir de 0.
Les appels ultérieurs à msql_fetch_row() retourneront les lignes suivantes, ou FALSE, lorsqu'il n'y aura plus de ligne.
Voir aussi msql_fetch_array(), msql_fetch_object(), msql_data_seek() et msql_result().
msql_field_seek
Description
int msql_field_seek ( resource query_identifier, int field_offset)msql_field_seek() recherche l'offset du champs field_offset. Le prochain appel à msql_fetch_field() sans l'argument field_offset, retournera ce champs.
Voir aussi msql_fetch_field().
msql_fieldflags
Description
string msql_fieldflags ( resource query_identifier, int i)msql_fieldflags() retourne le flag du champs spécifié. Actuellement, il peut valoir soit "not NULL", "primary key", ou une combinaison des deux ou "" (chaîne vide).
msql_fieldlen
Description
int msql_fieldlen ( resource query_identifier, int i)msql_fieldlen() retourne la longueur du champs i.
msql_fieldname
Description
string msql_fieldname ( resource query_identifier, int field)msql_fieldname() retourne le nom du champs à l'index field. query_identifier est un identifiant de résultat, et field est un index de champs. msql_fieldname($result, 2); retournera le nom du deuxième champs, dans le résultat associé à query_identifier.
msql_fieldtable
Description
int msql_fieldtable ( resource query_identifier, int field)msql_fieldtable() retourne le nom de la table d'où est le champs field a été extrait.
msql_fieldtype
Description
string msql_fieldtype ( resource query_identifier, int i)msql_fieldtype() est similaire à msql_fieldname(). Les arguments sont identiques, mais c'est le type du champs qui est retourné. Cela produira un résultat tel que "int", "string" ou "real".
msql_free_result
Description
int msql_free_result ( resource query_identifier)msql_free_result() libère de la mémoire le résultat associé à l'identifiant de résultat query_identifier. Lorsque PHP a terminé une requête, cette mémoire est libérée, ce qui fait que vous n'aurez pas besoin de cette fonction. Vous pouvez toujours l'utiliser pour vous assurer que vous n'utilisez pas trop de mémoire durant un script.
msql_freeresult
msql_list_dbs
Description
int msql_list_dbs ( void)msql_list_dbs() retournea un pointeur de résultat, qui contiendra les noms des bases de données disponibles sur la connexion mSQL courante. Utilisez msql_dbname() pour passer en revue toutes les lignes.
msql_list_fields
Description
int msql_list_fields ( string database, string tablename)msql_list_fields() lit les informations de la table tablename. Les arguments sont le nom de la base de données, database et le nom de la table tablename. Cette fonction retourne un identifiant de résultat qui sera utilisé avec msql_fieldflags(), msql_fieldlen(), msql_fieldname() et msql_fieldtype(). Un identifiant de résultat est un entier positif. La fonction retourne -1 si une erreur survient. Une chaîne décrivant l'erreur sera placée dans la variable $phperrmsg, et à moins que cette fonction n'ai été appelée avec @ (@msql_list_fields()), alors cette erreur sera affichée.
Voir aussi msql_error().
msql_list_tables
Description
int msql_list_tables ( string database)msql_list_tables() prend un nom de base de données, et fourni un résultat, un peu comme la fonction msql(). La fonction msql_tablename() devrait être utilisée de préférence pour extraire les nom de table d'un pointeur de résultat.
msql_listdbs
msql_listfields
msql_listtables
msql_num_fields
Description
int msql_num_fields ( resource query_identifier)msql_num_fields() retourne le nombre de champs du résultat associé à l'identifiant query_identifier.
Voir aussi msql(), msql_query(), msql_fetch_field() et msql_num_rows().
msql_num_rows
Description
int msql_num_rows ( resource query_identifier)msql_num_rows() retourne le nombre de lignes du résultat associé à l'identifiant query_identifier.
Voir aussi msql(), msql_query() et msql_fetch_row().
msql_numfields
msql_numrows
msql_pconnect
Description
int msql_pconnect ( [string hostname [, string hostname:port [, string username [, string password]]]])Retourne un identifiant de connexion persistante à un serveur mSQL en cas de succès, et FALSE sinon.
msql_pconnect() se comporte presque comme msql_connect() mais avec deux différences majeures.
D'abord, lors de la connexion, msql_pconnect() cherche si une connexion persistante a déjà été ouverte sur le même hôte. Si une telle connexion est trouvée, elle sera utilisée.
Deuxièmement, la connexion au serveur SQL ne sera pas terminée lors de la fin de l'exécution du script. A la place, le lien restera ouvert pour d'autres connexions futures. (msql_close() ne fermera pas un lien ouvert par msql_pconnect()).
C'est pourquoi une telle connexion est considérée comme 'persistante'.
msql_query
Description
resource msql_query ( string query, int link_identifier)msql_query() envoie une requête à la base de données active, sur le serveur associé à l'identifiant de connexion link_identifier. Si link_identifier n'est pas fourni, PHP tentera d'utiliser la dernière connexion ouverte. Si aucune connexion n'a été ouverte, la fonction tentera de se connecter par elle même, avec msql_connect() appelé sans argument.
msql_query() retourne un identifiant positif mSQL en cas de succès, et FALSE sinon.
Voir aussi msql(), msql_select_db(), et msql_connect().
msql_regcase
(PHP 3, PHP 4 )
msql_regcase -- Prépare une chaîne pour une recherche par expression régulière insensible à la casse.msql_result
Description
int msql_result ( resource query_identifier, int i, mixed field)msql_result() retourne la valeur de la cellule, à la ligne i et l'offset spécifié, field dans le résultat mSQL query_identifier.
msql_result() retourne le contenu d'une cellule depuis un résultat mSQL query_identifier. L'argument de champs field peut être aussi bien un offset, qu'un nom de champs, ou encore le nom de la table point le nom du fichier (nom_table.nom_champs). Si la colonne est un alias, (par exemple 'select foo as bar from...'), utilisez de préférence l'alias au nom de colonne.
Lorsque vous travailler sur des résutats de grande taille, il est préférable d'utiliser les fonctions qui récupèrent toute la ligne (voir ci-dessous). Comme ces fonctions retournent plusieurs cellules en même temps, elles sont beaucoup plus rapide que msql_result(). De plus, sachez qu'accéder à un champs avec son indice numérique est beaucoup plus rapide qu'en utilisant les autres méthodes.
Alternatives recommandées : msql_fetch_row(), msql_fetch_array() et msql_fetch_object().
msql_select_db
Description
int msql_select_db ( string database_name, resource link_identifier)msql_select_db() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
msql_select_db() choisi la base de données courante sur le serveur associé à l'identifiant de connexion link_identifier. Si link_identifier n'est pas fourni, PHP tentera d'utiliser la dernière connexion ouverte. Si aucune connexion n'a été ouverte, la fonction tentera de se connecter par elle-même, avec msql_connect() appelée sans argument.
Les prochains appels à msql_query() seront fait dans la base de données active.
Voir aussi msql_connect(), msql_pconnect() et msql_query().
msql_selectdb
msql_tablename
Description
string msql_tablename ( int query_identifier, int field)msql_tablename() prend un pointeur de résultat (retourné par la fonction msql_list_tables()), ainsi qu'un index, et retourne le nom d'une table. La fonction msql_numrows() peut servir à déterminer le nombre de table dans le pointeur de résultat.
msql
Description
resource msql ( string database, string query, resource link_identifier)msql() retourne un identifiant positif de résultat de requête, ou FALSE en cas d'erreur.
msql() sélectionne la base de données database, et y exécute la requête query. Si l'identifiant de connexion link_identifier n'est pas fourni, la fonction va rechercher un lien ouvert à un serveur mSQL, et sinon, il va tenter d'en créer une, avec msql_connect(), sans argument.
LXIII. MySQL
Ces fonctions vous permettent d'accéder aux bases de données MySQL. Afin de pouvoir les utiliser, vous devez compiler PHP avec le support MySQL, en utilisant l'option --with-mysql. Si vous utilisez cette fonction sans préciser le chemin d'accès à la base MySQL, PHP utilisera les librairies clientes MySQL fournies en standard. Les utilisateurs qui font tourner d'autres applications qui utilisent elles-mêmes MySQL (par exemple, PHP 3 et PHP 4 utilisés comme des modules concurrents apache, ou encore auth-mysql), devraient toujours spécifier le chemin jusqu'à MySQL : --with-mysql=/path/to/mysql. Cela va forcer PHP à utiliser les librairies clientes installées par MySQL et évitera les conflits.
Plus d'informations sont disponible à http://www.mysql.com/.
La documentation de MySQL est disponibles à http://www.mysql.com/documentation/, ainsi qu'en français chez nexen.
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 d'introduction
|
- Table des matières
- mysql_affected_rows -- Retourne le nombre de lignes affectées lors de la dernière requête SQL.
- mysql_change_user -- Change le nom de session de l'utilisateur actif.
- mysql_character_set_name -- Returns the name of the character set
- 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_db_name -- Lit les noms des bases de données
- mysql_db_query -- Envoie une requête MySQL à un serveur MySQL.
- mysql_drop_db -- Efface une base de données MySQL.
- mysql_errno -- Retourne le numéro de message d'erreur de la dernière opération 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 une chaîne pour la passer à mysql_query.
- mysql_fetch_array -- Retourne une ligne de résultat sous la forme d'un tableau associatif.
- mysql_fetch_assoc -- Lit une ligne de résultats dans un tableau associatif
- mysql_fetch_field -- Retourne les données enregistrées dans une colonne sous forme d'objet.
- mysql_fetch_lengths -- Retourne la taille de chaque colonne d'une ligne de résultat.
- mysql_fetch_object -- Retourne les lignes résultats sous la forme d'un objet.
- mysql_fetch_row -- Retourne une ligne de résultat sous la forme d'un tableau.
- mysql_field_flags -- Retourne le sémaphore associé à la colonne spécifiée dans le résultat courant.
- mysql_field_len -- Retourne la longueur du champs spécifié.
- mysql_field_name -- Retourne le nom d'une colonne
- mysql_field_seek -- Déplace le pointeur de résultat
- mysql_field_table -- Retourne le nom de la table où se trouve une colonne
- mysql_field_type -- Retourne le type de la colonne spécifiée dans le résultat courant.
- mysql_free_result -- Efface 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 -- Get information about the most recent query
- mysql_insert_id -- Retourne l'identifiant généré par la dernière requête INSERT.
- mysql_list_dbs -- Liste les bases de données disponibles sur le serveur MySQL.
- mysql_list_fields -- Liste les champs du résultat MySQL.
- mysql_list_processes -- List MySQL processes
- mysql_list_tables -- Liste les tables d'une base de données.
- mysql_num_fields -- Retourne le nombre de champs d'un résultat.
- mysql_num_rows -- Retourne le nombre de lignes d'un résultat.
- mysql_pconnect -- Ouvre une connexion persistante à un serveur MySQL.
- mysql_ping -- Ping a server connection or reconnect if there is no connection
- mysql_query -- Envoie une requête SQL à un serveur MySQL.
- mysql_real_escape_string -- Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection.
- mysql_result -- Retourne un champs d'un résultat.
- mysql_select_db -- Sélectionne une base de données MySQL.
- mysql_stat -- Get current system status
- mysql_tablename -- Lit le nom de la table qui contient le champs spécifié.
- mysql_thread_id -- Return the current thread ID
- mysql_unbuffered_query -- Exécute une requête SQL sans mobiliser les résultats
mysql_affected_rows
(PHP 3, PHP 4 )
mysql_affected_rows -- Retourne le nombre de lignes affectées lors de la dernière requête SQL.Description
int mysql_affected_rows ( [resource link_identifier])mysql_affected_rows() retourne le nombre de lignes affectées lors de la dernière requête INSERT, UPDATE ou DELETE sur le serveur associé à l'identifiant de connexion. Si cet identifiant n'est pas précisé, mysql_affected_rows() utilise la dernière connexion ouverte.
Note : Si vous utilisez les transactions, vous devez appeler mysql_affected_rows() après votre INSERT, UPDATE, ou DELETE et non après la validation.
Si la dernière requête était un DELETE sans clause WHERE, tous les enregistrements ont été effacés, mais mysql_affected_rows() va retourner 0.
mysql_affected_rows() n'est pas possible après un SELECT, car elle ne fonctionne qu'après des commandes qui modifient les enregistrements. Pour connaître le nombre de lignes retournées par un SELECT, utilisez mysql_num_rows().
Si la dernière requête a échoué, mysql_affected_rows() retourne -1.
mysql_change_user
Description
int mysql_change_user ( string user, string password [, string database [, resource link_identifier]])mysql_change_user() change l'utilisateur de la session courante, ou sur la connexion spécifiée avec l'option link_identifier. Si une base est spécifiée, elle deviendra la base par défaut de l'utilisateur. Si une erreur de connexion survient, la connexion en cours restera active.
Note : mysql_change_user() a été introduite en PHP 3.0.13 et requiert MySQL 3.23.3 ou plus récent.
mysql_character_set_name
Description
int mysql_character_set_name ( [resource link_identifier])mysql_character_set_name() returns the default character set name for the current connection.
See also: mysql_real_escape_string()
mysql_close
Description
boolean mysql_close ( [resource link_identifier])mysql_close() retourne TRUE en cas de succès et FALSE sinon.
mysql_close() ferme la connexion au serveur MySQL associée à l'identifiant link_identifier. Si cet identifiant n'est pas spécifié, cette commande s'applique à la dernière connexion ouverte.
Note : Notez que cette commande n'est pas nécessaire, car toutes les connexions non persistantes seront automatiquement fermées à la fin du script.
mysql_close() ne ferme pas les connexions persistantes générées par mysql_pconnect().
Voir aussi mysql_connect() et mysql_pconnect().
mysql_connect
Description
int mysql_connect ( [string server [, string username [, string password]]])mysql_connect() retourne un identifiant positif de connexion en cas de succès, et sinon FALSE.
mysql_connect() établit une connexion à un serveur MySQL. Tous les arguments sont optionnels, et s'ils manquent, les valeurs par défaut sont utilisées ( ('localhost', nom du propriétaire du processus, mot de passe vide).
Le nom d'hôte peut aussi inclure un numéro de port, sous la forme : "hostname:port" ou un chemin jusqu'à une socket sous la forme ":/path/to/socket" pour l'hôte localhost.
Note : Le support des ":port" a été ajouté à partir de la version 3.0B4.
Le support de ":/path/to/socket" a été ajouté à partir de la version 3.0.10.
Vous pouvez supprimer le message d'erreur de connexion en ajoutant une arobase '@' au nom de la fonction.
Si un second appel à mysql_connect() est fait avec les mêmes arguments, PHP ne va pas ouvrir une nouvelle connexion, mais va retourner l'identifiant de la connexion déjà ouverte.
Le lien sera fermé automatiquement dès que l'exécution du script sera terminée, à moins d'être fermé explicitement avec mysql_close().
Voir aussi mysql_pconnect() et mysql_close().
mysql_create_db
Description
int mysql_create_db ( string database_name [, resource link_identifier])mysql_create_db() tente de créer une nouvelle base de données nommée database_name sur le serveur associé à l'identifiant link_identifier, ou sur la dernière connexion ouverte.
Pour des raisons de compatibilité ascendante, mysql_createdb() est toujours utilisable.
Voir aussi mysql_drop_db().
mysql_data_seek
Description
int mysql_data_seek ( resource result_identifier, int row_number)mysql_data_seek() retourne TRUE en cas de succès et FALSE sinon.
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 à mysql_fetch_row() retournera cette ligne.
row_number commence à 0.
Exemple 1. Exemple mysql_data_seek()
|
mysql_db_name
Description
int mysql_db_name ( resource result_identifier, int row [, mixed field])mysql_db_name() prend comme premier argument le pointeur de résultat result_identifier, issu de mysql_list_dbs(). row est l'index dans le résultat.
Si une erreur survient, FALSE est retourné. Utilisez mysql_errno() et mysql_error() pour connaître la nature de l'erreur.
Pour des raisons de compatibilité ascendante, mysql_dbname() est aussi accepté, mais obsolète.
mysql_db_query
Description
resource mysql_db_query ( string database, string query [, resource link_identifier])mysql_db_query() retourne un identifiant de résultat si la requête réussit et FALSE sinon.
mysql_db_query() sélectionne une base de données et exécute une requête. Si l'identifiant de lien link_identifier n'est pas précisé, mysql_db_query() prendra par défaut la dernière connexion ouverte sur le serveur et si elle n'en trouve pas, elle tentera de se connecter, en utilisant la fonction mysql_connect(), sans arguments.
Voir aussi mysql_connect() et mysql_query().
Note : Cette fonction est obsolète, et abandonnée depuis PHP 4.0.6. Ne l'utilisez plus (ou pas!). Alternative recommandée : mysql_select_db() et mysql_query().
mysql_drop_db
Description
boolean mysql_drop_db ( string database_name [, resource link_identifier])mysql_drop_db() retourne TRUE en cas de succès et FALSE sinon.
mysql_drop_db() essaie d'effacer une base de données entière sur le serveur associé à l'identifiant de connexion link_identifier.
Voir aussi mysql_create_db().
Pour des raisons de compatibilité ascendante, mysql_drop_db() est toujours utilisable.
mysql_errno
(PHP 3, PHP 4 )
mysql_errno -- Retourne le numéro de message d'erreur de la dernière opération MySQL.Description
int mysql_errno ( [resource link_identifier])mysql_errno() retourne le numéro de message d'erreur de la dernière opération MySQL sur la connexion courante, ou sur la connexion spécifiée avec l'option link_identifier. Les erreurs qui sont remontées depuis le serveur MySQL ne sont plus des alertes. A la place, il faut utiliser mysql_errno() pour obtenir le numéro d'erreur.
<?php
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."<br>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."<br>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."<br>";
?> |
Voir aussi mysql_error().
mysql_error
(PHP 3, PHP 4 )
mysql_error -- Retourne le texte associé avec l'erreur générée lors de la dernière requête.Description
string mysql_error ( [resource link_identifier])mysql_error() retourne le dernier message d'erreur MySQL sur la connexion courante, ou sur la connexion spécifiée avec link_identifier.
Les erreurs générées par mySQL ne se transforment plus en alerte. A la place, elles sont accessibles via ces fonctions :
<?php
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."<br>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."<br>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."<br>";
?> |
Voir aussi mysql_errno().
mysql_escape_string
Description
string mysql_escape_string ( string unescaped_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(). Elle retourne la chaîne modifiée.
Note : mysql_escape_string() n'échappe pas les caractères pourcentage % ou _.
mysql_fetch_array
(PHP 3, PHP 4 )
mysql_fetch_array -- Retourne une ligne de résultat sous la forme d'un tableau associatif.Description
array mysql_fetch_array ( resource result_identifier [, int result_type])mysql_fetch_array() retourne un tableau qui contient la ligne demandée, ou FALSE si il ne reste plus de ligne.
mysql_fetch_array() est une version étendue de mysql_fetch_row(). En plus d'enregistrer les données sous forme d'un tableau à indice numérique, elle peut aussi les enregistrer dans un tableau associatif, en utilisant les noms des champs comme indices.
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, vous devez utiliser l'index numérique, ou faire un alias pour chaque colonne.
Il est important de souligner que mysql_fetch_array() N'est PAS plus lente que mysql_fetch_row(), tandis qu'elle ajoute un confort d'utilisation notable.
L'option result_type de mysql_fetch_array() est une constante qui peut prendre les valeurs suivantes : MYSQL_ASSOC, MYSQL_NUM et MYSQL_BOTH.
Voir aussi mysql_fetch_row().
mysql_fetch_assoc
Description
array mysql_fetch_assoc ( resource result_identifier)mysql_fetch_assoc() retourne un tableau associatif qui contient la ligne lue, ou bien FALSE, si il ne reste plus de lignes.
mysql_fetch_assoc() est équivalente à mysql_fetch_array() utilisée avec l'option MYSQL_ASSOC. Elle ne retourne qu'un tableau associatif. C'est le fonctionnement original de mysql_fetch_array(). Si vous avez besoin d'indices numériques, utilisez mysql_fetch_array().
Si plusieurs colonnes portent le même nom, la dernière aura la priorité. Pour accéder aux autres colonnes du même nom, vous devez utiliser mysql_fetch_array() et les indices numériques.
Une chose importante à noter est que mysql_fetch_assoc() n'est PAS significativement plus lente que mysql_fetch_row(), alors qu'elle apporte un confort d'utilisation important.
Pour plus de détails, reportez-vous à mysql_fetch_row() et mysql_fetch_array().
mysql_fetch_field
(PHP 3, PHP 4 )
mysql_fetch_field -- Retourne les données enregistrées dans une colonne sous forme d'objet.Description
object mysql_fetch_field ( resource result_identifier [, int field_offset])mysql_fetch_field() retourne un objet contenant les données, lu dans le résultat result_identifier.
mysql_fetch_field() sert à obtenir des informations à propos des champs, dans certaines requêtes. Si l'offset du champs n'est pas spécifié, le champs suivant le dernier champs retourné, est retourné.
Les propriétés de l'objet sont :
name - nom de la colonne
table - nom de la table de la colonne
max_length - taille maximale de la colonne
not_null - 1 si la colonne ne peut pas être NULL (attribut NOT NULL)
primary_key - 1 si la colonne est une clé primaire (attribut PRIMARY KEY)
unique_key - 1 si la colonne est une clé unique (attribut 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.
Voir aussi mysql_field_seek().
mysql_fetch_lengths
Description
array mysql_fetch_lengths ( resource result_identifier)mysql_fetch_lengths() retourne un tableau avec la taille de chaque colonne de la dernière ligne retournée par mysql_fetch_row(), sinon FALSE.
mysql_fetch_lengths() stocke les tailles de chaque colonne de la dernière ligne retournée par mysql_fetch_row(), mysql_fetch_array() et mysql_fetch_object() dans un tableau, en commençant à la position.
Voir aussi mysql_fetch_row().
mysql_fetch_object
Description
object mysql_fetch_object ( resource result_identifier [, int result_type])mysql_fetch_object() retourne un objet dont les propriétés correspondent à une ligne d'un résultat, ou FALSE si il n'y a plus d'autres lignes.
mysql_fetch_object() est identique à mysql_fetch_array(), à la différence qu'elle retourne un objet à la place d'un tableau. Vous pourrez ainsi accéder aux valeurs des champs par leur nom, mais plus par leur offset (les nombres ne sont pas des noms MySQL).
L'argument optionnel result_type est une constante qui peut prendre les valeurs suivantes : MYSQL_ASSOC, MYSQL_NUM et MYSQL_BOTH.
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)
Voir aussi mysql_fetch_array() et mysql_fetch_row().
mysql_fetch_row
Description
array mysql_fetch_row ( resource result_identifier)mysql_fetch_row() retourne un tableau énuméré qui correspond à la ligne demandée, ou FALSE s'il ne reste plus de ligne.
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 enregistrée sous la forme d'un tableau commençant à la position 0.
Les appels suivants à mysql_fetch_row() retourneront la ligne suivante dans le résultat, ou FALSE si il n'y a plus de ligne disponible.
Voir aussi mysql_fetch_array(), mysql_fetch_object(), mysql_data_seek(), mysql_fetch_lengths() et mysql_result().
mysql_field_flags
(PHP 3, PHP 4 )
mysql_field_flags -- Retourne le sémaphore associé à la colonne spécifiée dans le résultat courant.Description
string mysql_field_flags ( resource result_identifier, int field_offset)mysql_field_flags() retourne le sémaphore associé au champs spécifié par field_offset. Les sémaphores sont retournés comme des mots, séparés par des espaces, ce qui les rend faciles à séparer, avec la commande explode().
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", "timestamp".
Pour des raisons de compatibilité ascendante, mysql_fieldflags() peut encore être utilisé.
mysql_field_len
Description
int mysql_field_len ( resource result_identifier, int field_offset)mysql_field_len() retourne la taille du champs spécifié par son offset field_offset.
Pour des raisons de compatibilité ascendante, mysql_fieldlen() peut encore être utilisé.
mysql_field_name
Description
string mysql_field_name ( resource result_identifier, int field_index)mysql_field_name() retourne le nom d'une colonne. Les arguments de la fonction sont un identifiant de résultat result_identifier et l'index du champs, ie.mysql_field_name($result,2);.
mysql_field_name() retournera le nom du deuxième champs dans le résultat associé à $result.
Pour des raisons de compatibilité ascendante, mysql_fieldname() peut encore être utilisé.
mysql_field_seek
Description
int mysql_field_seek ( resource result_identifier, int field_offset)Place le pointeur de résultat sur le champs spécifié. Lors du prochain appel à mysql_fetch_field() qui n'aura pas d'argument d'index de champs, le champs désormais pointé sera retourné.
Voir aussi mysql_fetch_field().
mysql_field_table
Description
string mysql_field_table ( resource result_identifier, int field_offset)mysql_field_table() retourne le nom de la table où se trouve une colonne. Pour des raisons de compatibilité ascendante, mysql_fieldtable() peut encore être utilisé.
mysql_field_type
(PHP 3, PHP 4 )
mysql_field_type -- Retourne le type de la colonne spécifiée dans le résultat courant.Description
string mysql_field_type ( resource result_identifier, int field_offset)mysql_field_type() est similaire à la fonction mysql_field_name(). Les arguments sont identiques, mais c'est le type du champs qui est retourné. Il vaudra "int", "real", "string", "blob", ou d'autres, comme détaillé dans la documentation MySQL.
Exemple 1. Types mysql field
|
Pour des raisons de compatibilité ascendante, mysql_fieldtype() peut encore être utilisé.
mysql_free_result
Description
int mysql_free_result ( resource result_identifier)mysql_free_result() n'est à appeler que si vous avez peur d'utiliser trop de mémoire durant l'exécution de votre script. Toute la mémoire associée à l'identifiant de résultat sera automatiquement libérée.
Pour des raisons de compatibilité ascendante, mysql_freeresult() peut encore être utilisé.
mysql_get_client_info
Description
string mysql_get_client_info ( void )mysql_get_client_info() retourne une chaîne qui représente le numéro de version du client utilisé par PHP.
mysql_get_client_info() a été ajoutée en PHP 4.0.5.
mysql_get_host_info
Description
string mysql_get_host_info ( [resource link_identifier])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. Si link_identifier est omis, la dernière connexion ouverte est utilisée.
mysql_get_host_info() a été ajoutée en PHP 4.0.5.
mysql_get_proto_info
Description
string mysql_get_proto_info ( [resource link_identifier])mysql_get_proto_info() retourne une chaîne qui représente la version du protocole utilisé par la connexion link_identifier. Si link_identifier est omis, la dernière connexion ouverte est utilisée.
mysql_get_proto_info() a été ajoutée en PHP 4.0.5.
mysql_get_server_info
Description
string mysql_get_server_info ( [resource link_identifier])mysql_get_server_info() retourne une chaîne qui représente la version du serveur, dont la connexion est Si link_identifier est omis, la dernière connexion ouverte est utilisée.
mysql_get_server_info() a été ajoutée en PHP 4.0.5.
mysql_info
Description
string mysql_info ( [resource link_identifier])mysql_info() returns detailed information about the last query using the given link_identifier. If link_identifier isn't specified, the last opened link is assumed.
mysql_info() returns a string for all statements listed below. For all other FALSE. The string format depends on the given statement.
Exemple 1. Relevant MySQL Statements
|
Note : mysql_info() returns a non-FALSE value for the INSERT ... VALUES statement only if multiple value lists are specified in the statement.
See also: mysql_affected_rows()
mysql_insert_id
Description
int mysql_insert_id ( [resource link_identifier])mysql_insert_id() retourne le dernier identifiant généré par un champs de type AUTO_INCREMENT, sur la connexion MySQL courante, ou bien sÛr la connexion spécifiée par link_identifier. mysql_insert_id() ne prend aucun argument. Elle retourne le dernier identifiant généré par la dernière fonction INSERT effectuée.
mysql_list_dbs
Description
resource mysql_list_dbs ( [resource link_identifier])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 bien sÛr la connexion spécifiée par link_identifier. Utilisez la fonction mysql_tablename() pour lire toutes les bases de données.
Pour des raisons de compatibilité ascendante, mysql_listdbs() est encore disponible.
mysql_list_fields
Description
resource mysql_list_fields ( string database_name, string table_name [, resource link_identifier])mysql_list_fields() recherche les informations relatives à la table table_name sur la connexion MySQL courante, ou bien sÛr la connexion spécifiée par link_identifier. Les arguments sont la base de données et le nom de la table. Un pointeur de résultat est retourné et pourra être passé à mysql_field_flags(), mysql_field_len(), mysql_field_name() et mysql_field_type().
Un identifiant de résultat est un entier positif. La fonction retourne -1 si une erreur survient. Une chaîne décrivant le problème rencontré sera placée dans la variable $phperrmsg et, à moins que la fonction n'ait été appelée sous la forme @mysql(), cette erreur sera aussi affichée.
Pour des raisons de compatibilité ascendante, mysql_listfields() est encore disponible.
mysql_list_processes
Description
resource mysql_list_processes ( [resource link_identifier])mysql_list_processes() returns a result pointer describing the current server threads.
Exemple 1. mysql_list_processes() example
The above example would produce the following output:
|
See also: mysql_thread_id()
mysql_list_tables
Description
resource mysql_list_tables ( string database [, resource link_identifier])mysql_list_tables() prend le nom d'une base de données database et retourne un identifiant de résultat, qui contiendra la liste des tables sur la connexion MySQL courante, ou bien sÛr la connexion spécifiée par link_identifier. La fonction mysql_tablename() est le meilleur moyen d'extraire les noms des tables depuis l'identifiant de résultat.
Pour des raisons de compatibilité ascendante, mysql_listtables() est encore disponible.
mysql_num_fields
Description
int mysql_num_fields ( resource result_identifier)mysql_num_fields() retourne le nombre de champs du résultat result_identifier.
Voir aussi mysql_db_query(), mysql_query(), mysql_fetch_field() et mysql_num_rows().
Pour des raisons de compatibilité ascendante mysql_numfields() est encore disponible.
mysql_num_rows
Description
int mysql_num_rows ( resource result_identifier)mysql_num_rows() retourne le nombre de lignes d'un résultat. Cette commande n'est valide que pour les commandes SELECT . Pour connaître le nombre de lignes retournées par INSERT, UPDATE ou DELETE, utilisez mysql_affected_rows().
Exemple 1. Exemple mysql_num_rows() par crubel@trilizio.org
|
Voir aussi mysql_db_query(), mysql_query() et mysql_fetch_row().
Pour des raisons de compatibilité ascendante mysql_numrows() est encore disponible.
mysql_pconnect
Description
resource mysql_pconnect ( [string server [, string username [, string password]]])mysql_pconnect() retourne un lien persistant positif en cas de succès et sinon FALSE en cas d'erreur.
mysql_pconnect() établit une connexion persistante à un serveur MySQL. Tous les arguments sont optionnels et des valeurs par défaut seront utilisér en cas d'omission ('localhost', nom d'utilisateur propriétaire du processus, mot de passe vide).
Le nom de l'hôte peut aussi inclure le numéro de port, c'est-à-dire "hostname:port" ou un chemin jusqu'à la socket :/path/to/socket pour l'hôte local.
Note : Le support de ":port" a été ajouté à partir de la version 3.0B4.
Le support de ":/path/to/socket" a été ajouté à partir de la version 3.0.10.
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 permanente 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'.
mysql_ping
Description
bool mysql_ping ( [resource link_identifier])mysql_ping() checks whether or not the connection to the server is working. If it has gone down, an automatic reconnection is attempted. This function can be used by scripts that remain idle for a long while, to check whether or not the server has closed the connection and reconnect if necessary. mysql_ping() returns TRUE if the connection to the server is working, otherwise FALSE.
See also: mysql_thread_id(), mysql_list_processes().
mysql_query
Description
resource mysql_query ( string query [, resource link_identifier])mysql_query() envoie une requête SQL à la base de données actuellement active sur le serveur MysQL. Si link_identifier n'est pas précisé, la dernière connexion est utilisée. Si aucune connexion n'a été ouverte, la fonction tentera d'en ouvrir une, avec la fonction mysql_connect() mais sans aucun paramètre (c'est-à-dire avec les valeurs par défaut).
mysql_query() retourne TRUE ou FALSE, pour indiquer le succès ou l'échec de la requête. En cas de retour TRUE, la requête était valide et a pu être exécuté sur le serveur. Cela n'indique pas le nombre de lignes affectées, ou retournées. Il est parfaitement possible qu'une requête valide n'affecte aucune ligne ou ne retourne aucune ligne.
L'exemple suivant est syntaxiquement invalide, ce qui conduit mysql_query() à l'échec et retourne FALSE:
L'exemple suivant est sémantiquement invalide si my_col n'est pas une colonne de la table my_tbl, ce qui conduit mysql_query() à l'échec et retourne FALSE :
mysql_query() échouera aussi et retournera aussi FALSE si les droits d'accès ne sont pas suffisants.
En supposant que la requête réussisse, vous pouvez appeler mysql_affected_rows() pour connaître le nombre de lignes affectées (pour les commandes DELETE, INSERT, REPLACE, ou UPDATE ). Pour les commandes SELECT , mysql_query() retourne un identifiant de résultat que vous pouvez passer à mysql_result(). Lorsque vous avez terminé avec le résultat, libérez la mémoire avec mysql_free_result().
Voir aussi mysql_affected_rows(), mysql_unbuffered_query(), mysql_db_query(), mysql_free_result(), mysql_result(), mysql_select_db() et mysql_connect().
mysql_real_escape_string
(PHP 4 CVS only)
mysql_real_escape_string -- Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection.Description
string mysql_real_escape_string ( string unescaped_string [, resource link_identifier])This function will escape special characters in the unescaped_string, taking into account the current charset of the connection so that it is safe to place it in a mysql_query().
Note : mysql_real_escape_string() does not escape % and _.
Exemple 1. mysql_real_escape_string() example
The above example would produce the following output:
|
See also: mysql_escape_string(), mysql_character_set_name().
mysql_result
Description
mixed mysql_result ( resource result_identifier, int row [, mixed field])mysql_result() retourne le contenu d'un champs dans le résultat MySQL result_identifier. L'argument field peut-être un offset de champs, ou le nom d'un champs, ou le nom de la table + point + le nom du champs ("table.champs"). Si la colonne a été aliasée, utilisez de préférence l'alias.
Lorsque vous travaillez 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ériques est aussi beaucoup plus rapide que spécifier un nom littéral.
Les appels mysql_result() ne devraient pas être mélangés avec d'autres fonctions qui travaillent aussi sur le résultat.
Alternatives à haut rendement, RECOMMANDEES : mysql_fetch_row(), mysql_fetch_array() et mysql_fetch_object().
mysql_select_db
Description
int mysql_select_db ( string database_name [, resource link_identifier])mysql_select_db() retourne TRUE en cas de succès, FALSE sinon.
mysql_select_db() change la base de données active sur la connexion représentée par link_identifier. Si aucun identifiant n'est spécifié, la dernière connexion est utilisée. S'il n'y a pas de dernière connexion, la fonction tentera de se connecter seule, avec mysql_connect() et les paramètres par défaut.
Toutes les requêtes suivantes avec mysql_query() seront faites avec la base de données active.
Voir aussi mysql_connect(), mysql_pconnect() et mysql_query().
Pour des raisons de compatibilité ascendante mysql_selectdb() est encore disponible.
mysql_stat
Description
string mysql_stat ( [resource link_identifier])mysql_stat() returns the current server status.
Note : mysql_stat() currently only returns status for uptime, threads, queries, open tables, flush tables and queries per second. For a complete list of other status variables you have to use the SHOW STATUS SQL command.
Exemple 1. mysql_stat() example
The above example would produce the following output:
|
mysql_tablename
Description
string mysql_tablename ( resource result_identifier, int i)mysql_tablename() prend le pointeur de résultat obtenu avec mysql_list_tables() ou bien un index entier et retourne le nom de la table. La fonction mysql_num_rows() peut être utilisée pour déterminer le nombre de tables dans le pointeur de résultat.
mysql_thread_id
Description
int mysql_thread_id ( [resource link_identifier])mysql_thread_id() returns the current thread ID. If the connection is lost and you reconnect with mysql_ping(), the thread ID will change. This means you should not get the thread ID and store it for later. You should get it when you need it.
See also: mysql_ping(), mysql_list_processes().
mysql_unbuffered_query
Description
resource mysql_unbuffered_query ( string query [, resource link_identifier [, int result_mode]])mysql_unbuffered_query() envoie la requête SQL query au serveur MySQL identifié par link_identifier, sans préparer les résultats pour la lecture, comme le fait mysql_query(). D'une part, cela réduit considérablement la consommation de mémoire par MySQL, lorsque les requêtes génère des résultats de grandes tailles. D'autre part, vous pourrez utiliser les résultats dès que la première ligne aura été lue : pas besoin d'attendre que la requête ait complètement été exécutée.
Note : L'intérêt de mysql_unbuffered_query() est tempéré par une limitation : mysql_num_rows() ne fonctionne pas sur une ressource retournée par mysql_unbuffered_query(). Vous devez 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.
Voir aussi mysql_query().
LXIV. Mohawk Software session handler functions
msession is an interface to a high speed session daemon which can run either locally or remotely. It is designed to provide consistent session management for a PHP web farm.
The session server software can be found at http://www.mohawksoft.com/phoenix/.
- Table des matières
- msession_connect -- Connect to msession server
- msession_count -- Get session count
- msession_create -- Create a session
- msession_destroy -- Destroy a session
- msession_disconnect -- Close connection to msession server
- msession_find -- Find value
- msession_get_array -- Get array of ... ?
- msession_get -- Get value from session
- msession_getdata -- Get data ... ?
- msession_inc -- Increment value in session
- msession_list -- List ... ?
- msession_listvar -- List sessions with variable
- msession_lock -- Lock a session
- msession_plugin -- Call an escape function within the msession personality plugin
- msession_randstr -- Get random string
- msession_set_array -- Set array of ...
- msession_set -- Set value in session
- msession_setdata -- Set data ... ?
- msession_timeout -- Set/get session timeout
- msession_uniq -- Get uniq id
- msession_unlock -- Unlock a session
msession_connect
Description
bool msession_connect ( string host, string port)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_count
Description
int msession_count ( void)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_create
Description
bool msession_create ( string session)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_destroy
Description
bool msession_destroy ( string name)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_disconnect
Description
void msession_disconnect ( void)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_find
Description
array msession_find ( string name, string value)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_get_array
Description
array msession_get_array ( string session)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_get
Description
string msession_get ( string session, string name, string value)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_getdata
Description
string msession_getdata ( string session)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_inc
Description
string msession_inc ( string session, string name)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_list
Description
array msession_list ( void)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_listvar
Description
array msession_listvar ( string name)Returns an associative array of value, session for all sessions with a variable named name.
Used for searching sessions with common attributes.
msession_lock
Description
int msession_lock ( string name)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_plugin
Description
string msession_plugin ( string session, string val [, string param])| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_randstr
Description
string msession_randstr ( int param)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_set_array
Description
bool msession_set_array ( string session, array tuples)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_set
Description
bool msession_set ( string session, string name, string value)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_setdata
Description
bool msession_setdata ( string session, string value)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_timeout
Description
int msession_timeout ( string session [, int param])| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_uniq
Description
string msession_uniq ( int param)| Avertissement |
This function is currently not documented, only the argument list is available. |
msession_unlock
LXV. Fonctions muscat
- Table des matières
- muscat_close -- Ferme la connexion à muscat
- muscat_get -- Lit la réponse de l'API muscat
- muscat_give -- Envoie une chaîne à l'API de base muscat
- muscat_setup_net -- Crée une nouvelle session muscat
- muscat_setup -- Crée une nouvelle session
muscat_close
Description
int muscat_close ( resource muscat_handle)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
muscat_get
Description
string muscat_get ( resource muscat_handle)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
muscat_give
Description
int muscat_give ( resource muscat_handle, string string)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
muscat_setup_net
Description
resource muscat_setup_net ( string muscat_host, int port)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
muscat_setup
Description
resource muscat_setup ( int size [, string muscat_dir])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
LXVI. Réseau
- Table des matières
- checkdnsrr -- Résolution DNS d'une adresse IP.
- closelog -- Ferme la connexion à l'historique système.
- debugger_off -- Inactive le debugger interne de PHP.
- debugger_on -- Active le debugger interne de PHP.
- define_syslog_variables -- Initialise toutes les constantes liées au syslog
- fsockopen -- Ouvre une socket de connexion Internet ou Unix.
- gethostbyaddr -- Retourne le nom d'hôte correspondant à une IP.
- gethostbyname -- Retourne l'adresse IP correspondant à un hôte.
- gethostbynamel -- Retourne la liste d'IP correspondante à un hôte.
- getmxrr -- Retourne les enregistrements MX d'un hôte.
- getprotobyname -- Retourne le numéro de protocole associé à un nom de protocole
- getprotobynumber -- Retourne le nom de protocole associé à un numéro de protocole
- getservbyname -- Retourne le numéro de port associé à un service Internet et un protocole.
- getservbyport -- Retourne le service Internet qui correspond au port et protocole.
- ip2long -- Convertit une chaîne contenant une adresse (IPv4) IP numérique en adresse littérale.
- long2ip -- Convertit une adresse IP (IPv4) en adresse IP numérique
- openlog -- Ouvre la connexion à l'historique système.
- pfsockopen -- Ouvre une socket de connexion Internet ou Unix persistante.
- socket_get_status -- Retourne les informations sur une socket
- socket_set_blocking -- Active/désactive le mode bloquant d'une socket.
- socket_set_timeout -- Fixe la durée de vie de la socket
- syslog -- Génère un message dans l'historique système.
checkdnsrr
Description
int checkdnsrr ( string host [, string type])checkdnsrr() recherche l'enregistrement DNS de type type correspondant à l'hôte host. Retourne TRUE si un record a été trouvé, et FALSE en cas d'erreur ou d'échec.
type peut prendre les valeurs suivantes : A, MX, NS, SOA, PTR, CNAME, ou ANY. Par défaut, la valeur est : MX.
host peut être soit une adresse IP de la forme x.x.x.x avec x entre 0 et 256, soit un nom d'hôte.
checkdnsrr() n'est pas disponible sous Windows.
Voir aussi getmxrr(), gethostbyaddr(), gethostbyname(), gethostbynamel() et la page de manuel named(8).
closelog
Description
int closelog ( void)closelog() ferme le pointeur qui sert à écrire dans l'historique système. L'utilisation de closelog() est optionnelle.
Voir aussi define_syslog_variables(), syslog() et openlog().
debugger_off
Description
int debugger_off ( void)debugger_off() inactive le debuggeur interne de PHP. Le debuggeur est toujours en cours de développement.
debugger_on
Description
int debugger_on ( string address)debugger_on() active le debugger interne de PHP, et le connecte à l'adresse address. Le debuggeur est toujours en cours de développement.
define_syslog_variables
Description
void define_syslog_variables ( void)define_syslog_variables() initialise toutes les constantes utilisées par les fonctions de syslog.
Voir aussi openlog(), syslog() et closelog().
fsockopen
Description
int fsockopen ( [string udp://hostname, int port [, int errno [, string errstr [, float timeout]]]])fsockopen() crée un flot de connexion à l'Internet (AF_INET) ou à un domaine Unix (AF_UNIX). Via Internet, cette fonction va ouvrir une socket de connexion TCP avec l'hôte hostname sur le port port. Pour les connexions UDP, vous devez explicitement spécifier le protocole : udp://hostname. Via un domaine Unix, hostname représente le chemin jusqu'à la socket, et port doit être mis à 0. L'option timeout sert à donner une durée maximale à cet appel.
fsockopen() retourne un pointeur de fichier qui peut être utilisé avec d'autres fonctions fichiers, telles que fgets(), fgetss(), fputs(), fclose() et feof().
Si l'appel échoue, fsockopen() retourne FALSE, et si les options errno et errstr ont été fournies, elles contiennent désormais les raisons de l'échec. Si l'erreur retournée est 0 et que la fonction retourne FALSE, c'est une indication d'erreur. C'est probablement du à une erreur d'initialisation de la socket. Notez que errno et errstr sont passées par référence.
Suivant les environnements, le type 'domaine Unix' ou l'option timeout ne sont pas toujours disponibles.
La socket sera ouverte par défaut en mode bloquant. Vous pouvez changer de mode en utilisant : socket_set_blocking().
Note : Le paramètre timeout a été introduit en PHP 3.0.9 et le support UDP en PHP 4.
gethostbyaddr
Description
string gethostbyaddr ( string ip_address)gethostbyaddr() retourne le nom d'hôte correspondant à l'IP ip_address. Si une erreur survient, retourne ip_address.
Voir aussi gethostbyname().
gethostbyname
Description
string gethostbyname ( string hostname)gethostbyname() retourne l'adresse IP correspondant à l'hôte hostname.
Voir aussi gethostbyaddr().
gethostbynamel
Description
array gethostbynamel ( string hostname)gethostbynamel() retourne la liste d'IP correspondant à l'hôte hostname.
Voir aussi gethostbyname(), gethostbyaddr(), checkdnsrr(), getmxrr() et la page 8 du manuel.
getmxrr
Description
int getmxrr ( string hostname, array mxhosts [, array weight])getmxrr() effectue une recherche DNS pour obtenir les enregistrements MX de l'hôte hostname. Retourne TRUE si des enregistrements sont trouvés, et FALSE si une erreur est rencontrée, ou si la recherche échoue.
La liste des enregistrements MX est placée dans le tableau mxhosts. Si le tableau weight est fourni, il sera rempli par les informations de poids.
Voir aussi checkdnsrr(), gethostbyname(), gethostbynamel(), gethostbyaddr(), et la page 8 du manuel.
getprotobyname
Description
int getprotobyname ( string name)getprotobyname() retourne le numéro de protocole associé avec le nom de protocole name, comme dans /etc/protocols.
Voir aussi getprotobynumber().
getprotobynumber
Description
string getprotobynumber ( int number)getprotobynumber() retourne le nom de protocole associé avec le numéro de protocole name, comme dans /etc/protocols.
Voir aussi getprotobyname().
getservbyname
Description
int getservbyname ( string service, string protocol)getservbyname() retourne le numéro de port associé au service service et au protocole protocol, comme dans /etc/services. protocol vaut soit tcp, soit udp.
Voir aussi getservbyport().
getservbyport
Description
string getservbyport ( int port, string protocol)getservbyport() le service internet associé au port port pour le protocole protocol comme dans /etc/services. protocol vaut soit tcp, soit udp.
Voir aussi getservbyname().
ip2long
(PHP 4 )
ip2long -- Convertit une chaîne contenant une adresse (IPv4) IP numérique en adresse littérale.Description
int ip2long ( string ip_address)ip2long() génère une adresse IPv4 à partir de son équivalent numérique.
Ce second exemple montre comment afficher une adresse convertie à l'aide de la fonction printf() :
Voir aussi long2ip()
long2ip
Description
string long2ip ( int proper_address)long2ip() génère une adresse IP (format aaa.bbb.ccc.ddd) à partir de sa représentation littérale.
Voir aussi ip2long()
openlog
Description
int openlog ( string ident, int option, int facility)openlog() ouvre la connexion à l'historique système. La chaîne ident sera ajoutée à chaque message. Les valeurs de option et facility sont données ci-dessous. L'utilisation de openlog() est optionnelle; cette fonction sera automatiquement appelée par syslog() si nécessaire, et dans ce cas, l'identification sera mise par défaut à FALSE. facility sert à indiquer quel programme enregistre ce message. Cela vous permet de spécifier (sur la machine d'historique) comment traiter les messages venant de plusieurs serveurs.
Tableau 1. Options openlog()
| Constante | Description |
|---|---|
| LOG_CONS | Si une erreur survient lors de l'envoi des données au gestionnaire d'historique, écrire directement l'erreur sur la console. |
| LOG_NDELAY | Ouvre immédiatement une connexion au gestionnaire d'historique |
| LOG_ODELAY | Retarde l'ouverture de la connexion jusqu'à ce que le premier message soit enregistré (par défaut) |
| LOG_PERROR | Envoie le message au gestionnaire standard |
| LOG_PID | Inclut le PID à chaque message |
Tableau 2. Paramètre facility de openlog()
| Constante | Description |
|---|---|
| LOG_AUTH | sécurité/messages d'autorisation (utilisez LOG_AUTHPRIV, pour remplacer cette constante sur les systèmes où elle est définie). |
| LOG_AUTHPRIV | sécurité/messages d'autorisation (privé) |
| LOG_CRON | démon horloge (cron et at) |
| LOG_DAEMON | autres démons système |
| LOG_KERN | noyau (kernel) |
| LOG_LOCAL0 ... LOG_LOCAL7 | réservé pour utilisation ultérieure |
| LOG_LPR | imprimante (line printer subsystem) |
| LOG_MAIL | messagerie mail |
| LOG_NEWS | USENET : groupes de news (newsgroup) |
| LOG_SYSLOG | messages générés en interne par syslogd |
| LOG_USER | messages utilisateurs générique |
| LOG_UUCP | UUCP subsystem |
Voir aussi define_syslog_variables(), syslog() et closelog().
pfsockopen
Description
int pfsockopen ( string hostname, int port [, int errno [, string errstr [, int timeout]]])pfsockopen() se comporte exactement comme fsockopen() mais la connexion ouverte le reste, même après la fin du script. C'est la version persistante de fsockopen().
socket_get_status
Description
array socket_get_status ( resource socket_get_status)socket_get_status() retourne les informations sur la socket socket_get_status, et fournit la réponse sous la forme d'un tableau à quatre entrées:
timed_out (boolean) - La socket a expirée en attendant des données
blocked (boolean) - La socket a été bloquée
eof (boolean) - Indique un événement fin de fichier (EOF)
unread_bytes (int) - Nombre d'octets restant dans les buffers de la socket.
Voir aussi accept_connect(), bind(), connect(), listen() et strerror().
socket_set_blocking
Description
int socket_set_blocking ( int socket_descriptor, int mode)Si mode est FALSE, la socket est mise en mode non bloquant, et si il est TRUE, la socket est mise en mode bloquant. Cela affecte des appels tels que fgets() qui lisent depuis une socket. En mode non bloquant, un appel fgets() retournera immediatement toujours TRUE tandis qu'en mode bloquant, elle va attendre que des données arrivent pour répondre TRUE.
socket_set_timeout
Description
boolean socket_set_timeout ( int socket_descriptor, int seconds, int microseconds)socket_set_timeout() fixe la durée de vie de la socket socket_descriptor, exprimée comme la somme de seconds secondes et microseconds micro-secondes.
Cette fonction s'appelait set_socket_timeout() mais elle est désormais obsolète.
Voir aussi fsockopen() et fopen().
syslog
Description
int syslog ( int priority, string message)syslog() génère un message qui sera inscrit dans l'historique par le système. priority est une combinaison des valeurs d'accès et de niveau, qui seront décrites dans la prochaine section. Le dernier argument est le message à envoyer. Attention : les caractères %m seront remplacés par l'erreur (sous forme de chaîne), présente dans errno.
Tableau 1. Priorités syslog()(en ordre décroissant)
| Constante | Description |
|---|---|
| LOG_EMERG | système inutilisable |
| LOG_ALERT | une décision doit être prise immédiatement |
| LOG_CRIT | conditions critiques |
| LOG_ERR | conditions d'erreur |
| LOG_WARNING | conditions d'alerte |
| LOG_NOTICE | condition normale, mais significative |
| LOG_INFO | message d'information |
| LOG_DEBUG | message de débuggage |
Exemple 1. Utilisation de syslog()
|
Avec Windows NT, l'historique est pris en charge par Event Log.
LXVII. Ncurses terminal screen control functions
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
What is ncurses?
ncurses (new curses) is a free software emulation of curses in System V Rel 4.0 (and above). It uses terminfo format, supports pads, colors, multiple highlights, form characters and function key mapping.
Platforms
Ncurses is available for the following platforms:
AIX
BeOS
Cygwin
Digital Unix (aka OSF1)
FreeBSD
GNU/Linux
HPUX
IRIX
OS/2
SCO OpenServer
Solaris
SunOS
Requirements
You need the ncurses libraries and headerfiles. Download the latest version from the ftp://ftp.gnu.org/pub/gnu/ncurses/ or from an other GNU-Mirror.
Installation
To get these functions to work, you have to compile the CGI version of PHP with --with-ncurses.
Ncurses predefined constants
Error codes
On error ncurses functions return NCURSES_ERR.
Colors
Tableau 1. ncurses color constants
| constant | meaning |
|---|---|
| NCURSES_COLOR_BLACK | no color (black) |
| NCURSES_COLOR_WHITE | white |
| NCURSES_COLOR_RED | red - supported when terminal is in color mode |
| NCURSES_COLOR_GREEN | green - supported when terminal is in color mod |
| NCURSES_COLOR_YELLOW | yellow - supported when terminal is in color mod |
| NCURSES_COLOR_BLUE | blue - supported when terminal is in color mod |
| NCURSES_COLOR_CYAN | cyan - supported when terminal is in color mod |
| NCURSES_COLOR_MAGENTA | magenta - supported when terminal is in color mod |
Keys
Tableau 2. ncurses key constants
| constant | meaning |
|---|---|
| NCURSES_KEY_F0 - NCURSES_KEY_F64 | function keys F1 - F64 |
| NCURSES_KEY_DOWN | down arrow |
| NCURSES_KEY_UP | up arrow |
| NCURSES_KEY_LEFT | left arrow |
| NCURSES_KEY_RIGHT | right arrow |
| NCURSES_KEY_HOME | home key (upward+left arrow) |
| NCURSES_KEY_BACKSPACE | backspace |
| NCURSES_KEY_DL | delete line |
| NCURSES_KEY_IL | insert line |
| NCURSES_KEY_DC | delete character |
| NCURSES_KEY_IC | insert char or enter insert mode |
| NCURSES_KEY_EIC | exit insert char mode |
| NCURSES_KEY_CLEAR | clear screen |
| NCURSES_KEY_EOS | clear to end of screen |
| NCURSES_KEY_EOL | clear to end of line |
| NCURSES_KEY_SF | scroll one line forward |
| NCURSES_KEY_SR | scroll one line backward |
| NCURSES_KEY_NPAGE | next page |
| NCURSES_KEY_PPAGE | previous page |
| NCURSES_KEY_STAB | set tab |
| NCURSES_KEY_CTAB | clear tab |
| NCURSES_KEY_CATAB | clear all tabs |
| NCURSES_KEY_SRESET | soft (partial) reset |
| NCURSES_KEY_RESET | reset or hard reset |
| NCURSES_KEY_PRINT | |
| NCURSES_KEY_LL | lower left |
| NCURSES_KEY_A1 | upper left of keypad |
| NCURSES_KEY_A3 | upper right of keypad |
| NCURSES_KEY_B2 | center of keypad |
| NCURSES_KEY_C1 | lower left of keypad |
| NCURSES_KEY_C3 | lower right of keypad |
| NCURSES_KEY_BTAB | back tab |
| NCURSES_KEY_BEG | beginning |
| NCURSES_KEY_CANCEL | cancel |
| NCURSES_KEY_CLOSE | close |
| NCURSES_KEY_COMMAND | cmd (command) |
| NCURSES_KEY_COPY | copy |
| NCURSES_KEY_CREATE | create |
| NCURSES_KEY_END | end |
| NCURSES_KEY_EXIT | exit |
| NCURSES_KEY_FIND | find |
| NCURSES_KEY_HELP | help |
| NCURSES_KEY_MARK | mark |
| NCURSES_KEY_MESSAGE | message |
| NCURSES_KEY_MOVE | move |
| NCURSES_KEY_NEXT | next |
| NCURSES_KEY_OPEN | open |
| NCURSES_KEY_OPTIONS | options |
| NCURSES_KEY_PREVIOUS | previous |
| NCURSES_KEY_REDO | redo |
| NCURSES_KEY_REFERENCE | ref (reference) |
| NCURSES_KEY_REFRESH | refresh |
| NCURSES_KEY_REPLACE | replace |
| NCURSES_KEY_RESTART | restart |
| NCURSES_KEY_RESUME | resume |
| NCURSES_KEY_SAVE | save |
| NCURSES_KEY_SBEG | shiftet beg (beginning) |
| NCURSES_KEY_SCANCEL | shifted cancel |
| NCURSES_KEY_SCOMMAND | shifted command |
| NCURSES_KEY_SCOPY | shifted copy |
| NCURSES_KEY_SCREATE | shifted create |
| NCURSES_KEY_SDC | shifted delete char |
| NCURSES_KEY_SDL | shifted delete line |
| NCURSES_KEY_SELECT | select |
| NCURSES_KEY_SEND | shifted end |
| NCURSES_KEY_SEOL | shifted end of line |
| NCURSES_KEY_SEXIT | shifted exit |
| NCURSES_KEY_SFIND | shifted find |
| NCURSES_KEY_SHELP | shifted help |
| NCURSES_KEY_SHOME | shifted home |
| NCURSES_KEY_SIC | shifted input |
| NCURSES_KEY_SLEFT | shifted left arrow |
| NCURSES_KEY_SMESSAGE | shifted message |
| NCURSES_KEY_SMOVE | shifted move |
| NCURSES_KEY_SNEXT | shifted next |
| NCURSES_KEY_SOPTIONS | shifted options |
| NCURSES_KEY_SPREVIOUS | shifted previous |
| NCURSES_KEY_SPRINT | shifted print |
| NCURSES_KEY_SREDO | shifted redo |
| NCURSES_KEY_SREPLACE | shifted replace |
| NCURSES_KEY_SRIGHT | shifted right arrow |
| NCURSES_KEY_SRSUME | shifted resume |
| NCURSES_KEY_SSAVE | shifted save |
| NCURSES_KEY_SSUSPEND | shifted suspend |
| NCURSES_KEY_UNDO | undo |
| NCURSES_KEY_MOUSE | mouse event has occured |
| NCURSES_KEY_MAX | maximum key value |
Mouse
Tableau 3. mouse constants
| Constant | meaning |
|---|---|
| NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED | button (1-4) released |
| NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED | button (1-4) pressed |
| NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED | button (1-4) clicked |
| NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKED | button (1-4) double clicked |
| NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKED | button (1-4) triple clicked |
| NCURSES_BUTTON_CTRL | ctrl pressed during click |
| NCURSES_BUTTON_SHIFT | shift pressed during click |
| NCURSES_BUTTON_ALT | alt pressed during click |
| NCURSES_ALL_MOUSE_EVENTS | report all mouse events |
| NCURSES_REPORT_MOUSE_POSITION | report mouse position |
- Table des matières
- ncurses_addch -- Add character at current position and advance cursor
- ncurses_addchnstr -- Add attributed string with specified length at current position
- ncurses_addchstr -- Add attributed string at current position
- ncurses_addnstr -- Add string with specified length at current position
- ncurses_addstr -- Output text at current position
- ncurses_assume_default_colors -- Define default colors for color 0
- ncurses_attroff -- Turn off the given attributes
- ncurses_attron -- Turn on the given attributes
- ncurses_attrset -- Set given attributes
- ncurses_baudrate -- Returns baudrate of terminal
- ncurses_beep -- Let the terminal beep
- ncurses_bkgd -- Set background property for terminal screen
- ncurses_bkgdset -- Control screen background
- ncurses_border -- Draw a border around the screen using attributed characters
- ncurses_can_change_color -- Check if we can change terminals colors
- ncurses_cbreak -- Switch of input buffering
- ncurses_clear -- Clear screen
- ncurses_clrtobot -- Clear screen from current position to bottom
- ncurses_clrtoeol -- Clear screen from current position to end of line
- ncurses_color_set -- Set fore- and background color
- ncurses_curs_set -- Set cursor state
- ncurses_def_prog_mode -- Saves terminals (program) mode
- ncurses_def_shell_mode -- Saves terminals (shell) mode
- ncurses_define_key -- Define a keycode
- ncurses_delay_output -- Delay output on terminal using padding characters
- ncurses_delch -- Delete character at current position, move rest of line left
- ncurses_deleteln -- Delete line at current position, move rest of screen up
- ncurses_delwin -- Delete a ncurses window
- ncurses_doupdate -- Write all prepared refreshes to terminal
- ncurses_echo -- Activate keyboard input echo
- ncurses_echochar -- Single character output including refresh
- ncurses_end -- Stop using ncurses, clean up the screen
- ncurses_erase -- Erase terminal screen
- ncurses_erasechar -- Returns current erase character
- ncurses_filter --
- ncurses_flash -- Flash terminal screen (visual bell)
- ncurses_flushinp -- Flush keyboard input buffer
- ncurses_getch -- Read a character from keyboard
- ncurses_getmouse -- Reads mouse event
- ncurses_halfdelay -- Put terminal into halfdelay mode
- ncurses_has_colors -- Check if terminal has colors
- ncurses_has_ic -- Check for insert- and delete-capabilities
- ncurses_has_il -- Check for line insert- and delete-capabilities
- ncurses_has_key -- Check for presence of a function key on terminal keyboard
- ncurses_hline -- Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch -- Get character and attribute at current position
- ncurses_init_color -- Set new RGB value for color
- ncurses_init_pair -- Allocate a color pair
- ncurses_init -- Initialize ncurses
- ncurses_insch -- Insert character moving rest of line including character at current position
- ncurses_insdelln -- Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln -- Insert a line, move rest of screen down
- ncurses_insstr -- Insert string at current position, moving rest of line right
- ncurses_instr -- Reads string from terminal screen
- ncurses_isendwin -- Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok -- Enable or disable a keycode
- ncurses_killchar -- Returns current line kill character
- ncurses_longname -- Returns terminals description
- ncurses_mouseinterval -- Set timeout for mouse button clicks
- ncurses_mousemask -- Sets mouse options
- ncurses_move -- Move output position
- ncurses_mvaddch -- Move current position and add character
- ncurses_mvaddchnstr -- Move position and add attrributed string with specified length
- ncurses_mvaddchstr -- Move position and add attributed string
- ncurses_mvaddnstr -- Move position and add string with specified length
- ncurses_mvaddstr -- Move position and add string
- ncurses_mvcur -- Move cursor immediately
- ncurses_mvdelch -- Move position and delete character, shift rest of line left
- ncurses_mvgetch -- Move position and get character at new position
- ncurses_mvhline -- Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch -- Move position and get attributed character at new position
- ncurses_mvvline -- Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr -- Add string at new position in window
- ncurses_napms -- Sleep
- ncurses_newwin -- Create a new window
- ncurses_nl -- Translate newline and carriage return / line feed
- ncurses_nocbreak -- Switch terminal to cooked mode
- ncurses_noecho -- Switch off keyboard input echo
- ncurses_nonl -- Do not translate newline and carriage return / line feed
- ncurses_noqiflush -- Do not flush on signal characters
- ncurses_noraw -- Switch terminal out of raw mode
- ncurses_putp --
- ncurses_qiflush -- Flush on signal characters
- ncurses_raw -- Switch terminal into raw mode
- ncurses_refresh -- Refresh screen
- ncurses_resetty -- Restores saved terminal state
- ncurses_savetty -- Saves terminal state
- ncurses_scr_dump -- Dump screen content to file
- ncurses_scr_init -- Initialize screen from file dump
- ncurses_scr_restore -- Restore screen from file dump
- ncurses_scr_set -- Inherit screen from file dump
- ncurses_scrl -- Scroll window content up or down without changing current position
- ncurses_slk_attr -- Returns current soft label key attribute
- ncurses_slk_attroff --
- ncurses_slk_attron --
- ncurses_slk_attrset --
- ncurses_slk_clear -- Clears soft labels from screen
- ncurses_slk_color -- Sets color for soft label keys
- ncurses_slk_init -- Initializes soft label key functions
- ncurses_slk_noutrefresh -- Copies soft label keys to virtual screen
- ncurses_slk_refresh -- Copies soft label keys to screen
- ncurses_slk_restore -- Restores soft label keys
- ncurses_slk_touch -- Fources output when ncurses_slk_noutrefresh is performed
- ncurses_standend -- Stop using 'standout' attribute
- ncurses_standout -- Start using 'standout' attribute
- ncurses_start_color -- Start using colors
- ncurses_termattrs -- Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname -- Returns terminals (short)-name
- ncurses_timeout -- Set timeout for special key sequences
- ncurses_typeahead -- Specify different filedescriptor for typeahead checking
- ncurses_ungetch -- Put a character back into the input stream
- ncurses_ungetmouse -- Pushes mouse event to queue
- ncurses_use_default_colors -- Assign terminal default colors to color id -1
- ncurses_use_env -- Control use of environment information about terminal size
- ncurses_use_extended_names -- Control use of extended names in terminfo descriptions
- ncurses_vidattr --
- ncurses_vline -- Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_wrefresh -- Refresh window on terminal screen
ncurses_addch
Description
int ncurses_addch ( int ch)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_addchnstr
(PHP 4 >= 4.2.0)
ncurses_addchnstr -- Add attributed string with specified length at current positionDescription
int ncurses_addchnstr ( string s, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_addchstr
Description
int ncurses_addchstr ( string s)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_addnstr
Description
int ncurses_addnstr ( string s, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_addstr
Description
int ncurses_addstr ( string text)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_assume_default_colors
Description
int ncurses_assume_default_colors ( int fg, int bg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_attroff
Description
int ncurses_attroff ( int attributes)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_attron
Description
int ncurses_attron ( int attributes)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_attrset
Description
int ncurses_attrset ( int attributes)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_baudrate
Description
int ncurses_baudrate ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_beep
Description
int ncurses_beep ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_beep() sends an audlible alert (bell) and if its not possible flashes the screen. Returns FALSE on success, otherwise TRUE.
See also: ncurses_flash()
ncurses_bkgd
Description
int ncurses_bkgd ( int attrchar)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_bkgdset
Description
void ncurses_bkgdset ( int attrchar)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_border
Description
int ncurses_border ( int left, int right, int top, int bottom, int tl_corner, int tr_corner, int bl_corner, int br_corner)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_can_change_color
Description
bool ncurses_can_change_color ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function ncurses_can_change_color() returns TRUE or FALSE, depending on whether the terminal has color capabilities and whether the programmer can change the colors.
ncurses_cbreak
Description
bool ncurses_cbreak ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_cbreak() disables line buffering and character processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the program.
ncurses_cbreak() returns TRUE or NCURSES_ERR if any error occured.
See also: ncurses_nocbreak()
ncurses_clear
Description
bool ncurses_clear ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_clear() clears the screen completely without setting blanks. Returns FALSE on success, otherwise TRUE.
Note: ncurses_clear() clears the screen without setting blanks, which have the current background rendition. To clear screen with blanks, use ncurses_erase().
See also: ncurses_erase()
ncurses_clrtobot
Description
bool ncurses_clrtobot ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_clrtobot() erases all lines from cursor to end of screen and creates blanks. Blanks created by ncurses_clrtobot() have the current background rendition. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_clear(), ncurses_clrtoeol()
ncurses_clrtoeol
Description
bool ncurses_clrtoeol ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_clrtoeol() erases the current line from cursor position to the end. Blanks created by ncurses_clrtoeol() have the current background rendition. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_clear(), ncurses_clrtobot()
ncurses_color_set
Description
int ncurses_color_set ( int pair)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_curs_set
Description
int ncurses_curs_set ( int visibility)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_def_prog_mode
Description
bool ncurses_def_prog_mode ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_def_prog_mode() saves the current terminal modes for program (in curses) for use by ncurses_reset_prog_mode(). Returns FALSE on success, otherwise TRUE.
See also: ncurses_reset_prog_mode()
ncurses_def_shell_mode
Description
bool ncurses_def_shell_mode ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_def_shell_mode() saves the current terminal modes for shell (not in curses) for use by ncurses_reset_shell_mode(). Returns FALSE on success, otherwise TRUE.
See also: ncurses_reset_shell_mode()
ncurses_define_key
Description
int ncurses_define_key ( string definition, int keycode)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_delay_output
Description
int ncurses_delay_output ( int milliseconds)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_delch
Description
bool ncurses_delch ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_delch() deletes the character under the cursor. All characters to the right of the cursor on the same line are moved to the left one position and the last character on the line is filled with a blank. The cursor position does not change. Returns FALSE on success, otherwise TRUE.
See also: ncurses_deleteln()
ncurses_deleteln
Description
bool ncurses_deleteln ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_deleteln() deletes the current line under cursorposition. All lines below the current line are moved up one line. The bottom line of window is cleared. Cursor position does not change. Returns FALSE on success, otherwise TRUE.
See also: ncurses_delch()
ncurses_delwin
Description
int ncurses_delwin ( resource window)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_doupdate
Description
bool ncurses_doupdate ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_doupdate()() compares the virtual screen to the physical screen and updates the physical screen. This way is more effective than using multiple refresh calls. Returns FALSE on success, TRUE if any error occured.
ncurses_echo
Description
bool ncurses_echo ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_echo() enables echo mode. All characters typed by user are echoed by ncurses_getch(). Returns FALSE on success, TRUE if any error occured.
To disable echo mode use ncurses_noecho().
ncurses_echochar
Description
int ncurses_echochar ( int character)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_end
Description
int ncurses_end ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_erase
Description
bool ncurses_erase ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_erase() fills the terminal screen with blanks. Created blanks have the current background rendition, set by ncurses_bkgd(). Returns FALSE on success, TRUE if any error occured.
See also: ncurses_bkgd(), ncurses_clear()
ncurses_erasechar
Description
string ncurses_erasechar ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_erasechar() returns the current erase char character.
See also: ncurses_killchar()
ncurses_filter
Description
int ncurses_filter ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_flash
Description
bool ncurses_flash ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_flash() flashes the screen, and if its not possible, sends an audible alert (bell). Returns FALSE on success, otherwise TRUE.
See also: ncurses_beep()
ncurses_flushinp
Description
bool ncurses_flushinp ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The ncurses_flushinp() throws away any typeahead that has been typed and has not yet been read by your program. Returns FALSE on success, otherwise TRUE.
ncurses_getch
Description
int ncurses_getch ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_getmouse
Description
bool ncurses_getmouse ( array mevent)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_getmouse() reads mouse event out of queue. Function ncurses_getmouse() will return ;FALSE if a mouse event is actually visible in the given window, otherwise it will return TRUE. Event options will be delivered in parameter mevent, which has to be an array, passed by reference (see example below). On success an associative array with following keys will be delivered:
"id" : Id to distinguish multiple devices
"x" : screen relative x-position in character cells
"y" : screen relative y-position in character cells
"z" : currently not supported
"mmask" : Mouse action
See also: ncurses_ungetmouse()
ncurses_halfdelay
Description
int ncurses_halfdelay ( int tenth)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_has_colors
Description
bool ncurses_has_colors ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_has_colors() returns TRUE or FALSE depending on whether the terminal has color capacitites.
See also: ncurses_can_change_color()
ncurses_has_ic
Description
bool ncurses_has_ic ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_has_ic() checks terminals insert- and delete capabilitites. It returns TRUE when terminal has insert/delete-capabilities, otherwise FALSE.
See also: ncurses_has_il()
ncurses_has_il
Description
bool ncurses_has_il ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_has_il() checks terminals insert- and delete-line-capabilities. It returns TRUE when terminal has insert/delete-line capabilities, otherwise FALSE
See also: ncurses_has_ic()
ncurses_has_key
Description
int ncurses_has_key ( int keycode)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_hline
(PHP 4 >= 4.2.0)
ncurses_hline -- Draw a horizontal line at current position using an attributed character and max. n characters longDescription
int ncurses_hline ( int charattr, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_inch
Description
string ncurses_inch ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_inch() returns the character from the current position.
ncurses_init_color
Description
int ncurses_init_color ( int color, int r, int g, int b)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_init_pair
Description
int ncurses_init_pair ( int pair, int fg, int bg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_init
Description
int ncurses_init ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_insch
(PHP 4 >= 4.1.0)
ncurses_insch -- Insert character moving rest of line including character at current positionDescription
int ncurses_insch ( int character)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_insdelln
(PHP 4 >= 4.1.0)
ncurses_insdelln -- Insert lines before current line scrolling down (negative numbers delete and scroll up)Description
int ncurses_insdelln ( int count)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_insertln
Description
bool ncurses_insertln ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_insertln() inserts a new line above the current line. The bottom line will be lost.
ncurses_insstr
Description
int ncurses_insstr ( string text)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_instr
Description
int ncurses_instr ( string buffer)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_instr() returns the number of charaters read from the current character position until end of line. buffer contains the characters. Atrributes are stripped from the characters.
ncurses_isendwin
(PHP 4 >= 4.1.0)
ncurses_isendwin -- Ncurses is in endwin mode, normal screen output may be performedDescription
bool ncurses_isendwin ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_isendwin() returns TRUE, if ncurses_endwin() has been called without any subsequent calls to ncurses_wrefresh(), otherwise FALSE.
See also: ncurses_endwin() ncurses_wrefresh()()
ncurses_keyok
Description
int ncurses_keyok ( int keycode, bool enable)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_killchar
Description
bool ncurses_killchar ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_killchar() returns the current line kill character.
See also: ncurses_erasechar()
ncurses_longname
Description
string ncurses_longname ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_longname() returns a verbose description of the terminal. The descritpion is truncated to 128 characters. On Error ncurses_longname() returns NULL.
See also: ncurses_termname()
ncurses_mouseinterval
Description
int ncurses_mouseinterval ( int milliseconds)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mousemask
Description
int ncurses_mousemask ( int newmask, int oldmask)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Function ncurses_mousemask() will set mouse events to be reported. By default no mouse events will be reported. The function ncurses_mousemask() will return a mask to indicated which of the in parameter newmask specified mouse events can be reported. On complete failure, it returns 0. In parameter oldmask, which is passed by reference ncurses_mousemask() returns the previous value of mouse event mask. Mouse events are represented bei NCURSES_KEY_MOUSE in the ncurses_wgetch() input stream. To read the event data and pop the event of of queue, call ncurses_getmouse().
As a side effect, setting a zero mousemask in newmask turns off the mouse pointer. Setting a non zero value turns mouse pointer on.
mouse mask options can be set with the following predefined constants:
NCURSES_BUTTON1_PRESSED
NCURSES_BUTTON1_RELEASED
NCURSES_BUTTON1_CLICKED
NCURSES_BUTTON1_DOUBLE_CLICKED
NCURSES_BUTTON1_TRIPLE_CLICKED
NCURSES_BUTTON2_PRESSED
NCURSES_BUTTON2_RELEASED
NCURSES_BUTTON2_CLICKED
NCURSES_BUTTON2_DOUBLE_CLICKED
NCURSES_BUTTON2_TRIPLE_CLICKED
NCURSES_BUTTON3_PRESSED
NCURSES_BUTTON3_RELEASED
NCURSES_BUTTON3_CLICKED
NCURSES_BUTTON3_DOUBLE_CLICKED
NCURSES_BUTTON3_TRIPLE_CLICKED
NCURSES_BUTTON4_PRESSED
NCURSES_BUTTON4_RELEASED
NCURSES_BUTTON4_CLICKED
NCURSES_BUTTON4_DOUBLE_CLICKED
NCURSES_BUTTON4_TRIPLE_CLICKED
NCURSES_BUTTON_SHIFT>
NCURSES_BUTTON_CTRL
NCURSES_BUTTON_ALT
NCURSES_ALL_MOUSE_EVENTS
NCURSES_REPORT_MOUSE_POSITION
See also: ncurses_getmouse(), ncurses_ungetmouse() ncurese_getch()
ncurses_move
Description
int ncurses_move ( int y, int x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvaddch
Description
int ncurses_mvaddch ( int y, int x, int c)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvaddchnstr
(PHP 4 >= 4.2.0)
ncurses_mvaddchnstr -- Move position and add attrributed string with specified lengthDescription
int ncurses_mvaddchnstr ( int y, int x, string s, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvaddchstr
Description
int ncurses_mvaddchstr ( int y, int x, string s)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvaddnstr
Description
int ncurses_mvaddnstr ( int y, int x, string s, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvaddstr
Description
int ncurses_mvaddstr ( int y, int x, string s)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvcur
Description
int ncurses_mvcur ( int old_y, int old_x, int new_y, int new_x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvdelch
Description
int ncurses_mvdelch ( int y, int x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvgetch
Description
int ncurses_mvgetch ( int y, int x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvhline
(PHP 4 >= 4.2.0)
ncurses_mvhline -- Set new position and draw a horizontal line using an attributed character and max. n characters longDescription
int ncurses_mvhline ( int y, int x, int attrchar, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvinch
Description
int ncurses_mvinch ( int y, int x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvvline
(unknown)
ncurses_mvvline -- Set new position and draw a vertical line using an attributed character and max. n characters longDescription
int ncurses_mvvline ( int y, int x, int attrchar, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_mvwaddstr
Description
int ncurses_mvwaddstr ( resource window, int y, int x, string text)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_napms
Description
int ncurses_napms ( int milliseconds)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_newwin
Description
int ncurses_newwin ( int rows, int cols, int y, int x)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_nl
Description
bool ncurses_nl ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_nocbreak
Description
bool ncurses_nocbreak ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_nocbreak() routine returns terminal to normal (cooked) mode. Initially the terminal may or may not in cbreak mode as the mode is inherited. Therefore a program should call ncurses_cbreak() and ncurses_nocbreak() explicitly. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_cbreak()
ncurses_noecho
Description
bool ncurses_noecho ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_noecho() prevents echoing of user typed characters. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_echo(), ncurses_getch()
ncurses_nonl
Description
bool ncurses_nonl ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_noqiflush
Description
int ncurses_noqiflush ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_noraw
Description
bool ncurses_noraw ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_noraw() switches the terminal out of raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_raw(), ncurses_cbreak(), ncurses_nocbreak()
ncurses_putp
Description
int ncurses_putp ( string text)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_qiflush
Description
int ncurses_qiflush ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_raw
Description
bool ncurses_raw ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_raw() places the terminal in raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal. Returns TRUE if any error occured, otherwise FALSE.
See also: ncurses_noraw(), ncurses_cbreak(), ncurses_nocbreak()
ncurses_refresh
Description
int ncurses_refresh ( int ch)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_resetty
Description
bool ncurses_resetty ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Function ncurses_resetty() restores the terminal state, which was previously saved by calling ncurses_savetty(). This function always returns FALSE.
See also: ncurses_savetty()
ncurses_savetty
Description
bool ncurses_savetty ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Function ncurses_savetty() saves the current terminal state. The saved terminal state can be restored with function ncurses_resetty(). ncurses_savetty() always returns FALSE.
See also: ncurses_resetty()
ncurses_scr_dump
Description
int ncurses_scr_dump ( string filename)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_scr_init
Description
int ncurses_scr_init ( string filename)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_scr_restore
Description
int ncurses_scr_restore ( string filename)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_scr_set
Description
int ncurses_scr_set ( string filename)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_scrl
Description
int ncurses_scrl ( int count)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_attr
Description
bool ncurses_slk_attr ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_slk_attr() returns the current soft label key attribute. On error returns TRUE, otherwise FALSE.
ncurses_slk_attroff
Description
int ncurses_slk_attroff ( int intarg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_attron
Description
int ncurses_slk_attron ( int intarg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_attrset
Description
int ncurses_slk_attrset ( int intarg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_clear
Description
bool ncurses_slk_clear ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function ncurses_slk_clear() clears soft label keys from screen. Returns TRUE on error, otherwise FALSE.
ncurses_slk_color
Description
int ncurses_slk_color ( int intarg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_init
Description
bool ncurses_slk_init ( int format)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Funtion ncurses_slk_init() must be called before ncurses_initscr() or ncurses_newterm() is called. If ncurses_initscr() eventually uses a line from stdscr to emulate the soft labels, then format determines how the labels are arranged of the screen. Setting format to 0 indicates a 3-2-3 arrangement of the labels, 1 indicates a 4-4 arrangement and 2 indicates the PC like 4-4-4 mode, but in addition an index line will be created.
ncurses_slk_noutrefresh
Description
bool ncurses_slk_noutrefresh ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_slk_refresh
Description
bool ncurses_slk_refresh ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_slk_refresh() copies soft label keys from virtual screen to physical screen. Returns TRUE on error, otherwise FALSE.
ncurses_slk_restore
Description
bool ncurses_slk_restore ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function ncurses_slk_restore() restores the soft label keys after ncurses_slk_clear() has been performed.
ncurses_slk_touch
Description
bool ncurses_slk_touch ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The ncurses_slk_touch() function forces all the soft labels to be output the next time a ncurses_slk_noutrefresh() is performed.
ncurses_standend
Description
int ncurses_standend ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_standout
Description
int ncurses_standout ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_start_color
Description
int ncurses_start_color ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_termattrs
(PHP 4 >= 4.1.0)
ncurses_termattrs -- Returns a logical OR of all attribute flags supported by terminalDescription
bool ncurses_termattrs ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_termname
Description
string ncurses_termname ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_termname() returns terminals shortname. The shortname is truncated to 14 characters. On error ncurses_termname() returns NULL.
See also: ncurses_longname()
ncurses_timeout
Description
void ncurses_timeout ( int millisec)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_typeahead
Description
int ncurses_typeahead ( int fd)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_ungetch
Description
int ncurses_ungetch ( int keycode)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_ungetmouse
Description
bool ncurses_ungetmouse ( array mevent)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
ncurses_getmouse() pushes a KEY_MOUSE event onto the unput queue and associates with this event the given state sata and screen-relative character cell coordinates, specified in mevent. Event options will be specified in associative array mevent:
"id" : Id to distinguish multiple devices
"x" : screen relative x-position in character cells
"y" : screen relative y-position in character cells
"z" : currently not supported
"mmask" : Mouse action
ncurses_ungetmouse() returns FALSE on success, otherwise TRUE.
See also: ncurses_getmouse()
ncurses_use_default_colors
Description
bool ncurses_use_default_colors ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_use_env
Description
void ncurses_use_env ( bool flag)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_use_extended_names
(PHP 4 >= 4.1.0)
ncurses_use_extended_names -- Control use of extended names in terminfo descriptionsDescription
int ncurses_use_extended_names ( bool flag)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_vidattr
Description
int ncurses_vidattr ( int intarg)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_vline
(PHP 4 >= 4.2.0)
ncurses_vline -- Draw a vertical line at current position using an attributed character and max. n characters longDescription
int ncurses_vline ( int charattr, int n)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
ncurses_wrefresh
Description
int ncurses_wrefresh ( resource window)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
undocumented
LXVIII. Lotus Notes functions
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
- Table des matières
- notes_body -- Open the message msg_number in the specified mailbox on the specified server (leave serv
- notes_copy_db -- Create a note using form form_name
- notes_create_db -- Create a Lotus Notes database
- notes_create_note -- Create a note using form form_name
- notes_drop_db -- Drop a Lotus Notes database
- notes_find_note -- Returns a note id found in database_name. Specify the name of the note. Leaving type bla
- notes_header_info -- Open the message msg_number in the specified mailbox on the specified server (leave serv
- notes_list_msgs -- Returns the notes from a selected database_name
- notes_mark_read -- Mark a note_id as read for the User user_name
- notes_mark_unread -- Mark a note_id as unread for the User user_name
- notes_nav_create -- Create a navigator name, in database_name
- notes_search -- Find notes that match keywords in database_name
- notes_unread -- Returns the unread note id's for the current User user_name
- notes_version -- Get the version Lotus Notes
notes_body
(PHP 4 >= 4.0.5)
notes_body -- Open the message msg_number in the specified mailbox on the specified server (leave servDescription
array notes_body ( string server, string mailbox, int msg_number)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_copy_db
Description
string notes_copy_db ( string from_database_name, string to_database_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_create_db
Description
bool notes_create_db ( string database_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_create_note
Description
string notes_create_note ( string database_name, string form_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_drop_db
Description
bool notes_drop_db ( string database_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_find_note
(PHP 4 >= 4.0.5)
notes_find_note -- Returns a note id found in database_name. Specify the name of the note. Leaving type blaDescription
bool notes_find_note ( string database_name, string name [, string type])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_header_info
(PHP 4 >= 4.0.5)
notes_header_info -- Open the message msg_number in the specified mailbox on the specified server (leave servDescription
object notes_header_info ( string server, string mailbox, int msg_number)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_list_msgs
Description
bool notes_list_msgs ( string db)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_mark_read
Description
string notes_mark_read ( string database_name, string user_name, string note_id)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_mark_unread
Description
string notes_mark_unread ( string database_name, string user_name, string note_id)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_nav_create
Description
bool notes_nav_create ( string database_name, string name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_search
Description
string notes_search ( string database_name, string keywords)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_unread
Description
string notes_unread ( string database_name, string user_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
notes_version
Description
string notes_version ( string database_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
LXIX. ODBC unifié
En plus du support de l'ODBC normal, l'ODBC unifié de PHP vous donne accès à diverses bases de données qui ont emprunté la sémantique des API ODBC pour implémenter leur propres 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.
Reportez-vous à Installation sous Unix pour plus de détails sur les configurations de ces serveurs.
Note : Il n'y a pas d'ODBC utilisé lors des connexions aux bases de données ci-dessus. Les fonctions que vous utiliserez portent des noms évocateurs, et utilisent les mêmes syntaxes que leurs cousines d'ODBC. L'exception à ceci est iODBC. En compilant PHP avec le support iODBC, vous pourrez utiliser n'importe quel pilote compatible ODBC avec vos applications PHP. iODBC est mis à jour à OpenLink Software. Plus d'informations sur iODBC, ainsi qu'un HOWTO (en anglais), est disponible à www.iodbc.org.
- Table des matières
- odbc_autocommit -- Active le mode auto-validation
- odbc_binmode -- Modifie la gestion des colonnes de données binaires.
- odbc_close_all -- Ferme toutes les connexions ODBC
- odbc_close -- Ferme une connexion 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_cursor -- Lecture du pointeur de fiche courante (cursorname).
- odbc_do -- Synonyme de odbc_exec()
- odbc_error -- Lit le dernier code d'erreur
- odbc_errormsg -- Lit le dernier message d'erreur
- odbc_exec -- Prépare et exécute une requête SQL.
- odbc_execute -- Exécute une requête SQL préparée.
- odbc_fetch_array -- Fetch a result row as an associative array
- odbc_fetch_into -- Lit une ligne de résultat, et la place dans un tableau.
- odbc_fetch_object -- Fetch a result row as an object
- odbc_fetch_row -- Lit une ligne de résultat.
- odbc_field_len -- Lit la longueur d'un champs.
- 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 champs
- odbc_field_type -- Type de données d'un champs.
- odbc_foreignkeys -- Liste les clés étrangères
- odbc_free_result -- Libère les ressources associées à 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 -- Checks if multiple results are avaiable
- odbc_num_fields -- Nombre de colonnes dans un résultat
- odbc_num_rows -- Nombre de ligne 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édure stockées
- odbc_result_all -- Affiche le résultat sous la forme d'une table HTML.
- odbc_result -- Lit les données de résultat.
- odbc_rollback -- Annule une transaction
- odbc_setoption -- Modifie les paramètres ODBC.
- odbc_specialcolumns -- Retourne l'ensemble optimal de colonnes, qui permettent de définir uniquement une ligne dans une table
- odbc_statistics -- Calcule des statistiques sur une table
- odbc_tableprivileges -- Liste les tables et leurs privilèges
- odbc_tables -- Liste les tables d'une source.
odbc_autocommit
Description
int odbc_autocommit ( resource connection_id [, int OnOff])Sans le paramètre OnOff, odbc_autocommit() retourne le statut d'auto-validation de la connexion connection_id. TRUE si le mode est activé, FALSE s'il ne l'est pas, ou si une erreur survient.
Si OnOff vaut TRUE, l'auto-validation est activée. S'il est FALSE, l'auto-validation est désactivée. odbc_autocommit() retourne TRUE en cas de succès, FALSE en cas d'échec.
Par défaut, l'auto-validation est activée. Désactiver l'auto-validation est équivalent à démarrer une transaction.
Voir aussi odbc_commit() et odbc_rollback().
odbc_binmode
Description
int odbc_binmode ( resource result_id, int mode)Types ODBC SQL affectés: BINARY, VARBINARY, LONGVARBINARY.
ODBC_BINMODE_PASSTHRU: Mode Passthru
ODBC_BINMODE_RETURN: Retourne tel quel.
ODBC_BINMODE_CONVERT: Convertit en char et retourne la valeur.
Lorsqu'une donnée SQL est convertie en caractère C, 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".
Tableau 1. 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_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 result_id vaut 0, ces paramètres seront appliqués aux nouveaux résultats.
Note : La valeur par défaut de 4096 est 4096 et les valeurs par défaut de odbc_binmode est ODBC_BINMODE_RETURN. La gestion des colonnes binaires est aussi modifiée par odbc_longreadlen().
odbc_close_all
Description
void odbc_close_all ( void)odbc_close_all() ferme toutes les connexions ODBC à des sources de données.
Note : odbc_close_all() échouera s'il y a des transactions en cours sur cette connexion. Dans ce cas, la connexion restera ouverte.
odbc_close
Description
void odbc_close ( resource connection_id)odbc_close() ferme la connexion avec la source de données représentée par l'identifiant de connexion connection_id.
Note : odbc_close() échouera s'il y a des transactions en cours sur cette connexion. Dans ce cas, la connexion restera ouverte.
odbc_columnprivileges
Description
int odbc_columnprivileges ( resource connection_id [, string qualifier [, string owner [, string table_name [, string column_name]]]])odbc_columnprivileges() liste les colonnes et leurs droits associés pour la table table_name. odbc_columnprivileges() retourne un identifiant de résultat ODBC, ou bien FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
GRANTOR
GRANTEE
PRIVILEGE
IS_GRANTABLE
Le résultat est ordonné par TABLE_QUALIFIER, TABLE_OWNER et TABLE_NAME.
Le paramètre column_name accepte des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
odbc_columns
Description
int odbc_columns ( resource connection_id [, string qualifier [, string owner [, string table_name [, string column_name]]]])odbc_columns() liste toutes les colonnes de la source dedonnées. odbc_columns() retourne un identifiant de résultat ODBC, ou bien FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
COLUMN_NAME
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
RADIX
NULLABLE
REMARKS
Le résultat est ordonné par TABLE_QUALIFIER, TABLE_OWNER et TABLE_NAME.
Les paramètres owner, column_name et table_name acceptent des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
Voir aussi odbc_columnprivileges() pour connaître les droits associés.
odbc_commit
Description
int odbc_commit ( resource connection_id)odbc_commit() retourne TRUE en cas de succès, FALSE en cas d'erreur. Toutes les connexions en cours sur connection_id sont validées.
odbc_connect
Description
resource odbc_connect ( string dsn, string user, string password [, int cursor_type])odbc_connect() retourne un identifiant de connexion ODBC ou 0 (FALSE) en cas d'erreur.
L'identifiant de connexion retournée par cette fonction est nécessaire pour toutes les autres fonctions ODBC. Vous pouvez avoir de multiples connexions en même temps. Le quatrième paramètre 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.
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 permet d'éviter cette erreur. De plus, certains pilotes ne supportent 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.
Les constantes suivantes sont définies comme type de pointeur :
SQL_CUR_USE_IF_NEEDED
SQL_CUR_USE_ODBC
SQL_CUR_USE_DRIVER
SQL_CUR_DEFAULT
Pour les connexions persistantes, reportez-vous à odbc_pconnect().
odbc_cursor
Description
string odbc_cursor ( resource result_id)odbc_cursor() lit le pointeur de fiche courante (cursorname) pour le résultat result_id.
odbc_do
Description
string odbc_do ( resource connection_id, string query)odbc_do() exécute la requête query avec la connexion connection_id.
odbc_error
Description
string odbc_error ( [resource connection_id])odbc_error() retourne un état ODVBC sur 6 chiffres, ou une chaîne vide s'il n'y avait plus d'erreurs. Si connection_id 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é.
Voir aussi odbc_errormsg() et odbc_exec().
odbc_errormsg
Description
string odbc_errormsg ( [int connection_id])odbc_errormsg() retourne une chaîne contenant le dernier message d'erreur ODBC, ou une chaîne vide s'il n'y avait pas d'erreur. Si connection_id 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é.
Voir aussi odbc_error() et odbc_exec().
odbc_exec
Description
int odbc_exec ( resource connection_id, string query_string)odbc_exec() retourne FALSE en cas d'erreur, ou bien retourne un identifiant de résultat ODBC en cas d'exécution réussie.
odbc_exec() envoie une commande SQL à la source de données représentée par connection_id. Ce paramètre doit être un identifiant valide de connexion, retourné par odbc_connect() ou odbc_pconnect().
Voir aussi : odbc_prepare() et odbc_execute() pour les éxecutions multiples de requêtes SQL.
odbc_execute
Description
int odbc_execute ( resource result_id [, array parameters_array])odbc_execute() exécute une requête SQL préparée par odbc_prepare(). odbc_execute() retourne TRUE en cas d'exécution réussie, et FALSE sinon. Le tableau de paramètres parameters_array ne sert que si vous avez besoin de paramètrer votre requête.
odbc_fetch_array
Description
array odbc_fetch_array ( resource result [, int rownumber])
| Avertissement |
This function is currently not documented, only the argument list is available. |
odbc_fetch_into
Description
int odbc_fetch_into ( resource result_id [, int rownumber, array result_array])odbc_fetch_into() retourne le nombre de colonnes dans le résultat, ou FALSE en cas d'erreur. result_array doit avoir été passé par référence, mais il 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.
<?php $rc = odbc_fetch_into($res_id, $row, $my_array); $rc = odbc_fetch_into($res_id, 1, $my_array); ?> |
Jusqu'en PHP 4.0.5, le paramètre result_array n'a plus besoin d'être passé par référence.
Depuis PHP 4.0.6, le paramètre rownumber ne peut pas être passé comme une constante, mais comme une variable.
Evolution ultérieure : en PHP 4.1, odbc_fetch_into()
aura le format suivant :
int odbc_fetch_into ( int result_id, array result_array [, int rownumber])
Notez que le paramètre rownumber sera optionnel, tandis que
result_array ne l'est pas.
odbc_fetch_object
Description
object odbc_fetch_object ( resource result [, int rownumber])
| Avertissement |
This function is currently not documented, only the argument list is available. |
odbc_fetch_row
Description
int odbc_fetch_row ( resource result_id [, int row_number])Si odbc_fetch_row() a réussi, TRUE est retourné. S'il n'y avait plus de ligne, ou en cas d'erreur, FALSE est retourné.
odbc_fetch_row() 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().
Si row_number est omis, row_number 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_number peuvent être combinés librement.
Pour passer en revue toutes les lignes d'un résultat plusieurs fois, vous pouvez appeler odbc_fetch_row() avec row_number = 1, puis continue à appeler odbc_fetch_row() sans le paramètre row_number 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é.
odbc_field_len
Description
int odbc_field_len ( resource result_id, int field_number)odbc_field_len() retourne la longueur du champs référence par le nombre field_number, dans la connexion ODBC result_id. Les numéros de champs commencent à 1.
odbc_field_name
Description
string odbc_field_name ( resource result_id, int field_number)odbc_field_name() lit le nom de la colonne dont l'index est field_number. La numérotation des champs commence à 1. FALSE est retourné en cas d'erreur.
odbc_field_num
Description
int odbc_field_num ( resource result_id, string field_name)odbc_field_num() retourne le numéro de la colonne nommée field_name. Ce numéro correspond à l'index du champs dans le résultat ODBC. La numérotation commence à 1. FALSE est retourné en cas d'erreur.
odbc_field_precision
Description
string odbc_field_precision ( resource result_id, int field_number)odbc_field_precision() retourne la précision du champs référéncé par son numéro field_number, dans le résultat ODBC result_id.
Voir aussi : odbc_field_scale() pour connaître l'échelle d'un nombre à virgule flottante.
odbc_field_scale
Description
string odbc_field_scale ( resource result_id, int field_number)odbc_field_precision() retourne l'échelle du champs référéncé par son numéro de champs field_number dans le résultat ODBC result_id.
odbc_field_type
Description
string odbc_field_type ( resource result_id, int field_number)odbc_field_type() retourne le type de données SQL d'un champs, identifié par son index. La numérotation des champs commence à 1.
odbc_foreignkeys
Description
int odbc_foreignkeys ( resource connection_id, string pk_qualifier, string pk_owner, string pk_table, string fk_qualifier, string fk_owner, string fk_table)odbc_foreignkeys() liste les clés étrangèes utilisées dans la table pk_table. odbc_foreignkeys() retourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
PKTABLE_QUALIFIER
PKTABLE_OWNER
PKTABLE_NAME
PKCOLUMN_NAME
FKTABLE_QUALIFIER
FKTABLE_OWNER
FKTABLE_NAME
FKCOLUMN_NAME
KEY_SEQ
UPDATE_RULE
DELETE_RULE
FK_NAME
PK_NAME
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.
odbc_free_result
Description
int odbc_free_result ( resource result_id)odbc_free_result() retourne toujours TRUE.
odbc_free_result() n'est nécessaire que si vous craignez d'utiliser trop de mémoire lors de l'exécution de votre script. Tous les résultats en mémoire seront libérés dès la fin du script. Mais, si vous êtes sÛr que vous n'aurez plus besoin d'un résultat jusqu'à la fin de votre script, vous pouvez appeler odbc_free_result(), et la mémoire associée à result_id sera libérée.
Note : Si auto-validation est désactivée (voir odbc_autocommit()) et que vous appelez odbc_free_result() avant de valider vos requêtes, toutes les transactions préparées seront annulées.
odbc_gettypeinfo
Description
int odbc_gettypeinfo ( resource connection_id [, int data_type])odbc_gettypeinfo() liste les types de données qui sont supportées par une source. odbc_gettypeinfo() retourne un identifiant de résultat, ou FALSE en cas d'erreur. L'argument optionnel data_type peut être utilisé pour restreindre les informations à un seul type de données.
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.
odbc_longreadlen
Description
int odbc_longreadlen ( resource result_id, int length)Types ODBC SQL affectés: LONG, LONGVARBINARY.
Le nombre d'octets retournés à PHP est contrôlé par le paramètre length. Si sa valeur est 0, les colonnes de type Long seront transformées en chaîne vide.
Note : La gestion des types LONGVARBINARY est aussi affectée par odbc_binmode().
odbc_next_result
Description
bool odbc_next_result ( resource result_id)
| Avertissement |
This function is currently not documented, only the argument list is available. |
odbc_num_fields
Description
int odbc_num_fields ( resource result_id)odbc_num_fields() retourne le nombre de colonnes dans un résultat ODBC. odbc_num_fields() retournera -1 en cas d'erreur. L'argument est un identifiant de résultat valide, retourné par odbc_exec().
odbc_num_rows
Description
int odbc_num_rows ( odbc_prepare result_id)odbc_num_rows() retourne le nombre de lignes dans un résultat ODBC. odbc_num_rows() retournera -1 en cas d'erreur. Pour les commandes INSERT, UPDATE et DELETE, odbc_num_rows() retourne le nombre de ligne affectées. Pour les commandes SELECT, ce PEUT le nombre de lignes disponibles, mais ce n'est pas certain.
Note: odbc_num_rows() après un SELECT retournera -1 avec de nombreux pilotes.
odbc_pconnect
Description
resource odbc_pconnect ( string dsn, string user, string password [, int cursor_type])odbc_pconnect() retourne un identifiant de connexion ODBC ou 0 (FALSE) en cas d'erreur. odbc_pconnect() se comporte de manière similaire à odbc_connect(), mais la connexion ouverte n'est pas vraiment terminée lorsque le script est terminé. 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.
Note : Les connexions persistantes n'ont aucun effet si PHP est utilisé comme CGI.
Pour plus de détails sur le paramètre optionnel cursor_type, voyez odbc_connect(). Pour plus de détails sur les connexions persistantes, reportez-vous à la FAQ PHP.
odbc_prepare
Description
resource odbc_prepare ( resource connection_id, string query_string)odbc_prepare() prépare une commande pour l'exécution.
odbc_prepare() retourne un identifiant de résultat ODBC si la commande SQL a été préparée avec succès. L'identifiant peut être utilisé plus tard pour exécuter la commande avec odbc_execute().
odbc_primarykeys
Description
int odbc_primarykeys ( resource connection_id, string qualifier, string owner, string table)odbc_primarykeys() liste les colonnes utilisées dans une clé primaire de la table table. odbc_primarykeys() retourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
COLUMN_NAME
KEY_SEQ
PK_NAME
odbc_procedurecolumns
Description
int odbc_procedurecolumns ( resource connection_id [, string qualifier [, string owner [, string proc [, string column]]]])odbc_procedurecolumns() list 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. odbc_procedurecolumns() etourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
PROCEDURE_QUALIFIER
PROCEDURE_OWNER
PROCEDURE_NAME
COLUMN_NAME
COLUMN_TYPE
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
RADIX
NULLABLE
REMARKS
Le résultat est ordonné par PROCEDURE_QUALIFIER, PROCEDURE_OWNER, PROCEDURE_NAME et COLUMN_TYPE.
Les paramètres owner, proc et column acceptent des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
odbc_procedures
Description
int odbc_procedures ( resource connection_id [, string qualifier [, string owner [, string name]]])odbc_procedures() liste toutes les procédures stockées dans la source de données. odbc_procedures() retourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
PROCEDURE_QUALIFIER
PROCEDURE_OWNER
PROCEDURE_NAME
NUM_INPUT_PARAMS
NUM_OUTPUT_PARAMS
NUM_RESULT_SETS
REMARKS
PROCEDURE_TYPE
Les paramètres owner et name acceptent des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
odbc_result_all
Description
int odbc_result_all ( odbc_prepare result_id [, string format])odbc_result_all() retourne le nombre de lignes dans le résultat, ou FALSE en cas d'erreur.
odbc_result_all() affiche toutes les lignes d'un résultat. L'affichage se fait au format HTML. Avec l'option format, il est possible de modifier l'aspect global de la table.
odbc_result
Description
string odbc_result ( odbc_prepare result_id, mixed field)odbc_result() retourne le contenu d'un champs.
field peut être aussi bien un entier, contenant le numéro de colonne du champs, dans le résultat, ou bien une chaîne de caractère, qui représente le nom du champs. Par exemple:
Le premier appel à odbc_result() retourne la valeur du troisième champs de la ligne courante, du résultat result_id. Le deuxième appel à odbc_result() retourne la valeur du troisième champs 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 champs passé ne correspond à aucun champs dans le résultat.
Les index de champs commencent à 1. Pour plus d'informations sur la façon de lire des colonnes de type binaire ou long, reportez-vous à odbc_binmode() et odbc_longreadlen().
odbc_rollback
Description
int odbc_rollback ( odbc_prepare connection_id)odbc_rollback() annule toutes les transactions sur la connexion connection_id. odbc_rollback() retourne TRUE en cas de succès, et FALSE en cas d'échec.
odbc_setoption
Description
int odbc_setoption ( resource id, int function, int option, int param)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ème liés aux pilotes ODBC récalcitrants. Vous aurez sÛrement à utiliser odbc_setoption() si vous êtes un programmeur ODBC et que vous comprenez les divers effets des options disponibles. Vous aurez 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.
Etant 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() vous permet d'utiliser PHP sans que votre patron vous pousse à utiliser un produit commercial, alors cela n'a pas d'importance.
Id est un identifiant de connexion, ou un identifiant de résultat, pour lequel vous souhaitez modifier des options. Pour SQLSetConnectOption(), c'est un identifiant de connexion. Pour SQLSetStmtOption(), c'est un identifiant de résultat.
function est la fonction ODBC à utiliser. La valeur doit être de 1 pour utiliser SQLSetConnectOption() et 2 pour SQLSetStmtOption().
Le paramètre option est l'option à modifier.
Le paramètre param est la valeur de l'option option.
Exemple 1. Exemple de modification d'option ODBC
|
odbc_specialcolumns
(PHP 4 )
odbc_specialcolumns -- Retourne l'ensemble optimal de colonnes, qui permettent de définir uniquement une ligne dans une tableDescription
int odbc_specialcolumns ( resource connection_id, int type, string qualifier, string owner, string table, int scope, int nullable)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 type est SQL_ROWVER, odbc_specialcolumns() retourne l'ensemble optimal de colonne tel qu'en lisant les valeurs de ces colonnes, on puisse spécifier n'importe quelle ligne de manière unique.
odbc_specialcolumns() retourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
SCOPE
COLUMN_NAME
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
PSEUDO_COLUMN
Le résultat est ordonné par SCOPE.
odbc_statistics
Description
int odbc_statistics ( resource connection_id, string qualifier, string owner, string table_name, int unique, int accuracy)odbc_statistics() effectue quelques statistiques sur une tables et ses index. odbc_statistics() retourne un identifiant de résultat, ou FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
NON_UNIQUE
INDEX_QUALIFIER
INDEX_NAME
TYPE
SEQ_IN_INDEX
COLUMN_NAME
COLLATION
CARDINALITY
PAGES
FILTER_CONDITION
Le résultat est ordonné par NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME et SEQ_IN_INDEX.
odbc_tableprivileges
Description
int odbc_tableprivileges ( resource connection_id [, string qualifier [, string owner [, string name]]])odbc_tableprivileges() liste les tables de la source et leurs droits associés. odbc_tableprivileges() retourne un identifiant de résultat ODBC, ou bien FALSE en cas d'erreur.
Le résultat possède les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
GRANTOR
GRANTEE
PRIVILEGE
IS_GRANTABLE
Le résultat est ordonné par TABLE_QUALIFIER, TABLE_OWNER et TABLE_NAME.
Les paramètres owner et name acceptent des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
odbc_tables
Description
int odbc_tables ( odbc_setoption connection_id [, string qualifier [, string owner [, string name [, string types]]]])odbc_tables() liste toutes les tables de la source et retourne un identifiant de résultat ODBC, ou bien FALSE en cas d'erreur.
Le résultat contient les colonnes suivantes :
TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
TABLE_TYPE
REMARKS
Le résultat est ordonné grâce aux options TABLE_TYPE, TABLE_QUALIFIER, TABLE_OWNER et TABLE_NAME.
Les paramètres owner et name acceptent des masques de recherche ('%' pour remplacer zéro ou plus caractères, et '_' pour n'en remplacer qu'un seul).
Pour supporter les énumérations de qualificateurs propriétaires et types de table, la sémantique suivante pour les paramètres qualifier, owner, name et table_type sont disponibles :
Si qualifier est un signe de pourcentage (%), et owner et name sont des chaînes vides, alors le résultat contient la liste des qualifiers valides pour la source. (toutes les colonnes hormis TABLE_QUALIFIER contiennent NULL).
Si owner est un signe de pourcentage (%), et qualifier et name 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 qualifier, owner et name 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).
Si table_type n'est pas une chaîne vide, il doit contenir une liste de valeurs, séparées par des virgules, qui representent 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.
Voir aussi odbc_tableprivileges() pour connaître les droits associés.
LXX. Oracle 8
Ces fonctions vous permettront d'accéder aux serveurs Oracle8 et Oracle7. Elles utilisent l'interface Oracle8 Call-Interface (oci8). Vous aurez donc besoin des librairies clientes Oracle8 pour pouvoir les utiliser.
Il faut noter que cette extension est plus souple que l'extension Oracle officielle. Elle supporte notamment les liaisons entre les variables globales et locales de PHP avec des emplacements Oracle; elle supporte complètement les types LOB, FILE et ROWID et vous permet d'utiliser des variables de définitions personnalisables.
Avant d'utiliser cette extension, assurez-vous que vous avez bien paramétré vos variables d'environnement Oracle, ainsi que votre démon utilisateur. Les variables dont vous pouvez avoir besoin sont :
ORACLE_HOME
ORACLE_SID
LD_PRELOAD
LD_LIBRARY_PATH
NLS_LANG
ORA_NLS33
Après avoir configuré ces variables pour votre utilisateur "serveur web", assurez-vous aussi d'ajouter cet utilisateur (nobody, www) au group Oracle.
Si votre serveur web ne démarre pas, ou crashe au démarrage : Vérifiez que Apache a bien été compilé avec la librairie 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 libpthread n'est pas listée, vous devez réinstaller Apache :
Exemple 1. Aide oci
|
Vous pouvez facilement accéder aux procédures stockées, de la même façon que vous le feriez par ligne de commande :
Exemple 2. Utilisation de procédures stockées
|
- Table des matières
- ociBindByName -- Utilise une variable PHP pour la phase de définition, dans un SELECT.
- OCICancel -- Bientôt documenté....
- OCICollAppend -- Coming soon
- OCICollAssign -- Bientôt documenté....
- OCICollAssignElem -- Bientôt documenté....
- OCICollGetElem -- Bientôt documenté....
- OCICollMax -- Bientôt documenté....
- OCICollSize -- Bientôt documenté....
- OCICollTrim -- Bientôt documenté....
- ociColumnIsNULL -- Teste si la valeur d'une colonne est NULL.
- ociColumnName -- Retourne le nom d'une colonne.
- OCIColumnPrecision -- Bientôt documenté....
- OCIColumnScale -- Bientôt documenté....
- ociColumnSize -- Retourne la taille de la colonne.
- ociColumnType -- Retourne le type de données d'une colonne.
- OCIColumnTypeRaw -- Bientôt documenté....
- ociCommit -- Valide les transactions en cours.
- ociDefineByName -- Utilise une variable PHP pour la phase de définition, dans une commande SELECT.
- ociError -- Retourne la dernière erreur de stmt|conn|global.
- ociexecute -- Exécute une commande.
- ociFetch -- Modifie la prochaine ligne dans le résultat.
- ociFetchInto -- Retourne la ligne suivante dans un tableau.
- ociFetchStatement -- Retourne toutes les lignes d'un résultat.
- OCIFreeCollection -- Bientôt documenté....
- ociFreeCursor -- Libère toutes les ressources occupées par un pointeur.
- ociFreeDesc -- Supprime un descripteur de LOB
- ociFreeStatement -- Libère toutes les ressources occupées par une commande.
- ociinternaldebug -- Active ou désactive l'affichage des données de debuggage.
- OCILoadLob -- Bientôt documenté....
- ociLogOff -- Déconnexion d'un serveur Oracle.
- ociLogon -- Etablit une connexion à un serveur Oracle.
- OCINewCollection -- Bientôt documenté....
- ociNewCursor -- Retourne un nouveau pointeur à utiliser pour lier les pointeurs de références
- ociNewDescriptor -- Initialise un nouveau pointeur vide de LOB/FILE
- ociNLogon -- Se connecte à un serveur Oracle avec une nouvelle connexion.
- ociNumCols -- Retourne le nombre de colonnes dans un résultat
- ociparse -- Analyse une requête.
- ociPLogon -- Connection persistante à un serveur Oracle.
- ociResult -- Retourne la valeur d'une colonne
- ociRollback -- Annule les transactions en cours.
- ociRowCount -- Retourne le nombre de lignes affectées.
- OCISaveLob -- Bientôt documenté....
- OCISaveLobFile -- Bientôt documenté....
- ociServerVersion -- Retourne une chaîne contenant les informations de version du serveur.
- ocisetprefetch -- Indique le nombre de lignes qui doivent être pré-lues
- ociStatementType -- Retourne le type de commande OCI.
- OCIWriteLobToFile -- Bientôt documenté....
ociBindByName
(PHP 3>= 3.0.4, PHP 4 )
ociBindByName -- Utilise une variable PHP pour la phase de définition, dans un SELECT.Description
int ocibindbyname ( resource stmt, string ph_name, mixed & variable, int length [, int type])ocibindbyname() relie la variable PHP variable à l'emplacement Oracle ph_name. Son utilisation (comme entrée ou comme sortie) sera définie à l'exécution, et l'espace nécessaire sera alloué. Le paramètre de longueur length fixe la taille maximum pour la liaison. Si vous affectez une longueur de -1, ocibindbyname() utilisera la longueur de variable comme maximum.
Si vous devez lier des types abstraits de données (LOB/ROWID/BFILE), vous devrez l'allouer dans un premier temps, avec ocinewdescriptor(). La longueur length ne sert pas pour ces types et devrait être fixée à -1. La variable type indique au serveur Oracle, quel type de pointeur va être utilisé. Les valeurs possibles sont : oci_B_FILE (Fichier binaires), oci_B_CFILE (Fichier texte), oci_B_CLOB (LOB- texte), oci_B_BLOB (LOB binaire) et oci_B_ROWID (ROWID).
Exemple 1. ociDefineByName
|
OCICancel
Description
int ocicancel ( resource stmt)ocicancel() détruit les ressources liées au dernier résultat stmt. Si vous ne souhaitez plus lire d'informations dans ce résultat, utilisez cette fonction.
OCICollAppend
Description
string OCICollAppend ( object collection, object object)
| Avertissement |
This function is currently not documented, only the argument list is available. |
OCICollAssign
OCICollAssignElem
Description
string ocicollassignelem ( object collection, string ndx, string val)Bientôt documenté....
OCICollGetElem
OCICollMax
OCICollSize
OCICollTrim
ociColumnIsNULL
Description
int ocicolumnisnull ( resource stmt, mixed column)ocicolumnisnull() retourne TRUE si la colonne col du résultat stmt est NULL. Vous pouvez utiliser le numéro de colonne (l'indexation des colonnes commence à 1) ou le nom de la colonne, pour le paramètre col.
ociColumnName
Description
string ocicolumnname ( resource stmt, int col)ocicolumnname() retourne le nom de la colonne numéro col (en commençant à 1).
Exemple 1. ociColumnName
|
Voir aussi ocinumcols(), ocicolumntype() et ocicolumnsize().
OCIColumnPrecision
OCIColumnScale
ociColumnSize
Description
int ocicolumnsize ( resource stmt, mixed column)ocicolumnsize() retourne la taille de la colonne. Vous pouvez utiliser l'index de colonne (l'indexation commence à 1) ou le nom de la colonne dans le paramètre col.
Exemple 1. ociColumnSize
|
Voir aussi ocinumcols(), ocicolumnname() et ocicolumnsize().
ociColumnType
Description
mixed ocicolumntype ( resource stmt, int col)ocicolumntype() retourne le type de données de la colonne correspondant au numéro de colonne col dans le résultat stmt (les colonnes sont indexées à partir de 1).
Exemple 1. Exemple avec ocicolumntype()
|
Voir aussi ocinumcols(), ocicolumnname() et ocicolumnsize().
OCIColumnTypeRaw
ociCommit
Description
int ocicommit ( resource connection)ocicommit() valide toutes les transactions en cours sur la connexion Oracle connection.
ociDefineByName
(PHP 3>= 3.0.7, PHP 4 )
ociDefineByName -- Utilise une variable PHP pour la phase de définition, dans une commande SELECT.Description
int ocidefinebyname ( resource stmt, string Column-Name, mixed variable [, int type])ocidefinebyname() copie les valeurs issues de colonnes SQL Column-Name dans les variables PHP. Méfiez-vous des colonnes Oracle qui sont toutes en majuscule, tandis que dans les SELECT, vous pouvez aussi les écrire en minuscules. ocidefinebyname() s'attends à ce que Column-Name soit en majuscules. Si vous définissez une variable qui n'existe pas dans la commande SELECT, vous ne serez pas prévenu par une erreur.
Si vous avez besoin de définir un type de données abstrait, tel que (LOB/ROWID/BFILE), vous devez lui allouer la mémoire avec ocinewdescriptor(). Reportez-vous aussi à ocibindbyname().
Exemple 1. ociDefineByName
|
ociError
Description
array ocierror ( [int stmt|conn])ocierror() retourne la dernière erreur trouvée. Si l'option stmt|conn n'est pas fournie, la dernière erreur rencontrée est retournée. Si aucune erreur n'est trouvée, ocierror() retourne FALSE.
ociexecute
Description
int ociexecute ( resource statement [, int mode])ociexecute() éxécute une commande déjà préparée (voir ociparse()). L'option mode vous permet de spécifier le mode d'exécution (par défaut, il est à oci_COMMIT_ON_SUCCESS). Si vous ne voulez pas que la commande soit automatiquement validée, utilisez le mode oci_DEFAULT.
ociFetch
Description
int ocifetch ( resource statement)ocifetch() place la prochaine ligne (d'une commande SELECT) dans le pointeur interne de résultat.
ociFetchInto
Description
int ocifetchinto ( resource stmt, array & result [, int mode])ocifetchinto() retourne la ligne suivante (pour une commande SELECT) dans le tableau result. ocifetchinto() écrasera le contenu de result. Par défaut, result sera un tableau à index numérique, commençant à 1, et qui contiendra toute les colonnes qui ne sont pas NULL.
L'option mode vous permet de modifier le comportement par défaut de la fonction. Vous pouvez passer plusieurs modes simplement en les additionnant (i.e. OCI_ASSOC+OCI_RETURN_NULLS). Les modes valides sont :
| OCI_ASSOC Retourne un tableau associatif. |
| OCI_NUM Retourne un tableau à index numérique (DEFAULT, valeur par défaut) |
| OCI_RETURN_NULLS Retourne les colonnes vides. |
| OCI_RETURN_LOBS Retourne la valeur des objets LOB plutôt que leur descripteur. |
ociFetchStatement
Description
int ocifetchstatement ( resource stmt, array & variable)ocifetchstatement() retourne toutes les lignes d'un résultat dans le tableau variable. ocifetchstatement() retourne le nombre de lignes retournées.
Exemple 1. ociFetchStatement
|
OCIFreeCollection
ociFreeCursor
Description
boolean ocifreecursor ( resource stmt)ocifreecursor() retourne TRUE en cas de succès, et FALSE en cas d'échec.
ociFreeDesc
Description
int ocifreedesc ( object lob)ocifreedesc() retourne TRUE en cas de succès, et FALSE en cas d'échec.
ociFreeStatement
Description
int ocifreestatement ( resource stmt)ocifreestatement() retourne TRUE en cas de succès, et FALSE en cas d'échec.
ociinternaldebug
(PHP 3>= 3.0.4, PHP 4 )
ociinternaldebug -- Active ou désactive l'affichage des données de debuggage.Description
void ociinternaldebug ( int onoff)ociinternaldebug() active ou désactive l'affichage des informations de debuggage. Pour les afficher, mettez onoff à 1, ou sinon mettez onoff à 0 pour les cacher.
OCILoadLob
ociLogOff
ociLogon
Description
resource ocilogon ( string username, string password [, string db])ocilogon() retourne un identifiant de connexion, nécessaire à la plupart des fonctions oci. Si l'option ORACLE_SID n'est pas précisée, PHP utilisera la variable d'environnement ORACLE_SID pour déterminer le serveur de connexion.
Les connexions sont partagées, à l'intérieur d'une même page avec ocilogon(). Cela signifie que COMMIT et ROLLBACK s'appliquent à toutes les transactions commencées à l'intérieur d'une même page, même si vous avez créé de multiples connexions.
Cet exemple montre comment les connexions sont partagées :
Exemple 1. ociLogon
|
Voir aussi ociplogon() et ocinlogon().
OCINewCollection
ociNewCursor
(PHP 3>= 3.0.8, PHP 4 )
ociNewCursor -- Retourne un nouveau pointeur à utiliser pour lier les pointeurs de référencesDescription
int ocinewcursor ( resource conn)ocinewcursor() alloue un nouveau pointeur de commande, pour la connexion conn.
Exemple 1. Utiliser un REF CURSOR issue d'une procédure enregistrée.
|
Exemple 2. Utiliser un REF CURSOR issue d'une commande SELECT
|
ociNewDescriptor
Description
resource ocinewdescriptor ( resource connection [, int type])ocinewdescriptor() alloue l'espace nécessaire pour stocker un descripteur, ou un pointeur de LOB. Les valeurs acceptées pour type sont oci_D_FILE, oci_D_LOB et oci_D_ROWID.
Exemple 1. ocinewdescriptor
|
Exemple 2. Exemple avec ocinewdescriptor()
|
ociNLogon
Description
resource ocinlogon ( string username, string password [, string db])ocinlogon() crée une nouvelle connexion à un serveur Oracle et s'authentifie. Si l'option ORACLE_SID n'est pas spécifié, PHP utilisera la variable d'environnement ORACLE_SID pour déterminer le serveur de connexion.
ocinlogon() force le serveur à établir une nouvelle connexion. Cette fonction ne doit être utilisée que si vous voulez isoler un ensemble de transactions. Par défaut, les connexions sont partagées au niveau de la page, si vous utilisez la fonction ocinlogon() ou bien au niveau du processus web, si vous utilisez ociplogon(). Si vous avez de multiples connexions ouvertes avec ocinlogon(), les validations et annulations ne s'appliquent qu'à la connexion spécifée.
L'exemple ci-dessous montre l'utilisation des connexions séparées.
Exemple 1. ociNLogon
|
Voir aussi ocilogon() et ociplogon().
ociNumCols
Description
int ocinumcols ( resource stmt)ocinumcols() retourne le nombre de colonnes dans un résultat.
Exemple 1. ociNumCols
|
ociparse
Description
int ociparse ( resource conn, string query)ociparse() analyse la requête query sur la connexion conn, et retourne TRUE si la requête query est valide, et FALSE, si ce n'est pas le cas. query peut être n'importe quelle requête SQL.
ociPLogon
Description
resource ociplogon ( string username, string password [, string db])ociplogon() crée une connexion persistante à un serveur Oracle 8 et s'authentifie. Si l'option ORACLE_SID n'est pas spécifiée, PHP utilisera la variable d'environnement ORACLE_SID pour déterminer le serveur de connexion.
Voir aussi ocilogon() et ocinlogon().
ociResult
Description
mixed ociresult ( resource statement, mixed column)ociresult() retourne les données de la colonne column dans la ligne courante (voir ocifetch()). ocifetch() retournera tout les types, sauf les types abstraits (ROWIDs, LOBs et FILEs).
ociRollback
Description
int ocirollback ( resource connection)ocirollback() annule les transactions en cours sur la connexion Oracle connection.
ociRowCount
Description
int ocirowcount ( resource statement)ocirowcount() retourne le nombre de lignes affectées par une commande de modification. Cette fonction ne vous indiquera pas le nombre de lignes retournées par un SELECT : il faut que les lignes aient été modifiées.
Exemple 1. ociRowCount
|
OCISaveLob
OCISaveLobFile
ociServerVersion
(PHP 3>= 3.0.4, PHP 4 )
ociServerVersion -- Retourne une chaîne contenant les informations de version du serveur.Description
string ociserverversion ( resource conn)ociserverversion() retourne une chaîne contenant les informations de version du serveur
ocisetprefetch
Description
int ocisetprefetch ( resource stmt, int rows)ocisetprefetch() indique le nombre des premières lignes qui doivent être pré-lues. La valeur par défaut est de 1.
ociStatementType
Description
string ocistatementtype ( resource stmt)ocistatementtype() retourne une des valeurs suivantes :
"SELECT"
"UPDATE"
"DELETE"
"INSERT"
"CREATE"
"DROP"
"ALTER"
"BEGIN"
"DECLARE"
"UNKNOWN"
Exemple 1. Exemples
|
OCIWriteLobToFile
LXXI. OpenSSL
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Introduction
Cette extension utilise les fonctions de OpenSSL pour générer et vérifier les signatures, ainsi que pour sceller (chiffrer) et ouvrir (déchiffrer) les données. Vous avez besoin de OpenSSL >= 0.9.5 pour utiliser ce module.
Cette extension supporte aussi la signature et le cryptage des courrier éléctroniques. Il est aussi possible de spécifier des couples clés/certificats d'un grand nombre de cas, qui rendent le code PHP plus facile à lire. Ces fonctionnalités sont disponibles en développement sur CVS, et probablement avec PHP 4.0.6. ATTENTION : cette extension est encore expérimentale!
OpenSSL offre de nombreuses fonctionnalités qui ne sont pas encore supportées par ce module. Elle seront ajoutées ultérieurement.
Paramètres clés/certificats
Un bon nombre de fonctions OpenSSL demandent une clé et un certificat comme paramètres. PHP 4.0.5 et plus récent utilisait des clés ou certificats sous forme de ressource, retournée par l'une des fonctions openssl_get_xxx(). Les versions ultérieures utilisent l'une des méthodes suivantes :
Certificats
Une ressource X.509 retournée par openssl_x509_read()
Une chaîne au format file://path/to/cert.pem; Le fichier ainsi repéré doit contenir un certificat, encodé au format PEM
Une chaîne contenant le contenu d'un certificat, encodé au format PEM.
Clés publiques/privée
Une ressource clé, retournée par la fonction openssl_get_publickey() ou openssl_get_privatekey()
Pour les clés publiques seulement : une ressource X.509
Une chaîne avec le format : file://path/to/file.pem. Le fichier doit contenir une clé privé ou un certificat, encodé au format PEM (il peut contenir les deux).
Une chaîne contenant une clé ou un certificat encodé au format PEM
Pour les clés privées, vous pouvez aussi 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 passe-phrase de cette clé privée.
Vérification de certificats
Lorsque vous appelez une fonction qui va vérifier une signature ou un certificat, le paramètre cainfo doit être un tableau contenant les noms d'un dossier et d'un fichier contenant les tiers de confiance. Si un dossier est spécifié, il doit être correct, car openssl va l'utiliser.
Constantes/flags PKCS7
Les fonctions S/MIME utilisent des flags qui sont spécifiés par un champs de bits. Les valeurs valides sont :
Tableau 1. Constantes PKCS7
| Constante | Description |
|---|---|
| PKCS7_TEXT | Ajoute le texte plein en clair dans les en-têtes du message signé/chiffré. Lors du déchiffrement ou 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 | Normalement, le message est converti au format canonique qui utilise effectivement des CR et LF comme fin de ligne, comme demandé dans les spécification de S/MIME. Lorsque cette option est activée, le message ne sera pas converti. Cela sert lorsque vous manipulez des données binaires qui ne sont pas au format MIME. |
| PKCS7_NOINTERN | Lors de la vérification d'un message, les certificats (s'il y en a) inclus dans le message sont normalement utilisé pour rechercher le certificat de signature. Avec cette option, seul le certificat spécifié par le paramètre extracerts de la fonction openssl_pkcs7_verify() est utilisé. Les certificats fournis peuvent toujours être utilisé, avec un niveau de confiance réduit. |
| PKCS7_NOVERIFY | Ne vérifie pas les certificats des signataires d'un message signé. |
| PKCS7_NOCHAIN | N'enchaine pas les vérifications des signataires de certificats. C'est-à-dire, n'utilise pas les certificats contenu dans le message. |
| PKCS7_NOCERTS | 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 local du certificat du signataire (passée au paramètre extracerts, avec la fonction openssl_pkcs7_verify()). |
| PKCS7_NOATTR | Normalement, lorsqu'un message est signé, un jeu d'attributs contenant l'heure de signature et l'algorithme symétrique supporté, est inclus dans le message. Avec cette option, il n'est pas inclus. |
| PKCS7_DETACHED | Lors de la signature d'un message, utilise la signature en texte claire, avec le type MIME "multipart/signed". C'est la valeur par défaut du paramètre flags pour la fonction openssl_pkcs7_sign(). Si vous annulez cette optoin, le message sera signé de manière opaque, ce qui resiste mieux à la traduction des relais mails (certains serveur mail anciens corrompent les messages), mais empêche la lecture par les client mails qui ne connaissent pas S/MIME. |
| PKCS7_NOSIGS | Ne vérifie pas les signatures d'une message |
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
- Table des matières
- openssl_csr_export_to_file -- Exports a CSR to file or a var
- openssl_csr_export -- Exports a CSR to file or a var
- openssl_csr_new -- Generates a privkey and CSR
- openssl_csr_sign -- Signs a cert with another CERT
- openssl_error_string -- Retourne le message d'erreur OpenSSL
- openssl_free_key -- Libère les ressources
- openssl_get_privatekey -- Prépare une clé privée au format PEM
- openssl_get_publickey -- Extrait une clé publique d'un certificat
- openssl_open -- Ouvre des données scellées
- openssl_pkcs7_decrypt -- Déchiffre un message S/MIME
- openssl_pkcs7_encrypt -- Chiffre un message S/MIME
- openssl_pkcs7_sign -- Signe un message S/MIME
- openssl_pkcs7_verify -- Vérifie la signature d'un message S/MIME
- openssl_pkey_export_to_file -- Gets an exportable representation of a key into a file
- openssl_pkey_export -- Gets an exportable representation of a key into a string or file
- openssl_pkey_new -- Generates a new private key
- openssl_private_decrypt -- Decrypts data with private key
- openssl_private_encrypt -- Encrypts data with private key
- openssl_public_decrypt -- Decrypts data with public key
- openssl_public_encrypt -- Encrypts data with public key
- openssl_seal -- Scelle des données
- openssl_sign -- Signe les données
- openssl_verify -- Vérifie une signature
- openssl_x509_check_private_key -- Checks if a private key corresponds to a CERT
- openssl_x509_checkpurpose -- Vérifie l'usage d'un certificat
- openssl_x509_export_to_file -- Exports a CERT to file or a var
- openssl_x509_export -- Exports a CERT to file or a var
- 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 une ressource
openssl_csr_export_to_file
Description
bool openssl_csr_export_to_file ( resource csr, string outfilename [, bool notext])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_csr_export
Description
bool openssl_csr_export ( resource csr, string out [, bool notext])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_csr_new
Description
bool openssl_csr_new ( array dn, resource privkey [, array extraattribs [, array configargs]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_csr_sign
Description
resource openssl_csr_sign ( mixed csr, mixed x509, mixed priv_key, long days)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_error_string
Description
mixed openssl_error_string ( void )openssl_error_string() retourne un message d'erreur, sous forme de chaîne de caractères, ou FALSE s'il n'y a pas de message d'erreur.
openssl_error_string() retourne la dernière erreur de la librairie OpenSSL. Les messages d'erreurs sont empilés, et openssl_error_string() doit être appelé plusieurs fois pour afficher toutes les erreurs.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_free_key
Description
void openssl_free_key ( resource key_identifier)openssl_free_key() libère les ressources associées à key_identifier.
openssl_get_privatekey
Description
resource openssl_get_privatekey ( mixed key [, string passphrase])openssl_get_privatekey() retourne un identifiant de clé positif, ou FALSE en cas d'erreur.
openssl_get_privatekey() analyse la clé privée key, au format PEM, et la prépare pour à être utilisée par d'autres fonctions. Le paramètre optionnel passphrase doit être utilisé si la clé est chiffrée (protégée par un mot de passe).
openssl_get_publickey
Description
resource openssl_get_publickey ( mixed certificate)openssl_get_publickey() retourne un identifiant de clé positif, ou FALSE en cas d'erreur.
openssl_get_publickey() extrait la clé publique du certificat certificate (format X.509), et la prépare à être utilisée ultérieurement.
openssl_open
Description
boolean openssl_open ( string sealed_data, string open_data, string env_key, mixed priv_key_id)openssl_open() TRUE en cas de succès, et FALSE sinon. En cas de succès, les données déchiffrées sont placées dans open_data.
openssl_open() ouvre (déchiffre) les données sealed_data en utilisant la clé prviée priv_key_id et la clé d'enveloppe env_key et remplis open_data avec les données déchiffrées. La clé d'enveloppe est générée lorsque les données sont scellées, et ne peut être utilisée qu'avec la clé privée spécifique. Reportez-vous à openssl_seal() pour plus d'informations.
Exemple 1. Exemple avec openssl_open()
|
Voir aussi openssl_seal().
openssl_pkcs7_decrypt
Description
boolean openssl_pkcs7_decrypt ( string infilename, string outfilename, mixed recipcert, mixed recipkey)openssl_pkcs7_decrypt() déchiffre le message S/MIME contenu dans le fichier infilename, en utilisant le certificat et la clé privée spécifiés par recipcert et recipkey. Le message déchiffré sera écrit dans le fichier outfilename.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Exemple 1. Exemple avec openssl_pkcs7_decrypt()
|
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_pkcs7_encrypt
Description
boolean openssl_pkcs7_encrypt ( string infilename, string outfilename, mixed recipcerts, array headers [, long flags])openssl_pkcs7_encrypt() prend le contenu du fichier infilename et le chiffre en utilisant un chiffrement RC2 à 40-bit, de manière à ce que le message ne puisse être lu que par le possesseur de recipcerts, qui peut être un certificat X.509, ou un tableau de certificats X.509. headers est un tableau d'en-têtes qui seront ajouté en tête de message, une fois que les données auront été chiffrées. flags peut être utilisé pour spécifier des options qui affecteront le chiffrement (voir les constantes PKCS7). 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 une en-tête complète.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Exemple 1. Exemple avec openssl_pkcs7_encrypt()
|
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_pkcs7_sign
Description
boolean openssl_pkcs7_sign ( string infilename, string outfilename, mixed signcert, mixed privkey, array headers [, long flags [, string extracertsfilename]])openssl_pkcs7_sign() prend le contenu du fichier infilename et le signe en utilisant le certificat et la clé privée contenus dans les arguments signcert et privkey.
headers est un tableau d'en-têtes qui seront ajouté au données chiffrées (voir la fonction openssl_pkcs7_encrypt() pour plus de détails sur le format du paramètre).
flags sert à modifier le message final. Voyez les constantes PKCS7. Par défaut, la valeur est : PKCS7_DETACHED.
extracerts spécifi le nom du fichier contenant un ensemble de certificat supplémentaires à inclure dans la signature, qui pourront aider le destinataire à vérifier les données que vous utilisez.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Exemple 1. Exemple avec openssl_pkcs7_sign()
|
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_pkcs7_verify
Description
boolean openssl_pkcs7_verify ( string filename, int flags [, string outfilename [, array cainfo [, string extracerts]]])openssl_pkcs7_verify() lit le message S/MIME contenu dans le fichier filename et examine la signature digitale. openssl_pkcs7_verify() 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). openssl_pkcs7_verify() retourne -1 en cas d'erreur de vérification (la vérification s'est mal déroulée, aucune conclusion possible).
flags sert à modifier le message final. Voyez les constantes PKCS7. Par défaut, la valeur est : PKCS7_DETACHED.
Si le paramètre outfilename est spécifié, il doit être une chaîne contenant le nom d'un fichier qui contient le certificat du signataire, au format PEM.
Si le paramètre cainfo est spécifié, il doit contenir les informations sur les tiers de certificats de confiance utilisé lors de la vérification. Voyez vérification des certificats pour plus de détails.
Si le paramètre extracerts est spécifié, il doit représenter le nom d'un fichier contenant un ensemble de certificat utilisé comme certificats de peu de confiance.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_pkey_export_to_file
(PHP 4 >= 4.2.0)
openssl_pkey_export_to_file -- Gets an exportable representation of a key into a fileDescription
bool openssl_pkey_export_to_file ( mixed key, string outfilename [, string passphrase [, array config_args]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_pkey_export
(PHP 4 >= 4.2.0)
openssl_pkey_export -- Gets an exportable representation of a key into a string or fileDescription
bool openssl_pkey_export ( mixed key, mixed out [, string passphrase [, array config_args]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_pkey_new
Description
resource openssl_pkey_new ( [array configargs])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_private_decrypt
Description
bool openssl_private_decrypt ( string data, string crypted, mixed key [, int padding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_private_encrypt
Description
bool openssl_private_encrypt ( string data, string crypted, mixed key [, int padding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_public_decrypt
Description
bool openssl_public_decrypt ( string data, string crypted, resource key [, int padding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_public_encrypt
Description
bool openssl_public_encrypt ( string data, string crypted, mixed key [, int padding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_seal
Description
int openssl_seal ( string data, string sealed_data, array env_keys, array pub_key_ids)openssl_seal() 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 env_keys.
openssl_seal() scelle (chiffre) les données data en utilisant l'algorithme RC4 avec une clé secrètre générée aléatoirement. La clé est chiffrée avec chaque clé publique associée à pub_key_ids et chaque clé ainsi encryptée est retournée dans env_keys. Cela signifique que vous pouvez envoyez des données scellées à plusieurs destinataires (en supposant que chacun ait recu la clé publique). Chaque destinataire doit recevoir les données encryptées et la clé d'enveloppe, qui a été encryptée avec la clé publique du destinataire.
Exemple 1. Exemple avec openssl_seal()
|
Voir aussi openssl_open().
openssl_sign
Description
boolean openssl_sign ( string data, string signature, mixed priv_key_id)openssl_sign() retourne TRUE en cas de succès, et FALSE sinon. En cas de succès, la signature est placée dans signature.
openssl_sign() calcule la signature des données data en utilisant l'algorithme SHA1 (hashing) suivi du chiffrage avec la clé privée priv_key_id. Notez que les données elles-mêmes ne sont pas chiffrées.
Exemple 1. Exemple avec openssl_sign()
|
Voir aussi openssl_verify().
openssl_verify
Description
int openssl_verify ( string data, string signature, resource pub_key_id)openssl_verify() retourne 1 si la signature est correcte, 0 si la signature est incorrecte, et -1 en cas d'erreur.
openssl_verify() vérifie que la signature signature est correcte pour les données data, et avecd la clé publique pub_key_id. Cette clé doit être la clé publique correspondant à la clé privée utilisée lors de la signature.
Exemple 1. Exemple avec openssl_verify()
|
Voir aussi openssl_sign().
openssl_x509_check_private_key
Description
bool openssl_x509_check_private_key ( mixed cert, mixed key)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_x509_checkpurpose
Description
boolean openssl_x509_checkpurpose ( mixed x509cert, int purpose, array cainfo [, string untrustedfile])openssl_x509_checkpurpose() TRUE si le certificat peut être utilisé pour un but particulier, FALSE s'il ne le peut pas, et -1 en cas d'erreur.
openssl_x509_checkpurpose() examine le certificat spécifié par x509cert, pour voir s'il peut être utilisé pour une opération particulière purpose.
cainfo doit être un tableau de dossiers/fichiers de CA de confiance comme décrit dans la Vérification des certificats.
untrustedfile, 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 une confiance limitée doit leur être portée.
Les paramètres et le type de retour de cette fonction risquent d'evoluer d'ici à la prochaine version de PHP.
Tableau 1. Utilisations 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 courrier à 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 chiffrer une liste de revocation de certificat? (CRL)? |
| X509_PURPOSE_ANY | Est-ce que le certificat peut être utilisé pour n'importe lequel de ces cas? |
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_x509_export_to_file
Description
bool openssl_x509_export_to_file ( mixed x509, string outfilename [, bool notext])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_x509_export
Description
bool openssl_x509_export ( mixed x509, string outfilename [, bool notext])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
openssl_x509_free
Description
void openssl_x509_free ( resource x509cert)openssl_x509_free() libère les ressources prises par le certificat x509cert
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_x509_parse
Description
array openssl_x509_parse ( mixed x509cert [, boolean shortnames])openssl_x509_parse() analyse le certificat X509 x509cert, 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... shortnames contrôle l'indexation des données dans le tableau : si shortnames 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).
La structure des données retournées est (délibérément) non documentée, car elle est sujette à des changements probables.
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
openssl_x509_read
LXXII. Oracle
- Table des matières
- Ora_Bind -- Lie une variable PHP à un paramètre Oracle.
- Ora_Close -- Ferme un pointeur Oracle.
- Ora_ColumnName -- Retourne le nom de la colonne de résultat.
- Ora_ColumnSize -- Lit la taille d'une colonne
- Ora_ColumnType -- Retourne le type de la colonne de résultat.
- Ora_Commit -- Valide une transaction Oracle.
- Ora_CommitOff -- Inactive la validation automatique.
- Ora_CommitOn -- Active la validation automatique.
- Ora_Do -- Analyse, exécute et lit une requête
- Ora_Error -- Retourne le message d'erreur Oracle.
- Ora_ErrorCode -- Retourne le code d'erreur Oracle.
- Ora_Exec -- Exécute une commande analysée sur un pointeur Oracle.
- Ora_Fetch_Into -- Lit une ligne dans un tableau
- Ora_Fetch -- Retourne une ligne de résultat.
- Ora_GetColumn -- Retourne une donnée d'une ligne lue.
- Ora_Logoff -- Ferme une connexion Oracle.
- Ora_Logon -- Ouvre une connexion Oracle.
- Ora_Numcols -- Retourne le nombre de colonnes
- Ora_Numrows -- Retourne le nombre de colonnes
- Ora_Open -- Ouvre un pointeur Oracle.
- Ora_Parse -- Analyse une requête SQL.
- Ora_pLogon -- Ouvre une connexion persistante à Oracle
- Ora_Rollback -- Annule une transaction.
Ora_Bind
Description
int ora_bind ( resource cursor, string PHP variable name, string SQL parameter name, int length [, int type])ora_bind() retourne TRUE si la liaison a pu se faire, et sinon FALSE. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
Cette fonction lie une variable PHP avec un paramètre SQL. Le paramètre SQL doit être de la forme ":name". Avec l'option, vous pouvez choisir si le paramètre SQL est de type entrée/sortie (0, valeur par défaut), entrée seulement (1) ou sortie seulement (2). Comme dans PHP 3.0.1, vous pouvez respectivement utiliser les constantes ORA_BIND_INOUT, ORA_BIND_IN et ORA_BIND_OUT plutôt que des nombres.
ora_bind() doit être appelée après la fonction ora_parse() et avant ora_exec(). Les valeurs d'entrées peuvent alors être fournies par assignation des variables PHP. Après la fonction ora_exec() les variables liées contiennent les valeurs de sortie, si elles sont disponibles. Par exemple :
<?php ora_parse($curs, "declare tmp INTEGER; begin tmp := :in; :out := tmp; :x := 7.77; end;"); ora_bind($curs, "result", ":x", $len, 2); ora_bind($curs, "input", ":in", 5, 1); ora_bind($curs, "output", ":out", 5, 2); $input = 765; ora_exec($curs); echo "Résultat: $result<br>Sortie: $output<br>Entrée: $input"; ?> |
Ora_Close
Description
int ora_close ( resource cursor)ora_close() retourne TRUE si la fermeture a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
ora_close() termine les pointeurs ouverts avec la fonction ora_open().
Ora_ColumnName
Description
string ora_columnname ( resource cursor, int column)ora_columnname() retourne le nom du champs column du pointeur cursor. Le nom retourné sera en majuscule.
Ora_ColumnSize
Description
int ora_columnsize ( resource cursor, int column)ora_columnsize() retourne la taille de la colonne column dans le résultat cursor.
Ora_ColumnType
Description
string ora_columntype ( resource cursor, int column)ora_columntype() retourne le type de la colonne column du résultat cursor. Le type retourné prendra une des valeurs suivantes :
| "VARCHAR2" |
| "VARCHAR" |
| "CHAR" |
| "NUMBER" |
| "LONG" |
| "LONG RAW" |
| "ROWID" |
| "DATE" |
| "CURSOR" |
Ora_Commit
Description
int ora_commit ( resource conn)ora_commit() retourne TRUE si la validation a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
ora_commit() valide les transactions Oracle. Une transaction est définie par toutes les requêtes effectuées sur la connexion conn depuis la dernière validation ou annulation (avec auto-validation inactivée) ou depuis l'établissement de la connexion.
Ora_CommitOff
Description
int ora_commitoff ( resource conn)ora_commitoff() retourne TRUE si la désactivation a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
ora_commitoff() inactive la validation automatique après chaque ora_exec().
Ora_CommitOn
Description
int ora_commiton ( resource conn)ora_commiton() active la validation automatique après chaque ora_exec().
ora_commiton() retourne TRUE si l'activation a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
Ora_Do
Description
int ora_do ( resource conn, string query)ora_do() est une combinaison de ora_parse(), ora_exec() et ora_fetch(). Elle va analyser la requête, l'éxécuter et lire la première ligne du résultat.
ora_do() retourne TRUE en cas de succès, et FALSE sinon. Le détails sur les erreurs est accessible avec les fonctions ora_error() et ora_errorcode().
Voir aussi ora_parse(), ora_exec() et ora_fetch().
Ora_Error
Description
string ora_error ( resource cursor_or_connection)ora_error() retourne un messages d'erreur de la forme XXX-NNNNN avec XXX qui est l'origine de l'erreur, et NNNNN qui identifie le message d'erreur.
Note : Le support des connexions a été ajouté en PHP 3.0.4.
Avec les versions UNIX d'Oracle, vous pouvez avoir des messages d'erreur tels que : $ oerr ora 00001 00001, 00000, "unique constraint (%s.%s) violated" // *Cause: An update or insert statement attempted to insert a duplicate key // For Trusted ORACLE configured in DBMS MAC mode, you may see // this message if a duplicate entry exists at a different level. // *Action: Either remove the unique restriction or do not insert the key .
Ora_ErrorCode
Description
int ora_errorcode ( resource cursor_or_connection)ora_errorcode() retourne le code d'erreur numérique de la dernière commande exécuté sur la connexion ou le pointeur fourni en paramètre.
Note : Les identifiants de connexion ne sont acceptés qu'à partir de la version 3.0.4.
Ora_Exec
Description
boolean ora_exec ( resource cursor)ora_exec() retourne TRUE en cas de succès, et FALSE en cas d'erreur. L'erreur générée sera alors accessible avec les fonctions ora_error() et ora_errorcode().
Ora_Fetch_Into
Description
int ora_fetch_into ( resource cursor, array result [, int flags])ora_fetch_into() lit la ligne courante du résultat cursor dans le tableau result.
Voir aussi ora_parse(), ora_exec(), ora_fetch() et ora_do().
Ora_Fetch
Description
int ora_fetch ( resource cursor)ora_fetch() retourne TRUE (une ligne a été lue) ou FALSE (plus de lignes à lire ou erreur). Si une erreur survient, sa valeur sera disponible dans les fonctions ora_error() et ora_errorcode().
Lit une ligne de données sur le pointeur cursor.
Voir aussi ora_parse(), ora_exec() et ora_do().
Ora_GetColumn
Description
mixed ora_getcolumn ( resource cursor, mixed column)ora_getcolumn() retourne la valeur de la colonne. Si une erreur survient, FALSE est retourné et ora_errorcode() aura une valeur non nulle. Notez, qu'un test à FALSE, avec cette fonction peut être \TRUE, même sans erreur : en effet, la fonction peut retourner des valeurs telles que résultat NULL, chaînes vides, nombre 0, la chaîne "0".
Ora_Logoff
Description
int ora_logoff ( resource connection)ora_getcolumn() retourne la valeur de la colonne. Si une erreur survient, FALSE est retourné et ora_errorcode() aura une valeur non nulle. Notez, qu'un test à FALSE, avec cette fonction peut être TRUE, même sans erreur : en effet, la fonction peut retourner des valeurs telles que (résultat NULL, chaînes vides, nombre 0, la chaîne "0").
Ora_Logon
Description
resource ora_logon ( string user, string password)ora_logon() établit une connexion entre PHP et un serveur Oracle avec les noms d'utilisateur user et le mot de passe password.
Les connexions peut être faîtes avec SQL*Net en fournissant le nom TNS de la manière suivante :
Si vous avez des données qui ne sont pas ASCII, vous devriez vérifier que la variable NLS_LANG a été correctement configuré dans votre environnement. Pour les modules de serveur, vous devrez la configurer dans l'environnement d'exécution du serveur avant de le lancer.
ora_logon() retourne un index de connexion, en cas de succès, ou FALSE en cas d'échec. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
Ora_Numcols
Description
int ora_numcols ( resource cursor_ind)ora_numcols() retourne le nombre de colonne dans le résultat cursor_ind. Cette valeur n'est significative qu'après une requête parse/exec/fetch.
Voir aussi ora_parse(), ora_exec(), ora_fetch() et ora_do().
Ora_Numrows
Description
int ora_numrows ( resource cursor_ind)ora_numrows() retourne le nombre de colonnes dans le résultat cursor_ind.
Ora_Open
Description
resource ora_open ( resource connection)ora_open() ouvre un pointeur Oracle sur la connexion.
ora_open() retourne TRUE si la fermeture a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
Ora_Parse
Description
int ora_parse ( resource cursor_ind, string sql_statement, int defer)ora_parse() analyse une requête SQL ou un bloc PL/SQL et l'associe avec le pointeur cursor_ind. Retourne 0 en cas de succès, et -1 en cas d'erreur.
ora_parse() retourne 0 en cas de succès, et -1 en cas d'erreur.
Voir aussi ora_exec(), ora_fetch() et ora_do().
Ora_pLogon
Description
resource ora_plogon ( string user, string password)ora_plogon() établit une connexion persistante à un serveur Oracle, avec l'utilisateur user et le mot de passe password.
Voir aussi ora_logon().
Ora_Rollback
Description
int ora_rollback ( resource connection)ora_rollback() annule une transaction Oracle. (Voir ora_commit() pour la définition d'une transaction).
ora_rollback() retourne TRUE si la fermeture a bien eu lieu, et FALSE sinon. Les erreurs sont accessibles avec les fonctions ora_error() et ora_errorcode().
LXXIII. Ovrimos SQL
Ovrimos SQL Server est une base de données relationnelle client/serveur et transactionnelle, combinée avec des fonctionnalités web, et des transactions rapides.
Ovrimos SQL Server est disponible à www.ovrimos.com. Pour activer le support ovrimos de PHP, il suffit de compiler PHP avec l'option --with-ovrimos du script de configuration. Vous devrez aussi installer la librairie sqlcli disponible avec la distribution Ovrimos SQL Server.
Exemple 1. Connection au serveur Ovrimos SQL Server et sélection d'une table système
|
- Table des matières
- ovrimos_close -- Ferme une connexion
- ovrimos_commit -- Valide une transaction
- ovrimos_connect -- Connexion à un serveur
- ovrimos_cursor -- Retourne le nom du curseur
- ovrimos_exec -- Exécute une requête SQL
- ovrimos_execute -- Exécute une requête préparée
- ovrimos_fetch_into -- Lit une ligne dans un résultat
- ovrimos_fetch_row -- Lit une ligne dans un résultat
- ovrimos_field_len -- Retourne la taille d'une colonne
- ovrimos_field_name -- Retourne le nom d'une colonne
- ovrimos_field_num -- Retourne le numéro de colonne
- ovrimos_field_type -- Retourne le type numérique d'une colonne
- ovrimos_free_result -- Libère les ressources utilisées par un résultat
- ovrimos_longreadlen -- Indique la taille des données à lire dans une colonne de grande taille
- ovrimos_num_fields -- Retourne le nombre de colonnes
- ovrimos_num_rows -- Retourne le nombre de lignes affectées par une modification
- ovrimos_prepare -- Prépare une requête SQL
- ovrimos_result_all -- Affiche un résultat sous forme de table HTML
- ovrimos_result -- Lit le contenu d'une colonne
- ovrimos_rollback -- Annule une transaction
ovrimos_close
Description
void ovrimos_close ( int connection)ovrimos_close() sert à ferme une connexion à un serveur Ovrimos.
ovrimos_close() ferme la connexion au serveur Ovrimos. Toutes les transactions non validées sont annulées.
ovrimos_commit
Description
int ovrimos_commit ( int connection_id)ovrimos_commit() sert à exécuter une transaction.
ovrimos_commit() exécute la transaction préparée sur la connexion connection_id.
ovrimos_connect
Description
int ovrimos_connect ( string host, string db, string user, string password)ovrimos_connect() sert à se connecter à un serveur Ovrimos.
ovrimos_connect() retourne un identifiant de connexion, supérieur à 0, ou 0 en cas d'échec.host est l'adresse IP de l'hôte Ovrimos, et db est soit le nom d'une base de données, soit une chaîne contenant le numéro de port.
Exemple 1. Exemple avec ovrimos_connect()
|
ovrimos_cursor
Description
int ovrimos_cursor ( int result_id)ovrimos_cursor() sert à lire le nom du curseur
ovrimos_cursor() retourne le nom du curseur. Pratique, lorsqu'on veut faire des modifications ou des effacements avec des curseurs déjà positionnés.
ovrimos_exec
Description
int ovrimos_exec ( int connection_id, string query)ovrimos_exec() sert à exécuter une requête SQL.
ovrimos_exec() exécute une requête SQL (selection ou modification), et retourne un identifiant de résultat result_id (ou bien FALSE, en cas d'échec). Evidemment, la requête SQL ne doit pas contenir de paramètres.
ovrimos_execute
Description
boolean ovrimos_execute ( int result_id [, array parameters_array])ovrimos_execute() sert à exécuter une requête SQL.
ovrimos_execute() exécute une requête préparée. ovrimos_execute() retourne TRUE ou FALSE. Si la requête préparée contient des paramètres (des points d'interrogations dans la requête), un nombre correct de paramètre doit être passé dans le tableau parameters_array. Notez que ovrimos_execute() ne suit pas les conventions PHP qui placent les noms des paramètres entre crochets. L'auteur n'a pas pu s'y faire.
ovrimos_fetch_into
Description
boolean ovrimos_fetch_into ( int result_id, array result_array [, string how [, int rownumber]])ovrimos_fetch_into() lit une ligne dans un résultat SQL.
ovrimos_fetch_into() lit une ligne dans le résultat result_id, qui doit être passé en référence. La ligne qui sera lue est déterminée par les deux paramètres how et rownumber. how peut prendre les valeurs de 'Next' (suivant, valeur par défaut), 'Prev' (précédent), 'First' (premier), 'Last' (dernier), 'Absolute' (position absolue). La casse de how n'est pas prise en compte. rownumber est optionnel, sauf dans le cas d''Absolute'. ovrimos_fetch_into() retourne TRUE ou FALSE.
Exemple 1. Lit un exemple
|
ovrimos_fetch_row
Description
boolean ovrimos_fetch_row ( int result_id [, int how [, int row_number]])ovrimos_fetch_row() lit une ligne dans un résultat SQL.
ovrimos_fetch_row() lit une ligne dans un résultat. Les colonnes doivent être lues par un autre appel. Retourne TRUE en cas de succès et FALSE sinon.
Exemple 1. Exemple de lecture de ligne
|
ovrimos_field_len
Description
int ovrimos_field_len ( int result_id, int field_number)ovrimos_field_len() sert à connaître la taille d'une colonne.
ovrimos_field_len() retourne la taille de la colonne field_number, dans le résultat field_number.
ovrimos_field_name
Description
int ovrimos_field_name ( int result_id, int field_number)ovrimos_field_name() sert à obtenir le nom d'une colonne.
ovrimos_field_name() retourne le nom d'une colonne à partir de son numéro de colonne field_number, (la première colonne est à 1).
ovrimos_field_num
Description
int ovrimos_field_num ( int result_id, string field_name)ovrimos_field_num() sert à connaître le nuémro de colonne, à partir de son nom.
ovrimos_field_num() retourne le numéro de la colonne field_name (la numérotation commence à 1), dans result_id.
ovrimos_field_type
Description
int ovrimos_field_type ( int result_id, int field_number)ovrimos_field_type() sert à connaître le type numérique d'une colonne.
ovrimos_field_type() retourne le type numérique d'une colonne, identifiée par son numéro field_number dans le résultat field_number.
ovrimos_free_result
Description
int ovrimos_free_result ( int result_id)ovrimos_free_result() sert à effacer un résultat.
ovrimos_free_result() libère toutes les ressources prises par le résultat result_id. ovrimos_free_result() retourne TRUE.
ovrimos_longreadlen
(PHP 4 >= 4.0.3)
ovrimos_longreadlen -- Indique la taille des données à lire dans une colonne de grande tailleDescription
int ovrimos_longreadlen ( int result_id, int length)ovrimos_longreadlen() sert à lire la taille des données qui sera lues lors de l'accès une colonne de grande taille.
ovrimos_longreadlen() indique le nombre d'octets qui seront lus dans une colonne de grande taille (long varchar et long varbinary). Par défaut, 0. Indépendemment du fait que ovrimos_longreadlen() requiert result_id, actuellement ovrimos_longreadlen() affecte ce paramètre pour tous les résultats.
ovrimos_num_fields
Description
int ovrimos_num_fields ( int result_id)ovrimos_num_fields() indique le nombre de colonnes du résultat result_id.
ovrimos_num_rows
Description
int ovrimos_num_rows ( int result_id)ovrimos_num_rows() retourne le nombre de lignes affectées par une modification
ovrimos_prepare
Description
int ovrimos_prepare ( int connection_id, string query)ovrimos_prepare() sert à préparer une requête SQL.
ovrimos_prepare() prépare une requête SQL et retourne un identifiant de résultat result_id (ou FALSE en cas d'échec).
Exemple 1. Connexion à un serveur Ovrimos SQL Server et préparation d'une requête
|
ovrimos_result_all
Description
boolean ovrimos_result_all ( int result_id [, string format])ovrimos_result_all() sert à afficher tout le résultat d'une requête.
ovrimos_result_all() affiche le résultat de la requête représentée par result_id. ovrimos_result_all() retourne TRUE ou FALSE.
Exemple 1. Prépare une requête, l'éxécute, et affiche le résultat
|
Exemple 2. ovrimos_result_all() avec meta-information
|
Exemple 3. Exemple avec ovrimos_result_all()
|
ovrimos_result
Description
int ovrimos_result ( int result_id, mixed field)ovrimos_result() sert à lire le contenu de l;a colonne field dans le résultat result_id.
ovrimos_result() lit le contenu de la colonne field dans le résultat result_id. field peut être le nom de la colonne (une chaîne) ou bien le numéro de la colonne (la première colonne est alors 1).
ovrimos_rollback
LXXIV. Entrées/sorties
Les fonctions d'entrée/sorties vous permettent de contrôler quand les données ont été envoyées par le script. Cela peut être utile dans certaines situations, notamment si vous devez envoyer des en-têtes au navigateur après avoir envoyé des données. Ces fonctions n'affectent pas les en-têtes envoyées 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.
Dans l'exemple ci-dessus, la fonction 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. (D'habitude, vous devez envoyer les en-têtes avant les données).
Voir aussi header() et setcookie().
- Table des matières
- flush -- Vide les buffers de sortie.
- ob_clean -- Clean (erase) the output buffer
- ob_end_clean -- Détruit les données du buffer de sortie, et éteint la bufferisation de sortie
- ob_end_flush -- Envoie les données du buffer de sortie, et éteint la bufferisation de sortie
- ob_flush -- Flush (send) the output buffer
- ob_get_contents -- Retourne le contenu du buffer de sortie
- ob_get_length -- Retourne la longueur du contenu du buffer de sortie
- ob_get_level -- Return the nesting level of the output buffering mechanism
- ob_get_status -- Get status of output buffers
- ob_gzhandler -- Fonction de callback pour la compression automatique des buffers
- ob_implicit_flush -- Active/désactive l'envoi implicite
- ob_start -- Enclenche la bufferisation de sortie
flush
Description
void flush ( void)flush() vide les buffers de sortie de PHP et tous ceux que PHP utilisait (CGI, un serveur web, etc.). Cette fonction envoye réellement toutes les données préparées vers l'utilsateur.
Note : flush() n'a aucun effet sur la bufferisation de votre serveur web ou du navigateur.
De nombreux serveurs, essentiellement sous Windows, continueront à bufferiser l'affichage de votre script jusqu'à ce qu'il soit terminé, avant de transmettre les résultats à l'internaute.
Des modules Apache comme mod_gzip utilisent leur propre bufferisation, ce qui fait que flush() n'enverra pas les données jusqu'au navigateur client immédiatement.
Même le navigateur peut réaliser une bufferisation avant de l'afficher. Netscape, par exemple, met en cache le texte jusqu'à ce qu'il recoive une fin de ligne, ou une nouvelle et il ne va effectuer aucun affichage tant que les balises </table> ne seront pas toutes refermées.
Certaines versions de Microsoft Internet Explorer ne commençeront l'affichage de la page qu'après avoir reçu 256 octets d'affichage. Cela vous obligera à envoyer des espaces supplémentaires pour afficher la page.
ob_clean
Description
void ob_clean ( void)This function discards the contents of the output buffer.
This function does not destroy the output buffer like ob_end_clean() does.
See also ob_flush(), ob_end_flush() and ob_end_clean().
ob_end_clean
(PHP 4 )
ob_end_clean -- Détruit les données du buffer de sortie, et éteint la bufferisation de sortieDescription
void ob_end_clean ( void)ob_end_clean() détruit les données du buffer de sortie, et éteint la bufferisation.
Voir aussi ob_start() et ob_end_flush().
ob_end_flush
(PHP 4 )
ob_end_flush -- Envoie les données du buffer de sortie, et éteint la bufferisation de sortieDescription
void ob_end_flush ( void)ob_end_flush() envoie le contenu du buffer de sortie (s'il existe) et éteint la bufferisation de sortie. Si vous voulez continuer à manipuler la valeur du buffer, vous pouvez appeler ob_get_contents() avant ob_end_flush() car le contenu du buffer est détruit après un appel à ob_end_flush().
Voir aussi ob_start(), ob_get_contents() et ob_end_clean().
ob_flush
Description
void ob_flush ( void)This function will send the contents of the output buffer (if any). If you want to further process the buffer's contents you have to call ob_get_contents() before ob_flush() as the buffer contents are discarded after ob_flush() is called.
This function does not destroy the output buffer like ob_end_flush() does.
See also ob_get_contents(), ob_clean(), ob_end_flush() and ob_end_clean().
ob_get_contents
Description
string ob_get_contents ( void)ob_get_contents() retourne le contenu du buffer de sortie si la bufferisation est activée, ou FALSE sinon.
Voir aussi ob_start() et ob_get_length().
ob_get_length
Description
string ob_get_length ( void)ob_get_length() retourne la longueur du contenu du buffer de sortie si la bufferisation est activée, et FALSE sinon.
Voir aussi ob_start() et ob_get_contents().
ob_get_level
Description
int ob_get_level ( void)This will return the level of nested output buffering handlers.
See also ob_start() and ob_get_contents().
ob_get_status
Description
array ob_get_status ( [bool full_status])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
This will return the current status of output buffers. It returns array contains buffer status or FALSE for error.
See also ob_get_level().
ob_gzhandler
Description
string ob_gzhandler ( string buffer)ob_gzhandler() est destinée à être utilisée comme fonction de callback 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 buffers de manière appropriée. Tous les navigateurs sont traités, car c'est aux navigateurs d'envoyer une en-tête indiquant les types de pages supportés.
Voir aussi ob_start() et ob_end_flush().
ob_implicit_flush
Description
void ob_implicit_flush ( [int flag])ob_implicit_flush() active/désactive l'envoi implicite (si flag est fourni. Par défaut, il est activé). L'envoi implicite signifie que toute fonction qui envoie des données au navigateur verra ses données envoyées immédiatement (la fonction flush() est appelée automatiquement).
Une fois que l'envoi implicite est désactivé, le buffer de sortie ne sera envoyé qu'au moment de l'appel de ob_end_flush().
Voir aussi flush(), ob_start() et ob_end_flush().
ob_start
Description
void ob_start ( [string output_callback])ob_start() démarre la bufferisation de sortie. Tant qu'elle est enclenchée, aucune donnée, hormis les en-têtes, n'est envoyée au navigateur, mais temporairement mise en buffer.
Le contenu de ce buffer peut être copié dans une chaîne avec la fonction ob_get_contents(). Pour afficher le contenu de ce buffer, utilisez ob_end_flush(). Au contraire, ob_end_clean() effacera le contenu de ce buffer.
Une fonction optionnelle de callback peut être spécifiée en troisième argument. ob_start() prend une chaîne comme paramètre, et retourne une chaîne. Elle sera appelée par ob_end_flush() ou lorsque le buffer sera envoyé au navigateur à la fin du script et recevra le contenu du buffer de sortie. Lorsque la fonction output_callback est appelée, elle doit retourner un nouveau contenu pour le buffer de sortie : celui-ci sera envoyé au navigateur.
Note : En PHP 4.0.4, ob_gzhandler() a été introduit pour faciliter l'envoi de fichier compressé avec gz aux navigateurs web qui supportent les pages compressées. ob_gzhandler() détermine le type d'encodage accepté par un navigateur, et retourne le contenu le plus adéquat.
Les buffers de sortie sont gérés par pile, c'est-à-dire que vous pouvez appeler plusieurs fois ob_start() simultanément. Assurez-vous que vous appelez ob_end_flush() suffisamment souvent. Si plusieurs fonctions de callback sont actives, les contenus seront filtrés séquentiellement, dans l'ordre d'emboîtement.
Exemple 1. Exemple de callback avec fonction utilisateur
|
va afficher :
Voir aussi ob_get_contents(), ob_end_flush(), ob_end_clean(), ob_implicit_flush() et ob_gzhandler().
LXXV. Overload
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Le but de cette extension est de permettre de maîtriser les appels aux méthodes et aux membres d'un objet. Seule une fonction est définie dans cette extension, overload() qui demande le nom de la classe qui supporte cet fonctionnalité. Cette classe doit être pourvue des méthodes nécessaire au bon fonctionnement de l'extension, c'est à dire : __get(), __set() et __call(), qui servent respectivement à lire et modifier un membre, et appeler une méthode. De cette manière, l'overloading assure un contrôle sur les fonctions appelées. A l'intérieur de ces méthodes, l'overloading est désactivé, pour que vous puissiez accéder à l'objet.
Voici un exemple simple de fonctions utilisant overload() :
Exemple 1. Overload avec une classe PHP
|
| Avertissement |
Comme c'est une extension expérimentale, tout ne fonctionne pas encore. Il n'y a pas de support pour __call() actuellement, et nouvs ne pouvez overloader que des accesseurs. Vous ne pouvez pas appeler les fonctions d'overload de la classe, et __set() ne fonctionne que pour un seul niveau d'accesseur. |
- Table des matières
- overload -- Active la couche de contrôle des membres et méthodes
overload
Description
void overload ( [string class_name])overload() active le contrôle des accesseurs et appels de méthodes pour la classe class_name. Voir un exemple dans l'introduction de ce chapitre.
LXXVI. PDF
Vous disposez de fonctions PDF en PHP pour créer des fichiers PDF, pour peu que vous ayez la bibliothèque PDF de Thomas Merz (disponible à : http://www.pdflib.com/pdflib/index.html (site anglais)). Vous aurez aussi besoin des librairies JPEG library, the TIFF library, pour compiler cette librairie. Ces deux librairies posent pas mal de problèmes lors de la configuration. Suivez attentivement les messages d'erreur.
Reportez vous à l'excellente documentation de PDFLib, disponible avec la distribution de PDFLib. C'est une introduction très pratique des possibilités de PDFLib et elle contient la liste la plus complète et les descriptions les plus à jours des fonctions.
Toutes les fonctions de PDFLib se retrouvent dans PHP sous le même nom. De même, les paramètres sont identiques. Vous devez connaître les concepts de base de PDF ou de Postscript pour utiliser efficacement ce module. Toutes les longueurs et coordonnées sont mesurées en points Postscript points. Il y a généralement 72 points PostScript par pouce, mais cela dépend en fait de la résolution d'affichage.
Il y a un autre module PHP pour créer des document PDF, basé sur la bibliothèque FastIO's's ClibPDF. Les API sont légèrement différentes. Reportez-vous à la section fonctions ClipPDF pour plus de détails.
Le module PDF introduit un nouveau type de variables. C'est pdfdoc : c'est un pointeur sur un document PDF et toutes les fonctions l'utilise comme premier paramètre.
Confusion entre les vieilles versions de PDFLib
Depuis le début du support de PDF sous PHP, (commençant avec la version PDFLib 0.6), il y a eu des milliers de modifications dans les API de PDFLib. La plus part de ces modifications ont été suivies par PHP, et parfois même au prix de modifications des API PHP. Depuis la version 3.x, ces API semblent s'être stabilisées, et PHP 4 a adoptée cette version comme le minimum nécessaire pour supporter PDF. En conséquence de quoi, un grand nombre de fonction vont disparaître, ou être remplacée. Le support de PDFLib 0.6 est complétement abandonné. La liste suivante indique quelles sont les fonctions obsolètes en PHP 4.02, et qui devraient être remplacées par de nouvelles versions.
Tableau 1. Fonctions obsolètes et leur remplacements
| Anciennes fonctions | Nouvelles fonctions |
|---|---|
| pdf_put_image() | Désormais inutile |
| pdf_execute_image() | Désormais inutile |
| pdf_get_annotation() | pdf_get_bookmark() avec les mêmes paramètres. |
| pdf_get_font() | pdf_get_value() avec "font" comme second paramètre. |
| pdf_get_fontsize() | pdf_get_value() avec "fontsize" comme second paramètre. |
| pdf_get_fontname() | pdf_get_parameter() avec "fontname" comme second paramètre. |
| pdf_set_info_creator() | pdf_set_info() avec "Creator" comme second paramètre. |
| pdf_set_info_title() | pdf_set_info() avec "Title" comme second paramètre. |
| pdf_set_info_subject() | pdf_set_info() avec "Subject" comme second paramètre. |
| pdf_set_info_author() | pdf_set_info() avec "Author" comme second paramètre. |
| pdf_set_info_keywords() | pdf_set_info() avec "Keywords" comme second paramètre. |
| pdf_set_leading() | pdf_set_value() avec "leading" comme second paramètre. |
| pdf_set_text_rendering() | pdf_set_value() avec "textrendering" comme second paramètre. |
| pdf_set_text_rise() | pdf_set_value() avec "textrise" comme second paramètre. |
| pdf_set_horiz_scaling() | pdf_set_value() avec "horizscaling" comme second paramètre. |
| pdf_set_text_matrix() | Désormais inutile |
| pdf_set_char_spacing() | pdf_set_value() avec "charspacing" comme second paramètre. |
| pdf_set_word_spacing() | pdf_set_value() avec "wordspacing" comme second paramètre. |
| pdf_set_transition() | pdf_set_parameter() avec "transition" comme second paramètre. |
| pdf_open() | pdf_new() suivi d'un appel à pdf_open_file() |
| pdf_set_font() | pdf_findfont() suivi d'un appel à pdf_setfont() |
| pdf_set_duration() | pdf_set_value() avec "duration" comme second paramètre. |
| pdf_open_gif() | pdf_open_image_file() avec "gif" comme second paramètre. |
| pdf_open_jpeg() | pdf_open_image_file() avec "jpeg" comme second paramètre. |
| pdf_open_tiff() | pdf_open_image_file() avec "tiff" comme second paramètre. |
| pdf_open_png() | pdf_open_image_file() avec "png" comme second paramètre. |
| pdf_get_imagewidth() | pdf_get_value() avec "imagewidth" comme second paramètre et l'image comme troisième. |
| pdf_get_imageheight() | pdf_get_value() avec "imageheight" comme second paramètre et l'image comme troisième. |
Conseils pour installer PDFLib 3.x
Depuis la version 3.0 de PDFLib vous pouvez configurer cette librairie avec l'option --enable-shared-pdflib.
Choix de la version de PDFlib
Avec toutes les versions de PHP 4, ultérieure au 9 mars 2000, vous devez utiliser PDFlib 3.0 ou plus récent.
PHP 3, d'un autre coté, ne doit pas être utilisé avec une version plus récente que la 2.01. Depuis la version 1.61 du source php3/functions/pdf.c (php 3.19), il est possible d'utiliser la version PDFlib 3.0 ou plus récent.
Installation des anciennes versions de PDFLib
Si vous utilisez PDFLib 2.01 vérifiez comment votre librairie a été installée. Il doit y avoir un fichier (ou un lien) vers libpdf.so. La version 2.01 ne fait que créer une librairie avec le nom libpdf2.01.so qui ne peut être trouvé lors de la compilation du programme de configuration. Vous devez créer vous même ce lien symbolique de libpdf.so vers libpdf2.01.so.
La version 2.20 de PDFLib a introduit de nombreuses modifications dans ses API, ainsi que le support des polices chinoises et japonaises. Cela impliquent malheureusement des modifications dans le module PDF de PHP 4 (mais pas de PHP 3). Si vous utilisez PDFLib 2.20, gérer correctement votre mémoire. Jusqu'à la version 3.0, PDFLib peut se révéler très instable. Le paramètre d'encodage pdf_set_font() est devenu une chaîne. Cela signifique notamment qu'il faut remplacer 4 par 'winansi'.
Si vous utilisez PDFLib 2.30, pdf_set_text_matrix() a disparu. Elle n'est plus supporté. En général, il est recommandé de consulter les notes de version de la PDFLib pour lister toutes les modifications.
A partir du 9 mars 2000, PHP 4 ne supporte plus que la version 3.0 et plus récente de PDFLib. PHP 3, par contre, ne doit pas être utilisé avec des versions plus récentes que la 2.01.
Exemples
La plus part des fonctions sont simples d'emploi. Le plus difficile est probablement de créer un fichier PDF simple. L'exemple suivant devrait vous mettre sur les rails. Il crée un fichier test.pdf d'une page. La page contient du texte "Times Roman outlined", de taille de 30pt. Le texte est aussi souligné.
Exemple 1. Création d'un document PDF avec PDFLib
Ce script getpdf.php retourne simplement le document PDF. |
La distribution PDFLib contient un exemple plus complexe, qui crée des pages plus élaborées, avec une horloge. Cet exemple a été converti en script PHP (vous retrouverez cet exemple dans le module clibpdf). Il utilise les possibilités de création de fichier en mémoire, sans fichier temporaire.
Exemple 2. Exemple pdfclock issue de la distribution PDFLib
|
- Table des matières
- pdf_add_annotation -- Obsolète: Ajoute une annotation
- pdf_add_bookmark -- Ajoute un signet à la page courante
- pdf_add_launchlink -- Ajoute une annotation éxécutable dans la page courante
- pdf_add_locallink -- Ajoute un lien sur une annotation dans la page courante
- pdf_add_note -- Ajoute une note d'annotation dans la page courante
- pdf_add_outline -- Obsolète: Ajoute un signet dans la page courante
- pdf_add_pdflink -- Ajoute un lien sur un fichier dans la page courante
- pdf_add_thumbnail -- Adds thumbnail for current page
- pdf_add_weblink -- Ajoute un lien hypertexte dans la page courante
- pdf_arc -- Dessine un arc.
- pdf_arcn -- Draws an arc (clockwise)
- pdf_attach_file -- Attache un fichier à la page courante
- pdf_begin_page -- Commence une nouvelle page.
- pdf_begin_pattern -- Starts new pattern
- pdf_begin_template -- Starts new template
- pdf_circle -- Dessine un cercle.
- pdf_clip -- Aligne sur le chemin courant.
- pdf_close_image -- Ferme une image
- pdf_close_pdi_page -- Close the page handle
- pdf_close_pdi -- Close the input PDF document
- pdf_close -- Ferme un document PDF.
- pdf_closepath_fill_stroke -- Remplis, dessine et ferme le chemin courant.
- pdf_closepath_stroke -- Ferme le chemin et dessine le long du chemin.
- pdf_closepath -- Ferme et clos le chemin.
- pdf_concat -- Concatène une matrice avec CTM
- pdf_continue_text -- Affiche un texte sur une nouvelle ligne.
- pdf_curveto -- Dessine une courbe.
- pdf_delete -- Efface un objet PDF
- pdf_end_page -- Termine une page.
- pdf_end_pattern -- Finish pattern
- pdf_end_template -- Finish template
- pdf_endpath -- Ferme le chemin courant
- pdf_fill_stroke -- Remplis et dessine le chemin courant.
- pdf_fill -- Remplis le chemin courant.
- pdf_findfont -- Prépare une police pour utilisation ultérieure
- pdf_get_buffer -- Lit un buffer contenant des données PDF
- pdf_get_font -- Obsolète : gestion de police
- pdf_get_fontname -- Obsolète : gestion de nom de police
- pdf_get_fontsize -- Obsolète : gestion de taille de police
- pdf_get_image_height -- Retourne la hauteur d'une image
- pdf_get_image_width -- Retourne la largeur d'une image
- pdf_get_majorversion -- Returns the major version number of the PDFlib
- pdf_get_minorversion -- Returns the minor version number of the PDFlib
- pdf_get_parameter -- Lit la valeur d'un paramètre PDFLib chaîne
- pdf_get_pdi_parameter -- Get some PDI string parameters
- pdf_get_pdi_value -- Gets some PDI numerical parameters
- pdf_get_value -- Lit la valeur d'un paramètre PDFLib numérique
- pdf_initgraphics -- Resets graphic state
- pdf_lineto -- Dessine une ligne.
- pdf_makespotcolor -- Makes a spotcolor
- pdf_moveto -- Déplace le point courant.
- pdf_new -- Crée un nouvel objet PDF
- pdf_open_CCITT -- Ouvre une nouvelle image à partir de données CCITT
- pdf_open_file -- Ouvre un nouvel objet PDF
- pdf_open_gif -- Obsolète: Ouvre une image GIF
- pdf_open_image_file -- Lit une image depuis un fichier
- pdf_open_image -- Fonction générique pour les images
- pdf_open_jpeg -- Obsolète: Ouvre une image JPEG
- pdf_open_memory_image -- Ouvre une image créée par les fonctions images PHP.
- pdf_open_pdi_page -- Prepare a page
- pdf_open_pdi -- Opens a PDF file
- pdf_open_png -- Obsolète: Ouvre une image PNG
- pdf_open_tiff -- Obsolète: Ouvre une image TIFF
- pdf_open -- Obsolète: Ouvre un nouvel objet PDF
- pdf_place_image -- Place une image dans la page.
- pdf_place_pdi_page -- Places an image on the page
- pdf_rect -- Dessine un rectangle.
- pdf_restore -- Restaure un environnement sauvé.
- pdf_rotate -- Choisi la rotation.
- pdf_save -- Enregistre l'environnement courant.
- pdf_scale -- Modifie l'échelle.
- pdf_set_border_color -- Modifie la couleur des liens et annotations
- pdf_set_border_dash -- Modifie les pointillés des liens et annotations
- pdf_set_border_style -- Modifie le bord des liens et annotations
- pdf_set_char_spacing -- Fixe l'espacement des caractères.
- pdf_set_duration -- Choisi la durée de transition entre deux pages.
- pdf_set_font -- Sélectionne la police et sa taille.
- pdf_set_horiz_scaling -- Fixe l'echelle horizontale du texte.
- pdf_set_info_author -- Fills the author field of the document
- pdf_set_info_creator -- Fills the creator field of the document
- pdf_set_info_keywords -- Fills the keywords field of the document
- pdf_set_info_subject -- Fills the subject field of the document
- pdf_set_info_title -- Fills the title field of the document
- pdf_set_info -- Remplis les entêtes du document
- pdf_set_leading -- Obsolète : Modifie la distance entre les lignes du texte
- pdf_set_parameter -- Modifie certains paramètres.
- pdf_set_text_matrix -- Obsolète: Modifie la transition des pages
- pdf_set_text_pos -- Fixe la position du texte.
- pdf_set_text_rendering -- Détermine le rendu du texte.
- pdf_set_text_rise -- Deprecated: Sets the text rise
- pdf_set_value -- Modifie certains paramètre numériques
- pdf_set_word_spacing -- Fixe l'espacement des mots.
- pdf_setcolor -- Sets fill and stroke color
- pdf_setdash -- Modifie les caractères de remplissage.
- pdf_setflat -- Modifie la platitude (flatness).
- pdf_setfont -- Modifie la police courante
- pdf_setgray_fill -- Modifie la couleur grise comme couleur de remplissage.
- pdf_setgray_stroke -- Modifie la couleur de dessin à un niveau de gris.
- pdf_setgray -- Modifie la couleur grise comme couleur de remplissage et de dessin.
- pdf_setlinecap -- Modifie le paramètre linecap.
- pdf_setlinejoin -- Modifie le paramètre linejoin.
- pdf_setlinewidth -- Modifie la largeur de ligne.
- pdf_setmatrix -- Sets current transformation matrix
- pdf_setmiterlimit -- Modifie la "miter limit".
- pdf_setpolydash -- Modifie les pointillés compliqués
- pdf_setrgbcolor_fill -- Modifie la couleur rgb comme couleur de remplissage.
- pdf_setrgbcolor_stroke -- Modifie la couleur rgb comme couleur de dessin.
- pdf_setrgbcolor -- Modifie la couleur rgb comme couleur de dessin et de remplissage.
- pdf_show_boxed -- Affiche un texte dans un rectangle.
- pdf_show_xy -- Affiche un texte à une position donnée.
- pdf_show -- Affiche un texte à la position courante.
- pdf_skew -- Modifie le système de coordonnées.
- pdf_stringwidth -- Retourne la largeur du texte avec la police courante.
- pdf_stroke -- Dessine le long du chemin.
- pdf_translate -- Modifie l'origine du système de coordonnées.
pdf_add_annotation
pdf_add_bookmark
Description
int pdf_add_bookmark ( resource pdf_object, string text [, int parent [, int open]])pdf_add_bookmark() ajoute un signet sous le père parent, ou un signet général, si parent vaut 0. pdf_add_bookmark() retourne un descripteur de signet, qui peut être utilisé comme père d'un autre signet. Si open vaut 1, les signets fils seront ouverts. Ils seront fermés sinon.
pdf_add_launchlink
Description
int pdf_add_launchlink ( resource pdf_object, double llx, double lly, double urx, double ury, string filename)pdf_add_launchlink() ajoute une annotation exécutable (le fichier de destination peut etre n'importe quel fichier).
pdf_add_locallink
Description
int pdf_add_locallink ( resource pdf_object, double llx, double lly, double urx, double ury, int page, string dest)Add a link annotation to a target within the current PDF file.
pdf_add_note
Description
int pdf_add_note ( resource pdf_object, double llx, double lly, double urx, double ury, string contents, string title, string icon, int open)pdf_add_note() ajoute une note d'annotation. icon peut prendre une des valeurs suivantes : "comment" (commentaire), "insert" (insertion), "note" (note), "paragraph" (paragraphe), "newparagraph" (nouveau paragraphe), "key" (cle), ou "help" (aide).
pdf_add_outline
pdf_add_pdflink
Description
int pdf_add_pdflink ( resource pdf_object, double llx, double lly, double urx, double ury, string filename, int page, string dest)pdf_add_pdflink() ajoute un lien vers un fichier PDF, sous forme d'annotation.
pdf_add_thumbnail
Description
int pdf_add_thumbnail ( int pdf object, int image)Add an existing image as thumbnail for the current page.
pdf_add_weblink
Description
int pdf_add_weblink ( resource pdf_object, double llx, double lly, double urx, double ury, string url)pdf_add_weblink() ajoute un lien hypertexte vers une URL sur le web.
pdf_arc
Description
void pdf_arc ( resource pdf_object, double x-coor, double y-coor, double radius, double start, double end)pdf_arc() dessine un arc de cercle, de centre (x-coor, y-coor) et de rayon radius, en commencant à l'angle start et finissant à l'angle end.
Voir aussi pdf_circle(), pdf_stroke().
pdf_arcn
Description
void pdf_arc ( resource pdf object, float x, float y, float r, float alpha, float beta)Draw a clockwise circular arc from alpha to beta degrees
See also: pdf_arc()
pdf_attach_file
Description
int pdf_attach_file ( resource pdf_object, double llx, double lly, double urx, double ury, string filename, string description, string author, string mimetype, string icon)pdf_attach_file() attache un fichier à la page courante. icon peut prendre l'une des valeurs suivantes : "graph" (image), "paperclip" (texte), "pushpin" (??? NdTraducteur : mailez moi!) ou "tag" (étiquette).
pdf_begin_page
Description
void pdf_begin_page ( resource pdf_object, double width, double height)pdf_begin_page() commence une nouvelle page avec la taille height et la largueur width. Afin de créer un nouveau document valide, vous devez appeler cette fonction et pdf_end_page() au moins une fois.
Voir aussi pdf_end_page().
pdf_begin_pattern
Description
int pdf_begin_pattern ( int pdf object, float width, float height, float xstep, float ystep, int painttype)Starts a new pattern definition and returns a pattern handle. width, and height define the bounding box for the pattern. xstep and ystep give the repeated pattern offsets. painttype=1 means that the pattern has its own colour settings whereas a value of 2 indicates that the current colour is used when the pattern is applied.
pdf_begin_template
Description
void pdf_begin_template ( int pdf object, float width, float height)Start a new template definition.
pdf_circle
Description
void pdf_circle ( resource pdf_object, double x-coor, double y-coor, double radius)pdf_circle() dessine un cercle de centre (x-coor, y-coor), et de rayon radius.
Voir aussi pdf_arc(), pdf_stroke().
pdf_clip
Description
void pdf_clip ( resource pdf_object)pdf_clip() aligne tous les dessins sur le chemin courant.
pdf_close_image
Description
void pdf_close_image ( resource image)pdf_close_image() ferme une image qui a été ouverte par pdf_open_gif() ou pdf_open_jpeg().
Voir aussi pdf_open_jpeg(), pdf_open_gif(), pdf_open_tiff() et pdf_open_memory_image().
pdf_close_pdi_page
Description
void pdf_close_pdi_page ( int pdf object, int pagehandle)Close the page handle, and free all page-related resources.
pdf_close_pdi
Description
void pdf_close_pdi ( int pdf object, int dochandle)Close all open page handles, and close the input PDF document.
pdf_close
Description
void pdf_close ( resource pdf_object)pdf_close() ferme un document PDF.
Voir aussi pdf_open(), fclose().
pdf_closepath_fill_stroke
Description
void pdf_closepath_fill_stroke ( resource pdf_object)pdf_closepath_fill_stroke() clos le chemin, le remplis avec la couleur courante, et dessine le chemin.
Voir aussi pdf_closepath(), pdf_stroke(), pdf_fill(), pdf_setgray_fill(), pdf_setgray(), pdf_setrgbcolor_fill(), pdf_setrgbcolor().
pdf_closepath_stroke
Description
void pdf_closepath_stroke ( resource pdf_object)pdf_closepath_stroke() est une combinaison de pdf_closepath() et pdf_stroke(). Elle ferme aussi le chemin.
Voir aussi pdf_closepath(), pdf_stroke().
pdf_closepath
Description
void pdf_closepath ( resource pdf_object)pdf_closepath() ferme et clos le chemin courant. Cela signifie qu'une ligne va être ajoutée entre le point courant et le premier point du chemin. De nombreuses fonctions telles que pdf_moveto(), pdf_circle() et pdf_rect() démarre un nouveau chemin.
pdf_concat
Description
void pdf_concat ( resource pdf_object, double a, double b, double c, double d, double e, double f)pdf_concat() concatène une matrice avec CTM.
pdf_continue_text
Description
void pdf_continue_text ( resource pdf_object, string text)pdf_continue_text() affiche le texte text sur une nouvelle ligne. La distance entre les lignes peut être choisie avec pdf_set_leading().
Voir aussi pdf_show_xy(), pdf_set_leading() et pdf_set_text_pos().
pdf_curveto
Description
void pdf_curveto ( resource pdf_object, double x1, double y1, double x2, double y2, double x3, double y3)pdf_curveto() dessine une courbe de Bézier entre le point courant et le point (x3, y3) en utilisant les points de contrôle (x1, y1) et (x2, y2).
Voir aussi pdf_moveto(), pdf_lineto() et pdf_stroke().
pdf_delete
Description
void pdf_delete ( resource pdf_object)pdf_delete() efface un objet PDF et libère les ressources.
pdf_end_page
Description
void pdf_end_page ( resource pdf_object)pdf_end_page() termine une page. Une fois qu'une page a été fermée, elle ne peut pas être modifiée.
Voir aussi pdf_begin_page().
pdf_end_pattern
pdf_end_template
pdf_endpath
Description
void pdf_endpath ( resource pdf_object)pdf_endpath() ferme le chemin courant mais ne le clôt pas.
Voir aussi pdf_closepath().
pdf_fill_stroke
Description
void pdf_fill_stroke ( resource pdf_object)pdf_fill_stroke() remplis l'intérieur du chemin courant avec la couleur courante, puis dessine le chemin courant.
Voir aussi pdf_closepath(), pdf_stroke(), pdf_fill(), pdf_setgray_fill(), pdf_setgray(), pdf_setrgbcolor_fill(), pdf_setrgbcolor().
pdf_fill
Description
void pdf_fill ( resource pdf_object)pdf_fill() remplis l'intérieur du chemin courant avec la couleur courante.
Voir aussi pdf_closepath(), pdf_stroke(), pdf_setgray_fill(), pdf_setgray(), pdf_setrgbcolor_fill(), pdf_setrgbcolor().
pdf_findfont
Description
void pdf_findfont ( resource pdf_object, string fontname, string encoding, int embed)pdf_findfont() prépare une police pour utilisation ultérieure avec pdf_setfont(). Les dimensions seront chargées, et lorsque c'est possible, le fichier de police sera vérifié, mais pas utilisé. encoding peut prendre l'une des valeurs suivantes : "builtin" (intégrée), "macroman", "winansi", "host", et nom d'encodage utilisateur, ou encore nom de CMap.
pdf_get_buffer
Description
string pdf_get_buffer ( resource pdf_object)pdf_get_buffer() lit le contenu du buffer pdf_object. Le résultat doit être utilisé par le client avant d'appeler toute autre fonction PDFLib.
pdf_get_font
pdf_get_fontname
pdf_get_fontsize
pdf_get_image_height
Description
string pdf_get_image_height ( resource pdf_object, resource image)pdf_get_image_height() retourne la hauteur de l'image image en pixels.
Voir aussi pdf_open_image_file(), pdf_open_memory_image() et pdf_get_image_width().
pdf_get_image_width
Description
string pdf_get_image_width ( resource pdf_object, resource image)pdf_get_image_width() retourne la largeur de l'image image, en pixels.
Voir aussi pdf_open_image_file(), pdf_open_memory_image() et pdf_get_image_height().
pdf_get_majorversion
pdf_get_minorversion
pdf_get_parameter
Description
string pdf_get_parameter ( resource pdf_object, string key [, double modifier])pdf_get_parameter() lit le contenu de certains paramètres PDFLib, au format chaîne de caractères.
pdf_get_pdi_parameter
Description
string pdf_get_pdi_parameter ( int pdf object, string key, int doc, int page, int index)Get the contents of some PDI document parameter with string type.
pdf_get_pdi_value
Description
string pdf_get_pdi_value ( int pdf object, string key, int doc, int page, int index)Get the contents of some PDI document parameter with numerical type.
pdf_get_value
Description
double pdf_get_value ( resource pdf_object, string key [, double modifier])pdf_get_value() lit le contenu de certains paramètres PDFLib, au format numérique.
pdf_initgraphics
Description
void pdf_initgraphics ( int pdf object)Reset all implicit color and graphics state parameters to their defaults.
pdf_lineto
Description
void pdf_lineto ( resource pdf_object, double x-coor, double y-coor)pdf_lineto() dessine une ligne entre le point courant et le point de coordonnées (x-coor, y-coor).
Voir aussi pdf_moveto(), pdf_curveto() et pdf_stroke().
pdf_makespotcolor
Description
void pdf_makespotcolor ( int pdf object, string spotname)Make a named spot color from the current color.
pdf_moveto
Description
void pdf_moveto ( resource pdf_object, double x-coor, double y-coor)pdf_moveto() déplace le point courant à la position (x-coor, y-coor).
pdf_new
Description
resource pdf_new ( void)pdf_new() crée un nouvel objet PDF, avec gestion des erreurs et de la mémoire par défaut.
pdf_open_CCITT
Description
int pdf_open_ccitt ( resource pdf_object, string filename, int width, int height, int BitReverse, int k, int Blackls1)pdf_open_ccitt() ouvre une image CCITT.
pdf_open_file
Description
int pdf_open_file ( resource pdf_object [, string filename])pdf_open_file() crée un nouvel objet PDF à partir du fichier filename. Si filename est vide, le fichier PDF sera généré en mémoire. Le résultat devrat être lu avec la fonction pdf_get_buffer() function.
L'exemple suivant montre comment créer un fichier PDF en mémoire, et l'envoyer correctement au navigateur.
Exemple 1. Création d'un fichier PDF en mémoire
|
pdf_open_gif
pdf_open_image_file
Description
int pdf_open_image_file ( resource pdf_object, string imagetype, string filename [, string stringparam [, string intparam]])pdf_open_image_file() ouvre une image dans le fichier filename. imagetype peut prendre une des valeurs suivantes : "jpeg", "tiff", "gif", et "png". stringparam peut prendre l'une des valeurs suivantes : "", "mask", "masked", ou "page". intparam peut valoir 0, l'id de l'image du masque appliqué, ou la page.
pdf_open_image
Description
int pdf_open_image ( int PDF-document, string imagetype, string source, string data, long length, int width, int height, int components, int bpc, string params)pdf_open_image() ouvre des fichiers de divers formats d'images. imagetype peut prendre l'une des valeurs suivantes : "jpeg", "ccitt", "raw". source peut prendre l'une des valeurs suivantes : "memory" (mémoire), "fileref" (pointeur de fichier), "url". length ne sert que pour le type "raw"; params ne sert qur pour le type "ccitt".
pdf_open_jpeg
pdf_open_memory_image
(PHP 3>= 3.0.10, PHP 4 )
pdf_open_memory_image -- Ouvre une image créée par les fonctions images PHP.Description
resource pdf_open_memory_image ( resource pdf_object, resource image)pdf_open_memory_image() prend comme argument une image créée avec les fonctions PHP, et la rend disponible pour le document PDF. La fonction retourne un identifiant PDF d'image.
Voir aussi pdf_close_image(), pdf_open_jpeg(), pdf_open_gif() et pdf_place_image().
pdf_open_pdi_page
Description
int pdf_open_pdi_page ( int pdf object, int dochandle, int pagenumber, string pagelabel)Prepare a page for later use with pdf_place_image()
pdf_open_pdi
Description
int pdf_open_pdi ( int pdf object, string filename, string stringparam, int intparam)Open an existing PDF document for later use.
pdf_open_png
pdf_open_tiff
Description
int pdf_open_tiff ( int PDF-document, string filename)Obsolète.
Voir aussi pdf_open_image().
pdf_open
Description
pdf_open() est obsolète. Utilisez pdf_new() puis pdf_open_file().
Voir aussi pdf_new() et pdf_open_file().
pdf_place_image
Description
void pdf_place_image ( resource pdf_object, resource image, double x-coor, double y-coor, double scale)pdf_place_image() place l'image image dans la page courante, à la position (x-coor, x-coor). L'image peut changer d'échelle simultanémement.
pdf_place_pdi_page
Description
void pdf_place_pdi_page ( int pdf object, int page, float x, float y, float sx, float sy)Place a PDF page with the lower left corner at (x, y), and scale it.
pdf_rect
Description
void pdf_rect ( resource pdf_object, double x-coor, double y-coor, double width, double height)pdf_rect() dessine un rectangle un rectangle de coin inférieur gauche de coordonnées (x-coor, y-coor). Sa longueur vaut width. Et sa largeur height.
Voir aussi pdf_stroke().
pdf_restore
Description
void pdf_restore ( resource pdf_object)pdf_restore() restaure un environnement sauvé par pdf_save(). Cela fonctionne de manière identique à la commande Postscript grestore. Très pratique lorsque vous vous faire des translations ou des rotations sans affecter les autres objets.
Voir aussi pdf_save().
pdf_rotate
Description
void pdf_rotate ( resource pdf_object, double angle)pdf_rotate() modifie la rotation de angle degré.
pdf_save
Description
void pdf_save ( resource pdf_object)pdf_save() enregistre l'environnement courant. Le fonctionnement est identique à la commande postscript gsave. Très pratique si vous voulez faire une translation ou une rotation d'un objet, sans affecter les autres. pdf_save() sera toujours suivi d'un pdf_restore().
Voir aussi pdf_restore().
pdf_scale
Description
void pdf_scale ( resource pdf_object, double x-scale, double y-scale)pdf_scale() modifie l'échelle dans les deux directions. L'exemple suivant multiplie l'échelle par 72. La ligne suivante sera dessinée sur un pouce (2.54 cm) de large.
pdf_set_border_color
Description
void pdf_set_border_color ( resource pdf_object, double red, double green, double blue)pdf_set_border_color() modifie la couleur des bords de liens et d'annotation. Les trois composants red, green, blue représentent une couleur RGB (rouge, vert, bleu) et leur valeur doivent être comprise entre 0 et 1.
Voir aussi pdf_set_border_style() et pdf_set_border_dash().
pdf_set_border_dash
Description
void pdf_set_border_dash ( resource pdf_object, double black, double white)pdf_set_border_dash() modifie la longueur des pointillés (si le style de bord d'une annotation est en pointillés). black représente la taille des traits noirs, et white celle des espaces blancs.
Voir aussi pdf_set_border_style() et pdf_set_border_color().
pdf_set_border_style
Description
void pdf_set_border_style ( resource pdf_object, string style, double width)pdf_set_border_style() modifie le style des bords de liens et d'annotation. style peut valoir 'solid' (trait plain) ou 'dashed'( pointillé).
Voir aussi pdf_set_border_color(), pdf_set_border_dash().
pdf_set_char_spacing
Description
void pdf_set_char_spacing ( resource pdf_object, double space)pdf_set_char_spacing() modifie l'espacement des caractères.
Voir aussi pdf_set_word_spacing() et pdf_set_leading().
pdf_set_duration
Description
void pdf_set_duration ( resource pdf_object, double duration)pdf_set_duration() choisi la durée de transition, en secondes, entre deux pages.
pdf_set_font
Description
void pdf_set_font ( resource pdf_object, string font name, double size, string encoding [, int embed])pdf_set_font() sélectionne la police, sa taille et son encodage. Il vous faudra fournir des fichiers Adobe Font Metrics (afm) comme police, dans le dossier de police (par défaut ./fonts). Si vous utilisez PDFLib 0.6, vous devrez fournir des fichiers Adobe Font Métric (afm-files) pour les polices, dans le chemin de police ( par défaut, ./fonts). Si vous utilisez php versin 3 ou une version plus ancienne que la version 2.20 de PDFLib, le quatrième paramètre encoding peut prendre les valeurs suivantes : 0 = builtin, 1 = pdfdoc, 2 = macroman, 3 = macexpert, 4 = winansi. Un encodage plus grand que 4 et inférieur à 0 sera transformé en 'winansi'. 'winansi' est souvent un bon choix. Si vous utilisez PHP version 4 et une version plus ancienne que la version 2.20 de PDFLib le quatrième paramètre encoding est une chaîne : 'builtin', 'pdfdoc', 'macroman', 'macexpert', 'winansi'. Si le dernier paramètre est à 1, la police est intégrée dans le document. Sinon, elle ne le sera pas. Incorporer une police dans un document est un bonne idée si la police n'est pas répandue, ou si vous ne pouvez pas vous assurez que le la personne qui regardera votre document peut accéder à cette police.
Note : pdf_set_font() doit être appelée après pdf_begin_page() pour créer un document PDF valide.
Note : Si vous référencez une police dans un fichier .upr, assurez-vous que le nom du fichier .afm et celui de la police sont bien les mêmes. Sinon, la police sera aggrandie plusieur fois (Merci à Paul Haddon pour cette info).
pdf_set_horiz_scaling
Description
void pdf_set_horiz_scaling ( resource pdf_object, double scale)pdf_set_horiz_scaling() fixe l'échelle horizontale du texte, à scale en pourcentage.
pdf_set_info_author
Description
bool pdf_set_info_author ( int pdfdoc, string author)This function is deprecate, use pdf_set_info() instead.
pdf_set_info_creator
Description
bool pdf_set_info_creator ( int pdfdoc, string creator)This function is deprecate, use pdf_set_info() instead.
pdf_set_info_keywords
Description
bool pdf_set_info_keywords ( int pdfdoc, string keywords)This function is deprecate, use pdf_set_info() instead.
pdf_set_info_subject
Description
bool pdf_set_info_subject ( int pdfdoc, string subject)This function is deprecate, use pdf_set_info() instead.
pdf_set_info_title
Description
bool pdf_set_info_title ( int pdfdoc, string title)This function is deprecate, use pdf_set_info() instead.
pdf_set_info
Description
void pdf_set_info ( resource pdf_object, string fieldname, string value)pdf_set_info() modifie un champs d'entête d'un document PDF. Les valeurs possibles pour fieldname sont : 'Subject' (sujet), 'Title'(titre), 'Creator'(créateur), 'Author'(auteur), 'Keywords'(mots-clé) et un autre nom, défini par l'utilisateur. pdf_set_info() peut être appelée avant la création d'une page.
Exemple 1. Préparer l'entête d'un document PDF
|
Note : pdf_set_info() remplace pdf_set_info_keywords(), pdf_set_info_title(), pdf_set_info_subject(), pdf_set_info_creator() et pdf_set_info_subject().
pdf_set_leading
pdf_set_parameter
Description
void pdf_set_parameter ( resource pdf_object, string name, string value)pdf_set_parameter() modifie certaines valeurs de pdglib. value est de type chaîne.
Voir aussi pdf_get_value(), pdf_set_value() et pdf_get_parameter().
pdf_set_text_matrix
pdf_set_text_pos
Description
void pdf_set_text_pos ( resource pdf_object, double x-coor, double y-coor)pdf_set_text_pos() modifie la position du texte qui sera utilisée lors du prochain pdf_show().
Voir aussi pdf_show() et pdf_show_xy().
pdf_set_text_rendering
Description
void pdf_set_text_rendering ( resource pdf_object, int mode)pdf_set_text_rendering() détermine le rendu du texte. Les valeurs possibles pour mode sont 0=fill text (texte plein), 1=stroke text (???), 2=fill et stroke text (texte plein et stroke), 3=invisible, 4=texte plein, et ajouté au chemin, 5=stroke text, ajouté au chemin, 6=texte plein et stroke, ajouté au chemin, 7=ajouté au chemin.
pdf_set_text_rise
pdf_set_value
Description
void pdf_set_value ( resource pdf_object, string name, double value)pdf_set_value() modifie la valeur (numérique) du paramètre name de PDFLib.
Voir aussi pdf_get_value(), pdf_get_parameter() et pdf_set_parameter().
pdf_set_word_spacing
Description
void pdf_set_word_spacing ( resource pdf_object, double space)pdf_set_word_spacing() modifie l'espacement des mots.
Voir aussi pdf_set_char_spacing() et pdf_set_leading().
pdf_setcolor
Description
void pdf_setcolor ( int pdf object, string type, string colorspace, float c1 [, float c2 [, float c3 [, float c4]]])Set the current color space and color. The parameter type can be "fill", "stroke", or "both" to specify that the color is set for filling, stroking or both filling and stroking. The parameter colorspace can be gray, rgb, cmyk, spot or pattern. The parameters c1, c2, c3 and c4 represent the color components for the color space specified by colorspace. Except as otherwise noted, the color components are floating-point values that range from 0 to 1.
For gray only c1 is used.
For rgb parameters c1, c2, and c3 specify the red, green and blue values respectively.
For cmyk, parameters c1, c2, c3, and c4 are the cyan, magenta, yellow and black values, respectively.
For spot, c1 should be a spot color handles returned by pdf_makespotcolor() and c2 is a tint value between 0 and 1.
For pattern, c1 should be a pattern handle returned by pdf_begin_pattern().
pdf_setdash
Description
void pdf_setdash ( resource pdf_object, double white, double black)pdf_setdash() modifie les caractères de remplissage, et affecte white comme caractère invisible, et black comme caractère de remplissage. Si les deux sont à zéros, une ligne continue est affichée.
pdf_setflat
Description
void pdf_setflat ( resource pdf_object, double value)pdf_setflat() modifie la platitude, et lui affecte la valeur value entre 0 et 100.
pdf_setfont
Description
void pdf_setfont ( resource pdf_object, int font, double size)pdf_setfont() remplace la police courante par font, à la taille size. font est créé par pdf_findfont().
pdf_setgray_fill
Description
void pdf_setgray_fill ( resource pdf_object, double gray value)pdf_setgray_fill() modifie la couleur grise comme couleur de remplissage.
Voir aussi pdf_setrgbcolor_fill().
pdf_setgray_stroke
Description
void pdf_setgray_stroke ( resource pdf_object, double gray value)pdf_setgray_stroke() modifie la couleur de dessin à un niveau de gris.
Voir aussi pdf_setrgbcolor_stroke().
pdf_setgray
(PHP 3>= 3.0.6, PHP 4 )
pdf_setgray -- Modifie la couleur grise comme couleur de remplissage et de dessin.Description
void pdf_setgray ( resource pdf_object, double gray value)pdf_setgray() modifie la couleur grise comme couleur de remplissage et de dessin.
Voir aussi pdf_setrgbcolor_stroke() et pdf_setrgbcolor_fill().
pdf_setlinecap
Description
void pdf_setlinecap ( resource pdf_object, int value)pdf_setlinecap() affecte au paramètre "linecap" la valeur value, entre 0 et 2.
pdf_setlinejoin
Description
void pdf_setlinejoin ( resource pdf_object, long value)pdf_setlinejoin() modifie le paramètre "linejoin", et lui affecte la valeur value, entre 0 et 2.
pdf_setlinewidth
Description
void pdf_setlinewidth ( resource pdf_object, double width)pdf_setlinewidth() affecte à largeur de ligne la valeur width.
pdf_setmatrix
Description
void pdf_setmatrix ( int pdf object, float a, float b, float c, float d, float e, float f)Explicitly set the current transformation matrix.
pdf_setmiterlimit
Description
void pdf_setmiterlimit ( resource pdf_object, double value)pdf_setmiterlimit() modifie la "miter limit" et lui affecte la valeur value, supérieure à 1.
pdf_setpolydash
Description
void pdf_setpolydash ( resource pdf_object, array dasharray)pdf_setpolydash() modifie les pointillés complexes, définit par le tableau dasharray.
pdf_setrgbcolor_fill
Description
void pdf_setrgbcolor_fill ( resource pdf_object, double red value, double green value, double blue value)pdf_setrgbcolor_fill() choisi la couleur RGB comme couleur de remplissage.
Voir aussi pdf_setrgbcolor_fill().
pdf_setrgbcolor_stroke
Description
void pdf_setrgbcolor_stroke ( resource pdf_object, double red value, double green value, double blue value)pdf_setrgbcolor_stroke() choisi la couleur RGB comme couleur de dessin.
Voir aussi pdf_setrgbcolor_fill().
pdf_setrgbcolor
(PHP 3>= 3.0.6, PHP 4 )
pdf_setrgbcolor -- Modifie la couleur rgb comme couleur de dessin et de remplissage.Description
void pdf_setrgbcolor ( resource pdf_object, double red value, double green value, double blue value)pdf_setrgbcolor_stroke() modifie la couleur RGB comme couleur de remplissage.
Voir aussi pdf_setrgbcolor_stroke() et pdf_setrgbcolor_fill().
pdf_show_boxed
Description
int pdf_show_boxed ( resource pdf_object, string text, double x-coor, double y-coor, double width, double height, string mode [, string feature])pdf_show_boxed() affiche le texte text dans un rectangle, dont le coin inférieur gauche est aux coordonnées (x-coor, y-coor). Les dimensions du rectangle sont height et width. Le paramètre mode indique le type de text. Si width et height sont à zéro, le mode mode peut être "left" (gauche), "right" (droite) ou "center" (centré). width ou height sont différents pouvant prendre les valeurs de "justify" (justification) ou "fulljustify" (justification complète).
Si le paramètre feature vaut "blind", le texte n'est pas affiché.
pdf_show_boxed() retourne le nombre de caractères qui n'ont pas pu être traités, car ils ne rentraient pas dans le rectangle.
Voir aussi pdf_show() et pdf_show_xy().
pdf_show_xy
Description
void pdf_show_xy ( resource pdf_object, string text, double x-coor, double y-coor)pdf_show_xy() affiche le texte text à la position donnée par les coordonnées (x-coor, y-coor).
Voir aussi pdf_show() et pdf_show_boxed().
pdf_show
Description
void pdf_show ( resource pdf_object, string text)pdf_show() affiche le texte text avec la position courante, et avec la police courante.
Voir aussi pdf_show_xy(), pdf_show_boxed(), pdf_set_text_pos() et pdf_set_font().
pdf_skew
Description
void pdf_skew ( resource pdf_object, double alpha, double beta)pdf_skew() modifie le système de coordonnées, en faisant une rotation d'angle alpha pour les (x) et d'angle beta pour les (y), en degrés. alpha et beta ne peuvent pas pendre les valeurs de 90 ou 270 degrés.
pdf_stringwidth
Description
double pdf_stringwidth ( resource pdf_object, string text)pdf_stringwidth() retourne la largeur du texte text avec la police courante. Il faut qu'une police ait été choisie auparavant.
Voir aussi pdf_set_font().
pdf_stroke
Description
void pdf_stroke ( resource pdf_object)pdf_stroke() dessine une ligne le long du chemin. Le chemin courant est la somme de toutes les lignes déssinées. Sans cette fonction, la ligne de chemin ne sera pas dessinée.
Voir aussi pdf_closepath(), pdf_closepath_stroke().
pdf_translate
Description
void pdf_translate ( resource pdf_object, double x-coor, double y-coor)pdf_translate() place l'origine du système de coordonnées au point (x-coor, y-coor). L'exemple suivant trace une ligne de (0, 0) à (200, 200) par rapport aux coordonnées initiales. Il faut aussi désigner le point courant après pdf_translate() et avant de commencer à dessiner les objets.
LXXVII. Paiement par Verisign
Cette extension vous permet d'effectuer des transactions avec des cartes de crédits en utilisant les services Verisign Payment Services, anciennement connu sous le nom de Signio (http://www.verisign.com/products/payflow/pro/index.html).
Ces fonctions sont utilisables dès que PHP a été compilé avec l'option --with-pfpro[=DIR]. Vous devez aussi utiliser le SDK approprié sur votre plate-forme : il est disponible l'interface du manager, une fois que vous vous êtes inscrit. Si vous avez l'intention d'utiliser cette extension sur un serveur web SSL ou avec d'autres composants SSL (tels que l'extension CURL et SSL) vous DEVEZ utiliser le SDK beta.
Une fois que vous avez téléchargé le SDK vous devez copier les fichiers depuis le dossier lib de la distribution. Copier le fichier d'en-têtes pfpro.h dans /usr/local/include et la librairie libpfpro.so dans /usr/local/lib.
Lorsque vous utilisez ces fonctions, vous pouvez omettre d'appeler les fonctions pfpro_init() et pfpro_cleanup() : l'extension se chargera de le faire automatiquement. Cependant, elles sont toujours disponibles au cas où vous auriez un grand nombre de transaction à traiter, ou que vous souhaiteriez un contrôle plus fin de la librairie. Vous pouvez effectuer autant de transaction que vous le souhaitez avec pfpro_process() lors d'une connexion.
Ces fonctions ont été ajoutée en PHP 4.0.2.
Note : Ces fonctions ne font que fournir un accès aux services Verisign Payment Services. Assurez-vous bien de lire le "Payflow Pro Developers Guide" pour plus de détails sur les paramètres.
- Table des matières
- pfpro_cleanup -- Eteint la librairie Payflow Pro
- pfpro_init -- Initialise la librairie Payflow Pro
- pfpro_process_raw -- Envoie une transaction brute à Payflow Pro
- pfpro_process -- Effectue une transaction avec Payflow Pro
- pfpro_version -- Lit le numéro de version de Payflow Pro
pfpro_cleanup
Description
void pfpro_cleanup ( void)pfpro_cleanup() sert à terminer proprement une session avec la librairie Payflow Pro library. Elle doit être appelé après toutes les transactions, et avant la fin du script. Cependant, vous pouvez omettre cet appel : dans ce cas, cette fonction sera automatiquement appelée à la fin du script.
Voir aussi pfpro_init().
pfpro_init
Description
void pfpro_init ( void)pfpro_init() initialise la librairie Payflow Pro library. Vous pouvez omettre cet appel : dans ce cas, elle sera appelée automatiquement pfpro_init() avant la première transaction.
Voir aussi pfpro_cleanup().
pfpro_process_raw
Description
string pfpro_process_raw ( string parameters [, string address [, int port [, int timeout [, string proxy_address [, int proxy_port [, string proxy_logon [, string proxy_password]]]]]]])pfpro_process_raw() retourne une chaîne avec une réponse.
pfpro_process_raw() envoie une transaction brute au serveur Payflow Pro. Il est vivement recommandé d'utiliser pfpro_process() à la place, car les règles de codage sont non standard.
Le premier argumentest une chaîne contenant la transaction brute. Tous les autres paramètres sont les mêmes que ceux de pfpro_process(). La valeur de retour est une chaîne contenant la réponse brute.
Note : Lisez attentivement le "Payflow Pro Developers Guide" pour connaître tous les détails des paramètres et leur règle d'encodage. Il est recommandé d'utiliser plutôt pfpro_process().
Exemple 1. Exemple pfpro_process_raw()
|
pfpro_process
Description
array pfpro_process ( array parameters [, string address [, int port [, int timeout [, string proxy_logon [, int proxy_port [, string proxy_logon [, string proxy_password]]]]]]])pfpro_process() retourne un tableau associatif, contenant la réponse à la transaction.
pfpro_process() effectue une transaction avec Payflow Pro. Le premier paramètre est un tableau associatif contenant des paires clés/valeurs, qui seront encodées, puis passées au serveur.
Le second paramètre address indique quel hôte contacter. Il est optionnel. Par défaut, il vaut "test.signio.com" : vous devrez probablement le remplacer par "connect.signio.com" pour effectuer de vraies transactions.
Le troisième paramètre port spécifie le port de connexion. Par défaut, c'est 443, le port SSL standard.
Le quatrième paramètre timeout indique le temps de timeout à utiliser. Par défaut, c'est 30 secondes. Notez que ce timeout ne prend effet que lorsqu'une connexion a été établie avec un serveur : votre script peut potentiellement attendre indéfiniment un événement DNS ou un problème de réseau.
Le cinquième paramètre proxy_address indique le nom du proxy SSL. Le sixième paramètre proxy port indique le port à utiliser sur ce proxy.
Les septième et huitième paramètres, proxy_logon et proxy_password indique le nom de compte et le mot de passe à utiliser sur le proxy.
pfpro_process() retourne un tableau associatif.
Note : Lisez attentivement le "Payflow Pro Developers Guide" pour connaître les détails des autres paramètres.
Exemple 1. Exemple Payflow Pro
|
pfpro_version
LXXVIII. Options PHP et informations
- Table des matières
- assert-options -- Fixe et lit différentes options d'assertions
- assert -- Vérifie si une assertion est fausse
- dl -- Charge une extension PHP à la volée
- extension_loaded -- Détermine si une extension est chargée ou non.
- 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 leur valeur
- get_extension_funcs -- Liste les fonctions d'une extension
- 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 -- Retourne un tableau avec les noms des fichiers qui sont requis et inclus dans un script
- getenv -- Retourne la valeur de la variable 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.
- getmyuid -- Retourne l'UID du propriétaire du script actuel.
- getrusage -- Retourne le niveau d'utilisation des ressources.
- ini_alter -- Change la valeur d'une option de configuration
- ini_get_all -- Lit toutes les valeurs de configuration
- ini_get -- Lit la valeur d'une option de configuration.
- ini_restore -- Restaure la valeur de l'option de configuration
- ini_set -- Change la valeur d'une option de configuration
- php_logo_guid -- Retourne le logo
- php_sapi_name -- Retourne le type d'interface utilisé entre le serveur web et PHP
- php_uname -- Retourne les informations sur le système d'exploitation
- phpcredits -- Imprime les crédits de PHP.
- phpinfo -- Affiche de nombreuses informations sur le PHP.
- phpversion -- Retourne le numéro de la version courante de PHP.
- putenv -- Fixe la valeur d'une variable d'environnement.
- set_magic_quotes_runtime -- Active/désactive l'option magic_quotes_runtime.
- set_time_limit -- Fixe le temps maximum d'exécution d'un script.
- version_compare -- Compare deux versions de PHP
- zend_logo_guid -- Retourne le logo de Zend
- zend_version -- Lit la version courante du moteur Zend.
assert-options
Description
mixed assert_options ( int what [, mixed value])Avec assert_options() vous pouvez modifier les diverses options de la fonction assert(), ou simplement connaître la configuration actuelle.
Tableau 1. options d'assert
| Option | Paramètre d'ini | Valeur par défaut | Description |
|---|---|---|---|
| ASSERT_ACTIVE | assert.active | 1 | active l'évaluation de la fonction assert() |
| 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 | inactive le rapport d'erreur durant l'évaluation d'une assertion |
| ASSERT_CALLBACK | assert_callback | (null) | fonction utilisateur de traitement des assertions fausses |
assert_options() retourne la valeur originale de l'option, ou bien FALSE en cas d'erreur.
assert
Description
int assert ( string|boolean assertion)assert() va vérifier l'assertion assertion et prendre la mesure appropriée si le résultat est FALSE.
Si assertion est donnée sous la forme d'une chaîne, elle sera évaluée comme un code PHP par la fonction assert(). Les avantages de ce type d'assertion sont d'être moins lourd si la vérification d'assertion est désactivée, et le contenu des messages lorsque l'assertion échoue.
Il est recommandé de n'utiliser les assertions que comme outil de débuggage. Vous pouvez les utiliser pour les vérifications d'usage : ces conditions doivent normalement être vraies, et indiquer une erreur de programmation si ce n'est pas le cas. Vous pouvez aussi vérifier la présence de certaines extensions ou limitations du système.
Les assertions ne doivent pas être utilisées pour faire des opérations de vérifications en production, comme par exemple des vérifications de valeur d'argument. En conditions normales, votre code doit être en état de fonctionner si la vérification d'assertion est désactivée.
Le comportement de assert() peut être configuré par assert_options() ou par .ini-settings.
dl
Description
int dl ( string library)dl() charge l'extension PHP library à la volée .
Voir aussi les directives de configuration extension_dir et enable_dl.
extension_loaded
Description
boolean extension_loaded ( string name)extension_loaded() retourne TRUE si l'extension name a été chargée. Vous pouvez voir les différents noms des extensions, en utilisant la fonction phpinfo().
Voir aussi phpinfo().
Note : Cette fonction a été ajoutée dans 3.0.10.
get_cfg_var
Description
string get_cfg_var ( string varname)get_cfg_var() retourne la valeur courante de l'option PHP varname, ou bien FALSE en cas d'erreur.
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é.
get_current_user
Description
string get_current_user ( void)get_current_user() retourne le nom du possesseur du script courant.
Voir aussi getmyuid(), getmypid(), getmyinode() et getlastmod().
get_defined_constants
Description
array get_defined_constants ( void)get_defined_constants() 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().
Par exemple :
afficheraArray
(
[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 get_loaded_extensions().
get_extension_funcs
Description
array get_extension_funcs ( string module_name)get_extension_funcs() retourne le nom des fonctions définies dans le module module_name.
Par exemple, les lignes suivantes :
vont afficher la liste des fonctions disponibles avec les modules xml et gd.Voir aussi get_loaded_extensions().
get_included_files
(PHP 4 )
get_included_files -- Retourne un tableau avec les noms des fichiers qui sont inclus dans un scriptDescription
array get_included_files ( void)get_included_files() retourne un tableau contenant les noms de tous les fichiers qui ont été ajoutés au script avec les fonctions require_once() ou include_once().
L'exemple ci-dessous
Fichiers appelés avec required_once/included_once Array ( [0] => local.php [1] => /full/path/to/inc/global.php [2] => util1.php [3] => util2.php [4] => util3.php [5] => util4.php ) |
Note : En PHP 4.0.1pl2, cette fonction supposait que required_once utilisait l'extension ".php" : les autres extensions ne fonctionnaient pas. Par ailleurs, dans cette version, le tableau retourné était un tableau associatif, et cette fonction n'était pas un alias de get_included_files()
Voir aussi require_once(), include_once() et get_required_files().
get_loaded_extensions
Description
array get_loaded_extensions ( void)get_loaded_extensions() retourne un tableau contenant les noms de tous les modules compilés et chargés sur l'interpreteur PHP courant.
Par exemple, la ligne ci-dessous
affichera la liste suivante :
Array
(
[0] => xml
[1] => wddx
[2] => standard
[3] => session
[4] => posix
[5] => pgsql
[6] => pcre
[7] => gd
[8] => ftp
[9] => db
[10] => Calendar
[11] => bcmath
)
Voir aussi get_extension_funcs().
get_magic_quotes_gpc
(PHP 3>= 3.0.6, PHP 4 )
get_magic_quotes_gpc -- Retourne la configuration actuelle de l'option magic_quotes_gpc.Description
long get_magic_quotes_gpc ( void)get_magic_quotes_gpc() retourne la configuration actuelle de l'option magic_quotes_gpc (0 pour l'option désactivée, 1 pour l'option activée).
Voir aussi get_magic_quotes_runtime() et set_magic_quotes_runtime().
get_magic_quotes_runtime
(PHP 3>= 3.0.6, PHP 4 )
get_magic_quotes_runtime -- Retourne la configuration actuelle de l'option magic_quotes_runtime.Description
long get_magic_quotes_runtime ( void)get_magic_quotes_runtime() retourne la configuration actuelle de l'option magic_quotes_runtime. (0 pour option désactivée, 1 pour option activée).
Voir aussi get_magic_quotes_gpc() et set_magic_quotes_runtime().
get_required_files
(PHP 4 )
get_required_files -- Retourne un tableau avec les noms des fichiers qui sont requis et inclus dans un scriptDescription
array get_required_files ( void)get_required_files() retourne un tableau contenant les noms de tous les fichiers qui ont été chargés dans un script avec la fonction require_once() ou include_once(). Les index de ces tableaux sont les noms des fichiers utilisés dans les fonctions require_once() ou include_once().
Note : En PHP 4.0.1pl2, cette fonction supposait que required_once utilisait l'extension ".php" : les autres extensions ne fonctionnaient pas. Par ailleurs, dans cette version, le tableau retourné était un tableau associatif, et cette fonction n'était pas un alias de get_included_files()
Depuis PHP 4.0.4, cette fonction est un alias de get_included_files()
Voir aussi require_once(), include_once() et get_included_files()
getenv
Description
string getenv ( string varname)getenv() retourne la valeur de la variable d'environnement varname, ou FALSE en cas d'erreur.
Vous pouvez voir une liste complète des variables d'environnement en utilisant la fonction phpinfo(). Vous pouvez trouver la signification de chacune d'entre elles en consultant le site concernant CGI specification (en anglais>, et particulièment la page concernant les variables d'environnement..
Voir aussi putenv().
getlastmod
Description
int getlastmod ( void)getlastmod() retourne la date de dernière modification de la page. La valeur retournée est un marqueur de temps UNIX, utilisable comme paramètre avec la fonction date(). getlastmod() retourne FALSE en cas d'erreur.
Voir aussi date(), getmyuid(), get_current_user(), getmyinode() et getmypid().
getmygid
Description
int getmygid ( void)getmygid() retourne le GID du propriétaire du script, ou FALSE en cas d'erreur.
Voir aussi getmyuid(), getmypid(), get_current_user(), getmyinode() et getlastmod().
getmyinode
Description
int getmyinode ( void)getmyinode() retourne l'inode du script, ou FALSE en cas d'erreur.
Voir aussi getmyuid(), get_current_user(), getmypid() et getlastmod().
Note : getmyinode() est inopérante sur les systèmes Windows.
getmypid
Description
int getmypid ( void)getmypid() retourne le numéro de processus actuel ou FALSE en cas d'erreur.
Il est à noter que si vous utilisez PHP comme module Apache, il n'est pas garanti que deux invocations distinctes de la fonction donnent des résultats différents.
| Avertissement |
Les identifiants de processus ne sont pas uniques, et forment une source d'entropie faible. Nous recommandons de ne pas utiliser les pid pour assurer la sécurité d'un système. |
Voir aussi getmyuid(), get_current_user(), getmyinode() et getlastmod().
getmyuid
Description
int getmyuid ( void)getmyuid() retourne l'UID du propriétaire du script actuel ou FALSE en cas d'erreur.
Voir aussi getmypid(), get_current_user(), getmyinode() et getlastmod().
getrusage
Description
array getrusage ( [int who])getrusage() est une interface à la fonction system getrusage(2). Elle retourne un tableau associatif contenant les informations renvoyées par cet appel système. Si "who is 1", getrusage sera appelé avec le paramètre RUSAGE_CHILDREN.
Toutes les valeurs du tableau sont accessibles en utilisant leur nom dans le tableau.
Exemple 1. Exemple getrusage
|
ini_alter
Description
string ini_alter ( string varname, string newvalue)ini_alter() change la valeur de l'option de configuration varname et lui donne la valeur de newvalue. ini_alter() retourne FALSE en cas d'échec, et la valeur précédente en cas de succès.
Note : ini_alter() est un alias de ini_set()
Voir aussi ini_get(), ini_restore() et ini_set()
ini_get_all
Description
array ini_get_all ( [string extension])ini_get_all() retourne toutes les valeurs de configuration sous la forme d'un tableau associatif. Si le paramètre optionnel extension est fourni, ini_get_all() retourne uniquement les configurations concernant cette extension.
Voir aussi ini_alter(), ini_restore(), ini_get() et ini_set()
ini_get
Description
string ini_get ( string varname)ini_get() retourne la valeur de l'option de configuration varname en cas de succès, et FALSE.
Voir aussi ini_alter(), ini_restore() et ini_set()
ini_restore
Description
string ini_restore ( string varname)ini_restore() restaure la valeur originale de l'option de configuration varname.
Voir aussi ini_alter(), ini_get() et ini_set()
ini_set
Description
string ini_set ( string varname, string newvalue)ini_set() change la valeur de l'option de configuration varname et lui donne la valeur de newvalue. ini_set() retourne FALSE en cas d'échec, et la valeur précédente en cas de succès. 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.
Toutes les options disponibles ne peuvent pas être toutes modifiées avec ini_set(). Ci-dessous, vous trouverez une liste de toutes les options (disponibles en PHP 4.0.5-dev), et si elles peuvent être modifiées.
Tableau 1. Options de configuration
| Nom | Par défaut | Modifiable |
|---|---|---|
| define_syslog_variables | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| highlight.bg | HL_BG_COLOR | PHP_INI_ALL |
| highlight.comment | HL_COMMENT_COLOR | PHP_INI_ALL |
| highlight.default | HL_DEFAULT_COLOR | PHP_INI_ALL |
| highlight.html | HL_HTML_COLOR | PHP_INI_ALL |
| highlight.keyword | HL_KEYWORD_COLOR | PHP_INI_ALL |
| highlight.string | HL_STRING_COLOR | PHP_INI_ALL |
| allow_call_time_pass_reference | "1" | PHP_INI_SYSTEM|PHP_INI_PERDIR |
| asp_tags | "0" | PHP_INI_SYSTEM|PHP_INI_PERDIR |
| display_errors | "1" | PHP_INI_ALL |
| display_startup_errors | "0" | PHP_INI_ALL |
| enable_dl | "1" | PHP_INI_SYSTEM |
| error_append_string | NULL | PHP_INI_ALL |
| error_prepend_string | NULL | PHP_INI_ALL |
| expose_php | "1" | PHP_INI_SYSTEM |
| html_errors | "1" | PHP_INI_SYSTEM |
| ignore_user_abort | "0" | PHP_INI_ALL |
| implicit_flush | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| log_errors | "0" | PHP_INI_ALL |
| magic_quotes_gpc | "1" | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| magic_quotes_runtime | "0" | PHP_INI_ALL |
| magic_quotes_sybase | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| output_buffering | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| output_handler | NULL | PHP_INI_PERDIR|PHP_INI_SYSTEM |
| register_argc_argv | "1" | PHP_INI_ALL |
| register_globals | "1" | PHP_INI_ALL |
| safe_mode | "0" | PHP_INI_SYSTEM |
| short_open_tag | "1" | PHP_INI_SYSTEM|PHP_INI_PERDIR |
| sql.safe_mode | "0" | PHP_INI_SYSTEM |
| track_errors | "0" | PHP_INI_ALL |
| y2k_compliance | "0" | PHP_INI_ALL |
| arg_separator | "&" | PHP_INI_ALL |
| auto_append_file | NULL | PHP_INI_ALL |
| auto_prepend_file | NULL | PHP_INI_ALL |
| doc_root | NULL | PHP_INI_SYSTEM |
| default_charset | SAPI_DEFAULT_CHARSET | PHP_INI_ALL |
| default_mimetype | SAPI_DEFAULT_MIMETYPE | PHP_INI_ALL |
| error_log | NULL | PHP_INI_ALL |
| extension_dir | PHP_EXTENSION_DIR | PHP_INI_SYSTEM |
| gpc_order | "GPC" | PHP_INI_ALL |
| include_path | PHP_INCLUDE_PATH | PHP_INI_ALL |
| max_execution_time | "30" | PHP_INI_ALL |
| open_basedir | NULL | PHP_INI_SYSTEM |
| safe_mode_exec_dir | "1" | PHP_INI_SYSTEM |
| upload_max_filesize | "2M" | PHP_INI_ALL |
| file_uploads | "1" | PHP_INI_ALL |
| post_max_size | "8M" | PHP_INI_SYSTEM |
| upload_tmp_dir | NULL | PHP_INI_SYSTEM |
| user_dir | NULL | PHP_INI_SYSTEM |
| variables_order | NULL | PHP_INI_ALL |
| SMTP | "localhost" | PHP_INI_ALL |
| browscap | NULL | PHP_INI_SYSTEM |
| error_reporting | NULL | PHP_INI_ALL |
| memory_limit | "8M" | PHP_INI_ALL |
| precision | "14" | PHP_INI_ALL |
| sendmail_from | NULL | PHP_INI_ALL |
| sendmail_path | DEFAULT_SENDMAIL_PATH | PHP_INI_SYSTEM |
| disable_functions | "" | PHP_INI_SYSTEM |
| allow_url_fopen | "1" | PHP_INI_ALL |
Tableau 2. Définition des constantes PHP_INI_*
| Constante | Valeur | Signification |
|---|---|---|
| PHP_INI_USER | 1 | La valeur peut être modifiée dans un script |
| PHP_INI_PERDIR | 2 | La valeur peut être modifiée dans le fichier .htaccess |
| PHP_INI_SYSTEM | 4 | La valeur peut être modifiée dans php.ini ou httpd.conf |
| PHP_INI_ALL | 7 | La valeur peut être modifiée n'importe où |
Voir aussi ini_alter(), ini_get() et ini_restore()
php_logo_guid
Description
string php_logo_guid ( void)
Note : Cette fonctionnalité a été ajoutée dans PHP 4 Beta 4.
php_sapi_name
Description
string php_sapi_name ( void)php_sapi_name() retourne une chaîne en minuscule qui décrit le type d'interface utilisé en le serveur web et PHP (Server API, SAPI). En CGI PHP, cette chaîne est "CGI", en mod_php pour Apache, cette chaîne est "apache", etc...
php_uname
Description
string php_uname ( void)php_uname() retourne les informations sur le système d'exploitation sur lequel tourne PHP.
phpcredits
Description
void phpcredits ( int flag)phpcredits() 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. Le paramètre flag indique les informations qui doivent être affichées. Par exemple, pour afficher les crédits généraux, vous pouvez utiliser le code suivant :
Et pour afficher la liste des développeurs et du groupe de documentation dans une page séparée, vous utiliserez Si vous vous sentez l'envie de placer tous les crédits dans votre page, vous pouvez utiliser ceci :<html>
<head>
<title>Ma page de crédits</title>
</head>
<body>
<?php
// Un peu de votre code
phpcredits(CREDITS_ALL + CREDITS_FULLPAGE);
// Un autre peu de votre code
?>
</body>
</html> |
Tableau 1. Paramètre 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 4.0, module SAPI. |
| CREDITS_GROUP | Une liste des développeurs principaux |
| CREDITS_MODULES | Une liste des extensions de PHP, et leurs auteurs |
| CREDITS_SAPI | Cette constante est définie, mais elle n'est toujours pas utilisée sous PHP 4.0.1pl2. |
Voir aussi version_compare(), phpinfo(), phpversion() et php_logo_guid().
phpinfo
Description
int phpinfo ( [int what])phpinfo() affiche de nombreuses informations sur le PHP, concernant sa configuration courante : options de compilation, extensions, version, informations sur le serveur, et environnement (lorsque compilé comme module), environnement PHP, chemins, utilisateur, en-têtes HTTP, et licence GNU Public License.
Les affichages peuvent être personnalisés en passant une ou plusieurs valeurs parmi les suivantes, comme paramètre optionnel what :
INFO_GENERAL
INFO_CREDITS
INFO_CONFIGURATION
INFO_MODULES
INFO_ENVIRONMENT
INFO_VARIABLES
INFO_LICENSE
INFO_ALL
Voir aussi phpversion(), phpcredits() et php_logo_guid()
phpversion
Description
string phpversion ( void)phpversion() retourne le numéro de la version courante de PHP.
Voir aussi phpinfo().
putenv
Description
void putenv ( string setting)putenv() fixe la valeur d'une variable d'environnement. Cette valeur n'existera que durant la vie du script courant, et l'environnement initial sera restauré lorsque le script sera terminé.
Modifier la valeur de certaines variables système peut être un trou de sécurité considérable. La directive de configuration safe_mode_allowed_env_vars contient une liste de préfixes, séparés par des virgules. Lorsque le Safe Mode est actif, l'utilisateur ne peut que modifier les variables qui dont le nom commence par les préfixes fournis par cette directive. Par défaut, les utilisateurs ne peuvent modifier que les variables qui commencent par PHP_ (i.e. PHP_FOO=BAR). Note: si cette directive est vide, PHP autorisera la modification de TOUTES les variables d'environnement!.
La directive de configuration safe_mode_protected_env_vars contient une liste de variables d'environnement, séparées par des virgules. Les utilisateurs ne pourront pas modifier ces variables avec la fonction putenv(). Ces variables seront protégées même si safe_mode_allowed_env_vars permet leur modification.
Voir aussi getenv().
set_magic_quotes_runtime
Description
long set_magic_quotes_runtime ( int new_setting)set_magic_quotes_runtime() active/désactive l'option magic_quotes_runtime. (0 l'option est désactivée, 1 l'option est activée).
Voir aussi get_magic_quotes_gpc() et get_magic_quotes_runtime().
set_time_limit
Description
void set_time_limit ( int seconds)set_time_limit() 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 fichier de configuration. Si la valeur est zéro, il n'y a alors aucune limite imposée.
Lorsqu'elle est appelée, la fonction set_time_limit() remet le compteur de 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.
Notez que set_time_limit() n'a pas d'effet lorsque PHP fonctionne en mode safe mode. Il n'y a pas d'autre solution que de changer de mode, ou de modifier la durée maximale d'exécution dans le fichier de configuration.
version_compare
Description
int version_compare ( string version1, string version2 [, string operator])version_compare() compare les deux versions de PHP standardisée. Cette fonction est pratique pour les programmes qui doivent vérifier la version de PHP qui les fait tourner.
version_compare() retourne -1 si version1 est inférieure à version2, 0 si elles sont égales, et 1 dans le reste des cas.
Si vous spécifiez le troisième argument optionnel operator, vous pouvez tester une relation particulière. Les opérateurs possibles sont <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne. En utilisant cet argument, version_compare() retournera 1 si la relation est vérifiée et 0 sinon.
zend_logo_guid
zend_version
Description
string zend_version ( void )zend_version() retourne une chaîne contenant le numéro de version du moteur d'analyse Zend, pour l'exécutable PHP courant.
Voir aussi phpinfo(), phpcredits(), php_logo_guid() et phpversion().
LXXIX. POSIX
Ce module contient une interface avec les documents au standard IEEE 1003.1 (POSIX.1), qui ne sont pas accessibles autrement. Par exemple, POSIX.1 définit les fonctions open(), read(), write() et close(), qui ont été traditionnellement des fonctions de PHP 3. Certains fonctionnalités spécifiques ne sont pas encore disponibles, bien que ce module tâche de remédier à cette situation.
- Table des matières
- posix_ctermid -- Retourne le chemin du terminal.
- posix_getcwd -- Chemin du dossier courant.
- posix_getegid -- Retourne l'ID effectif du groupe du processus courant.
- posix_geteuid -- Retourne l'UID effectif de l'utilisateur du processus courant.
- posix_getgid -- Retourne l'UID du groupe du processus courant.
- posix_getgrgid -- Retourne des informations sur un groupe.
- posix_getgrnam -- Retourne des informations sur un groupe.
- posix_getgroups -- Retourne les identifiants du groupe du processus courant.
- posix_getlogin -- Retourne le nom de login.
- posix_getpgid -- Retourne l'id du groupe de processus.
- posix_getpgrp -- Retourne l'identifiant du groupe de processus.
- posix_getpid -- Retourne l'identifiant du processus courant.
- posix_getppid -- Retourne l'identifiant du processus parent.
- posix_getpwnam -- Retourne des informations sur un utilisateur.
- posix_getpwuid -- Retourne des informations sur un utilisateur.
- posix_getrlimit -- Retourne les limites système.
- posix_getsid -- Retourne le sid du processus.
- posix_getuid -- Retourne l'ID de l'utilisateur du processus courant.
- posix_isatty -- Détermine si un pointeur de fichier est un terminal interactif.
- posix_kill -- Envoie un signal à un processus.
- posix_mkfifo -- Crée un fichier fifo (first in, first out) (un pipe nommé).
- posix_setegid -- Set the effective GID of the current process
- posix_seteuid -- Set the effective UID of the current process
- posix_setgid -- Fixe le GID effective du processus courant.
- posix_setpgid -- Fixe l'identifiant de group de processus.
- posix_setsid -- Fait du processus courant un chef de session.
- posix_setuid -- Fixe l'UID effective du processus courant.
- posix_times -- Utilisation des ressources.
- posix_ttyname -- Retourne le nom de device du terminal.
- posix_uname -- Retourne le nom du système.
posix_ctermid
posix_getcwd
posix_getegid
Description
int posix_getegid ( void )posix_getegid() retourne l'ID effectif du groupe du processus courant. Reportez-vous à posix_getgrgid() pour transformer cette information en nom de groupe.
posix_geteuid
(PHP 3>= 3.0.10, PHP 4 )
posix_geteuid -- Retourne l'UID effectif de l'utilisateur du processus courant.Description
int posix_geteuid ( void )posix_geteuid() retourne l'UID effectif de l'utilisateur du processus courant. Reportez-vous à posix_getpwuid() pour obtenir le nom d'utilisateur.
posix_getgid
Description
int posix_getgid ( void )posix_getgid() retourne l'UID du groupe du processus courant. Reportez-vous à posix_getgrgid() pour accéder au nom du groupe.
posix_getgrgid
posix_getgrnam
posix_getgroups
(PHP 3>= 3.0.10, PHP 4 )
posix_getgroups -- Retourne les identifiants du groupe du processus courant.Description
array posix_getgroups ( void )posix_getgroups() retourne un tableau contenant les identifiants du groupe du processus courant. Reportez-vous à posix_getgrgid() pour pouvoir utiliser ces id.
posix_getlogin
Description
string posix_getlogin ( void )posix_getlogin() retourne le nom de login de l'utilisateur qui possède le processus courant. Reportez-vous à posix_getpwnam() pour obtenir plus d'informations sur cet utilisateur.
posix_getpgid
Description
int posix_getpgid ( int pid)posix_getpgid() retourne l'id du groupe de processus pour le processus pid.
Ceci n'est pas une fonction POSIX, mais elle est répandue sur les systèmes BSD et System V. Si votre système ne supporte pas cette fonction, la fonction PHP retournera toujours FALSE.
posix_getpgrp
Description
int posix_getpgrp ( void )posix_getpgrp() retourne l'identifiant du groupe de processus du processus courant. Reportez-vous à POSIX.1 et à getpgrp(2) dans le manuel de votre système POSIX pour plus d'informations sur les groupes de processus.
posix_getpid
posix_getppid
Description
int posix_getppid ( void )posix_getppid() retourne l'identifiant du processus parent du processus courant.
posix_getpwnam
Description
array posix_getpwnam ( string username)posix_getpwnam() retourne un tableau associatif qui contient des informations à propos d'un utilisateur, identifié par son nom, passé en paramètre username.
Les éléments du tableau sont :
Tableau 1. Le tableau descriptif d'un utilisateur
| Elément | Déscription |
|---|---|
| name | Le nom contient le nom de l'utilisateur. Généralement, c'est un nom court, de moins de 16 caractères, mais ce n'est pas son nom réel et complet. Cette valeur devrait correspondre au paramètre username, et donc, il est redondant. |
| passwd | Contient le mot de passe de l'utilisateur, encrypté. Souvent, dans les systèmes utilisant les mots de passe "fantômes", un astérisque est retourné. |
| uid | L'UID de l'utilisateur. |
| gid | L'ID du groupe de l'utilisateur. Utilisez la fonction posix_getgrgid() pour connaître le nom du groupe, et ses membres. |
| gecos | GECOS est un terme obsolète qui fait référence aux données de finger, sur un système Honeywell. Le champs, cependant, a survécu, et son contenu a été formalisé par POSIX. Le champs contient une liste, séparée par des virgules, qui contient le nom complet de l'utilisateur, son téléphone professionnel, son numéro de téléphone bureau, et son numéro de téléphone personnel. Sur la plupart des sytèmes, seul le nom est disponible. |
| dir | Cet élément contient le chemin absolu jusqu'au dossier racine de l'utilisateur. |
| shell | Cet élément contient le chemin absolu jusqu'au dossier d'éxécution du shell de l'utilisateur. |
posix_getpwuid
Description
array posix_getpwuid ( int uid)posix_getpwuid() retourne un tableau associatif contenant des informations sur un utilisateur repéré par son UID, passé dans le paramètre uid.
Les éléments du tableau sont :
Tableau 1. Le tableau de description d'un utilisateur
| Elément | Description |
|---|---|
| name | Le nom contient le nom de l'utilisateur. Généralement, c'est un nom court, de moins de 16 caractères, mais ce n'est pas son nom réel et complet. |
| passwd | Contient le mot de passe de l'utilisateur, encrypté. Souvent, dans les systèmes utilisant les mots de passes "fantômes", un astérisque est retourné. |
| uid | Cette valeur devrait correspondre au paramètre uid, et donc, il est redondant. |
| gid | L'ID du groupe de l'utilisateur. Utilisez la fonction posix_getgrgid() pour connaître le nom du groupe, et ses membres. |
| gecos | GECOS est un terme obsolète qui fait référence aux données de finger, sur un système Honeywell. Le champs, cependant, a survécu, et son contenu a été formalisé par POSIX. Le champs contient une liste, séparée par des virgules, qui contient le nom complet de l'utilisateur, son téléphone professionne, son numéro de bureau, et son numéro de téléphone personnel. Sur la plupart des sytèmes, seul le nom est disponible. |
| dir | Cet élément contient le chemin absolu jusqu'au dossier racine de l'utilisateur. |
| shell | Cet élément contient le chemin absolu jusqu'au dossier d'éxécution du shell de l'utilisateur. |
posix_getrlimit
posix_getsid
Description
int posix_getsid ( int pid)posix_getsid() retourne le sid du processus pid. Si pid est à 0, le sid retourné sera celui du processus courant.
Ceci n'est pas une fonction POSIX, mais elle est répandue sur les systèmes BSD et System V. Si votre système ne supporte pas cette fonction, la fonction PHP retournera toujours FALSE.
posix_getuid
Description
int posix_getuid ( void )posix_getuid() retourne l'ID numérique de l'utilisateur du processus courant. Reportez-vous à posix_getpwuid() pour accéder au nom d'utilisateur.
posix_isatty
(PHP 3>= 3.0.13, PHP 4 )
posix_isatty -- Détermine si un pointeur de fichier est un terminal interactif.posix_kill
Description
boolean posix_kill ( int pid, int sig)posix_kill() envoie le signal sig au processus pid. posix_kill() retourne FALSE, s'il n'a pas pu envoyer le signal, et TRUE sinon.
Reportez-vous à la page de manuel de kill(2) de votre système POSIX, qui contient plus de détails sur les identifiants négatifs de processus, les pid spéciaux 0 et -1, et le signal numéro 0.
posix_mkfifo
posix_setegid
Description
bool posix_setegid ( int gid)Set the effective group ID of the current process. This is a privileged function and you need appropriate privileges (usually root) on your system to be able to perform this function.
Returns TRUE on success, FALSE otherwise.
posix_seteuid
Description
bool posix_seteuid ( int uid)Set the real user ID of the current process. This is a privileged function and you need appropriate privileges (usually root) on your system to be able to perform this function.
Returns TRUE on success, FALSE otherwise. See also posix_setgid().
posix_setgid
Description
boolean posix_setgid ( int gid)posix_setgid() fixe le GID effective du processus courant. Reportez-vous à posix_getgrgid() pour transformer cette information en nom de groupe. L'ordre approprié est d'abord posix_setgid(), puis posix_setuid().
posix_setgid() retourne TRUE en cas de succès, FALSE sinon.
posix_setpgid
Description
int posix_setpgid ( int pid, int pgid)posix_setpgid() ajoute le processus pid au groupe d'id pgid. Reportez-vous à POSIX.1 et setsid(2) dans le manuel de votre système POSIX pour plus d'informations sur le contrôle de tâche. posix_setpgid() retourne TRUE en cas de succès, et FALSE sinon.
posix_setsid
Description
int posix_setsid ( void )posix_setsid() fait du processus courant un chef de session. Reportez-vous à POSIX.1 et setsid(2) dans le manuel de votre système POSIX pour plus d'informations sur le contrôle de tâche. posix_setsid() retourne un identifiant de session.
posix_setuid
Description
boolean posix_setuid ( int uid)posix_setuid() fixe l'UID effective de l'utilisateur du processus courant. Vous devez avoir les privilèges nécessaires (traditionnellement ceux du root) sur votre système pour faire ceci.
posix_setuid() retourne TRUE en cas de succès, FALSE sinon. Voir aussi posix_setgid().
posix_times
Description
array posix_times ( void )posix_times() retourne un tableau avec les informations sur l'utilisation du CPU. Les indices sont :
ticks - nombre de ticks depuis le dernier démarrage
utime - temps utilisateur utilisé par le processus courant.
stime - temps système utilisé par le processus courant.
cutime - temps utilisateur utilisé par le processus courant et ses enfants.
cstime - temps système utilisé par le processus courant et ses enfants.
posix_ttyname
posix_uname
Description
array posix_uname ( void )posix_uname() retourne un tableau associatif avec des informations sur le système. Les indices du tableau sont :
sysname - nom du système d'exploitation (e.g. Linux)
nodename - nom du système (e.g. valiant)
release - édition du système d'exploitation (e.g. 2.2.10)
version - version du système d'exploitation (e.g. #4 Tue Jul 20 17:01:36 MEST 1999)
machine - architecture système (e.g. i586)
Posix impose que vous n'ayez pas d'a priori sur le format des chaînes, c'est-à-dire que vous ne devez pas vous attendre à avoir forcément 3 chiffres pour la version, par exemple.
LXXX. PostgreSQL
Postgres, initialement développé au département de Science informatique, à UC Berkeley, mis en place la majorité des concepts des bases relationnelles, actuellement disponibles sur le marché. PostgreSQL accepte le langage SQL92/SQL3, assure l'intégrité transactionnelle, et l'extension de type. PostgreSQL est une évolution du code originale de Berkeley : il est Open Source et dans le domaine public.
PostgreSQL est disponible sans frais. La version actuelle est disponible à (en anglais) : www.PostgreSQL.org.
Depuis la version 6.3 (03/02/1998) PostgreSQL utilise les sockets UNIX, et une table est dédiée à ces nouvelles capacités. La socket est située dans le dossier /tmp/.s.PGSQL.5432. Cette option peut être activée avec '-i' passé au postmaster et cela s'interprète: "écoute sur les sockets TCP/IP et sur les sockets Unix".
Tableau 1. Postmaster et PHP
| Postmaster | PHP | Statut |
|---|---|---|
| postmaster & | pg_connect("dbname=MonDbName"); | OK |
| postmaster -i & | pg_connect("dbname=MonDbName"); | OK |
| postmaster & | pg_connect("host=localhost dbname=MonDbName"); | Unable to connect to PostgreSQL server: connectDB() failed: Impossible de se connecter au serveur PostgreSQL: connectDB() a échoué. Est ce que le postmaster fonctionne, et accepte les TCP/IP (option -i) sur le port '5432'? |
| postmaster -i & | pg_connect("host=localhost dbname=MonDbName"); | OK |
Il est possible de se connecter avec la commande suivante : $conn = pg_Connect("host=monHote port=monPort tty=monTTY options=myOptions dbname=myDB user=myUser password=myPassword");
L'ancienne syntaxe : $conn = pg_connect("host", "port", "options", "tty", "dbname") est obsolète.
Pour utiliser l'interface des grands objets (large object (lo) interface), il est nécessaire de les placer dans un bloc de transaction. Un bloc de transaction commence avec begin et si la transaction se termine avec un commit et end. Si la transaction échoue, elle doit être conclue par un abort et rollback.
Exemple 1. Utilisation des objets de grande taille (Large Objects)
|
- Table des matières
- pg_affected_rows -- Returns number of affected records(tuples)
- pg_cancel_query -- Cancel async query
- pg_client_encoding -- Lit l'encodage du client
- pg_Close -- Termine une connexion PostgreSQL.
- pg_connect -- Ouvre une connexion.
- pg_connection_busy -- Get connection is busy or not
- pg_connection_reset -- Reset connection (reconnect)
- pg_connection_status -- Get connection status
- pg_convert -- Convert associative array value into suitable for SQL statement.
- pg_copy_from -- Insert records into a table from an array
- pg_copy_to -- Copy a table to an array
- pg_DBname -- Nom de la base de données.
- pg_delete -- Delete records.
- pg_end_copy -- Synchronise avec le serveur PostgreSQL
- pg_escape_bytea -- Escape binary for bytea type
- pg_escape_string -- Escape string for text/char type
- pg_Fetch_Array -- Lit une ligne dans un tableau.
- pg_Fetch_Object -- Lit une ligne dans un objet.
- pg_fetch_result -- Returns values from a result resource
- pg_Fetch_Row -- Lit une ligne dans un tableau.
- pg_field_is_null -- Test if a field is NULL
- pg_field_name -- Returns the name of a field
- pg_field_num -- Returns the field number of the named field
- pg_field_prtlen -- Returns the printed length
- pg_field_size -- Returns the internal storage size of the named field
- pg_field_type -- Returns the type name for the corresponding field number
- pg_free_result -- Free result memory
- pg_get_result -- Get asynchronous query result
- pg_Host -- Retourne le nom d'hôte.
- pg_insert -- Insert array into table.
- pg_last_error -- Get the last error message string of a connection
- pg_last_notice -- Returns the last notice message from PostgreSQL server
- pg_last_oid -- Returns the last object's oid
- pg_lo_close -- Close a large object
- pg_lo_create -- Create a large object
- pg_lo_export -- Export a large object to file
- pg_lo_import -- Import a large object from file
- pg_lo_open -- Open a large object
- pg_lo_read_all -- Read a entire large object and send straight to browser
- pg_lo_read -- Read a large object
- pg_lo_seek -- Seeks position of large object
- pg_lo_tell -- Returns current position of large object
- pg_lo_unlink -- Delete a large object
- pg_lo_write -- Write a large object
- pg_metadata -- Get metadata for table.
- pg_num_fields -- Returns the number of fields
- pg_num_rows -- Returns the number of rows
- pg_Options -- Retourne les options.
- pg_pConnect -- Etablit une connexion persistante.
- pg_Port -- Retourne le numéro de port.
- pg_put_line -- Envoie une chaîne au serveur PostgreSQL
- pg_query -- Execute a query
- pg_result_error -- Get error message associated with result
- pg_result_status -- Get status of query result
- pg_select -- Select records.
- pg_send_query -- Send asynchronous query
- pg_set_client_encoding -- Choisit l'encodage du client
- pg_trace -- Active le suivi d'une connexion PostgreSQL
- pg_tty -- Retourne le nom de tty.
- pg_untrace -- Termine le suivi d'une connexion PostgreSQL
- pg_update -- Update table.
pg_affected_rows
Description
int pg_affected_rows ( resource result)pg_affected_rows() returns the number of tuples (instances/records/rows) affected by INSERT, UPDATE, and DELETE queries executed by pg_query(). If no tuple is affected by this function, it will return 0.
Note : This function used to be called pg_cmdtuples().
See also pg_query() and pg_num_rows().
pg_cancel_query
Description
bool pg_cancel_query ( resource connection)pg_cancel_query() cancel asynchronous query sent by pg_send_query(). You cannot cancel query executed by pg_query().
See also pg_send_query() and pg_connection_busy()
pg_client_encoding
Description
string pg_client_encoding ( [resource connection])pg_client_encoding() retourne l'encodage du client. Elle retourne une des valeurs suivantes : SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, WIN1250.
Note : Cette fonction requiert PHP-4.0.2 ou plus récent et PostgreSQL-7.0 ou plus récent.
Jadis, pg_client_encoding() s'appelait pg_clientencoding().
Voir aussi pg_set_client_encoding().
pg_Close
Description
boolean pg_close ( resource connection)pg_close() retourne FALSE si l'index de connexion n'est pas valable, et TRUE sinon. 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.
pg_close() ne ferme pas les connexions persistantes ouvertes avec pg_pconnect().
pg_connect
Description
resource pg_connect ( string host, string port, string dbname)resource pg_connect ( string host, string port, string options, string dbname)
resource pg_connect ( string host, string port, string options, string tty, string dbname)
resource pg_connect ( string conn_string)
conn_string retourne un index de connexion en cas de succès, et FALSE sinon. Ouvre une connexion à un serveur PostgreSQL. Les arguments doivent être placé entre guillemets.
Exemple 1. Exemples avec pg_connect()
|
pg_connect() retourne un index de connexion qui sera nécessaire aux autres fonctions PostgreSQL. Vous pouvez ouvrir plusieurs connexions simultanées.
Si un deuxième appel à pg_connect() est fait avec les mêmes arguments, aucune nouvelle connexion ne sera établie, mais la connexion précédente sera retournée.
L'ancienne syntaxe $conn = pg_connect("host", "port", "options", "tty", "dbname") est obsolète.
Voir aussi pg_pconnect().
pg_connection_busy
Description
bool pg_connection_busy ( resource connection)pg_connection_busy() returns TRUE if the connection is busy. If it is busy, a previous query is still executing. If pg_get_result() is called, it will be blocked.
See also pg_connection_status() and pg_get_result()
pg_connection_reset
Description
bool pg_connection_reset ( resource connection)pg_connection_reset() resets the connection. It is useful for error recovery. Retourne TRUE en cas de succès, FALSE en cas d'échec.
See also pg_connect(), pg_pconnect() and pg_connection_status()
pg_connection_status
Description
int pg_connection_status ( resource connection)pg_connection_status() returns a connection status. Possible statuses are PGSQL_CONNECTION_OK and PGSQL_CONNECTION_BAD.
See also pg_connection_busy().
pg_convert
Description
array pg_convert ( resource connection, string table_name, array assoc_array [, int options])pg_convert() check and convert assoc_array suitable for SQL statement.
Note : This function is experimental.
See also pg_metadata()
pg_copy_from
Description
int pg_copy_from ( int connection, string table_name, array rows [, string delimiter [, string null_as]])pg_copy_from() insert records into a table from rows. It issues COPY command internally to insert records. Retourne TRUE en cas de succès, FALSE en cas d'échec.
See also pg_copy_to()
pg_copy_to
Description
int pg_copy_to ( int connection, string table_name [, string delimiter [, string null_as]])pg_copy_to() copies a table to an array. The resulting array is returned. It returns FALSE on failure.
See also pg_copy_from()
pg_DBname
Description
string pg_dbname ( resource connection)pg_dbname() retourne le nom de la base de données PostgreSQL associée à l'index de connexion connection, ou FALSE si connection n'est pas valide.
pg_delete
Description
long pg_delete ( resource connection, string table_name, array assoc_array [, int options])pg_delete() deletes record condition specified by assoc_array which has field=>value. If option is specified, pg_convert() is applied to assoc_array with specified option.
Note : This function is experimental.
See also pg_convert()
pg_end_copy
Description
boolean pg_end_copy ( [resource connection])pg_end_copy() synchronise le client PostgreSQL (ici PHP) avec le serveur, après une opération de copie. Il faut utiliser cette fonction, sous peine de recevoir une erreur "out of sync" (désynchronisé). pg_end_copy() retourne TRUE en cas de succès, et FALSE sinon.
Pour plus de détails et un exemple voyez : pg_put_line().
pg_escape_bytea
Description
string pg_escape_bytea ( string data)pg_escape_bytea() escapes string for bytea datatype. It returns escaped string.
Note : When you SELECT bytea type, PostgreSQL returns octal byte value prefixed by \ (e.g. \032). Users are supposed to convert back to binary format by yourself.
This function requires PostgreSQL 7.2 or later. With PostgreSQL 7.2.0 and 7.2.1, bytea type must be casted when you enable multi-byte support. i.e. INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 or later does not need cast. Exception is when client and backend character encoding does not match, there may be multi-byte stream error. User must cast to bytea to avoid this error.
Newer PostgreSQL will support unescape function. Support for built-in unescape function will be added when it's available.
See also pg_escape_string()
pg_escape_string
Description
string pg_escape_string ( string data)pg_escape_string() escapes string for text/char datatype. It returns escaped string for PostgreSQL. Use of this functon is recommended instead of addslashes().
Note : This function requires PostgreSQL 7.2 or later.
See also pg_escape_bytea()
pg_Fetch_Array
Description
array pg_fetch_array ( resource result, int row [, int result_type])pg_fetch_array() retourne un tableau qui contient à la ligne demandée, dans le résultat identifiée par result, et FALSE , s'il ne reste plus de lignes.
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.
L'argument optionnel result_type de pg_fetch_array() est une constante, qui peut prendre les valeurs suivantes : PGSQL_ASSOC, PGSQL_NUM, et PGSQL_BOTH.
Note : result_type a été ajoutée en PHP 4.0.
Il est important de noter que pg_fetch_array() n'est pas significativement plus lent que pg_fetch_row(), tandis qu'elle fournit un confort d'utilisation notable.
Pour plus de détails, reportez-vous à pg_fetch_row().
Exemple 1. PostgreSQL fetch array
|
pg_Fetch_Object
Description
object pg_fetch_object ( resource result, int row [, int result_type])pg_fetch_object() retourne un objet dont les membres sont les champs de la ligne demandée, ou FALSE , si il n'y a plus de lignes.
pg_fetch_object() est similaire à pg_fetch_array(), avec une différence majeure : c'est un objet qui est retourné, au lieu d'un tableau. Par conséquent, cela signifie que vous ne pouvez accéder aux membres qu'avec leur nom, et non plus leur offset (les nombres ne sont pas autorisés comme nom de membre).
L'argument optionnel result_type de result_type est une constante qui peut prendre les valeurs suivantes : PGSQL_ASSOC, PGSQL_NUM, et PGSQL_BOTH.
Note : result_type a été ajouté dans PHP 4.0.
Au niveau vitesse, pg_fetch_object() est aussi rapide que pg_fetch_row() et presque aussi rapide que pg_fetch_row() (la différence est non significative).
Voir aussi pg_fetch_array() et pg_fetch_row().
Exemple 1. Lecture d'un objet Postgres
|
pg_fetch_result
Description
mixed pg_fetch_result ( resource result, int row, mixed field)pg_fetch_result() returns values from a result resource returned by pg_query(). row is integer. field is field name(string) or field index (integer). The row and field specify what cell in the table of results to return. Row numbering starts from 0. Instead of naming the field, you may use the field index as an unquoted number. Field indices start from 0.
PostgreSQL has many built in types and only the basic ones are directly supported here. All forms of integer, boolean and void types are returned as integer values. All forms of float, and real types are returned as float values. All other types, including arrays are returned as strings formatted in the same default PostgreSQL manner that you would see in the psql program.
pg_Fetch_Row
Description
array pg_fetch_row ( resource result, int row)pg_fetch_row() retourne un tableau qui contient les données de la ligne demandée, ou FALSE , si il ne reste plus de lignes.
pg_fetch_row() lit une ligne dans le résultat associé à l'index result. La ligne est retournée sous la forme d'un tableau. La ligne est retournée sous la forme d'un tableau, qui commence à l'index 0.
Les appels ultérieurs à pg_fetch_row() retourneront la ligne d'après, ou bien FALSE, lorsqu'il n'y aura plus de lignes.
Voir aussi pg_fetch_array(), pg_fetch_object() et pg_result().
Exemple 1. Postgres retourne une ligne
|
pg_field_is_null
Description
int pg_field_is_null ( resource result, int row, mixed field)pg_field_is_null() test if a field is NULL or not. It returns 1 if the field in the given row is NULL. It returns 0 if the field in the given row is NOT NULL. Field can be specified as column index (number) or fieldname (string). Row numbering starts at 0.
Note : This function used to be called pg_fieldisnull().
pg_field_name
Description
string pg_field_name ( resource result, int field_number)pg_field_name() returns the name of the field occupying the given field_number in the given PostgreSQL result resource. Field numbering starts from 0.
Note : This function used to be called pg_fieldname().
See also pg_field_num().
pg_field_num
Description
int pg_field_num ( resource result, string field_name)pg_field_num() will return the number of the column (field) slot that corresponds to the field_name in the given PostgreSQL result resource. Field numbering starts at 0. This function will return -1 on error.
Note : This function used to be called pg_fieldnum().
See also pg_field_name().
pg_field_prtlen
Description
int pg_field_prtlen ( resource result, int row_number, string field_name)pg_field_prtlen() returns the actual printed length (number of characters) of a specific value in a PostgreSQL result. Row numbering starts at 0. This function will return -1 on an error.
Note : This function used to be called pg_field_prtlen().
See also pg_field_size().
pg_field_size
Description
int pg_field_size ( resource result, int field_number)pg_field_size() returns the internal storage size (in bytes) of the field number in the given PostgreSQL result. Field numbering starts at 0. A field size of -1 indicates a variable length field. This function will return FALSE on error.
Note : This function used to be called pg_fieldsize().
See also pg_field_len() and pg_field_type().
pg_field_type
Description
string pg_field_type ( resource result, int field_number)pg_field_type() returns a string containing the type name of the given field_number in the given PostgreSQL result resource. Field numbering starts at 0.
Note : This function used to be called pg_fieldtype().
See also pg_field_len() and pg_field_name().
pg_free_result
Description
bool pg_free_result ( resource result)pg_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script is finished. But, if you are sure you are not going to need the result data anymore in a script, you may call pg_free_result() with the result resource as an argument and the associated result memory will be freed. It returns true on success and false if an error occurs.
Note : This function used to be called pg_freeresult().
See also pg_query().
pg_get_result
Description
resource pg_get_result ( [resource connection])pg_get_result() get result resource from async query executed by pg_send_query(). pg_send_query() can send multiple queries to PostgreSQL server and pg_get_result() is used to get query result one by one. It returns result resource. If there is no more results, it returns FALSE.
pg_Host
Description
string pg_host ( resource connection_id)pg_host() retourne le nom d'hôte associé à l'index de connexion PostgreSQL.
pg_insert
Description
bool pg_insert ( resource connection, string table_name, array assoc_array [, int options])pg_insert() inserts assoc_array which has field=>value into table specified as table_name. If options is specified, pg_convert() is applied to assoc_array with specified option.
Note : This function is experimental.
See also pg_convert()
pg_last_error
Description
string pg_last_error ( resource connection)pg_last_error() returns the last error message for given connection.
Error messages may be overwritten by internal PostgreSQL(libpq) function calls. It may not return appropriate error message, if multiple errors are occured inside a PostgreSQL module function.
Use pg_result_error(), pg_result_status() and pg_connection_status() for better error handling.
Note : This function used to be called pg_errormessage().
See also pg_result_error().
pg_last_notice
Description
string pg_last_notice ( resource connection)pg_last_notice() returns the last notice message from the PostgreSQL server specified by connection. The PostgreSQL server sends notice messages in several cases, e.g. if the transactions can't be continued. With pg_last_notice(), you can avoid issuing useless queries, by checking whether the notice is related to the transaction or not.
| Avertissement |
This function is EXPERIMENTAL and it is not fully implemented yet. pg_last_notice() was added in PHP 4.0.6. However, PHP 4.0.6 has problem with notice message handling. Use of the PostgreSQL module with PHP 4.0.6 is not recommended even if you are not using pg_last_notice(). This function is fully implemented in PHP 4.3.0. PHP earlier than PHP 4.3.0 ignores database connection parameter. |
Notice message tracking can be set to optional by setting 1 for pgsql.ignore_notice ini from PHP 4.3.0.
Notice message logging can be set to optional by setting 0 for pgsql.log_notice ini from PHP 4.3.0. Unless pgsql.ignore_notice is set to 0, notice message cannot be logged.
See also pg_query() and pg_last_error().
pg_last_oid
Description
int pg_last_oid ( resource result)pg_last_oid() is used to retrieve the oid assigned to an inserted tuple (record) if the result resource is used from the last command sent via pg_query() and was an SQL INSERT. Returns a positive integer if there was a valid oid. It returns FALSE if an error occurs or the last command sent via pg_query() was not an INSERT or INSERT is failed.
OID field became an optional field from PostgreSQL 7.2. When OID field is not defined in a table, programmer must use pg_result_status() to check if record is is inserted successfully or not.
Note : This function used to be called pg_getlastoid().
See also pg_query() and pg_result_status()
pg_lo_close
Description
bool pg_lo_close ( resource large_object)pg_lo_close() closes a Large Object. large_object is a resource for the large object from pg_lo_open().
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_loclose().
See also pg_lo_open(), pg_lo_create() and pg_lo_import().
pg_lo_create
Description
int pg_lo_create ( resource connection)pg_lo_create() creates a Large Object and returns the oid of the large object. connection specifies a valid database connection opened by pg_connect() or pg_pconnect(). PostgreSQL access modes INV_READ, INV_WRITE, and INV_ARCHIVE are not supported, the object is created always with both read and write access. INV_ARCHIVE has been removed from PostgreSQL itself (version 6.3 and above). It returns large object oid otherwise. It returns FALSE, if an error occurred,
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_locreate().
pg_lo_export
Description
bool pg_lo_export ( int oid, string pathname [, resource connection])The oid argument specifies oid of the large object to export and the pathname argument specifies the pathname of the file. It returns FALSE if an error occurred, TRUE otherwise.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_loexport().
See also pg_lo_import().
pg_lo_import
Description
int pg_lo_import ( [resource connection, string pathname])In versions before PHP 4.2.0 the syntax of this function was different, see the following definition:
int pg_lo_import ( [resource connection, string pathname])The pathname argument specifies the pathname of the file to be imported as a large object. It returns FALSE if an error occurred, oid of the just created large object otherwise.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : Lorsque le safe-mode est activé, PHP vérifie si le fichier/dossier que vous allez utiliser a le même UID que le script qui est actuellement exécuté..
Note : This function used to be called pg_loimport().
See also pg_lo_export() and pg_lo_open().
pg_lo_open
Description
resource pg_lo_open ( resource connection, int oid, string mode)pg_lo_open() open a Large Object and returns large object resource. The resource encapsulates information about the connection. oid specifies a valid large object oid and mode can be either "r", "w", or "rw". It returns FALSE if there is an error.
| Avertissement |
Do not close the database connection before closing the large object resource. |
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_loopen().
See also pg_lo_close() and pg_lo_create().
pg_lo_read_all
Description
int pg_lo_read_all ( resource large_object)pg_lo_read_all() reads a large object and passes it straight through to the browser after sending all pending headers. Mainly intended for sending binary data like images or sound. It returns number of bytes read. It returns FALSE, if an error occurred.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_loreadall().
See also pg_lo_read().
pg_lo_read
Description
string pg_lo_read ( resource large_object, int len)pg_lo_read() reads at most len bytes from a large object and returns it as a string. large_object specifies a valid large object resource andlen specifies the maximum allowable size of the large object segment. It returns FALSE if there is an error.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_loread().
See also pg_lo_read_all().
pg_lo_seek
Description
bool pg_lo_seek ( resource large_object, int offset [, int whence])pg_lo_seek() seeks position of large object resource. whence is PGSQL_SEEK_SET, PGSQL_SEEK_CUR or PGSQL_SEEK_END.
See also pg_lo_tell().
pg_lo_tell
Description
int pg_lo_tell ( resource large_object)pg_lo_tell() returns current position (offset from the beginning of large object).
See also pg_lo_seek().
pg_lo_unlink
Description
bool pg_lo_unlink ( resource connection, int oid)pg_lo_unlink() deletes a large object with the oid. It returns TRUE on success, otherwise returns FALSE.
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_lo_unlink().
See also pg_lo_create() and pg_lo_import().
pg_lo_write
Description
int pg_lo_write ( resource large_object, string data)pg_lo_write() writes at most to a large object from a variable data and returns the number of bytes actually written, or FALSE in the case of an error. large_object is a large object resource from pg_lo_open().
To use the large object (lo) interface, it is necessary to enclose it within a transaction block.
Note : This function used to be called pg_lo_write().
See also pg_lo_create() and pg_lo_open().
pg_metadata
Description
array pg_metadata ( resource connection, string table_name)pg_metadata() returns table definition for table_name as array. If there is error, it returns FALSE
Note : This function is experimental.
See also pg_convert()
pg_num_fields
Description
int pg_num_fields ( resource result)pg_num_fields() returns the number of fields (columns) in a PostgreSQL result. The argument is a result resource returned by pg_query(). This function will return -1 on error.
Note : This function used to be called pg_numfields().
See also pg_num_rows() and pg_affected_rows().
pg_num_rows
Description
int pg_num_rows ( resource result)pg_num_rows() will return the number of rows in a PostgreSQL result resource. result is a query result resource returned by pg_query(). This function will return -1 on error.
Note : Use pg_affected_rows() to get number of rows affected by INSERT, UPDATE and DELETE query.
Note : This function used to be called pg_numrows().
See also pg_num_fields() and pg_affected_rows().
pg_Options
Description
string pg_options ( resource connection_id)pg_options() retourne une chaîne contenant les options de la connexion PostgreSQL.
pg_pConnect
Description
int pg_pconnect ( string conn_string)pg_pconnect() retourne un index de connexion en cas de succès, ou FALSE en cas d'erreur. pg_pconnect() ouvre une connexion permanente à une base PostgreSQL. Les arguments doivent être insérés dans une chaîne à guillemets. Ils incluent : host, port, tty, options, dbname, user et password.
pg_pconnect() retourne un indentifiant de connexion qui sera utilisées par les autres fonctions PostgreSQL. Vous pouvez ouvrir plusieurs connexions en même temps.
L'ancienne syntaxe $conn = pg_pconnect("host", "port", "options", "tty", "dbname") est obsolète.
pg_Port
Description
int pg_port ( resource connection_id)pg_port() retourne le numéro de port de la connexion identifiée connection_id.
pg_put_line
Description
boolean pg_put_line ( [resource connection_id, string data])pg_put_line() envoie une chaîne (terminée par NULL) au serveur PostgreSQL. Ceci est pratique pour effectuer des insertions très rapides dans une table, initiée par une opération de copie PostgreSQL copy-operation. Le caractère final NULL est automatiquement ajouté. pg_put_line() retourne TRUE en cas de succès, et FALSE.
Note : Notez que l'application doit explicitement ajouter les deux caractères "\." à la fin de la chaîne pour indiquer au serveur qu'elle a finit d'envoyer des données.
Voir aussi pg_end_copy().
Exemple 1. Insertion à grande vitesse dans une table
|
pg_query
Description
resource pg_query ( resource connection, string query)pg_query() returns a query result resource if query could be executed. It returns FALSE on failure or if connection is not a valid connection. Details about the error can be retrieved using the pg_last_error() function if connection is valid. pg_last_error() sends an SQL statement to the PostgreSQL database specified by the connection resource. The connection must be a valid connection that was returned by pg_connect() or pg_pconnect(). The return value of this function is an query result resource to be used to access the results from other PostgreSQL functions such as pg_fetch_array().
Note : connection is a optional parameter for pg_query(). If connection is not set, default connection is used. Default connection is the last connection made by pg_connect() or pg_pconnect().
Although connection can be omitted, it is not recommended, since it could be a cause of hard to find bug in script.
Note : This function used to be called pg_exec(). pg_exec() is still available for compatibility reasons but users are encouraged to use the newer name.
See also pg_connect(), pg_pconnect(), pg_fetch_array(), pg_fetch_object(), pg_num_rows(), and pg_affected_rows().
pg_result_error
Description
string pg_result_error ( resource result)pg_result_error() returns error message associated with result resource. Therefore, user has better chance to get better error message than pg_last_error().
See also pg_query(), pg_send_query(), pg_get_result(), pg_last_error() and pg_last_notice()
pg_result_status
Description
int pg_result_status ( resource result)pg_result_status() returns status of result resource. Possible retun values are PGSQL_EMPTY_QUERY, PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO, PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR and PGSQL_FATAL_ERROR.
See also pg_connection_status().
pg_select
Description
array pg_select ( resource connection, string table_name, array assoc_array [, int options])pg_select() selects records specified by assoc_array which has field=>value. For successful query, it returns array contains all records and fields that match the condition specified by assoc_array. If options is specified, pg_convert() s applied to assoc_array with specified option.
Note : This function is experimental.
See also pg_convert()
pg_send_query
Description
bool pg_send_query ( resource connection, string query)bool pg_send_query ( string query)
pg_send_query() send asynchronous query to the connection. Unlike pg_query(), it can send multiple query to PostgreSQL and get the result one by one using pg_get_result(). Script execution is not block while query is executing. Use pg_connection_busy() to check connection is busy (i.e. query is executing) Query may be canceled by calling pg_cancel_query().
Although, user can send multiple query at once. User cannot send multiple query over busy connection. If query is sent while connection is busy, it waits until last query is finished and discards all result.
See also pg_query(), pg_cancel_query(), pg_get_result() and pg_connection_busy()
pg_set_client_encoding
Description
int pg_set_client_encoding ( [resource connection, string encoding])pg_set_client_encoding() fixe l'encodage du client. Elle retourne 0 en cas de succès, et -1 sinon.
encoding est l'encodage du client, et peut être SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, WIN1250.
Note : Cette fonction requiert PHP-4.0.2 ou plus récent et PostgreSQL-7.0 ou plus récent.
Jadis, pg_set_client_encoding() s'appelait pg_setclientencoding().
Voir aussi pg_client_encoding().
pg_trace
Description
boolean pg_trace ( string filename [, string mode [, resource connection]])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 le ne sont pas, elles peuvent être utiles pour suivre les requêtes et les erreurs : avec la commande grep '^To backend' trace.log, vous pourrez voir les requêtes réellement envoyées au serveur PostgreSQL.
filename et mode sont les mêmes arguments que pour la fonction fopen() (mode par défaut à 'w'), connection indique la connexion à suivre. Par défaut, c'est la dernière ouverte.
pg_trace() retourne TRUE si filename a pu être ouvert en écriture, etFALSEsinon.
Voir aussi fopen() et pg_untrace().
pg_tty
Description
string pg_tty ( resource connection_id)pg_tty() retourne le nom de tty de la connexion associée à connection_id.
pg_untrace
Description
boolean pg_untrace ( [resource connection])pg_untrace() termine le suivi d'une connexion PostgreSQL, initiée avec pg_trace(). connection indique la connexion à suivre. Par défaut, c'est la dernière ouverte.
pg_untrace() retourne toujours TRUE.
Voir aussi pg_trace().
pg_update
Description
long pg_update ( resource connection, string table_name, array condition, array data [, int options])pg_update() updates records that matches condition with data If options is specified, pg_convert() is applied to assoc_array with specified options.
Exemple 1. pg_update
|
Note : This function is experimental.
See also pg_convert()
LXXXI. Contrôle des processus
Le gestionnaire de contrôle des processus n'est pas activé par défaut. Il faut utiliser l'option de configuration --enable-pcntl lors de la compilation de PHP pour l'activer.
La liste suivante rassemble tous les signaux qui sont actuellement supportés par les fonctions de gestion des processus de PHP. Reportez vous à votre manuel pour plus de détails sur les comportements de ces signaux.
Tableau 1. Signaux supportés
| SIG_IGN | SIGFPE | SIGCONT |
| SIG_DFL | SIGKILL | SIGSTOP |
| SIG_ERR | SIGUSR1 | SIGTSTP |
| SIGHUP | SIGUSR2 | SIGTTIN |
| SIGINT | SIGSEGV | SIGTTOU |
| SIGQUIT | SIGPIPE | SIGURG |
| SIGILL | SIGALRM | SIGXCPU |
| SIGTRAP | SIGTERM | SIGXFSZ |
| SIGABRT | SIGSTKFLT | SIGVTALRM |
| SIGIOT | SIGCHLD | SIGPROF |
| SIGBUS | SIGCLD | SIGWINCH |
| SIGPOLL | SIGIO | SIGPWR |
| SIGSYS |
Exemple de contrôle de processus
Cet exemple effectue un fork du processus démon grâce à un gestionnaire de signaux.
Exemple 1. Process Control Example
|
- Table des matières
- pcntl_exec -- Executes specified program in current process space
- pcntl_fork -- Forks the currently running process
- pcntl_signal -- Installe un gestionnaire de signaux
- pcntl_waitpid -- Attend la fin de l'exécution d'un processus fils
- pcntl_wexitstatus -- Retourne le code d'un processus fils terminé
- pcntl_wifexited -- Retourne TRUE si le code de retour représente une fin normale
- pcntl_wifsignaled -- Returns TRUE if status code represents a termination due to a signal
- pcntl_wifstopped -- Returns TRUE if child process is currently stopped
- pcntl_wstopsig -- Returns the signal which caused the child to stop
- pcntl_wtermsig -- Returns the signal which caused the child to terminate
pcntl_exec
Description
bool pcntl_exec ( string path [, array args [, array envs]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
pcntl_fork
Description
int pcntl_fork ( void)pcntl_fork() crée un processus fils, qui ne diffère du processus père que par l'identifiant de processus et l'identifiant PPID. Reportez vous à la page de man fork(2) pour avoir des détails sur le comportement de cette fonction sur votre système.
En cas de succès, le PID (identifiant de processus) du fils est retourné dans le processus père, et 0 est retourné dans le processus fils. En cas d'échec, -1 est retourné dans le contexte du père, aucun processu fils ne sera créé et PHP lèvera une erreur.
Voir aussi pcntl_waitpid() et pcntl_signal().
pcntl_signal
Description
bool pcntl_signal ( int signo, mixed handle)pcntl_signal() installe un nouveau gestionnaire de signaux opur le signal indiqué par le paramètre signo. Le gestionnaire de signaux est affecté à handler qui peut être le nom d'une fonction utilisateur, ou bien l'une des deux constantes globales SIG_IGN et SIG_DFL.
pcntl_signal() retourne TRUE en cas de succès et FALSE en cas d'échec.
Voir aussi pcntl_fork() et pcntl_waitpid().
pcntl_waitpid
Description
int pcntl_waitpid ( int pid, int status, int options)pcntl_waitpid() suspend l'exécution du processus courant jusqu'à ce que un processus fils spécifié par le paramètre pid ait terminé, ou bien qu'un signal ait mis fin à ce processus ou qu'un signal ait appelé un gestionnaire de signaux. Si le processus fils identifié par pid est déjà terminé au moment de l'appel de cette fonction (on les appelle des processus "zombie"), la fonction se termine immédiatement. Toute ressource système utilisé par le processus fils est libérée. Reportez vous à la page de man waitpid(2) pour avoir des détails sur le comportement de cette fonction sur votre système.
pcntl_waitpid() retourne l'identifiant de processus du processus fils qui s'est terminé, ou bien -1 en cas d'erreur ou encore zéro si WNOHANG a été utilisée et qu'aucun processus fils n'était disponible.
Le paramètre pid peut prendre l'une des valeurs suivantes :
Tableau 1. Valeurs possibles de pid
| < -1 | attend que tous les processus fils dont l'identifiant de groupe est égal à la valeur absolue de pid soient terminés. |
| -1 | attend que tous les processus fils soient terminés. Ceci est le même comportement que celui de la fonction wait(). |
| 0 | attend que tous les processus fils dont l'identifiant de groupe est égal à celui du processus courant soient terminés. |
| > 0 | attend que le processus fils dont l'identifiant est égal à pid soit terminé. |
pcntl_waitpid() enregistrera des informations sur le statut courant du processus dans le paramètre status, qui peut être accédé avec les fonctions suivantes : pcntl_wifexited(), pcntl_wifstopped(), pcntl_wifsignaled(), pcntl_wexitstatus(), pcntl_wtermsig() et pcntl_wstopsig().
Le paramètre options peut prendre la valeur de zéro, ou plusieurs des constantes globales suivantes (combinez les avec l'opérateur OR) :
Tableau 2. Valeurs possibles de options
| WNOHANG | retourne immédiatement si aucun processus fils ne s'est terminé. |
| WUNTRACED | retourne lorsque les processus fils sont arrêtés et que leur status n'a pas été mis à jour. |
Voir aussi pcntl_fork(), pcntl_signal(), pcntl_wifexited(), pcntl_wifstopped(), pcntl_wifsignaled(), pcntl_wexitstatus(), pcntl_wtermsig() et pcntl_wstopsig().
pcntl_wexitstatus
Description
int pcntl_wexitstatus ( int status)pcntl_wexitstatus() retourne le code de retour du processus fils. Cette fonction n'est utile que si la fonction pcntl_wifexited() a retourné TRUE.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid() et pcntl_wifexited().
pcntl_wifexited
Description
int pcntl_wifexited ( int status)pcntl_wifexited() retourne TRUE si le processus fils a retourné un code qui représente une fin normale.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid() et pcntl_wexitstatus().
pcntl_wifsignaled
(PHP 4 >= 4.1.0)
pcntl_wifsignaled -- Returns TRUE if status code represents a termination due to a signalDescription
int pcntl_wifsignaled ( int status)Returns TRUE if the child process exited because of a signal which was not caught.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid() et pcntl_signal().
pcntl_wifstopped
Description
int pcntl_wifstopped ( int status)Returns TRUE if the child process which caused the return is currently stopped; this is only possible if the call to pcntl_waitpid() was done using the option WUNTRACED.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid().
pcntl_wstopsig
Description
int pcntl_wstopsig ( int status)Returns the number of the signal which caused the child to stop. This function is only useful if pcntl_wifstopped() returned TRUE.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid() et pcntl_wifstopped().
pcntl_wtermsig
Description
int pcntl_wtermsig ( int status)Returns the number of the signal that caused the child process to terminate. This function is only useful if pcntl_wifsignaled() returned TRUE.
Le paramètre status est le paramètre fourni à la fonction pcntl_waitpid(), qui avait réussi.
Voir aussi pcntl_waitpid(), pcntl_signal() et pcntl_wifsignaled().
LXXXII. Exécution de programmes externes
Ces fonctions fournissent la possibilité de passer directement des commandes au système, mais aussi de protéger le système des commandes passées. Ces fonctions sont complétées par l'opérateur guillemets obliques.
- Table des matières
- escapeshellarg -- Echappe une chaîne de caractères pour qu'elle soit utilisée en ligne de commande.
- escapeshellcmd -- Echappe les méta-caractères Shell.
- exec -- Exécute un programme externe.
- passthru -- Exécute un programme externe et affiche le résultat brut.
- proc_close -- Close a process opened by proc_open and return the exit code of that process.
- proc_open -- Execute a command and open file pointers for input/output
- shell_exec -- Execute command via shell and return complete output as string
- system -- Exécute un programme externe et affiche le résultat.
escapeshellarg
(PHP 4 >= 4.0.3)
escapeshellarg -- Echappe une chaîne de caractères pour qu'elle soit utilisée en ligne de commande.Description
string escapeshellarg ( string arg)escapeshellarg() ajoute des guillemets simples autour des chaînes de caractères, et ajoute des guillemets puis échappe les guillemets simples de la chaîne. Cela permet de faire passer directement une chaîne comme argument shell, tout en assurant un maximum de sécurité. escapeshellarg() doit être utilisée pour traiter individuellement chacun des arguments à passer au shell. Les fonctions shell sont exec(), system() et les opérateurs guillemets obliques. Une utilisation typique est :
Voir aussi exec(), popen(), system() et les opérateurs guillemets obliques.
escapeshellcmd
Description
string escapeshellcmd ( string command)escapeshellcmd() échappe tous les caractères de la chaîne command qui pourraient avoir une signification spéciale dans une commande shell. Cette fonction permet de s'assurer que la commande sera correctement passée à l'exécuteur de commande shell exec() et system(), ou encore à guillemets obliques. Généralement, cette fonction est utilisée comme ceci :
Voir aussi exec(), popen(), system(), et les opérateurs guillemets obliques.
exec
Description
string exec ( string command [, string array [, int return_var]])exec() éxecute la commande command, mais ne renvoie rien comme retour, hormis la dernière ligne du résultat de la commande. Pour exécuter une commande et obtenir le résultat sans aucun traitement, il faut utiliser la fonction passthru().
Si l'argument array est présent, alors ce tableau sera rempli par les lignes retournées par la commande. Il faut noter que si ce tableau contient des éléments, exec() ajoutera les nouvelles lignes à la fin du tableau. Si vous ne voulez pars que les nouveaux éléments soient concaténés, utilisez la fonction unset() avec ce tableau avant de le passer à exec().
Si l'argument return_var est présent en plus du tableau array, alors de statut de retour d'exécution sera inscrit dans cette variable.
Notez que si vous allez fournir des commandes qui proviennent d'un utilisateur, il est avisé d'utiliser la fonction escapeshellcmd() pour s'assurer que l'utilisateur n'essaie pas de profiter des caractères spéciaux pour tromper le système.
Voir aussi system(), passthru(), popen(), escapeshellcmd(), et les opérateurs guillemets obliques.
passthru
Description
void passthru ( string command [, int return_var])La fonction passthru() est similaire à la fonction exec() car les deux exécutent la commande command. Si l'argument return_var est présent, le code de statut de réponse UNIX y sera placé. Cette fonction doit être utilisée de préférence aux commandes exec() ou system() lorsque le résultat attendu est de type binaire, et doit être passé tel quel à un navigateur. Une utilisation classique de cette fonction est l'exécution de l'utilitaire pbmplus qui peut retourner une image. En fixant le résultat du contenu (Content-Type) à "image/gif" puis en appelant pbmplus pour obtenir une image gif, vous pouvez créer des scripts PHP qui retourne des images.
Voir aussi exec(), system(), popen(), escapeshellcmd(), et les opérateurs guillemets obliques.
proc_close
(PHP 4 CVS only)
proc_close -- Close a process opened by proc_open and return the exit code of that process.Description
int proc_close ( resource process)proc_close() is similar to popen() except that it only works on processes opened by proc_open(). proc_close() waits for the process to terminate, and returns it's exit code. If you have open pipes to that process, you should fclose() them prior to calling this function in order to avoid a deadlock - the child process may not be able to exit while the pipes are open.
proc_open
Description
resource proc_open ( string cmd, array descriptorspec, array pipes)proc_open() is similar to popen() but provides a much greater degree of control over the program execution. cmd is the command to be executed by the shell. descriptorspec is an indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. pipes will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created. The return value is a resource representing the process; you should free it using proc_close() when you are finished with it.
$descriptorspec = array(
0 => array("pipe", "r"), // stdin is a pipe that the child will read from
1 => array("pipe", "w"), // stdout is a pipe that the child will write to
2 => array("file", "/tmp/error-output.txt", "a"), // stderr is a file to write to
);
$process = proc_open("php", $descriptorspec, $pipes);
if (is_resource($process)) {
// $pipes now looks like this:
// 0 => writeable handle connected to child stdin
// 1 => readable handle connected to child stdout
// Any error output will be appended to /tmp/error-output.txt
fwrite($pipes[0], "<?php echo \"Hello World!\"; ?>");
fclose($pipes[0]);
while(!feof($pipes[1])) {
echo fgets($pipes[1], 1024);
}
fclose($pipes[1]);
// It is important that you close any pipes before calling
// proc_close in order to avoid a deadlock
$return_value = proc_close($process);
echo "command returned $return_value\n";
} |
The file descriptor numbers in descriptorspec are not limited to 0, 1 and 2 - you may specify any valid file descriptor number and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure manner. It is also useful for reading status information provided by those programs on auxillary file descriptors.
Note : Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.
Note : This function was introduced in PHP 4.3.0.
Note : If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.
See also exec(), system(), passthru(), popen(), escapeshellcmd(), and the backtick operator.
shell_exec
system
Description
string system ( string command [, int return_var])system() est la version PHP de la fonction C qui exécute la commande command et retourne le résultat. Si une variable est fournie comme second argument, alors le code de statut de la commande y sera affecté.
Notez que si vous allez fournir des commandes qui proviennent d'un utilisateur, il est avisé d'utiliser la fonction escapeshellcmd() pour s'assurer que l'utilisateur n'essaie pas de profiter des caractères spéciaux pour tromper le système.
system() essaie automatiquement de vider les tampons du serveur web après chaque ligne de résultat PHP, lorsque ce dernier fonctionne comme un module.
system() retourne la dernière ligne du retour, en cas de succès, et FALSE en cas d'échec.
Si vous devez exécuter une commande et récupérer tout le résultat sans aucune intervention, utilisez la fonction passthru().
Voir aussi exec(), passthru(), popen(), escapeshellcmd() et les opérateurs guillemets obliques.
LXXXIII. Printer functions
These functions are only available under Windows 9.x, ME, NT4 and 2000. They have been added in PHP 4 (4.0.4).
- Table des matières
- printer_abort -- Deletes the printer's spool file
- printer_close -- Close an open printer connection
- printer_create_brush -- Create a new brush
- printer_create_dc -- Create a new device context
- printer_create_font -- Create a new font
- printer_create_pen -- Create a new pen
- printer_delete_brush -- Delete a brush
- printer_delete_dc -- Delete a device context
- printer_delete_font -- Delete a font
- printer_delete_pen -- Delete a pen
- printer_draw_bmp -- Draw a bmp
- printer_draw_chord -- Draw a chord
- printer_draw_elipse -- Draw an ellipse
- printer_draw_line -- Draw a line
- printer_draw_pie -- Draw a pie
- printer_draw_rectangle -- Draw a rectangle
- printer_draw_roundrect -- Draw a rectangle with rounded corners
- printer_draw_text -- Draw text
- printer_end_doc -- Close document
- printer_end_page -- Close active page
- printer_get_option -- Retrieve printer configuration data
- printer_list -- Return an array of printers attached to the server
- printer_logical_fontheight -- Get logical font height
- printer_open -- Open connection to a printer
- printer_select_brush -- Select a brush
- printer_select_font -- Select a font
- printer_select_pen -- Select a pen
- printer_set_option -- Configure the printer connection
- printer_start_doc -- Start a new document
- printer_start_page -- Start a new page
- printer_write -- Write data to the printer
printer_abort
Description
void printer_abort ( resource handle)This function deletes the printers spool file.
handle must be a valid handle to a printer.
printer_close
Description
void printer_close ( resource handle)This function closes the printer connection. printer_close() also closes the active device context.
handle must be a valid handle to a printer.
printer_create_brush
Description
mixed printer_create_brush ( int style, string color)The function creates a new brush and returns a handle to it. A brush is used to fill shapes. For an example see printer_select_brush(). color must be a color in RGB hex format, i.e. "000000" for black, style must be one of the following constants:
PRINTER_BRUSH_SOLID: creates a brush with a solid color.
PRINTER_BRUSH_DIAGONAL: creates a brush with a 45-degree upward left-to-right hatch ( / ).
PRINTER_BRUSH_CROSS: creates a brush with a cross hatch ( + ).
PRINTER_BRUSH_DIAGCROSS: creates a brush with a 45 cross hatch ( x ).
PRINTER_BRUSH_FDIAGONAL: creates a brush with a 45-degree downward left-to-right hatch ( \ ).
PRINTER_BRUSH_HORIZONTAL: creates a brush with a horizontal hatch ( - ).
PRINTER_BRUSH_VERTICAL: creates a brush with a vertical hatch ( | ).
PRINTER_BRUSH_CUSTOM: creates a custom brush from an BMP file. The second parameter is used to specify the BMP instead of the RGB color code.
printer_create_dc
Description
void printer_create_dc ( resource handle)The function creates a new device context. A device context is used to customize the graphic objects of the document. handle must be a valid handle to a printer.
Exemple 1. printer_create_dc() example
|
printer_create_font
Description
mixed printer_create_font ( string face, int height, int width, int font_weight, bool italic, bool underline, bool strikeout, int orientaton)The function creates a new font and returns a handle to it. A font is used to draw text. For an example see printer_select_font(). face must be a string specifying the font face. height specifies the font height, and width the font width. The font_weight specifies the font weight (400 is normal), and can be one of the following predefined constants.
PRINTER_FW_THIN: sets the font weight to thin (100).
PRINTER_FW_ULTRALIGHT: sets the font weight to ultra light (200).
PRINTER_FW_LIGHT: sets the font weight to light (300).
PRINTER_FW_NORMAL: sets the font weight to normal (400).
PRINTER_FW_MEDIUM: sets the font weight to medium (500).
PRINTER_FW_BOLD: sets the font weight to bold (700).
PRINTER_FW_ULTRABOLD: sets the font weight to ultra bold (800).
PRINTER_FW_HEAVY: sets the font weight to heavy (900).
italic can be TRUE or FALSE, and sets whether the font should be italic.
underline can be TRUE or FALSE, and sets whether the font should be underlined.
strikeout can be TRUE or FALSE, and sets whether the font should be striked out.
orientation specifies a rotation. For an example see printer_select_font().
printer_create_pen
Description
mixed printer_create_pen ( int style, int width, string color)The function creates a new pen and returns a handle to it. A pen is used to draw lines and curves. For an example see printer_select_pen(). color must be a color in RGB hex format, i.e. "000000" for black, width specifies the width of the pen whereas style must be one of the following constants:
PRINTER_PEN_SOLID: creates a solid pen.
PRINTER_PEN_DASH: creates a dashed pen.
PRINTER_PEN_DOT: creates a dotted pen.
PRINTER_PEN_DASHDOT: creates a pen with dashes and dots.
PRINTER_PEN_DASHDOTDOT: creates a pen with dashes and double dots.
PRINTER_PEN_INVISIBLE: creates an invisible pen.
printer_delete_brush
Description
bool printer_delete_brush ( resource handle)The function deletes the selected brush. For an example see printer_select_brush(). It returns TRUE on success, or FALSE otherwise. handle must be a valid handle to a brush.
printer_delete_dc
Description
bool printer_delete_dc ( resource handle)The function deletes the device context and returns TRUE on success, or FALSE if an error occurred. For an example see printer_create_dc(). handle must be a valid handle to a printer.
printer_delete_font
Description
bool printer_delete_font ( resource handle)The function deletes the selected font. For an example see printer_select_font(). It returns TRUE on success, or FALSE otherwise. handle must be a valid handle to a font.
printer_delete_pen
Description
bool printer_delete_pen ( resource handle)The function deletes the selected pen. For an example see printer_select_pen(). It returns TRUE on success, or FALSE otherwise. handle must be a valid handle to a pen.
printer_draw_bmp
Description
void printer_draw_bmp ( resource handle, string filename, int x, int y)The function simply draws an bmp the bitmap filename at position x, y. handle must be a valid handle to a printer.
The function returns TRUE on success, or otherwise FALSE.
printer_draw_chord
Description
void printer_draw_chord ( resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad_x, int rad_y, int rad_x1, int rad_y1)The function simply draws an chord. handle must be a valid handle to a printer.
rec_x is the upper left x coordinate of the bounding rectangle.
rec_y is the upper left y coordinate of the bounding rectangle.
rec_x1 is the lower right x coordinate of the bounding rectangle.
rec_y1 is the lower right y coordinate of the bounding rectangle.
rad_x is x coordinate of the radial defining the beginning of the chord.
rad_y is y coordinate of the radial defining the beginning of the chord.
rad_x1 is x coordinate of the radial defining the end of the chord.
rad_y1 is y coordinate of the radial defining the end of the chord.
Exemple 1. printer_draw_chord() example
|
printer_draw_elipse
Description
void printer_draw_elipse ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y)The function simply draws an ellipse. handle must be a valid handle to a printer.
ul_x is the upper left x coordinate of the ellipse.
ul_y is the upper left y coordinate of the ellipse.
lr_x is the lower right x coordinate of the ellipse.
lr_y is the lower right y coordinate of the ellipse.
Exemple 1. printer_draw_elipse() example
|
printer_draw_line
Description
void printer_draw_line ( resource printer_handle, int from_x, int from_y, int to_x, int to_y)The function simply draws a line from position from_x, from_y to position to_x, to_y using the selected pen. printer_handle must be a valid handle to a printer.
Exemple 1. printer_draw_line() example
|
printer_draw_pie
Description
void printer_draw_pie ( resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad1_x, int rad1_y, int rad2_x, int rad2_y)The function simply draws an pie. handle must be a valid handle to a printer.
rec_x is the upper left x coordinate of the bounding rectangle.
rec_y is the upper left y coordinate of the bounding rectangle.
rec_x1 is the lower right x coordinate of the bounding rectangle.
rec_y1 is the lower right y coordinate of the bounding rectangle.
rad1_x is x coordinate of the first radial's ending.
rad1_y is y coordinate of the first radial's ending.
rad2_x is x coordinate of the second radial's ending.
rad2_y is y coordinate of the second radial's ending.
Exemple 1. printer_draw_pie() example
|
printer_draw_rectangle
Description
void printer_draw_rectangle ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y)The function simply draws a rectangle.
handle must be a valid handle to a printer.
ul_x is the upper left x coordinate of the rectangle.
ul_y is the upper left y coordinate of the rectangle.
lr_x is the lower right x coordinate of the rectangle.
lr_y is the lower right y coordinate of the rectangle.
Exemple 1. printer_draw_rectangle() example
|
printer_draw_roundrect
Description
void printer_draw_roundrect ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y, int width, int height)The function simply draws a rectangle with rounded corners.
handle must be a valid handle to a printer.
ul_x is the upper left x coordinate of the rectangle.
ul_y is the upper left y coordinate of the rectangle.
lr_x is the lower right x coordinate of the rectangle.
lr_y is the lower right y coordinate of the rectangle.
width is the width of the ellipse.
height is the height of the ellipse.
Exemple 1. printer_draw_roundrect() example
|
printer_draw_text
Description
void printer_draw_text ( resource printer_handle, string text, int x, int y)The function simply draws text at position x, y using the selected font. printer_handle must be a valid handle to a printer.
Exemple 1. printer_draw_text() example
|
printer_end_doc
Description
bool printer_end_doc ( resource handle)Closes a new document in the printer spooler. The document is now ready for printing. For an example see printer_start_doc(). handle must be a valid handle to a printer.
printer_end_page
Description
bool printer_end_page ( resource handle)The function closes the active page in the active document. For an example see printer_start_doc(). handle must be a valid handle to a printer.
printer_get_option
Description
mixed printer_get_option ( resource handle, string option)The function retrieves the configuration setting of option. handle must be a valid handle to a printer. Take a look at printer_set_option() for the settings that can be retrieved, additionally the following settings can be retrieved:
PRINTER_DEVICENAME returns the devicename of the printer.
PRINTER_DRIVERVERSION returns the printer driver version.
printer_list
Description
array printer_list ( int enumtype [, string name [, int level]])The function enumerates available printers and their capabilities. level sets the level of information request. Can be 1,2,4 or 5. enumtype must be one of the following predefined constants:
PRINTER_ENUM_LOCAL: enumerates the locally installed printers.
PRINTER_ENUM_NAME: enumerates the printer of name, can be a server, domain or print provider.
PRINTER_ENUM_SHARED: this parameter can't be used alone, it has to be OR'ed with other parameters, i.e. PRINTER_ENUM_LOCAL to detect the locally shared printers.
PRINTER_ENUM_DEFAULT: (Win9.x only) enumerates the default printer.
PRINTER_ENUM_CONNECTIONS: (WinNT/2000 only) enumerates the printers to which the user has made connections.
PRINTER_ENUM_NETWORK: (WinNT/2000 only) enumerates network printers in the computer's domain. Only valid if level is 1.
PRINTER_ENUM_REMOTE: (WinNT/2000 only) enumerates network printers and print servers in the computer's domain. Only valid if level is 1.
printer_logical_fontheight
Description
int printer_logical_fontheight ( resource handle, int height)The function calculates the logical font height of height. handle must be a valid handle to a printer.
printer_open
Description
mixed printer_open ( [string devicename])This function tries to open a connection to the printer devicename, and returns a handle on success or FALSE on failure.
If no parameter was given it tries to open a connection to the default printer (if not specified in php.ini as printer.default_printer, php tries to detect it).
printer_open() also starts a device context.
printer_select_brush
Description
void printer_select_brush ( resource printer_handle, resource brush_handle)The function selects a brush as the active drawing object of the actual device context. A brush is used to fill shapes. If you draw an rectangle the brush is used to draw the shapes, while the pen is used to draw the border. If you haven't selected a brush before drawing shapes, the shape won't be filled. printer_handle must be a valid handle to a printer. brush_handle must be a valid handle to a brush.
Exemple 1. printer_select_brush() example
|
printer_select_font
Description
void printer_select_font ( resource printer_handle, resource font_handle)The function selects a font to draw text. printer_handle must be a valid handle to a printer. font_handle must be a valid handle to a font.
Exemple 1. printer_select_font() example
|
printer_select_pen
Description
void printer_select_pen ( resource printer_handle, resource pen_handle)The function selects a pen as the active drawing object of the actual device context. A pen is used to draw lines and curves. I.e. if you draw a single line the pen is used. If you draw an rectangle the pen is used to draw the borders, while the brush is used to fill the shape. If you haven't selected a pen before drawing shapes, the shape won't be outlined. printer_handle must be a valid handle to a printer. pen_handle must be a valid handle to a pen.
Exemple 1. printer_select_pen() example
|
printer_set_option
Description
bool printer_set_option ( resource handle, int option, mixed value)The function sets the following options for the current connection. handle must be a valid handle to a printer. For option can be one of the following constants:
PRINTER_COPIES: sets how many copies should be printed, value must be an integer.
PRINTER_MODE: specifies the type of data (text, raw or emf), value must be a string.
PRINTER_TITLE: specifies the name of the document, value must be a string.
PRINTER_ORIENTATION: specifies the orientation of the paper, value can be either PRINTER_ORIENTATION_PORTRAIT or PRINTER_ORIENTATION_LANDSCAPE
PRINTER_RESOLUTION_Y: specifies the y-resolution in DPI, value must be an integer.
PRINTER_RESOLUTION_X: specifies the x-resolution in DPI, value must be an integer.
PRINTER_PAPER_FORMAT: specifies the a predefined paper format, set value to PRINTER_FORMAT_CUSTOM if you want to specify a custom format with PRINTER_PAPER_WIDTH and PRINTER_PAPER_LENGTH. value can be one of the following constants.
PRINTER_FORMAT_CUSTOM: let's you specify a custom paper format.
PRINTER_FORMAT_LETTER: specifies standard letter format (8 1/2- by 11-inches).
PRINTER_FORMAT_LETTER: specifies standard legal format (8 1/2- by 14-inches).
PRINTER_FORMAT_A3: specifies standard A3 format (297- by 420-millimeters).
PRINTER_FORMAT_A4: specifies standard A4 format (210- by 297-millimeters).
PRINTER_FORMAT_A5: specifies standard A5 format (148- by 210-millimeters).
PRINTER_FORMAT_B4: specifies standard B4 format (250- by 354-millimeters).
PRINTER_FORMAT_B5: specifies standard B5 format (182- by 257-millimeter).
PRINTER_FORMAT_FOLIO: specifies standard FOLIO format (8 1/2- by 13-inch).
PRINTER_PAPER_LENGTH: if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, PRINTER_PAPER_LENGTH specifies a custom paper length in mm, value must be an integer.
PRINTER_PAPER_WIDTH: if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, PRINTER_PAPER_WIDTH specifies a custom paper width in mm, value must be an integer.
PRINTER_SCALE: specifies the factor by which the printed output is to be scaled. the page size is scaled from the physical page size by a factor of scale/100. for example if you set the scale to 50, the output would be half of it's original size. value must be an integer.
PRINTER_BACKGROUND_COLOR: specifies the background color for the actual device context, value must be a string containing the rgb information in hex format i.e. "005533".
PRINTER_TEXT_COLOR: specifies the text color for the actual device context, value must be a string containing the rgb information in hex format i.e. "005533".
PRINTER_TEXT_ALIGN: specifies the text alignment for the actual device context, value can be combined through OR'ing the following constants:
PRINTER_TA_BASELINE: text will be aligned at the base line.
PRINTER_TA_BOTTOM: text will be aligned at the bottom.
PRINTER_TA_TOP: text will be aligned at the top.
PRINTER_TA_CENTER: text will be aligned at the center.
PRINTER_TA_LEFT: text will be aligned at the left.
PRINTER_TA_RIGHT: text will be aligned at the right.
printer_start_doc
Description
bool printer_start_doc ( resource handle [, string document])The function creates a new document in the printer spooler. A document can contain multiple pages, it's used to schedule the print job in the spooler. handle must be a valid handle to a printer. The optional parameter document can be used to set an alternative document name.
printer_start_page
Description
bool printer_start_page ( resource handle)The function creates a new page in the active document. For an example see printer_start_doc(). handle must be a valid handle to a printer.
printer_write
LXXXIV. Pspell
La librairie pspell vous permet de vérifier l'orthographe d'un mot, et suggérer des corrections.
Vous aurez besoin des librairies aspell et pspell, disponibles à http://aspell.sourceforge.net/ et http://aspell.net/ (respectivement). Il faut aussi ajouter l'otpion --with-pspell[=dir] lors de la compilation de PHP.
- Table des matières
- 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_ignore -- Ignore les mots des 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 -- Active la sauvegarde des paires de remplacement
- pspell_new_config -- Charge un nouveau dictionnaire
- pspell_new_personal -- Charge un nouveau dictionnaire avec un dictionnaire personnel
- pspell_new -- Charge un nouveau dictionnaire
- pspell_save_wordlist -- Sauve le dictionnaire personnel dans un fichier.
- pspell_store_replacement -- Enregistre une paire de remplacement pour un mot
- pspell_suggest -- Suggèegrave;re une orthographe
pspell_add_to_personal
Description
int pspell_add_to_personal ( resource dictionary_link, string word)pspell_add_to_personal() ajoute un mot au dictionnaire personnel. Si vous utilisez pspell_new_config() avec pspell_config_personal() pour ouvrir le dictionnaire, vous pourrez sauver le dictionnaire personnel ultérieurement avec pspell_save_wordlist(). Notez bien que cette fonction ne fonctionnera pas avec les versions antérieures pspell .11.2 et aspell .32.5.
Exemple 1. Exemple avec pspell_add_to_personal()
|
pspell_add_to_session
(PHP 4 >= 4.0.2)
pspell_add_to_session -- Ajoute le mot au dictionnaire personnel de la session couranteDescription
int pspell_add_to_session ( resource dictionary_link, string word)pspell_add_to_session() ajoute un mot au dictionnaire personnel associé à la version courante. C'est une fonction similaire à pspell_add_to_personal().
pspell_check
Description
boolean pspell_check ( resource dictionary_link, string word)pspell_check() vérifie l'orthographe d'un mot et retourne TRUE si l'orthographe est correcte, FALSE sinon.
pspell_clear_session
Description
int pspell_clear_session ( resource dictionary_link)pspell_clear_session() remet à zéro la session courante. Le dictionnaire personnel est vidé, et par exemple si vous tentez de l'enregistrer avec pspell_save_wordlist(), rien ne se passera.
Exemple 1. Exemple avec pspell_add_to_personal()
|
pspell_config_create
Description
resource pspell_config_create ( string language [, string spelling [, string jargon [, string encoding]]])pspell_config_create() a une syntaxe similaire à 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éer une nouvelle configuration, vous pouvez aussi utiliser les fonctions pspell_config_* avant d'appeler pspell_new_config() pour tirer profit des fonctionnalités avancées.
Le paramètre de langage 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é (_).
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).
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.
Le paramètre d'encodage 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.
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, plus de vitesse)
PSPELL_NORMAL - Mode normal mode (plus de suggestions)
PSPELL_BAD_SPELLERS - Mode lent (beaucoup plus de suggestions, moins de vitesse)
Pour plus d'informations et d'exemples, vérifiez le manuel pspell sur leur site web :http://aspell.net/.
pspell_config_ignore
Description
int pspell_config_ignore ( resource dictionary_link, int n)pspell_config_ignore() doit être utilisé avec une configuration avant d'appeler pspell_new_config(). Cette fonction permet au vérificateur d'ignorer les mots trop courts.
pspell_config_mode
Description
int pspell_config_mode ( resource dictionary_link, int mode)pspell_config_mode() doit être appelé avant pspell_new_config(). Cette fonction détermine le nombre de suggestions qui seront retournés par pspell_suggest().
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, plus de vitesse)
PSPELL_NORMAL - Mode normal mode (plus de suggestions)
PSPELL_BAD_SPELLERS - Mode lent (beaucoup plus de suggestions, moins de vitesse)
pspell_config_personal
Description
int pspell_config_personal ( resource dictionary_link, string file)pspell_config_personal() doit être appelé dans une configuration avant d'appeler pspell_new_config(). Le dictionnaire personnel sera chargé est utilisé en plus du dictionnaire standard, une fois que vous aurez appelé pspell_new_config(). Si le fichier n'existe pas, il sera créé. Ce fichier sera aussi le fichier où pspell_save_wordlist() sauvera le dictionnaire personnel. Ce fichier devra donc être accessible en écriture par PHP. Notez que cette fonction ne fonctionne pas avec les versions antérieures à pspell .11.2 et aspell .32.5.
pspell_config_repl
Description
int pspell_config_repl ( resource dictionary_link, string file)pspell_config_repl() doit être appelé dans une configuration avant d'appeler pspell_new_config(). 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é pour enregistrer une paire de remplacement et pspell_save_wordlist() pour sauver le dictionnaire avec les paires de remplacement. Ce fichier devra donc être accessible en écriture par PHP. Notez que cette fonction ne fonctionne pas avec les versions antérieures à pspell .11.2 et aspell .32.5.
Exemple 1. Exemple avec pspell_config_repl()
|
pspell_config_runtogether
Description
int pspell_config_runtogether ( resource dictionary_link, boolean flag)pspell_config_runtogether() doit être appelé dans une configuration avant d'appeler pspell_new_config(). Cette fonction indique si deux mots accolés doivent être traités comme un composé valide, même si 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_save_repl
Description
int pspell_config_save_repl ( resource dictionary_link, boolean flag)pspell_config_save_repl() doit être appelé dans une configuration avant d'appeler pspell_new_config(). Elle 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 toutes façons, et si ce n'est pas le cas, elles ne seront pas sauvées. Ce fichier devra donc être accessible en écriture par PHP. Notez que cette fonction ne fonctionne pas avec les versions antérieures à pspell .11.2 et aspell .32.5.
pspell_new_config
Description
resource pspell_new_config ( resource config)pspell_new_config() ouvre un nouveau dictionnaire et charge les paramètrages spécifié dans la configuration config, créée avec pspell_config_create() et modifiée avec les fonctions pspell_config_*. Cette méthode vous donne le maximum de flexibilité, et dispose de toutes les fonctionnalités fournies par pspell_new() et pspell_new_personal().
Le paramètre de configuration est celui qui a été retourné par pspell_config_create() lors de création de la configuration.
pspell_new_personal
(PHP 4 >= 4.0.2)
pspell_new_personal -- Charge un nouveau dictionnaire avec un dictionnaire personnelDescription
resource pspell_new_personal ( string personal, string language [, string spelling [, string jargon [, string encoding [, int mode]]]])pspell_new_personal() charge un nouveau dictionnaire avec un dictionnaire personnel, et retourne un identifiant de dictionnaire utilisé par d'autres fonctions pspells. Le dictionnaire peut être modifiée et sauvé avec pspell_save_wordlist(). Cependant, les paires de remplacement ne seront pas sauvées. Pour ce faire, vous devez créer une configuration qui utilise pspell_config_create(), et choisir le fichier de destination du dictionnaire personnel avec pspell_config_personal(), choisir le fichier de paire de remplacement avec pspell_config_repl(), et ouvrir un nouveau dictionnaire avec pspell_new_config().
Le paramètre personal spécifie 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 pluspart des systèmes, et probablement pas ce que vous souhaitez.
Le paramètre de langage 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é (_).
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).
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.
Le paramètre d'encodage 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.
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, plus de vitesse)
PSPELL_NORMAL - Mode normal mode (plus de suggestions)
PSPELL_BAD_SPELLERS - Mode lent (beaucoup plus de suggestions, moins de vitesse)
Pour plus d'informations et d'exemples, vérifiez le manuel pspell sur leur site web :http://aspell.net/.
pspell_new
Description
resource pspell_new ( string language [, string spelling [, string jargon [, string encoding]]])pspell_new() ouvre un nouveau dictionnaire et retourne un identifiant de dictionnaire, pour utiliser avec d'autres fonctions pspell.
Le paramèegrave;tre de langue spelling est constitué des deux lettres du codage de langue ISO 639, et du codage optionnel de pays ISO 3166, séparé par un '_'.
Ce paramèegrave;tre est nécessaire pour les langues qui ont plus d'une orthographe, comme l'anglais ou le français. Les valeurs reconnues sont ``americain'', ``britannique'', et ``canadien''.
Le paramèegrave;tre de jargon contient des informations supplémentaires pour distinguer deux listes de mots qui ont le même marquage de langue et d'orthographe.
Le paramèegrave;tre d'encodage est le type d'encodage des mots. Les valeurs valides sont 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'.
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, plus de vitesse)
PSPELL_NORMAL - Mode normal mode (plus de suggestions)
PSPELL_BAD_SPELLERS - Mode lent (beaucoup plus de suggestions, moins de vitesse)
PSPELL_RUN_TOGETHER - Considère que des mots accolés forment un composé autorisé. C'est à dire que "lechat" sera un composé valide. Cette option ne modifie que les résutlat retournés par pspell_check(); pspell_suggest() retournera toujours les mêmes suggestions.
Pour plus d'informations et d'exemples, reportez vous au site http://aspell.net/ (en anglais).
pspell_save_wordlist
Description
int pspell_save_wordlist ( resource dictionary_link)pspell_save_wordlist() sauve le dictionnaire personnel de la session courante. Le dictionnaire doit avoir été ouvert avec pspell_new_personal(), et la localisation des fichiers doit avoir été spécifié avec pspell_config_personal() et (éventuellement) pspell_config_repl(). Notez que cette fonction n'est pas disponible avec les versions antérieures à pspell .11.2 et aspell .32.5.
Exemple 1. Exemple pspell_add_to_personal()
|
pspell_store_replacement
Description
int pspell_store_replacement ( resource dictionary_link, string misspelled, string correct)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, vous devez utiliser pspell_new_personal() pour ouvrir le dictionnaire. Pour pouvoir sauver tout le temps les paires de remplacement, vous devez 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. Ce fichier devra donc être accessible en écriture par PHP. Notez que cette fonction ne fonctionne pas avec les versions antérieures à pspell .11.2 et aspell .32.5.
Exemple 1. Exemple avec pspell_store_replacement()
|
pspell_suggest
LXXXV. Readline (GNU)
Les fonctions readline() implémente une interface avec la librairie GNU Readline. Ces fonctions fournissent une ligne de commande éditable, un peu comme lorsque Bash vous permet d'utiliser les flèches de déplacement pour insérer un caractère ou passer en revue l'historique. A cause de l'interactivité de ces commande, elles ne seront que rarement utiles pour les applications Web, mais peuvent se révéler utiles lorsqu'un script est exécuté depuis une commande shell.
Le site du projet GNU Readline est http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. Elle est entretenue par Chet Ramey, qui est aussi l'auteur de Bash.
- Table des matières
- readline_add_history -- Ajoute une ligne à l'historique
- readline_clear_history -- Efface l'historique
- readline_completion_function -- Enregistre une fonction de complétion
- readline_info -- Lit/modifie diverses variables internes
- readline_list_history -- Liste l'historique
- readline_read_history -- Lit l'historique
- readline_write_history -- Ecrit dans l'historique
- readline -- Lit une ligne
readline_add_history
Description
void readline_add_history ( string line)readline_add_history() ajoute une ligne à l'historique.
readline_clear_history
Description
boolean readline_clear_history ( void )readline_clear_history() efface tout l'historique.
readline_completion_function
Description
boolean readline_completion_function ( string line)readline_completion_function() enregistre une nouvelle fonction de complétion. Vous devez fournir le nom d'une fonction qui accepte un nom partiel de commande, et retourne une liste de fonctions complète possibles. C'est la même fonctionnalité que lorsque vous utilisez la touche de tabulation sous Bash.
readline_info
Description
mixed readline_info ( [string varname [, string newvalue]])Appelée sans paramètre, readline_info() retourne une 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.
Appelée avec le paramètre varname, la valeur de cette variable sera retournée. Appelée avec deux paramètres, et la valeur de la variable varname, sera remplacée par newvalue.
readline_list_history
Description
array readline_list_history ( void )readline_list_history() retourne un tableau avec la liste de toutes les lignes de commandes de l'historique. Les éléments sont indéxés numériquement, à partir de 0.
readline_read_history
Description
boolean readline_read_history ( string filename)readline_read_history() lit une ligne de l'historique.
readline_write_history
Description
boolean readline_write_history ( string filename)readline_write_history() écrit filename dans l'historique.
readline
Description
string readline ( [string prompt])readline() retourne une ligne entrée par l'utilisateur. Vous pouvez spécifier une chaîne de prompt. La ligne retournée est débarassée du caractère nouvelle ligne final. Vous devez ajouter cette ligne à l'historique vous-même, avec la fonction readline_add_history().
LXXXVI. Recode (GNU)
Ce module contient l'interface à la librairie GNU Recode library, version 3.5. Pour pouvoir utiliser ces fonctions, il faut que PHP ait été compilé avec l'option --with-recode. Pour cela, il faut que vous ayez la librairie GNU Recode 3.5 ou plus récent, installée sur votre système.
La librairie GNU Recode library convertit les fichiers ayant des jeux de caractères différents. Lorsque ce n'est pas possible, elle se débarasse des caractères illégaux, ou bien effectue une approximation. La librairie reconnait ou produit près de 150 jeux de caractères différents, et peut quasiment tous les convertir de l'un vers l'autre. La plus part des jeux de caractères de la RFC 1345 sont supportés.
- Table des matières
- recode_file -- Recode de fichier à fichier, en fonction de la requête.
- recode_string -- Recode une chaîne en fonction de la requête.
- recode -- Recode une fonction grâce à une requête
recode_file
Description
boolean recode_file ( string request, resource input, resource output)recode_file() recode le fichier identifié par input dans le fichier identifié par output en fonction de la requête de recodage request. Retourne FALSE, en cas d'échec, et TRUE sinon.
recode_file() ne gère pas encore les fichiers distants (URLs). Les deux fichiers doivent faire référence à des fichiers locaux.
recode_string
Description
string recode_string ( string request, string string)recode_string() recode la chaîne string en fonction de la requête request. recode_string() retourne FALSE, en cas d'échec, et TRUE sinon.
Une requête simple de recodage peut être "lat1..iso646-de". Reportez vous à la documentation GNU Recode de votre installation pour plus de détails sur les requêtes.
recode
Description
string recode ( string request, string string)Note : recode() est un alias de recode_string(). Elle a été ajoutée en PHP 4.
LXXXVII. Expressions régulières compatibles Perl
La syntaxe des masques utilisés dans ces fonctions ressemble fort à celle de Perl. Les expressions seront entourées de délimiteurs, slash (/), par exemple. N'importe quel caractère peut servir de délimiteur, tant qu'il n'est pas alpha-numérique ou n'est pas un antislash (\). Si un délimiteur doit être utilisé dans l'expression, il faudra l'échapper avec un antislash. Depuis PHP 4.0.4, vous pouvez utiliser les délimiteurs (), {}, [], et <>, comme en Perl.
Le délimiteur final peut être suivi d'options qui affecteront la recherche. Voir aussi options de recherche.
Note : Les expressions régulières Perl sont disponibles depuis la PHP 4 et PHP 3.0.9.
Le support des expressions régulières est assuré par la librairie PCRE, qui est open source, et écrite par Philip Hazel. Elle est soumise au copyright de l'University of Cambridge, Angleterre. Elle est disponible à ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/.
- Table des matières
- options de recherche -- Options disponibles pour les expressions régulières.
- syntaxe des masques -- Fonctionnement des expressions régulières.
- preg_grep -- Retourne un tableau avec les résultat de la recherche.
- preg_match_all -- Expression régulière globale.
- preg_match -- Expression régulière standard.
- preg_quote -- Echappement des caractères spéciaux des expressions régulières.
- preg_replace_callback -- Rechercher/remplacer avec fonction de callback
- preg_replace -- Rechercher et remplacer par expression régulière standard.
- preg_split -- Eclatement d'une chaîne par expression régulière.
options de recherche
Description
Les options de PCRE sont listées ci-dessous. Les noms entre parenthèses sont les noms internes à PCRE.
- i (PCRE_CASELESS)
Effectue une recherche insensible à la casse.
- m (PCRE_MULTILINE)
Par défaut, PCRE traite la chaîne sujet comme une seule ligne (même si cette chaîne contient des retours chariot). Le méta-caractère "début de ligne" (^) ne sera valable qu'une seule fois, au début de la ligne, et le méta caractère "fin de ligne " ($) ne sera valable qu'à la fin de la chaîne, ou avant le retour chariot final (à moins que l'option D ne soit activée). C'est le même fonctionnement qu'en Perl.
Lorsque cette option est activée, " début de ligne " et " fin de ligne " correspondront alors aux caractères suivant et précédent immédiatement un caractère de nouvelle ligne, en plus du début et de la fin de la chaîne. C'est le même fonctionnement que l'option Perl /m. S'il n'y a pas de caractère de nouvelle ligne "\n" dans la chaîne sujet, ou s'il n'y a aucune occurrence de ^ ou $ dans le masque, cette option ne sert à rien.
- s (PCRE_DOTALL)
Avec cette option, le méta caractère point (.) remplace n'importe quel caractère, y compris les nouvelles lignes. Sans cette option, le caractère point ne remplace pas les nouvelles lignes. Cette option est équivalente à l'option Perl /s. Une classe de caractères négative telle que [^a] acceptera toujours les caractères de nouvelles lignes, indépendamment de cette option.
- x (PCRE_EXTENDED)
Avec cette option, les caractères d'espacement sont ignorés, sauf lorsqu'ils sont échappés, ou à l'intérieur d'une classe de caractères, et tous les caractères entre # non échappés et en dehors d'une classe de caractères, et le prochain caractère de nouvelle ligne sont ignorés. C'est l'équivalent Perl de l'option /x : elle permet l'ajout de commentaires dans les masques compliqués. Notez bien, cependant, que cela ne s'appliquent qu'aux caractères de données. Les caractères d'espacement ne doivent jamais apparaître dans les séquences spéciales d'un masque, comme par exemple dans la séquence (?( qui introduit une parenthèse conditionnelle.
- E
Avec cette option, preg_replace() effectue la substitution normale des références arrières dans la chaîne de remplacement, puis l'évalue comme un code PHP, et utilise le résultat pour remplacer la chaîne de recherche.
Seule preg_replace() utilise cette option. Elle est ignorée par les autres.
- A (PCRE_ANCHORED)
Avec cette option, le masque est ancré de force, c'est-à-dire que le masque doit s'appliquer entre le début et la fin de la chaîne sujet pour être considéré comme trouvé. Il est possible de réaliser le même effet en ajoutant les méta-caractères adéquats, ce qui est la seule manière de le faire en Perl.
- E (PCRE_DOLLAR_ENDONLY)
Avec cette option, le méta-caractère $ ne sera valable qu'à la fin de la chaîne sujet. Sans cette option, $ est aussi valable avant une nouvelle ligne, si cette dernière est le dernier caractère de la chaîne. Cette option est ignorée si l'option m est activée. Il n'y a pas d'équivalent en Perl.
- S
Lorsqu'un masque est utilisé plusieurs fois, cela vaut la peine de passer quelques instants de plus pour l'analyser et optimiser le code pour accélérer les traitements ultérieurs. Cette option force cette analyse plus poussée. Actuellement, cette analyse n'est utile que pour les masques non ancrés, qui ne commencent pas par un caractère fixe.
- U (PCRE_UNGREEDY)
Cette option inverse la tendance à la gourmandise des expressions régulières. Vous pouvez aussi inverser cette tendance au coup par coup avec un ?. De même, si cette option est activée, le ? rendra gourmand une séquence. Cette option n'est pas compatible avec Perl. Elle peut aussi être mise dans le masque avec l'option ?U.
- X (PCRE_EXTRA)
Cette option ajoute d'autres fonctionnalités incompatible avec le PCRE de Perl. Tous les antislash suivis d'une lettre qui n'aurait pas de signification particulière cause une erreur, permettant la réservation de ces combinaisons pour des ajouts fonctionnels ultérieurs. Par défaut, comme en Perl, les antislash suivis d'une lettre sans signification particulière sont traités comme des valeurs littérales. Actuellement, cette option ne déclenche pas d'autres fonctions.
- u (PCRE_UTF8)
Cette option inactive les fonctionnalités additionnelles de PCRE qui ne sont pas compatibles avec Perl. Les chaînes sont traitées comme des chaînes UTF-8. Cette option est disponible en PHP 4.1.0 et plus récent.
syntaxe des masques
Description
La bibliothèque PCRE est un ensemble de fonctions qui implémentent la recherche par expressions régulières, en utilisant la même syntaxe et la même sémantique que le Perl 5, avec quelques nuances (voir ci-dessous). L'implémentation actuelle est celle de Perl 5.005.
Différences avec Perl
Les différences avec le Perl 5.005 sont présentée ici :
Par défaut, un caractère d'espacement correspond à n'importe quel caractère que la fonction C isspace() reconnaît, bien qu'il soit possible de recompiler la bibliothèque PCRE avec d'autres tables de caractères. Normalement, isspace() retourne TRUE pour les espaces, les retours chariot, les nouvelles lignes, les formfeed, les tabulations verticales et horizontales. Le Perl 5 n'accepte plus la tabulation verticale comme caractère d'espacement. La séquence \v qui était dans la documentation Perl depuis longtemps n'a jamais été reconnue. Cependant, la tabulation verticale elle-même était reconnue comme un caractère d'espacement jusqu'à la version 5.002. Avec les version 5.004 et 5.005, l'option \s l'ignore.
PRCE ne tolère pas la répétition de quantificateurs dans les expressions. Perl le permet, mais cela ne signifie pas ce que vous pourriez penser. Par exemple, (?!a){3} ne s'interprète pas : les trois caractères suivants ne sont pas des "a". En fait, cela s'interprète comme : le caractère suivant n'est pas "a" trois fois.
Les occurrences de sous-masques qui interviennent dans des assertions négatives sont comptées, mais elles ne sont pas enregistrées dans le vecteur d'occurrences. Perl modifie ses variables numériques pour toutes les occurrences de sous-masque, avant que l'assertion ne vérifie le masque entier, et uniquement si les sous-masques ne trouvent qu'une seule occurrence.
Bien que les caractères nul soient tolérés dans la chaîne de recherche, ils ne sont pas acceptés dans le masque, car le masque est utilisé comme une chaîne C standard, terminée par le caractère nul. Il faut donc utiliser la séquence d'échappement "\0" dans le masque pour rechercher les caractères nul.
Les séquence d'échappement suivantes ne sont pas supportées par le Perl: \l, \u, \L, \U, \E, \Q. En fait, elles sont implémentées par la gestion intrinsèque de chaînes du Perl, et ne font pas partie de ses caractères spéciaux.
L'assertion \G du Perl n'est pas supportée car elle n'est pas pertinente pour faire des recherches avec des masques uniques.
De manière assez évidente, PCRE n'accepte pas la construction (?{code}).
Au moment de l'écriture de PCRE, Perl 5.005_02 avait quelques comportements étranges avec la capture des chaînes lorsqu'une partie du masque est redoublée. Par exemple, "aba" avec le masque /^(a(b)?)+$/ va affecter à $2 la valeur "b", mais la même manipulation avec "aabbaa" et /^(aa(bb)?)+$/ laissera $2 vide. Cependant, si le masque est remplacé par /^(aa(b(b))?)+$/ alors $2 (et d'ailleurs $3) seront correctement affectés. Avec le Perl 5.004, $2 sera correctement affecté dans les deux cas, et c'est aussi vrai avec PCRE. Si Perl évolue vers un autre comportement cohérent, PCRE s'adaptera probablement.
Une autre différence encore non résolue est le fait qu'en Perl 5.005_02 le masque /^(a)?(?(1)a|b)+$/ accepte la chaîne "a", tandis que PCRE ne l'accepte pas. Cependant, que ce soit avec Perl ou PCRE /^(a)?a/ et "a" laisseront $1 vide.
PCRE propose quelques extensions aux expressions régulières du Perl.
(a) Bien que les assertions avec retour (lookbehind) soit obligée d'apparier une chaîne de longueur fixe, toutes les assertions avec retour peuvent avoir une longueur différente. Perl 5.005 leur impose d'avoir toutes la même longueur.
(b) Si PCRE_DOLLAR_ENDONLY est activé, et que PCRE_MULTILINE n'est pas activé, le méta caractère $ ne s'applique qu'à la fin physique de la chaîne, et non pas avant les caractères de nouvelle ligne.
(c) Si PCRE_EXTRA est activé, un antislash suivi d'une lettre sans signification spéciale est considérée comme une erreur.
(d) SI PCRE_UNGREEDY est activé, la "gourmandise" des quantificateurs de répétition est inversées, ce qui est rend non gourmand par défaut, mais s'ils sont suivis de ?, il seront gourmands.
Détails sur les expressions régulières
Introduction
La syntaxe et la sémantique des expressions régulière supportées par PCRE sont décrites ci-dessous. Les expressions régulières sont aussi décrites dans la documentation Perl, et dans un grand nombre d'autres livres, avec de nombreux exemples. Jeffrey Friedl's "Mastering Regular Expressions", édité chez O'Reilly (ISBN 1-56592-257-3), les décrits en profondeur. Cette description est organisée comme une documentation de référence.
Une expression régulière est un masque, appliqué à une chaîne sujet, de gauche à droite. La plupart des caractères se représentent eux-mêmes. Un exemple trivial : un masque qui serait "Le rapide renard gris", pourra correspondre à une partie de la chaîne sujet qui sera identique au masque, comme par exemple "Le rapide renard gris court dans la forêt",
Méta-caractères
La puissance des expressions régulières provient de leur capacité à autoriser des alternatives et des quantificateurs de répétition dans le masque. Ils sont encodés dans le masque par des méta-caractères, qui ne représentent pas ce qu'ils sont, mais sont interprétés d'une certaine manière.
Il y a deux sortes de méta-caractères : ceux qui sont reconnus n'importe où dans un masque, hormis entre crochets, et ceux qui sont reconnus entre crochets.
A l'extérieur des crochets, les méta caractères sont :
- / antislash
Caractère d'échappement, avec de multiples usages
- ^ Accent circonflexe
Le début de la chaîne sujet (ou de ligne, en mode multiligne)
- $ Dollar
La fin de la chaîne sujet (ou de ligne, en mode multiligne)
- . Point
Remplace n'importe quel caractère, hormis le caractère de nouvelle ligne (par défaut) ;
- [ Crochet ouvrant
Caractère de début de définition de classe
- ] Crochet fermant
Caractère de fin de définition de classe
- | Barre verticale
Caractère de début d'alternative
- ( Parenthèse ouvrante
Caractère de début de sous-masque
- ) Parenthèse fermante
Caractère de fin de sous-masque
- ? Point d'interrogation
Etend le sens de (; quantificateur de 0 ou 1; quantificateur de minimisation
- * Etoile
Quantificateur de 0 ou plus
- + Plus
Quantificateur de 1 ou plus
- { Accolade ouvrante
Caractère de début de quantificateur minimum/maximum
- } Accolade fermante
Caractère de fin de quantificateur minimum/maximum
La partie du masque qui est entourée de crochet et appelé une classe de caractères. Dans les classes de caractères, les seuls méta caractères autorisés sont :
- \ Antislash
Caractère d'échappement, avec de multiples usages
- ^ Accent circonflexe
Négation de la classe, mais uniquement si placé tout au début de la classe
- - Moins
Indique un intervalle de caractères
- ] Crochet fermant
Termine la classe de caractères
Antislash
Le caractère antislash a de nombreuses utilisations.
En premier lieu, s'il est suivi d'un caractère non alpha-numérique, il ne prendra pas la signification spéciale qui y est rattachée. Cette utilisation de l'antislash comme caractère d'échappement s'applique à l'intérieur et à l'extérieur des classes de caractères. Par exemple, pour recherche le caractère étoile "*", il faut écrire dans le masque : "\*". Cela s'applique dans tous les cas, que le caractère qui suive soit un méta-caractère ou non. C'est un moyen sÛr pour s'assurer qu'un caractère sera recherché pour sa valeur littérale, plutôt que pour sa valeur spéciale. En particulier, pour rechercher les antislash, il faut écrire : "\\".
Si un masque est utilisé avec l'option PCRE_EXTENDED, les espaces blancs du masque, mais qui ne sont pas dans une classe de caractères, et les caractères entre dièses "#", ainsi que les nouvelles lignes sont ignorées. L'antislash peut être utilisé pour échapper et ainsi rechercher un espace ou un dièse.
La deuxième utilité de l'antislash est de pouvoir coder des caractères invisibles dans les masques. Il n'y a pas de restriction sur la place de ces caractères invisibles, hormis pour le caractère nul qui doit terminer le masque.
Lors de la préparation du masque, il est souvent plus pratique d'utiliser les séquences d'échappement suivantes, plutôt que le caractère binaire qu'elle représente :
- \a
alarme, c'est-à-dire le caractère BEL (hex 07)
- \cx
"control-x", avec x qui peut être n'importe quel caractère.
- \e
escape (hex 1B)
- \f
formfeed (hex 0C)
- \n
nouvelle ligne (hex 0A)
- \r
retour chariot (hex 0D)
- \t
tabulation (hex 09)
- \xhh
caractère en hexadécimal, de code hh
- \ddd
caractère en octal, de code ddd, ou référence arrière
Dans la séquence "\cx" si "x" est en minuscule, il est converti en majuscule. Puis, le bit 6 (hex 40) est inversé. Ainsi "\cz" devient 1A, mais "\c{" devient hex 3B, tandis que "\c;" devient hex 7B.
Après "\x", deux caractères hexadécimaeux sont lus (les lettres peuvent être en majuscule ou minuscule).
Après "\0", deux caractères octal sont lus. Dans chacun des cas, le méta-caractère tente de lire autant de caractère que possible. Ainsi la séquence "\0\x\07", sera comprise comme deux caractères nuls, suivi d'un caractère alarme (BEL). Assurez-vous que vous fournissez suffisamment de chiffres après le méta-caractère.
La gestion de la séquence "\y", avec y <> 0 est plutôt compliquée. En dehors des caractères de classes, PCRE va lire y et tous les caractères qui suivent comme des chiffres décimaux. Si y est plus petit que 10, ou bien s'il y a déjà eu au moins autant de parenthèses ouvrantes auparavant, la séquence est prise pour une référence arrière. Le détail sera vu ultérieurement, après la section sur les sous-masques.
A l'intérieur d'un caractère de classe, ou si y est plus grand que 10, et qu'il n'y a pas eu assez de parenthèses ouvrantes auparavant, PCRE lis jusqu'à 3 chiffres octals à la suite de l'antislash, et génère un octet unique, à partir des 8 bits de poids faible de la séquence. Tous les chiffres qui suivent ne sont pas interprétés, et se representent eux-mêmes. Par exemple:
- \040
une autre manière d'écrire un espace
- \40
identique, dans la mesure où il n'y a pas 40 parenthèses ouvrantes auparavant
- \7
est toujours une référence arrière
- \11
peut être une référence de retour, ou une tabulation
- \011
toujours une tabulation
- \0113
est une tabulation suivi du caractère "3"
- \113
est le caractère 113 (étant donné qu'il ne peut y avoir plus de 99 références arrières)
- \377
est un octet dont tous les bits sont à 1
- \0113
peut être soit une référence arrière, soit le caractère NULL, suivi des caractères "8" et "1"
Les valeurs octales supérieures ou égales à 100 ne doivent pas être introduites par un 0, car seuls les trois premiers octets seront lus.
Toutes les séquences qui définissent une valeur d'un seul octet peuvent être utilisé dans les classes de caractères, et à l'extérieur. De plus, dans une classe de caractères, la séquence "\b" est interprétée comme un caractère effacer (backspace, hex 08). A l'extérieur d'une classe de caractères, il peut avoir d'autres significations (voir ci-dessous).
On peut encore se servir de l'antislash pour préciser des types génériques de valeurs :
- \d
tout caractère décimal
- \D
tout caractère qui n'est pas un caractère décimal
- \S
tout caractère blanc
- \s
tout caractère qui n'est pas un caractère blanc
- \W
tout caractère de "mot"
- \w
tout caractère qui n'est pas un caractère de "mot"
Chaque paire précédente définit une partition de la table des caractères : les deux ensembles sont disjoints. Un caractère satisfera soit un méta-caractère, soit l'autre.
Un caractère de "mot" sera une lettre, un chiffre ou le caractère souligné, c'est-à-dire un caractère qui pourra être une partie d'un mot Perl. La définition des lettres et chiffres est définie par les tables de caractères de PCRE, et peut varier suivant la table locale de caractère (voir "Tables de caractères locales ", ci-dessus. Par exemple, dans la configuration français ("fr"), certains caractères ont des codes supérieurs à 128, pour les caractères accentués, et ils seront compris par le méta caractère \w.
Ces séquences de caractères peuvent apparaître à l'intérieur ou à l'extérieur des classes de caractères. Elles remplacent à chaque fois un caractère du type correspondant. Si cette séquence est placée en fin de masque, et qu'il n'y a plus de caractère à comparer dans la chaîne sujet, la recherche échoue.
La quatrième utilisation de l'antislash intervient lors d'assertions simples. Une assertion impose une condition à un certain point, sans remplacer de caractère. L'utilisation de sous-masques pour réaliser des assertions plus complexes est décrites plus-bas. Les assertions avec antislash sont les suivantes :
- \b
limite de mot
- \B
pas limite de mot
- \A
début de la chaîne sujet (indépendant du mode multi-lignes)
- \Z
fin de la chaîne sujet ou nouvelle ligne à la fin de la chaîne sujet (indépendant du mode multi-lignes)
- \z
fin de la chaîne sujet (indépendant du mode multi-lignes)
Ces assertions ne peuvent pas apparaître dans une classe de caractères (mais "\b" a une autre signification à l'intérieur d'une classe de caractères).
Une limite de mot est un emplacement dans la chaîne sujet ou un caractère et son suivant ne sont pas en même temps des caractères de mot, ou le contraire (on peut le voir comme \w\W ou \W\w), ou encore le premier ou le dernier caractère est un caractère mot.
Les assertions \A, \Z, et \z diffèrent des méta caractères ^ et $ dans la mesure où ils ne sont pas dépendants des options, notamment PCRE_NOTBOL ou PCRE_NOTEOL. La différence entre \Z et \z tient au fait que \Z recherche les positions avant les nouvelles lignes et à la fin de la chaîne sujet, tandis que \z ne recherche que la fin de la chaîne.
Accent circonflexe et Dollar
En dehors d'une classe de caractères, avec les options par défaut, ^ est une assertion qui n'est vraie que si elle est placée tout au début de la chaîne. A l'intérieur d'une classe de caractères, ^ a un tout autre sens (voir ci-dessous).
^ n'a pas besoin d'être le premier caractère du masque, si plusieurs alternatives sont proposées, mais il doit être placé en premier dans chaque alternative. Si toutes les alternatives commencent par ^, alors le masque est dit ancré (il y a une autre construction qui porte cette appellation).
$ est une assertion qui n'est vraie que si elle est placée tout en fin de chaîne ou juste avant un caractère de nouvelle ligne qui serait le dernier caractère de la chaîne. A l'intérieur d'une classe de caractères, $ a un tout autre sens (voir ci-dessous).
$ n'a pas besoin d'être le dernier caractère du masque, si plusieurs alternatives sont proposées, mais il doit être placé en dernier dans chaque alternative. Si toutes les alternatives finissent par $, alors le masque est dit ancré (il y a une autre construction qui porte cette appellation). $ n'a pas de valeur particulière dans une classe de caractères.
La signification de $ peut changer, de manière à l'amener à ce qu'il ne puisse se trouver qu'en toute fin de la chaîne sujet. Cela se fait en ajoutant l'option PCRE_DOLLAR_ENDONLY au moment de la compilation, ou de l'exécution. Cette option est inopérante sur \Z.
La signification de ^ peut changer, de manière à l'amener à ce qu'il puisse se trouver immédiatement avant et immédiatement après un caractère de nouvelle ligne "\n". Cela se fait en ajoutant l'option PCRE_MULTILINE au moment de la compilation ou de l'exécution. Par exemple, le masque /^abc$/ accepte la chaîne "def\nabc" uniquement en mode multi-lignes. Par conséquent, toutes les parties du masques qui commencent par "^" ne sont pas ancrées, en mode multi-lignes. L'option PCRE_DOLLAR_ENDONLY est ignorée si l'option PCRE_MULTILINE est choisie.
Notez que les méta caractères \A, \Z, et \z peuvent servir à répérer le début et la fin du sujet, et toutes les parties du masque qui commenceront par \A seront toujours ancrées, avec l'option PCRE_MULTILINE ou non.
Point
En dehors d'une classe de caractères, un point remplace n'importe quel caractère, même invisible et à l'exception du caractère de nouvelle ligne. Avec l'option PCRE_DOTALL le point remplace n'importe quel caractère, même le caractère de nouvelle ligne. La gestion des points et complètement indépendante de ^ et $. Le seul point commun est que les deux ont un comportement particulier vis à vis des caractère de nouvelle ligne.
Le point n'a pas de comportement particulier dans une classe de caractères.
Crochets
Un crochet ouvrant [ introduit une classe de caractères, et le crochet fermant ]la conclut. Le crochet fermant n'a pas de signification en lui-même. Si le crochet fermant est nécessaire à l'intérieur d'une classe de caractères, il faut qu'il soit le premier caractère (après un ^ éventuel) ou échappé avec un antislash.
Une classe de caractères remplace un seul caractère dans la chaîne sujet, à moins que le premier caractère de la classe soit un accent circonflexe ^, qui représente une négation : le caractère ne doit pas se trouver dans la classe. Si ^ est nécessaire dans la classe, il suffit qu'il ne soit pas le premier caractère, ou bien qu'il soit échappé avec un antislash.
Par exemple, le caractère [aeiou] remplace n'importe quelle voyelle minuscule, tandis que [^aeiou] remplace n'importe quelle caractère qui n'est pas une voyelle minuscule. ^ est une notation pratique pour spécifier des caractères qui sont dans une classe, en ne citant que ceux qui n'y sont pas. Le comportement est inchangé.
Avec l'option d'insensibilité à la casse, toutes les lettres d'une classe de caractères représentent en même temps la majuscule et la minuscule. Par exemple, [aeiou] représentera "A" ou "a", et [^aeiou] n'acceptera pas ni "A", tandis que sans l'option, elle l'accepterait.
Le caractère de nouvelle ligne n'est pas traité de manière spéciale dans les classes de caractères, quelque soit l'option PCRE_DOTALL ou PCRE_MULTILINE. Une classe telle que [^a] acceptera toujours une nouvelle ligne.
Le signe moins (-) est utilisé pour spécifier un intervalle de caractères, dans une classe. Par exemple, [d-m] remplace toutes les lettres entre d et m inclus. Si le caractère moins est requis dans une classe, il faut l'échapper avec un antislash, ou le faire apparaître à une position ou il ne pourra pas être interprété comme une indication d'intervalle, c'est-à-dire au début ou à la fin de la classe.
Il n'est pas possible d'avoir le caractère crochet fermant "]" comme fin d'intervalle. Un masque tel que [W-]46] est compris comme la classe de caractères contenant deux caractères ("W" et "-") suivi de la chaîne littérale "46]", ce qui fait qu'il va accepter "W46]" ou "-46]". Cependant, si "]" est échappé avec un antislash, le masque [W-\]46] est interprété comme une classe d'un seul caractère, contenant un intervalle de caractères.
La valeur octale ou hexadécimale de "]" peut aussi être utilisée pour déterminer les limites de l'intervalle. Les intervalles travaillent sur des séquences ASCII. Ils peuvent aussi être précisées avec des valeurs numériques, par exemple "[\000-\037]". Si cet intervalle inclut des lettres utilisées avec une option d'insensibilité de casse, les majuscules ou minuscules correspondantes seront aussi incluses. Par exemple, "[C-c]" est équivalent é "[][\^_`wxyzabc]", avec l'option d'insensibilité de casse. Si la table locale de caractères est "fr", "[\xc8-\xcb]" correspond aux caractères accentués.
Les types de caractères \d, \D, \S, \s, \w, \W peuvent aussi intervenir dans les classes de caractères. Par exemple, "[][\^_`wxyzabc][\dABCDEF]" acceptera n'importe quel caractère hexadécimal. Un accent circonflexe peut aussi être utilisé pour spécifier adroitement des ensembles de caractères plus restrictifs : par exemple [^\W_] accepte toutes les lettres et les chiffres, mais pas les soulignés. Tous les caractères non alpha- numériques autres que \, -, ^ (placés en début de chaîne) et ] n'ont pas de signification particulière, mais ils ne perdront rien à être échappés.
Barre verticale
La barre verticale | sert à séparer des alternatives. Par exemple, dans le masque "/dupont|martin/" recherche soit "dupont", soit "martin". Le nombre d'alternatives n'est pas limité, et il est même possible d'utiliser la chaîne vide. Lors de la recherche, toutes les alternatives sont essayées, de gauche à droite, et la première qui est acceptée est utilisée.
Si les alternatives sont dans un sous-masque, elle ne réussiront que si le masque principal réussi aussi.
Options internes
Les options PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL et PCRE_EXTENDED peuvent être changée à l'intérieur du masque lui-même, avec des séquences mises entre "(?" et ")". Les options sont :
- i
PCRE_CASELESS
- m
PCRE_MULTILINE
- s
PCRE_DOTALL
- x
PCRE_EXTENDED
Le domaine d'application de ces options dépend de la position de la séquence d'option. Pour toutes les séquences d'options qui sont hors des sous-masques (définis plus loin), l'effet est le même que si l'option avait été fixée dès le début de la recherche. Les exemples suivants se comportent tous de la même façons : (?i)abc, a(?i)bc, ab(?i)c, abc(?i), et sont parfaitement équivalents au masque abc avec l'option PCRE_CASELESS. En d'autres termes, activer des séquences d'options dans le corps principal du masque revient à appliquer l'option à tout le masque, sauf ordre contraire dans les sous-masques. S'il y a plusieurs séquences d'options qui portent sur la même option, la dernière s'appliquera.
Si une option intervient dans un sous-masque, le comportement est différent. C'est un changement de comportement apparu en Perl 5.005. Une option à l'intérieur d'un sous-masque n'affecte que cette partie du masque, ce qui fait que (a(?i)b)c acceptera abc et aBc mais aucune autre chaîne (en supposant que PCRE_CASELESS n'est pas utilisé). Cela signifie que les options permettent d'avoir différente configuration de recherche pour différentes parties du masque.
Une séquence d'options dans une alternative affecte toute l'alternative. Par exemple : (a(?i)b|c) accepte "ab", "aB", "c", et "C", même si, comme dans le cas de "C", la première alternative qui porte l'option n'est pas prise en compte. Sinon, cela risque d'introduire des comportements très étranges : les options spécifiques à PCRE telles que PCRE_UNGREEDY et PCRE_EXTRA peuvent être modifiées de la même manière, en utilisant respectivement les caractères U et X. L'option (?X) est particulière, car elle doit toujours intervenir avant toutes les autres options, même au niveau du masque entier. Il vaut mieux l'activer au début du masque.
Sous-masques
Les sous-masques sont délimités par des parenthèses, et peuvent être imbriquées. Ajouter des sous-masques a deux utilités :
1. Délimiter des alternatives. Par exemple, le masque char(don|mant|) acceptera les mots "char", "charmant", ou "charmant". Sans les parenthèses, il n'accepterait que "chardon", "mant" ou la chaîne vide "".
2. Le sous-masque est considéré comme capturant : lorsqu'une chaîne sujet est acceptée par le masque complet, les sous-masques sont transmis à l'appelant grâce à un vecteur de sous-masques. Les parenthèses ouvrantes sont comptées de gauche à droite, (commençant à 1). Par exemple, soit la chaîne sujet "le roi soleil" qui est utilisée avec le masque suivant : Le ((roi|prince) (soleil|charmant)) les sous-masques capturé sont "roi soleil", "roi", et "soleil", numérotés respectivement 1, 2, et 3.
L'ubiquité des parenthèses n'est pas toujours simple d'emploi. Il y a des moments où regrouper des sous-masques est nécessaire, sans pour autant capturer la valeur trouvée. Si une parenthèse ouvrante est suivie de "?:", le sous-masque ne capture pas la chaîne assortie, et ne sera pas compté lors de la numérotation des captures. Par exemple, avec la chaîne "le prince charmant", utilisé avec le masque Le (( ?roi|prince) (soleil|charmant)) les chaînes capturées seront "prince charmant" et "charmant", numérotés respectivement 1 et 2.
Le nombre maximal de chaîne capturées est de 99, et le nombre total de sous-masque (capturant ou non) ne doit pas dépasser 200.
(?i:samedi|dimanche) et (?:(?i) samedi | dimanche) : De plus, comme les séquences d'options sont valables sur toute une alternative, les masques ci-dessus accepteront aussi bien "DIMANCHE" que "Dimanche".
Répétitions
Les répétitions sont spécifiées avec des quantificateurs, qui peuvent être placés à la suite des caractères suivants :
- a
Un caractère unique, même s'il s'agit d'un méta caractère
- [abc]
Une classe de caractères
- \2
Une référence de retour (Voir section suivante)
- (a|b|c)
Un sous-masque avec parenthèses (à moins que ce ne soit une assertion, voir plus loin)
Les quantificateurs généraux précisent un nombre minimum et maximum de répétitions possibles, donnés par deux nombres entre accolades, et séparés par une virgule. Ces nombres doivent être plus petits que 65536, et le premier nombre doit être égal ou inférieur au second. Par exemple z{2,4} accepte "zz", "zzz", ou "zzzz". L'accolade fermante n'a pas de signification par elle-même.
Si le second nombre est omis, mais que la virgule est là, cela signifie qu'il n'y a pas de limite supérieure. Si le second nombre et la virgule sont omis, le quantificateur correspond au nombre exact de répétition attendues. Par exemple : accepte n'importe quelle succession d'au moins 3 voyelles minuscules, tandis que \d{d} n'accepte que 8 chiffres exactement.
Une accolade ouvrante qui apparaît à une position où un quantificateur n'est pas accepté, ou si la syntaxe des quantificateurs n'est pas respectée, sera considérée littérale. Par exemple, "{,6}" n'est pas un quantificateur, mais une chaîne de 4 caractères.
Le quantificateur {0} est autorisé, mais l'expression est alors ignorée.
- *
équivalent à {0,}
- +
équivalent à {1,}
- ?
équivalent à {0,1}
Il est possible de constituer des boucles infinies en créant un sous-masque sans caractères, mais pourvu d'un quantificateur sans limite supérieure. Par exemple "(a?)*.
Les versions plus anciennes de Perl et PCRE généraient alors une erreur au moment de la compilation. Cependant, étant donné qu'il existe des situations où ces constructions peuvent être utiles, ces masques sont désormais autorisés. Cependant, si la répétion du sous-masque ne trouve aucun caractère, la boucle est interrompue.
Par défaut, les quantificateurs sont dits "gourmands", c'est à dire, qu'ils cherchent d'abord à trouve le nombre maximal de répétitions qui autorise le succès de la recherche. L'exemple classique posé par cette gourmandise est la recherche de commentaires d'un programme en C. Les commentaires apparaissent entre les séquences /*....*/ et à l'intérieur de ces délimiteurs, les * et / sont autorisés. Appliquer le masque /\*.*\*/ à la chaîne /* first commet */ not comment /* second comment */ ne peut réussir, car le masque travaille sur toute la chaîne, à cause de la gourmandise du caractère .*.
Cependant, un quantificateur suivi d'un point d'interrogation cesse d'être gourmand, et au contraire, ne recherche que le nombre minimum de répétition. Dans ces conditions, le masque /\*.*?\*/ trouvera bien les commentaires du code C. La signification des autres quantificateurs n'est pas changée.
Attention à ne pas confondre l'utilisation du point d'interrogation ici avec son utilisation comme quantificateur lui-même. A cause cette ambiguité, il peut apparaître des situations où il faut le doubler : \d??\d. Ce masque va tenter de lire un seul chiffre, mais le cas échéant, il acceptera 2 chiffres pour permettre à la recherche d'aboutir. Si l'option PCRE_UNGREEDY est activée, (une option qui n'est pas disponible avec Perl) alors les quantificateurs sont non gourmand par défaut, mais peuvent être rendu gourmand au cas par cas, en ajoutant un point d'interrogation après. En d'autres termes, cette option inverse le comportement par défaut.
Lorsqu'un sous-masque est quantifié avec un nombre minimum de répétitions, qui soit plus grand que 1, ou avec un maximum de répétitions, le masque compilé aura besoin de plus de place de stockage, proportionnellement au minimum et au maximum.
Si un masque commence par ..* ou .{0,} et que l'option PCRE_DOTALL (équivalent en Perl à /s) est activée, c'est-à-dire en autorisant le remplacement des nouvelles lignes par un méta-caractère, alors le masque est implicitement ancré, car tout ce qui suit va être mangé par la première séquence, et se comportera comme si le masque se terminait par le méta caractère \A. Dans le cas où on sait d'avance qu'il n'y aura pas de caractère de nouvelle ligne, activer l'option PCRE_DOTALL et commencer le masque par .* permet d'optmiser le masque.
Alternativement, on peut utiliser ^ pour ancrer explicitement le masque. Lorsqu'un sous-masque capturant est répété, la valeur capturée est la dernière. Par exemple, après que "(inter[net]{3}\s*)+" ai été appliqué à "internet interne", la valeur de la chaîne capturée est "interne".
Cependant, s'il y a des sous-masques imbriqués, la valeur capturée correspondante peut l'avoir été lors des précédentes itérations. Par exemple : /(a|(b))+/ accepte "aba" et la deuxième valeur capturée est "b".
Références arrières
En dehors des classes de caractères, un antislash suivi d'un nombre plus grand que 0 (et possiblement plusieurs chiffres) est une référence arrière (c'est à dire vers la gauche) dans le masque, en supposant qu'il y ait suffisamment de sous-masques capturants précédants.
Cependant, si le nombre décimal suivant l'antislash est plus petit que 10, il sera toujours considéré comme une référence arrière, et cela génèrera une erreur si le nombre de capture n'est pas suffisant. En d'autres termes, il faut qu'il existe suffisamment de parenthèses ouvrantes à gauche de la référence, surtout si la référence est inférieure à 10.
Reportez-vous à la section "antislash" pour avoir de plus amples détails à propos du nombre de chiffres qui suivent l'antislash.
La référence arrière remplace ce qui a été capturé par un sous-masque dans le masque courant, plutôt que remplace le sous-masque lui-même. Ainsi (calme|rapide) et \1ment trouvera "calme et calmement" et "rapide et rapidement", mais pas "calme et rapidement". Si la recherche tient compte de la casse, alors la casse de la chaîne capturée sera importante. Par exemple, ((?i)rah)\s+\1 trouve "rah rah" et "RAH RAH", mais pas "RAH rah", même si le sous-masque capturant initial ne tenait pas compte de la casse.
Il peut y avoir plusieurs références arrières dans le même sous-masque. Si un sous-masque n'a pas été utilisé dans une recherche, alors les références arrières échoueront. Par exemple "(a|(bc))\2" ne réussira jamais si la chaîne sujet commence par "a" plutôt que par "bc".
Etant donné qu'il peyt y avoir jusqu'à 99 références arrières, tous les chiffres après l'antislash sont considérés comment faisant potentiellement partie de la référence arrière. Si le masque recherche un chiffre après la référence, alors il faut impérativement utiliser des délimiteurs pour terminer la référence arrière.
> Si l'option PCRE_EXTENDED est activée, on peut utiliser un espace. Sinon, un commentaire vide fait l'affaire. Une référence arrière qui intervient à l'intérieur de parenthèses auquel elle fait référence échouera dès que le sous-masque sera utilisé. Par exemple, (a\1) échouera toujours. Cependant, ces références peuvent être utiles dans les sous-masques répétitifs. Par exemple, le masque "(a|b\1)+" pourra convenir pour "a", "aba", "ababaa", etc....
A chaque itération du sous-masque, la référence arrière utilise le résultat du dernier sous-masque. Pour que cela fonctionne, il faut que la première itération n'ai pas besoin d'utiliser la référence arrière. Cela arrive avec les alternatives, comme dans l'exemple ci-dessus, ou avec un quantificateur de minimum 0.
Assertions
Une assertion est un test sur les caractères suivants ou précédent celui qui est en cours d'étude. Ce test ne consomme par de caractère (ie, on ne déplace pas le pointeur de caractères). Les assertions simples sont codées avec \b, \B, \A, \Z, \z, ^ et $, et sont décrites précédemment.
Il existe cependant un type d'assertions plus complexes, codées sous la forme de sous-masques. Il en existe deux types : celles qui travaillent au-delà de la position courante (\w+(?=;)), et celles qui travaillent en deça ((?!)\w+).
Une assertion se comporte comme un sous-masque, hormis le fait qu'elle ne déplace pas le pointeur de position. Les assertions avant commencent par (?= pour les assertions positives, et par (?!, pour les assertions négatives. Par exemple : \w+(?=;) s'assure qu'un mot est suivi d'un point-virgule, mais n'inclus pas le point virgule dans la capture. D'autre part, (?!foo)bar en est proche, mais ne trouve pas une occurrence de "bar" qui soit précédée par quelque chose d'autre que "foofoo"; il trouve toutes les occurrences de "bar", quelque soit ce qui le précéde, car l'assertion (?!foo) est toujours vraie quand les trois caractères suivants sont "bar". Une assertion arrière est ici nécessaire.
Les assertions arrières commencent par (?<= pour les assertions positives, et (?<! pour les assertions négatives. Par exemple : (?<!foo)bar trouve les occurrences de "bar" qui ne sont pas précédées par "foo".
Le contenu d'une référence arrière est limité de telle façon que les chaînes qu'il utilise soient toujours de la même taille. Cependant, lorsqu'il y a plusieurs alternatives, elles n'ont pas besoin d'être de la même taille. Par exemple, (?<=bullock|donkey) est autorisé, tandis que (?<!dogs?|cats?) provoque une erreur de compilation. Les alternatives qui ont des longueurs différentes ne sont autorisées qu'au niveau supérieur des assertions arrières. C'est une amélioration du fonctionnement de Perl 5.005, qui impose aux alternatives d'avoir toutes la même taille. Une assertion telle que (?<=ab(c|de)) n'est pas autorisée, car l'assertion de bas niveau (la deuxième, ici) a deux alternatives de longueurs différentes. Pour la rendre acceptable, il faut écrire (?<=abc|abde)
L'implémentation des assertions arrières déplace temporairement le pointeur de position vers l'arrière, et cherche à vérifier l'assertion. Si le nombre de caractères est différent, la position ne sera pas correcte, et l'assertion échouera. La combinaison d'assertions arrières avec des sous-masques peut être particulièrement pratique à fin des chaînes. Un exemple est donné à la fin de cette section.
Plusieurs assertions peuvent intervenir successivement. Par exemple, le masque (?<=\d{3})(?<!999)foo recherche les chaînes "foo" précédées par trois chiffres qui ne sont pas "999". Notez que chaque assertion est appliquées indépendemment, au même point de la chaîne à traiter. Tout d'abord, il est vérifié que les trois premiers caractères ont tous des chiffres, puis on s'assure que ces trois caractères ne sont pas "999". Le masque précédant n'accepte pas "foo" précédé de 6 caractères, les trois premiers étant des chiffres et les trois suivants étant différents de "999". Par exemple, ce masque n'acceptera pas la chaîne "123abcfoo". Pour ce faire, il faut utiliser le masque suivant : (?<=\d{3}...)(?<!999)foo. Dans ce masque, la première assertion vérifie les six premiers caractères, s'assure que les trois premiers sont des entiers, et la deuxième assertion s'assure que les trois derniers caractères ne sont pas "999".
De plus, les assertions peuvent être imbriquées : (?<=(?<!foo)bar)baz recherche les occurrences de "baz" qui sont précédées par "bar", qui, à son tour, n'est pas précédé par "foo". Au contraire, (?<=\d{3}(?!999)...)foo est un autre masque, qui recherche les caractères "foo", précédés par trois chiffres, suivis trois autres caractères qui ne forment pas "999". Les assertions ne sont pas capturantes, et ne peuvent pas être répétées. Si une assertion contient des sous-masques capturants en son sein, ils seront compris dans le nombre de sous-masques capturants du masque entier. La capture est réalisée pour les assertions positives, mais cela n'a pas de sens pour les assertions négatives.
200 assertions au maximum sont autorisées.
Sous-masques uniques
Avec les quantificateurs de répétitions, l'échec d'une recherche conduit normalement à une autre recherche, avec un nombre différent de répétitions, pour voir si le masque ne s'applique pas dans d'autres conditions. Parfois, il est pratique d'éviter ce comportement, soit pour changer la nature de la recherche, soit pour la faire abandonner plus tôt, si on pense qu'il n'est pas besoin d'aller plus loin.
Considérons par exemple, le masque \d+foo appliqué à la ligne 123456bar. Après avoir tenté d'utiliser les 6 chiffres suivi de "foo" qui font échouer, l'action habituelle sera de réessayer avec 5 chiffres, puis avec 4, et ainsi de suite jusqu'à l'échec final.
Un sous-masque évalué une seule fois permettrait d'indiquer que lorsqu'une partie du masque est trouvée, elle n'a pas besoin d'être réévaluée à chaque tentative. Ceci conduirait à ce que la recherche échoue immédiatement après le premier test. Ces assertions ont leur propre notation, commençant avec (?> comme ceci : (?>\d+)bar.
Ce type de parenthèses verrouille le sous-masque qu'il contient un fois qu'il a été trouvé, et empêche un échec ultérieur d'y repasser, mais autorise à revenir plus loin en arrière. Une autre description est que les sous-masques de ce type recherche les chaînes de caractères, et les ancre le sous-masque à l'intérieur de la chaîne.
Les sous-masques uniques ne sont pas capturants. Des cas simples comme ceux présentés ci-dessus peuvent être pris comme des situations maximisantes, qui réservent le maximum de caractères. En effet, alors que \d+ et \d+? ajustent le nombre de chiffres trouvés de manière à laisser la possibilité au masque de réussir, (?>\d+) ne peut retenir que la séquence entière de chiffres. Cette construction peut contenir un nombre arbitraire de sous-masques complexes, et ils peuvent être imbriqués.
Les sous-masques uniques ne peuvent être utilisés qu'avec les assertions arrières, pour effectuer une recherche efficace en fin de chaîne. Considérons un masque simple tel que "abcd$" appliqué à une très longue chaîne qui ne lui correspond pas. A cause du système de recherche de gauche à droite, PCRE va commencer par rechercher un "a" dans la chaîne sujet, puis vérifier si ce qui suit convient au reste du masque. Si le masque est spécifié sous la forme ^.*abcd$ alors, la séquence .* remplace en premier lieu la chaîne entière, et échoue, repart en arrière, et remplace tous les caractères sauf le dernier, échoue, retourne en arrière, prend un caractère de moins, etc... et ainsi de suite. Encore une fois, la recherche du "a" passe en revue toute la chaîne de gauche à droite, ce qui n'est pas très efficace. Par contre, si le masque était écrit ^(?>.*)(?<=abcd) alors il n'y aurait pas de retour en arrière, pour satisfaire la séquence .*, car elle ne peut que remplacer toute la chaîne. L'assertion arrière consécutive va alors faire un test sur les 4 derniers caractères. Si elle échoue, la recherche est immédiatement interrompue.
Pour les chaînes très longues, cette approche fait la différence en terme de performances et de temps de recherche. Lorsqu'un masque contient une répétition illimitée dans un sous-masque, qui contient lui-même un nombre illimité de répétiteur, l'utilisation des sous-masques à utilisation unique sont la seule façon d'éviter l'échec de la recherche à après un temps de calcul trop long.
Le masque (\D+|<\d+>)*[!?] recherche un nombre illimité de sous-chaînes, qui contiennent soit des non-chiffres, soit des chiffres inclus dans <>, suivi soit par ! ou par ?. Lorsqu'il trouve une solution, ce masque va très vite. Mais, lorsqu'il est appliqué à une chaîne telle que : aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, il lui faut beaucoup de temps pour annoncer un échec. Cela est dÛ au fait que la chaine peut être divisée en deux sous-chaînes d'un grand nombre de façons, et qu'elles ont toutes été essayées. (Cet exemple utilisait [!?] plutôt qu'un caractère simple, car PCRE et PHP utilise une optimisation qui leur permettent de détecter rapidement l'échec lorsqu'un caractère unique est trouvé. Il se souvient du dernier caractère qui est attendu, et s'aperçoit rapidement qu'il n'y a pas ce caractère).
Si le masque utilisé est ((?>\D+)|<\d+>)*[!?] les séquences de chiffres ne peuvent pas être trouvées, et l'échec intervient rapidement.
Les sous-masques conditionnels
Il est possible de lier un sous-masque à une condition, ou de choisir entre deux sous-masques alternatifs, en fonction du résultat d'une assertion, ou suivant les résultats de recherche précédents.
Les deux formes possibles de sous-masques conditionnels sont (?(condition)masque positif) et (?(condition) masque positif | masque négatif).
Si les conditions sont satisfaites, le masque positif est utilisé, sinon, le masque négatif est utilisé, si présent. S'il y a plus de deux alternatives, une erreur est générée à la compilation.
Il y a deux types de conditions : si le texte entre les parenthèses est une séquence de chiffres, alors la condition est satisfaite si le sous-masque correspondant à ce numéro a réussi. Considérons le masque suivant, qui contient des espaces non significatifs pour le rendre plus compréhensible (on supposera l'option PCRE_EXTENDED activée) et qui est divisé en trois parties pour simplifier les explications : ( \( )? [^()]+ (?(1) \) ).
La première partie recherche une parenthèse ouvrante optionnelle, et si elle existe, elle est capturée. La deuxième partie recherche un séquence de caractères qui ne contiennent pas de parenthèses. La troisième partie est conditionnée à la première, et s'assure que s'il y avait une parenthèse ouvrante, il en existe une fermante. Si une parenthèse ouvrante a été trouvée, elle a été capturée, et donc la première capture existe, et la condition est exécutée. Sinon, elle est ignorée.
Ce masque recherche donc une séquence de lettres, éventuellement placées entre parenthèse. Si la condition n'est pas une séquence de chiffres, il faut que ce soit une assertion. Ce peut être une assertion positive ou négative, arrière ou avant. Considérons le masque suivant (même conditions que le précédent) et avec deux alternatives en seconde ligne : (?(?=[^a-z]*[a-z])\d{2}[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} ). La condition est une assertion avant positive, qui recherche une séquence optionnelle de caractères non-lettre. En d'autres termes, elle teste la presence d'au moins une lettre dans la chaîne sujet. Si une lettre est trouvée, la recherche se poursuit avec la première alternative, et sinon, avec la seconde. Ce masque recherche des chaînes de la forme dd-aaa-dd ou dd-dd-dd, avec "aaa" qui sont des lettres, et dd qui sont des chiffres.
Commentaires
La séquence (?# marque le début d'un commentaire, qui se termine à la prochaine parenthèse fermante. Les parenthèses imbriquées ne sont pas autorisées. Les caractères entre ces délimiteurs ne jouent alors aucun rôle dans le masque.
Si l'option PCRE_EXTENDED est activée, les caractères dièses # non échappés en dehors d'une classe de caractères introduisent un commentaire qui continuera jusqu'à la prochaine ligne dans le masque.
Masques récursifs
Considérons le cas où il faut recherche dans une chaîne, avec un niveau d'imbrications infini de parenthèses. Sans l'aide de la récursivité, le mieux que nous puissions obtenir est de créer un masque avec un niveau fixé de profondeur d'imbrication. Il n'est pas possible de traiter des masques à niveau d'imbrications variable. PCRE fournit un nouvel outil expérimental qui permet d'utiliser la récursivité dans les masques (entre autre). L'option (?R) est fournie pour servir la cause de la récursivité. Le masque suivant résoud le problème des parenthèses (l'option PCRE_EXTENDED est utilisée pour ignorer les espaces) : \( ( (?>[^()]+) | (?R) )* \)
Tout d'abord, le masque recherche une parenthèse ouvrante. Puis, il recherche n'importe quel nombre de sous-chaînes qui sont soit des séquences de caractères non-parenthèses, ou bien une recherche récursive avec le même masque (i.e. une chaîne correctement incluse entre parenthèses). Finalement, il recherche une parenthèse fermante.
Cet exemple particulier contient un nombre illimité de répétitions imbriquées, ce qui fait que l'utilisation de sous-chaînes à utilisation unique pour rechercher les séquence de caractères non-parenthèses est important, lorsqu'il s'applique à une chaîne qui n'est pas valide. Par exemple, si on l'applique à "(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()" la réponse arrive rapidement. Sinon, si les sous-chaînes à utilisation unique ne sont pas utilisées, la recherche peut prendre un très long temps, car il existe de très nombreuses combinaisons de + et * à tester avant de conclure à l'échec.
Les valeurs utilisées pour capturer les sous-masques sont celles utilisées par les niveaux les plus hauts de récursivités, auquel la valeur est fixée. Si le masque précédent est utilisé avec (ab(cd)ef) la valeur de la parenthèse capturante est "ef", qui est la dernière valeur lue au niveau supérieur. Si de nouvelles parenthèses sont ajoutées, par exemple : \( ( ( (?>[^()]+) | (?R) )* ) \) alors la chaîne capturée est "ab(cd)ef", c'est-à-dire le contenu de la parenthèses capturant de plus haut niveau. S'il y a plus de 15 parenthèses capturantes dans une chaîne, PCRE doit utiliser plus de mémoire pour stocker ces données. S'il ne peut obtenir cette mémoire supplémentaire, il ne fait que sauver les 15 premières, car il n'y a pas moyen de générer une erreur de mémoire lors d'une récursion.
Performances
Certaines séquences de recherches sont plus efficaces que d'autres. Ainsi, il est plus efficace d'utiliser une classe de caractères telle que [aeiou] plutôt qu'une alternative (a|e|i|o|u).
En général, le masque le plus simple, qui permette la recherche désirée est le plus efficace. Le livre de Jeffrey Friedl's contient de nombreuses études à propos de l'optimisation des expressions régulières.
Lorsqu'un masque commence par.* et que l'option PCRE_DOTALL est activée, le masque est implicitement ancré par PCRE, étant donné qu'il ne peut que rechercher au début de la chaîne. Cependant, si option PCRE_DOTALL n'est pas activée, PCRE ne peut faire aucune optimisation car le méta-caractères point "." ne remplace pas une nouvelle ligne, et si la chaîne sujet contient des nouvelles lignes, le masque peut trouver une solution qui serait située juste après une de ces nouvelles lignes, et non pas seulement au début de la chaîne sujet. Par exemple, le masque, (.*)second acceptera la chaîne "premier \net second" (avec "\n" qui remplace la nouvelle ligne), et la première chaîne capturée sera "et".
Afin d'effectuer la recherche, PCRE va essayer d'appliquer le masque à partir de chaque début de ligne. Si vous utilisez un tel masque avec des chaînes qui ne contiennent pas de caractères de nouvelles lignes, les meilleures performances seront atteintes avec l'option PCRE_DOTALL, ou en ancrant le masque avec ^.*. Cela évite à PCRE de scanner toute la chaîne pour rechercher un caractère de nouvelle ligne et recommencer la recherche.
Attention aux masques qui contiennent des quantificateurs infinis imbriqués. Ils peuvent demander un temps de calcul très long, lorsqu'appliqués à une chaîne qui ne correspond pas à ce masque. Par exemple, (a+)* peut accepter "aaaa" de 33 manières différentes, et ce nombre croit rapidement avec la taille de la chaîne (le quantificateur * peut prendre les valeurs de 0, 1, 2, 3, ou 4, et pour chaque cas non nul, le quantificateur + peut prendre différentes valeurs).
Lorsque le reste de la chaîne est tel que l'on s'achemine vers un échec, PCRE doit en principe vérifier toutes les possibilités, et cela prend un temps extrêmement long. Un optmiseur repère les cas les plus simples, tel que (a+)*b où un caractère simple suit les quantificateurs. Avant de partir dans les procédures standard de recherche, PCRE s'assure qu'il y a au moins un "b" dans la chaîne, et si ce n'est pas le cas, l'échec est annoncé immédiatement. Sinon, il n'y a pas d'optimisation dans la recherche. Vous pouvez voir la différence de comportement avec le masque suivant : (a+)*\d. Le premier retourne un échec quasi-immédiatement, s'il est appliqué à une ligne de "a", alors que le second masque prend un temps significatif pour une chaîne de plus de 20 caractères.
preg_grep
Description
array preg_grep ( string pattern, array input)preg_grep() retourne un tableau qui contient les éléments de input qui satisfont le masque pattern.
Depuis PHP 4.0.4, le tableau retourné par preg_grep() est indexé en utilisant les clés issues du tableau input. Si ces clés sont inutiles, utilisez la fonction array_values() sur le tableau retourné par preg_grep() pour obtenir le comportement traditionnel.
preg_match_all
Description
int preg_match_all ( string pattern, string subject, array matches [, int order])preg_match_all() analyse subject pour trouver l'expression pattern et met les résultats dans matches, dans l'ordre spécifié par order.
Après avoir trouvé un premier résultat, la recherche continue jusqu'à la fin de la chaîne.
order peut prendre une des deux valeurs suivantes :
- PREG_PATTERN_ORDER
L'ordre est tel que $matches[0] est un tableau qui contient les résultats qui satisfont le masque complet, $matches[1] est un tableau qui contient les résultats qui satisfont la première parenthèse capturante, etc..
Cet exemple va afficher : Ainsi, $out[0] est un tableau qui contient les résultats qui satisfont le masque complet, et $out[1] est un tableau qui contient les balises entre > et <.- PREG_SET_ORDER
Les résultats sont classés de telle façon que $matches[0] contient la première série de résultat, $matches[1] contient la deuxième série de résultat, etc...
Cet exemple va afficher : Dans ce cas, $matches[0] est la première série de résultat, et $matches[0][0] contient le texte qui satisfait le masque complet, $matches[0][1] contient le texte de la première parenthèse capturante, etc... De même, $matches[1] contient le texte qui satisfait le masque complet, etc...
Si order est omis, PREG_PATTERN_ORDER est utilisé par défaut.
preg_match_all() retourne le nombre de résultat qui satisfont le masque complet, ou FALSE en cas d'échec ou d'erreur.
Exemple 2. Recherche les couples de balises HTML (gourmand)
|
Voir aussi preg_match(), preg_replace() et preg_split().
preg_match
Description
int preg_match ( string pattern, string subject [, array matches])preg_match() analyse subject pour trouver l'expression pattern.
Si matches est fourni, il sera rempli par les résultats de la recherche. $matches[0] contiendra le texte qui satisfait le masque complet, $matches[1] contiendra le texte qui satisfait la première parenthèse capturante, etc..
preg_match() retourne TRUE si la recherche réussit, et FALSE sinon (notamment en cas d'erreur).
Exemple 2. Trouve le mot "web"
|
Exemple 3. Lire un nom de domaine dans une URL
|
preg_quote
(PHP 3>= 3.0.9, PHP 4 )
preg_quote -- Echappement des caractères spéciaux des expressions régulières.Description
string preg_quote ( string str [, string delimiter])preg_quote() ajoute un antislash devant tous les caractères de la chaîne str. Cela est très utile si vous avez une chaîne qui va servir de masque, mais qui est générée durant l'exécution.
Si l'argument optionnel delimiter est fourni, il sera aussi échappé. Ceci est pratique pour échapper le délimiteur requis par les fonctions PCRE. Le slash / est le délimiteur le plus répandu.
Les caractères spéciaux qui seront échappés :
. \\ + * ? [ ^ ] $ ( ) { } = ! < > | : |
Exemple 2. Mise en italique d'un mot dans un texte
|
preg_replace_callback
Description
mixed preg_replace_callback ( mixed pattern, mixed callback, mixed subject [, int limit])Le comportement de preg_replace() est presque identique à celui de preg_replace(), hormis le fait qu'à la place du paramètre replacement, il faut spécifier une fonction de callback callback qui sera appelée, avec les éléments trouvés en arguments. Cette fonction retourne alors la chaîne de remplacement.
preg_replace_callback() a été ajoutée en PHP 4.0.5.
Voir aussi preg_replace().
preg_replace
Description
mixed preg_replace ( mixed pattern, mixed replacement, mixed subject [, int limit])preg_replace() analyse subject pour trouver l'expression pattern et remplace les résultats par replacement.
replacement peut contenir des références de la forme \\n ou, depuis PHP 4.0.4) $n. Cette dernière forme est recommandée. Ces références seront remplacées par le texte capturé par la n'-ième parenthèse capturante du masque. n peut prendre des valeurs de 0 à 99, et \\0 ou $0, correspondent au texte de qui satisfait le masque complet. Les parenthèses ouvrantes sont comptées de gauche à droite (en commençant à 1) pour déterminer le numéro de parenthèse capturante.
Si la recherche n'aboutit à aucun résultat, subject sera inchangé.
Tous les paramètres de preg_replace() peuvent être des tableaux.
Si subject est un tableau, alors l'opération sera appliquée à chacun des éléments du tableau, et le tableau sera retourné.
Si pattern et replacement sont des tableaux, alors preg_replace() prend une valeur de chaque tableau, et l'utilise pour faire la recherche et le remplacement. Si replacement à moins d'éléments que pattern, alors la chaîne vide est utilisé pour le reste des valeurs. Si pattern est un tableau, et que replacement est une chaîne, alors cette chaîne sera utilisée pour chaque valeur de pattern. Le contraire n'aurait pas de sens.
/e force preg_replace() à traiter replacement comme du code PHP une fois que les substitutions adéquates ont été faites. Conseil :assurez-vous que replacement est un code PHP valide, car sinon, PHP trouvera une erreur d'analyse (parse error) dans cette ligne.
/F indique que le paramètre replacement doit être considéré comme un nom de fonction. Cette fonction sera appelée, avec un tableau contenant les éléments trouvés comme arguments. La fonctoin doit retourner la chaine de remplacement. Cette option a été ajoutée en PHP 4.0.4.
Exemple 3. Conversion HTML en texte
|
Note : Le paramètre limit a été ajouté à partir de PHP 4.0.1pl2.
Voir aussi preg_match(), preg_match_all() et preg_split().
preg_split
Description
array preg_split ( string pattern, string subject [, int limit [, int flags]])preg_split() retourne un tableau contenant les sous-chaînes de subject, séparées par les chaînes qui vérifient pattern.
Si limit est spécifié, alors seules les limit premières sous-chaînes sont retournées et si limit vaut -1, cela signifie en fait "sans limite", ce qui est utile pour passer le paramètre flags.
flags peut être la combinaison des options suivantes (combinées avec l'opérateur |):
- PREG_SPLIT_NO_EMPTY
Si cette option est activée, seules les sous-chaînes non vides seront retournées par preg_split().
- PREG_SPLIT_DELIM_CAPTURE
Si cette option est activée, les expressions entre parenthèses entre les délimiteurs de masques seront aussi capturées et retournées. Cette option a été ajoutée en PHP 4.0.5.
Note : Le paramètre flags a été ajouté en PHP Beta 3.
Voir aussi explode(), spliti(), split(), implode(), preg_match(), preg_match_all() et preg_replace().
LXXXVIII. qtdom
- Table des matières
- qdom_error -- Retourne le message 'derreur de la dernière opération QTDOM, ou FALSE si aucune erreur n'est survenue
- qdom_tree -- Crée une arbre à partir d'un code XML
qdom_error
(PHP 4 >= 4.0.5)
qdom_error -- Retourne le message 'derreur de la dernière opération QTDOM, ou FALSE si aucune erreur n'est survenueDescription
string qdom_error ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
qdom_tree
Description
object qdom_tree ( string )| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
LXXXIX. Expressions régulières
Les expressions régulières sont utilisées pour effectuer des manipulations complexes de chaînes de caractères. Les fonctions sont :
Ces fonctions requièrent toutes une expression régulière comme premier argument. PHP utilise les expressions régulières avancées de POSIX (POSIX 1003.2). Pour avoir tous les détails sur ces expressions, reportez vous aux pages de manuel inclues dans le répertoire de la distribution PHP.
Exemple 1. Expressions régulières
|
- Table des matières
- ereg_replace -- Remplacement par expression régulière.
- ereg -- Expression régulière standard.
- eregi_replace -- Remplacement par expression régulière insensible à la casse.
- eregi -- Recherche par expression régulière insensible à la casse.
- split -- Scinde une chaîne en un tableau, grâce à une expression régulière.
- spliti -- Scinde une chaîne en un tableau, grâce à une expression régulière.
- sql_regcase -- Prépare une expression régulière pour effectuer une recherche insensible à la casse.
ereg_replace
Description
string ereg_replace ( string pattern, string replacement, string string)ereg_replace() effectue une recherche par expression régulière dans la chaîne string en recherchant les occurrences de pattern, puis les remplace par la chaîne replacement.
La chaîne modifiée est retournée. (Ce qui signifie que la chaîne originale sera retournée si aucune occurrence n'est trouvée).
Si pattern contient des parenthèses capturantes, replacement pourra contenir des séquences de la forme \\digit, qui seront remplacées par le texte capturé par la n-ième parenthèse capturante. \\0 correspond à la chaîne originale complète. De 0 à 9 parenthèses capturantes peuvent être utilisées. Les parenthèses peuvent être imbriquées, et leur numéro d'ordre est défini par leur parenthèse ouvrante.
Si aucune occurrence n'est trouvée, la chaîne string sera retournée intacte.
Par exemple, le code suivant affiche "Ceci etait un test" trois fois :
Notez bien que si vous utilisez une valeur de type entier dans le paramètre de remplacement replacement, vous risquez de ne pas obtenir le résultat escompté. Tout cela parce que ereg_replace() va interpréter le nombre comme la valeur ordinale d'un caractère, et l'utiliser. Par exemple :
Exemple 2. Exemple avec ereg_replace()
|
Voir aussi ereg(), eregi() et eregi_replace().
ereg
Description
int ereg ( string pattern, string string [, array regs])Recherche dans la chaîne string les séquences de caractères qui correspondent au masque pattern.
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 regs, les résultats seront enregistrés dans regs. $regs[1] contiendra la première parenthèse capturante (celle qui commence le plus tôt), $regs[2] contiendra la deuxième parenthèse capturante (celle qui commence après la première), et ainsi de suite. $regs[0] contient une copie de la chaîne.
Si ereg() trouve ses solutions pour les parenthèses capturantes, $regs contiendra exactement 10 éléments, même si il y avait plus ou moins de 10 parenthèses capturantes qui étaient valides. Cela n'a aucun effet sur les capacités de la fonction ereg() à trouver d'autres sous chaînes. Si aucune valeur n'est trouvée, $regs ne sera pas modifié par ereg().
La recherche est sensible à la casse.
ereg() retourne TRUE si une occurrence a été trouvée dans la chaîne et FALSE dans le cas contraire, ou si une erreur est survenue.
L'exemple suivant prend une date au format ISO (YYYY-MM-DD) et l'affiche sous la forme DD.MM.YYYY :
Voir aussi eregi(), ereg_replace() et eregi_replace().
eregi_replace
Description
string eregi_replace ( string pattern, string replacement, string string)eregi_replace() est identique à ereg_replace(), hormis le fait qu'elle ne tient pas compte de la casse des caractères alphabétiques.
Voir aussi ereg(), eregi() et ereg_replace().
eregi
Description
int eregi ( string pattern, string string [, array regs])eregi() est identique à ereg(), hormis le fait qu'elle ignore la casse des caractère lors de la recherche sur les caractère alphabétiques.
Voir aussi ereg(), ereg_replace() et eregi_replace().
split
Description
array split ( string pattern, string string [, int limit])split() retourne une tableau de chaînes : chacune d'entre elle est une sous-chaîne de string délimitée par les occurrences trouvées de l'expression régulière pattern. Si une erreur survient, retourne FALSE.
Pour lire les 5 premiers champs d'une ligne du fichier /etc/passwd:
Pour analyser une date qui est délimitée par des /, des points ou des tirets :
Notez que patternest insensible à la casse
Notez bien que si vous n'avez pas besoin de la puissance des expressions régulières, il est plus rapide d'utiliser explode(), qui n'utilise pas le moteur d'expressions régulières.
Notez aussi que pattern est une expression régulière. Si vous voulez utiliser n'importe quel caractère spécial des expressions régulières, vous devez les échapper. Si vous pensez que split() (ou toute autre expression régulière) se comporte bizarrement, lisez d'abord le fichier regex.7, inclus dans le dossier regex/ de la distribution PHP . Il est au format manpage, et vous pourrez le lire avec une commande telle que man /usr/local/src/regex/regex.7.
spliti
Description
array spliti ( string pattern, string string [, int limit])spliti() est identique à split(), hormis le fait qu'elle ignore la casse.
sql_regcase
(PHP 3, PHP 4 )
sql_regcase -- Prépare une expression régulière pour effectuer une recherche insensible à la casse.Description
string sql_regcase ( string string)sql_regcase() retourne une expression régulière valide qui acceptera la chaîne string, et toutes les variantes majuscule/minuscule possibles de cette chaîne. Cette expression sera construite à partir de la chaîne string en remplacant tous les caractères par des expressions entre crochets (des classes de caractères), contenant la lettre majuscule et minuscule. Si le caractère n'est pas une lettre, les crochets contiendront deux fois le caractère original.
Cette expression sert à effectuer des recherches insensibles à la casse avec d'autres logiciels, qui n'acceptent les recherches insensibles à la casse.
XC. Sémaphores et gestion de la mémoire partagée
Ce module fourni un système de sémaphore. Ce système utilise les sémaphores System V. Les sémaphores peuvent être utilisés pour fournir un accès exclusif à certaines ressources de la machine, ou pour limiter le nombre de processus qui utilisent en même temps une ressource.
Ce module fournit aussi un système de mémoire partagée, qui utilise la mémoire partagée System V. Cette mémoire partagée permet d'accéder à des variables globales. Les différents démons httpd et mêmes d'autres programmes (tels que Perl, C, ...) permettent un tel échange de données global. N'oubliez pas que la mémoire partagée n'est pas protégées contre l'accès simultané. Il vous faudra utiliser les sémaphores pour assurer la synchronisation.
Tableau 1. Limites de la mémoire partagée sous Unix OS
| SHMMAX | Taille maximale de mémoire partagée, par défaut, 131072 octets. |
| SHMMIN | Taille minimale de mémoire partagée, par défaut, 1 octet. |
| SHMMNI | Nombre maximal de segment de mémoire partagé, par défaut 100. |
| SHMSEG | Taille maximale de mémoire partagée par processus, par défaut 6. |
- Table des matières
- ftok -- Convert a pathname and a project identifier to a System V IPC key
- msg_get_queue -- Create or attach to a message queue
- msg_receive -- Receive a message from a message queue
- msg_remove_queue -- Destroy a message queue
- msg_send -- Send a message to a message queue
- msg_set_queue -- Set information in the message queue data structure
- msg_stat_queue -- Returns information from the message queue data structure
- sem_acquire -- Réserve un sémaphore.
- sem_get -- Retourne un identifiant de sémaphore.
- sem_release -- Libère un sémaphore.
- sem_remove -- Remove a semaphore
- shm_attach -- Crée ou ouvre un segment de mémoire partagée.
- shm_detach -- Libère un segment de mémoire partagée.
- shm_get_var -- Lit une variable dans la mémoire partagée.
- shm_put_var -- Insère ou modifie une variable de la mémoire partagée.
- shm_remove_var -- Efface une variable de la mémoire partagée.
- shm_remove -- Supprime un segment de mémoire partagée sous Unix.
ftok
Description
int ftok ( string pathname, string proj)
| Avertissement |
This function is currently not documented, only the argument list is available. |
msg_get_queue
Description
int msg_get_queue ( int key [, int perms])msg_get_queue() returns an id that can be used to access the System V message queue with the given key. The first call creates the message queue with the optional perms (default: 0666). A second call to msg_get_queue() for the same key will return a different message queue identifier, but both identifiers access the same underlying message queue. If the message queue already exists, the perms will be ignored.
See also: msg_remove_queue(), msg_receive(), msg_send(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
msg_receive
Description
bool msg_receive ( int queue, int desiredmsgtype, int msgtype, int maxsize, mixed message [, bool unserialize [, int flags [, int errorcode]]])msg_receive() will receive the first message from the specified queue of the type specified by desiredmsgtype. The type of the message that was received will be stored in msgtype. The maximum size of message to be accepted is specified by the maxsize; if the message in the queue is larger than this size the function will fail (unless you set flags as described below). The received message will be stored in message, unless there were errors receiving the message, in which case the optional errorcode will be set to the value of the system errno variable to help you identify the cause.
If desiredmsgtype is 0, the message from the front of the queue is returned. If desiredmsgtype is greater than 0, then the first message of that type is returned. If desiredmsgtype is less than 0, the first message on the queue with the lowest type less than or equal to the absolute value of desiredmsgtype will be read. If no messages match the criteria, your script will wait until a suitable message arrives on the queue. You can prevent the script from blocking by specifying MSG_IPC_NOWAIT in the flags parameter.
unserialize defaults to TRUE; if it is set to TRUE, the message is treated as though it was serialized using the same mechanism as the session module. The message will be unserialized and then returned to your script. This allows you to easily receive arrays or complex object structures from other PHP scripts, or if you are using the WDDX serializer, from any WDDX compatible source. If unserialize is FALSE, the message will be returned as a binary-safe string.
The optional flags allows you to pass flags to the low-level msgrcv system call. It defaults to 0, but you may specify one or more of the following values (by adding or ORing them together).
Tableau 1. Flag values for msg_receive
| MSG_IPC_NOWAIT | If there are no messages of the desiredmsgtype, return immediately and do not wait. The function will fail and return an integer value corresponding to ENOMSG. |
| MSG_EXCEPT | Using this flag in combination with a desiredmsgtype greater than 0 will cause the function to receive the first message that is not equal to desiredmsgtype. |
| MSG_NOERROR | If the message is longer than maxsize, setting this flag will truncate the message to maxsize and will not signal an error. |
Upon successful completion the message queue data structure is updated as follows: msg_lrpid is set to the process-ID of the calling process, msg_qnum is decremented by 1 and msg_rtime is set to the current time.
msg_receive() returns TRUE on success or FALSE on failure. If the function fails, the optional errorcode will be set to the value of the system errno variable.
See also: msg_remove_queue(), msg_send(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
msg_remove_queue
Description
bool msg_remove_queue ( int queue)msg_remove_queue() destroys the message queue specified by the queue. Only use this function when all processes have finished working with the message queue and you need to release the system resources held by it.
See also: msg_remove_queue(), msg_receive(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
msg_send
Description
bool msg_send ( int queue, int msgtype, mixed message [, bool serialize [, bool blocking [, int errorcode]]])msg_send() sends a message of type msgtype (which MUST be greater than 0) to a the message queue specified by queue.
If the message is too large to fit in the queue, your script will wait until another process reads messages from the queue and frees enough space for your message to be sent. This is called blocking; you can prevent blocking by setting the optional blocking parameter to FALSE, in which case msg_send() will immediately return FALSE if the message is too big for the queue, and set the optional errorcode to EAGAIN, indicating that you should try to send your message again a little later on.
The optional serialize controls how the message is sent. serialize defaults to TRUE which means that the message is serialized using the same mechanism as the session module before being sent to the queue. This allows complex arrays and objects to be sent to other PHP scripts, or if you are using the WDDX serializer, to any WDDX compatible client.
Upon successful completion the message queue data structure is updated as follows: msg_lspid is set to the process-ID of the calling process, msg_qnum is incremented by 1 and msg_stime is set to the current time.
See also: msg_remove_queue(), msg_receive(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
msg_set_queue
Description
bool msg_set_queue ( int queue, array data)msg_set_queue() allows you to change the values of the msg_perm.uid, msg_perm.gid, msg_perm.mode and msg_qbytes fields of the underlying message queue data structure. You specify the values you require by setting the value of the keys that you require in the data array.
Changing the data structure will require that PHP be running as the same user that created the the queue, owns the queue (as determined by the existing msg_perm.xxx fields), or be running with root privileges. root privileges are required to raise the msg_qbytes values above the system defined limit.
See also: msg_remove_queue(), msg_receive(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
msg_stat_queue
Description
array msg_stat_queue ( int queue)msg_stat_queue() returns the message queue meta data for the message queue specified by the queue. This is useful, for example, to determine which process sent the message that was just received.
The return value is an array whose keys and values have the following meanings:
Tableau 1. Array structure for msg_stat_queue
| msg_perm.uid | The uid of the owner of the queue. |
| msg_perm.gid | The gid of the owner of the queue. |
| msg_perm.mode | The file access mode of the queue. |
| msg_stime | The time that the last message was sent to the queue. |
| msg_rtime | The time that the last message was received from the queue. |
| msg_ctime | The time that the queue was last changed. |
| msg_qnum | The number of messages waiting to be read from the queue. |
| msg_qbytes | The number of bytes of space currently available in the queue to hold sent messages until they are received. |
| msg_lspid | The pid of the process that sent the last message to the queue. |
| msg_lrpid | The pid of the process that received the last message from the queue. |
See also: msg_remove_queue(), msg_receive(), msg_stat_queue() and msg_set_queue().
This function was introduced in PHP 4.3.0 (not yet released).
sem_acquire
Description
int sem_acquire ( resource sem_identifier)sem_acquire() retourne TRUE en cas de succès, et FALSE sinon.
sem_acquire() se bloque (si nécessaire) jusqu'à ce que le sémaphore puisse être réservé. Un processus qui tente de réserver un sémaphore qu'il a déjà reservé restera en attente indéfinie, si cette acquisition excède le nombre max_acquire de réservation simultanée.
A la fin d'un script, tous les sémaphores réservés mais non explicitement libérés seront libérés automatiquement, et une alerte sera générée.
Voir aussi sem_get() et sem_release().
sem_get
Description
resource sem_get ( int key [, int max_acquire [, int perm]])sem_get() retourne un identifiant positif de sémaphore en cas de succès, et FALSE en cas d'erreur.
sem_get() retourne un identifiant qui pourra être utilisé pour accéder à un sémaphore System V. Le sémaphore est créé, si nécessaire, en utilisant les bits de permission (par défaut, 0666). Le nombre de processus qui peuvent réserver simultanément le sémaphore est précisé dans max_acquire (par défaut à 1). Actuellement, cette valeur n'est affectée que si le processus est le seul processus actuellement attaché au sémaphore.
Un deuxième appel à sem_get() avec la même clé retournera un identifiant différent, mais les deux identifiants permettront d'accéder au même sémaphore.
Voir aussi sem_acquire() et sem_release().
Note : sem_get() n'est pas disponibles sous Windows.
sem_release
Description
int sem_release ( int sem_identifier)Retourne TRUE en cas de succès, FALSE en cas d'erreur.
sem_release() libère le sémaphore s'il a été réservé par le processus courant. Sinon, génère une erreur.
Après libération du sémaphore, sem_acquire() peut être appelé pour le réserver à nouveau.
Voir aussi : sem_get() et sem_acquire().
Note : Cette fonction n'est pas disponibles sous Windows.
sem_remove
Description
bool sem_remove ( int sem_identifier)Returns: TRUE on success, FALSE on error.
sem_remove() removes the semaphore sem_identifier if it has been created by sem_get(), otherwise generates a warning.
After removing the semaphore, it is no more accessible.
See also: sem_get(), sem_release() and sem_acquire().
Note : This function does not work on Windows systems. It was added on PHP 4.1.0.
shm_attach
Description
resource shm_attach ( int key [, int memsize [, int perm]])shm_attach() retourne un identifiant qui permettra d'accéder au System V de mémoire partagée. Au premier appel, la mémoire sera créée, avec la taille mem_size (par défaut: sysvshm.init_mem dans php3.ini, sinon 10000 octets) et avec les permissions perm(par défaut : 666).
Aux appels suivants avec la même clé key, shm_attach() retournera un nouvel identifiant, mais cet identifiant accédera toujours à la même portion de mémoire partagée. Dans ce cas, memsize et permseront ignorés.
Note : Cette fonction n'est pas disponibles sous Windows.
shm_detach
Description
resource shm_detach ( int shm_identifier)shm_detach() libère le segment de mémoire partagée identifié par shm_identifier et créé par sem_get(). N'oubliez pas que cette mémoire partagée existe toujours sous Unix, et que les données sont toujours accessibles.
shm_get_var
Description
mixed shm_get_var ( resource shm_identifier, int variable_key)shm_get_var() retourne la variable repérée par variable_key. La variable est toujours présente en mémoire partagée.
Note : shm_get_var() n'est pas disponibles sous Windows.
shm_put_var
Description
int shm_put_var ( resource shm_identifier, int variable_key, mixed variable)shm_put_var() insère ou modifie la variable variable avec la clé variable_key. Tous les types de variables (double, int, string, array, objects...) sont supportés.
Note : shm_put_var() n'est pas disponibles sous Windows.
shm_remove_var
Description
int shm_remove_var ( int shm_identifier, int variable_key)shm_remove_var() efface la variable variable_key de la mémoire partagée et libère la mémoire.
Note : shm_remove_var() n'est pas disponibles sous Windows.
shm_remove
XCI. SESAM
SESAM/SQL-Server est une base de données mainframe, développée par Fujitsu Siemens Computers, Allemagne. Elle fonctionne sur les serveur mainframe, sous BS2000/OSD.
Sur de nombreuses installation BS2000 en production, SESAM/SQL-Server a prouvé ...
La facilité de connectivité Java, Web et client/serveur
La disponibilité de plus de 99.99%,
La capacité de gérer des dizaines et mêmes des centaines de milliers d'utilisateurs.
Désormais, il existe une interface PHP pour SESAM, qui donne l'accès à cette base aux scripts PHP.
Notes de configuration : Il n'y a pas de support pour l'interface SESAM si PHP est un CGI : elle ne fonctionne que comme module Apache. En module Apache, l'interface SESAM peut être configurée avec les directives Apache.
Tableau 1. Directives de configuration SESAM
Directive Signification php3_sesam_oml Nom de la librairie BS2000 PLAM contenant le module du pilote SESAM. Ceci est obligatoire pour utiliser les fonctions SESAM. Exemple:
php3_sesam_configfile Nom du fichier de configuration de l'application SESAM. Ceci est obligatoire pour utiliser les fonctions SESAM. Exemple:
Ce fichier contient généralement une configuration comme celle ci (voir dans le manuel de référence SESAM):php3_sesam_messagecatalog Nom du fichier de messages SESAM. Dans la plus part des cas, cette directive n'est pas nécessaire. Uniquement si le fichier de messages SESAM n'es pas installé dans la table de messages BS2000. Il peut alors être choisi avec cette directive. Exemple:
En plus de la configuration de l'interface PHP/SESAM, vous devez aussi configurer le serveur SESAM-Database sur votre mainframe, comme d'habitude. Cela signifie notamment qu'il faut :
démarrer le gestionnaire de base SESAM (DBH)
connecter les bases avec le gestionnaire de bases SESAM
Pour connecter un script PHP au serveur de bases SESAM, les paramètres CNF et NAM de la configuration SESAM selectionnée doivent correspondre à l'id du gestionnaire de base démarré.
Dans le cas des bases de données distribuées, vous devez démarrer un agent SESAM/SQL-DCN, avec la table de distribution incluant le nom de l'hôte et de la base de données.
La communication entre PHP (fonctionnant sur le sous-système POSIX) et le gestionnaire de base (fonctionnant hors du sous-système POSIX) est réalisée par un pilote spécial appelé SQLSCI et le module de connexion SESAM, qui utilise la mémoire partagée. A cause de la mémoire partagée, et parce que PHP est une partie statique du serveur web, les accès à la base de données sont extrêmement rapide, car il ne requièrent pas de connexion distante via ODBC, JDBC ou UTM.
Seul un chargeur de stub (stub loader, SESMOD) est compilé dans PHP. Les modules de connexion SESAM proviennent de la librairie OML PLAM. Dans la configuration, vous devez indiquer à PHP le nom de la librairie PALM, et le fichier de lien à utiliser pour la configuration de SESAM (En SESAM V3.0, SQLSCI est disponible dans la librairie d'outils SESAM (SESAM Tool Library), qui fait partie de la distribution standard).
Les commandes SQL imposent que les guillemets simples soient doublés pour être interprété litéralement (contrairement à d'autres bases de données qui utilisent un guillemet simple, précédé d'un antislash), il est recommandé d'activer les directives PHP php3_magic_quotes_gpc et php3_magic_quotes_sybase.
Exécutions : A cause des limitations du modèle de processus BS2000, le pilote peut être chargé uniquement après que le serveur Apache ait généré le processus fils. Cela ralentit légèrement le traitement de la première requête, mais toutes les requêtes suivantes seront effecutée à pleine vitesse.
Lorsque vous définissez explicitement le catalogue de messages SESAM, ce catalogue ser chargé à chaque fois que le pilote est chargé (i.e., au moment de la requête initiale). Le système d'exploitation BS2000 affiche un message après avoir correctement chargé le catalogue de messages, qui sera envoyé au fichier d'erreurs Apache. BS2000 ne permet pas la suppression de ce message, qui va remplir progressivement ce fichier.
Assurez vous que la librairie SESAM OML PLAM et le fichier de configuration SESAM sont accessibles par l'utilisateur qui fait tourner le serveur web. Sinon, le serveur ne sera pas capable de charger le pilote, ou d'appeler les fonctions SESAM. L'accès à la base doit être donné à cet utilisateur. Sinon, les connexions SESAM échoueront.
Types de curseurs : Les curseurs de résultat sont alloués pour les requêtes SQL de selection, peuvent être soit "séquentiels", soit "à défilement" ("scrollable"). Les curseurs à défilement sont beaucoup plus gourmands en mémoire, et le mode par défaut est séquentiel.
Lorsque vous utilisez les curseurs à défilement, le curseur peut être positionné librement dans le résultat. Pour chaque requête à défilement, il existe des valeurs globales de types de défilement (initialisée à :SESAM_SEEK_NEXT) et la position peut être fixée une seule fois par sesam_seek_row() ou bien à chaque appel, avec la fonction sesam_fetch_row(). Lorsque vous lisez une ligne avec un curseur à défilement, le traitement suivant est effectué à partir des valeurs globales de type de défilement et de position :
Tableau 2. Scrolled Cursor Post-Processing
Type de défilement Action SESAM_SEEK_NEXT aucun SESAM_SEEK_PRIOR aucun SESAM_SEEK_FIRST le type de défilement devient SESAM_SEEK_NEXT SESAM_SEEK_LAST le type de défilement devient SESAM_SEEK_PRIOR SESAM_SEEK_ABSOLUTE incrémente automatiquement la valeur interne de position SESAM_SEEK_RELATIVE aucune. conserve les valeurs globales par défaut de position, ce qui permet, par exemple de lire toutes les 10 lignes, en arrière.
Porting note : En PHP, il est naturel de commencer les index à zéro (plutôt que 1), et quelques adaptations ont été faite pour l'interface SESAM : à chaque fois qu'un tableau indexé commence à l'index 1 en SESAM natif, l'interface PHP utilisera l'index 0 comme point de départ. Par exemple, lorsque vous lisez des données avec sesam_fetch_row(), la première colonne sera à l'index 0, et les suivantes suivront juqu'au nombre de colonne (exclus) du résultat ($array["count"]). Lors du portage d'applications depuis d'autres langage évolués vers le PHP, soyez attentifs à ce changement. A chaque fois que c'est nécessaire, la description d'une fonction PHP SESAM indique que l'index du tableau commence à 0.
Sécurité : Lorsque vous autorisez l'accès à une base de données SESAM, le serveur web doit avoir le minimum de privilèges possible. Pour la plus part des bases de données, seul le droit de lecture doit être fourni. Suivant votre utilisation, ajoutez d'autres droits d'accès au fur et à mesure de vos besoins. Ne donnez jamais le contrôle total de vos bases à un utilisateur du web! Limitez l'accès aux scripts PHP qui doivent administrer la base en utilisant un mot de passe et/ou une sécurisation SSL.
Migration d'une autre base SQL : Deux langage SQL ne sont jamais 100% compatibles. Lorsque vous portez une application SQL depuis une autre interface vers SESAM, certaines adaptation doivent être faîtes. Les différences suivantes sont les plus courantes :
Types de données spécifiques
Certains types de données spécifiques à une base doivent être remplacés par les types de données standard SQL. (i.e., TEXT doit être remplacé par VARCHAR(taille max)).
Mots reservés comme identifiants SQL.
En SESAM (comme dans le standard SQL), les mots reservés utilisés comme identifiants doivent être entourés de guillemets doubles (ou renommés).
Taille d'affichage des données.
Les types de données SESAM ont une taille de stockage, mais par de taille d'affichage. A la place de int(4) (c'est à dire : les entiers jusqu'à '9999'), SESAM requiert simplement int, pour une taille implicite de 31 bits. De même, les seuls types de date disponible dans SESAM sont : DATE, TIME(3) et TIMESTAMP(3).
Les types de données unsigned (non signé), zerofill (complété avec des zéros), ou auto_increment
Unsigned et zerofill ne sont pas supportés. Auto_increment est automatique (utilisez "INSERT ... VALUES(*, ...)" au lieu de "... VALUES(0,...)" pour profiter des auto-increment implicites de SESAM.
int ... DEFAULT '0000'
Les variables numériques ne doivent pas être initialisées avec des constantes de type chaîne de caractères. Utilisez DEFAULT 0 à la place. Pour initialiser une date, la chaîne doit être préfixée avec le type de date adapté, tel que : CREATE TABLE exmpl (xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT NULL);
$count = xxxx_num_rows();
Certaines bases de données essaient d'estimer le nombre de lignes d'un résultat, même grossièrement approximativement. SESAM ne connait pas le nombre de lignes avant de les avoir lues lui-même. Si vous avez vraiment besoin de les compter, utilisez la commande SELECT COUNT(...) WHERE ..., qui vous dira combien de lignes sont disponibles. Une deuxième requête devrait vous retourner tous ces résultats.
DROP TABLE lenom;
Avec SESAM, dans la commande DROP TABLE, le nom de la table doit être suivi du mot clé RESTRICT ou CASCADE. Avec RESTRICT, une erreur est retounrée si il y a des objets dépendant (par exemple, des vues), tandis qu'avec CASCADE, les objets dépendants seront supprimés en même temps que la table.
Notes sur l'utilisation de types SQL divers : SESAM ne supporte pas le type BLOB. Une future version de SESAM devra le faire.
L'interface PHP effectue automatiquement les conversions suivantes lors de la lecture de lignes de résultats SQL :
Lorsque vous lisez une ligne entière, le résultat est retourné sous la forme d'un tableau. Les champs vides ne sont pas remplis, et vous aurez à vérifier vous même l'existence des champs ( (utilisez isset() ou empty() pour tester les champs vides). Cela donne plus de contrôle à l'utilisateur sur l'apparence des champs que si les champs vides étaient représenté par des chaînes vides).Tableau 3. Conversion de type SQL vers PHP
Type SQL Type PHP SMALLINT, INTEGER "integer" (entier) NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE "double" (nombre à virgule flottante) DATE, TIME, TIMESTAMP "string"(chaîne de caractères) VARCHAR, CHARACTER "string"(chaîne de caractères)
Support des "champs multiples" de SESAM : La fonctionnalité spéciale des "champs multiples" de SESAM permet à une colonne de contenir un tableau de champs. Un tel "champs multiple" peut être créé comme ceci :
et peut être remplie avec :
Notez que (comme c'est le cas ci-dessus), les sous-champs vides initiaux sont ignorés, et que le tableau est alors compacté, ce qui fait que l'exemple ci-dessus conduit à un tableau multi(1..2) au lieu de multi(2..3).
Lors de la lecture d'une ligne, les "champs multiples" sont mis en colonne. Dans l'exemple ci-dessu, "pkey" prend l'index 0, et les trois colonnes "multi(1..3)" sont accessibles depuis les index 1 à 3.
Pour de plus amples détails sur SESAM, reportez vous à la documentation SESAM/SQL-Server en anglais ou SESAM/SQL-Server en allemand, disponibles toutes deux en ligne, ou en manuels.
- Table des matières
- sesam_affected_rows -- Lit le nombre de lignes affectées par une requête immédiate
- sesam_commit -- Valide la transaction SESAM en cours
- sesam_connect -- Ouvre une connexion SESAM
- sesam_diagnostic -- Retourne l'état de la dernière requête SESAM
- sesam_disconnect -- Déconnexion d'une base SESAM
- sesam_errormsg -- retourne le message d'erreur
- sesam_execimm -- Exécute immédiatement une requête SQL
- sesam_fetch_array -- Lit une ligne dans un tableau associatif
- sesam_fetch_result -- Retourne tout ou partie d'un résultat SESAM
- sesam_fetch_row -- Lit une ligne dans un tableau
- sesam_field_array -- Retourne des informations sur une colonne
- sesam_field_name -- Retourne le nom d'une colonne
- sesam_free_result -- Libère les ressources
- sesam_num_fields -- Retourne le nombre de colonne dans un résultat
- sesam_query -- Exécute une requête SESAM
- sesam_rollback -- Annule une transaction SESAM
- sesam_seek_row -- Déplace un curseur à défilement
- sesam_settransaction -- Modifie les paramètres de transaction SESAM
sesam_affected_rows
Description
int sesam_affected_rows ( string result_id)result_id est un identifiant valide de résultat, retourné par sesam_query().
sesam_affected_rows() retourne le nombre de lignes affectées par la requête associée à result_id.
sesam_affected_rows() ne retourne de valeur cohérente que lorsqu'utilisée avec une requête immédiate (INSERT/UPDATE/DELETE), car SESAM ne fournit aucune information de nombre de lignes affectées pour les requêtes de selection.
Voir aussi : sesam_query() et sesam_execimm()
sesam_commit
Description
bool sesam_commit ( void)sesam_commit() retourne TRUE en cas de succès et FALSE sinon.
sesam_commit() valide toutes les modifications de tables en attente sur la base.
Notez qu'il n'y a pas de mode "auto-commit", comme dans d'autres bases de données, car cela peut conduire à une perte accidentelle de données. Les données non valides à la fin d'un script (ou au moment de l'appel de sesam_disconnect()) seront annulées par un appel implicite à sesam_rollback().
Voir aussi : sesam_rollback().
sesam_connect
Description
bool sesam_connect ( string catalog, string schema, string user)sesam_connect() retourne TRUE si une connexion à la base SESAM a été faite, ou FALSE en cas d'erreur.
sesam_connect() établit une connexion au serveur SESAM. La connexion est toujours "persistante", en ce sens que le pilote sera chargé par la première requête avec la librairie SESAM OML PLAM. Les appels suivants réutiliseront le pilote chargé, son catalogue catalog, son schéma schema et son utilisateur user.
Lors de la création d'une base de données, le nom catalog est spécifié dans les directives de configuration SESAM avec la commande //ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 = *CATALOG(CATALOG-NAME = catalogname,...)
schema référence le schéma de base voulu (voir dans le manuel SESAM).
user spéficie l'un des utilisateurs qui est autorisé à accéder à la comibinaison catalog et/ou schema. Notez que user est complétement indépendant de l'utilisateur système et des protections HTTP par mot de passe. Il n'apparait que dans la configuration SESAM.
Voir aussi sesam_disconnect().
sesam_diagnostic
Description
array sesam_diagnostic ( void)sesam_diagnostic() retourne un tableau associatif avec l'état et les codes de la dernière requête SQL. Les éléments du tableau sont :
Tableau 1. Informations retournées par sesam_diagnostic()
| Elément | Contenu |
|---|---|
| $array["sqlstate"] | code d'erreur à 5 chiffres (voir le manuel SESAM pour obtenir une description des valeurs possibles de SQLSTATE) |
| $array["rowcount"] | nombre de lignes affectées dans la dernière requête immédiate (update/insert/delete) : uniquement après une requête immédiate. |
| $array["errmsg"] | message d'erreur lisible : uniquement après une erreur |
| $array["errcol"] | numéro de colonne de la dernière erreur (indexée à partir de 0, -1 si indéfinies. uniquement après une erreur). |
| $array["errlin"] | numéro de ligne de la dernière erreur (indexée à partir de 0, -1 si indéfinies. uniquement après une erreur). |
Dans l'exemple suivant, une erreur de syntaxe (E SEW42AE ILLEGAL CHARACTER) est affichée avec la requête SQL, et en désignant la position de l'erreur :
Exemple 1. Afficher une erreur SESAM
|
Voir aussi : sesam_errormsg() pour un accès simplifié aux messages d'erreur.
sesam_disconnect
Description
bool sesam_disconnect ( void)sesam_disconnect() retourne toujours TRUE.
sesam_disconnect() ferme le lien logique à la base de données SESAM (sans réellement déconnecter et démonter le pilote).
Notez que ceci n'est généralement pas nécessaire, car la connexion ouverte est automatiquement fermée à la fin du script. Les données qui ne seront pas validées seront alors annulées, grâce à un sesam_rollback() implicite.
sesam_disconnect() ne ferme pas les connexions persistantes : elle invalide simplement les catalogues catalog, schéma schema et utilisateur user courants, de manière à ce que les prochains appels à des fonctions SESAM échouent.
Voir aussi : sesam_connect().
sesam_errormsg
Description
string sesam_errormsg ( void)sesam_errormsg() retourne le message d'erreur SESAM associé à la dernière requête SQL.
Voir aussi : sesam_diagnostic() pour la liste complète des états de requêtes SQL.
sesam_execimm
Description
string sesam_execimm ( string query)sesam_execimm() retourne un identifiant de résultat SESAM en cas de succès, et FALSE sinon.
sesam_execimm() exécute immédiatement la requête query (i.e., une requête de type UPDATE, INSERT ou DELETE qui ne retourne aucun résultat, et n'a aucune variables d'entrées ou de sorties). Les requêtes de types "SELECT" ne peuvent pas être utilisées avec la fonctoin sesam_execimm(). sesam_execimm() mofidie la valeur affected_rows, pour lecture ultérieure avec sesam_affected_rows().
Notez que sesam_query() peut gérer les requêtes immédiates et les requêtes de selection. Utilisez sesam_execimm() uniquement si vous connaissez le type de requête auparavant. Une tentative de requête de selection avec sesam_execimm() retournera $err["sqlstate"] == "42SBW".
L'identifiant de résultat retourné ne peut pas être utilisé pour lire quoi que ce soit, mais il peut être passé à sesam_affected_rows(); il n'est retourné que pour symétrie avec la fonction sesam_query().
<?php
$stmt = "INSERT INTO matable VALUES('un', 'deux')";
$result = sesam_execimm ($stmt);
$err = sesam_diagnostic();
print("sqlstate = ".$err["sqlstate"]."\n".
"Nombre de lignes affectées = ".$err["rowcount"]." == ".
sesam_affected_rows($result)."\n");
?> |
sesam_fetch_array
Description
array sesam_fetch_array ( string result_id [, int whence [, int offset]])sesam_fetch_array() retourne un tableau qui correspond à la ligne lue dans le résultat result_id, ou FALSE si il n'y a pas d'autres lignes.
sesam_fetch_array() est une version alternative de sesam_fetch_row(). Au lieu de stocker les données dans un tableau à indice numérique, il enregistre les données dans un tableau associatif, en utilisant les noms des champs comme clés.
result_id est un identifiant de résultat valide retourné par sesam_query() (avec une requête de selection seulement!).
Pour connaître les valeurs valides des options whence et offset, reportez vous à sesam_fetch_row().
sesam_fetch_array() lit une ligne de données dans le résultat result_id. La ligne est retournée sous forme d'un tableau associatif. Chaque colonne est enregistrée avec leur nom comme index. Les noms des colonnes sont convertis en minuscules.
Les colonnes sans noms (par exemple, les résultats d'opérations arithmétiques) et les champs vides ne sont pas stockés dans ce tableau. De plus, si deux colonnes ont le même noms, la dernière colonne écrasera la précédente. Dans cette situation, utilisez de préférence sesam_fetch_row() ou bien, faîtes un alias de la colonne.
Une gestion spéciale permet de lire les champs multiples, qui sinon, auraient toutes le même nom. Pour chaque colonne d'un champs multiple, le nom d'index est créé en ajoutant le numéro de sous-index à la suite du nom de la colonne. Ces sous indices sont numérotés à partir de 1.
Les index associatifs utilisé pour les valeurs individuelles du champs multiple sont : "multi(1)", "multi(2)", et "multi(3)", respectivement.Les prochains appels à sesam_fetch_array() liront la prochaine ligne (ou la précédente, ou la n-ième, suivant les attributs de défilement), jusqu'à ce qu'il n'y ait plus de lignes.
Exemple 1. Exemple avec sesam_fetch_array()
|
Voir aussi : sesam_fetch_row() qui retourne un tableau numérique.
sesam_fetch_result
Description
mixed sesam_fetch_result ( string result_id [, int max_rows])sesam_fetch_result() retourne un tableau avec les lignes du résultat identifié par result_id, éventuellement limité à un maximum de max_rows Noteaz que les lignes et les colonnes sont indexées à partir de 0.
Tableau 1. Résultat de sesam_fetch_result()
| Elément du tableau | Contents |
|---|---|
| int $arr["count"] | Nombre de colonnes dans le résultat (ou zéro si c'était une requête immédiate). |
| int $arr["rows"] | Nombre de ligne dans le résultat (entre zéro et max_rows) |
| bool $arr["truncated"] | TRUE si le nombre de ligne était d'au moins max_rows, FALSE sinon. Notez que même si cette valeur est à TRUE, le prochain appel à sesam_fetch_result() peut retourner aucune ligne parce qu'il n'y a plus d'entrées. |
| mixed $arr[col][row] | les valeurs du résultat à la ligne row et colonne col. Le résultat est un tableau multidimensionnel. row va de 0 à $arr["rows"]-1, et col de 0 à $arr["count"]-1). Les champs peuvent être vides : vous devez vérifier leur existence avec la fonction isset(). Le type retourné dépend du type SQL déclaré pour cette colonne (voir Introduction SESAM pour connaître les conversions utilisées). Les champs multiples SESAM sont traités comme des séquences de colonnes. |
Voir aussi : sesam_fetch_row(), et sesam_field_array() pour vérifier les champs multiples. Voyez sesam_query() pour une exemple complet avec sesam_fetch_result().
sesam_fetch_row
Description
array sesam_fetch_row ( string result_id [, int whence [, int offset]])sesam_fetch_row() retourne un tableau qui correspond à la ligne lue dans le résultat result_id, ou FALSE s'il n'y a plus de ligne.
Le nombre de colonnes du résultat est retourné dans un élémen du tableau associatif retourné $array["count"]. Comme certaines lignes peuvent être vides, la fonction count() ne peut être utilisée avec le tableau ainsi retourné par sesam_fetch_row().
result_id est un identifiant de résultat valide retourné par sesam_query() (avec une requête de selection seulement!).
whence est un parmètre optionnel lors d'une opération de lecture sur un curseur à défilement, qui peut prendre une des valeurs suivantes :
Tableau 1. Valeurs valides pour whence
| Valeur | Constante | Signification |
|---|---|---|
| 0 | SESAM_SEEK_NEXT | Lecture séquentielle (après la lecture, la position est déplacé à SESAM_SEEK_NEXT) |
| 1 | SESAM_SEEK_PRIOR | Lecture séquentielle à rebours (après la lecture, la position est déplacé à SESAM_SEEK_PRIOR) |
| 2 | SESAM_SEEK_FIRST | Repositionnement au début (après la lecture, la position est déplacée à SESAM_SEEK_NEXT) |
| 3 | SESAM_SEEK_LAST | Repositionnement à la fin (après la lecture, la position est déplacée à SESAM_SEEK_PRIOR) |
| 4 | SESAM_SEEK_ABSOLUTE | Repositionnement absolu à offset (index commencant à 0. Après la lecture, la position est placé à SESAM_SEEK_ABSOLUTE, et le pointeur interne est auto-incrémenté). |
| 5 | SESAM_SEEK_RELATIVE | Repositionnement relatif à offset, où offset peut être positif ou négatif |
Lors de l'utilisation de curseurs à défilement, le curseur peut être librement repositionné. Si le paramètre whence est omis, les valeur par défaut seront utilisées (initialisées à : SESAM_SEEK_NEXT, et modifiée par sesam_seek_row()). Si whence est fourni, sa valeur remplacera les valeurs par défaut.
offset est un parmètre optionnel qui n'est utilisé (et nécessaire) que si whence vaut soit SESAM_SEEK_RELATIVE ou SESAM_SEEK_ABSOLUTE. Ce paramètre n'est valable que pour les curseurs à défilement.
sesam_fetch_row() lit une ligne de données dans le résultat result_id. La ligne est retournée sous forme d'un tableau (indexé de 0 à $array["count"]-1). Les champs peuvent être vides : il faut vous assurer de leur existence en utilisant la fonction isset(). Le type de la valeur retournée dépend du type SQL déclaré dans la base (voir introduction SESAM pour connaître les conversion utilisées). Les champs multiples SESAM sont linéarisés, et traités comme autant de colonnes.
Les prochains appels à sesam_fetch_row() liront la prochaine ligne (ou la précédente, ou la n-ième, suivant le type de défilement) dans le résultat, ou FALSE, s'il n'y a plus de lignes.
Exemple 1. Exemple avec sesam_fetch_row()
|
Voir aussi : sesam_fetch_array() qui retourne un tableau associatif, et sesam_fetch_result() qui retourne plusieurs lignes en même temps.
sesam_field_array
Description
array sesam_field_array ( string result_id)result_id is a valid result id returned by sesam_query().
sesam_field_array() retourne un tableau contenant les informations (nom de colonne, type, précision...) sur une colonne dans le résultat associé à result_id.
Tableau 1. Informations retournées par sesam_field_array()
| Index | Contenu |
|---|---|
| int $arr["count"] | Nombre total de colonnes dans le résultat (ou zéro si la requête était immédiate). Les champs multiples de SESAM sont linéarisés, et traités comme autant de colonnes. |
| string $arr[col]["name"] | Le nom de la colonne col, avec col qui vaut entre 0 et $arr["count"]-1. La valeur retournée peut être une chaîne vide (pour les colonnes dynamiquement générées). Les champs multiples SESAM sont linéarisés, et traités comme autant de colonnes, avec le même nom. |
| string $arr[col]["count"] | L'attribut "count" décrit le facteur de répétition quand la colonne a été déclarée comme un champs multiple. Généralement, cet attribut est à 1. La première colonne d'un champs multiple contient le nombre de répétitions, tandis que les colonnes suivantes ont un facteur de répétition mis à 1. Ceci peut être utilisé pour detecter les champs multiples. Reportez vous à l'exemple de la fonction sesam_query() pour avoir un exemple d'utilisation. |
| string $arr[col]["type"] |
Type de variable PHP pour les données de la colonne
col, où col vaut de
0 à $arr["count"]-1. La valeur retournée
peut être l'une de celles-ci :
|
| string $arr[col]["sqltype"] |
Type dedonnées SQL de la colonne col, où
col vaut de 0 à $arr["count"]-1.
La valeur retournée peut être l'une de celle-ci :
|
| string $arr[col]["length"] | La taille de l'attribut, au sens SQL, de la colonne col, où col vaut de 0 à $arr["count"]-1. La longueur est utilisée avec les champs "CHARACTER" et "VARCHAR", pour spécifier la taille maximale de la colonne. Les champs multiples SESAM sont linéarisés et traités comme autant de colonnes ayant la même taille SQL. |
| string $arr[col]["precision"] | La précision de la colonne col, au sens SQL, où col vaut de 0 à $arr["count"]-1. La précision est utilisée avec les champs numériques et de date. Les champs multiples SESAM sont linéarisés et traités comme autant de colonnes ayant la même précision SQL. |
| string $arr[col]["scale"] | L'échelle de la colonne col, au sens SQL, où col vaut de 0 à $arr["count"]-1. L'échelle est utilisée avec les champs numériques. Les champs multiples SESAM sont linéarisés et traités comme autant de colonnes ayant la même échelle SQL. |
Voir aussi sesam_query(), pour un exemple d'utilisation de sesam_field_array().
sesam_field_name
Description
int sesam_field_name ( string result_id, int index)sesam_field_name() retourne le nom du champs index dans le résultat identifié par result_id, ou FALSE en cas d'erreur.
Pour les requêtes immédiates, ou les colonnes dynamiques, une chaîne vide est retournée.
Note : Les colonnes sont indexées à partir de 0, et non pas 1.
Voir aussi : sesam_field_array(). Cette fonction fournit une interface simple aux noms et types de colonnes, et permet la detection des champs multiples.
sesam_free_result
Description
int sesam_free_result ( string result_id)sesam_free_result() libère les ressources reservées par la requête result_id. retourne FALSE en cas d'erreur.
sesam_num_fields
Description
int sesam_num_fields ( string result_id)Après avoir appelé sesam_query() avec une requête de selection, sesam_num_fields() indique le nombre de colonnes du résultat identifié par result_id. Retourne FALSE en cas d'erreur.
Pour les requêtes immédiates, la valeur zéro est retournée. Les champs multiples SESAM compte autant que leur taille respective, c'est à dire qu'un champs multiple de trois colonnes compte comme trois colonne.
Voir aussi : sesam_query() et sesam_field_array() pour savoir distinguer les champs multiples des colonnes standard.
sesam_query
Description
string sesam_query ( string query [, bool scrollable])sesam_query() retourne un identifiant de résultat SESAM en cas de succès, ou FALSE en cas d'erreur.
L'identifiant de résultat est utilisé par d'autres fonctions sesam pour lire les valeurs.
sesam_query() envoie une requête à la base active. Elle peut exécuter aussi bien une requête immédiate (DELETE, UPDATE ou INSERT), ou une requête de selection. Si une requête immédiate est exécutée, aucun curseur n'est alloué, et il ne sera pas possible d'utiliser les fonctions sesam_fetch_row() ou sesam_fetch_result(). Pour les requêtes de selection, un descripteur de résultat et un curseur (scrollable ou séquentiel, suivant le paramètre optionnel scrollable passé) sear alloué. Si scrollable est omis, le curseur sera séquentiel.
Lorsque vous utilisez les curseurs à défilement, le curseur peut être positionné librement dans le résultat. Pour chaque requête à défilement, il existe des valeurs globales de types de défilement (initialisée à :SESAM_SEEK_NEXT) et la position peut être fixée une seule fois par sesam_seek_row() ou bien à chaque appel, avec la fonction sesam_fetch_row().
Pour les requêtes immédiates, le nombre de lignes affectées est sauvé, et est accessible par la fonction sesam_affected_rows().
Voir aussi : sesam_fetch_row() et sesam_fetch_result().
Exemple 1. Liste toutes les lignes de table "phone" sous forme de table HTML
|
sesam_rollback
Description
bool sesam_rollback ( void)sesam_rollback() retourne TRUE en cas de succès et FALSE en cas d'erreur.
sesam_rollback() annule toutes les modifications en cours sur la base. Les curseurs de résultat et les descripteurs de résultats seront affectés.
A la fin de chaque script, et dans chaque appel à sesam_disconnect(), un appel implicite à sesam_rollback() est fait, annulant toutes les transactions non validées dans la base.
Voir aussi : sesam_commit().
Exemple 1. Annulation d'une transaction SESAM
|
sesam_seek_row
Description
bool sesam_seek_row ( string result_id, int whence [, int offset])result_id est un indentifiant de résultat valide (requête de sélection, et curseur à défilement créé avec sesam_query()).
whence modifie la valeur globale par défaut pour le type de défilement, spécifie le type de défilement à utiliser lors des opérations de lectures ultérieurs. Les valeurs valides sont les suivantes :
Tableau 1. Valeurs valides pour whence
| Valeur | Constante | Signification |
|---|---|---|
| 0 | SESAM_SEEK_NEXT | Lecture séquentielle (après la lecture, la position est déplacé à SESAM_SEEK_NEXT) |
| 1 | SESAM_SEEK_PRIOR | Lecture séquentielle à rebours (après la lecture, la position est déplacé à SESAM_SEEK_PRIOR) |
| 2 | SESAM_SEEK_FIRST | Repositionnement au début (après la lecture, la position est déplacée à SESAM_SEEK_NEXT) |
| 3 | SESAM_SEEK_LAST | Repositionnement à la fin (après la lecture, la position est déplacée à SESAM_SEEK_PRIOR) |
| 4 | SESAM_SEEK_ABSOLUTE | Repositionnement absolu à offset (index commencant à 0. Après la lecture, la position est placé à SESAM_SEEK_ABSOLUTE, et le pointeur interne est auto-incrémenté). |
| 5 | SESAM_SEEK_RELATIVE | Repositionnement relatif à offset, où offset peut être positif ou négatif |
offset est optionnel. Il ne sert que lorsque whence vaut soit SESAM_SEEK_RELATIVE, soit SESAM_SEEK_ABSOLUTE.
sesam_settransaction
Description
bool sesam_settransaction ( int isolation_level, int read_only)sesam_settransaction() retourne TRUE si les valeurs sont valides et que a modification a été réussie. FALSE sinon.
sesam_settransaction() remplace les valeurs par défaut du niveau d'isolation ("isolation level") et de lecture seule ("read-only") fixée par le fichier de configuration SESAM), afin d'optimiser les requêtes ultérieures et garantir la cohérence de la base. Ces valeurs ne sont utilisées que pour la prochaine transaction.
sesam_settransaction() ne peut être appelée qu'avant le début de la transaction. Elle est inefficace si la transaction a déjà commencé.
Pour simplifier l'utilisation de cette fonction dans les scripts PHP, les constantes suivantes ont été définies en PHP (reportez vous au manuel SESAM pour avoir des détails sur leur signification) :
Tableau 1. Valeurs valides pour le paramètre Isolation_Level
| Valeur | Constante | Signification |
|---|---|---|
| 1 | SESAM_TXISOL_READ_UNCOMMITTED | Lecture sans validation |
| 2 | SESAM_TXISOL_READ_COMMITTED | Lecutre avec validation |
| 3 | SESAM_TXISOL_REPEATABLE_READ | Lecture récurente |
| 4 | SESAM_TXISOL_SERIALIZABLE | Sérialisable |
Tableau 2. Valeurs valides pour le paramètre Read_Only
| Valeur | Constante | Signification |
|---|---|---|
| 0 | SESAM_TXREAD_READWRITE | Lecture/écriture |
| 1 | SESAM_TXREAD_READONLY | Lecture seule |
Les valeurs modifiées par sesam_settransaction() remplaceront les valeurs par défaut spécifiée dans le fichier de configuration SESAM.
XCII. Sessions
La gestion des sessions avec PHP est un moyen de sauver des informations entre deux accès. Cela permet notamment de construire des applications personnalisées, et d'accroître l'attrait de votre site.
Si vous connaissez déjà la gestion des sessions avec phplib, vous remarquerez que certains concepts sont similaires.
Chaque visiteur qui accède à votre site se voit assigner un numéro d'identifiant, appelé plus loin "identifiant de session". Celui-ci est enregistré soit dans un cookie, chez le client, soit dans l'URL.
Les sessions vous permettront d'enregistrer des variables pour les préserver et les réutiliser tout au long de la visites de votre site. Lorsqu'un visiteur accèdere à votre site, PHP vérifiera automatiquement (si session.auto_start est à 1) ou manuellement (explicitement avec session_start() ou implicitement avec session_register()) si une session a déjà été ouverte. Si une telle session existe déjà, l'environnement précédent sera recréé.
Toutes les variables à enregistrer seront enregistrées sur le disque à la fin de chaque requête. Les variables enregistrées mais non définies seront marquées comme telles. Lors des accès ultérieurs, elles ne seront définies que si l'utilisateur le fait.
Les options track_vars et gpc_globals modifient la façon dont les variables sont rechargées.
Note : Depuis PHP 4.0.3, track_vars est toujours activée.
Si track_vars est activée, et register_globals désactivée, alors les variables de session seront accessibles uniquement dans le tableau associatif global $HTTP_STATE_VARS. Les variables de session lues seront disponibles dans $HTTP_STATE_VARS.
Exemple 1. Enregistrer une variable lorsque l'option track_vars est activée
|
Si register_globals est activée, alors les variables de session seront placées dans les variables globales associées.
Exemple 2. Enregistrer une variable lorsque register_globals est activée
|
Si les deux options track_vars et register_globals sont activées, alors les variables globales et $HTTP_STATE_VARS contiendront les valeurs de session.
Il y a deux modes de propagation de l'identifiant de session :
Cookies
Paramètre URL
Le module de session supporte les deux techniques. La méthode par cookies est optimale, mais étant donné son peu de fiabilité (les clients peuvent refuser ou effacer les cookies), on ne peut pas se contenter de cette technique. La deuxième méthode place l'identifiant de session directement dans l'URL.
PHP est capable de gérer ceci de manière transparente, lorsque vous le compilez avec l'option --enable-trans-sid. Dans ce cas, les URL relatives seront modifiées pour contenir l'identifiant de session automatiquement. Sinon, vous pouvez toujours utiliser la constante SID, qui sera définie si le client n'envoie pas le cookie approprié. SID prend la forme de session_name=session_id, ou bien, c'est une chaîne vide.
Note : La fonction qui gérera l'écriture des données ne sera appelée qu'une fois que le script aura envoyé toutes ses données. Ainsi, les affichages tentés par cette fonction ne pourront jamais être reçus par le navigateur. Si un tel affichage est nécessaire, il est conseillé d'écrire les debugs dans un fichier.
L'exemple suivant montre comment enregistrer une variable, et comment relier correctement des pages avec SID.
Exemple 3. Compter le nombre de hits d'un utilisateur.
Pour continuer, <A HREF="nextpage.php?<?=SID"?>clique ici</?> |
Le <?=SID-> n'est pas nécessaire, si l'option --enable-trans-sid a été utilisée pour compiler PHP.
Note : Les URL absolues sont considérées comme des sites externes, et PHP ne leur attribuera pas le SID, qui pourrait représenter un trou de sécurité.
Pour enregistrer ces informations dans une base de données, il vous faut utiliser la fonction session_set_save_handler(). Il faudra alors implémenter la fonction suivante pour l'adapter à MySQL ou à toute autre base de données :
Le système de gestion des sessions dispose d'un grand nombre d'options, qui sont placées dans le fichier php.ini. En voici un survol rapide :
session.save_handler définit les noms des fonctions qui seront utilisées pour enregistrer et retrouver les données associées à une session. Par défaut, les sessions sont enregistrées dans des fichiers.
session.save_path définit l'argument qui est passé à la fonction de sauvegarde. Si vous utilisez la sauvegarde par fichier, cet argument est le chemin jusqu'au dossier où les fichiers sont créés. Par défaut, le dossier est /tmp.
Avertissement Si le dossier que vous utilisez a les droits de lecture universels, comme /tmp (valeur par défaut), les autres utilisateurs du serveur peuvent aussi lire ces fichiers, et s'immiscer dans vos sessions.
session.name spécifie le nom de la session, qui sera utilisé comme nom de cookie. Par défaut : PHPSESSID.
session.auto_start indique qu'une session doit commencer automatiquement lors de la premier requête. Par défaut, la valeur est à 0 (inactivé).
session.lifetime fixe la durée de vie, en secondes, du cookie envoyé au client. La valeur 0 signifie "jusqu'à ce que le client soit fermé". Par défaut à 0 (inactivé).
session.serialize_handler définit le nom de la fonction qui sera utilisée pour enregistrer et relire les donnés. Actuellement, c'est un format interne de PHP (nom : php) et WDDX (nom : wddx). WDDX n'est utilisable que si PHP a été compilé avec le support WDDX. Par défaut, c'est le mode php qui est sélectionné.
session.gc_probability précise la probabilité que la routine gc (garbage collection) soit lancée, en pourcentage. Par défaut, la valeur est à 1.
session.gc_maxlifetime fixe la durée, en secondes, au-delà de laquelle les données considérées comme inutiles seront supprimées.
session.referer_check représente la sous-chaîne que vous utilisez pour vérifier la provenance de l'internaute. Si l'entête HTTP Referer vous est fournie par le navigateur et que cette sous-chaîne n'est pas trouvée, la session qui vous est fournie sera considérée comme invalide (car provenant probablement d'un autre site que le votre). Par défaut, cette chaîne est vide.
session.entropy_file est le chemin jusqu'à une source externe (fichier) d'entropie, qui sera utilisée lors de la création de l'identifiant de session. Par exemple, /dev/random ou /dev/urandom qui sont disponibles sur de nombreux systèmes UNIX.
session.entropy_length précise le nombre d'octets qui seront lus dans le fichier ci-dessus. Par défaut, 0 (inactivé).
session.use_cookies cookies indique si le module doit utiliser des cookies pour enregistrer l'identifiant de session chez le client. Par défaut, 1 (activé).
session.cookie_path spécifie le chemin à utiliser avec session_cookie. Par défaut, /.
session.cookie_domain spécifie le domaine à utiliser avec session_cookie. Par défaut, rien du tout.
session.cache_limiter spécifie le contrôle du cache, à utiliser avec les pages de session (nocache/private/public). Par défaut, nocache.
session.cache_expire spécifie la durée de vie des pages de session cachées, en minutes, mais sans que cela ait d'effets sur le limiteur "nocache". Par défaut, 180.
session.use_trans_sid indique si le support du SID est activé ou pas, lors de la compilation avec l'option --enable-trans-sid. Par défaut, elle vaut 1 (activée).
url_rewriter.tags spefifies which html tags are rewritten to include session id if transient sid support is enabled. Defaults to a=href,area=href,frame=src,input=src,form=fakeentry
Note : La gestion des sessions a été ajoutée en PHP 4.0.
- Table des matières
- session_cache_expire -- Return current cache expire
- session_cache_limiter -- Lit et/ou modifie le limiteur de cache
- session_decode -- Décode les données de session à partir d'une chaîne
- session_destroy -- Détruit toutes les données enregistrées d'une session
- session_encode -- Encode les données de session dans une chaîne
- session_get_cookie_params -- Lit les paramètres du cookie de session
- session_id -- Affecte et/ou retourne l'identifiant de session courante
- session_is_registered -- Indique si une variable a été enregistrée dans la session ou pas
- session_module_name -- Affecte et/ou retourne le module courant de session courante
- session_name -- Affecte et/ou retourne le nom de la session courante
- session_readonly -- Lit les variables de session sans verrouiller les données
- session_register -- Enregistre une variable dans la session courante
- session_save_path -- Affecte et/ou retourne le chemin de sauvegarde de la session courante
- session_set_cookie_params -- Modifie les paramètres du cookie de session
- session_set_save_handler -- Définit les fonctions utilisateurs de stockage des sessions
- session_start -- Initialise les données de session
- session_unregister -- Supprime une variable dans la session courante
- session_unset -- Détruit toutes les variables de session
- session_write_close -- Write session data and end session
session_cache_expire
Description
int session_cache_expire ( [int new_cache_expire])session_cache_expire() returns current cache expire. If new_cache_expire is given, the current cache expire is replaced with new_cache_expire.
session_cache_limiter
Description
string session_cache_limiter ( [string cache_limiter])session_cache_limiter() retourne le nom du limiteur de cache courant. Si cache_limiter est spécifié, le nom du limiteur de cache est remplacé par cette nouvelle valeur.
Le limiteur de cache contrôle l'envoi des en-têtes HTTP envoyés au client. Ces en-têtes déterminent les règles de mise en cache des pages. En utilisant la valeur de nocache, par exemple, vous désactiverez la mise en cache côté client. La valeur de public, cependant, le permettra. private aussi, tout en étant légèrement plus restrictive que public.
Le limiteur de cache est remis à sa valeur par défaut, stockée dans session.cache_limiter, initialisée au lancement. Vous devrez donc appeler session_cache_limiter() pour chaque requête (et avant l'appel à session_start()).
Note : session_cache_limiter() a été ajoutée dans PHP 4.0.3.
session_decode
Description
boolean session_decode ( string data)session_decode() décode les données de session à partir de la chaîne data, et affecte les valeurs des variables de session.
Note : session_decode() a été ajoutée en PHP 4.0.
session_destroy
Description
boolean session_destroy ( void)session_destroy() détruit toutes les données associées à la session courante.
session_destroy() retourne TRUE en cas de succès, et FALSE sinon.
session_encode
Description
boolean session_encode ( void)session_encode() retourne les données de session dans une chaîne.
Note : session_encode() a été ajoutée en PHP 4.0.
session_get_cookie_params
Description
array session_get_cookie_params ( void)session_get_cookie_params() retourne un tableau avec les paramètres du cookie de la session courante. Le tableau contient les éléments suivants :
"lifetime" - La durée de vie du cookie.
"path" - Le chemin de stockage du cookie.
"domain" - Le domaine du cookie.
session_id
Description
string session_id ( [string id])session_id() retourne l'identifiant de session courante. Si id est fourni, il remplacera l'identifiant courant de la session.
La constante SID peut aussi être utilisée pour retrouver le nom de la session courante et son identifiant, comme chaîne à ajouter dans les URL.
Note : session_id() a été ajoutée en PHP 4.0.
session_is_registered
Description
boolean session_is_registered ( string name)session_is_registered() retourne TRUE s'il y a une variable du nom de name enregistrée dans la session courante.
Note : session_is_registered() a été ajoutée en PHP 4.0.
session_module_name
Description
string session_module_name ( [string module])session_module_name() affecte et/ou retourne le module courant de session courante. Si module est fourni, ce module sera utilisé à la place du courant.
Note : session_module_name() a été ajoutée en PHP 4.0.
session_name
Description
string session_name ( [string name])session_name()retourne le nom de la session courante. Si name est fourni, le nom de la session changera, et prendra la valeur fournie.
Le nom de session fait référence à l'identifiant de session dans les cookies. Il ne doit contenir que des caractères alpha-numériques; il doit être court et descriptif. (i.e. surtout pour les utilisateurs d'alertes de cookie). Le nom de session est remis à une valeur par défaut, enregistrée dans session.name au moment du démarrage. Ainsi, vous devez appeler session_name() à chaque requête (et avant session_start() ou session_register()).
Note : session_name() a été ajoutée en PHP 4.0.
session_readonly
Description
void session_readonly ( void)session_readonly() lit les variables de session sans verrouiller les données. Les modifications ne seront pas possibles, mais les performances de PHP avec les frames seront améliorées.
session_register
Description
boolean session_register ( mixed name [, mixed ...])session_register() enregistre une variable avec le nom name dans la session courante. session_register() accepte un nombre d'arguments variable. Ces arguments peuvent être soit des chaînes représentants le nom de la variable, soit un tableau, contenant des chaînes ou d'autres tableaux (cas d'un tableau récursif).
session_register() retourne TRUE lorsque les variables sont correctement enregistrées.
Note : Actuellement, il n'est pas possible d'enregistrer des variables de ressources dans une session. Par exemple, vous ne pouvez pas créer une connexion à une base de données dans un script, la stocker dans une session, et retrouver cette connexion lors de la prochaine utilisation de la session. Les fonctions qui retournent des ressources PHP sont identifées par leur valeur de retour resource, dans leur fonction de définition. Vous pouvez aussi les retrouver dans les annexes.
Note : session_register() a été ajoutée en PHP 4.0.
session_save_path
Description
string session_save_path ( [string path])session_save_path() retourne le chemin du dossier utilisé pour enregistrer les données de sessions. Si path est fourni, le chemin prendra alors la valeur fournie.
Note : Sur certains systèmes d'exploitation, il vous faudra peut être fournir un chemin vers un système de sauvegarde qui peut gérer efficacement de grandes quantités de petits fichiers : par exemple, sous Linux, reiserfs peut être plus efficace que ext2fs.
Note : session_save_path() a été ajoutée en PHP 4.0.
session_set_cookie_params
Description
void session_set_cookie_params ( int lifetime [, string path [, string domain]])session_set_cookie_params() modifie les paramètres du cookie de session, tels qu'ils ont été définis dans le fichier php.ini. L'effet de cette fonction ne dure que le temps du script.
session_set_save_handler
Description
void session_set_save_handler ( string open, string close, string read, string write, string destroy, string gc)session_set_save_handler() définit les fonctions utilisateurs de stockage et chargement des sessions. Cela est particulièrement pratique pour spécifier une autre méthode de stockage que celle fournie en standard avec PHP. Notamment, il est possible de stocker les sessions dans une base de données.
Note : Vous devez donner à l'option de configuration session.save_handler la valeur de user dans votre fichier php.ini pour que session_set_save_handler() soit effective.
L'exemple suivant fournit un exemple de stockage de session dans un fichier, similaire aux fonctions standards de PHP. Cet exemple peut être facilement étendu pour utiliser un stockage en base de données, en utilisant votre base préférée.
Exemple 1. Exemple avec session_set_save_handler()
|
session_start
Description
boolean session_start ( void)session_start() crée une session (ou continue la session courante, en fonction de l'identifiant de session passé par une variable GET ou par un cookie)
session_start() retourne toujours TRUE.
Note : session_start() a été ajoutée en PHP 4.0.
session_unregister
Description
boolean session_unregister ( string name)session_unregister() supprime la variable nommée name dans la session courante.
session_unregister() retourne TRUE lorsque la variable a été correctement supprimée de la session.
Note : session_unregister() a été ajoutée en PHP 4.0.
session_unset
Description
void session_unset ( void)session_unset() détruit toutes les variables de session couramment enregistrées.
session_write_close
Description
void session_write_close ( void)End the current session and store session data.
Session data is usually stored after your script terminated without the need to call session_write_close(), but as session data is locked to prevent concurrent writes only one script may operate on a session at any time. When using framesets together with sessions you will experience the frames loading one by one due to this locking. You can reduce the time needed to load all the frames by ending the session as soon as all changes to session variables are done.
XCIII. Mémoire partagée
Shmop est un ensemble de fonctions simples pour gérer la mémoire partagée avec PHP (lecture, écriture, création et suppressions de segments de mémoire paragée UNIX). Ces fonctions ne fonctionnent pas sous Windows, car ce système d'exploitation ne supporte pas la mémoire partagée. Pour utiliser les fonctions shmop, compilez PHP avec l'option --enable-shmop parameter.
Note : Toutes les fonctions décrites ci-dessous commencent par shm_ poru les versions jusqu'à PHP 4.0.3, mais en PHP 4.0.4 et plus récent, elles sont préfixées par shmop_.
Exemple 1. Introduction à la mémoire partagée
|
- Table des matières
- shmop_close -- Ferme un bloc de mémoire partagée
- shmop_delete -- Détruit un bloc de mémoire partagée
- shmop_open -- Crée ou ouvre un bloc de mémoire partagée
- shmop_read -- Lit un bloc
- shmop_size -- Lire la taille du bloc de mémoire partagée
- shmop_write -- Ecrire dans un bloc de mémoire partagée
shmop_close
Description
int shmop_close ( resource shmid)shmop_close() sert à fermer un bloc de mémoire partagée.
shmop_close() prend un identifiant de mémoire partagée, shmid, créé par shmop_open().
Cet exemple ferme le bloc de mémoire partagée identifié par $shm_id.
shmop_delete
Description
int shmop_delete ( resource shmid)shmop_delete() sert à détruire un bloc de mémoire partagée.
shmop_delete() prend un identifiant de mémoire partagée shmid, créé par shmop_open(). En cas de succès, la fonction retourne 1, et sinon, 0.
Ce exemple efface le bloc de mémoire partagée identifié par $shm_id.
shmop_open
Description
resource shmop_open ( int key, string flags, int mode, int size)shmop_open() peut créer ou ouvrir un bloc de mémoire partagée.
shmop_open() prend 4 paramètres: la clé, qui sera l'identifiant système pour le bloc. Ce paramètre peut être passé comme un décimal ou un héxadécimal. Le deuxième paramètre est un groupe d'options :
"a" pour accès (utilise IPC_EXCL) utilisez cette option pour ouvrir un bloc déjà existant.
"c" pour création (utilise IPC_CREATE) utilisez cette option pour créer un nouveau bloc.
Note : Les troisième et quatrième paramètres doivent être passés à 0 si vous voulez ouvrir un bloc de mémoire partagée déjà existant. En cas de succès shmop_open() retourne un identifiant que vous pouvez utiliser pour accéder à la mémoire que vous venez de créer.
Cet exemple ouvre un nouveau bloc de mémoire partagée, dont l'identifiant est 0x0fff.
shmop_read
Description
string shmop_read ( resource shmid, int start, int count)shmop_read() lit une chaîne dans une bloc de mémoire partagée.
shmop_read() prend 3 paramètres: shmid, qui est un identifiant de mémoire partagée, créé par shmop_open(), start qui est la position à partir de laquelle on commence à lire dans la mémoire et count, le nombre d'octets à lire.
Cet exemple lit 50 octets dans le bloc de mémoire partagée $shm_data.
shmop_size
Description
int shmop_size ( resource shmid)shmop_size() sert à connaître la taille, en octets, d'un bloc de mémoire partagée.
shmop_size() prend comme argument shmid, un identifiant de bloc de mémoire partagée créé par shmop_open(), et retourne un entier, qui représente le taille de ce bloc.
Cet exemple lit la taille du bloc identifié par $shm_id, et le place dans $shm_size.
shmop_write
Description
int shmop_write ( resource shmid, string data, int offset)shmop_write() écrit une chaîne dans un bloc de mémoire partagée.
shmop_write() prend 3 paramètres: shmid, qui est un identifiant de mémoire partagée, créé par shmop_open(), data qui est la chaîne à écrire dans la mémoire et offset, la position à partir de laquelle il faut commencer à écrire.
Cet exemple écrit les données de la chaîne $my_string dans un bloc de mémoire partagée. $shm_bytes_written représentera le nombre d'octets écrits.
XCIV. Shockwave Flash
PHP a la capacité de créer des animations Shockwave Flash grâce au module de Paul Haeberli : libswf module. Vous pouvez télécharger libswf à ftp://ftp.sgi.com/sgi/graphics/grafica/flash. Une fois que vous avez libswf, tout ce qui reste à faire est de configurer PHP avec --with-swf[=DIR] où DIR est le dossier qui accueille les dossiers de include et lib. Le dossier include doit contenir le fichier swf.h file et le dossier lib doit contenir le fichier libswf.a. Si vous décompressez la distribution de libswf, les deux fichiers seront dans le même dossier. Par conséquent, vous devrez les mettre dans le dossier ad hoc manuellement.
Une fois que vous avez réussi à installer PHP avec Shockwave Flash, vous pouvez créer des animations Flash avec PHP. Vous serez surpris du résultat. Essayez donc ceci :
Exemple 1. Exemple SWF
|
Note : Le support de Flash a été ajouté en PHP 4.0RC2.
La librairie libswf n'est pas disponible pour Windows : son développement a été stoppé, et les sources ne sont plus disponibles pour permettre le portage vers d'autres systèmes.
- Table des matières
- swf_actiongeturl -- Retourne l'URL d'une animation Shockwave Flash.
- swf_actiongotoframe -- Joue un frame puis stoppe.
- swf_actiongotolabel -- Affiche le frame nommé.
- swf_actionnextframe -- Avance d'un frame.
- swf_actionplay -- Joue l'animation flash à partir du frame courant.
- swf_actionprevframe -- Recule d'un frame.
- swf_actionsettarget -- Fixe le contexte des actions.
- swf_actionstop -- Arrête l'animation flash.
- swf_actiontogglequality -- Choisit le niveau de qualité haut ou bas.
- swf_actionwaitforframe -- Ignore les actions si le frame n'est pas chargé.
- swf_addbuttonrecord -- Contrôle la situation, l'aparance et la zone active du bouton courant.
- swf_addcolor -- Fixe la couleur globale d'addition (? : the global add color).
- swf_closefile -- Ferme le fichier courant Shockwave Flash.
- swf_definebitmap -- Définit une image bitmap.
- swf_definefont -- Définit une police.
- swf_defineline -- Définit une ligne.
- swf_definepoly -- Définit un polygone.
- swf_definerect -- Définit un rectangle.
- swf_definetext -- Définit une chaîne de texte.
- swf_endbutton -- Termine la définition du bouton courant.
- swf_enddoaction -- Termine l'action courante.
- swf_endshape -- Complète la définition de la forme courante.
- swf_endsymbol -- Termine la définition de symbole.
- swf_fontsize -- Change la taille de la police.
- swf_fontslant -- Change l'inclinaison de la police courante.
- swf_fonttracking -- Change l'espacement des caractères.
- swf_getbitmapinfo -- Lit les informations sur une image.
- swf_getfontinfo -- Retourne la hauteur du A majuscule, et du x minuscule.
- swf_getframe -- Retourne le numéro de frame courant.
- swf_labelframe -- Nomme le frame courant.
- swf_lookat -- Définit une transformation de vue.
- swf_modifyobject -- Modifie un objet.
- swf_mulcolor -- Fixe la couleur globale de multiplication (? : the global multiply color).
- swf_nextid -- Retourne le prochain identifiant d'objet libre.
- swf_oncondition -- Décrit une transition utilisée pour déclencher une liste d'actions.
- swf_openfile -- Ouvre un nouveau fichier Shockwave Flash
- swf_ortho2 -- Définit une projection orthogonale à 2 dimensions entre les coordonnées utilisateur et le port courant.
- swf_ortho -- Définit une projection orthogonale entre les coordonnées utilisateur et le port courant.
- swf_perspective -- Définit une projection orthogonale à 3 dimensions entre les coordonnées utilisateur et le port courant
- swf_placeobject -- Place un objet sur la scène.
- swf_polarview -- Défini le point de vue de l'utilisateur en coordonnées polaire.
- swf_popmatrix -- Dépile la matrice de transformation.
- swf_posround -- Active l'approximation des translation d'objets.
- swf_pushmatrix -- Empile la matrice de transformation courante dans la pile.
- swf_removeobject -- Enlève un objet.
- swf_rotate -- Rotation de la transformation courante.
- swf_scale -- Homothétie.
- swf_setfont -- Change la police courante.
- swf_setframe -- Fixe le frame courant.
- swf_shapearc -- Dessine une arc de cercle.
- swf_shapecurveto3 -- Dessine une courbe Bézier cubique.
- swf_shapecurveto -- Dessine une courbe de Bézier quadratique entre deux points.
- swf_shapefillbitmapclip -- Choisit le mode de remplissage par texture.
- swf_shapefillbitmaptile -- Choisit le mode de remplissage par texture repétée.
- swf_shapefilloff -- Inactive le remplissage.
- swf_shapefillsolid -- Fixe la couleur pour le style courant de remplissage.
- swf_shapelinesolid -- Fixe le style courant de ligne.
- swf_shapelineto -- Dessine une ligne.
- swf_shapemoveto -- Change la position courante.
- swf_showframe -- Affiche le frame courant.
- swf_startbutton -- Commence la définition d'un bouton.
- swf_startdoaction -- Commence la description d'une liste d'action pour la frame courante.
- swf_startshape -- Commence une forme complexe.
- swf_startsymbol -- Définit un symbole.
- swf_textwidth -- Retourne la longueur d'une chaîne.
- swf_translate -- Translate la transformation courante.
- swf_viewport -- Sélectionne une nouvelle zone pour un dessin ultérieur.
swf_actiongeturl
Description
void swf_actiongeturl ( string url, string target)swf_actiongeturl() lit l'URL url, avec la destination target.
swf_actiongotoframe
Description
void swf_actiongotoframe ( int framenumber)swf_actiongotoframe() se déplace jusqu'au frame framenumber, le joue, puis s'arrête.
swf_actiongotolabel
Description
void swf_actiongotolabel ( string label)swf_actiongotolabel() affiche le frame de nom label, puis stoppe.
swf_actionnextframe
Description
void swf_actionnextframe ( void)swf_actionnextframe() avance d'un frame le frame courant.
swf_actionplay
Description
void swf_actionplay ( void)swf_actionplay() joue l'animation Flash à partir du frame courant.
swf_actionprevframe
Description
void swf_actionprevframe ( void)swf_actionnextframe() recule d'un frame le frame courant.
swf_actionsettarget
Description
void swf_actionsettarget ( string target)swf_actionsettarget() fixe le contexte des actions. Vous pouvez utiliser cette fonction pour contrôler d'autres animations Flash qui seraient en fonctionnement.
swf_actionstop
swf_actiontogglequality
Description
void swf_actiontogglequality ( void)swf_actiontogglequality() modifie le niveau de qualité haut ou bas.
swf_actionwaitforframe
Description
void swf_actionwaitforframe ( int framenumber, int skipcount)swf_actionwaitforframe() vérifie que le frame framenumber a bien été chargé. Si ce n'est pas le cas, elle ignore les actions skipcount. Cela est très utile pour les séquences du type "Chargement...".
swf_addbuttonrecord
(PHP 4 )
swf_addbuttonrecord -- Contrôle la situation, l'aparance et la zone active du bouton courant.Description
void swf_addbuttonrecord ( int states, int shapeid, int depth)swf_addbuttonrecord() permet de modifier les caractéristiques d'un bouton. states, définit les états du bouton autorisés : ce peut être : BSHitTest, BSDown, BSOver ou BSUp. shapeid est l'apparence du bouton, c'est-à-dire l'objet qui représente le bouton. depth est la profondeur de placement du bouton, dans le frame courant.
Exemple 1. Exemple avec swf_addbuttonrecord()
|
swf_addcolor
Description
void swf_addcolor ( float r, float g, float b, float a)swf_mulcolor() fixe la valeur globale de multiplication (the global multiply color...) à la couleur rgba. Cette couleur est utilisée (implicitement) par swf_placeobject(), swf_modifyobject() et swf_addbuttonrecord(). La couleur d'un objet sera ajouté à rgba lorsque l'objet est placé sur la scène.
Note : Les valeurs de rgba peuvent être positives ou négatives.
swf_closefile
Description
void swf_closefile ( [int return_file])swf_closefile() ferme le fichier courant, qui a été ouvert avec swf_openfile(). Si le paramètre return_file a été fourni, il contiendra le fichier SWF fermé.
Exemple 1. Création d'un fichier Flash simple, basé sur une entrée de l'utilisateur, et sauvegarde dans une base.
|
swf_definebitmap
Description
void swf_definebitmap ( int objid, string image_name)swf_definebitmap() définit une bitmap à partir d'une image au format GIF, JPEG, RGB ou FI. L'image sera convertie en Flash JPEG ou Flash color map.
swf_definefont
Description
void swf_definefont ( int fontid, string fontname)swf_definefont() définit la police fontname et lui affecte l'identifiant fontid. Cette police devient alors la police courante.
swf_defineline
Description
void swf_defineline ( int objid, float x1, float y1, float x2, float y2, float width)swf_defineline() définit une ligne commençant aux coordonnées (x1, y1), et finissant au point de coordonnées (x2, y2). Elle aura la largeur de width.
swf_definepoly
Description
void swf_definepoly ( int objid, array coords, int npoints, float width)swf_definepoly() définit un polygone, dont les coordonnées des sommets sont placés dans le tableau coords). npoints est le nombre de points contenu dans le tableau coords. width est la largeur des bords du polygone. Si width vaut 0.0, le polygone sera rempli.
swf_definerect
Description
void swf_definerect ( int objid, float x1, float y1, float x2, float y2, float width)swf_definerect() définit un rectangle, de coin supérieur gauche aux coordoonées (x1,y1), et de coin inférieur droit aux coordonnées (x2, y2). L'épaisseur des bords est données par le paramètre width. width, 0.0 le rectangle sera rempli.
swf_definetext
Description
void swf_definetext ( int objid, string str, int docenter)swf_definetext() définit la chaîne de texte str, en utilisant la police courante. docenter indique si la chaîne doit être centrée (valeur de 1), ou pas.
swf_endbutton
swf_enddoaction
Description
void swf_enddoaction ( void)swf_startdoaction() termine l'action courante, démarrée par swf_startdoaction().
swf_endshape
swf_endsymbol
Description
void swf_endsymbol ( void)swf_endsymbol() termine la définition de symble, qui a été commencée avec swf_startsymbol().
swf_fontsize
Description
void swf_fontsize ( float size)swf_fontsize() remplace la taille de la police par la taille size.
swf_fontslant
Description
void swf_fontslant ( float slant)swf_fontslant() fixe l'inclinaison de la police courante à slant. Les valeurs positives values créeront une inclinaison vers la droite, et les valeurs négatives, vers la gauche.
swf_fonttracking
Description
void swf_fonttracking ( float tracking)swf_fonttracking() change l'espacement, et lui affecte la valeur de tracking. Cette fonction sert à accroître l'espace entre les lettres et le texte. Les valeurs positives accroissent cet espace, et les valeurs négatives le réduisent.
swf_getbitmapinfo
Description
array swf_getbitmapinfo ( int bitmapid)swf_getbitmapinfo() retourne un tableau d'informations sur l'image bitmap repérée par bitmapid. Le tableau a les éléments suivants :
"size" - La taille en octets de l'image.
"width" - La largueur en pixels de l'image.
"height" - La hauteur en pixels de l'image.
swf_getfontinfo
Description
array swf_getfontinfo ( void)swf_getfontinfo() retourne la hauteur du A majuscule, et du x minuscule, dans un tableau associatif :
Aheight - La hauteur du A majuscule, en pixels.
xheight - La hauteur du x minuscule, en pixels.
swf_getframe
swf_labelframe
swf_lookat
Description
void swf_lookat ( float view_x, float view_y, float view_z, float reference_x, float reference_y, float reference_z, float twist)swf_lookat() définit une transformation de vue, en donnant la position de la vue, de coordonnées (view_x, view_y et view_z) et les coordonnées du point de référence dans la scène, de coordonnées (reference_x, reference_y, reference_z). Le paramètre twist contrôle la rotation le long de l'axe des z de l'utilisateur.
swf_modifyobject
Description
void swf_modifyobject ( int depth, int how)swf_modifyobject() modifie la position et/ou la couleur de l'objet situé à la profondeur de depth. L'argument how détermine ce qui doit être modifié. how peut prendre les valeurs de MOD_MATRIX, MOD_COLOR ou la combinaison des deux.
MOD_COLOR utilise la couleur courante de multiplication (spécifiée par swf_mulcolor()) et la couleur courante d'addition (spécifiée par swf_addcolor()) pour colorer l'objet, et MOD_MATRIX utilise la matrice courante pour positionner l'objet.
swf_mulcolor
Description
void swf_mulcolor ( float r, float g, float b, float a)swf_mulcolor() fixe la valeur globale de multiplication (the global multiply color...) à la couleur rgba. Cette couleur est utilisée (implicitement) par swf_placeobject(), swf_modifyobject() et swf_addbuttonrecord(). La couleur d'un objet sera multipliée par rgba lorsque l'objet est placé sur la scène.
Note : Les valeurs de rgba peuvent être positives ou négatives.
swf_nextid
swf_oncondition
Description
void swf_oncondition ( int transition)swf_oncondition() décrit une transition qui va déclencher une liste d'actions. Il y a plusieurs types de transition possibles, les suivantes sont destinées aux boutons de type TYPE_MENUBUTTON:
IdletoOverUp
OverUptoIdle
OverUptoOverDown
OverDowntoOverUp
IdletoOverDown
OutDowntoIdle
MenuEnter (IdletoOverUp|IdletoOverDown)
MenuExit (OverUptoIdle|OverDowntoIdle)
IdletoOverUp
OverUptoIdle
OverUptoOverDown
OverDowntoOverUp
OverDowntoOutDown
OutDowntoOverDown
OutDowntoIdle
ButtonEnter (IdletoOverUp|OutDowntoOverDown)
ButtonExit (OverUptoIdle|OverDowntoOutDown)
swf_openfile
Description
void swf_openfile ( string filename, float width, float height, float framerate, float r, float g, float b)swf_openfile() crée un nouveau fichier filename de largeur width, et de hauteur height, à la vitesse de framerate, de couleur de fond RGB (r, g, b).
swf_openfile() doit être la première fonction à appeler, sous peine d'erreur mémoire (segmentation fault). Si vous voulez envoyer votre production au client HTML, utilisez le nom de fichier "php://stdout" (le support de ceci est prévue pour la version 4.0.1 et ultérieur).
swf_ortho2
(PHP 4 )
swf_ortho2 -- Définit une projection orthogonale à 2 dimensions entre les coordonnées utilisateur et le port courant.Description
void swf_ortho2 ( float xmin, float xmax, float ymin, float ymax)swf_ortho2() définit une projection orthogonale à 2 dimensions entre les coordonnées utilisateur et le port courant. C'est la projection par défaut des animations Flash. Si vous souhaitez une perspective, utilisez plutôt swf_perspective().
swf_ortho
(PHP 4 >= 4.0.1)
swf_ortho -- Définit une projection orthogonale entre les coordonnées utilisateur et le port courant.Description
void swf_ortho ( float xmin, float xmax, float ymin, float ymax, float zmin, float zmax)swf_ortho() définit une projection orthogonale entre les coordonnées utilisateur et le port courant.
swf_perspective
(PHP 4 )
swf_perspective -- Définit une projection orthogonale à 3 dimensions entre les coordonnées utilisateur et le port courantDescription
void swf_perspective ( float fovy, float aspect, float near, float far)swf_perspective() définit une projection orthogonale à 3 dimensions entre les coordonnées utilisateur et le port courant. Le paramètre fovy est l'angle de vue de la direction y. Le paramètre aspect doit être choisi pour correspondre au ratio de la vue utilisée. near est le plan adjacent proche far est le plan adjacent distant.
Note : Diverses distorsions peuvent apparaître lors de ce genre de projection, car Flash ne dispose que d'une matrice à 2 dimensions. Certaines distorsions font vraiment tâche d'encre.
swf_placeobject
Description
void swf_placeobject ( int objid, int depth)swf_placeobject() place l'objet objid dans le frame courant, à la profondeur depth. objid et depth doivent être compris entre 1 et 65535.
swf_placeobject() utilise la couleur courante de multiplication (spécifiée par swf_mulcolor()) et la couleur courante d'addition (spécifiée par swf_addcolor()) pour colorer l'objet, et utilise la matrice courante pour positionner l'objet.
Note : Le support des couleurs RGBA est complet.
swf_polarview
Description
void swf_polarview ( float dist, float azimuth, float incidence, float twist)swf_polarview() définit la position de l'utilisateur en coordonnées polaires. dist est la distance entre le point de vue et l'origine. azimuth définit l'angle azimutal dans le plan x,y mesuré en distance depuis l'axe y. incidence définit l'angle d'incidence dans le plan y,z, mesuré en distance depuis l'axe z. Finalement, twist est l'angle de rotation du point de vue sur la ligne de vue, en utilisant la règle de la main droite.
swf_popmatrix
swf_posround
Description
void swf_posround ( int round)swf_posround() active ou désactive l'approximation lors des translations, lorsque des objets sont placés ou déplacés. Il y a des situations où le texte devient plus lisible lorsque l'approximation a été activée. round active l'approximation (1) ou la désactive (0).
swf_pushmatrix
Description
void swf_pushmatrix ( void)swf_pushmatrix() empile la matrice de transformation courante dans la pile.
swf_removeobject
Description
void swf_removeobject ( int depth)swf_removeobject() enlève l'objet situé à la profondeur depth de la scène.
swf_rotate
Description
void swf_rotate ( float angle, string axis)swf_rotate() fait subir la roation d'angle angle, autour de l'axe axis. Les valeurs possibles pour axis sont : 'x' (axe x), 'y' (axe y) ou 'z' (axe z).
swf_scale
Description
void swf_scale ( float x, float y, float z)swf_scale() fait une mise à l'échelle de x pour les coordonnées x, de y pour les coordonnées y et z pour les coordonnées z.
swf_setfont
Description
void swf_setfont ( int fontid)swf_setfont() remplace la police courante par la police repérée par l'identifiant fontid.
swf_setframe
Description
void swf_setframe ( int framenumber)swf_setframe() sélectionne le frame framenumber comme frame actif.
swf_shapearc
Description
void swf_shapearc ( float x, float y, float r, float ang1, float ang2)swf_shapearc() dessine un arc de cercle, depuis l'angle ang1 jusqu'à l'angle ang2. Le centre du cercle est aux coordonnées (x, y), et de rayon r.
swf_shapecurveto3
Description
void swf_shapecurveto3 ( float x1, float y1, float x2, float y2, float x3, float y3)Dessine une courbe de Bézier cubique, en utilisant les points de coordoonnées (x1, y1) et (x2,y2) comme points de contrôle et le point de coordonnées (x3,y3) comme point final. La position finale devient alors la position courante.
swf_shapecurveto
Description
void swf_shapecurveto ( float x1, float y1, float x2, float y2)swf_shapecurveto() dessine la courbe de Bézier quadratique entre les points de coordonnées (x1 , y1) et (x2, y2). La position courante devient alors (x2, y2).
swf_shapefillbitmapclip
Description
void swf_shapefillbitmapclip ( int bitmapid)Choisit le mode de remplissage par texture : les espaces vides seront remplis avec la bitmap bitmapid.
swf_shapefillbitmaptile
Description
void swf_shapefillbitmaptile ( int bitmapid)Choisit le mode de remplissage par texture : les espaces vides seront remplis avec la bitmap bitmapid, repétée autant de fois qu'il le faut (mode carrelage).
swf_shapefilloff
Description
void swf_shapefilloff ( void)swf_shapefilloff() inactive le remplissage pour la forme courante.
swf_shapefillsolid
Description
void swf_shapefillsolid ( float r, float g, float b, float a)swf_shapefillsolid() fixe la couleur pour le style courant de remplissage à rgba.
swf_shapelinesolid
Description
void swf_shapelinesolid ( float r, float g, float b, float a, float width)swf_shapelinesolid() permet de choisir le style de ligne, à savoir la couleur et la largeur. Si width vaut 0.0, les lignes ne seront pas dessinées.
swf_shapelineto
Description
void swf_shapelineto ( float x, float y)swf_shapelineto() dessine une ligne entre la position courante et le point de coordonnées (x, y). La position courante devient alors (x, y).
swf_shapemoveto
Description
void swf_shapemoveto ( float x, float y)swf_shapemoveto() fixe la position courante au point de coordonnées (x, y).
swf_showframe
swf_startbutton
Description
void swf_startbutton ( int objid, int type)swf_startbutton() commence la définition d'un bouton. type peut prendre les valeurs de TYPE_MENUBUTTON ou TYPE_PUSHBUTTON. La constante TYPE_MENUBUTTON permet au focus de traverser lorsque la souris est cliquée, alors que TYPE_PUSHBUTTON ne le permet pas.
swf_startdoaction
Description
void swf_startdoaction ( void)swf_startdoaction() commence la description d'une liste d'actions pour la frame courante. Cette fonction doit être appelée avant que les actions ne soient définies pour le cadre courant.
swf_startshape
Description
void swf_startshape ( int objid)swf_startshape() commence une forme complexe, qui sera reperé par l'identifiant d'objet objid.
swf_startsymbol
Description
void swf_startsymbol ( int objid)swf_startsymbol() définit un identifiant d'objet comme symbole. Les symboles sont des petites animations Flash qui peuvent être jouées simultanément. objid est l'identifiant d'objet que vous voulez définir comme symbole.
swf_textwidth
Description
float swf_textwidth ( string str)swf_textwidth() retourne la longueur de la chaîne str, en pixels, en utilisant la police courante.
swf_translate
Description
void swf_translate ( float x, float y, float z)swf_translate() déplace la transformation courante de x, y et z, dans les directions x, y et z.
swf_viewport
Description
void swf_viewport ( float xmin, float xmax, float ymin, float ymax)swf_viewport() sélectionne une nouvelle zone pour y dessiner ultérieurement. La zone est définie de xmin à xmax et de ymin à ymax. Si cette fonction n'est pas appelée, les valeurs par défaut sont celles de l'écran courant.
XCV. SNMP
Afin de pouvoir utiliser les fonctions SNMP sous Unix, vous aurez besoin d'installer le package UCD SNMP. Sous Windows ces fonctions ne sont disponibles que sous NT, et pas sous Win95/98.
Important : Afin d'utiliser le package UCD SNMP, vous devez mettre la variable NO_ZEROLENGTH_COMMUNITY à 1 avant de compiler. Après avoir configuré UCD SNMP, éditez le fichier config.h et recherchez la valeur NO_ZEROLENGTH_COMMUNITY. Décommentez la ligne avec le #define. Cela doit ressembler à ceci :
#define NO_ZEROLENGTH_COMMUNITY 1 |
Si vous avez des erreurs "segmentation faults", lors de l'utilisation des commandes SNMP, c'est que vous n'avez pas suivi les recommendations précédentes. Si vous ne voulez pas recompiler UCD SNMP, vous pouvez aussi recompiler PHP avec l'option --enable-ucd-snmp-hack qui évitera cette erreur.
- Table des matières
- snmp_get_quick_print -- Lit la valeur courante de l'option quick_print de la librairie UCD.
- snmp_set_quick_print -- Ecrit la valeur courante de l'option quick_print de la librairie UCD.
- snmpget -- Reçoit un objet SNMP.
- snmprealwalk -- Return all objects including their respective object ID within the specified one
- snmpset -- Envoie un objet SNMP.
- snmpwalk -- Reçoit tous les objets SNMP d'un agent.
- snmpwalkoid -- Demande d'informations d'arbre sur une entité du réseau.
snmp_get_quick_print
(PHP 3>= 3.0.8, PHP 4 )
snmp_get_quick_print -- Lit la valeur courante de l'option quick_print de la librairie UCD.Description
boolean snmp_get_quick_print ( void )snmp_get_quick_print() retourne la valeur courante, stockée dans la librairie UCD, de l'option quick_print. Par défaut, quick_print est inactivée.
L'exemple ci-dessus devrait retourner FALSE, si quick_print est inactivée et, TRUE si quick_print est activée.
snmp_get_quick_print() est seulement disponible avec la librairie UCD SNMP. Cette fonction n'est pas disponible avec la librairie Windows SNMP.
Voir : snmp_set_quick_print() pour une description complète de l'affichage de quick_print.
snmp_set_quick_print
(PHP 3>= 3.0.8, PHP 4 )
snmp_set_quick_print -- Ecrit la valeur courante de l'option quick_print de la librairie UCD.Description
void snmp_set_quick_print ( boolean quick_print)snmp_set_quick_print() fixe la valeur de l'option quick_print de la librairie UCD SNMP. Lorsqu'elle a la valeur de (1), la librairie SNMP retournera des valeurs 'rapides'. Cela signifie que seule, la valeur sera retournée. Lorsqu'elle a la valeur de (0), la librairie va afficher d'autres informations (telles que l'adresse IP (IpAddress) ou OID). De plus, si quick_print n'est pas activée, la librairie affichera aussi des valeurs hexadécimales supplémentaires pour toutes les chaînes de trois caractères, ou moins.
Modifier quick_print est plus fréquent lorsqu'on utilise les valeurs retournées que lorsqu'on les affiche.
snmp_set_quick_print(0);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a<BR>\n";
snmp_set_quick_print(1);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a<BR>\n"; |
La première valeur affichée sera : 'Timeticks: (0) 0:00:00.00', tandis qu'avec quick_print activée, seul '0:00:00.00' sera affiché.
Par défaut, UCD SNMP retourne des valeurs détaillées, et quick_print sert à ne retourner que la valeur.
Actuellement, les chaînes sont toujours retournées avec des guillemets supplémentaires. Ceci sera corrigé ultérieurement.
snmp_set_quick_print() ne fonctionne qu'avec la librairie UCD SNMP. snmp_set_quick_print() n'est pas disponible avec la librairie Windows SNMP.
snmpget
Description
string snmpget ( string hostname, string community, string object_id [, int timeout [, int retries]])snmpget() retourne un objet SNMP en cas de succès, et FALSE en cas d'erreur.
snmpget() sert à lire une valeur d'un objet SNMP représenté par object_id. L'agent SNMP est défini par hostname et la communauté de lecture est spécifiée par le paramètre community.
snmprealwalk
(PHP 3>= 3.0.8, PHP 4 )
snmprealwalk -- Return all objects including their respective object ID within the specified oneDescription
array snmprealwalk ( string host, string community, string object_id [, int timeout [, int retries]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
snmpset
Description
bool snmpset ( string hostname, string community, string object_id, string type, mixed value [, int timeout [, int retries]])snmpset() modifie la valeur de l'objet SNMP spécifié, en retournant TRUE en cas de succès et FALSE en cas d'erreur.
snmpget() sert à affecter une valeur donnée à un objet SNMP, référencé par object_id. L'agent SNMP est défini par hostname et la communauté de lecture est spécifiée par le paramètre community.
snmpwalk
Description
array snmpwalk ( string hostname, string community, string object_id [, int timeout [, int retries]])snmpwalk() retourne un tableau d'objets SNMP, en commencant à partir de object_id comme racine, ou FALSE en cas d'erreur.
snmpwalk() sert à lire toutes les valeurs d'un agent SNMP, défini par hostname. community définit la communauté de lecture de l'agent. Un objet (object_id = NULL) sert de racine à l'arbre d'objet SNMP et tous les objets sous cette racine sont retournés dans un tableau. Si object_id est spécifié, tous les objets SNMP sous cet objet sont retournés.
La fonction ci-dessus va retourner tous les objets SNMP d'un agent SNMP qui fonctionnerait sur l'hôte local (localhost). Il suffit alors de faire une boucle pour travailler avec chacun des objets.
snmpwalkoid
Description
array snmpwalkoid ( string hostname, string community, string object_id [, int timeout [, int retries]])snmpwalkoid() retourne un tableau associatif, avec les identifiants d'objet et les objets associés, pour tous les objets situés sous la racine object_id, ou FALSE en cas d'erreur.
snmpwalkoid() sert à lire tous les identifiants d'objet, et leur valeurs respectives, depuis un serveur SNMP. community indique la communauté de lecture pour cet agent. Un object_id NULL signifie qu'il faut utiliser la racine de l'arbre SNMP et tous les objets sous cet arbre seront retournés. Si object_id est spécifié, tous les objets SNMP situés sous cet objet seront retournés.
La fonction ci-dessous va lire tous les objets de l'agent SNMP qui fonctionne sur l'hôte local. Il est alors possible de les passer en revue avec une boucle : l'existence de snmpwalkoid() et snmpwalk() est une question d'évolution. Ces deux fonctions sont fournies pour des raisons de compatbilité ascendante.
La fonction ci-dessous va lire tous les objets de l'agent SNMP qui fonctionne sur l'hôte local. Il est alors possible de les passer en revue avec une boucle :
XCVI. Sockets
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
L'extension socket implémente une interface bas niveau avec les fonctions de communication par socket. Cela permet de mettre en place un serveur aussi bien qu'un client.
Les fonctions socket décrites ici sont rassemblées dans une extension PHP. Pour être activées, il faut utiliser l'option de compilation --enable-sockets au script configure.
Pour une interface client plus générique, reportez vous à fsockopen() et pfsockopen().
Lorsque vous utiliserez les fonctions de sockets qui sont décrites ici, gardez bien à l'esprit que même si elles ont souvent des noms identiques aux fonctions C, elles ont souvent des prototypes différents. Lisez attentivement la documentation pour éviter les confusions.
Cela dit, ceux qui n'ont pas l'habitude de la programmation avec les sockets pourront trouver beaucoup de documentation pertinente dans les pages de manuel Unix, et de nombreux tutorial de programmation C sur le web, dont la plus part peuvent être repris après de légère modifications, en PHP.
Exemple 1. Exemple de programmation Socket : serveur TCP/IP Cet exemple est un serveur perroquete : tout ce que vous lui envoyez vous est retourné. Changez les variables address et port pour les adapter à votre configuration, et lancez le script. Vous pouvez vous connecter au serveur avec une commande telle que telnet 192.168.1.53 10000 (avec l'adresse et le port qui sont ceux de votre configuration). Pour vous déconnecter, tapez 'quit'.
|
Exemple 2. Exemple avec les sockets : Client TCP/IP Cet exemple est un client HTTP basique. Il se connecte à une page envoi les entêtes (requête HEAD), affiche le retour, et quitte.
|
- Table des matières
- socket_accept -- Accepts a connection on a socket
- socket_bind -- Binds a name to a socket
- socket_clear_error -- Clears the error on the socket or the last error code
- socket_close -- Closes a socket resource
- socket_connect -- Initiates a connection on a socket
- socket_create_listen -- Opens a socket on port to accept connections
- socket_create_pair -- Creates a pair of indistinguishable sockets and stores them in fds.
- socket_create -- Create a socket (endpoint for communication)
- socket_get_option -- Gets socket options for the socket
- socket_getpeername -- Queries the remote side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type.
- socket_getsockname -- Queries the local side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type.
- socket_iovec_add -- Adds a new vector to the scatter/gather array
- socket_iovec_alloc -- ...]) Builds a 'struct iovec' for use with sendmsg, recvmsg, writev, and readv
- socket_iovec_delete -- Deletes a vector from an array of vectors
- socket_iovec_fetch -- Returns the data held in the iovec specified by iovec_id[iovec_position]
- socket_iovec_free -- Frees the iovec specified by iovec_id
- socket_iovec_set -- Sets the data held in iovec_id[iovec_position] to new_val
- socket_last_error -- Returns the last error on the socket
- socket_listen -- Listens for a connection on a socket
- socket_read -- Reads a maximum of length bytes from a socket
- socket_readv -- Reads from an fd, using the scatter-gather array defined by iovec_id
- socket_recv -- Receives data from a connected socket
- socket_recvfrom -- Receives data from a socket, connected or not
- socket_recvmsg -- Used to receive messages on a socket, whether connection-oriented or not
- socket_select -- Runs the select() system call on the given arrays of sockets with a timeout specified by tv_sec and tv_usec
- socket_send -- Sends data to a connected socket
- socket_sendmsg -- Sends a message to a socket, regardless of whether it is connection-oriented or not
- socket_sendto -- Sends a message to a socket, whether it is connected or not
- socket_set_nonblock -- Sets nonblocking mode for file descriptor fd
- socket_set_option -- Sets socket options for the socket
- socket_shutdown -- Shuts down a socket for receiving, sending, or both.
- socket_strerror -- Return a string describing a socket error
- socket_write -- Write to a socket
- socket_writev -- Writes to a file descriptor, fd, using the scatter-gather array defined by iovec_id
socket_accept
Description
resource socket_accept ( resource socket)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
After the socket socket has been created using socket_create(), bound to a name with socket_bind(), and told to listen for connections with socket_listen(), this function will accept incoming connections on that socket. Once a successful connection is made, a new socket resource is returned, which may be used for communication. If there are multiple connections queued on the socket, the first will be used. If there are no pending connections, socket_accept() will block until a connection becomes present. If socket has been made non-blocking using socket_set_blocking() or socket_set_nonblock(), FALSE will be returned.
The socket resource returned by socket_accept() may not be used to accept new connections. The original listening socket socket, however, remains open and may be reused.
Returns a new socket resource on success, or FALSE on error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to socket_strerror() to get a textual explanation of the error.
See also socket_bind(), socket_connect(), socket_listen(), socket_create(), and socket_strerror().
socket_bind
Description
bool socket_bind ( resource socket, string address [, int port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
socket_bind() binds the name given in address to the socket described by socket, which must be a valid socket resource created with socket_create().
The address parameter is either an IP address in dotted-quad notation (e.g. 127.0.0.1), if the socket is of the AF_INET family; or the pathname of a Unix-domain socket, if the socket family is AF_UNIX.
The port parameter is only used when connecting to an AF_INET socket, and designates the port on the remote host to which a connection should be made.
Retourne TRUE en cas de succès, FALSE en cas d'échec. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.
See also socket_connect(), socket_listen(), socket_create(), socket_last_error() and socket_strerror().
socket_clear_error
Description
void socket_clear_error ( [resource socket])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
This function clears the error code on the given socket or the global last socket error.
This function allows explicitely resetting the error code value either of a socket or of the extension global last error code. This may be useful to detect within a part of the application if an error occured or not.
See also socket_last_error() and socket_strerror().
socket_close
Description
void socket_close ( resource socket)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
socket_close() closes the socket resource given by socket.
Note : socket_close() can't be used on PHP file resources created with fopen(), popen(), fsockopen(), or psockopen(); it is meant for sockets created with socket_create() or socket_accept().
See also socket_bind(), socket_listen(), socket_create() and socket_strerror().
socket_connect
Description
bool socket_connect ( resource socket, string address [, int port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Initiates a connection using the socket resource socket, which must be a valid socket resource created with socket_create().
The address parameter is either an IP address in dotted-quad notation (e.g. 127.0.0.1), if the socket is of the AF_INET family; or the pathname of a Unix-domain socket, if the socket family is AF_UNIX.
The port parameter is only used when connecting to an AF_INET socket, and designates the port on the remote host to which a connection should be made.
Retourne TRUE en cas de succès, FALSE en cas d'échec. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.
See also socket_bind(), socket_listen(), socket_create(), socket_last_error() and socket_strerror().
socket_create_listen
Description
resource socket_create_listen ( int port [, int backlog])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
This function is meant to ease the task of creating a new socket which only listens to accept new connections.
socket_create_listen() create a new socket resource of type AF_INET listening on all local interfaces on the given port waiting for new connections.
The backlog parameter defines the maximum length the queue of pending connections may grow to. SOMAXCONN may be passed as backlog parameter, see socket_listen() for more information.
socket_create_listen() returns a new socket resource on success or FALSE on error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.
Note : If you want to create a socket which only listens on a certain interfaces you need to use socket_create(), socket_bind() and socket_listen().
See also socket_create(), socket_bind(), socket_listen(), socket_last_error() and socket_strerror().
socket_create_pair
(PHP 4 >= 4.1.0)
socket_create_pair -- Creates a pair of indistinguishable sockets and stores them in fds.Description
bool socket_create_pair ( int domain, int type, int protocol, array &fd)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_create
Description
resource socket_create ( int domain, int type, int protocol)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
Creates a communication endpoint (a socket), and returns a socket resource.
The domain parameter sets the domain (protocol family) to be used for communication. Currently, AF_INET and AF_UNIX are understood. AF_INET is typical used for internet based communication. AF_UNIX uses pathnames to identify sockets and can therefore only be used for local communication (which is faster, on the other hand).
The type parameter selects the socket type. This is one of SOCK_STREAM, SOCK_DGRAM, SOCK_SEQPACKET, SOCK_RAW, SOCK_RDM, or SOCK_PACKET. The two most common types are SOCK_DGRAM for UDP (connectionless) communication and SOCK_STREAM for TCP communication.
protocol sets the protocol which is either SOL_UDP or SOL_TCP.
Returns a socket resource on success, or FALSE on error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to socket_strerror() to get a textual explanation of the error.
For more information on the usage of socket_create(), as well as on the meanings of the various parameters, see the Unix man page socket (2).
Note : If an invalid domain or type is given, socket_create() defaults to AF_INET and SOCK_STREAM respectively and additionally emits an E_WARNING message.
See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), and socket_strerror().
socket_get_option
Description
mixed socket_get_option ( resource socket, int level, int optname)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
Note : This function used to be called socket_getopt() prior to PHP 4.3.0
socket_getpeername
(PHP 4 >= 4.1.0)
socket_getpeername -- Queries the remote side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type.Description
bool socket_getpeername ( resource socket, string &addr [, int &port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
If the given socket is of type AF_INET, socket_getpeername() will return the peers (remote) IP address in dotted-quad notation (e.g. 127.0.0.1) in the address parameter and, if the optional port parameter is present, also the associated port.
If the given socket is of type AF_UNIX, socket_getpeername() will return the UNIX filesystem path (e.g. /var/run/daemon.sock) in the address parameter.
Retourne TRUE en cas de succès, FALSE en cas d'échec. socket_getpeername() may also return FALSE if the socket type is not any of AF_INET or AF_UNIX, in which case the last socket error code is not updated.
See also socket_getpeername(), socket_last_error() and socket_strerror().
socket_getsockname
(PHP 4 >= 4.1.0)
socket_getsockname -- Queries the local side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type.Description
bool socket_getsockname ( resource socket, string &addr [, int &port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
If the given socket is of type AF_INET, socket_getsockname() will return the local IP address in dotted-quad notation (e.g. 127.0.0.1) in the address parameter and, if the optional port parameter is present, also the associated port.
If the given socket is of type AF_UNIX, socket_getsockname() will return the UNIX filesystem path (e.g. /var/run/daemon.sock) in the address parameter.
Retourne TRUE en cas de succès, FALSE en cas d'échec. socket_getsockname() may also return FALSE if the socket type is not any of AF_INET or AF_UNIX, in which case the last socket error code is not updated.
See also socket_getpeername(), socket_last_error() and socket_strerror().
socket_iovec_add
Description
bool socket_iovec_add ( resource iovec, int iov_len)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_iovec_alloc
(PHP 4 >= 4.1.0)
socket_iovec_alloc -- ...]) Builds a 'struct iovec' for use with sendmsg, recvmsg, writev, and readvDescription
resource socket_iovec_alloc ( int num_vectors [, int ])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_iovec_delete
Description
bool socket_iovec_delete ( resource iovec, int iov_pos)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_iovec_fetch
(PHP 4 >= 4.1.0)
socket_iovec_fetch -- Returns the data held in the iovec specified by iovec_id[iovec_position]Description
string socket_iovec_fetch ( resource iovec, int iovec_position)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_iovec_free
Description
bool socket_iovec_free ( resource iovec)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_iovec_set
Description
bool socket_iovec_set ( resource iovec, int iovec_position, string new_val)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_last_error
Description
int socket_last_error ( [resource socket])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
This function returns a socket error code.
If a socket resource is passed to this function, the last error which occured on this particular socket is returned. If the socket resource is ommited, the error code of the last failed socket function is returned. The latter is in particular helpful for functions like socket_create() which don't return a socket on failure and socket_select() which can fail for reasons not directly tied to a particular socket. The error code is suitable to be fed to socket_strerror() which returns a string describing the given error code.
if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) {
die("Couldn't create socket, error code is: " . socket_last_error() .
",error message is: " . socket_strerror(socket_last_error()));
} |
Note : socket_last_error() does not clear the error code, use socket_clear_error() for this purpose.
socket_listen
Description
bool socket_listen ( resource socket [, int backlog])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
After the socket socket has been created using socket_create() and bound to a name with socket_bind(), it may be told to listen for incoming connections on socket.
A maximum of backlog incoming connections will be queued for processing. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed.
Note : The maximum number passed to the backlog parameter highly depends on the underlying platform. On linux, it is silently truncated to SOMAXCONN. On win32, if passed SOMAXCONN, the underlying service provider responsible for the socket will set the backlog to a maximum reasonable value. There is no standard provision to find out the actual backlog value on this platform.
socket_listen() is applicable only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.
Retourne TRUE en cas de succès, FALSE en cas d'échec. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.
See also socket_accept(), socket_bind(), socket_connect(), socket_create() and socket_strerror().
socket_read
Description
string socket_read ( resource socket, int length [, int type])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function socket_read() reads from the socket resource socket created by the socket_create() or socket_accept() functions. The maximum number of bytes read is specified by the length parameter. Otherwise you can use \r, \n, or \0 to end reading (depending on the type parameter, see below).
socket_read() returns the data as a string on success, or FALSE on error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual representation of the error.
Note : socket_read() may return a zero length string ("") indicating the end of communication (i.e. the remote end point has closed the connection).
Optional type parameter is a named constant:
PHP_BINARY_READ - use the system read() function. Safe for reading binary data. (Default in PHP >= 4.1.0)
PHP_NORMAL_READ - reading stops at \n or \r. (Default in PHP <= 4.0.6)
See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), socket_strerror() and socket_write().
socket_readv
(PHP 4 >= 4.1.0)
socket_readv -- Reads from an fd, using the scatter-gather array defined by iovec_idDescription
bool socket_readv ( resource socket, resource iovec_id)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_recv
Description
string socket_recv ( resource socket, int len, int flags)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_recvfrom
Description
int socket_recvfrom ( resource socket, string &buf, int len, int flags, string &name [, int &port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_recvmsg
(PHP 4 >= 4.1.0)
socket_recvmsg -- Used to receive messages on a socket, whether connection-oriented or notDescription
bool socket_recvmsg ( resource socket, resource iovec, array &control, int &controllen, int &flags, string &addr [, int &port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_select
(PHP 4 >= 4.1.0)
socket_select -- Runs the select() system call on the given arrays of sockets with a timeout specified by tv_sec and tv_usecDescription
int socket_select ( resource &read, resource &write, resource &except, int tv_sec [, int tv_usec])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The socket_select() accepts arrays of sockets and waits for them to change status. Those coming with BSD sockets background will recognize that those socket resource arrays are in fact the so-called file descriptor sets. Three independent arrays of socket resources are watched.
The sockets listed in the read array will be watched to see if characters become available for reading (more precisely, to see if a read will not block - in particular, a socket resource is also ready on end-of-file, in which case a socket_read() will return a zero length string).
The sockets listed in the write array will be watched to see if a write will not block.
The sockets listed in the except array will be watched for exceptions.
| Avertissement |
On exit, the arrays are modified to indicate which socket resource actually changed status. |
You do not need to pass every array to socket_select(). You can leave it out and use an empty array or NULL instead. Also do not forget that those arrays are passed by reference and will be modified after socket_select() returns.
Example:
/* Prepare the read array */
$read = array($socket1, $socket2);
if (false === ($num_changed_sockets = socket_select($read, $write = NULL, $except = NULL, 0))) {
/* Error handling */
else if ($num_changed_sockets > 0) {
/* At least at one of the sockets something interesting happened */
} |
Note : Due a limitation in the current Zend Engine it is not possible to pass a constant modifier like NULL directly as a parameter to a function which expects this parameter to be passed by reference. Instead use a temporary variable or an expression with the leftmost member being a temporary variable:
The tv_sec and tv_usec together form the timeout parameter. The timeout is an upper bound on the amount of time elapsed before socket_select() return. tv_sec may be zero , causing socket_select() to return immediately. This is useful for polling. If tv_sec is NULL (no timeout), socket_select() can block indefinitely.
On success socket_select() returns the number of socket resorces contained in the modified arrays, which may be zero if the timeout expires before anything interesting happens. On error FALSE is returned. The error code can be retrieved with socket_last_error().
Note : Be sure to use the === operator when checking for an error. Since the socket_select() may return 0 the comparison with == would evaluate to TRUE:
if (false === socket_select($r, $w, $e = NULL, 0)) { echo "socket_select() failed, reason: " . socket_strerror(socket_last_error()) . "\n"; }
Note : Be aware that some socket implementations need to be handled very carefully. A few basic rules:
You should always try to use socket_select() without timeout. Your program should have nothing to do if there is no data available. Code that depends on timeouts is not usually portable and difficult to debug.
No socket resource must be added to any set if you do not intend to check its result after the socket_select() call, and respond appropriately. After socket_select() returns, all socket resources in all arrays must be checked. Any socket resource that is available for writing must be written to, and any socket resource available for reading must be read from.
If you read/write to a socket returns in the arrays be aware that they do not necessarily read/write the full amount of data you have requested. Be prepared to even only be able to read/write a single byte.
It's common to most socket implementations that the only exception caught with the except array is out-of-bound data received on a socket.
See also socket_read(), socket_write(), socket_last_error() and socket_strerror().
socket_send
Description
int socket_send ( resource socket, string buf, int len, int flags)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_sendmsg
(PHP 4 >= 4.1.0)
socket_sendmsg -- Sends a message to a socket, regardless of whether it is connection-oriented or notDescription
bool socket_sendmsg ( resource socket, resource iovec, int flags, string addr [, int port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_sendto
Description
int socket_sendto ( resource socket, string buf, int len, int flags, string addr [, int port])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_set_nonblock
Description
bool socket_set_nonblock ( resource socket)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_set_option
Description
bool socket_set_option ( resource socket, int level, int optname, int )| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
Note : This function used to be called socket_setopt() prior to PHP 4.3.0
socket_shutdown
Description
bool socket_shutdown ( resource socket [, int how])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
socket_strerror
Description
string socket_strerror ( int errno)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
socket_strerror() takes as its errno parameter a socket error code as returned by socket_last_error() and returns the corresponding explanatory text. This makes it a bit more pleasant to figure out why something didn't work; for instance, instead of having to track down a system include file to find out what '-111' means, you just pass it to socket_strerror(), and it tells you what happened.
Exemple 1. socket_strerror() example
The expected output from the above example (assuming the script is not run with root privileges):
|
See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), and socket_create().
socket_write
Description
int socket_write ( resource socket, string buffer [, int length])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
The function socket_write() writes to the socket socket from buffer.
The optional parameter length can specify an alternate length of bytes written to the socket. If this length is greater then the buffer length, it is silently truncated to the length of the buffer.
Returns the number of bytes successfully written to the socket or FALSE one error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.
Note : socket_write() does not necessarily write all bytes from the given buffer. It's valid that, depending on the network buffers etc., only a certain amount of data, even one byte, is written though your buffer is greater. You have to watch out so you don't unintentionally forget to transmit the rest of your data.
Note : It is perfectly valid for socket_write() to return zero which means no bytes have been written. Be sure to use the === operator to check for FALSE in case of an error.
See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_read() and socket_strerror().
socket_writev
(PHP 4 >= 4.1.0)
socket_writev -- Writes to a file descriptor, fd, using the scatter-gather array defined by iovec_idDescription
bool socket_writev ( resource socket, resource iovec_id)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
XCVII. Chaîne de caractères
Ces fonctions permettent la manipulation de chaînes de caractères. Certaines sections plus spécialisées sont disponibles dès les sections sur les expressions régulières et dans la section URL.
Pour plus de détails sur le comportement des chaînes de caractères, notamment concernant les guillemets simples ou doubles, et les séquences d'échappement, reportez-vous à chaînes de caractères, dans le chapitre Types.
- Table des matières
- AddCSlashes -- Ajoute des slash dans une chaîne, comme en langage C.
- AddSlashes -- Ajoute un slash devant tous les caractères spéciaux.
- bin2hex -- Convertit une valeur binaire en hexadécimale
- chop -- Enlève les espaces de fin de chaîne.
- chr -- Retourne un caractère.
- chunk_split -- Scinde une chaîne en plus petits morceaux.
- convert_cyr_string -- Convertit la chaîne d'un alphabet cyrillique vers un autre.
- count_chars -- Retourne des informations sur les caractères utilisés dans une chaîne.
- crc32 -- Calcule le polynôme crc32 d'une chaîne
- crypt -- Chiffre une chaîne avec un DES.
- echo -- Affiche une ou plusieurs chaînes.
- explode -- Scinde une chaîne en morceaux, grâce à un délimiteur.
- get_html_translation_table -- Retourne la table de traduction HTML
- get_meta_tags -- Extrait toutes les balises meta d'un fichier
- hebrev -- Convertit un texte hébreux logique en texte visual
- hebrevc -- Convertit un texte hébreux logique en texte visuel avec les nouvelles lignes de conversion.
- htmlentities -- Convertit tous les caractères spéciaux en entité HTML.
- htmlspecialchars -- Convertit tous les caractères spéciaux en entité HTML.
- implode -- Regroupe tous les éléments d'un tableau dans une chaîne, avec une chaîne de jointure.
- join -- Regroupe tous les éléments d'un tableau dans une chaîne, avec une chaîne de jointure.
- levenshtein -- Calcule la distance Levenshtein entre deux chaînes
- localeconv -- Lit le formatage numérique et monétaire
- ltrim -- Enlève les espaces de début de chaîne.
- md5_file -- Calculates the md5 hash of a given filename
- md5 -- Calcule un md5 avec la chaîne.
- metaphone -- Calcule la clé métaphone d'une chaîne de caractères.
- nl_langinfo -- Query language and locale information
- nl2br -- Insère une césure HTML avant chaque nouvelle ligne.
- ord -- Retourne la valeur ASCII du caractère.
- parse_str -- Analyse une chaîne, et en déduit des variables et leur valeur.
- print -- Affiche une chaîne.
- printf -- Affiche une chaîne formatée.
- quoted_printable_decode -- Décode une chaîne
- QuoteMeta -- Ajoute un antislash devant tous les caractères méta
- rtrim -- Efface les espaces de fin de chaîne.
- setlocale -- Change les informations locales.
- similar_text -- Calcule la similarité de deux chaînes.
- soundex -- Calcule la valeur soundex d'une chaîne.
- sprintf -- Retourne une chaîne formatée.
- sscanf -- Analyse une fonction en fonction d'un format
- str_pad -- Complète une chaîne avec une autre
- str_repeat -- Répète une chaîne.
- str_replace -- Remplace toutes les occurrences d'une chaîne par une autre.
- str_rot13 -- Perform the rot13 transform on a string
- strcasecmp -- Compare en binaire des chaînes, insensible à la casse.
- strchr -- Renvoie la chaîne à partir de la première occurrence
- strcmp -- Compare en binaire des chaînes.
- strcoll -- Compare des chaînes localisées
- strcspn -- Recherche la longueur du premier segment de chaîne qui ne corresponde pas au masque donné.
- strip_tags -- Enlève les balises HTML et PHP.
- StripCSlashes -- Déquote une chaîne quotée avec addcslashes()
- StripSlashes -- Enlève les slashs ajoutés par la fonction addslashes()
- stristr -- strstr(), insensible à la casse.
- strlen -- Retourne la longueur de la chaîne.
- strnatcasecmp -- Compare des chaînes par ordre "naturel" insensible à la casse
- strnatcmp -- Compare des chaînes par ordre "naturel"
- strncasecmp -- Compare en binaire des chaînes de caractères
- strncmp -- Compare en binaire les premiers caractères
- strpos -- Recherche la première occurrence d'un caractère dans une chaîne.
- strrchr -- Recherche la partie terminale d'une chaîne après un caractère donné
- strrev -- Inverse l'ordre des caractères d'une chaîne.
- strrpos -- Recherche la dernière occurrence d'un caractère dans une chaîne.
- strspn -- Retourne la longueur du premier segment qui vérifie le masque.
- strstr -- Renvoie la chaîne à partir de la première occurrence
- strtok -- Morcelle une chaîne
- strtolower -- Met tous les caractères en minuscules.
- strtoupper -- Met tous les caractères en majuscules.
- strtr -- Remplace toutes les occurrences d'un caractère par un autre.
- substr_count -- Compte le nombre de sous-chaînes
- substr_replace -- Remplace dans une sous partie de chaîne
- substr -- Retourne une partie de la chaîne.
- trim -- Enlève les espaces de début et de fin de chaîne
- ucfirst -- Force le premier caractère d'une chaîne en majuscule.
- ucwords -- Force le premier caractère de chaque mot d'une chaîne en majuscule
- vprintf -- Output a formatted string
- vsprintf -- Return a formatted string
- wordwrap -- Ajoute une césure à une chaîne tous les n caractères
AddCSlashes
Description
string addcslashes ( string str, string charlist)addcslashes() retourne une chaîne avec des antislash devant les caractères qui sont dans la liste charlist. Les caractères \n, \r etc... sont échappés. En langage C, les caractères avec un code ASCII inférieur à 32 ou supérieur à 126 sont convertis en représentation octale. Faites bien attention lorsque vous échappez des caractères alpha-numériques. Vous pouvez spécifier un intervalle dans charlist comme "\0..\37", qui échappera les caractères compris dans cet intervalle.
Note : addcslashes() a été ajouté en PHP 4.0b3-dev.
Voir aussi stripcslashes(), stripslashes(), htmlspecialchars() et quotemeta().
AddSlashes
Description
string addslashes ( string str)addslashes() retourne une chaîne avec des antislash devant chaque caractère qui a en a besoin pour être inséré dans une requête de base de données. Ces caractères sont guillemets simples ('), guillemets doubles ("), antislash (\) et NULL (la valeur nulle).
Voir aussi stripslashes(), htmlspecialchars() et quotemeta().
bin2hex
Description
string bin2hex ( string str)bin2hex() retourne une chaîne ASCII contenant la représentation hexadécimale de str. La conversion est faite avec le bit de poids fort en premier.
chop
Description
string chop ( string str)chop() retourne l'argument sans les espaces de fin de chaîne.
Note : chop() diffère de sa cousine Perl chop(), qui supprime le dernier caractère de la chaîne.
chr
Description
string chr ( int ascii)chr() retourne le caractère de code ASCII ascii.
Voir aussi sprintf() avec le format de chaîne %c.
chunk_split
Description
string chunk_split ( string string [, int chunklen [, string end]])chunk_split() permet de scinder une chaîne en plus petit morceaux, comme dans le cas de la conversion en base64_encode pour se conformer à la RFC 2045. chunk_split() insère une fin de chaîne end (par défaut "\r\n"), tous les chunklen (par défaut 76) caractères. La chaîne retournée est une nouvelle chaîne, et l'original n'est pas modifié.
Note : chunk_split() a été ajoutée en 3.0.6.
convert_cyr_string
(PHP 3>= 3.0.6, PHP 4 )
convert_cyr_string -- Convertit la chaîne d'un alphabet cyrillique vers un autre.Description
string convert_cyr_string ( string str, string from, string to)convert_cyr_string() convertit la chaîne donnée depuis un alphabet cyrillique vers un autre. Les arguments from et to sont des caractères qui représentent la source et la destination. Les valeurs acceptées :
k - koi8-r
w - windows-1251
i - iso8859-5
a - x-cp866
d - x-cp866
m - x-mac-cyrillic
count_chars
Description
mixed count_chars ( string string [, int mode])count_chars() compte le nombre d'occurrences de chaque octet (0..255) dans la chaîne string et le retourne de différentes façons. L'option mode prend, par défaut, la valeur 0. Suivant le mode, count_chars() retourne une des réponses suivantes :
0 - Un tableau avec l'octet comme clé, et la fréquence comme valeur.
1 - Identique à 0, mais seules les fréquences non nulles sont listées.
2 - Identique à 0, mais seules les fréquences nulles sont listées.
3 - Une chaîne qui contient tous les octets utilisés.
4 - Une chaîne contenant tous les octets non utilisés.
Note : count_chars() a été ajoutée en PHP 4.0.
crc32
Description
int crc32 ( string str)crc32() génère la somme de vérification de redondances cycliques (32 bits) de la chaîne str. Cette valeur sert généralement à vérifier l'intégrité de données transmises.
Voir aussi md5().
crypt
Description
string crypt ( string str [, string salt])crypt() va coder une chaîne en utilisant la méthode de chiffrage du DES standard. Les arguments sont : la chaîne à chiffrer, et un grain de sel qui servira de base pour le chiffrement. Reportez-vous au manuel Unix pour plus de détails.
Si le grain de sel n'est pas fourni, il sera automatiquement généré par PHP.
Certains systèmes d'exploitation acceptent plus d'un type de chiffrement. En fait, le DES standard est parfois remplacé par un chiffrement MD5. Le type de chiffrement est alors choisi en fonction du grain de sel. A l'installation, PHP détermine les possibilités de cryptage et décidera d'accepter d'autres grains de sel pour d'autres types de chiffrement. Si le grain de sel n'est pas fourni, PHP génèrera alors un grain de 2 caractères, pour le DES standard, à moins que le système ne dispose de MD5 : dans ce cas, PHP génèrera un grain de sel pour MD, par défaut. PHP affecte la variable d'environnement CRYPT_SALT_LENGTH, à 2 s'il utilise le DES standard, et à 12 s'il utilise le MD5.
Si vous utilisez le grain de sel fourni, retenez bien que ce grain de sel est généré une seule fois. Si vous appelez crypt() récursivement, cela aura un impact sur l'apparence et finalement la sécurité de votre cryptage.
Le chiffrement standard fournit le grain de sel dans les deux premiers octets du résultat de la fonction crypt().
Sur les systèmes qui supportent plusieurs méthodes de chiffrement, les variables d'environnement suivantes sont mises à 0 ou à 1, en fonction de la disponibilité de la méthode :
CRYPT_STD_DES - DES Standard avec 2-octets de SALT
CRYPT_EXT_DES - DES étendu avec 9-octets SALT
CRYPT_MD5 - MD5 avec 12-octets SALT commençant à $1$
CRYPT_BLOWFISH - DES étendu avec 16-octets SALT commençant à $2$
Il n'y a pas d'algorithme de décryptage, étant donné que crypt() est injective.
echo
Description
echo ( string arg1 [, string argn...])echo() affiche tous les paramètres.
echo() n'est pas une fonction à proprement parler, ce qui rend l'usage des parenthèses facultatifs. En fait, si vous voulez passer plus d'un paramètre, vous ne devez pas utiliser les parenthèses.
Exemple 1. Exemple avec echo()
|
explode
Description
array explode ( string separator, string string [, int limit])explode() retourne un tableau qui contient les éléments de la chaîne string, séparés par separator. Si limit est fourni, le tableau retourné contiendra un maximum de limit éléments, et le dernier éléments contiendra le reste de la chaîne string. Si une chaîne vide est utilisée comme separator, alors explode() retournera FALSE. So separator contient une valeur qui n'est pas dans string, Alors explode() retournera la chaîne string.
Note : Le paramètre limit a été ajouté en PHP 4.0.1.
Note : Bien que implode() accepte, pour des raisons historiques, les arguments dans un sens ou l'autre, explode(), lui, ne le peut pas. Vous devez vous assurer que l'argument séparateur separator arrive avant l'argument de chaîne.
Voir aussi preg_split(), spliti(), split() et implode().
get_html_translation_table
Description
string get_html_translation_table ( int table [, int quote_style])get_html_translation_table() retourne la table de traduction utilisée en interne par htmlspecialchars() et htmlentities(). Il y a deux nouvelles définitions : (html_entities, html_specialchars) qui vous permettent de spécifier vos propres tables.
array_flip() est alors très efficace pour inverser la direction de traduction :
Le contenu de $original sera : "Hallo & <Frau> & Krämer".Note : get_html_translation_table() a été ajoutée en PHP 4.0.
Voir aussi htmlspecialchars(), htmlentities(), strtr() et array_flip().
get_meta_tags
Description
array get_meta_tags ( string filename [, int use_include_path])get_meta_tags() ouvre le fichier filename et l'analyse ligne par ligne, en recherchant les balises <meta>.
Le nom d'une propriété devient sa clé, et la valeur devient la valeur dans le tableau associatif retourné, ce qui rend aisé la manipulation des informations. Les caractères spéciaux dans le nom de la propriété sont remplacés par des '_', le reste est converti en minuscules.
Mettre use_include_path à 1 forcera PHP à ouvrir les fichiers dans le chemin standard d'inclusion.
hebrev
Description
string hebrev ( string hebrew_text [, int max_chars_per_line])Le paramètre optionnel max_chars_per_line indique le nombre maximum de caractères par ligne qui seront générés. La fonction essaie d'éviter les césures de mots.
Voir aussi hebrevc()
hebrevc
(PHP 3, PHP 4 )
hebrevc -- Convertit un texte hébreux logique en texte visuel avec les nouvelles lignes de conversion.Description
string hebrevc ( string hebrew_text [, int max_chars_per_line])hebrevc() est similaire à hebrev(), au détail près qu'elle convertit les nouvelles lignes (\n) en "<br>\n". Le paramètre optionnel max_chars_per_line indique le nombre maximum de caractères par ligne qui seront générés. La fonction essaie d'éviter les césures de mots.
Voir aussi hebrev()
htmlentities
Description
string htmlentities ( string string [, int quote_style])htmlentities() est identique à htmlspecialchars() en tous points, sauf que tous les caractères qui ont une entité équivalente en HTML sont remplacés par ces entités. Comme htmlspecialchars(), elle prend un argument optionnel qui indique ce qui doit être fait avec les guillemets simples et doubles. ENT_COMPAT (par défaut) convertira les guillemets doubles, et ignorera les guillemets simples. ENT_QUOTES convertira les deux types de guillemets et ENT_NOQUOTES les ignorera tous les deux.
Actuellement, le jeu de caractères ISO-8859-1 est utilisé. Notez que l'argument optionnel a été ajouté PHP 3.0.17 et PHP 4.0.3.
Voir aussi htmlspecialchars() et nl2br().
htmlspecialchars
Description
string htmlspecialchars ( string string [, int quote_style])Certains caractères ont une valeur avec HTML, et doivent être remplacés par des balises HTML pour conserver leur valeur. htmlspecialchars() retourne une chaîne dont tous les caractères sensibles ont été remplacés par leur équivalent.
htmlspecialchars() est utile pour empêcher un utilisateur de fournir un texte avec un sens HTML, comme dans un livre d'or.
htmlspecialchars() est pratique pour éviter que les textes fournis par les utilisateurs contiennent des balises HTML, comme dans le cas d'un livre d'or ou d'une tribune. htmlspecialchars() prend un argument optionnel qui indique ce qui doit être fait avec les guillemets simples et doubles. ENT_COMPAT (par défaut) convertira les guillemets doubles, et ignorera les guillemets simples. ENT_QUOTES convertira les deux types de guillemets et ENT_NOQUOTES les ignorera tous les deux.
Actuellement, PHP remplace les valeurs suivantes :
'&' (et commercial) devient '&'
'"' (guillemet double) devient '"' si ENT_NOQUOTES n'est pas actif
''' (guillemet simple) devient ''' si ENT_QUOTES est actif
'<' (inférieur à) devient '<'
'>' (supérieur à) devient '>'
Notez bien que htmlspecialchars() ne fait aucun autre remplacement que ceux listés ci-dessus. Pour une traduction complète de toutes les balises, reportez-vous à htmlentities(). Notez que l'argument optionnel a été ajouté PHP 3.0.17 et PHP 4.0.3.
Voir aussi htmlentities() et nl2br().
implode
(PHP 3, PHP 4 )
implode -- Regroupe tous les éléments d'un tableau dans une chaîne, avec une chaîne de jointure.Description
string implode ( string glue, array pieces)implode() retourne une chaîne constituée de tous les éléments du tableau, pris dans l'ordre, transformés en chaîne, et séparés par glue.
Note : Pour des raisons historiques, implode() accepte ces arguments dans l'un ou l'autre sens. Par cohérence avec la fonction explode(), il est plus clair d'utiliser l'ordre des arguments tel que documenté.
join
(PHP 3, PHP 4 )
join -- Regroupe tous les éléments d'un tableau dans une chaîne, avec une chaîne de jointure.Description
string join ( string glue, array pieces)join() est un alias de implode(), et lui est identique en tous points.
levenshtein
Description
int levenshtein ( string str1, string str2)int levenshtein ( string str1, string str2, int cost_ins, int cost_rep, int cost_del)
int levenshtein ( string str1, string str2, function cost)
levenshtein() retourne la distance Levenshtein entre les deux chaînes str1 et str1 ou -1 si un des arguments excède la limite de 255 caractères.
La distance Levenshtein est définie comme le nombre minimal de caractères qu'il faut remplacer, insérer ou effacer pour transformer la chaîne str1 en str2. La complexité de l'algorithme est en O(m*n), où n et m sont les longueurs respectives de str1 et str2 (ceci est plutôt un bon résultat, comparé à similar_text(), qui est en O(max(n,m)**3), mais cela reste coÛteux en terme de ressources).
Dans sa forme la plus simple, la fonction va prendre uniquement deux chaînes en paramètres, et calculer uniquement le nombre d'insertions, remplacements et effacements nécessaires pour transformer la chaîne str1 en str2.
Une variante prend trois paramètres additionnels, qui définissent le coÛt des insertions, des remplacements et des effacement. C'est une version plus générale et plus souple que la version simple, mais qui n'est pas aussi efficace.
La deuxième variante n'est pas encore implémentée. Elle est encore plus générale, et plus souple, mais plus lente. Elle appellera une fonction utilisateur qui déterminera le coÛt de chaque opération.
La fonction utilisateur sera appelée avec les arguments suivants :
opération a appliquer : 'I', 'R' or 'D'
caractère courant de la chaîne str1
caractère courant de la chaîne str2
position courante de la chaîne str1
position courante de la chaîne str2
caractères restants dans la chaîne str1
caractères restants dans la chaîne str2
L'utilisation d'une fonction utilisateur permet de prendre en compte la différence entre certains caractères, ou leur contexte pour déterminer le coÛt d'une opération d'insertion, remplacement ou effacement. Elle accroît la charge de calcul demandée au CPU, et annule l'optimisation des autres variantes.
Voir aussi soundex(), similar_text() et metaphone().
localeconv
Description
array localeconv ( void)localeconv() retourne un tableau associatif contenant les informations locales de formats monétaire et numérique utilisés par le serveur.
localeconv() retourne les informations à partir des données locales, comme définies par setlocale(). Le tableau associatif retourné contient les entrées suivantes :
| Index | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| decimal_point | Séparateur décimal | ||||||||||
| thousands_sep | Séparateur de milliers | ||||||||||
| grouping | Tableau contenant les groupages numériques | ||||||||||
| int_curr_symbol | Symbole monétaire international (i.e. FRF) | ||||||||||
| currency_symbol | Symbole monétaire local (i.e. F) | ||||||||||
| mon_decimal_point | Séparateur décimal monétaire | ||||||||||
| mon_thousands_sep | Séparateur de milliers monétaires | ||||||||||
| mon_grouping | Tableau contenant les groupages numériques monétaires | ||||||||||
| positive_sign | Signe des valeurs positives | ||||||||||
| negative_sign | Signe des valeurs négatives | ||||||||||
| int_frac_digits | Nombre de chiffres décimaux international | ||||||||||
| frac_digits | Nombre de chiffres décimaux locaux | ||||||||||
| p_cs_precedes | TRUE si currency_symbol précède une valeur positive, FALSE s'il lui succède | ||||||||||
| p_sep_by_space | TRUE si un espace sépare currency_symbol d'une valeur positive, FALSE sinon | ||||||||||
| n_cs_precedes | TRUE si currency_symbol précède une valeur négative, FALSE s'il lui succède | ||||||||||
| n_sep_by_space | TRUE si un espace sépare currency_symbol d'une valeur négative, FALSE sinon | ||||||||||
| p_sign_posn |
| ||||||||||
| n_sign_posn |
|
Le champs de groupage contient un tableau qui définit comment les chiffres doivent être regroupés. Par exemple, ce champs pour le dollar américain contient un tableau de deux éléments (3 et 3). Les éléments sont classés de gauche à droite. Si un des éléments vaut CHAR_MAX, les groupages ne sont plus effectués. Si un éléments vaut 0, la valeur du précédent doit être utilisée.
Exemple 1. Exemple avec localeconv()
|
La constante CHAR_MAX est aussi définie ci-dessus.
Note : Ajouté en PHP 4.0.5
Voir aussi setlocale().
ltrim
Description
string ltrim ( string str)ltrim() enlève les caractères blancs placés au début d'une chaîne et retourne la chaîne raccourcie. Les caractères blancs sont : "\n", "\r", "\t", "\v", "\0", et " ".
md5_file
Description
string md5_file ( string filename)Calculates the MD5 hash of the specified filename using the RSA Data Security, Inc. MD5 Message-Digest Algorithm, and returns that hash.
This function has the same purpose of the command line utility md5sum.
md5
Description
string md5 ( string str)Crypte la chaîne str en utilisant la méthode MD5 (voir RSA Data Security, Inc. MD5 Message-Digest Algorithm.).
metaphone
Description
string metaphone ( string str)metaphone() calcule la clé métaphone de la chaîne str.
Similairement à soundex(), métaphone crée une clé similaire pour des sons proches. C'est une fonction plus précise que soundex() car elle prend en compte les règles basiques de la prononciation en anglais. Les clés métaphones sont de longueur variable.
Le métaphone a été développée par Lawrence Philips <lphilips@verity.com>. Elle est décrite dans ["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995].
Note : Cmetaphone() a été ajoutée en PHP 4.0.
nl_langinfo
Description
string nl_langinfo ( int item)
| Avertissement |
This function is currently not documented, only the argument list is available. |
nl2br
Description
string nl2br ( string string)nl2br() retourne la chaîne string dont toutes les lignes ont été remplaçées par '<BR />'.
A partir de la version PHP 4.0.5, nl2br() est désormais compatible XHTML. Toutes les versions antérieures retourneront la chaîne string avec '<br>' remplaçant les nouvelles lignes, au lieu de '<br />'.
Voir aussi htmlspecialchars() et htmlentities().
ord
Description
int ord ( string string)ord() retourne la valeur ASCII du premier caractère de la chaîne string. ord() est le contraire de chr().
Voir aussi chr().
parse_str
Description
void parse_str ( string str [, array arr])Analyse la chaîne str comme si c'était une chaîne passée par URL, et affecte les variables qu'elle y trouve.
printf
Description
int printf ( string format [, mixed args])printf() affiche les arguments en fonction du format. Ce format est décrit en détails dans la documentation de sprintf().
Voir aussi print(), sprintf(), sscanf(), fscanf() et flush().
quoted_printable_decode
Description
string quoted_printable_decode ( string str)quoted_printable_decode() retourne une chaîne 8-bit résultant du décodage de la chaîne str. quoted_printable_decode() est similaire à imap_qprint(), hormis le fait qu'elle ne requiert pas le module IMAP.
QuoteMeta
Description
string quotemeta ( string str)quotemeta() retourne une version de la chaîne str, avec un antislash (\) devant tous les caractères de la liste ci-dessous :
. \ + * ? [ ^ ] ( $ ) |
Voir aussi addslashes(), htmlentities(), htmlspecialchars(), nl2br() et stripslashes().
rtrim
Description
string rtrim ( string str)rtrim() la chaîne str, débarassée de ses espaces terminaux, y compris les nouvelles lignes. rtrim() est un alias de chop().
setlocale
Description
string setlocale ( mixed category, string locale)category est une chaîne ou une constante qui spécifie la catégorie de fonctions qui va être affectée par les informations locales :
LC_ALL : toutes les fonctions ci-dessous
LC_COLLATE : pour les comparaisons de chaînes (voir strcoll())
LC_CTYPE : pour la classification de caractères et les conversions, par exemple strtoupper()
LC_MONETARY : pour localeconv() - (en cours d'implémentation)
LC_NUMERIC : pour les séparateurs décimaux
LC_TIME : pour le format des dates et heures date avec strftime()
Si locale est une chaîne vide (""), les noms locaux prendront la valeur des variables d'environnement de même nom, ou à partir de "LANG".
Si locale vaut zéro ou "0", la valeur reste inchangée, mais l'état courant est retourné.
setlocale() retourne la valeur courante, ou FALSE si la fonctionnalité n'est pas encore implémentée pour la plate-forme. Une catégorie invalide provoque une alerte.
similar_text
Description
int similar_text ( string first, string second [, double percent])similar_text() calcule la similarité entre deux chaînes, comme décrit par Oliver [1993]. Notez que cette implémentation n'utilise pas une pile, comme dans le pseudo-code d'Oliver, mais un appel récursif qui accélère parfois l'exécution. Notez aussi que la complexité de cet algorithme est en o(N**3) avec N la taille de la plus grande chaîne.
En passant une référence comme troisième argument, similar_text() va calculer le pourcentage de similarité. Il retourne le nombre de caractères correspondant l'un à l'autre, d'une chaîne à l'autre.
soundex
Description
string soundex ( string str)soundex() calcule la valeur soundex de str.
Une valeur Soundex est telle que deux mots prononcés de la même façon auront des valeurs Soundex identiques. Cela permet d'effectuer des recherches dans les bases de données, si vous connaissez la prononciation mais pas l'orthographe. soundex() retourne une chaîne de 4 caractères, commençant par une lettre.
soundex() particulière a été décrite par Donald Knuth dans "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392.
Attention : le soundex dépend de la langue, et le soundex PHP est optimisé pour l'anglais. Des versions françaises existent sous forme de script.
sprintf
Description
string sprintf ( string format [, mixed args])sprintf() retourne une chaîne, construite à partir des arguments args, et formatée avec format.
La chaîne de format est composée de 0 ou plus directives : généralement des caractères qui sont recopiés tels quels (hormis %), et des spécifications, chacune d'elle disposant de son propre paramètre. Cela s'applique à sprintf() et printf().
Chaque conversion consiste en un signe pourcentage (%), suivi d'un ou plusieurs éléments parmi ceux-ci :
Une option de remplissage, qui indique quel caractère sera utilisé pour le remplissage, et la taille finale de la chaîne. Le caractère de remplissage peut être un espace ou le caractère zéro (0).). La valeur par défaut est l'espace. Une autre valeur peut être spécifiée en la préfixant par un guillemet simple ('). Voir les exemples plus loin.
Un argument optionnel alignment spécifier qui indique que le résultat doit être justifié à droite ou à droite. Par défaut, il est justifié à gauche. Le caractère - signifie : justification à gauche.
Argument optionnel, width spécifier indique le nombre minimum de caractères que la conversion devrait retourner.
Argument optionnel, precision spécifier indique le nombre de chiffres utilisé pour afficher un nombre à virgule flottante. Cette option n'a d'effet que sur les nombres à virgule de type double (Une autre fonction pratique pour formater les nombres est : number_format()).
type specifier indique le type de données passées en argument. Les types possibles sont :
% - un signe pourcentage : aucun argument nécessaire. b - l'argument est traité comme un entier, et représenté comme un nombre binaire. c - l'argument est traité comme un entier, et représenté comme un nombre ascii. d - l'argument est traité comme un entier, et représenté comme un nombre décimal. u - l'argument est traité comme un entier, et représenté comme un nombre décimal non signé. f - l'argument est traité comme un double, et représenté comme un nombre à virgule flottante. o - l'argument est traité comme un entier, et représenté comme un nombre octal. s - l'argument est traité tel quel, et représenté comme une chaîne. x - l'argument est traité comme un entier, et représenté comme un nombre hexadécimal (en minuscules). X - l'argument est traité comme un entier, et représenté comme un nombre hexadécimal (en majuscules).
A partir de PHP 4.0.6, le paramètre format supportera aussi la numérotation des arguments, et leur échange. Par exemple :
Voir aussi printf(), sscanf(), fscanf() et number_format().
sscanf
Description
mixed sscanf ( string str, string format [, string var1])sscanf() est le complémentaire de printf(). sscanf() lit les données de la chaîne str et interprète son contenu en fonction du format format. Si seulement deux paramètres sont passés à sscanf(), les valeurs obtenues seront retournées sous forme d'un tableau.
Exemple 1. Exemple avec sscanf()
|
Exemple 2. Utilisation des options avec sscanf()
|
str_pad
Description
string str_pad ( string input, int pad_length [, string pad_string [, int pad_type]])str_pad() complète la chaîne input à droite, à gauche ou dans les deux directions, avec pad_string jusqu'à la taille de pad_length. Si pad_string n'est pas fourni, input est complété avec des espaces. Sinon, il est complété avec pad_string.
pad_type peut prendre les valeurs de STR_PAD_RIGHT, STR_PAD_LEFT, ou STR_PAD_BOTH. Si pad_type n'est pas spécifiée, cela vaut STR_PAD_RIGHT.
Si pad_length est négative ou inférieure à la taille courante de la chaîne input, aucun complément n'est ajouté.
str_repeat
Description
string str_repeat ( string input, int multiplier)str_repeat() retourne input_str répétée multiplier fois. multiplier doit être supérieur à 0.
Cet exemple affichera "-=-=-=-=-=-=-=-=-=-=".
Note : str_repeat() a été ajoutée en PHP 4.0.
str_replace
Description
mixed str_replace ( mixed search, mixed replace, mixed subject)str_replace() remplace toutes les occurrences de search dans subject par la chaîne replace. Si vous n'avez pas besoin de règles de remplacement sophistiquées, utilisez str_replace() de préférence à ereg_replace() et preg_replace().
En PHP 4.0.5 et plus récent, chaque paramètre de str_replace() peut être un tableau.
Si subject est un tableau, alors le remplacement est effectué pour chaque valeur de subject, et la valeur retournée sera un tableau.
Si search et replace sont des tableaux, alors str_replace() prend une valeur dans chaque tableau, et s'en sert pour chercher et remplacer dans subject. Si replace contient moins de valeurs que search, des chaînes vides seront utilisées pour compléter le tableau replace. Si search est un tableau et replace est une chaîne, alors la même chaîne de remplacement sera utilisée pour chaque valeur de search. Le contraire n'aurait pas beaucoup de sens.
str_replace() n'altère pas les données binaires.
Note : str_replace() a été ajoutée en PHP 3.0.6, mais était erronée jusqu'à PHP 3.0.8.
Voir aussi ereg_replace(), preg_replace() et strtr().
str_rot13
Description
string str_rot13 ( string str)This function performs the ROT13 encoding on the str argument and returns the resulting string. The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched. Encoding and decoding are done by the same function, passing an encoded string as argument will return the original version.
strcasecmp
Description
int strcasecmp ( string str1, string str2)strcasecmp() retourne < 0 si str1 est plus petit que str2; > 0 si str1 est plus grand que str2, et 0 s'ils sont égaux.
Voir aussi ereg(), strcmp(), substr(), stristr(), strncasecmp() et strstr().
strchr
Description
string strchr ( string haystack, string needle)strchr() est un alias de strstr(), et lui est identique en tous points.
strcmp
Description
int strcmp ( string str1, string str2)strcmp() retourne < 0 si str1 est plus petit que str2; > 0 si str1 est plus grand que str2, et 0 s'ils sont égaux.
Notez bien que la comparaison est sensible à la casse.
Voir aussi ereg(), strcasecmp(), substr(), stristr(), strncmp(), strncasecmp() et strstr().
strcoll
Description
int strcoll ( string str1, string str2)strcoll() retourne < 0 si str1 est plus petit que str2; > 0 si str1 est plus grand que str2, et 0 si elles sont égales. strcoll() utilise la configuration locale pour effectuer les comparaisons. Si la configuration locale est : C ou POSIX, strcoll() est équivalente à strcmp().
Notez que cette comparaison est sensible à la casse, et que contrairement à strcmp(), strcoll() n'est pas binaire.
Note : Ajoutée en PHP 4.0.5.
Voir aussi ereg(), strcmp(), strcasecmp(), substr(), stristr(), strncasecmp(), strncmp(), strstr() et setlocale().
strcspn
(PHP 3>= 3.0.3, PHP 4 )
strcspn -- Recherche la longueur du premier segment de chaîne qui ne corresponde pas au masque donné.Description
int strcspn ( string str1, string str2)strcspn() retourne la longueur du premier segment de la chaîne str1 qui ne contiennent aucun des caractères de la chaîne str2.
Voir aussi strspn().
strip_tags
Description
string strip_tags ( string str [, string allowable_tags])strip_tags() recherche et supprime toutes les balises HTML et PHP d'une chaîne. En cas de balises non fermées, ou de balises mal formées, elle génère une erreur. strip_tags() utilise le même système que la fonction fgetss().
Vous pouvez utiliser l'option allowable_tags pour spéficier les balises qui seront ignorées.
Note : allowable_tags a été ajouté en PHP 3.0.13, et PHP 4.0B3.
StripCSlashes
Description
string stripcslashes ( string str)stripcslashes() retourne une chaîne dont les anti-slash ont été supprimés. stripcslashes() reconnaît les \n, \r..., et les représentations octales et hexadécimales utilisées en C.
Note : stripcslashes() a été ajouté en PHP 4.0b3-dev.
Voir aussi addcslashes().
StripSlashes
Description
string stripslashes ( string str)stripslashes() retourne une chaîne dont tous les slashs ont été supprimés. (\' devient ') et ainsi de suite). Les doubles antislash sont remplacés par des simples antislash.
Voir aussi addslashes().
stristr
Description
string stristr ( string haystack, string needle)stristr() retourne tous les éléments de haystack à partir de la première occurrence de needle, jusqu'à la fin. needle et haystack sont examinés sans tenir compte de la casse.
Si needle n'est pas trouvé, retourne FALSE.
Si needle n'est pas une chaîne, elle est convertie en entier, puis est utilisée comme si elle était passée à chr().
strlen
Description
int strlen ( string str)strlen() retourne la longueur de la chaîne string, c'est-à-dire le nombre de caractères.
strnatcasecmp
Description
int strnatcasecmp ( string str1, string str2)strnatcasecmp() implémente un algorithme de comparaison qui traite les chaînes alpha-numériques comme un être humain : c'est ce qui est appelé l'"ordre naturel". Pour plus d'informations, reportez-vous à Martin Pool Natural Order String Comparison.
Comme les autres fonctions de comparaisons de chaînes, elle retourne une valeur < 0 si str1 est plus petite que str2; > 0 si str1 est plus grande que str2, et 0 si elles sont égales.
Voir aussi ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncmp(), strnatcmp(), strncasecmp() et strstr().
strnatcmp
Description
int strnatcmp ( string str1, string str2)strnatcmp() implémente un algorithme de comparaison qui traite les chaînes alpha-numériques comme un être humain : c'est ce qui est appelé l'"ordre naturel". Un exemple de la différence de traitement entre un tel algorithme et un algorithme de comparaison de chaînes (comme lorsqu'on utilise strcmp()) est illustré ci-dessous :
<?php
$arr1 = $arr2 = array("img12.png","img10.png","img2.png","img1.png");
echo "Comparaison standard de chaînes\n";
usort($arr1,"strcmp");
print_r($arr1);
echo "\nComparaison de chaînes par ordre naturel\n";
usort($arr2,"strnatcmp");
print_r($arr2);
?> |
Comparaison standard de chaînes
Array
(
[0] => img1.png
[1] => img10.png
[2] => img12.png
[3] => img2.png
)
Comparaison de chaînes par ordre naturel
Array
(
[0] => img1.png
[1] => img2.png
[2] => img10.png
[3] => img12.png
)
Comme les autres fonctions de comparaison de chaînes, elle retourne une valeur < 0 si str1 est plus petite que str2; > 0 si str1 est plus grande que str2, et 0 si elles sont égales.
Notez que ces comparaisons sont sensibles à la casse.
Voir aussi ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncmp(), strnatcasecmp(), strstr(), natsort(), strncasecmp() et natcasesort().
strncasecmp
Description
int strncasecmp ( string str1, string str2, int len)strncasecmp() est similaire à strcasecmp(), à la différence près qu'elle permet de limiter le nombre de caractères utilisés pour comparer str1 et str1, avec le paramètre len. Si une des chaînes est plus courte que len, alors la longueur de cette chaîne sera utilisée pour effectuer la comparaison.
strncasecmp() retourne < 0 si str1 est plus petit que str2; > 0 si str1 est plus grand que str2, et 0 si elles sont égales.
Voir aussi ereg(), strcasecmp(), strcmp(), substr(), stristr() et strstr().
strncmp
Description
int strncmp ( string str1, string str2, int len)strncmp() est similaire à strcmp(), à la différence près que vous pouvez spécifier le nombre limite de caractères (len) utilisés pour faire la comparaison. Si l'une des chaînes est plus courte que len, alors cette longueur sera utilisée pour faire la comparaison.
Comme les autres fonctions de comparaisons de chaînes, elle retourne une valeur < 0 si str1 est plus petite que str2; > 0 si str1 est plus grande que str2, et 0 si elles sont égales.
Notez que la comparaison est sensible à la casse.
Voir aussi ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncasecmp() et strstr().
strpos
Description
int strpos ( string haystack, string needle [, int offset])strpos() retourne la position numérique de la première occurrence de needle dans la chaîne haystack. Contrairement à strrpos(), needle peut être une chaîne.
Si needle n'est pas trouvée, retourne FALSE.
Note : Il est facile de confondre la valeur de retour "caractère trouvé à la position 0" et "caractère introuvable". Voici comment faire la différence :
Si needle n'est pas une chaîne, elle est convertie en entier, et utilisée comme la valeur ASCII d'un caractère.
L'argument optionnel offset permet de préciser le caractère à partir duquel chercher, dans haystack. La position doit être relative au début de la chaîne haystack.
Voir aussi strrpos(), strrchr(), strchr(), substr(), stristr() et strstr().
strrchr
Description
string strrchr ( string haystack, string needle)strrchr() retourne la partie de la chaîne haystack qui commence à la dernière occurrence de needle et va jusqu'à la fin de la chaîne haystack.
strrchr() retourne FALSE si needle n'est pas trouvé.
Si needle contient plus d'un caractère, les autres sont ignorés.
Si needle n'est pas une chaîne, il est converti en un entier, et utilisé comme valeur ordinale.
strrev
Description
string strrev ( string string)strrev() retourne string, après avoir changé l'ordre des caractères.
strrpos
Description
int strrpos ( string haystack, char needle)strrpos() retourne la position numérique de la dernière occurrence de needle dans la chaîne haystack. strrpos() ne peut accepter qu'un seul caractère.
Si needle n'est pas trouvé, retourne FALSE.
Note : Il est facile de confondre la valeur de retour "caractère trouvé à la position 0" et "caractère introuvable". Voici comment faire la différence :
Si needle n'est pas une chaîne, elle est convertie en entier, et utilisée comme la valeur ASCII d'un caractère.
Voir aussi strpos(), strrchr(), substr(), stristr() et strstr().
strspn
Description
int strspn ( string str1, string str2)strspn() retourne la longueur du premier segment de str1 qui est constitué entièrement de caractères dans la chaîne str2.
<?php
strspn("42 est une réponse, quelle est la question...", "1234567890");
?> |
Cet exemple affichera "2", car "42" est la plus longue chaîne contenant des chiffres dans la chaîne de questions.
Voir aussi strcspn().
strstr
Description
string strstr ( string haystack, string needle)strstr() retourne toute la chaîne haystack à partir de la première occurrence de needle, jusqu'à la fin.
Si needle n'est pas trouvé, retourne FALSE.
Note : strstr() est sensible à la casse. Si besoin est, utilisez stristr().
Si needle n'est pas une chaîne, elle est convertie en entier, et utilisée comme valeur ordinale d'un caractère.
strtok
Description
string strtok ( string arg1, string arg2)strtok() est utilisée pour morceler une chaîne. Pour cela, si vous avez une chaîne du type "ceci est une chaîne exemple", vous pouvez la morceler en mots, en utilisant ' ' comme délimiteur.
Notez que seul, le premier appel à strtok() utilise l'argument chaîne. Après, chaque appel à strtok ne requiert que le délimiteur à utiliser. Pour recommencer, vous pouvez simplement appeler strtok() avec un nouvel argument, pour l'initialiser. Notez que vous pouvez mettre des délimiteurs multiples. La chaîne sera morcelée à chaque fois qu'on rencontrera un des délimiteurs.
Soyez prudents avec les délimiteurs qui sont égaux à "0". Cette valeur sera confondue avec FALSE.
strtolower
Description
string strtolower ( string str)strtolower() retourne string avec tous les caractères alphabétiques en minuscule.
Notez que le caractère 'alphabétique' est déterminé par la table de caractères locale. Par exemple, dans la table des caractères par défaut du "C", des caractères tels que a-umlaut (ä) ne seront pas convertis.
Voir aussi strtoupper() et ucfirst().
strtoupper
Description
string strtoupper ( string string)strtoupper() retourne string avec tous ses caractères alphabétiques mis en majuscule.
Notez que le caractère 'alphabétique' est déterminé par la table de caractères locale. Par exemple, dans la table des caractères par défaut du "C", des caractères tels que a-umlaut (ä) ne seront pas convertis.
Voir aussi strtolower() et ucfirst().
strtr
Description
string strtr ( string str, string from, string to)strtr() travaille sur str, remplaçant chaque occurrence de chaque caractère de la chaîne from correspondant à la chaîne to et retourne le résultat.
Si from et to sont de longueurs différentes, les caractères en trop sont ignorés.
strtr() peut aussi être appelée avec deux arguments. Dans ce cas, elle se comporte différemment : from doit être un tableau associatif contenant des paires de chaînes, qui seront remplacées dans la chaîne source. strtr() recherchera toujours la chaîne la plus longue, et la remplacera en premier. Elle ne remplacera jamais une portion de chaîne qu'elle a déjà remplacé.
Exemples:
<?php
$trans = array("bonjour" => "salut", "salut" => "bonjour");
echo strtr("bonjour à tous, j'ai dit salut", $trans)."\n";
?> |
Note : Travailler avec deux arguments a été ajouté en PHP 4.0.
Voir aussi ereg_replace().
substr_count
Description
int substr_count ( string haystrack, string needle)substr_count() retourne le nombre de fois que needle apparaît dans haystack.
substr_replace
Description
string substr_replace ( string string, string replacement, int start [, int length])substr_replace() effectue un remplacement dans la portion de string délimitée par le caractère start et de longueur optionnelle length. Le remplacement est fait avec la chaîne replacement. Le résultat est retourné.
Si start est positif, le remplacement commencera au caractère start, dans la chaîne string.
Si start est négative, le remplacement commencera au caractère start en partant de la fin de la chaîne string.
Si length est donné et positif, la chaîne retournée aura la longueur length. Si length est donné et négatif, la chaîne retournée aura la longueur length, en partant de la fin. Par défaut, il prendra la valeur de strlen(string ); c'est-à-dire qu'il remplacera jusqu'à la fin de la chaîne string.
Exemple 1. Exemple avec substr_replace()
|
Voir aussi str_replace() et substr().
Note : substr_replace() a été ajoutée en PHP 4.0.
substr
Description
string substr ( string string, int start [, int length])substr() retourne une portion de string, spécifiée avec le début start et la longueur length.
Si start est positif, la chaîne retournée commencera au caractère start de la chaîne string. Par exemple, 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. Par exemple:
<?php
$reste = substr("abcdef", 1); // retourne "bcdef"
$reste = substr("abcdef", 1, 3); // retourne "bcd"
?> |
Si start est négatif, la chaîne retournée commencera au caractère start de la chaîne string, en partant de la fin. Par exemple:
<?php
$reste = substr("abcdef", -1); // retourne "f"
$reste = substr("abcdef", -2); // retourne "ef"
$reste = substr("abcdef", -3, 1); // retourne "d"
?> |
Si length est donné et positive, la chaîne retournée aura la longueur length. Si length est donnée et négative, la chaîne retournée aura la longueur length, en partant de la fin.
trim
Description
string trim ( string str)trim() retire les espaces blancs de début et de fin de chaîne, et retourne la chaîne nettoyée. Les espaces blancs sont : "\n", "\r", "\t", "\v", "\0", et " " (espace).
ucfirst
Description
string ucfirst ( string str)ucfirst() met le premier caractère d'une chaîne str en majuscules, si ce caractère est alphabétique.
Notez que le caractère 'alphabétique' est déterminé par la table de caractères locale. Par exemple, dans la table des caractères par défaut du "C", des caractères tels que a-umlaut (ä) ne seront pas convertis.
Voir aussi strtoupper() et strtolower().
ucwords
(PHP 3>= 3.0.3, PHP 4 )
ucwords -- Force le premier caractère de chaque mot d'une chaîne en majusculeDescription
string ucwords ( string str)ucwords() met le premier caractère de chaque mot de la chaîne str si ce caractère est une lettre.
Note : La définition d'un mot est : une chaîne de caractères immédiatement après un caractère blanc (c'est-à-dire : espace, form-feed, nouvelle ligne, retour chariot, tabulation horizontale, et tabulation verticale).
Voir aussi strtoupper(), strtolower() et ucfirst().
vprintf
Description
void vprintf ( string format, array args)Display array values as a formatted string according to format (which is described in the documentation for sprintf()).
Operates as printf() but accepts an array of arguments, rather than a variable number of arguments.
See also: printf(), sprintf(), vsprintf()
vsprintf
Description
string vsprintf ( string format, array args)Return array values as a formatted string according to format (which is described in the documentation for sprintf()).
Operates as sprintf() but accepts an array of arguments, rather than a variable number of arguments.
wordwrap
Description
string wordwrap ( string str [, int width [, string break [, int cut]]])wordwrap() ajoute la césure str au numéro de colonne width. La ligne est césurée avec la chaîne break.
wordwrap() ajoute la césure automatiquement à la ligne 75 et utilise '\n' (nouvelle ligne) si width ou break sont omis.
Si cut vaut 1, la chaîne sera toujours coupée à la taille spécifiée. Dans ce cas, les mots qui dépasseront, seront coupés : voyez le second exemple.
Note : Le paramètre cut a été ajouté dans PHP 4.0.3.
Cet exemple va afficher :
Cet exemple va afficher
Voir aussi nl2br().
XCVIII. Sybase
- Table des matières
- sybase_affected_rows -- Retourne le nombre de lignes affectées par la dernière requête.
- sybase_close -- Ferme une connexion Sybase.
- sybase_connect -- Ouvre une connexion à un serveur Sybase.
- sybase_data_seek -- Déplace le pointeur interne de lignes.
- sybase_fetch_array -- Retourne une ligne sous la forme d'un tableau.
- sybase_fetch_field -- Lit les informations d'un champs.
- sybase_fetch_object -- Retourne une ligne sous la forme d'un objet.
- sybase_fetch_row -- Retourne une ligne sous la forme d'un tableau énuméré.
- sybase_field_seek -- Modifie l'index d'un champs.
- sybase_free_result -- Libère un résultat de la mémoire.
- sybase_get_last_message -- Retourne le dernier message du serveur
- sybase_min_client_severity -- Fixe la sévérité minimale du client
- sybase_min_error_severity -- Fixe la sévérité minimale du client pour les erreurs
- sybase_min_message_severity -- Fixe la sévérité minimale du client pour les messages
- sybase_min_server_severity -- Fixe la sévérité minimale du client pour le serveur
- sybase_num_fields -- Retourne le nombre de champs dans un résultat.
- sybase_num_rows -- Retourne le nombre de lignes dans un résultat.
- sybase_pconnect -- Ouvre une connexion persistante à un serveur Sybase.
- sybase_query -- Envoie une requête à une base Sybase.
- sybase_result -- Lit une valeur dans un résultat.
- sybase_select_db -- Sélectionne une base de données Sybase.
sybase_affected_rows
(PHP 3>= 3.0.6, PHP 4 )
sybase_affected_rows -- Retourne le nombre de lignes affectées par la dernière requête.Description
int sybase_affected_rows ( [resource link_identifier])sybase_affected_rows() retourne le nombre de lignes affectées par la dernière requête.
sybase_affected_rows() retourne le nombre de lignes affectées par la dernière requête INSERT, UPDATE ou DELETE sur le serveur associé à l'identifiant de connexion link_identifier. Si le lien n'est pas précisé, le dernier lien ouvert est utilisé.
Cette commande ne sert à rien sur les requête SELECT : uniquement sur des requêtes qui modifient les lignes. Pour connaître le nombre de lignes retournées par un SELECT, utilisez sybase_num_rows().
Note : sybase_affected_rows() est disponible avec l'interface CT vers Sybase, mais pas avec la librairie DB.
sybase_close
Description
boolean sybase_close ( resource link_identifier)sybase_close() retourne TRUE en cas de succès et FALSE en cas d'erreur.
sybase_close() termine la connexion avec le serveur Sybase associé à l'identifiant de connexion link_identifier.
Notez qu'il n'est pas utile de fermer les connexions non persistantes, car elles seront terminées à la fin du script.
sybase_close() ne ferme pas les connexions persistantes générées par sybase_pconnect().
Voir aussi sybase_connect() et sybase_pconnect().
sybase_connect
Description
resource sybase_connect ( string servername, string username, string password)sybase_connect() retourne un identifiant positif de lien Sybase en cas de succès, et FALSE en cas d'erreur.
sybase_connect() établit une connexion à un serveur Sybase. Le nom de serveur servername doit être valide, défini dans le fichier d'interface.
Si un deuxième appel à sybase_connect() est fait avec les mêmes arguments, une nouvelle connexion ne sera pas établie, mais ce sera l'identifiant de la connexion déjà ouverte qui sera retourné.
La connexion sera fermée dès la fin du script, à moins qu'elle ne soit pas explicitement fermée avec sybase_close().
Voir aussi sybase_pconnect() et sybase_close().
sybase_data_seek
Description
boolean sybase_data_seek ( resource result_identifier, int row_number)sybase_data_seek() retourne TRUE en cas de succès, et FALSE en cas d'échec.
sybase_data_seek() déplace le pointeur interne de ligne du résutalt Sybase associé à result_identifier jusqu'à la ligne row_number. Le prochain appel à sybase_fetch_row() sans préciser la ligne, retournera la ligne row_number.
Voir aussi sybase_data_seek().
sybase_fetch_array
Description
array sybase_fetch_array ( resource result)sybase_fetch_array() retourne un tableau qui contient la ligne demandée, ou FALSE s'il ne reste plus de ligne.
sybase_fetch_array() est une version évoluée de sybase_fetch_row(). En plus d'enregistrer les données dans un tableau à index numérique, cette fonction peut aussi les enregistrer dans un tableau associatif, en utilisant les nom des champs comme clés.
Il est très important de noter quesybase_fetch_array() N'est PAS nettement plus lent que sybase_fetch_row(), tandis qu'elle fourni un confort d'utilisation notable.
Pour plus de détails : sybase_fetch_row().
sybase_fetch_field
Description
object sybase_fetch_field ( resource result [, int field_offset])sybase_fetch_field() retourne un objet contenant les informations du champs.
sybase_fetch_field() sert à obtenir des informations à propos des champs dans le résultat result. Si l'offset du champs n'est pas précisé, le champs suivant est traité.
Les propriétés des objets sont :
name - column name. nom de la colonne. Si la colonne est un résultat de fonction, le nom de cette fonction devient computed#N, où #N est un numéro de série.
column_source - la table d'origine de la colonne.
max_length - taille maximale de la colonne
numeric - 1 si la colonne est de type numérique.
type - type de données de la colonne
Voir aussi sybase_field_seek().
sybase_fetch_object
Description
int sybase_fetch_object ( resource result)sybase_fetch_object() retourne un objet qui contient la ligne demandée, en cas de succès, et FALSE en cas d'erreur.
sybase_fetch_object() est similaire à sybase_fetch_array(), avec une différence : c'est un objet qui est retourné à la place d'un tableau. Indirectement, cela signifie que vous ne pourrez accéder aux valeurs que par les propriétés, et non plus avec des offsets (les nombres sont interdits comme nom de propriété).
Au niveau de la vitesse, cette fonction est identique à sybase_fetch_array(), et presque aussi rapide que sybase_fetch_row() (la différence est insignifiante).
Voir aussi sybase_fetch-array() et sybase_fetch-row().
sybase_fetch_row
Description
array sybase_fetch_row ( resource result)sybase_fetch_row() retourne un tableau qui contient la ligne demandée, en cas de succès, et FALSE en cas d'erreur.
sybase_fetch_row() lit une ligne dans le résultat associé à l'identifiant de résultat result. La ligne retournée est sous la forme d'un tableau. Chaque champs est enregistré dans un index du tableau, les index commençant à 0.
Les prochains appels à sybase_fetch_row() retourneront la ligne suivante du résultat, ou FALSE, s'il ne reste plus de ligne.
Voir aussi sybase_fetch_array(), sybase_fetch_object(), sybase_data_seek() et sybase_result().
sybase_field_seek
Description
int sybase_field_seek ( resource result, int field_offset)sybase_field_seek() modifie l'index d'un champs. Le prochain appel à la fonction sybase_fetch_field() sans préciser l'index du champs retournera ce champs.
Voir aussi sybase_fetch_field().
sybase_free_result
Description
boolean sybase_free_result ( int result)sybase_free_result() n'est vraiment utile que si vous risquez d'utiliser trop de mémoire durant votre script. La mémoire occupée par les résultats est automatiquement libérée à la fin du script. Mais, si vous êtes sÛr de ne pas avoir besoin du résultat ultérieurement.
sybase_get_last_message
Description
string sybase_get_last_message ( void)sybase_get_last_message() retourne le dernier message rapporté par le serveur.
sybase_min_client_severity
Description
void sybase_min_client_severity ( int severity)sybase_min_client_severity() fixe la sévérité minimale du client.
Note : sybase_min_client_severity() est disponible avec l'interface CT vers Sybase, mais pas avec la librairie DB.
Voir aussi sybase_min_server_severity().
sybase_min_error_severity
Description
void sybase_min_error_severity ( int severity)sybase_min_error_severity() fixe la sévérité minimale du client pour les erreurs.
Voir aussi sybase_min_message_severity().
sybase_min_message_severity
Description
void sybase_min_message_severity ( int severity)sybase_min_message_severity() fixe la sévérité minimale du client pour les messages.
Voir aussi sybase_min_error_severity().
sybase_min_server_severity
Description
void sybase_min_server_severity ( int severity)sybase_min_server_severity() fixe la sévérité minimale du client pour le serveur.
Note : sybase_min_server_severity() est disponible avec l'interface CT vers Sybase, mais pas avec la librairie DB.
Voir aussi sybase_min_client_severity().
sybase_num_fields
Description
int sybase_num_fields ( resource result)sybase_num_fields() retourne le nombre de champs du résultat result.
Voir aussi sybase_query(), sybase_fetch_field() et sybase_num_rows().
sybase_num_rows
Description
int sybase_num_rows ( resource result)sybase_num_rows() retourne le nombre de lignes du résultat result.
Voir aussi sybase_query() et sybase_fetch_row().
sybase_pconnect
Description
resource sybase_pconnect ( string servername, string username, string password)sybase_pconnect() retourne un identifiant de connexion positif en cas de succès, et FALSE en cas d'erreur.
sybase_connect() se comporte comme sybase_connect() avec deux différence majeures :
Premièrement, lors de la connexion, la fonction va chercher une connexion (persistante) déjà ouverte, avec le même hôte, nom de compte et mot de passe. Si une telle connexion est trouvée, un identifiant de cette connexion est retourné, plutôt que d'en ouvrir une nouvelle.
Deuxièmement, la connexion au serveur SyBase ne sera pas terminée lors de la fin du script. Au contraire, le lien sera maintenu pour des connexions ultérieures. sybase_close() ne fermera pas un lien crée par sybase_pconnect().
Ce type de liens est dit 'persistant'.
sybase_query
Description
int sybase_query ( string query, int link_identifier)sybase_query() retourne un identifiant de résultat positif en cas de succès, et FALSE sinon.
sybase_query() envoie une requête à la base de données courante, sur le serveur associé à l'identifiant de connexion. Si l'identifiant de connexion n'est pas précisé, la fonction essaiera d'utiliser la dernière connexion ouverte. Si aucune connexion n'a été ouverte, la fonction va tenter d'ouvrir une connexion avec la fonction sybase_connect().
Voir aussi sybase_select_db() et sybase_connect().
sybase_result
Description
string sybase_result ( resource result, int i, mixed field)sybase_result() retourne le contenu d'une cellule. L'argument field peut être l'index du champs, ou bien le nom du champs, ou encore, le nom de la table " point " le nom du champs. Si la colonne a été aliasée ('SELECT foo AS bar FROM...'), utilisez l'alias à la place du nom de la colonne.
Lorsque vous travaillez sur des résultats de grande taille, vous devriez utiliser les autres fonctions qui lisent une ligne entière (voir plus loin). Etant donné que ces fonctions lisent une ligne entière, elles sont BEAUCOUP plus rapide que sybase_result(). De plus, l'utilisation d'index numérique est beaucoup plus rapide que les noms des champs, ou les noms des tables et des champs.
Fonctions de substitution, à haute efficacité : sybase_fetch_row(), sybase_fetch_array() et sybase_fetch_object().
sybase_select_db
Description
boolean sybase_select_db ( string database_name, resource link_identifier)sybase_select_db() retourne TRUE en cas de succès, et FALSE en cas d'erreur.
sybase_select_db() change la base de données courante et active sur le serveur associé avec l'identifiant de connexion link_identifier. Si link_identifier n'est pas précisé, le dernier lien ouvert est utilisé. Si aucun lien n'a été ouvert, la fonction va tenter d'en établir un en appelant sybase_connect().
Tous les prochains appels à sybase_query() seront faits sur la bas de données courante et active.
Voir aussi sybase_connect(), sybase_pconnect() et sybase_query().
XCIX. Tokenizer functions
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
- Table des matières
- token_get_all -- Split given source in tokens
- token_name -- Get the name of a given token
token_get_all
Description
array token_get_all ( string source)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
token_name
Description
string token_name ( int type)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
C. URL
- Table des matières
- base64_decode -- Décode une chaîne en MIME base64
- base64_encode -- Encode une chaîne en MIME base64.
- parse_url -- Analyse une URL et retourne ses composants.
- rawurldecode -- Décode une chaîne URL.
- rawurlencode -- Encode une chaîne en URL, selon la RFC1738.
- urldecode -- Décode une chaîne encodée URL.
- urlencode -- Encode une chaîne en URL.
base64_decode
Description
string base64_decode ( string encoded_data)base64_decode() décode encoded_data et retourne les données décodées. Les informations initiales peuvent être binaires.
Voir aussi base64_encode() et la RFC2045 section 6.8.
base64_encode
Description
string base64_encode ( string data)base64_encode() retourne data encodé en base64. Cet encodage est fait pour permettre aux informations binaires d'être manipulées par les systèmes qui ne gèrent pas correctement les 8 bits, comme par exemple, les corps de mail.
Une chaîne encodée Base64 prend, grosso modo, 33% de plus que les données initiales.
Voir aussi base64_decode(), chunk_split() et la RFC2045 section 6.8.
parse_url
Description
array parse_url ( string url)parse_url() retourne un tableau associatif contenant les composants de l'URL. Les composants recherchés sont : "scheme", "host", "port", "user", "pass", "path", "query", et "fragment".
rawurldecode
Description
string rawurldecode ( string str)rawurldecode() retourne une chaîne dont les séquences de caractères %xy, avec xy deux valeurs hexadécimales, auront été remplacées par le caractère ASCII correspondant. Par exemple, la chaîne
foo%20bar%40baz |
foo bar@baz |
Voir aussi rawurlencode(), urldecode() et urlencode().
rawurlencode
Description
string rawurlencode ( string str)rawurlencode() retourne une chaîne dont tous les caractères non-alpha-numériques (hormis
-_. |
Voir aussi rawurldecode(), urldecode() et urlencode().
urldecode
Description
string urldecode ( string str)urldecode() décode toutes les séquences %## et les remplace par leur valeur. La chaîne ainsi décodée est retournée.
Voir aussi urlencode(), rawurlencode() et rawurldecode().
urlencode
Description
string urlencode ( string str)urlencode() retourne une chaîne dont les caractères non alpha-numériques (hormis -_.) sont remplacés par des séquences commençant par un caractère pourcentage (%), suivi de deux chiffres hexadécimaux. Les espaces sont remplacés par des signes plus (+). Ce codage est celui qui est utilisé pour poster des informations dans les formulaires HTML. Le type MIME est application/x-www-form-urlencoded. Ce codage est différent de celui spécifié dans la RFC1738 (voir rawurlencode()) : pour des raisons historiques, les espaces sont remplacés par des signes plus (+). urlencode() est pratique pour transmettre des informations via une URL. C'est aussi un moyen de passer des informations d'une page à l'autre.
Voir aussi urldecode().
Note: Faites bien attention aux variables qui ressemblent à des entités HTML, comme par exemple &, © et £, qui sont analysées par le client web et remplacée par leur valeur. C'est un vrai problème qui a été montré par le W3C depuis longtemps. La référence est ici : http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2. PHP supporte le remplacement de séparateur d'arguments par un point-virgule, comme recommandé par le W3C, grâce à la directive arg_separator .ini. Malheureusement, la plupart des clients web n'envoient pas leurs données de formulaire avec des points-virgules. Une solution plus portable est d'utiliser & à la place de & comme séparateur. Vous n'avez alors pas à changer la directive arg_separator. Laissez-la à &, mais encodez vos URL avec htmlentities().
Exemple 2. Exemple avec urlencode() et htmlentities()
|
Voir aussi urldecode(), htmlentities(), rawurldecode() et rawurlencode().
CI. Variables
- Table des matières
- doubleval -- Retourne la valeur numérique (double) de la variable.
- empty -- Détermine si une variable est affectée.
- floatval -- Get float value of a variable
- get_defined_vars -- Liste toutes les variables définies
- get_resource_type -- Retourne le type de ressource
- gettype -- Retourne le type de la variable.
- import_request_variables -- Import GET/POST/Cookie variables into the global scope
- intval -- Retourne la valeur numérique (integer) de la variable.
- is_array -- Détermine si une variable est un tableau.
- is_bool -- Détermine si une variable est un tableau booléen
- is_callable -- Find out whether the argument is a valid callable construct
- is_double -- Détermine si une variable est de type double.
- is_float -- Détermine si une variable est de type float.
- is_int -- Détermine si une variable est de type integer.
- is_integer -- Détermine si une variable est de type int.
- is_long -- Détermine si une variable est de type integer.
- is_null -- Indique si une variable est NULL
- is_numeric -- Détermine si une variable est un type numérique
- is_object -- Détermine si une variable est de type object.
- is_real -- Détermine si une variable est de type real.
- is_resource -- Détermine si une variable est une ressource
- is_scalar -- Indique si une variable est un scalaire
- is_string -- Détermine si une variable est de type string.
- isset -- Détermine si une variable est affectée.
- print_r -- Affiche des informations lisibles pour une variable.
- serialize -- Linéarise une variable
- settype -- Affecte un type à une variable.
- strval -- Retourne la valeur de la variable, au format chaîne.
- unserialize -- Crée une variable PHP à partir d'une valeur linéarisée
- unset -- Détruit une variable
- var_dump -- Dumpe les informations d'une variable.
- var_export -- Outputs or returns a string representation of a variable
doubleval
Description
double doubleval ( mixed var)doubleval() retourne la valeur numérique (double) de la variable var.
var peut être de type scalaire. Vous ne pouvez pas utiliser la fonction doubleval() avec un tableau ou un objet.
<?php $var = '122.34343Le'; $double_valeur_de_var = doubleval($var); print $double_valeur_de_var; // affiche 122.34343 ?> |
Voir aussi intval(), strval(), settype() et Transtypage.
empty
Description
int empty ( mixed var)empty() retourne la valeur FALSE si la variable var est affectée ou bien a une valeur différente de 0; la valeur TRUE dans les autres cas.
<?php
$var = 0;
if (empty($var)) { // retourne TRUE
print 'soit $var vaut 0, soit il n'est pas défini';
}
if (!isset($var)) { // retourne FALSE
print '$var n'est pas définie';
}
?> |
Notez que cette fonction n'a pas de sens si elle est utilisée sur autre chose qu'une variable. i.e. empty (addslashes ($name)) n'a pas de sens, car cela revient à vérifier une entité qui n'est pas une variable.
floatval
Description
float floatval ( mixed var)Returns the float value of var.
Var may be any scalar type. You cannot use floatval() on arrays or objects.
$var = '122.34343The'; $float_value_of_var = floatval ($var); print $float_value_of_var; // prints 122.34343 |
See also intval(), strval(), settype() and Type juggling.
get_defined_vars
Description
array get_defined_vars ( void )get_defined_vars() retourne un tableau multidimensionnel contenant la liste de toutes les variables définies, qu'elles soient des variables d'environnement, de serveurs ou définies par l'utilisateur.
<?php $b = array(1,1,2,3,5,8); $arr = get_defined_vars(); // affiche $b print_r($arr["b"]); // affiche le chemin jusqu'à l'interpréteur CGI PHP (si PHP est utilisé en CGI) // i.e. /usr/local/bin/php echo $arr["_"]; // affiche la ligne de commande, s'il y en a une print_r($arr["argv"]); // affiche toutes les variables serveurs print_r($arr["HTTP_SERVER_VARS"]); // affiche toutes les clés disponibles dans les tableaux de variables print_r(array_keys(get_defined_vars())); ?> |
Voir aussi get_defined_functions().
get_resource_type
Description
string get_resource_type ( resource handle)get_resource_type() retourne une chaîne représentant le type de ressources de handle. Si le paramètre n'est pas une ressource valide, une erreur est générée.
<?php
$c = mysql_connect();
echo get_resource_type($c)."\n";
// affiche : mysql link
// (lien mysql)
$fp = fopen("foo","w");
echo get_resource_type($fp)."\n";
// affiche : file
// (fichier)
$doc = new_xmldoc("1.0");
echo get_resource_type($doc->doc)."\n";
// affiche : domxml document
// (document domxml)
?> |
gettype
Description
string gettype ( mixed var)gettype() retourne le type de la variable PHP var.
Les chaînes de caractères que peut retourner la fonction sont les suivantes :
"boolean"
"integer"
"double"
"string"
"array"
"object"
"resource"
"user function"
"unknown type"
Voir aussi settype().
import_request_variables
Description
bool import_request_variables ( string types [, string prefix])Imports GET/POST/Cookie variables into the global scope. It is useful if you disabled register_globals, but would like to see some variables in the global scope.
Using the types parameter, you can specify which request variables to import. You can use 'G', 'P' and 'C' characters respectively for GET, POST and Cookie. These characters are not case sensitive, so you can also use any combination of 'g', 'p' and 'c'. POST includes the POST uploaded file information. Note that the order of the letters matters, as when using "gp", the POST variables will overwrite GET variables with the same name. Any other letters than GPC are discarded.
The prefix parameter is used as a variable name prefix, prepended before all variable's name imported into the global scope. So if you have a GET value named "userid", and provide a prefix "pref_", then you'll get a global variable named $pref_userid.
If you're interested in importing other variables into the global scope, such as SERVER, consider using extract().
Note : Although the prefix parameter is optional, you will get an E_NOTICE level error if you specify no prefix, or specify an empty string as a prefix. This is a possible security hazard. Notice level errors are not displayed using the default error reporting level.
// This will import GET and POST vars
// with an "rvar_" prefix
import_request_variables("gP", "rvar_");
print $rvar_foo; |
See also $_REQUEST, register_globals, Predefined Variables, and extract().
intval
Description
int intval ( mixed var [, int base])intval() retourne la valeur numérique entière (integer) de la variable var, en convertisant la valeur dans la base spécifiée (par défaut en base 10).
var peut être de type scalaire. Vous ne pouvez pas utiliser la fonction intval() avec un tableau ou un objet.
Voir aussi doubleval(), strval(), settype() et Transtypage.
is_array
Description
bool is_array ( mixed var)is_array() renvoie la valeur TRUE si la variable var est un tableau, FALSE sinon.
Voir aussi is_double(), is_float(), is_int(), is_integer(), is_real(), is_string(), is_long(), et is_object().
is_bool
Description
bool is_bool ( mixed var)is_bool() retourne TRUE si var est un booléen.
Voir aussi is_array(), is_double(), is_float(), is_int(), is_integer(), is_real(), is_string(), is_long(), et is_object().
is_callable
Description
bool is_callable ( mixed var [, bool syntax_only [, string callable_name]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
is_double
Description
bool is_double ( mixed var)is_double() renvoie TRUE si la variable var est du type "double", FALSE sinon.
Voir aussi is_array(), is_bool(), is_float(), is_int(), is_integer(), is_real(), is_string(), is_long(), et is_object().
is_float
Description
bool is_float ( mixed var)Cette fonction est un alias de la fonction is_double().
Voir aussi is_double(), is_bool(), is_real(), is_int(), is_integer(), is_string(), is_object(), is_array(), et is_long().
is_int
Description
bool is_int ( mixed var)is_int() est un alias de la fonction is_long().
Voir aussi is_bool(), is_double(), is_float(), is_integer(), is_string(), is_real(), is_object(), is_array(), et is_long().
is_integer
Description
bool is_integer ( mixed var)Cette fonction est un alias de la fonction is_long().
Voir aussi is_bool(), is_double(), is_float(), is_int(), is_string(), is_real(), is_object(), is_array(), et is_long().
is_long
Description
bool is_long ( mixed var)is_long() renvoie TRUE si la variable var est du type entier long (long), FALSE sinon.
Voir aussi is_bool(), is_double(), is_float(), is_int(), is_real(), is_string(), is_object(), is_array(), et is_integer().
is_null
Description
bool is_null ( mixed var)is_null() retourne TRUE, si var est NULL, et FALSE.
Voir aussi : is_bool(), is_double(), is_numeric(), is_float(), is_int(), is_real(), is_string(), is_object(), is_array() et is_integer().
is_numeric
Description
bool is_numeric ( mixed var)is_numeric() retourne TRUE si var est un nombre, ou une chaîne numérique, ou FALSE sinon.
Voir aussi is_bool(), is_double(), is_float(), is_int(), is_real(), is_string(), is_object(), is_array(), et is_integer().
is_object
Description
bool is_object ( mixed var)is_object() renvoie TRUE si la variable var est un objet, FALSE sinon.
Voir aussi is_bool(), is_long(), is_int(), is_integer(), is_float(), is_double(), is_real(), is_string(), et is_array().
is_real
Description
bool is_real ( mixed var)Cette fonction est un alias de la fonction is_double().
Voir aussi is_bool(), is_long(), is_int(), is_integer(), is_float(), is_double(), is_object(), is_string(), et is_array().
is_resource
Description
bool is_resource ( mixed var)is_resource() retourne TRUE si la variable var est une ressource PHP, sinon FALSE.
Les ressources peuvent être des pointeurs de fichiers, des identifiants de résultats SQL, qui sont allouées et libérées en interne, par PHP, et qui peuvent demander un peut de nettoyage lorsqu'elle sont devenues inutiles, mais pas encore supprimées.
is_scalar
Description
bool is_scalar ( mixed var)is_scalar() retourne TRUE si la variable var est scalaire, et FALSE sinon.
Les variables scalaires sont celles qui contiennent des entiers, des nombres à virgules flottantes, des chaînes de caractères ou des booléens. Par exemple :
<?php
function show_var($var) {
if (is_scalar($var))
echo $var;
else
var_dump($var);
}
$pi = 3.1416;
$proteines = array("hemoglobine", "cytochrome c oxidase", "ferredoxine");
show_var($pi);
// affiche : 3.1416
show_var($proteines)
// affiche:
// array(3) {
// [0]=>
// string(10) "hemoglobine"
// [1]=>
// string(20) "cytochrome c oxidase"
// [2]=>
// string(10) "ferredoxine"
// }
?> |
Note : is_scalar() a été ajoutée en version PHP 4.05.
Voir aussi : is_bool(), is_double(), is_numeric(), is_float(), is_int(), is_real(), is_string(), is_object(), is_array() et is_integer().
is_string
Description
bool is_string ( mixed var)is_string() renvoie TRUE si la variable var est du type chaine de caractères (string), FALSE sinon.
Voir aussi is_long(), is_int(), is_integer(), is_float(), is_double(), is_real(), is_object(), et is_array().
isset
Description
int isset ( mixed var)isset() renvoie TRUE si la variable var est définie, FALSE sinon.
Si une variable a été désaffectée avec la fonction unset(), la fonction isset() renverra FALSE.
print_r
Description
void print_r ( mixed expression)Cette fonction affiche des informations à propos d'une variable, de manière à ce qu'elle soit lisible. Pour une chaîne, un entier ou un double, la valeur sera elle même sera affichée. Pour les tableaux, les valeurs seront présentées dans un format qui montre les clés et les valeurs. Une notation similaire est disponible pour les objets.
Comparer print_r() et var_dump().
serialize
Description
string serialize ( mixed value)serialize() retourne une chaîne contenant une représentation linéaire de value, pour stockage.
C'est une technique pratique pour stocker ou passer des valeurs de PHP entre scripts, sans perdre ni leur structure, ni leur type.
Pour récupérer une variable linéarisée, et retrouver une variable, utilisez unserialize(). serialize() acceptent les types integer, double, string, array (multidimensionnels) et object (les propriétés des objets seront linéarisées, mais pas les méthodes).
Exemple 1. Exemple avec serialize()
|
settype
Description
int settype ( string var, string type)settype() modifie le type de la variable var en type.
Les valeurs possibles pour le paramètre type sont :
"integer"
"double"
"string"
"array"
"object"
settype() renvoie TRUE en cas de succès, FALSE sinon.
Voir aussi gettype().
strval
Description
string strval ( mixed var)strval() retourne la valeur de la variable var, au format chaîne de caractères.
var peut être un scalaire. Vous ne pouvez pas utiliser la fonction strval() avec des tableaux ou des objets.
Voir aussi doubleval(), intval(), settype() et Transtypage.
unserialize
Description
mixed unserialize ( string str)unserialize() prend une variable linéarisée (voir serialize()) et la convertit en variable PHP. La valeur convertie est retournée par la fonction, et peut être de type integer, double, string, array ou object. Les objets linéarisés perdent leurs méthodes.
Exemple 1. Exemple avec unserialize()
|
unset
Description
void unset ( mixed var [, mixed var [, ...]])unset() détruit les variables var. Notez qu'en PHP 3, unset() retournait toujours TRUE (en fait, la valeur entière 1). unset() n'est plus une véritable fonction : c'est une structure du langage, ce qui fait qu'elle ne retourne pas de valeur. Lire la valeur retournée par unset() (dans une variable, par exemple), retourne une erreur d'analyse.
Le comportement de unset() à l'intérieur d'une fonction peut varier suivant le type de variable que vous voulez détruire.
Si une variable globale est détruite avec unset() depuis une fonction, seule la variable locale sera détruite. Le variable globale gardera la valeur acquise avant l'appel à unset().
<?php
function destroy_foo() {
global $foo;
unset($foo);
}
$foo = 'bar';
destroy_foo();
echo $foo;
?> |
Si une variable qui est passée par référence est détruite à l'intérieur d'une fonction, seule la variable locale sera détruite. La variable globale conservera la dernière valeur qu'elle avait avant l'appel de unset().
<?php
function foo(&$bar) {
unset($bar);
$bar = "bla";
}
$bar = 'truc';
echo "$bar\n";
foo($bar);
echo "$bar\n";
?> |
Si une variable statique est détruite à l'intérieure d'une fonction unset() détruira la référence à la variable statique, plutôt que la variable statique elle même.
L'affichage du script ci-dessus donnera :Si vous voulez détruire une variable globale, depuis une fonction, vous pouvez utiliser le tableau $GLOBALS :
Note : unset() est une structure du langage et non pas une fonction.
var_dump
Description
void var_dump ( mixed expression)Cette fonction retourne les informations structurées d'une variable, y compris son type et sa valeur. Les tableaux sont explorés recursivement, avec des indentations, pour mettre en valeur leur structure.
Comparez var_dump() et print_r().
var_export
Description
mixed var_export ( mixed expression [, bool return])This function returns structured information about the variable that is passed to this function. It is similar to var_dump() with the exception that the returned representation is valid PHP code.
You can also return the variable representation by using TRUE as second parameter to this function.
Compare var_export() to var_dump().
CII. vpopmail functions
- Table des matières
- vpopmail_add_alias_domain_ex -- Add alias to an existing virtual domain
- vpopmail_add_alias_domain -- Add an alias for a virtual domain
- vpopmail_add_domain_ex -- Add a new virtual domain
- vpopmail_add_domain -- Add a new virtual domain
- vpopmail_add_user -- Add a new user to the specified virtual domain
- vpopmail_alias_add -- insert a virtual alias
- vpopmail_alias_del_domain -- deletes all virtual aliases of a domain
- vpopmail_alias_del -- deletes all virtual aliases of a user
- vpopmail_alias_get_all -- get all lines of an alias for a domain
- vpopmail_alias_get -- get all lines of an alias for a domain
- vpopmail_auth_user -- Attempt to validate a username/domain/password. Returns true/false
- vpopmail_del_domain_ex -- Delete a virtual domain
- vpopmail_del_domain -- Delete a virtual domain
- vpopmail_del_user -- Delete a user from a virtual domain
- vpopmail_error -- Get text message for last vpopmail error. Returns string
- vpopmail_passwd -- Change a virtual user's password
- vpopmail_set_user_quota -- Sets a virtual user's quota
vpopmail_add_alias_domain_ex
Description
bool vpopmail_add_alias_domain_ex ( string olddomain, string newdomain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_add_alias_domain
Description
bool vpopmail_add_alias_domain ( string domain, string aliasdomain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_add_domain_ex
Description
bool vpopmail_add_domain_ex ( string domain, string passwd [, string quota [, string bounce [, bool apop]]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_add_domain
Description
bool vpopmail_add_domain ( string domain, string dir, int uid, int gid)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_add_user
Description
bool vpopmail_add_user ( string user, string domain, string password [, string gecos [, bool apop]])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_alias_add
Description
bool vpopmail_alias_add ( string user, string domain, string alias)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_alias_del_domain
Description
bool vpopmail_alias_del_domain ( string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_alias_del
Description
bool vpopmail_alias_del ( string user, string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_alias_get_all
Description
array vpopmail_alias_get_all ( string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_alias_get
Description
array vpopmail_alias_get ( string alias, string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_auth_user
(PHP 4 >= 4.0.5)
vpopmail_auth_user -- Attempt to validate a username/domain/password. Returns true/falseDescription
bool vpopmail_auth_user ( string user, string domain, string password [, string apop])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_del_domain_ex
Description
bool vpopmail_del_domain_ex ( string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_del_domain
Description
bool vpopmail_del_domain ( string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_del_user
Description
bool vpopmail_del_user ( string user, string domain)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_error
Description
string vpopmail_error ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_passwd
Description
bool vpopmail_passwd ( string user, string domain, string password)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
vpopmail_set_user_quota
Description
bool vpopmail_set_user_quota ( string user, string domain, string quota)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
CIII. API Windows 32 bits
- Table des matières
- w32api_deftype -- Définit un type pour utilisation avec les fonctions windows API
- w32api_init_dtype -- Crée une instance de type de données et la remplit
- w32api_invoke_function -- Appelle une fonction windows 32
- w32api_register_function -- Enregistre une fonction win32 dans PHP
- w32api_set_call_method -- Modifie le nom de la méthode appelée
w32api_deftype
Description
int w32api_deftype ( string typename, string member1_type, string member1_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
w32api_init_dtype
Description
resource w32api_init_dtype ( string typename, mixed val1, mixed val2)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
w32api_invoke_function
Description
mixed w32api_invoke_function ( string funcname)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
w32api_invoke_function() appelle la fonction funcname, en lui passant les arguments passés après le nom de la fonction.
w32api_register_function
Description
bool w32api_register_function ( string libary, string function_name)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
w32api_set_call_method
Description
void w32api_set_call_method ( int method)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
CIV. WDDX
Ces fonctions doivent fonctionner avec l'aide de WDDX.
Pour utiliser WDDX, you devez installer la librairie EXPAT (qui est fournie avec la distribution d'Apache 1.3.7 ou plus récent), et recompiler PHP avec --with-xml et --enable-wddx.
Notez bien que toutes les fonctions qui enregistrent des données, utilisent le premier élément d'un tableau pour savoir si ce tableau doit être enregistré sous la forme d'un tableau, ou d'une structure. Si le premier élément a une clé de type chaîne, le tableau sera enregistré sous la forme d'une structure, et sinon, sous la forme d'un tableau.
Cet exemple va produire le résultat suivant :
<wddxPacket version='0.9'><header comment='Paquet PHP' ><data> <string>Exemple de paquet de PHP à WDDX</string></data></wddxPacket> |
Exemple 2. Utilisation de paquets incrémentaux
|
Cet exemple donnera :
- Table des matières
- wddx_add_vars -- Ajouter des variables à un paquet WDDX.
- wddx_deserialize -- Lire un paquet WDDX.
- wddx_packet_end -- Clos un paquet WDDX.
- wddx_packet_start -- Commencer un nouveau paquet WDDX avec une structure
- wddx_serialize_value -- Enregistrer une valeur dans un paquet WDDX
- wddx_serialize_vars -- Enregistrer plusieurs valeurs dans un paquet WDDX
wddx_add_vars
Description
wddx_add_vars ( resource packet_id, mixed name_var [, mixed ...])wddx_add_vars() sert à enregistrer les variables passées en argument, et les ajouter au paquet repéré par son identifiant packet_id. Les variables enregistrées sont spécifiées de la même façon que pour wddx_serialize_vars().
wddx_deserialize
Description
mixed wddx_deserialize ( string packet)wddx_deserialize() prend la chaîne packet et la lit. Cette fonction retourne un résultat qui peut être une chaîne, un nombre ou un tableau. Notez que les structures sont lues sous la forme de tableaux associatifs.
wddx_packet_end
Description
string wddx_packet_end ( resource packet_id)wddx_packet_end() clos un paquet WDDX repéré par son identifiant packet_id.
wddx_packet_start
Description
resource wddx_packet_start ( [string comment])wddx_packet_start() sert à créer un nouveau paquet WDDX, pour pouvoir y faire des ajouts incrémentaux de variables. Cette fonction prend un argument optionnel comment et retourne un identifiant de paquet, qui servira à d'autres fonctions. Elle va automatiquement créer une définition de structure dans le paquet, pour accueillir des variables.
wddx_serialize_value
Description
string wddx_serialize_value ( mixed var [, string comment])wddx_serialize_value() sert à créer un paquet WDDX à partir d'une seule valeur. Cette fonction prend la valeur de var, et un argument optionnel comment qui apparaîtra dans l'en-tête du paquet, et retourne un paquet WDDX.
wddx_serialize_vars
Description
string wddx_serialize_vars ( mixed var_name [, mixed ...])wddx_serialize_vars() sert à créer un paquet WDDX avec une structure qui contient la représentation des variables passées en arguments.
wddx_serialize_vars() prend un nombre variable d'arguments, chacun d'entre eux pouvant être une chaîne contenant le nom d'une variable, ou un tableau de chaîne de nom de variable, ou même d'autres tableaux.
L'exemple ci-dessus donnera : <wddxPacket version='0.9'><header ><data><struct><var name='a'><number>1</number></var> <var name='b'><number>5.5</number></var><var name='c'><array length='3'> <string>bleu</string><string>orange</string><string>violet</string></array></var> <var name='d'><string>colors</string></var></struct></data></wddxPacket>
CV. Analyseur syntaxique XML
Introduction
A propos de XML
Le langage XML (eXtensible Markup Language (Langage à Balises Etendu)) est un format structuré de données pour les échanges sur le web. C'est un standard défini par le consortium World Wide Web (W3C). Plus d'informations à propos du XML et des technologies afférentes sont accessibles (en anglais) http://www.w3.org/XML/.
Installation
Cette extension de PHP utilise expat, disponible à http://www.jclark.com/xml/. Le fichier Makefile livré avec expat ne construit pas par défaut de librairie : il faut utiliser la ligne suivante :
libexpat.a: $(OBJS) ar -rc $@ $(OBJS) ranlib $@ |
Notez que si vous utilisez Apache-1.3.7 ou plus récent, vous disposez déjà de la librairie expat. Configurez simplement PHP avec --with-xml (sans aucun autre information) et la librairie expat d'Apache sera automatiquement utilisée.
Sous UNIX, lancez la configuration de PHP avec l'option --with-xml, la librairie expat étant installée là où votre compilateur peut la trouver. Si vous compilez PHP comme module de PHP 1.3.9 ou plus récent, PHP utilisera automatiquement le module expat livré avec Apache. Il vous faudra peut être fixer les valeurs des variables d'environnement CPPFLAGS et LDFLAGS, si vous avez fait une installation exotique.
Compilez PHP. Tada! C'est fait !
A propos de cette extension :
Cette extension PHP supporte la librairie expat de James Clark sous PHP. Cela vous permettra d'analyser mais pas de valider les documents XML. Il supporte trois types de codage différents, disponibles aussi sous PHP: US-ASCII, ISO-8859-1 et UTF-8. UTF-16 n'est pas supporté.
Cette extension vous permet de créer des analyseurs XML puis de définir des points d'entrée pour chaque événement XML. Les analyseurs XML disposent de quelques paramétrages.
Les gestionnaires d'évènements XML sont:
Tableau 1. Les gestionnaires d'évènements XML
| Fonction PHP de configuration du gestionnaire | Description de l'événement |
|---|---|
| xml_set_element_handler() | Un événement est généré à chaque fois que l'analyseur XML rencontre une balise de début ou de fin. Deux gestionnaires sont disponibles : un pour le début, et un pour la fin. |
| xml_set_character_data_handler() | "Character data" correspond grosso modo à tout ce qui n'est pas une balise XML, y compris les espaces entre les balises. Notez bien que l'analyseur XML n'ajoute ou n'efface aucun espace, et que c'est à l'application (c'est-à-dire vous) de décider de la signification de ces espaces. |
| xml_set_processing_instruction_handler() | Les programmeurs PHP sont habitués aux instructions exécutables (processing instructions ou PIs). <?php ?> est une instruction exécutable où php est appelé programme cible. Ces instructions sont gérées de manière spécifiques, (sauf le programme cible, qui est réservé à XML). |
| xml_set_default_handler() | Tout ce qui n'a pas trouvé de gestionnaire est transmis au gestionnaire par défaut. Vous retrouverez par exemple, les déclarations de type de document dans ce gestionnaire. |
| xml_set_unparsed_entity_decl_handler() | Ce gestionnaire est appelé pour gérer les déclaration des entités non analysés. |
| xml_set_notation_decl_handler() | Ce gestionnaire est appelé pour gérer les notations. |
| xml_set_external_entity_ref_handler() | Ce gestionnaire est appelé lorsque l'analyseur XML trouve une référence à un fichier externe. Cela peut être un fichier, ou une URL. Reportez-vous à entité externe pour un exemple. |
Problèmes de casse
Les fonctions de gestion des balises peuvent rencontrer des balises en minuscule, majuscule ou encore dans un mélange des deux. En XML, la procédure standard est d' "identifier les séquences de caractère qui ne sont pas reconnues comme majuscule, et de les remplacer par leur équivalent majuscule". En d'autres termes, XML met toutes lettres en majuscules.
Par défaut, tous les noms des éléments qui sont transmis aux fonctions de gestion sont mises en majuscule. Ce comportement est contrôlé par l'analyseur XML, et peut être lu et modifié avec les fonctions respectives xml_parser_get_option() et xml_parser_set_option(), respectivement.
Codes d'erreurs
Les constantes suivantes sont définies comme des codes d'erreurs XML : (retournée par xml_parse())
| XML_ERROR_NONE |
| XML_ERROR_NO_MEMORY |
| XML_ERROR_SYNTAX |
| XML_ERROR_NO_ELEMENTS |
| XML_ERROR_INVALID_TOKEN |
| XML_ERROR_UNCLOSED_TOKEN |
| XML_ERROR_PARTIAL_CHAR |
| XML_ERROR_TAG_MISMATCH |
| XML_ERROR_DUPLICATE_ATTRIBUTE |
| XML_ERROR_JUNK_AFTER_DOC_ELEMENT |
| XML_ERROR_PARAM_ENTITY_REF |
| XML_ERROR_UNDEFINED_ENTITY |
| XML_ERROR_RECURSIVE_ENTITY_REF |
| XML_ERROR_ASYNC_ENTITY |
| XML_ERROR_BAD_CHAR_REF |
| XML_ERROR_BINARY_ENTITY_REF |
| XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF |
| XML_ERROR_MISPLACED_XML_PI |
| XML_ERROR_UNKNOWN_ENCODING |
| XML_ERROR_INCORRECT_ENCODING |
| XML_ERROR_UNCLOSED_CDATA_SECTION |
| XML_ERROR_EXTERNAL_ENTITY_HANDLING |
Codage des caractères
L'extension XML de PHP supporte les caractères Unicode grâce à différents codages. Il y a deux types de codages de caractères : le codage à la source et le codage à la cible. PHP utilise le UTF-8 comme représentation interne.
L'encodage à la source est effectué lors de l'analyse du fichier par XML. Lors de la création d'un analyseur XML), un type de codage à la source doit être spécifié (et il ne pourra plus être modifié jusqu'à la destruction de l'analyseur). Les codages supportés sont : ISO-8859-1, US-ASCII et UTF-8. Les deux derniers sont des codages à un seul octet, c'est-à-dire que les caractères sont représentés sur un seul octet. UTF-8 peut représenter des caractères composés par un nombre variable de bits (jusqu'à 21), allant de 1 à quatre octets. Le codage par défaut utilisé par PHP ISO-8859-1.
Le codage à la cible est effectué lorsque PHP transfert les données aux gestionnaires XML. Lorsqu'un analyseur est créé, le codage à la cible est spécifié de la même façon que le codage à la source, mais il peut être modifié à tout moment. Le codage à la cible affectera les balises, tout comme les données brutes, et les noms des instructions exécutables.
Si l'analyseur XML rencontre un caractère qu'il ne connaît pas (hors limite, par exemple), il retournera une erreur.
Si PHP rencontre un caractère dans le document XML analysé, qu'il ne peut pas représenter dans le codage à la cible choisi, le caractère sera remplacé par un point d'interrogation (cette attitude est susceptible de changer ultérieurement).
Quelques exemples
Voici une liste d'exemple de code PHP qui analyse un document XML.
Exemple de structure XML
Ce premier exemple affiche la structure de l'élément de début dans un document avec indentation.
Exemple 1. Afficher une structure XML
|
XML Transtypage XML -> HTML
Exemple 2. XML Transtypage XML -> HTML Cet exemple remplace les balises XML d'un document par des balises HTML. Les éléments inconnus seront ignorés. Bien entendu, cet exemple sera appliqué à un type précis de fichiers XML.
|
XML Entité externe
Cet exemple exploite les références externes de XML : il est possible d'utiliser un gestionnaire d'entité externe pour inclure et analyser les documents, tous comme les instructions exécutables peuvent servir à inclure et analyser d'autres documents, et aussi fournir une indication de confiance (voir plus bas).
Le document XML qui est utilisé dans cet exemple est fourni plus loin dans l'exemple (xmltest.xml et xmltest2.xml).
Exemple 3. Entité externe
|
Exemple 4. xmltest.xml
|
Ce fichier est inclus depuis xmltest.xml:
- Table des matières
- utf8_decode -- Convertit une chaîne UTF-8 en ISO-8859.
- utf8_encode -- Convertit une chaîne ISO-8859-1 en UTF-8.
- xml_error_string -- Lit le message d'erreur de l'analyseur XML.
- xml_get_current_byte_index -- Retourne l'index de l'octet courant d'un analyseur XML.
- xml_get_current_column_number -- Retourne le nombre courant de colonne d'un analyseur XML.
- xml_get_current_line_number -- Retourne le numéro de ligne courant d'un analyseur XML.
- xml_get_error_code -- Retourne le nombre courant de colonne d'un analyseur XML.
- xml_parse_into_struct -- Analyse une structure XML
- xml_parse -- Commence l'analyse d'un fichier XML.
- xml_parser_create_ns -- Create an XML parser
- xml_parser_create -- Création d'un analyseur XML.
- xml_parser_free -- Détruit un analyseur XML.
- xml_parser_get_option -- Lit les options d'un analyseur XML.
- xml_parser_set_option -- Affecte les options d'un analyseur XML.
- xml_set_character_data_handler -- Affecte les gestionnaires de caractère bruts.
- xml_set_default_handler -- Affecte le gestionnaire par défaut.
- xml_set_element_handler -- Affecte les gestionnaires de début et de fin.
- xml_set_end_namespace_decl_handler -- Set up character data handler
- xml_set_external_entity_ref_handler -- Modifie le gestionnaire de référence externes.
- xml_set_notation_decl_handler -- Affecte les gestionnaires de notation.
- xml_set_object -- Utilise un analyseur XML à l'intérieur d'un objet.
- xml_set_processing_instruction_handler -- Affecte les gestionnaires d'instructions exécutables.
- xml_set_start_namespace_decl_handler -- Set up character data handler
- xml_set_unparsed_entity_decl_handler -- Affecte les gestionnaires d'entité non déclaré.
utf8_decode
Description
string utf8_decode ( string data)utf8_decode() décode la chaîne data, en supposant qu'elle est au format UTF-8, et la convertit au format ISO-8859-1.
Voir aussi utf8_encode()pour plus de détails sur le codage UTF-8.
utf8_encode
Description
string utf8_encode ( string data)utf8_encode() code la chaîne data au format UTF-8, et retourne la version codée. UTF-8 est un mécanisme standardisé utilisé par Unicode pour coder les caractère de grande taille dans des flots d'octets. UTF-8 est transparent pour les caractères ASCII, il est auto-synchronisé (c'est à dire qu'un programme peut toujours savoir dans un flot d'octet où un caractère commence), et peut être utilisé pour faire des comparaisons de chaînes standard, comme pour le tri. PHP utilise l'UTF-8 pour coder les caractères jusqu'à 4 octets comme ceci :
Chaque b représente un bit qui peut être utilisé pour enregistrer un caractère.xml_error_string
Description
string xml_error_string ( int code)
- code
Un message d'erreur, issu de xml_get_error_code().
xml_error_string() retourne la chaîne avec un message textuel, décrivant l'erreur code, ou FALSE si aucune description n'a été trouvée.
xml_get_current_byte_index
(PHP 3>= 3.0.6, PHP 4 )
xml_get_current_byte_index -- Retourne l'index de l'octet courant d'un analyseur XML.Description
int xml_get_current_byte_index ( resource parser)
- parser
Une référence sur un analyseur XML valide.
xml_get_current_byte_index() retourne FALSE si parser n'est pas valide, ou sinon, retourne l'index de l'octet d'analyse courante de l'analyseur XML.
xml_get_current_column_number
(PHP 3>= 3.0.6, PHP 4 )
xml_get_current_column_number -- Retourne le nombre courant de colonne d'un analyseur XML.Description
int xml_get_current_column_number ( resource parser)
- parser
Une référence sur un analyseur XML valide.
xml_get_current_column_number() retourne FALSE si parser n'est pas valide, ou sinon, retourne le numéro de colonne courante de la ligne courante de l'analyseur, qui correspond à la position d'analyse courante de l'analyseur XML.
xml_get_current_line_number
(PHP 3>= 3.0.6, PHP 4 )
xml_get_current_line_number -- Retourne le numéro de ligne courant d'un analyseur XML.Description
int xml_get_current_line_number ( resource parser)
- parser
Une référence sur un analyseur XML valide.
xml_get_current_line_number() retourne FALSE si parser n'est pas valide, ou sinon, retourne le numéro de la ligne en cours d'analyse.
xml_get_error_code
(PHP 3>= 3.0.6, PHP 4 )
xml_get_error_code -- Retourne le nombre courant de colonne d'un analyseur XML.Description
int xml_get_error_code ( resource parser)xml_get_error_code() retourne FALSE si parser n'est pas valide, ou sinon, retourne le numéro de colonne courante de la ligne courante de l'analyseur, qui correspond à la position d'analyse courante de l'analyseur XML.
xml_parse_into_struct
Description
int xml_parse_into_struct ( resource parser, string data, array &values, array &index)xml_parse_into_struct() analyse le fichier XML data, et le place dans deux tableaux : le premier index contient des pointeurs sur la position des valeurs correspondantes dans le tableau values array. Ces deux paramètres sont passés par références.
Ci-dessous, vous trouverez un exemple qui illustre la structure des deux tableaux générés par la fonction. On utilise une balise simple note, placée dans une autre balise para. On analyse le tout, et on affiche la structure générée :
<?php $simple = "<para><note>simple note</note></para>"; $p = xml_parser_create(); xml_parse_into_struct($p,$simple,$vals,$index); xml_parser_free($p); echo "Tableau d'index\n"; print_r($index); echo "\nTableau de valeurs\n"; print_r($vals); ?> |
Tableau d'index
Array
(
[PARA] => Array
(
[0] => 0
[1] => 2
)
[NOTE] => Array
(
[0] => 1
)
)
Tableau de valeurs
Array
(
[0] => Array
(
[tag] => PARA
[type] => open
[level] => 1
)
[1] => Array
(
[tag] => NOTE
[type] => complete
[level] => 2
[value] => simple note
)
[2] => Array
(
[tag] => PARA
[type] => close
[level] => 1
)
)
L'analyse événementielle (comme celle de expat), peut se révéler complexe lorsque le document XML est complexe. xml_parse_into_struct() ne génère pas d'objet de type DOM, mais il génère plutôt des structures qui peuvent être parcourues à la façon d'un arbre. Considérons le fichier suivant, qui représente une petite base de données XML :
Exemple 1. moldb.xml - Petite base de données moléculaire
|
Exemple 2. parsemoldb.php - analyse moldb.xml et crée un tableau d'objet moléculaires
|
xml_parse
Description
int xml_parse ( resource parser, string data [, int isFinal])
- parser
une référence sur l'analyseur XML à utiliser.
- data
Une partie des données à analyser. Un document peut être analysé morceau par morceau, en appelant xml_parse() plusieurs fois, tant que le paramètre isFinal est mis à TRUE pour le dernier morceau.
- isFinal (optional)
S'il vaut TRUE, data est la dernière partie à analyser.
Lorsqu'un document XML est analysé, les gestionnaires d'événements sont appelés aussi souvent que nécessaire, et retournent TRUE ou FALSE.
TRUE est retourné lorsque l'analyse a été concluante, et FALSE en cas d'échec, ou si parser n'est pas un analyseur valide. Lors d'un échec d'analyse, la cause de l'erreur peut être obtenue grâce aux fonctions xml_get_error_code(), xml_error_string(), xml_get_current_line_number(), xml_get_current_column_number() et xml_get_current_byte_index().
xml_parser_create_ns
Description
resource xml_parser_create_ns ( [string encoding [, string sep]])
| Avertissement |
This function is currently not documented, only the argument list is available. |
xml_parser_create
Description
resource xml_parser_create ( [string encoding])
- encoding (optional)
Le codage de caractère de l'analyseur : les codages suivants sont supportés :
ISO-8859-1 (par défaut) US-ASCII UTF-8
xml_parser_free
Description
boolean xml_parser_free ( resource parser)
- parser
Une référence sur un analyseur XML.
xml_parser_free() retourne FALSE si parser n'est pas une référence valide, ou sinon, détruit l'analyseur et retourne TRUE.
xml_parser_get_option
Description
mixed xml_parser_get_option ( resource parser, int option)
- parser
Une référence sur un analyseur XML valide.
- option
L'option demandée. Reportez-vous à xml_parser_set_option() pour avoir la liste des options disponibles.
xml_parser_get_option() retourne FALSE si parser n'est pas valide, ou sinon, retourne la valeur de l'option demandée.
Reportez-vous à xml_parser_set_option() pour avoir la liste des options disponibles.
xml_parser_set_option
Description
int xml_parser_set_option ( resource parser, int option, mixed value)
- parser
Une référence vers un analyseur XML.
- option
L'option à modifier. Voir ci-dessous :
- value
La nouvelle valeur de l'option.
xml_parser_set_option() retourne FALSE si parser n'est pas une référence valide sur un analyseur XML, ou si l'option n'a pas pu être modifiée. Sinon, l'option est effectivement modifiée, et la fonction retourne TRUE.
Les options suivantes sont disponibles :
Tableau 1. options d'analyseur XML
| Option | Type de données | Description |
|---|---|---|
| XML_OPTION_CASE_FOLDING | entier | Contrôle la gestion de la casse des balises de cet analyseur XML. Par défaut, activé. |
| XML_OPTION_TARGET_ENCODING | string | Modifie le codage à la cible utilisé par cet analyseur XML. Par défaut, c'est celui qui a été spécifié lors de l'appel de xml_parser_create(). Les codages supportés sont ISO-8859-1, US-ASCII et UTF-8. |
xml_set_character_data_handler
(PHP 3>= 3.0.6, PHP 4 )
xml_set_character_data_handler -- Affecte les gestionnaires de caractère bruts.Description
int xml_set_character_data_handler ( resource parser, string handler)Affecte les gestionnaires de début et de fin de l'analyseur XML parser. handler est une chaîne qui contient le nom d'une fonction qui existe lorsque xml_parse() est appelé pour créer parser.
La fonction handler doit accepter deux paramètres:
handler ( resource parser, string data)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- data
Le second paramètre, data, contient les caractères sous la forme d'une chaîne.
Si un gestionnaire reçoit une chaîne vide ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_character_data_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon, ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_default_handler
Description
int xml_set_default_handler ( resource parser, string handler)Affecte le gestionnaire par défaut de l'analyseur XML parser. handler est une chaîne qui contient le nom d'une fonction qui existe lorsque xml_parse() est appelé pour créer parser.
La fonction handler doit accepter deux paramètres:
handler ( resource parser, string data)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- data
Le second paramètre, data, contient les caractères sous la forme d'une chaîne. Cela peut être une déclaration XML, un type de document, une entité ou d'autre données pour qui aucun gestionnaire n'est prévu.
Si un gestionnaire reçoit une chaîne vide ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_default_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon, ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_element_handler
Description
int xml_set_element_handler ( resource parser, string startElementHandler, string endElementHandler)xml_set_element_handler() affecte les gestionnaires de début et de fin de l'analyseur XML parser. startElementHandler et endElementHandler sont des chaînes qui contiennent les noms de fonctions qui existent lorsque xml_parse() est appelé pour créer parser.
La fonction startElementHandler doit
accepter trois paramètres:
startElementHandler ( resource parser, string name, array attribs)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- name
Le deuxième paramètre, name, contient le nom de l'élément qui a provoqué l'appel du gestionnaire. Si l'analyseur gère la casse, cet élément sera en majuscule.
- attribs
Le troisième paramètre, attribs, contient un tableau associatif avec les attributs de l'éléments (s'il en existe). Les clés de ce tableau seront les noms des attributs, et les valeurs seront les valeurs correspondantes des attributs. Les noms des attributs seront mis en majuscule si l'analyseur gère la casse. Les valeurs des attributs seront intouchées.
L'ordre original des attributs peut être retrouvé en passant en revue le tableau attribs, avec la fonction each(). La première clé sera la première clé du tableau.
La fonction endElementHandler doit accepter deux
paramètres:
endElementHandler ( resource parser, string name)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- name
Le second paramètre, name, contient le nom de l'élément qui a provoqué l'appel du gestionnaire. Si l'analyseur gère la casse, cet élément sera en majuscule.
Si un gestionnaire reçoit une chaîne vide, ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_element_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon, ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_end_namespace_decl_handler
Description
bool xml_set_end_namespace_decl_handler ( resource pind, string hdl)
| Avertissement |
This function is currently not documented, only the argument list is available. |
Note : Instead of a function name, an array containing an object reference and a method name can also be supplied.
xml_set_external_entity_ref_handler
(PHP 3>= 3.0.6, PHP 4 )
xml_set_external_entity_ref_handler -- Modifie le gestionnaire de référence externes.Description
int xml_set_external_entity_ref_handler ( resource parser, string handler)Fixe le gestionnaire d'entité externe de l'analyseur XML parser. handler et endElementHandler sont des chaînes qui contiennent les noms de fonction qui existent lorsque xml_parse() est appelé pour créer le parser.
La fonction handler doit accepter 5
paramètres, et retourner un entier. Si la valeur retourné par
le gestionnaire est FALSE (comme par exemple si aucune valeur n'est
retournée), l'analyseur XML s'arrêtera, et la fonction
xml_get_error_code() retournera
XML_ERROR_EXTERNAL_ENTITY_HANDLING.
int handler ( resource parser, string openEntityNames, string base, string systemId, string publicId)
- parser
Le premier paramètre,parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- openEntityNames
Le deuxième paramètre, openEntityNames, est la liste de noms d'entité, séparés par des espaces. Ces entités sont accessibles à l'analyse par cet entité (y compris le nom de l'entité reférencé).
- base
La meilleure base de résolution de l'identifiant système de cet entité externe. Actuellement, ce paramètre est toujours une chaîne vide.
- systemId
Identifiant système pour cet entité externe.
- publicId
Le cinquième paramètre, publicId, est l'identifiant public, comme spécifié dans la déclaration d'entité, ou un chaîne vide, si aucune déclaration n'a été spécifiée. L'espace dans l'identifiant public sera normalisé comme spécifié dans les spécifications XML.
Si un gestionnaire reçoit une chaîne vide, ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_external_entity_ref_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_notation_decl_handler
Description
int xml_set_notation_decl_handler ( resource parser, string handler)Affecte les gestionnaires de début et de fin de l'analyseur XML parser. handler est une chaîne qui contient le nom d'une fonction qui existe lorsque xml_parse() est appelé pour créer parser.
Une notation est une partie du DTD du document, qui a le format suivant :
<!NOTATION name
{ systemId | publicId?> |
La fonction handler doit accepter cinq
paramètres:
handler ( resource parser, string notationName, string base, string systemId, string publicId)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- notationName
Le nom de la notation,name, comme précisé dans le format de notation ci-dessus.
- base
La meilleure base de résolution de l'identifiant système de cette entité externe. Actuellement, ce paramètre est toujours une chaîne vide.
- systemId
Identifiant système pour cet entité externe.
- publicId
Identifiant public pour cet entité externe.
Si un gestionnaire reçoit une chaîne vide ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_notation_decl_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaires. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_object
Description
void xml_set_object ( resource parser, object &object)xml_set_object() rend l'analyseur parser utilisable depuis un objet. Toutes les méthodes de callback, affectées par xml_set_element_handler(), seront les méthodes de cet objet.
<?php
class xml {
var $parser;
function xml() {
$this->parser = xml_parser_create();
xml_set_object($this->parser,&$this);
xml_set_element_handler($this->parser,"tag_open","tag_close");
xml_set_character_data_handler($this->parser,"cdata");
}
function parse($data) {
xml_parse($this->parser,$data);
}
function tag_open($parser,$tag,$attributes) {
var_dump($parser,$tag,$attributes);
}
function cdata($parser,$cdata) {
var_dump($parser,$cdata);
}
function tag_close($parser,$tag) {
var_dump($parser,$tag);
}
} // Fin de la classe xml
$xml_parser = new xml();
$xml_parser->parse("<A ID=\"bonjour\">PHP</?>");
?> |
xml_set_processing_instruction_handler
(PHP 3>= 3.0.6, PHP 4 )
xml_set_processing_instruction_handler -- Affecte les gestionnaires d'instructions exécutables.Description
int xml_set_processing_instruction_handler ( resource parser, string handler)Affecte les gestionnaires d'instructions exécutables de l'analyseur XML parser. handler est une chaîne qui contient le nom d'une fonction qui existe lorsque xml_parse() est appelé pour créer parser.
Une instruction exécutable a la forme suivante :
Vous pouvez mettre du code PHP entre ces balises, mais soyez conscient d'une des limitations des instructions exécutables de XML : la balise de fin d'instruction exécutable (?>) ne peut être échappée, ce qui fait que cette séquence NE DOIT JAMAIS apparaître dans le code PHP placé dans le document PHP. Si un tel texte apparaît, la balise de fin d'instruction exécutable sera reconnue, et le reste du code sera considéré comme des données brutes (et donc, pas exécutées).
La fonction handler doit accepter trois paramètres:
handler ( resource parser, string target, string data)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- target
Le second paramètre, target, contient l'application cible.
- data
Le troisième paramètre, data, contient le code sous la forme d'une chaîne.
Si un gestionnaire reçoit une chaîne vide, ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_processing_instruction_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon, ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
xml_set_start_namespace_decl_handler
Description
bool xml_set_start_namespace_decl_handler ( resource pind, string hdl)
| Avertissement |
This function is currently not documented, only the argument list is available. |
Note : Instead of a function name, an array containing an object reference and a method name can also be supplied.
xml_set_unparsed_entity_decl_handler
(PHP 3>= 3.0.6, PHP 4 )
xml_set_unparsed_entity_decl_handler -- Affecte les gestionnaires d'entité non déclaré.Description
int xml_set_unparsed_entity_decl_handler ( resource parser, string handler)Affecte les gestionnaires d'entité non déclaré de l'analyseur XML parser. handler est une chaîne qui contient le nom d'une fonction qui existe lorsque xml_parse() est appelé pour créer parser.
Ce gestionnaire sera appelé si l'analyseur XML rencontre une déclaration d'entité externe avec une déclaration de NDATA, comme suit :
<!ENTITY name {publicId | systemId}
NDATA notationName |
Reportez-vous à la section des spécifications XML 1.0 pour connaître les notations des entités externes.
La fonction handler doit accepter six paramètres:
handler ( resource parser, string entityName, string base, string systemId, string publicId, string notationName)
- parser
Le premier paramètre, parser, est une référence sur l'analyseur XML qui appelle cette fonction.
- entityName
Le nom de l'entité qui va être définie
- base
La meilleure base de résolution de l'identifiant système de cette entité externe. Actuellement, ce paramètre est toujours une chaîne vide.
- systemId
Identifiant système pour cet entité externe.
- publicId
Identifiant public pour cet entité externe.
- notationName
Nom de la notation de cette entité. (Voir xml_set_notation_decl_handler()).
Si un gestionnaire reçoit une chaîne vide ou FALSE, c'est qu'il est en train d'être désactivé.
xml_set_unparsed_entity_decl_handler() retourne TRUE si le gestionnaire est actif, et FALSE sinon, ou si parser n'est pas un analyseur.
Il n'est pas pour l'instant possible d'utiliser des objets pour servir de gestionnaire. Reportez-vous à xml_set_object() pour utiliser l'analyseur XML depuis un objet.
CVI. XMLRPC
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
- Table des matières
- xmlrpc_decode_request -- Décode le code XML en variables PHP natives
- xmlrpc_decode -- Décode le code XML en types PHP natifs
- xmlrpc_encode_request -- Génère le code XML d'une requête de méthode
- xmlrpc_encode -- Génère le code XML pour une valeur PHP
- xmlrpc_get_type -- Retourne le type XMLRPC d'une valeur PHP. Particulièrement pratique pour les types chaînes de type base64 et datetime
- xmlrpc_parse_method_descriptions -- Décode le code XML en une liste de descriptions de méthodes
- xmlrpc_server_add_introspection_data -- Ajoute des données d'introspection
- xmlrpc_server_call_method -- Analyse une requête XML est appelle les méthodes associées
- xmlrpc_server_create -- Crée un serveur XMLRPC
- xmlrpc_server_destroy -- Détruit un serveur XMLRPC
- xmlrpc_server_register_introspection_callback -- Enregsitre une fonction PHP pour générer la documentation
- xmlrpc_server_register_method -- Enregistre une fonction PHP avec une méthode
- xmlrpc_set_type -- Modifie le type XMLRPC, base64 ou datetime, pour une chaînes de caractères PHP
xmlrpc_decode_request
Description
array xmlrpc_decode_request ( string xml, string method [, string encoding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_decode
Description
array xmlrpc_decode ( string xml [, string encoding])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_encode_request
Description
string xmlrpc_encode_request ( string method, mixed params)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_encode
Description
string xmlrpc_encode ( mixed value)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_get_type
(PHP 4 >= 4.1.0)
xmlrpc_get_type -- Retourne le type XMLRPC d'une valeur PHP. Particulièrement pratique pour les types chaînes de type base64 et datetimeDescription
string xmlrpc_get_type ( mixed value)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_parse_method_descriptions
(PHP 4 >= 4.1.0)
xmlrpc_parse_method_descriptions -- Décode le code XML en une liste de descriptions de méthodesDescription
array xmlrpc_parse_method_descriptions ( string xml)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_add_introspection_data
Description
int xmlrpc_server_add_introspection_data ( resource server, array desc)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_call_method
(PHP 4 >= 4.1.0)
xmlrpc_server_call_method -- Analyse une requête XML est appelle les méthodes associéesDescription
mixed xmlrpc_server_call_method ( resource server, string xml, mixed user_data [, array output_options])| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_create
Description
resource xmlrpc_server_create ( void)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_destroy
Description
void xmlrpc_server_destroy ( resource server)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_register_introspection_callback
(PHP 4 >= 4.1.0)
xmlrpc_server_register_introspection_callback -- Enregsitre une fonction PHP pour générer la documentationDescription
bool xmlrpc_server_register_introspection_callback ( resource server, string function)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_server_register_method
Description
bool xmlrpc_server_register_method ( resource server, string method_name, string function)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
xmlrpc_set_type
(PHP 4 >= 4.1.0)
xmlrpc_set_type -- Modifie le type XMLRPC, base64 ou datetime, pour une chaînes de caractères PHPDescription
bool xmlrpc_set_type ( string value, string type)| Avertissement |
Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez cette fonction à vos risques et périls. |
| Avertissement |
This function is currently not documented, only the argument list is available. |
CVII. XSLT
| Avertissement |
Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utiliser ce module à vos risques et périls. |
Introduction
A propos de XSLT et Sablotron
XSLT (Extensible Stylesheet Language (XSL) Transformations) est un langage de transformation des documents XML en d'autres documents XML. C'est un standard défini par le consortium World Wide Web (W3C). Les informations sur le XLST et ses technologies sont disponibles à http://www.w3.org/TR/xslt.
Installation
Cette extension utilise Sablotron et expat, qui sont toutes les deux disponibles à http://www.gingerall.com/. Les sources comme les exécutables sont proposés.
Sous UNIX, lancez configure avec l'option --with-sablot. La librairie Sablotron doit être installée là où le compilateur peut la trouver.
A propos de Sablotron
Cette extension PHP implémente le support de Sablotron, par Ginger Alliance. Cette librairie vous permet de transformer des documents XML en d'autres documents XML, mais aussi en HTML ou encore n'importe quel format à balise. Elle fournit un mécanisme basique et portable de templates, séparant le contenu de l'interface d'un site web.
- Table des matières
- xslt_create -- Crée un nouvel analyseur XSLT.
- xslt_errno -- Retourne le numéro d'erreur courant
- xslt_error -- Retourne le message d'erreur courant
- xslt_free -- Détruit un analyseur XSLT
- xslt_process -- Transforme des données XML
- xslt_set_base -- Set the base URI for all XSLT transformations
- xslt_set_encoding -- Set the encoding for the parsing of XML documents
- xslt_set_error_handler -- Set an error handler for a XSLT processor
- xslt_set_log -- Set the log file to write log messages to
- xslt_set_sax_handler -- Modifie les gestionnaires SAX de l'analyseur XSLT
- xslt_set_sax_handlers -- Set the SAX handlers to be called when the XML document gets processed
- xslt_set_scheme_handler -- Set Scheme handlers for a XSLT processor
- xslt_set_scheme_handlers -- Set the scheme handlers for the XSLT processor
xslt_create
Description
resource xslt_create ( void)xslt_create() retourne un identifiant d'analyseur XSLT. Il sera nécessaire pour les appels ultérieurs aux fonctions.
xslt_errno
Description
int xslt_errno ( [resource xh])xslt_errno() le numéro courant d'erreur, pour l'analyseur xh. Si xh n'est pas fourni, le dernier numéro d'erreur est retourné.
xslt_error
Description
mixed xslt_error ( [resource xh])xslt_errno() le message d'erreur courant, pour l'analyseur xh. Si xh n'est pas fourni, le dernier numéro d'erreur est retourné.
xslt_free
xslt_process
Description
boolean xslt_process ( string xsl_data, string xml_data, string result)xslt_process() prend la chaîne string xsl_data comme feuille de style XSLT, et des données XML dans xml_data. Le résultat de la transformation sera placé dans result. xslt_process() retourne TRUE en cas de succès, et FALSE sinon. Vous pourrez lire les erreurs survenues grâce aux fonctions xslt_errno() et xslt_error().
Exemple 1. Utilisation de xslt_process() pour transformer trois
|
xslt_set_base
Description
void xslt_set_base ( resource xh, string uri)Sets the base URI for all XSLT transformations, the base URI is used with Xpath instructions to resolve document() and other commands which access external resources.
xslt_set_encoding
Description
void xslt_set_encoding ( resource xh, string encoding)Set the output encoding for the XSLT transformations. When using the Sablotron backend this option is only available when you compile Sablotron with encoding support.
xslt_set_error_handler
Description
void xslt_set_error_handler ( resource xh, mixed handler)Set an error handler function for the XSLT processor given by xh, this function will be called whenever an error occurs in the XSLT transformation (this function is also called for notices).
xslt_set_log
Description
void xslt_set_log ( resource xh, mixed log)
- xh
A reference to the XSLT parser.
- log
This parameter is either a boolean value which toggles logging on and off, or a string containing the logfile in which log errors too.
This function allows you to set the file in which you want XSLT log messages to, XSLT log messages are different than error messages, in that log messages are not actually error messages but rather messages related to the state of the XSLT processor. They are useful for debugging XSLT, when something goes wrong.
By default logging is disabled, in order to enable logging you must first call xslt_set_log() with a boolean parameter which enables logging, then if you want to set the log file to debug to, you must then pass it a string containing the filename:
xslt_set_sax_handler
Description
boolean xslt_set_sax_handler ( resource xh, array handlers)xslt_set_sax_handler() remplace les gestionnaires SAX de l'analyseur XSLT xh par handlers.
xslt_set_sax_handlers
(PHP 4 >= 4.0.6)
xslt_set_sax_handlers -- Set the SAX handlers to be called when the XML document gets processedDescription
void xslt_set_sax_handlers ( resource processor, array handlers)
| Avertissement |
This function is currently not documented, only the argument list is available. |
xslt_set_scheme_handler
Description
void xslt_set_scheme_handler ( resource xh, array handlers)Set Scheme handlers on the resource handle given by xh. Scheme handlers should be an array with the format (all elements are optional):
xslt_set_scheme_handlers
CVIII. YAZ
Introduction
Cette extension offre à PHP l'interface avec les produits YAZ, qui implémentent le protocole Z39.50. Avec cette extension, vous pouvez facilement implémenter un client Z39.50 qui analyse ou scanne des serveurs Z39.50 en paralléle.
YAZ est disponible à http://www.indexdata.dk/yaz/. Vous pouvez trouvez des informations, des scripts d'exemples, etc... pour cette extension à http://www.indexdata.dk/phpyaz/.
Le module masque l'essentiel de la complexité de Z39.50, ce qui le rend très facile à utiliser. Il supporte les connexions peristantes de manière similaire à celle supportés par les serveurs SQL : cela signifie qu'une connexion est partagée entre plusieurs scripts PHP, ce qui évite les opérations de connexions.
Installation
Compilez YAZ et installez le. Compilez PHP avec vos modules et ajoutez l'option --with-yaz. Les instructions sont :
Exemple
PHP/YAZ conserve les connexions aux serveurs. Un entier positif représente l'ID d'une connexion particulière.
Le script ci-dessous montre comment effectuer une recherche paralléle. Lorsqu'il est appelé sans paramètre, ce script affiche la requête. Sinon, il effectue la recherche sur les serveurs.
Exemple 1. Recherche paralléle utilisant YAZ
|
- Table des matières
- yaz_addinfo -- Retourne plus de détails après une erreur
- yaz_ccl_conf -- Configure l'analyseur CCL
- yaz_ccl_parse -- Appelle l'analyseur CCL
- yaz_close -- Ferme une connexion YAZ
- yaz_connect -- Prépare une connexion à un hôte YAZ
- yaz_database -- Spécifie la base d'une session
- yaz_element -- Spécifie le type d'éléments à lire
- yaz_errno -- Retourne le numéro d'erreur
- yaz_error -- Retourne une description de l'erreur
- yaz_hits -- Retourne le nombre de résultat de la dernière recherche
- yaz_itemorder -- Prépare une requête Z39.50 Item Order avec le package ILL-Request
- yaz_present -- Prépare à la lecture (Z39.50 present).
- yaz_range -- Spécifie le nombre maximal de résultat à lire
- yaz_record -- Retourne un résultat
- yaz_scan_result -- Retourne le résultat d'un scan
- yaz_scan -- Prépare un scan
- yaz_search -- Prépares une recherche
- yaz_sort -- Sets sorting criteria
- yaz_syntax -- Spécifie la syntaxe de lecture des lignes
- yaz_wait -- Attend l'exécution d'une requête
yaz_addinfo
Description
int yaz_addinfo ( int id)yaz_addinfo() retourne plus de détails après la dernière erreur survenue. Une chaîne vide est retournée si la dernière opération a été réussie, ou bien si aucune autre information n'est disponible.
yaz_ccl_conf
Description
int yaz_ccl_conf ( int id, array config)yaz_ccl_conf() configure l'analyseur CCL de requete de l'hôte id, avec les définitions de points d'accès (CCL qualifiers) et leur équivalent en RPN. Pour cabler une requête spécifique vers un appel RPN, utilisez yaz_ccl_parse(). Chaque index du tableau config est un nom de champs CCL et la valeur correspondante contient une chaîne spécifiant le code RPN. Ce code est une séquence de paires "attribut-type, attribute-value". Les "attribut-type" et "attribut-value" sont séparé par le signe égal (=). Chaque paire est séparé par un espace ("=").
Exemple 1. Exemple de configuration CCL Dans l'exemple ci-dessous, l'analyseur CCL est configuré pour supporter trois champs CCL : ti, au et isbn. Chaque champs correspond à leur équivalent équivalent BIB-1. On suppose que chaque variable $id est un hôte de destination.
|
yaz_ccl_parse
Description
int yaz_ccl_parse ( int id, string query, array & result)yaz_ccl_parse() appelle l'analyseyr CCL. Il convertit une requête CCL FIND en une requête RPN qui peut être passée à yaz_search() pour effectuer une recherche. Pour définir un champs CCL valide, utilisez la fonction yaz_ccl_conf() avant celle-ci. Si la requête query a pu être convertie en RPN, yaz_ccl_parse() retourne TRUE, et l'index rpn du tableau result contient une requête RPN valide. Si la requête n'a pas pu être convertie, (pour n'importe quelle raison, comme syntaxe invalide, champs inconnu...), yaz_ccl_parse() retourne FALSE. Trois index sont alors créés dans le tableau de résultat : errorcode (code d'erreur CCL, un entier), errorstring (message d'erreur CCL), et errorpos position estimée de l'erreur dans la requête (entier, position en nombre de caractères).
yaz_close
Description
int yaz_close ( int id)yaz_close() ferme une connexion à un hôte YAZ. L'application ne pourra plus utiliser l'identifiant de connexion id. id est un identifiant d'hôte, retourné par yaz_connect().
yaz_connect
Description
int yaz_connect ( string zurl [, string authentication])yaz_connect() retourne un identifiant positif en cas de succès, et FALSE sinon.
yaz_connect() prépare une connexion à un serveur Z39.50. zurl est de la forme "host[:port][/database]". Si port est omis, 210 est utilisé. Si database est omis, default est utilisé. yaz_connect() n'est pas bloquante, et ne tente pas d'établir une socket. En fait, elle ne fait que préparer la connexion pour exécution ultérieure par yaz_wait().
yaz_database
Description
int yaz_database ( int id, string databases)yaz_database() spécifie databases, la ou les bases utilisées lors des recherches, lectures, etc, en remplaçant celles spécifiées lors de la fonction yaz_connect(). Pour indiquer plusieurs bases de données, séparez les noms par des +.
yaz_database() vous permet d'utiliser différents jeux de bases durant une session.
yaz_database() retourne TRUE en cas de succès, ou FALSE en cas d'erreur.
yaz_element
Description
int yaz_element ( int id, string elementset)yaz_element() est à utiliser en conjonction avec yaz_search() et yaz_present() pour spécifier le type d'éléments à lire. La majorité des serveurs supporte F (full, tous), et B (brief, bref).
yaz_element() retourne TRUE en cas de succès, et FALSE sinon.
yaz_errno
Description
int yaz_errno ( int id)yaz_errno() retourne le numéro d'erreur de la dernière requête. Une valeur positive est retournée si le serveur a retourné un diagnostic. La valeur 0 est retournée si aucune erreur n'est survenue. Une valeur négative indique une erreur sans diagnostic (connexion perdue,...).
yaz_errno() doit être appelée après chaque requête. (après la fin de yaz_wait()), pour savoir si la transaction a réussi ou échoué.
yaz_error
Description
string yaz_error ( int id)yaz_error() retourne un message d'erreur pour la dernière requête. Une chaîne vide est retournée si la dernière requête a réussi.
yaz_error() retourne un message en anglais, qui correspond au numéro d'erreur retourné par yaz_errno().
yaz_hits
Description
int yaz_hits ( int id)yaz_hits() retourne le nombre de résultat de la dernière recherche.
yaz_itemorder
Description
int yaz_itemorder ( array args)yaz_itemorder() prépare une requête de type "Extended Services" en utilisant le "Profile" avec "Use of Z39.50 Item Order Extended Service to Transport ILL (Profile/1)" (Note du Traducteur : mailez moi de l'aide!). Reportez-vous ici ou aux spécification. Le paramètre args doit être un tableau associatif, contenant les informations "Item Order" à envoyer. L'index du tableau est le nom ASN.1 correspondant au tag path. Par exemple, le numéro ISBN sous l'Item-ID est la clé item-id,ISBN.
Les paramètres de ILL-Request sont :
protocol-version-num
transaction-id,initial-requester-id,person-or-institution-symbol,person
transaction-id,initial-requester-id,person-or-institution-symbol,institution
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
transaction-id,transaction-group-qualifier
transaction-id,transaction-qualifier
transaction-id,sub-transaction-qualifier
service-date-time,this,date
service-date-time,this,time
service-date-time,original,date
service-date-time,original,time
requester-id,person-or-institution-symbol,person
requester-id,person-or-institution-symbol,institution
requester-id,name-of-person-or-institution,name-of-person
requester-id,name-of-person-or-institution,name-of-institution
responder-id,person-or-institution-symbol,person
responder-id,person-or-institution-symbol,institution
responder-id,name-of-person-or-institution,name-of-person
responder-id,name-of-person-or-institution,name-of-institution
transaction-type
delivery-address,postal-address,name-of-person-or-institution,name-of-person
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
delivery-address,postal-address,extended-postal-delivery-address
delivery-address,postal-address,street-and-number
delivery-address,postal-address,post-office-box
delivery-address,postal-address,city
delivery-address,postal-address,region
delivery-address,postal-address,country
delivery-address,postal-address,postal-code
delivery-address,electronic-address,telecom-service-identifier
delivery-address,electronic-address,telecom-service-addreess
billing-address,postal-address,name-of-person-or-institution,name-of-person
billing-address,postal-address,name-of-person-or-institution,name-of-institution
billing-address,postal-address,extended-postal-delivery-address
billing-address,postal-address,street-and-number
billing-address,postal-address,post-office-box
billing-address,postal-address,city
billing-address,postal-address,region
billing-address,postal-address,country
billing-address,postal-address,postal-code
billing-address,electronic-address,telecom-service-identifier
billing-address,electronic-address,telecom-service-addreess
ill-service-type
requester-optional-messages,can-send-RECEIVED
requester-optional-messages,can-send-RETURNED
requester-optional-messages,requester-SHIPPED
requester-optional-messages,requester-CHECKED-IN
search-type,level-of-service
search-type,need-before-date
search-type,expiry-date
search-type,expiry-flag
place-on-hold
client-id,client-name
client-id,client-status
client-id,client-identifier
item-id,item-type
item-id,call-number
item-id,author
item-id,title
item-id,sub-title
item-id,sponsoring-body
item-id,place-of-publication
item-id,publisher
item-id,series-title-number
item-id,volume-issue
item-id,edition
item-id,publication-date
item-id,publication-date-of-component
item-id,author-of-article
item-id,title-of-article
item-id,pagination
item-id,ISBN
item-id,ISSN
item-id,additional-no-letters
item-id,verification-reference-source
copyright-complicance
retry-flag
forward-flag
requester-note
forward-note
Il y a quelques paramètres du package Extended Services Request et ItemOrder :
package-name
user-id
contact-name
contact-phone
contact-email
itemorder-item
yaz_present
Description
int yaz_present ( void)yaz_present() prépare PHP à la lecture des résultats, après une recherche. yaz_range() doit être appelée avant celle-ci pour spécifier la plage de résultat à lire.
yaz_range
Description
int yaz_range ( int id, int start, int number)yaz_range() est utilisée conjointement à yaz_search(), pour spécifier le nombre maximal number de résultat à lire, ainsi que la position de début de lecture avec start. Si yaz_range() n'est pas utilisée, start vaudra 1 et number vaudra 10.
yaz_range() retourne TRUE en cas de succès; FALSE en cas d'erreur.
yaz_record
Description
int yaz_record ( int id, int pos, string type)yaz_record() retourne un résultatà la position pos, ou une chaîicirc;ne vide si aucun résultat n'est disponible à la position pos.
yaz_record() recherche une ligne dans le résultat, à la position spécifiée. Si aucune ligne n'existe à la position donnée, une chaîicirc;ne vide est retournée. L'argument type spécifie la forme du résultat retourné : si type vaut "string", la ligne est retournée sous la forme d'une chaîicirc;ne, prête à l'affichage. Si type vaut "array", la ligne sera retournée sous la forme d'un tableau structuré.
yaz_scan_result
Description
array yaz_scan_result ( int id [, array & result])yaz_scan_result() retourne un tableau contenant les termes recu de l'hôte id, lors de la dernière requête de scan. Le tableau commence à l'index 0. Chaque valeur est une paire, où le premier élément est le terme, et le second est un compte de résultat. Si result est fourni, il sera rempli avec les informations générales de la requête de scan : number (numbre d'entrée retournées), stepsize (taille du pas), position (position du terme), status (Statut du Scan).
yaz_scan
Description
int yaz_scan ( int id, string type, string startterm [, array flags])yaz_scan() prépare une requête "Z39.50 Scan Request". id spécifie l'hôte cible. Le point de départ est donné avec startterm. La forme de spécification du point de départ est donné par type. Actuellement, le type rpn est supporté. Le paramètre optionnel flags donne des informations supplémentaires pour contrôler le comportement de la requête de scan. Actuellement, trois index sont lus dans ce paramètre : number (nombre de termes requis), position (position préférée du terme) et stepSize (taille du pas préférée). Pour reéllement envoyer la requête de recherche à l'hôte, et recevoir la réponse, yaz_wait() doit être appelée. A la fin de yaz_wait(), yaz_error() et yaz_scan_result() auront les résultats.
La syntaxe de startterm est similaire aux requêtes RPN, décrites dans yaz_search(). startterm est constitué de zéro ou plus spécifications, avec les opérateurs @attr, suivi par exactement un token.
Exemple 1. Fonction PHP qui scanne les titres
|
yaz_search
Description
int yaz_search ( int id, string type, string query)yaz_search() prépare une recherche sur le serveur identifié par id. type représente le type de requête : seul RPN est supporté actuellement, et dans ce cas, le troisième argument est un préfixe de notation de requête utilisé par YAZ. Comme pour yaz_connect(), yaz_search() n'est pas bloquante, et ne fait que préparer la recherche pour exécution ultérieure, avec yaz_wait().
Requêtes RPN
Les requêtes RPN sont des représentation textuelles des requêtes de type Type-1, comme définit dans le standard Z39.50. Cependant, dans la représentation textuelle utilisée par YAZ, une notation à préfixage est utilisée, c'est-à-dire que l'opérateur précédent l'opérande. La chaîne de requête est une séquence de mots réservés, où les espaces sont ignorés, à moins qu'ils n'ai été mis entre guillemets doubles. Les mots réservés qui commencent par un arobase (@) sont considérés comme des opérateurs et traités comme tels.
Tableau 1. Opérateurs RPN
| Syntaxe | Description |
|---|---|
| @and query1 query2 | intersection des requêtes query1 et query2 |
| @or query1 query2 | union des requêtes query1 et query2 |
| @not query1 query2 | requêtes "query1 et non(query2)" |
| @set name | nomme le résultat |
| @attrset set query | spécifie le jeu d'attributs de la requête. Cette construction n'est autorisée qu'une seule fois, au début d'une requête. |
| @attr set type=value query | Applique les attributs à une requête. Le type et la valeur sont des entiers indiquant les types et valeurs des attributs, dans cet ordre. Le jeu, si fourni, spécifie le jeu d'attribut utilisé. |
Les requêtes suivantes illustrent des requêtes valides :
Recherche les documents qui contiennent le mot "ordinateur". Aucun attribut n'est spécifié.Recherche les documents qui contiennent les mots "serveur rapide"
L'attribut est de type 1 (Bib-1 use), sa valeur est 4 (Title, titre) : cette requête recherche les documents où le mot "php" est dans le titre.
Cette requête utilise tout le jeu d'attributs GILS. Elle recherche les documents dont le titre contient "php", et qui contiennent le nom "Rasmus Lerdorf" comme auteur.
yaz_sort
Description
int yaz_sort ( int id, string criteria)This function sets sorting criteria and enables Z39.50 Sort. Use this function together with yaz_search() or yaz_present(). Using this function alone doesn't have any effect. If used in conjunction with yaz_search() a Z39.50 Sort will be sent after a search response has been received and before any records are retrieved with Z39.50 Present. The criteria takes the form
field1 flags1 field2 flags2 ...
where field1 specifies primary attributes for sort, field2 seconds, etc.. The field specifies either numerical attribute combinations consisting of type=value pairs separated by comma (e.g. 1=4,2=1) ; or the field may specify a plain string criteria (e.g. title. The flags is a sequnce of the following characters which may not be separated by any white space.
Sort Flags
- a
Sort ascending
- d
Sort descending
- i
Case insensitive sorting
- s
Case sensitive sorting
yaz_syntax
Description
int yaz_syntax ( int id, string syntax)yaz_syntax() est utilisée conjointement avec yaz_search() pour spécifier la méthode de lecture des lignes. La syntaxe est spécifiée comme un OID (Identifiant d'Objet), en notation brute, séparée par des points (i.e. 1.2.840.10003.5.10), ou bien avec une des valeurs prédéfinies : sutrs, usmarc, grs1, xml, etc... yaz_syntax() doit être utilisée en conjonction avec yaz_search() et yaz_present() pour spécifier la méthode de lecture des résultats.
yaz_wait
Description
int yaz_wait ( void)yaz_wait() exécute les requêtes préparée par les fonctions yaz_search(), yaz_present(), yaz_scan() et yaz_itemorder(). yaz_wait() se termine lorsque tous les hôtes ont terminé leurs requêtes (éventuellement en cas d'erreur).
CIX. NIS
NIS (feu Yellow Pages / Pages jaunes) permet la gestion par le réseau de fichiers d'administration importants (tel un fichier de mot de passe). Pour plus d'informations, reportez vous au manuel NIS, ou à Introduction to YP/NISIntroduction to YP/NIS (en anglais). Il existe un livre en anglais Managing NFS and NIS" par Hal Stern.
Pour ajouter ces fonctionnalitées, vous devez compiler PHP avec l'option --with-yp (PHP 3) ou --enable-yp (PHP 4).
- Table des matières
- yp_all -- Traverse the map and call a function on each entry
- yp_cat -- Return an array containing the entire map
- yp_err_string -- Retourne la chaîne d'erreur associée à la dernière opération.
- yp_errno -- Retourne le code d'erreur de la dernière opération.
- yp_first -- Retourne le premier couple (clé ; valeur) d'une carte donnée.
- yp_get_default_domain -- Retourne le domaine NIS par défaut.
- yp_master -- Retourne le nom de la machine maître pour une carte.
- yp_match -- Retourne la ligne associée.
- yp_next -- Retourne le couple (clé ; valeur) suivant d'une carte donnée.
- yp_order -- Retourne le numéro d'ordre d'une carte.
yp_all
Description
void yp_all ( string domain, string map, string callback)
| Avertissement |
This function is currently not documented, only the argument list is available. |
yp_cat
Description
array yp_cat ( string domain, string map)
| Avertissement |
This function is currently not documented, only the argument list is available. |
yp_err_string
Description
string yp_err_string ( void )yp_err_string() Retourne la chaîne d'erreur associée à la dernière opération. Très pratique pour savoir exactement ce qui n'est pas allé.
Voir aussi yp_errno.
yp_errno
Description
int yp_errno ( void)yp_errno() retourne le code d'erreur de la dernière opération.
Les erreurs possibles sont :
| 1 Mauvais arguments |
| 2 Erreur RPC - Le domaine n'existe pas |
| 3 Impossible de se connecter à ce domaine |
| 4 Impossible de trouver cette carte sur le serveur |
| 5 Cette clé n'existe pas |
| 6 Erreur yp interne ou erreur client |
| 7 Erreur d'allocation de ressources |
| 8 Il n'y a plus d'enregistrements dans cette carte |
| 9 Impossible de communiquer avec le portmapper |
| 10 Impossible de communiquer avec ypbind |
| 11 Impossible de communiquer avec ypserv |
| 12 Le nom de domaine local n'est pas assigné |
| 13 La base de données yp n'est pas valide |
| 14 Erreur de version yp |
| 15 Accès interdit |
| 16 Base de données occupée |
Voir aussi yp_err_string.
yp_first
Description
array yp_first ( string domain, string map)yp_first() retourne le premier couple (clé ; valeur) d'une carte donnée, ou FALSE.
Voir aussi yp-get-default-domain().
yp_get_default_domain
Description
int yp_get_default_domain ( void)yp_get_default_domain() retourne le nom de domaine NIS par défaut. Ce nom de domaine peut être utilisé pour les futurs appels NIS.
Un domaine NIS peut être décrit comme un regroupement de cartes NIS. Tous les hôtes qui ont besoin d'informations, s'attachent à un domaine. Référez-vous aux documents cités en début de document pour plus de détails.
yp_master
Description
string yp_master ( string domain, string map)yp_master() retourne le nom de la machine maître d'une carte.
Voir aussi yp-get-default-domain().
yp_match
Description
string yp_match ( string domain, string map, string key)yp_match() retourne la valeur associée à la clé passée en argument, pour la carte spécifiée, ou FALSE. La clé doit exister et être exacte.
Dans le cas présent, ce pourrait être: joe:##joe:11111:100:Joe User:/home/j/joe:/usr/local/bin/bash
Voir aussi yp-get-default-domain().
yp_next
Description
array yp_next ( string domain, string map, string key)yp_next() retourne le couple (clé ; valeur) suivant la clé donnée d'une carte donnée ou FALSE.
Voir aussi yp-get-default-domain().
yp_order
Description
int yp_order ( string domain, string map)yp_order() retourne le numéro d'ordre d'une carte ou FALSE.
Voir aussi yp-get-default-domain().
CX. Zip (décompression)
Ce module utilise les fonctions de la librairie ZZIPlib, créée par Guido Draheim pour lire de manière transparente des archives compressées Zip, et les fichiers qu'elles contiennent.
Notez que ZZIPlib ne fournit qu'une partie des fonctions utilisant l'algorithme de compression ZIP : elle ne permet que de lire les fichiers Zip. Un utilitaire Zip est nécessaire pour créer ces archives, vous ne pourrez pas le faire en PHP.
Le support de Zip par PHP n'est pas activé par défaut. Vous devez utiliser l'option --with-zip lorsque vous compilez PHP pour l'activer. Ce module requiert par ailleurs la librairie ZZIPlib version >= 0.10.6.
Note : Le support de Zip pour les versions antérieures à PHP 4.0.7 est expérimental. Cette section décrit l'extension Zip telle qu'elle existe en PHP 4.0.7 et plus récent.
Exemple d'utilisation
Cet exemple ouvre un fichier ZIP, lit chaque fichier de l'archive, et affiche son contenu. Le script test2.php utilisé dans cet exemple est un des fichiers de test de la distribution source de ZZIPlib.
Exemple 1. Exemple d'utilisation de l'extension Zip
|
- Table des matières
- zip_close -- Ferme une archive Zip
- zip_entry_close -- Ferme un élément d'archive
- zip_entry_compressedsize -- Lit la taille compressée d'un dossier
- zip_entry_compressionmethod -- Retourne la méthode de compression d'un dossier
- zip_entry_filesize -- Retourne la taille réelle d'un fichier dans un dossier
- zip_entry_name -- Retourne le nom de l'élément d'archive
- zip_entry_open -- Ouvre un nouveau dossier dans une archive
- zip_entry_read -- Lit dans un fichier d'archive
- zip_open -- Ouvre une archive Zip
- zip_read -- Lit le prochain élément d'archive
zip_close
Description
void zip_close ( resource zip)zip_close() ferme l'archive zip zip. Le paramètre zip doit être une archive zip, créée par la fonction zip_open().
Cette fonction ne retourne pas de valeur.
Voir aussi zip_open() et zip_read().
zip_entry_close
Description
void zip_entry_close ( resource zip_entry)zip_entry_close() ferme l'élément d'archive zip_entry. Le paramètre zip_entry doit être un élément d'archive valide, créé par la fonction zip_entry_open().
zip_entry_close() ne retourne pas de valeur.
Voir aussi zip_entry_open() et zip_entry_read().
zip_entry_compressedsize
Description
int zip_entry_compressedsize ( resource zip_entry)zip_entry_compressedsize() retourne la taille compressée de l'élément d'archive zip_entry. Le paramètre zip_entry doit être un élément d'archive valide, créé par la fonction zip_entry_open().
Voir aussi zip_open() et zip_read().
zip_entry_compressionmethod
Description
string zip_entry_compressionmethod ( resource zip_entry)zip_entry_compressionmethod() la méthode de compression de l'élément d'archive spécifié zip_entry. Le paramètre zip_entry doit être un élément d'archive valide, créé par la fonction zip_entry_open().
Voir aussi zip_open() et zip_read().
zip_entry_filesize
Description
int zip_entry_filesize ( resource zip_entry)zip_entry_filesize() retourne la taille réelle de l'élément d'archive zip_entry. Le paramètre zip_entry doit être un élément d'archive valide, créé par la fonction zip_entry_open().
Voir aussi zip_open() et zip_read().
zip_entry_name
Description
string zip_entry_name ( resource zip_entry)zip_entry_name() retourne le nom de l'élément d'archive spécifié par zip_entry. Le paramètre zip_entry doit être un élément d'archive valide, créé par la fonction zip_entry_open().
Voir aussi zip_open() et zip_read().
zip_entry_open
Description
bool zip_entry_open ( resource zip, resource zip_entry [, string mode])zip_entry_open() ouvre un dossier dans une archive Zip, en lecture seule. Le parmaètre zip est une ressource valide, retournée par zip_open(). Le paramètre zip_entry est une ressource de dossier, retournée par zip_read(). Le paramètre optinnel mode peut être l'un des mode spécifié dans la documentation de fopen().
Note : Actuellement, mode est ignoré et est vaut simplement "rb". Cela est lié au fait que l'extention zip est en lecture seule. Reportez vous à la fonction fopen() pour plus de détails sur le mode "rb".
zip_entry_open() retourne true en cas de succès, ou false en cas d'échec.
Note : Contrairement à fopen() et d'autres fonctions du même acabi, la valeur retournée par zip_entry_open() indique uniquement le résultat de l'opération, et n'est pas nécessaire pour lire ou fermer le dossier.
Voir aussi zip_entry_read() et zip_entry_close().
zip_entry_read
Description
string zip_entry_read ( resource zip_entry [, int length])zip_entry_read() jusqu'à length octets dans un fichier d'archive. Si length n'est pas spécifié, alors zip_entry_read() essaiera de lire 1024 octets. Le paramètre zip_entry est un élément d'archive valide, retourné par zip_read().
Note : Le paramètre length exprime une taille non compressée.
zip_entry_read() retourne les données lues, ou bien false si la fin du fichier est atteinte.
Voir aussi zip_entry_open(), zip_entry_close() et zip_entry_filesize().
zip_open
Description
resource zip_open ( string filename)zip_open() ouvre une nouvelle archive en lecture. Le paramètre filename est le chemin jusqu'au fichier à ouvrir.
zip_open() retourne une ressource à utiliser plus tard avec les fonctions zip_read() et zip_close(). zip_open() retourne FALSE si filename n'existe pas.
Voir aussi zip_read() et zip_close().
zip_read
Description
resource zip_read ( resource zip)zip_read() lit le prochain élément d'archive zip, dans l'archive zip. Le paramètre zip doit être une archive zip, ouverte précédemment par la fonction zip_open().
zip_read() une ressource d'élément d'archive, qui peut être utilisée ultérieurement par les fonctions zip_open(), zip_close(), zip_entry_open() et zip_entry_read().
Voir aussi zip_open(), zip_close(), zip_entry_open() et zip_entry_read().
CXI. Zlib (Compression)
Ce module utilise les fonctions de la librairie zlib (zlib) de Jean-loup Gailly et Mark Adler pour lire et écrire, de manière transparente, des fichiers compressés avec gzip (.gz). Il faut utiliser la librairie zlib, de version >= 1.0.9.
Ce module contient des versions de la plupart des fonctions du chapitre système de fichier. Mais celles-ci fonctionnent non seulement avec des fichiers compressés, mais aussi des fichiers décompressés (hormis les fonctions utilisant les sockets).
Petit exemple
Ouvre un fichier temporaire, écrit un texte et puis affiche deux fois le contenu.
Exemple 1. Petit exemple avec ZLIB
|
- Table des matières
- gzclose -- Ferme un pointeur sur un fichier compressé.
- gzcompress -- Compresse une chaîne (ZLIB)
- gzdeflate -- Compresse une chaîne (DEFLATE)
- gzencode -- Crée une chaîne compressée avec gzip
- gzeof -- Teste la fin d'un fichier compressé.
- gzfile -- Lit la totalité d'un fichier compressé dans un tableau.
- gzgetc -- Lit un caractère d'un fichier compressé.
- gzgets -- Lit une ligne d'un fichier compressé
- gzgetss -- Lit une ligne d'un fichier compressé et supprime les balises HTML
- gzinflate -- Décompresse une chaîne (INFLATE)
- gzopen -- Ouvre un fichier compressé
- gzpassthru -- Lit toutes les informations restantes d'un fichier compressé
- gzputs -- Ecrit dans un fichier compressé
- gzread -- Lit un fichier compressé en mode binaire
- gzrewind -- Replace le pointeur courant au début du fichier
- gzseek -- Déplace le pointeur courant dans un fichier compressé
- gztell -- Retourne la position courante du pointeur interne
- gzuncompress -- Décompresse une chaîne gz-compressée
- gzwrite -- Ecrit un fichier compressé en mode binaire
- readgzfile -- Affiche un fichier compressé
gzclose
Description
int gzclose ( resource zp)gzclose() ferme le pointeur zp.
gzclose() retourne TRUE ou FALSE, suivant le succès ou l'échec.
Le pointeur de fichier compressé doit être valide et doit référencer un fichier qui a été ouvert par gzopen().
gzcompress
Description
string gzcompress ( string data [, int level])gzcompress() retourne la version compressé avec le format de données ZLIB de la chaîne data, ou FALSE en cas d'erreur. Le paramètre level peut prendre des valeurs depuis 0 (pas de compression) jusqu'à 9 (compression maximum).
Pour plus de détails sur la compression ZLIB et son algorithme, reportez-vous au document de spécifications ZLIB Compressed Data Format Specification version 3.3 (RFC 1950).
Voir aussi gzdeflate(), gzinflate(), gzuncompress() et gzencode().
gzdeflate
Description
string gzdeflate ( string data [, int level])gzdeflate() retourne la version compressée de data en utilisant le format de données DEFLATE, ou FALSE si une erreur est survenue. Le paramètre optionnel level peut prendre des valeurs de 0 (pas de compression) jusqu'à 9 (compression maximum, vitesse minimum).
Pour plus de détails sur la compression ZLIB et son algorithme, reportez-vous au document de spécifications DEFLATE Compressed Data Format Specification version 1.3 (RFC 1951).
Voir aussi gzinflate(), gzcompress(), gzuncompress() et gzencode().
gzencode
Description
string gzencode ( string data [, int level])gzencode() retourne la chaîne data compressée et compatible avec le programme gzip, ou bien FALSE si une erreur survient. Le paramètre optionnel level peut prendre des valeurs de 0 (par de compression) jusqu'à 9 (compression maximum, vitess minimum). Par défaut, le niveau de compression est 1.
La chaîne retournée contient les en-têtes appropriées et la structure de données demandées par gzip pour faire un fichier .gz file, e.g.:
Pour plus de détails sur le format GZIP, reportez-vous à : GZIP file format specification version 4.3 (RFC 1952).
Voir aussi gzcompress(), gzuncompress(), gzdeflate() et gzinflate().
gzeof
Description
int gzeof ( resource zp)gzeof() retourne TRUE si le pointeur interne du fichier compressé zp est à la fin du fichier, sinon retourne FALSE.
Le pointeur de fichier compressé doit être valide et doit référencer un fichier qui a été ouvert par gzopen().
gzfile
Description
array gzfile ( string filename [, int use_include_path])gzfile() est identique à readgzfile(), mais gzfile() retourne un tableau.
Vous pouvez aussi utiliser le deuxième paramètre optionnel en le mettant à "1", si vous voulez rechercher le fichier dans le dossier include_path.
Voir aussi readgzfile() et gzopen().
gzgetc
Description
string gzgetc ( resource zp)gzgetc() retourne une chaîne décompressée, qui contient un caractère unique, lu depuis le fichier référencé par le pointeur zp. gzgetc() retourne FALSE à la fin du fichier (voir gzeof()).
Le pointeur de fichier compressé doit être valide et doit référencer un fichier qui a été ouvert par gzopen().
gzgets
Description
string gzgets ( resource zp, int length)gzgets() retourne une chaîne décompressée, de longueur inférieure ou égale à length - 1 octets, lue depuis de fichier référencé par le pointeur de fichier zp. La lecture s'interrompt lorsque length - 1 octets ont été lus, ou bien lorsqu'une nouvelle ligne a été rencontrée, ou bien lorsque la fin du fichier a été atteinte.
Si une erreur survient, retourne FALSE.
Le pointeur de fichier compressé doit être valide et doit référencer un fichier qui a été ouvert par gzopen().
gzgetss
Description
string gzgetss ( resource zp, int length [, string allowable_tags])gzgetss() est identique à gzgets(), mais elle essaie de supprimer toutes les balises HTML et PHP du texte lu depuis zp.
Vous pouvez utiliser le troisième argument optionnel allowable_tags pour indiquer les balises qui ne doivent pas être supprimées.
Note : allowable_tags a été ajouté en PHP 3.0.13, PHP 4.0B3.
Voir aussi gzgets(), gzopen() et strip_tags().
gzinflate
Description
string gzinflate ( string data [, int length])gzinflate() décompresse la chaîne data. data doit avoir été compressée avec gzdeflate(). gzinflate() retourne les données originales décompressées, ou bien FALSE si une erreur survient. gzinflate() retournera une erreur si les données décompressées sont plus grandes que 256 fois la taille des données compressées data ou que le paramètre optionnel length.
Voir aussi gzcompress(), gzuncompress(), gzdeflate() et gzencode().
gzopen
Description
int gzopen ( string filename, string mode [, int use_include_path])gzopen() ouvre un fichier compressé avec gzip (.gz) pour le lire ou l'écrire. Le paramètre de mode est le même que dans fopen() ("rb" ou "wb") mais il peut aussi inclure un niveau de compression ("wb9") ou une stratégie: 'f' pour les données filtrées, comme dans "wb6f", 'h' pour Huffman seul , comme dans "wb1h". (Voir la description de deflateInit2 dans zlib.h pour plus de détails a propos des paramètres de stratégie).
gzopen() peut être utilisé pour ouvrir des fichiers qui ne sont pas au format gzip; dans ce cas, gzread() lira directement le fichier, sans appliquer de décompression.
gzopen() retourne un pointeur de fichier sur le fichier ouvert. Ce pointeur sera nécessaire pour toutes les opérations ultérieures sur ce fichier. Les opérations de compression/décompression seront transparaentes.
Si l'ouverture échoue, la fonction retourne FALSE.
Vous pouvez utiliser le paramètre optionnel en le mettant à "1", si vous voulez rechercher le fichier dans le dossier include_path.
Voir aussi gzclose().
gzpassthru
Description
int gzpassthru ( resource zp)gzpassthru() lit toutes les informations d'un fichier compressé jusqu'à la fin du fichier zp et écrit le résultat décompressé dans la sortie standard.
Si une erreur survient, retourne FALSE.
Le pointeur de fichier doit être valide et avoir été ouvert par gzopen().
Le fichier pointé est refermé par gzpassthru() ce qui le rend inutilisable pour les opérations ultérieures.
gzputs
Description
int gzputs ( resource zp, string str [, int length])gzputs()est un alias de gzwrite() et lui est identique en tous points.
gzread
Description
string gzread ( resource zp, int length)gzread() lit jusqu'à length octets depuis le fichier compressé référencé par zp. La lecture stoppe lorsque length octets décompressés ont été lus, ou que la fin du fichier a été trouvée.
<?php // lit le contenu d'un fichier compressé et le met dans une chaîne $filename = "/usr/local/something.txt.gz"; $zd = gzopen( $filename, "r" ); $contents = gzread( $zd, 10000 ); gzclose( $zd ); ?> |
Voir aussi gzwrite(), gzopen(), gzgets(), gzgetss(), gzfile() et gzpassthru().
gzrewind
Description
int gzrewind ( resource zp)gzrewind() positionne le pointeur interne du fichier au début du fichier compressé.
Si une erreur survient, retourne 0.
Le pointeur de fichier doit être valide et avoir été retourné par la fonction gzopen().
gzseek
Description
int gzseek ( resource zp, int offset)gzseek() positionne le pointeur interne du fichier compressé zp à la position donnée en offset. Equivalent à l'appel (en C) de gzseek(zp, offset, SEEK_SET).
Si le fichier est ouvert en lecture seule, cette fonction émulée peut être extrêmement lente. Si le fichier est ouvert en lecture, seul le déplacement avant (forward seek) sont acceptés. gzseek() compresse alors une séquence de zéro jusqu'à la nouvelle position.
gzseek() retourne 0 en cas de succès, sinon retourne -1. Notez que positionner le pointeur au-delà de la fin du fichier est une erreur.
Voir aussi gztell() et gzrewind().
gztell
Description
int gztell ( resource zp)gztell() retourne la position du pointeur interne du fichier référencé par zp, i.e., son offset en octets depuis le début du fichier.
Si une erreur survient, retourne FALSE.
Le pointeur de fichier doit être valide et doit avoir été retourné par la fonction gzopen().
Voir aussi gzopen(), gzseek() et gzrewind().
gzuncompress
Description
string gzuncompress ( string data [, int length])gzuncompress() prend la chaîne data en entrée (compressée par gzcompress()) et retourne la chaîne originale, ou bien FALSE en cas d'erreur. gzuncompress() retournera une erreur si la taille de la chaîne décompressée est plus de 256 fois la longueur de la chaîne compressée data ou plus que le paramètre optionnel length.
Note : Ceci n'est pas équivalent à une compression gzip, qui inclus en plus des données d'en-tête. Voir gzencode() pour la compression gzip.
Voir aussi gzdeflate(), gzinflate(), gzcompress() et gzencode().
gzwrite
Description
int gzwrite ( resource zp, string string [, int length])gzwrite() écrit le contenu de la chaîne string dans le fichier compressé référencé par le pointeur zp. Si l'argument length est donné, l'écriture cessera après avoir écrit length octets (non compressé), ou bien si la fin de la chaîne a été atteinte.
Notez que si l'argument length est donné, alors l'option magic_quotes_runtime sera ignorée et les slash ne seront pas supprimés de la chaîne string.
readgzfile
Description
int readgzfile ( string filename [, int use_include_path])readgzfile() lit un fichier, le décompresse et l'écrit dans la sortie standard.
readgzfile() peut être utilisé pour lire un fichier qui n'est pas au format gzip, car dans ce cas, la décompression est omise et le fichier est directement affiché.
readgzfile() retourne le nombre d'octets (non compressé) lus depuis le fichier. Si une erreur survient, retourne FALSE, et à moins que la fonction n'ai été appelée avec @readgzfile, l'erreur est affichée.
Le fichier filename sera ouvert et son contenu sera écrit dans la sortie standard.
Vous pouvez utiliser le paramètre optionnel en le mettant à "1", si vous voulez rechercher le fichier dans le dossier include_path.
Voir aussi gzpassthru(), gzfile() et gzopen().
V. Extending PHP 4.0
Hacking the Core of PHP
Sometimes, PHP "as is" simply isn't enough. Although these cases are rare for the average user, professional applications will soon lead PHP to the edge of its capabilities, in terms of either speed or functionality. New functionality cannot always be implemented natively due to language restrictions and inconveniences that arise when having to carry around a huge library of default code appended to every single script, so another method needs to be found for overcoming these eventual lacks in PHP.
As soon as this point is reached, it's time to touch the heart of PHP and take a look at its core, the C code that makes PHP go.
- Table des matières
- 25. Overview
- 26. Extension Possibilities
- 27. Source Layout
- 28. PHP's Automatic Build System
- 29. Creating Extensions
- 30. Using Extensions
- 31. Troubleshooting
- 32. Source Discussion
- 33. Accepting Arguments
- 34. Creating Variables
- 35. Duplicating Variable Contents: The Copy Constructor
- 36. Returning Values
- 37. Printing Information
- 38. Startup and Shutdown Functions
- 39. Calling User Functions
- 40. Initialization File Support
- 41. Where to Go from Here
- 42. Reference: Some Configuration Macros
- 43. API Macros
Chapitre 25. Overview
"Extending PHP" is easier said than done. PHP has evolved to a full-fledged tool consisting of a few megabytes of source code, and to hack a system like this quite a few things have to be learned and considered. When structuring this chapter, we finally decided on the "learn by doing" approach. This is not the most scientific and professional approach, but the method that's the most fun and gives the best end results. In the following sections, you'll learn quickly how to get the most basic extensions to work almost instantly. After that, you'll learn about Zend's advanced API functionality. The alternative would have been to try to impart the functionality, design, tips, tricks, etc. as a whole, all at once, thus giving a complete look at the big picture before doing anything practical. Although this is the "better" method, as no dirty hacks have to be made, it can be very frustrating as well as energy- and time-consuming, which is why we've decided on the direct approach.
Note that even though this chapter tries to impart as much knowledge as possible about the inner workings of PHP, it's impossible to really give a complete guide to extending PHP that works 100% of the time in all cases. PHP is such a huge and complex package that its inner workings can only be understood if you make yourself familiar with it by practicing, so we encourage you to work with the source.
What Is Zend? and What Is PHP?
The name Zend refers to the language engine, PHP's core. The term PHP refers to the complete system as it appears from the outside. This might sound a bit confusing at first, but it's not that complicated (see Figure 25-1). To implement a Web script interpreter, you need three parts:
The interpreter part analyzes the input code, translates it, and executes it.
The functionality part implements the functionality of the language (its functions, etc.).
The interface part talks to the Web server, etc.
The following sections discuss where PHP can be extended and how it's done.
Chapitre 26. Extension Possibilities
As shown in Figure 25-1 above, PHP can be extended primarily at three points: external modules, built-in modules, and the Zend engine. The following sections discuss these options.
External Modules
External modules can be loaded at script runtime using the function dl(). This function loads a shared object from disk and makes its functionality available to the script to which it's being bound. After the script is terminated, the external module is discarded from memory. This method has both advantages and disadvantages, as described in the following table:
| Advantages | Disadvantages |
| External modules don't require recompiling of PHP. | The shared objects need to be loaded every time a script is being executed (every hit), which is very slow. |
| The size of PHP remains small by "outsourcing" certain functionality. | External additional files clutter up the disk. |
| Every script that wants to use an external module's functionality has to specifically include a call to dl(), or the extension tag in php.ini needs to be modified (which is not always a suitable solution). |
Third parties might consider using the extension tag in php.ini to create additional external modules to PHP. These external modules are completely detached from the main package, which is a very handy feature in commercial environments. Commercial distributors can simply ship disks or archives containing only their additional modules, without the need to create fixed and solid PHP binaries that don't allow other modules to be bound to them.
Built-in Modules
Built-in modules are compiled directly into PHP and carried around with every PHP process; their functionality is instantly available to every script that's being run. Like external modules, built-in modules have advantages and disadvantages, as described in the following table:
Built-in modules are best when you have a solid library of functions that remains relatively unchanged, requires better than poor-to-average performance, or is used frequently by many scripts on your site. The need to recompile PHP is quickly compensated by the benefit in speed and ease of use. However, built-in modules are not ideal when rapid development of small additions is required.The Zend Engine
Of course, extensions can also be implemented directly in the Zend engine. This strategy is good if you need a change in the language behavior or require special functions to be built directly into the language core. In general, however, modifications to the Zend engine should be avoided. Changes here result in incompatibilities with the rest of the world, and hardly anyone will ever adapt to specially patched Zend engines. Modifications can't be detached from the main PHP sources and are overridden with the next update using the "official" source repositories. Therefore, this method is generally considered bad practice and, due to its rarity, is not covered in this book.
Chapitre 27. Source Layout
Note : Prior to working through the rest of this chapter, you should retrieve clean, unmodified source trees of your favorite Web server. We're working with Apache (available at http://www.apache.org/) and, of course, with PHP (available at http://www.php.net/ - does it need to be said?).
Make sure that you can compile a working PHP environment by yourself! We won't go into this issue here, however, as you should already have this most basic ability when studying this chapter.
Before we start discussing code issues, you should familiarize yourself with the source tree to be able to quickly navigate through PHP's files. This is a must-have ability to implement and debug extensions.
After extracting the PHP archive, you'll see a directory layout similar to that in Figure 27-1.
The following table describes the contents of the major directories.
| Directory | Contents |
| php-4 | Main PHP source files and main header files; here you'll find all of PHP's API definitions, macros, etc. (important). |
| ext | Repository for dynamic and built-in modules; by default, these are the "official" PHP modules that have been integrated into the main source tree. In PHP 4.0, it's possible to compile these standard extensions as dynamic loadable modules (at least, those that support it). |
| pear | Directory for the PHP class repository. At the time of this writing, this is still in the design phase, but it's being tried to establish something similar to CPAN for Perl here. |
| sapi | Contains the code for the different server abstraction layers. |
| TSRM | Location of the "Thread Safe Resource Manager" (TSRM) for Zend and PHP. |
| Zend | Location of Zend's file; here you'll find all of Zend's API definitions, macros, etc. (important). |
Discussing all the files included in the PHP package is beyond the scope of this chapter. However, you should take a close look at the following files:
php.h, located in the main PHP directory. This file contains most of PHP's macro and API definitions.
zend.h, located in the main Zend directory. This file contains most of Zend's macros and definitions.
zend_API.h, also located in the Zend directory, which defines Zend's API.
Extension Conventions
Zend is built using certain conventions; to avoid breaking its standards, you should follow the rules described in the following sections.
Macros
For almost every important task, Zend ships predefined macros that are extremely handy. The tables and figures in the following sections describe most of the basic functions, structures, and macros. The macro definitions can be found mainly in zend.h and zend_API.h. We suggest that you take a close look at these files after having studied this chapter. (Although you can go ahead and read them now, not everything will make sense to you yet.)
Memory Management
Resource management is a crucial issue, especially in server software. One of the most valuable resources is memory, and memory management should be handled with extreme care. Memory management has been partially abstracted in Zend, and you should stick to this abstraction for obvious reasons: Due to the abstraction, Zend gets full control over all memory allocations. Zend is able to determine whether a block is in use, automatically freeing unused blocks and blocks with lost references, and thus prevent memory leaks. The functions to be used are described in the following table:
| Function | Description |
| emalloc() | Serves as replacement for malloc(). |
| efree() | Serves as replacement for free(). |
| estrdup() | Serves as replacement for strdup(). |
| estrndup() | Serves as replacement for strndup(). Faster than estrdup() and binary-safe. This is the recommended function to use if you know the string length prior to duplicating it. |
| ecalloc() | Serves as replacement for calloc(). |
| erealloc() | Serves as replacement for realloc(). |
| Avertissement |
To allocate resident memory that survives termination of the current script, you can use malloc() and free(). This should only be done with extreme care, however, and only in conjunction with demands of the Zend API; otherwise, you risk memory leaks. |
Directory and File Functions
The following directory and file functions should be used in Zend modules. They behave exactly like their C counterparts, but provide virtual working directory support on the thread level.
String Handling
Strings are handled a bit differently by the Zend engine than other values such as integers, Booleans, etc., which don't require additional memory allocation for storing their values. If you want to return a string from a function, introduce a new string variable to the symbol table, or do something similar, you have to make sure that the memory the string will be occupying has previously been allocated, using the aforementioned e*() functions for allocation. (This might not make much sense to you yet; just keep it somewhere in your head for now - we'll get back to it shortly.)
Complex Types
Complex types such as arrays and objects require different treatment. Zend features a single API for these types - they're stored using hash tables.
Note : To reduce complexity in the following source examples, we're only working with simple types such as integers at first. A discussion about creating more advanced types follows later in this chapter.
Chapitre 28. PHP's Automatic Build System
PHP 4 features an automatic build system that's very flexible. All modules reside in a subdirectory of the ext directory. In addition to its own sources, each module consists of an M4 file (for example, see http://www.gnu.org/manual/m4/html_mono/m4.html) for configuration and a Makefile.in file, which is responsible for compilation (the results of autoconf and automake; for example, see http://sourceware.cygnus.com/autoconf/autoconf.html and http://sourceware.cygnus.com/automake/automake.html).
Both files are generated automatically, along with .cvsignore, by a little shell script named ext_skel that resides in the ext directory. As argument it takes the name of the module that you want to create. The shell script then creates a directory of the same name, along with the appropriate config.m4 and Makefile.in files.
Step by step, the process looks like this:
root@dev:/usr/local/src/php4/ext > ./ext_skel my_module
Creating directory
Creating basic files: config.m4 Makefile.in .cvsignore [done].
To use your new extension, you will have to execute the following steps:
$ cd ..
$ ./buildconf
$ ./configure # (your extension is automatically enabled)
$ vi ext/my_module/my_module.c
$ make
Repeat the last two steps as often as necessary. |
Finally, running configure parses all configuration options and generates a makefile based on those options and the options you specify in Makefile.in.
Exemple 28-1shows the previously generated Makefile.in:
There's not much to tell about this one: It contains the names of the input and output files. You could also specify build instructions for other files if your module is built from multiple source files.
The default config.m4 shown in Exemple 28-2'/> is a bit more complex:
Exemple 28-2. The default config.m4.
|
If you're unfamiliar with M4 files (now is certainly a good time to get familiar), this might be a bit confusing at first; but it's actually quite easy.
Note: Everything prefixed with dnl is treated as a comment and is not parsed.
The config.m4 file is responsible for parsing the command-line options passed to configure at configuration time. This means that it has to check for required external files and do similar configuration and setup tasks.
The default file creates two configuration directives in the configure script: --with-my_module and --enable-my_module. Use the first option when referring external files (such as the --with-apache directive that refers to the Apache directory). Use the second option when the user simply has to decide whether to enable your extension. Regardless of which option you use, you should uncomment the other, unnecessary one; that is, if you're using --enable-my_module, you should remove support for --with-my_module, and vice versa.
By default, the config.m4 file created by ext_skel accepts both directives and automatically enables your extension. Enabling the extension is done by using the PHP_EXTENSION macro. To change the default behavior to include your module into the PHP binary when desired by the user (by explicitly specifying --enable-my_module or --with-my_module), change the test for $PHP_MY_MODULE to == "yes":
if test "$PHP_MY_MODULE" == "yes"; then dnl
Action.. PHP_EXTENSION(my_module, $ext_shared)
fi |
Note: Be sure to run buildconf every time you change config.m4!
We'll go into more details on the M4 macros available to your configuration scripts later in this chapter. For now, we'll simply use the default files. The sample sources on the CD-ROM all have working config.m4 files. To include them into the PHP build process, simply copy the source directories to your PHP ext directory, run buildconf, and then include the sample modules you want by using the appropriate --enable-* directives with configure.
Chapitre 29. Creating Extensions
We'll start with the creation of a very simple extension at first, which basically does nothing more than implement a function that returns the integer it receives as parameter. Exemple 29-1 shows the source.
Exemple 29-1. A simple extension.
|
This code contains a complete PHP module. We'll explain the source code in detail shortly, but first we'd like to discuss the build process. (This will allow the impatient to experiment before we dive into API discussions.)
Note : The example source makes use of some features introduced with the Zend version used in PHP 4.1.0 and above, it won't compile with older PHP 4.0.x versions.
Compiling Modules
There are basically two ways to compile modules:
Use the provided "make" mechanism in the ext directory, which also allows building of dynamic loadable modules.
Compile the sources manually.
The second method is good for those who (for some reason) don't have the full PHP source tree available, don't have access to all files, or just like to juggle with their keyboard. These cases should be extremely rare, but for the sake of completeness we'll also describe this method.
Compiling Using Make. To compile the sample sources using the standard mechanism, copy all their subdirectories to the ext directory of your PHP source tree. Then run buildconf, which will create an updated configure script containing appropriate options for the new extension. By default, all the sample sources are disabled, so you don't have to fear breaking your build process.
After you run buildconf, configure --help shows the following additional modules:
--enable-array_experiments BOOK: Enables array experiments --enable-call_userland BOOK: Enables userland module --enable-cross_conversion BOOK: Enables cross-conversion module --enable-first_module BOOK: Enables first module --enable-infoprint BOOK: Enables infoprint module --enable-reference_test BOOK: Enables reference test module --enable-resource_test BOOK: Enables resource test module --enable-variable_creation BOOK: Enables variable-creation module |
The module shown earlier in Exemple 29-1 can be enabled with --enable-first_module or --enable-first_module=yes.
Compiling Manually. To compile your modules manually, you need the following commands:
The command to compile the module simply instructs the compiler to generate position-independent code (-fpic shouldn't be omitted) and additionally defines the constant COMPILE_DL to tell the module code that it's compiled as a dynamically loadable module (the test module above checks for this; we'll discuss it shortly). After these options, it specifies a number of standard include paths that should be used as the minimal set to compile the source files.Note: All include paths in the example are relative to the directory ext. If you're compiling from another directory, change the pathnames accordingly. Required items are the PHP directory, the Zend directory, and (if necessary), the directory in which your module resides.
The link command is also a plain vanilla command instructing linkage as a dynamic module.
You can include optimization options in the compilation command, although these have been omitted in this example (but some are included in the makefile template described in an earlier section).
Note: Compiling and linking manually as a static module into the PHP binary involves very long instructions and thus is not discussed here. (It's not very efficient to type all those commands.)
Chapitre 30. Using Extensions
Depending on the build process you selected, you should either end up with a new PHP binary to be linked into your Web server (or run as CGI), or with an .so (shared object) file. If you compiled the example file first_module.c as a shared object, your result file should be first_module.so. To use it, you first have to copy it to a place from which it's accessible to PHP. For a simple test procedure, you can copy it to your htdocs directory and try it with the source in Exemple 30-1. If you compiled it into the PHP binary, omit the call to dl(), as the module's functionality is instantly available to your scripts.
| Avertissement |
For security reasons, you should not put your dynamic modules into publicly accessible directories. Even though it can be done and it simplifies testing, you should put them into a separate directory in production environments. |
Calling this PHP file in your Web browser should give you the output shown in Figure 30-1.
If required, the dynamic loadable module is loaded by calling the dl() function. This function looks for the specified shared object, loads it, and makes its functions available to PHP. The module exports the function first_module(), which accepts a single parameter, converts it to an integer, and returns the result of the conversion.
If you've gotten this far, congratulations! You just built your first extension to PHP.
Chapitre 31. Troubleshooting
Actually, not much troubleshooting can be done when compiling static or dynamic modules. The only problem that could arise is that the compiler will complain about missing definitions or something similar. In this case, make sure that all header files are available and that you specified their path correctly in the compilation command. To be sure that everything is located correctly, extract a clean PHP source tree and use the automatic build in the ext directory with the fresh files; this will guarantee a safe compilation environment. If this fails, try manual compilation.
PHP might also complain about missing functions in your module. (This shouldn't happen with the sample sources if you didn't modify them.) If the names of external functions you're trying to access from your module are misspelled, they'll remain as "unlinked symbols" in the symbol table. During dynamic loading and linkage by PHP, they won't resolve because of the typing errors - there are no corresponding symbols in the main binary. Look for incorrect declarations in your module file or incorrectly written external references. Note that this problem is specific to dynamic loadable modules; it doesn't occur with static modules. Errors in static modules show up at compile time.
Chapitre 32. Source Discussion
Now that you've got a safe build environment and you're able to include the modules into PHP files, it's time to discuss how everything works.
Module Structure
All PHP modules follow a common structure:
Header file inclusions (to include all required macros, API definitions, etc.)
C declaration of exported functions (required to declare the Zend function block)
Declaration of the Zend function block
Declaration of the Zend module block
Implementation of get_module()
Implementation of all exported functions
Header File Inclusions
The only header file you really have to include for your modules is php.h, located in the PHP directory. This file makes all macros and API definitions required to build new modules available to your code.
Tip: It's good practice to create a separate header file for your module that contains module-specific definitions. This header file should contain all the forward definitions for exported functions and include php.h. If you created your module using ext_skel you already have such a header file prepared.
Declaring Exported Functions
To declare functions that are to be exported (i.e., made available to PHP as new native functions), Zend provides a set of macros. A sample declaration looks like this:
ZEND_FUNCTION ( my_function ); |
ZEND_FUNCTION declares a new C function that complies with Zend's internal API. This means that the function is of type void and accepts INTERNAL_FUNCTION_PARAMETERS (another macro) as parameters. Additionally, it prefixes the function name with zif. The immediately expanded version of the above definitions would look like this:
void zif_my_function ( INTERNAL_FUNCTION_PARAMETERS ); |
void zif_my_function( int ht
, zval * return_value
, zval * this_ptr
, int return_value_used
, zend_executor_globals * executor_globals
); |
Since the interpreter and executor core have been separated from the main PHP package, a second API defining macros and function sets has evolved: the Zend API. As the Zend API now handles quite a few of the responsibilities that previously belonged to PHP, a lot of PHP functions have been reduced to macros aliasing to calls into the Zend API. The recommended practice is to use the Zend API wherever possible, as the old API is only preserved for compatibility reasons. For example, the types zval and pval are identical. zval is Zend's definition; pval is PHP's definition (actually, pval is an alias for zval now). As the macro INTERNAL_FUNCTION_PARAMETERS is a Zend macro, the above declaration contains zval. When writing code, you should always use zval to conform to the new Zend API.
The parameter list of this declaration is very important; you should keep these parameters in mind (see Tableau 32-1 for descriptions).
Tableau 32-1. Zend's Parameters to Functions Called from PHP
| Parameter | Description |
| ht | The number of arguments passed to the Zend function. You should not touch this directly, but instead use ZEND_NUM_ARGS() to obtain the value. |
| return_value | This variable is used to pass any return values of your function back to PHP. Access to this variable is best done using the predefined macros. For a description of these see below. |
| this_ptr | Using this variable, you can gain access to the object in which your function is contained, if it's used within an object. Use the function getThis() to obtain this pointer. |
| return_value_used | This flag indicates whether an eventual return value from this function will actually be used by the calling script. 0 indicates that the return value is not used; 1 indicates that the caller expects a return value. Evaluation of this flag can be done to verify correct usage of the function as well as speed optimizations in case returning a value requires expensive operations (for an example, see how array.c makes use of this). |
| executor_globals | This variable points to global settings of the Zend engine. You'll find this useful when creating new variables, for example (more about this later). The executor globals can also be introduced to your function by using the macro TSRMLS_FETCH(). |
Declaration of the Zend Function Block
Now that you have declared the functions to be exported, you also have to introduce them to Zend. Introducing the list of functions is done by using an array of zend_function_entry. This array consecutively contains all functions that are to be made available externally, with the function's name as it should appear in PHP and its name as defined in the C source. Internally, zend_function_entry is defined as shown in Exemple 32-1.
Exemple 32-1. Internal declaration of zend_function_entry.
|
zend_function_entry firstmod_functions[] =
{
ZEND_FE(first_module, NULL)
{NULL, NULL, NULL}
}; |
Note : You cannot use the predefined macros for the end marker, as these would try to refer to a function named "NULL"!
The macro ZEND_FE (short for 'Zend Function Entry') simply expands to a structure entry in zend_function_entry. Note that these macros introduce a special naming scheme to your functions - your C functions will be prefixed with zif_, meaning that ZEND_FE(first_module) will refer to a C function zif_first_module(). If you want to mix macro usage with hand-coded entries (not a good practice), keep this in mind.
Tip: Compilation errors that refer to functions named zif_*() relate to functions defined with ZEND_FE.
Tableau 32-2 shows a list of all the macros that you can use to define functions.
Tableau 32-2. Macros for Defining Functions
| Macro Name | Description |
| ZEND_FE(name, arg_types) | Defines a function entry of the name name in zend_function_entry. Requires a corresponding C function. arg_types needs to be set to NULL. This function uses automatic C function name generation by prefixing the PHP function name with zif_. For example, ZEND_FE("first_module", NULL) introduces a function first_module() to PHP and links it to the C function zif_first_module(). Use in conjunction with ZEND_FUNCTION. |
| ZEND_NAMED_FE(php_name, name, arg_types) | Defines a function that will be available to PHP by the name php_name and links it to the corresponding C function name. arg_types needs to be set to NULL. Use this function if you don't want the automatic name prefixing introduced by ZEND_FE. Use in conjunction with ZEND_NAMED_FUNCTION. |
| ZEND_FALIAS(name, alias, arg_types) | Defines an alias named alias for name. arg_types needs to be set to NULL. Doesn't require a corresponding C function; refers to the alias target instead. |
| PHP_FE(name, arg_types) | Old PHP API equivalent of ZEND_FE. |
| PHP_NAMED_FE(runtime_name, name, arg_types) | Old PHP API equivalent of ZEND_NAMED_FE. |
Note: You can't use ZEND_FE in conjunction with PHP_FUNCTION, or PHP_FE in conjunction with ZEND_FUNCTION. However, it's perfectly legal to mix ZEND_FE and ZEND_FUNCTION with PHP_FE and PHP_FUNCTION when staying with the same macro set for each function to be declared. But mixing is not recommended; instead, you're advised to use the ZEND_* macros only.
Declaration of the Zend Module Block
This block is stored in the structure zend_module_entry and contains all necessary information to describe the contents of this module to Zend. You can see the internal definition of this module in Exemple 32-2.
Exemple 32-2. Internal declaration of zend_module_entry.
|
In our example, this structure is implemented as follows:
zend_module_entry firstmod_module_entry =
{
STANDARD_MODULE_HEADER,
"First Module",
firstmod_functions,
NULL, NULL, NULL, NULL, NULL,
NO_VERSION_YET,
STANDARD_MODULE_PROPERTIES,
}; |
For reference purposes, you can find a list of the macros involved in declared startup and shutdown functions in Tableau 32-3. These are not used in our basic example yet, but will be demonstrated later on. You should make use of these macros to declare your startup and shutdown functions, as these require special arguments to be passed (INIT_FUNC_ARGS and SHUTDOWN_FUNC_ARGS), which are automatically included into the function declaration when using the predefined macros. If you declare your functions manually and the PHP developers decide that a change in the argument list is necessary, you'll have to change your module sources to remain compatible.
Tableau 32-3. Macros to Declare Startup and Shutdown Functions
| Macro | Description |
| ZEND_MINIT(module) | Declares a function for module startup. The generated name will be zend_minit_<module> (for example, zend_minit_first_module). Use in conjunction with ZEND_MINIT_FUNCTION. |
| ZEND_MSHUTDOWN(module) | Declares a function for module shutdown. The generated name will be zend_mshutdown_<module> (for example, zend_mshutdown_first_module). Use in conjunction with ZEND_MSHUTDOWN_FUNCTION. |
| ZEND_RINIT(module) | Declares a function for request startup. The generated name will be zend_rinit_<module> (for example, zend_rinit_first_module). Use in conjunction with ZEND_RINIT_FUNCTION. |
| ZEND_RSHUTDOWN(module) | Declares a function for request shutdown. The generated name will be zend_rshutdown_<module> (for example, zend_rshutdown_first_module). Use in conjunction with ZEND_RSHUTDOWN_FUNCTION. |
| ZEND_MINFO(module) | Declares a function for printing module information, used when phpinfo() is called. The generated name will be zend_info_<module> (for example, zend_info_first_module). Use in conjunction with ZEND_MINFO_FUNCTION. |
Creation of get_module()
This function is special to all dynamic loadable modules. Take a look at the creation via the ZEND_GET_MODULE macro first:
#if COMPILE_DL_FIRSTMOD
ZEND_GET_MODULE(firstmod)
#endif |
The function implementation is surrounded by a conditional compilation statement. This is needed since the function get_module() is only required if your module is built as a dynamic extension. By specifying a definition of COMPILE_DL_FIRSTMOD in the compiler command (see above for a discussion of the compilation instructions required to build a dynamic extension), you can instruct your module whether you intend to build it as a dynamic extension or as a built-in module. If you want a built-in module, the implementation of get_module() is simply left out.
get_module() is called by Zend at load time of the module. You can think of it as being invoked by the dl() call in your script. Its purpose is to pass the module information block back to Zend in order to inform the engine about the module contents.
If you don't implement a get_module() function in your dynamic loadable module, Zend will compliment you with an error message when trying to access it.
Implementation of All Exported Functions
Implementing the exported functions is the final step. The example function in first_module looks like this:
ZEND_FUNCTION(first_module)
{
long parameter;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", ¶meter) == FAILURE) {
return;
}
RETURN_LONG(parameter);
} |
After the declaration, code for checking and retrieving the function's arguments, argument conversion, and return value generation follows (more on this later).
Summary
That's it, basically - there's nothing more to implementing PHP modules. Built-in modules are structured similarly to dynamic modules, so, equipped with the information presented in the previous sections, you'll be able to fight the odds when encountering PHP module source files.
Now, in the following sections, read on about how to make use of PHP's internals to build powerful extensions.
Chapitre 33. Accepting Arguments
One of the most important issues for language extensions is accepting and dealing with data passed via arguments. Most extensions are built to deal with specific input data (or require parameters to perform their specific actions), and function arguments are the only real way to exchange data between the PHP level and the C level. Of course, there's also the possibility of exchanging data using predefined global values (which is also discussed later), but this should be avoided by all means, as it's extremely bad practice.
PHP doesn't make use of any formal function declarations; this is why call syntax is always completely dynamic and never checked for errors. Checking for correct call syntax is left to the user code. For example, it's possible to call a function using only one argument at one time and four arguments the next time - both invocations are syntactically absolutely correct.
Determining the Number of Arguments
Since PHP doesn't have formal function definitions with support for call syntax checking, and since PHP features variable arguments, sometimes you need to find out with how many arguments your function has been called. You can use the ZEND_NUM_ARGS macro in this case. In previous versions of PHP, this macro retrieved the number of arguments with which the function has been called based on the function's hash table entry, ht, which is passed in the INTERNAL_FUNCTION_PARAMETERS list. As ht itself now contains the number of arguments that have been passed to the function, ZEND_NUM_ARGS has been stripped down to a dummy macro (see its definition in zend_API.h). But it's still good practice to use it, to remain compatible with future changes in the call interface. Note: The old PHP equivalent of this macro is ARG_COUNT.
The following code checks for the correct number of arguments:
if(ZEND_NUM_ARGS() != 2) WRONG_PARAM_COUNT; |
This macro prints a default error message and then returns to the caller. Its definition can also be found in zend_API.h and looks like this:
ZEND_API void wrong_param_count(void);
#define WRONG_PARAM_COUNT { wrong_param_count(); return; } |
Retrieving Arguments
New parameter parsing API : This chapter documents the new Zend parameter parsing API introduced by Andrei Zmievski. It was introduced in the development stage between PHP 4.0.6 and 4.1.0 .
Parsing parameters is a very common operation and it may get a bit tedious. It would also be nice to have standardized error checking and error messages. Since PHP 4.1.0, there is a way to do just that by using the new parameter parsing API. It greatly simplifies the process of receiving parameteres, but it has a drawback in that it can't be used for functions that expect variable number of parameters. But since the vast majority of functions do not fall into those categories, this parsing API is recommended as the new standard way.
The prototype for parameter parsing function looks like this:
int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...); |
zend_parse_parameters() also performs type conversions whenever possible, so that you always receive the data in the format you asked for. Any type of scalar can be converted to another one, but conversions between complex types (arrays, objects, and resources) and scalar types are not allowed.
If the parameters could be obtained successfully and there were no errors during type conversion, the function will return SUCCESS, otherwise it will return FAILURE. The function will output informative error messages, if the number of received parameters does not match the requested number, or if type conversion could not be performed.
Here are some sample error messages:
Warning - ini_get_all() requires at most 1 parameter, 2 given
Warning - wddx_deserialize() expects parameter 1 to be string, array given |
Here is the full list of type specifiers:
l - long
d - double
s - string (with possible null bytes) and its length
b - boolean
r - resource, stored in zval*
a - array, stored in zval*
o - object (of any class), stored in zval*
O - object (of class specified by class entry), stored in zval*
z - the actual zval*
| - indicates that the remaining parameters are optional. The storage variables corresponding to these parameters should be initialized to default values by the extension, since they will not be touched by the parsing function if the parameters are not passed.
/ - the parsing function will call SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows, to provide a copy of the parameter, unless it's a reference.
! - the parameter it follows can be of specified type or NULL (only applies to a, o, O, r, and z). If NULL value is passed by the user, the storage pointer will be set to NULL.
The best way to illustrate the usage of this function is through examples:
/* Gets a long, a string and its length, and a zval. */
long l;
char *s;
int s_len;
zval *param;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
"lsz", &l, &s, &s_len, ¶m) == FAILURE) {
return;
}
/* Gets an object of class specified by my_ce, and an optional double. */
zval *obj;
double d = 0.5;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
"O|d", &obj, my_ce, &d) == FAILURE) {
return;
}
/* Gets an object or null, and an array.
If null is passed for object, obj will be set to NULL. */
zval *obj;
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &obj, &arr) == FAILURE) {
return;
}
/* Gets a separated array. */
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &arr) == FAILURE) {
return;
}
/* Get only the first three parameters (useful for varargs functions). */
zval *z;
zend_bool b;
zval *r;
if (zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE) {
return;
} |
Note that in the last example we pass 3 for the number of received parameters, instead of ZEND_NUM_ARGS(). What this lets us do is receive the least number of parameters if our function expects a variable number of them. Of course, if you want to operate on the rest of the parameters, you will have to use zend_get_parameters_array_ex() to obtain them.
The parsing function has an extended version that allows for an additional flags argument that controls its actions.
int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...); |
The only flag you can pass currently is ZEND_PARSE_PARAMS_QUIET, which instructs the function to not output any error messages during its operation. This is useful for functions that expect several sets of completely different arguments, but you will have to output your own error messages.
For example, here is how you would get either a set of three longs or a string:
long l1, l2, l3;
char *s;
if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
ZEND_NUM_ARGS() TSRMLS_CC,
"lll", &l1, &l2, &l3) == SUCCESS) {
/* manipulate longs */
} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
ZEND_NUM_ARGS(), "s", &s, &s_len) == SUCCESS) {
/* manipulate string */
} else {
php_error(E_WARNING, "%s() takes either three long values or a string as argument",
get_active_function_name(TSRMLS_C));
return;
} |
With all the abovementioned ways of receiving function parameters you should have a good handle on this process. For even more example, look through the source code for extensions that are shipped with PHP - they illustrate every conceivable situation.
Old way of retrieving arguments (deprecated)
Deprecated parameter parsing API : This API is deprecated and superseded by the new ZEND parameter parsing API.
After having checked the number of arguments, you need to get access to the arguments themselves. This is done with the help of zend_get_parameters_ex():
zval **parameter; if(zend_get_parameters_ex(1, ¶meter) != SUCCESS) WRONG_PARAM_COUNT; |
zend_get_parameters_ex() accepts at least two arguments. The first argument is the number of arguments to retrieve (which should match the number of arguments with which the function has been called; this is why it's important to check for correct call syntax). The second argument (and all following arguments) are pointers to pointers to pointers to zvals. (Confusing, isn't it?) All these pointers are required because Zend works internally with **zval; to adjust a local **zval in our function,zend_get_parameters_ex() requires a pointer to it.
The return value of zend_get_parameters_ex() can either be SUCCESS or FAILURE, indicating (unsurprisingly) success or failure of the argument processing. A failure is most likely related to an incorrect number of arguments being specified, in which case you should exit with WRONG_PARAM_COUNT.
To retrieve more than one argument, you can use a similar snippet:
zval **param1, **param2, **param3, **param4;
if(zend_get_parameters_ex(4, ¶m1, ¶m2, ¶m3, ¶m4) != SUCCESS)
WRONG_PARAM_COUNT; |
zend_get_parameters_ex() only checks whether you're trying to retrieve too many parameters. If the function is called with five arguments, but you're only retrieving three of them with zend_get_parameters_ex(), you won't get an error but will get the first three parameters instead. Subsequent calls of zend_get_parameters_ex() won't retrieve the remaining arguments, but will get the same arguments again.
Dealing with a Variable Number of Arguments/Optional Parameters
If your function is meant to accept a variable number of arguments, the snippets just described are sometimes suboptimal solutions. You have to create a line calling zend_get_parameters_ex() for every possible number of arguments, which is often unsatisfying.
For this case, you can use the function zend_get_parameters_array_ex(), which accepts the number of parameters to retrieve and an array in which to store them:
zval **parameter_array[4];
/* get the number of arguments */
argument_count = ZEND_NUM_ARGS();
/* see if it satisfies our minimal request (2 arguments) */
/* and our maximal acceptance (4 arguments) */
if(argument_count < 2 || argument_count > 5)
WRONG_PARAM_COUNT;
/* argument count is correct, now retrieve arguments */
if(zend_get_parameters_array_ex(argument_count, parameter_array) != SUCCESS)
WRONG_PARAM_COUNT; |
A very clever implementation of this can be found in the code handling PHP's fsockopen() located in ext/standard/fsock.c, as shown in Exemple 33-1. Don't worry if you don't know all the functions used in this source yet; we'll get to them shortly.
Exemple 33-1. PHP's implementation of variable arguments in fsockopen().
|
fsockopen() accepts two, three, four, or five parameters. After the obligatory variable declarations, the function checks for the correct range of arguments. Then it uses a fall-through mechanism in a switch() statement to deal with all arguments. The switch() statement starts with the maximum number of arguments being passed (five). After that, it automatically processes the case of four arguments being passed, then three, by omitting the otherwise obligatory break keyword in all stages. After having processed the last case, it exits the switch() statement and does the minimal argument processing needed if the function is invoked with only two arguments.
This multiple-stage type of processing, similar to a stairway, allows convenient processing of a variable number of arguments.
Accessing Arguments
To access arguments, it's necessary for each argument to have a clearly defined type. Again, PHP's extremely dynamic nature introduces some quirks. Because PHP never does any kind of type checking, it's possible for a caller to pass any kind of data to your functions, whether you want it or not. If you expect an integer, for example, the caller might pass an array, and vice versa - PHP simply won't notice.
To work around this, you have to use a set of API functions to force a type conversion on every argument that's being passed (see Tableau 33-1).
Note: All conversion functions expect a **zval as parameter.
Tableau 33-1. Argument Conversion Functions
| Function | Description |
| convert_to_boolean_ex() | Forces conversion to a Boolean type. Boolean values remain untouched. Longs, doubles, and strings containing 0 as well as NULL values will result in Boolean 0 (FALSE). Arrays and objects are converted based on the number of entries or properties, respectively, that they have. Empty arrays and objects are converted to FALSE; otherwise, to TRUE. All other values result in a Boolean 1 (TRUE). |
| convert_to_long_ex() | Forces conversion to a long, the default integer type. NULL values, Booleans, resources, and of course longs remain untouched. Doubles are truncated. Strings containing an integer are converted to their corresponding numeric representation, otherwise resulting in 0. Arrays and objects are converted to 0 if empty, 1 otherwise. |
| convert_to_double_ex() | Forces conversion to a double, the default floating-point type. NULL values, Booleans, resources, longs, and of course doubles remain untouched. Strings containing a number are converted to their corresponding numeric representation, otherwise resulting in 0.0. Arrays and objects are converted to 0.0 if empty, 1.0 otherwise. |
| convert_to_string_ex() | Forces conversion to a string. Strings remain untouched. NULL values are converted to an empty string. Booleans containing TRUE are converted to "1", otherwise resulting in an empty string. Longs and doubles are converted to their corresponding string representation. Arrays are converted to the string "Array" and objects to the string "Object". |
| convert_to_array_ex(value) | Forces conversion to an array. Arrays remain untouched. Objects are converted to an array by assigning all their properties to the array table. All property names are used as keys, property contents as values. NULL values are converted to an empty array. All other values are converted to an array that contains the specific source value in the element with the key 0. |
| convert_to_object_ex(value) | Forces conversion to an object. Objects remain untouched. NULL values are converted to an empty object. Arrays are converted to objects by introducing their keys as properties into the objects and their values as corresponding property contents in the object. All other types result in an object with the property scalar , having the corresponding source value as content. |
| convert_to_null_ex(value) | Forces the type to become a NULL value, meaning empty. |
Note : You can find a demonstration of the behavior in cross_conversion.php on the accompanying CD-ROM. Figure 33-2 shows the output.
Using these functions on your arguments will ensure type safety for all data that's passed to you. If the supplied type doesn't match the required type, PHP forces dummy contents on the resulting value (empty strings, arrays, or objects, 0 for numeric values, FALSE for Booleans) to ensure a defined state.
Following is a quote from the sample module discussed previously, which makes use of the conversion functions:
zval **parameter;
if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, ¶meter) != SUCCESS))
{
WRONG_PARAM_COUNT;
}
convert_to_long_ex(parameter);
RETURN_LONG(Z_LVAL_P(parameter)); |
Exemple 33-2. PHP/Zend zval type definition.
|
Actually, pval (defined in php.h) is only an alias of zval (defined in zend.h), which in turn refers to _zval_struct. This is a most interesting structure. _zval_struct is the "master" structure, containing the value structure, type, and reference information. The substructure zvalue_value is a union that contains the variable's contents. Depending on the variable's type, you'll have to access different members of this union. For a description of both structures, see Tableau 33-2, Tableau 33-3 and Tableau 33-4.
Tableau 33-2. Zend zval Structure
| Entry | Description |
| value | Union containing this variable's contents. See Tableau 33-3 for a description. |
| type | Contains this variable's type. For a list of available types, see Tableau 33-4. |
| is_ref | 0 means that this variable is not a reference; 1 means that this variable is a reference to another variable. |
| refcount | The number of references that exist for this variable. For every new reference to the value stored in this variable, this counter is increased by 1. For every lost reference, this counter is decreased by 1. When the reference counter reaches 0, no references exist to this value anymore, which causes automatic freeing of the value. |
Tableau 33-3. Zend zvalue_value Structure
| Entry | Description |
| lval | Use this property if the variable is of the type IS_LONG, IS_BOOLEAN, or IS_RESOURCE. |
| dval | Use this property if the variable is of the type IS_DOUBLE. |
| str | This structure can be used to access variables of the type IS_STRING. The member len contains the string length; the member val points to the string itself. Zend uses C strings; thus, the string length contains a trailing 0x00. |
| ht | This entry points to the variable's hash table entry if the variable is an array. |
| obj | Use this property if the variable is of the type IS_OBJECT. |
Tableau 33-4. Zend Variable Type Constants
| Constant | Description |
| IS_NULL | Denotes a NULL (empty) value. |
| IS_LONG | A long (integer) value. |
| IS_DOUBLE | A double (floating point) value. |
| IS_STRING | A string. |
| IS_ARRAY | Denotes an array. |
| IS_OBJECT | An object. |
| IS_BOOL | A Boolean value. |
| IS_RESOURCE | A resource (for a discussion of resources, see the appropriate section below). |
| IS_CONSTANT | A constant (defined) value. |
To access a long you access zval.value.lval, to access a double you use zval.value.dval, and so on. Because all values are stored in a union, trying to access data with incorrect union members results in meaningless output.
Accessing arrays and objects is a bit more complicated and is discussed later.
Dealing with Arguments Passed by Reference
If your function accepts arguments passed by reference that you intend to modify, you need to take some precautions.
What we didn't say yet is that under the circumstances presented so far, you don't have write access to any zval containers designating function parameters that have been passed to you. Of course, you can change any zval containers that you created within your function, but you mustn't change any zvals that refer to Zend-internal data!
We've only discussed the so-called *_ex() API so far. You may have noticed that the API functions we've used are called zend_get_parameters_ex() instead of zend_get_parameters(), convert_to_long_ex() instead of convert_to_long(), etc. The *_ex() functions form the so-called new "extended" Zend API. They give a minor speed increase over the old API, but as a tradeoff are only meant for providing read-only access.
Because Zend works internally with references, different variables may reference the same value. Write access to a zval container requires this container to contain an isolated value, meaning a value that's not referenced by any other containers. If a zval container were referenced by other containers and you changed the referenced zval, you would automatically change the contents of the other containers referencing this zval (because they'd simply point to the changed value and thus change their own value as well).
zend_get_parameters_ex() doesn't care about this situation, but simply returns a pointer to the desired zval containers, whether they consist of references or not. Its corresponding function in the traditional API, zend_get_parameters(), immediately checks for referenced values. If it finds a reference, it creates a new, isolated zval container; copies the referenced data into this newly allocated space; and then returns a pointer to the new, isolated value.
This action is called zval separation (or pval separation). Because the *_ex() API doesn't perform zval separation, it's considerably faster, while at the same time disabling write access.
To change parameters, however, write access is required. Zend deals with this situation in a special way: Whenever a parameter to a function is passed by reference, it performs automatic zval separation. This means that whenever you're calling a function like this in PHP, Zend will automatically ensure that $parameter is being passed as an isolated value, rendering it to a write-safe state:
my_function(&$parameter); |
But this is not the case with regular parameters! All other parameters that are not passed by reference are in a read-only state.
This requires you to make sure that you're really working with a reference - otherwise you might produce unwanted results. To check for a parameter being passed by reference, you can use the macro PZVAL_IS_REF. This macro accepts a zval* to check if it is a reference or not. Examples are given in in Exemple 33-3.
Exemple 33-3. Testing for referenced parameter passing.
|
Assuring Write Safety for Other Parameters
You might run into a situation in which you need write access to a parameter that's retrieved with zend_get_parameters_ex() but not passed by reference. For this case, you can use the macro SEPARATE_ZVAL, which does a zval separation on the provided container. The newly generated zval is detached from internal data and has only a local scope, meaning that it can be changed or destroyed without implying global changes in the script context:
zval **parameter;
/* retrieve parameter */
zend_get_parameters_ex(1, ¶meter);
/* at this stage, <parameter> still is connected */
/* to Zend's internal data buffers */
/* make <parameter> write-safe */
SEPARATE_ZVAL(parameter);
/* now we can safely modify <parameter> */
/* without implying global changes */ |
Note: As you can easily work around the lack of write access in the "traditional" API (with zend_get_parameters() and so on), this API seems to be obsolete, and is not discussed further in this chapter.
Chapitre 34. Creating Variables
When exchanging data from your own extensions with PHP scripts, one of the most important issues is the creation of variables. This section shows you how to deal with the variable types that PHP supports.
Overview
To create new variables that can be seen "from the outside" by the executing script, you need to allocate a new zval container, fill this container with meaningful values, and then introduce it to Zend's internal symbol table. This basic process is common to all variable creations:
zval *new_variable; /* allocate and initialize new container */ MAKE_STD_ZVAL(new_variable); /* set type and variable contents here, see the following sections */ /* introduce this variable by the name "new_variable_name" into the symbol table */ ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); /* the variable is now accessible to the script by using $new_variable_name */ |
The macro MAKE_STD_ZVAL allocates a new zval container using ALLOC_ZVAL and initializes it using INIT_ZVAL. As implemented in Zend at the time of this writing, initializing means setting the reference count to 1 and clearing the is_ref flag, but this process could be extended later - this is why it's a good idea to keep using MAKE_STD_ZVAL instead of only using ALLOC_ZVAL. If you want to optimize for speed (and you don't have to explicitly initialize the zval container here), you can use ALLOC_ZVAL, but this isn't recommended because it doesn't ensure data integrity.
ZEND_SET_SYMBOL takes care of introducing the new variable to Zend's symbol table. This macro checks whether the value already exists in the symbol table and converts the new symbol to a reference if so (with automatic deallocation of the old zval container). This is the preferred method if speed is not a crucial issue and you'd like to keep memory usage low.
Note that ZEND_SET_SYMBOL makes use of the Zend executor globals via the macro EG. By specifying EG(active_symbol_table), you get access to the currently active symbol table, dealing with the active, local scope. The local scope may differ depending on whether the function was invoked from within a function.
If you need to optimize for speed and don't care about optimal memory usage, you can omit the check for an existing variable with the same value and instead force insertion into the symbol table by using zend_hash_update():
zval *new_variable;
/* allocate and initialize new container */
MAKE_STD_ZVAL(new_variable);
/* set type and variable contents here, see the following sections */
/* introduce this variable by the name "new_variable_name" into the symbol table */
zend_hash_update(
EG(active_symbol_table),
"new_variable_name",
strlen("new_variable_name") + 1,
&new_variable,
sizeof(zval *),
NULL
); |
The variables generated with the snippet above will always be of local scope, so they reside in the context in which the function has been called. To create new variables in the global scope, use the same method but refer to another symbol table:
zval *new_variable;
// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);
//
// set type and variable contents here
//
// introduce this variable by the name "new_variable_name" into the global symbol table
ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable); |
Note: The active_symbol_table variable is a pointer, but symbol_table is not. This is why you have to use EG(active_symbol_table) and &EG(symbol_table) as parameters to ZEND_SET_SYMBOL - it requires a pointer.
Similarly, to get a more efficient version, you can hardcode the symbol table update:
zval *new_variable;
// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);
//
// set type and variable contents here
//
// introduce this variable by the name "new_variable_name" into the global symbol table
zend_hash_update(
&EG(symbol_table),
"new_variable_name",
strlen("new_variable_name") + 1,
&new_variable,
sizeof(zval *),
NULL
); |
Note: You can see that the global variable is actually not accessible from within the function. This is because it's not imported into the local scope using global $global_variable; in the PHP source.
Exemple 34-1. Creating variables with different scopes.
|
Longs (Integers)
Now let's get to the assignment of data to variables, starting with longs. Longs are PHP's integers and are very simple to store. Looking at the zval.value container structure discussed earlier in this chapter, you can see that the long data type is directly contained in the union, namely in the lval field. The corresponding type value for longs is IS_LONG (see Exemple 34-2).
zval *new_long; MAKE_STD_ZVAL(new_long); ZVAL_LONG(new_long, 10); |
Doubles (Floats)
Doubles are PHP's floats and are as easy to assign as longs, because their value is also contained directly in the union. The member in the zval.value container is dval; the corresponding type is IS_DOUBLE.
zval *new_double; MAKE_STD_ZVAL(new_double); new_double->type = IS_DOUBLE; new_double->value.dval = 3.45; |
zval *new_double; MAKE_STD_ZVAL(new_double); ZVAL_DOUBLE(new_double, 3.45); |
Strings
Strings need slightly more effort. As mentioned earlier, all strings that will be associated with Zend's internal data structures need to be allocated using Zend's own memory-management functions. Referencing of static strings or strings allocated with standard routines is not allowed. To assign strings, you have to access the structure str in the zval.value container. The corresponding type is IS_STRING:
zval *new_string; char *string_contents = "This is a new string variable"; MAKE_STD_ZVAL(new_string); new_string->type = IS_STRING; new_string->value.str.len = strlen(string_contents); new_string->value.str.val = estrdup(string_contents); |
zval *new_string; char *string_contents = "This is a new string variable"; MAKE_STD_ZVAL(new_string); ZVAL_STRING(new_string, string_contents, 1); |
If you want to truncate the string at a certain position or you already know its length, you can use ZVAL_STRINGL(zval, string, length, duplicate), which accepts an explicit string length to be set for the new string. This macro is faster than ZVAL_STRING and also binary-safe.
To create empty strings, set the string length to 0 and use empty_string as contents:
new_string->type = IS_STRING; new_string->value.str.len = 0; new_string->value.str.val = empty_string; |
MAKE_STD_ZVAL(new_string); ZVAL_EMPTY_STRING(new_string); |
Booleans
Booleans are created just like longs, but have the type IS_BOOL. Allowed values in lval are 0 and 1:
zval *new_bool; MAKE_STD_ZVAL(new_bool); new_bool->type = IS_BOOL; new_bool->value.lval = 1; |
Arrays
Arrays are stored using Zend's internal hash tables, which can be accessed using the zend_hash_*() API. For every array that you want to create, you need a new hash table handle, which will be stored in the ht member of the zval.value container.
There's a whole API solely for the creation of arrays, which is extremely handy. To start a new array, you call array_init().
zval *new_array;
MAKE_STD_ZVAL(new_array);
if(array_init(new_array) != SUCCESS)
{
// do error handling here
} |
To add new elements to the array, you can use numerous functions, depending on what you want to do. Tableau 34-1, Tableau 34-2 and Tableau 34-3 describe these functions. All functions return FAILURE on failure and SUCCESS on success.
Tableau 34-1. Zend's API for Associative Arrays
| Function | Description |
| add_assoc_long(zval *array, char *key, long n);() | Adds an element of type long. |
| add_assoc_unset(zval *array, char *key);() | Adds an unset element. |
| add_assoc_bool(zval *array, char *key, int b);() | Adds a Boolean element. |
| add_assoc_resource(zval *array, char *key, int r);() | Adds a resource to the array. |
| add_assoc_double(zval *array, char *key, double d);() | Adds a floating-point value. |
| add_assoc_string(zval *array, char *key, char *str, int duplicate);() | Adds a string to the array. The flag duplicate specifies whether the string contents have to be copied to Zend internal memory. |
| add_assoc_stringl(zval *array, char *key, char *str, uint length, int duplicate); () | Adds a string with the desired length length to the array. Otherwise, behaves like add_assoc_string(). |
Tableau 34-2. Zend's API for Indexed Arrays, Part 1
| Function | Description |
| add_index_long(zval *array, uint idx, long n);() | Adds an element of type long. |
| add_index_unset(zval *array, uint idx);() | Adds an unset element. |
| add_index_bool(zval *array, uint idx, int b);() | Adds a Boolean element. |
| add_index_resource(zval *array, uint idx, int r);() | Adds a resource to the array. |
| add_index_double(zval *array, uint idx, double d);() | Adds a floating-point value. |
| add_index_string(zval *array, uint idx, char *str, int duplicate);() | Adds a string to the array. The flag duplicate specifies whether the string contents have to be copied to Zend internal memory. |
| add_index_stringl(zval *array, uint idx, char *str, uint length, int duplicate);() | Adds a string with the desired length length to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()(). |
Tableau 34-3. Zend's API for Indexed Arrays, Part 2
| Function | Description |
| add_next_index_long(zval *array, long n);() | Adds an element of type long. |
| add_next_index_unset(zval *array);() | Adds an unset element. |
| add_next_index_bool(zval *array, int b);() | Adds a Boolean element. |
| add_next_index_resource(zval *array, int r);() | Adds a resource to the array. |
| add_next_index_double(zval *array, double d);() | Adds a floating-point value. |
| add_next_index_string(zval *array, char *str, int duplicate);() | Adds a string to the array. The flag duplicate specifies whether the string contents have to be copied to Zend internal memory. |
| add_next_index_stringl(zval *array, char *str, uint length, int duplicate);() | Adds a string with the desired length length to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()(). |
All these functions provide a handy abstraction to Zend's internal hash API. Of course, you can also use the hash functions directly - for example, if you already have a zval container allocated that you want to insert into an array. This is done using zend_hash_update()() for associative arrays (see Exemple 34-3) and zend_hash_index_update() for indexed arrays (see Exemple 34-4):
Exemple 34-3. Adding an element to an associative array.
|
Exemple 34-4. Adding an element to an indexed array.
|
To emulate the functionality of add_next_index_*(), you can use this:
zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL) |
Note: To return arrays from a function, use array_init() and all following actions on the predefined variable return_value (given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use MAKE_STD_ZVAL on this.
Tip: To avoid having to write new_array->value.ht every time, you can use HASH_OF(new_array), which is also recommended for compatibility and style reasons.
Objects
Since objects can be converted to arrays (and vice versa), you might have already guessed that they have a lot of similarities to arrays in PHP. Objects are maintained with the same hash functions, but there's a different API for creating them.
To initialize an object, you use the function object_init():
zval *new_object;
MAKE_STD_ZVAL(new_object);
if(object_init(new_object) != SUCCESS)
{
// do error handling here
} |
Tableau 34-4. Zend's API for Object Creation
| Function | Description |
| add_property_long(zval *object, char *key, long l);() | Adds a long to the object. |
| add_property_unset(zval *object, char *key);() | Adds an unset property to the object. |
| add_property_bool(zval *object, char *key, int b);() | Adds a Boolean to the object. |
| add_property_resource(zval *object, char *key, long r);() | Adds a resource to the object. |
| add_property_double(zval *object, char *key, double d);() | Adds a double to the object. |
| add_property_string(zval *object, char *key, char *str, int duplicate);() | Adds a string to the object. |
| add_property_stringl(zval *object, char *key, char *str, uint length, int duplicate);() | Adds a string of the specified length to the object. This function is faster than add_property_string() and also binary-safe. |
| add_property_zval(zval *obect, char *key, zval *container):() | Adds a zval container to the object. This is useful if you have to add properties which aren't simple types like integers or strings but arrays or other objects. |
Resources
Resources are a special kind of data type in PHP. The term resources doesn't really refer to any special kind of data, but to an abstraction method for maintaining any kind of information. Resources are kept in a special resource list within Zend. Each entry in the list has a correspondending type definition that denotes the kind of resource to which it refers. Zend then internally manages all references to this resource. Access to a resource is never possible directly - only via a provided API. As soon as all references to a specific resource are lost, a corresponding shutdown function is called.
For example, resources are used to store database links and file descriptors. The de facto standard implementation can be found in the MySQL module, but other modules such as the Oracle module also make use of resources.
Note : In fact, a resource can be a pointer to anything you need to handle in your functions (e.g. pointer to a structure) and the user only has to pass a single resource variable to your function.
To create a new resource you need to register a resource destruction handler for it. Since you can store any kind of data as a resource, Zend needs to know how to free this resource if its not longer needed. This works by registering your own resource destruction handler to Zend which in turn gets called by Zend whenever your resource can be freed (whether manually or automatically). Registering your resource handler within Zend returns you the resource type handle for that resource. This handle is needed whenever you want to access a resource of this type later and is most of time stored in a global static variable within your extension. There is no need to worry about thread safety here because you only register your resource handler once during module initialization.
The Zend function to register your resource handler is defined as:
ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number); |
There are two different kinds of resource destruction handlers you can pass to this function: a handler for normal resources and a handler for persistent resources. Persistent resources are for example used for database connection. When registering a resource, either of these handlers must be given. For the other handler just pass NULL.
zend_register_list_destructors_ex() accepts the following parameters:
| ld | Normal resource destruction handler callback |
| pld | Pesistent resource destruction handler callback |
| type_name | A string specifying the name of your resource. It's always a good thing to specify an unique name within PHP for the resource type so when the user for example calls var_dump($resource); he also gets the name of the resource. |
| module_number | The module_number is automatically available in your PHP_MINIT_FUNCTION function and therefore you just pass it over. |
The resource destruction handler (either normal or persistent resources) has the following prototype:
void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC); |
typedef struct _zend_rsrc_list_entry {
void *ptr;
int type;
int refcount;
} zend_rsrc_list_entry; |
Now we know how to start things, we define our own resource we want register within Zend. It is only a simple structure with two integer members:
typedef struct {
int resource_link;
int resource_type;
} my_resource; |
void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
// You most likely cast the void pointer to your structure type
my_resource *my_rsrc = (my_resource *) rsrc->ptr;
// Now do whatever needs to be done with you resource. Closing
// Files, Sockets, freeing additional memory, etc.
// Also, don't forget to actually free the memory for your resource too!
do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
} |
Note : One important thing to mention: If your resource is a rather complex structure which also contains pointers to memory you allocated during runtime you have to free them before freeing the resource itself!
Now that we have defined
what our resource is and
our resource destruction handler
create a global variable within the extension holding the resource ID so it can be accessed from every function which needs it
define the resource name
write the resource destruction handler
and finally register the handler
// Somewhere in your extension, define the variable for your registered resources.
// If you wondered what 'le' stands for: it simply means 'list entry'.
static int le_myresource;
// It's nice to define your resource name somewhere
#define le_myresource_name "My type of resource"
[...]
// Now actually define our resource destruction handler
void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
my_resource *my_rsrc = (my_resource *) rsrc->ptr;
do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}
[...]
PHP_MINIT_FUNCTION(my_extension) {
// Note that 'module_number' is already provided through the
// PHP_MINIT_FUNCTION() function definition.
le_myresource = zend_register_resource_destructors_ex(my_destruction_handler, NULL, le_myresource_name, module_number);
// You can register additional resources, initialize
// your global vars, constants, whatever.
} |
To actually register a new resource you use can either use the zend_register_resource() function or the ZEND_REGISTER_RESOURE() macro, both defined in zend_list.h . Although the arguments for both map 1:1 it's a good idea to always use macros to be upwards compatible:
int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type); |
| rsrc_result | This is an already initialized zval * container. |
| rsrc_pointer | Your resource pointer you want to store. |
| rsrc_type | The type which you received when you registered the resource destruction handler. If you followed the naming scheme this would be le_myresource. |
What is really going on when you register a new resource is it gets inserted in an internal list in Zend and the result is just stored in the given zval * container:
rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);
if (rsrc_result) {
rsrc_result->value.lval = rsrc_id;
rsrc_result->type = IS_RESOURCE;
}
return rsrc_id; |
RETURN_RESOURCE(rsrc_id) |
Note : It is common practice that if you want to return the resource immidiately to the user you specify the return_value as the zval * container.
Zend now keeps track of all references to this resource. As soon as all references to the resource are lost, the destructor that you previously registered for this resource is called. The nice thing about this setup is that you don't have to worry about memory leakages introduced by allocations in your module - just register all memory allocations that your calling script will refer to as resources. As soon as the script decides it doesn't need them anymore, Zend will find out and tell you.
Now that the user got his resource, at some point he is passing it back to one of your functions. The value.lval inside the zval * container contains the key to your resource and thus can be used to fetch the resource with the following macro: ZEND_FETCH_RESOURCE:
ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type) |
| rsrc | This is your pointer which will point to your previously registered resource. |
| rsrc_type | This is the typecast argument for your pointer, e.g. myresource *. |
| rsrc_id | This is the address of the zval *container the user passed to your function, e.g. &z_resource if zval *z_resource is given. |
| default_rsrc_id | This integer specifies the default resource ID if no resource could be fetched or -1. |
| resource_type_name | This is the name of the requested resource. It's a string and is used when the resource can't be found or is invalid to form a meaningful error message. |
| resource_type | The resource_type you got back when registering the resource destruction handler. In our example this was le_myresource. |
To force removal of a resource from the list, use the function zend_list_delete(). You can also force the reference count to increase if you know that you're creating another reference for a previously allocated value (for example, if you're automatically reusing a default database link). For this case, use the function zend_list_addref(). To search for previously allocated resource entries, use zend_list_find(). The complete API can be found in zend_list.h.
Macros for Automatic Global Variable Creation
In addition to the macros discussed earlier, a few macros allow easy creation of simple global variables. These are nice to know in case you want to introduce global flags, for example. This is somewhat bad practice, but Table Tableau 34-5 describes macros that do exactly this task. They don't need any zval allocation; you simply have to supply a variable name and value.
Tableau 34-5. Macros for Global Variable Creation
| Macro | Description |
| SET_VAR_STRING(name, value) | Creates a new string. |
| SET_VAR_STRINGL(name, value, length) | Creates a new string of the specified length. This macro is faster than SET_VAR_STRING and also binary-safe. |
| SET_VAR_LONG(name, value) | Creates a new long. |
| SET_VAR_DOUBLE(name, value) | Creates a new double. |
Creating Constants
Zend supports the creation of true constants (as opposed to regular variables). Constants are accessed without the typical dollar sign ($) prefix and are available in all scopes. Examples include TRUE and FALSE, to name just two.
To create your own constants, you can use the macros in Tableau 34-6. All the macros create a constant with the specified name and value.
You can also specify flags for each constant:
CONST_CS - This constant's name is to be treated as case sensitive.
CONST_PERSISTENT - This constant is persistent and won't be "forgotten" when the current process carrying this constant shuts down.
// register a new constant of type "long"
REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS |
CONST_PERSISTENT); |
Tableau 34-6. Macros for Creating Constants
| Macro | Description |
| REGISTER_LONG_CONSTANT(name, value, flags) REGISTER_MAIN_LONG_CONSTANT(name, value, flags) | Registers a new constant of type long. |
| REGISTER_DOUBLE_CONSTANT(name, value, flags) REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags) | Registers a new constant of type double. |
| REGISTER_STRING_CONSTANT(name, value, flags) REGISTER_MAIN_STRING_CONSTANT(name, value, flags) | Registers a new constant of type string. The specified string must reside in Zend's internal memory. |
| REGISTER_STRINGL_CONSTANT(name, value, length, flags) REGISTER_MAIN_STRINGL_CONSTANT(name, value, length, flags) | Registers a new constant of type string. The string length is explicitly set to length. The specified string must reside in Zend's internal memory. |
Chapitre 35. Duplicating Variable Contents: The Copy Constructor
Sooner or later, you may need to assign the contents of one zval container to another. This is easier said than done, since the zval container doesn't contain only type information, but also references to places in Zend's internal data. For example, depending on their size, arrays and objects may be nested with lots of hash table entries. By assigning one zval to another, you avoid duplicating the hash table entries, using only a reference to them (at most).
To copy this complex kind of data, use the copy constructor. Copy constructors are typically defined in languages that support operator overloading, with the express purpose of copying complex types. If you define an object in such a language, you have the possibility of overloading the "=" operator, which is usually responsible for assigning the contents of the lvalue (result of the evaluation of the left side of the operator) to the rvalue (same for the right side).
Overloading means assigning a different meaning to this operator, and is usually used to assign a function call to an operator. Whenever this operator would be used on such an object in a program, this function would be called with the lvalue and rvalue as parameters. Equipped with that information, it can perform the operation it intends the "=" operator to have (usually an extended form of copying).
This same form of "extended copying" is also necessary for PHP's zval containers. Again, in the case of an array, this extended copying would imply re-creation of all hash table entries relating to this array. For strings, proper memory allocation would have to be assured, and so on.
Zend ships with such a function, called zend_copy_ctor() (the previous PHP equivalent was pval_copy_constructor()).
A most useful demonstration is a function that accepts a complex type as argument, modifies it, and then returns the argument:
zval *parameter; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", ¶meter) == FAILURE) return; } // do modifications to the parameter here // now we want to return the modified container: *return_value == *parameter; zval_copy_ctor(return_value); |
The first part of the function is plain-vanilla argument retrieval. After the (left out) modifications, however, it gets interesting: The container of parameter is assigned to the (predefined) return_value container. Now, in order to effectively duplicate its contents, the copy constructor is called. The copy constructor works directly with the supplied argument, and the standard return values are FAILURE on failure and SUCCESS on success.
If you omit the call to the copy constructor in this example, both parameter and return_value would point to the same internal data, meaning that return_value would be an illegal additional reference to the same data structures. Whenever changes occurred in the data that parameter points to, return_value might be affected. Thus, in order to create separate copies, the copy constructor must be used.
The copy constructor's counterpart in the Zend API, the destructor zval_dtor(), does the opposite of the constructor.
Chapitre 36. Returning Values
Returning values from your functions to PHP was described briefly in an earlier section; this section gives the details. Return values are passed via the return_value variable, which is passed to your functions as argument. The return_value argument consists of a zval container (see the earlier discussion of the call interface) that you can freely modify. The container itself is already allocated, so you don't have to run MAKE_STD_ZVAL on it. Instead, you can access its members directly.
To make returning values from functions easier and to prevent hassles with accessing the internal structures of the zval container, a set of predefined macros is available (as usual). These macros automatically set the correspondent type and value, as described in Tableau 36-1 and Tableau 36-2.
Note : The macros in Tableau 36-1 automatically return from your function, those in Tableau 36-2 only set the return value; they don't return from your function.
Tableau 36-1. Predefined Macros for Returning Values from a Function
| Macro | Description |
| RETURN_RESOURCE(resource) | Returns a resource. |
| RETURN_BOOL(bool) | Returns a Boolean. |
| RETURN_NULL() | Returns nothing (a NULL value). |
| RETURN_LONG(long) | Returns a long. |
| RETURN_DOUBLE(double) | Returns a double. |
| RETURN_STRING(string, duplicate) | Returns a string. The duplicate flag indicates whether the string should be duplicated using estrdup(). |
| RETURN_STRINGL(string, length, duplicate) | Returns a string of the specified length; otherwise, behaves like RETURN_STRING. This macro is faster and binary-safe, however. |
| RETURN_EMPTY_STRING() | Returns an empty string. |
| RETURN_FALSE | Returns Boolean false. |
| RETURN_TRUE | Returns Boolean true. |
Tableau 36-2. Predefined Macros for Setting the Return Value of a Function
| Macro | Description |
| RETVAL_RESOURCE(resource) | Sets the return value to the specified resource. |
| RETVAL_BOOL(bool) | Sets the return value to the specified Boolean value. |
| RETVAL_NULL | Sets the return value to NULL. |
| RETVAL_LONG(long) | Sets the return value to the specified long. |
| RETVAL_DOUBLE(double) | Sets the return value to the specified double. |
| RETVAL_STRING(string, duplicate) | Sets the return value to the specified string and duplicates it to Zend internal memory if desired (see also RETURN_STRING). |
| RETVAL_STRINGL(string, length, duplicate) | Sets the return value to the specified string and forces the length to become length (see also RETVAL_STRING). This macro is faster and binary-safe, and should be used whenever the string length is known. |
| RETVAL_EMPTY_STRING | Sets the return value to an empty string. |
| RETVAL_FALSE | Sets the return value to Boolean false. |
| RETVAL_TRUE | Sets the return value to Boolean true. |
Complex types such as arrays and objects can be returned by using array_init() and object_init(), as well as the corresponding hash functions on return_value. Since these types cannot be constructed of trivial information, there are no predefined macros for them.
Chapitre 37. Printing Information
Often it's necessary to print messages to the output stream from your module, just as print() would be used within a script. PHP offers functions for most generic tasks, such as printing warning messages, generating output for phpinfo(), and so on. The following sections provide more details. Examples of these functions can be found on the CD-ROM.
zend_printf()
zend_printf() works like the standard printf(), except that it prints to Zend's output stream.
zend_error()
zend_error() can be used to generate error messages. This function accepts two arguments; the first is the error type (see zend_errors.h), and the second is the error message.
zend_error(E_WARNING, "This function has been called with empty arguments"); |
Tableau 37-1. Zend's Predefined Error Messages.
| Error | Description |
| E_ERROR | Signals an error and terminates execution of the script immediately . |
| E_WARNING | Signals a generic warning. Execution continues. |
| E_PARSE | Signals a parser error. Execution continues. |
| E_NOTICE | Signals a notice. Execution continues. Note that by default the display of this type of error messages is turned off in php.ini. |
| E_CORE_ERROR | Internal error by the core; shouldn't be used by user-written modules. |
| E_COMPILE_ERROR | Internal error by the compiler; shouldn't be used by user-written modules. |
| E_COMPILE_WARNING | Internal warning by the compiler; shouldn't be used by user-written modules. |
Including Output in phpinfo()
After creating a real module, you'll want to show information about the module in phpinfo() (in addition to the module name, which appears in the module list by default). PHP allows you to create your own section in the phpinfo() output with the ZEND_MINFO() function. This function should be placed in the module descriptor block (discussed earlier) and is always called whenever a script calls phpinfo().
PHP automatically prints a section in phpinfo() for you if you specify the ZEND_MINFO function, including the module name in the heading. Everything else must be formatted and printed by you.
Typically, you can print an HTML table header using php_info_print_table_start() and then use the standard functions php_info_print_table_header() and php_info_print_table_row(). As arguments, both take the number of columns (as integers) and the column contents (as strings). Exemple 37-1 shows a source example and its output. To print the table footer, use php_info_print_table_end().
Exemple 37-1. Source code and screenshot for output in phpinfo().
|
Execution Information
You can also print execution information, such as the current file being executed. The name of the function currently being executed can be retrieved using the function get_active_function_name(). This function returns a pointer to the function name and doesn't accept any arguments. To retrieve the name of the file currently being executed, use zend_get_executed_filename(). This function accesses the executor globals, which are passed to it using the TSRMLS_C macro. The executor globals are automatically available to every function that's called directly by Zend (they're part of the INTERNAL_FUNCTION_PARAMETERS described earlier in this chapter). If you want to access the executor globals in another function that doesn't have them available automatically, call the macro TSRMLS_FETCH() once in that function; this will introduce them to your local scope.
Finally, the line number currently being executed can be retrieved using the function zend_get_executed_lineno(). This function also requires the executor globals as arguments. For examples of these functions, see Exemple 37-2.
Exemple 37-2. Printing execution information.
|
Chapitre 38. Startup and Shutdown Functions
Startup and shutdown functions can be used for one-time initialization and deinitialization of your modules. As discussed earlier in this chapter (see the description of the Zend module descriptor block), there are global, module, and request startup and shutdown events.
The global startup functions are called once when PHP starts up; similarly, the global shutdown functions are called once when PHP shuts down. Please note that they're really only called once, not when a new Apache process is being created!
The module startup and shutdown functions are called whenever a module is loaded and needs initialization; the request startup and shutdown functions are called every time a request is processed (meaning that a file is being executed).
For dynamic extensions, module and request startup/shutdown events happen at the same time.
Declaration and implementation of these functions can be done with macros; see the earlier section "Declaration of the Zend Module Block" for details.
Chapitre 39. Calling User Functions
You can call user functions from your own modules, which is very handy when implementing callbacks; for example, for array walking, searching, or simply for event-based programs.
User functions can be called with the function call_user_function_ex(). It requires a hash value for the function table you want to access, a pointer to an object (if you want to call a method), the function name, return value, number of arguments, argument array, and a flag indicating whether you want to perform zval separation.
ZEND_API int call_user_function_ex(HashTable *function_table, zval *object, zval *function_name, zval **retval_ptr_ptr, int param_count, zval **params[], int no_separation); |
Note that you don't have to specify both function_table and object; either will do. If you want to call a method, you have to supply the object that contains this method, in which case call_user_function()automatically sets the function table to this object's function table. Otherwise, you only need to specify function_table and can set object to NULL.
Usually, the default function table is the "root" function table containing all function entries. This function table is part of the compiler globals and can be accessed using the macro CG. To introduce the compiler globals to your function, call the macro TSRMLS_FETCH once.
The function name is specified in a zval container. This might be a bit surprising at first, but is quite a logical step, since most of the time you'll accept function names as parameters from calling functions within your script, which in turn are contained in zval containers again. Thus, you only have to pass your arguments through to this function. This zval must be of type IS_STRING.
The next argument consists of a pointer to the return value. You don't have to allocate memory for this container; the function will do so by itself. However, you have to destroy this container (using zval_dtor()) afterward!
Next is the parameter count as integer and an array containing all necessary parameters. The last argument specifies whether the function should perform zval separation - this should always be set to 0. If set to 1, the function consumes less memory but fails if any of the parameters need separation.
Exemple 39-1 shows a small demonstration of calling a user function. The code calls a function that's supplied to it as argument and directly passes this function's return value through as its own return value. Note the use of the constructor and destructor calls at the end - it might not be necessary to do it this way here (since they should be separate values, the assignment might be safe), but this is bulletproof.
Exemple 39-1. Calling user functions.
|
<?php
dl("call_userland.so");
function test_function()
{
print("We are in the test function!<br>");
return("hello");
}
$return_value = call_userland("test_function");
print("Return value: \"$return_value\"<br>");
?> |
Chapitre 40. Initialization File Support
PHP 4 features a redesigned initialization file support. It's now possible to specify default initialization entries directly in your code, read and change these values at runtime, and create message handlers for change notifications.
To create an .ini section in your own module, use the macros PHP_INI_BEGIN() to mark the beginning of such a section and PHP_INI_END() to mark its end. In between you can use PHP_INI_ENTRY() to create entries.
PHP_INI_BEGIN()
PHP_INI_ENTRY("first_ini_entry", "has_string_value", PHP_INI_ALL, NULL)
PHP_INI_ENTRY("second_ini_entry", "2", PHP_INI_SYSTEM, OnChangeSecond)
PHP_INI_ENTRY("third_ini_entry", "xyz", PHP_INI_USER, NULL)
PHP_INI_END() |
The permissions are grouped into three sections:PHP_INI_SYSTEM allows a change only directly in the php3.ini file; PHP_INI_USER allows a change to be overridden by a user at runtime using additional configuration files, such as .htaccess; and PHP_INI_ALL allows changes to be made without restrictions. There's also a fourth level, PHP_INI_PERDIR, for which we couldn't verify its behavior yet.
The fourth parameter consists of a pointer to a change-notification handler. Whenever one of these initialization entries is changed, this handler is called. Such a handler can be declared using the PHP_INI_MH macro:
PHP_INI_MH(OnChangeSecond); // handler for ini-entry "second_ini_entry"
// specify ini-entries here
PHP_INI_MH(OnChangeSecond)
{
zend_printf("Message caught, our ini entry has been changed to %s<br>", new_value);
return(SUCCESS);
} |
#define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value,
uint new_value_length, void *mh_arg1,
void *mh_arg2, void *mh_arg3) |
The change-notification handlers should be used to cache initialization entries locally for faster access or to perform certain tasks that are required if a value changes. For example, if a constant connection to a certain host is required by a module and someone changes the hostname, automatically terminate the old connection and attempt a new one.
Access to initialization entries can also be handled with the macros shown in Tableau 40-1.
Tableau 40-1. Macros to Access Initialization Entries in PHP
| Macro | Description |
| INI_INT(name) | Returns the current value of entry name as integer (long). |
| INI_FLT(name) | Returns the current value of entry name as float (double). |
| INI_STR(name) | Returns the current value of entry name as string. Note: This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory. |
| INI_BOOL(name) | Returns the current value of entry name as Boolean (defined as zend_bool, which currently means unsigned char). |
| INI_ORIG_INT(name) | Returns the original value of entry name as integer (long). |
| INI_ORIG_FLT(name) | Returns the original value of entry name as float (double). |
| INI_ORIG_STR(name) | Returns the original value of entry name as string. Note: This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory. |
| INI_ORIG_BOOL(name) | Returns the original value of entry name as Boolean (defined as zend_bool, which currently means unsigned char). |
Finally, you have to introduce your initialization entries to PHP. This can be done in the module startup and shutdown functions, using the macros REGISTER_INI_ENTRIES() and UNREGISTER_INI_ENTRIES():
ZEND_MINIT_FUNCTION(mymodule)
{
REGISTER_INI_ENTRIES();
}
ZEND_MSHUTDOWN_FUNCTION(mymodule)
{
UNREGISTER_INI_ENTRIES();
} |
Chapitre 41. Where to Go from Here
You've learned a lot about PHP. You now know how to create dynamic loadable modules and statically linked extensions. You've learned how PHP and Zend deal with internal storage of variables and how you can create and access these variables. You know quite a set of tool functions that do a lot of routine tasks such as printing informational texts, automatically introducing variables to the symbol table, and so on.
Even though this chapter often had a mostly "referential" character, we hope that it gave you insight on how to start writing your own extensions. For the sake of space, we had to leave out a lot; we suggest that you take the time to study the header files and some modules (especially the ones in the ext/standard directory and the MySQL module, as these implement commonly known functionality). This will give you an idea of how other people have used the API functions - particularly those that didn't make it into this chapter.
Chapitre 42. Reference: Some Configuration Macros
config.m4
The file config.m4 is processed by buildconf and must contain all the instructions to be executed during configuration. For example, these can include tests for required external files, such as header files, libraries, and so on. PHP defines a set of macros that can be used in this process, the most useful of which are described in Tableau 42-1.
Tableau 42-1. M4 Macros for config.m4
| Macro | Description |
| AC_MSG_CHECKING(message) | Prints a "checking <message>" text during configure. |
| AC_MSG_RESULT(value) | Gives the result to AC_MSG_CHECKING; should specify either yes or no as value. |
| AC_MSG_ERROR(message) | Prints message as error message during configure and aborts the script. |
| AC_DEFINE(name,value,description) | Adds #define to php_config.h with the value of value and a comment that says description (this is useful for conditional compilation of your module). |
| AC_ADD_INCLUDE(path) | Adds a compiler include path; for example, used if the module needs to add search paths for header files. |
| AC_ADD_LIBRARY_WITH_PATH(libraryname,librarypath) | Specifies an additional library to link. |
| AC_ARG_WITH(modulename,description,unconditionaltest,conditionaltest) | Quite a powerful macro, adding the module with description to the configure --help output. PHP checks whether the option --with-<modulename> is given to the configure script. If so, it runs the script unconditionaltest (for example, --with-myext=yes), in which case the value of the option is contained in the variable $withval. Otherwise, it executes conditionaltest. |
| PHP_EXTENSION(modulename, [shared]) | This macro is a must to call for PHP to configure your extension. You can supply a second argument in addition to your module name, indicating whether you intend compilation as a shared module. This will result in a definition at compile time for your source as COMPILE_DL_<modulename>. |
Chapitre 43. API Macros
A set of macros was introduced into Zend's API that simplify access to zval containers (see Tableau 43-1).
Tableau 43-1. API Macros for Accessing zval Containers
| Macro | Refers to |
| Z_LVAL(zval) | (zval).value.lval |
| Z_DVAL(zval) | (zval).value.dval |
| Z_STRVAL(zval) | (zval).value.str.val |
| Z_STRLEN(zval) | (zval).value.str.len |
| Z_ARRVAL(zval) | (zval).value.ht |
| Z_LVAL_P(zval) | (*zval).value.lval |
| Z_DVAL_P(zval) | (*zval).value.dval |
| Z_STRVAL_P(zval_p) | (*zval).value.str.val |
| Z_STRLEN_P(zval_p) | (*zval).value.str.len |
| Z_ARRVAL_P(zval_p) | (*zval).value.ht |
| Z_LVAL_PP(zval_pp) | (**zval).value.lval |
| Z_DVAL_PP(zval_pp) | (**zval).value.dval |
| Z_STRVAL_PP(zval_pp) | (**zval).value.str.val |
| Z_STRLEN_PP(zval_pp) | (**zval).value.str.len |
| Z_ARRVAL_PP(zval_pp) | (**zval).value.ht |
VI. FAQ : Foire Aux Questions
- Table des matières
- 44. General Information
- 45. Mailing lists
- 46. Obtaining PHP
- 47. Database issues
- 48. Installation
- 49. Build Problems
- 50. Using PHP
- 51. PHP and HTML
- 52. PHP and COM
- 53. PHP and other languages
- 54. Migrating from PHP 2 to PHP 3
- 55. Migrating from PHP 3 to PHP 4
- 56. Miscellaneous Questions
Chapitre 44. General Information
This section holds the most general questions about PHP: what it is and what it does.
- 1. What is PHP?
- 2. What does PHP stand for?
- 3. What is the relation between the versions?
- 4. Can I run several versions of PHP at the same time?
- 5. What are the differences between PHP 3 and PHP 4?
- 6. I think I found a bug! Who should I tell?
From the preface of the manual:
PHP is an HTML-embedded scripting language. Much of its syntax is borrowed from C, Java and Perl with a couple of unique PHP-specific features thrown in. The goal of the language is to allow web developers to write dynamically generated pages quickly.
A nice introduction to PHP by Stig Sæther Bakken can be found here on the Zend website. Also, much of the PHP Conference Material is freely available.
PHP stands for PHP: Hypertext Preprocessor. This confuses many people because the first word of the acronym is the acronym. This type of acronym is called a recursive acronym. The curious can visit Free On-Line Dictionary of Computing for more information on recursive acronyms.
PHP/FI 2.0 is an early and no longer supported version of PHP. PHP 3 is the successor to PHP/FI 2.0 and is a lot nicer. PHP 4 is the latest generation of PHP, which uses the Zend engine under the hood.
Yes. See the INSTALL file that is included in the PHP 4 source distribution. Also, read the related appendix.
There are a couple of articles written on this by the authors of PHP 4. Here's a list of some of the more important new features:
Extended API module
Generalized build process under UNIX
Generic web server interface that also supports multi-threaded web servers
Improved syntax highlighter
Native HTTP session support
Output buffering support
More powerful configuration system
Reference counting
You should go to the PHP Bug Database and make sure the bug isn't a known bug. If you don't see it in the database, use the reporting form to report the bug. It is important to use the bug database instead of just sending an email to one of the mailing lists because the bug will have a tracking number assigned and it will then be possible for you to go back later and check on the status of the bug. The bug database can be found at http://bugs.php.net/.
Chapitre 45. Mailing lists
This section holds questions about how to get in touch with the PHP community. The best way is the mailing lists.
- 1. Are there any PHP mailing lists?
- 2. Are there any other communities?
- 3. Help! I can't seem to subscribe/unsubscribe to/from one of the mailing lists!
- 4. Is there an archive of the mailing lists anywhere?
- 5. What can I ask the mailing list?
- 6. What information should I include when posting to the mailing list?
Of course! There are many mailing lists for several subjects. A whole list of mailing lists can be found on our Support page.
The most general mailing list is php-general. To subscribe, send mail to php-general-subscribe@lists.php.net. You don't need to include anything special in the subject or body of the message. To unsubscribe, send mail to php-general-unsubscribe@lists.php.net.
You can also subscribe and unsubscribe using the web interface on our Support page.
There are countless of them around the world. We have links for example to some IRC servers and foreign language mailing lists on our Support page.
If you have problems subscribing to or unsubscribing from the php-general mailing list, it may be because the mailing list software can't figure out the correct mailing address to use. If your email address was joeblow@example.com, you can send your subscription request to php-general-subscribe-joeblow=example.com@lists.php.net, or your unsubscription request to php-general-unsubscribe-joeblow=example.com@lists.php.net. Use similar addresses for the other mailing lists.
Yes, you will find a list of archive sites on the Support page. The mailing list articles are also archived as news messages. You can access the news server at news://news.php.net/ with a news client. There is also an experimental web interface for the news server at http://news.php.net/
Since PHP is growing more and more popular by the day the traffic has increased on the php-general mailing list and as of now the list gets about 150 to 200 posts a day. Because of this it is in everyones interest that you use the list as a last resort when you have looked everywhere else.
Before you post to the list please have a look in this FAQ and the manual to see if you can find the help there. If there is nothing to be found there try out the mailing list archives (see above). If you're having problem with installing or configuring PHP please read through all included documentation and README's. If you still can't find any information that helps you out you're more than welcome to use the mailing list.
Posts like "I can't get PHP up and running! Help me! What is wrong?" are of absolutely no use to anyone. If you're having problems getting PHP up and running you must include what operating system you are running on, what version of PHP you're trying to set up, how you got it (pre-compiled, CVS, RPMs and so on), what you have done so far, where you got stuck and the exact error message.
This goes for any other problem as well. You have to include information on what you have done, where you got stuck, what you're trying to do and, if applicable, exact error messages. If you're having problems with your source code you need to include the part of the code that isn't working. Do not include more code than necessary though! It makes the post hard to read and a lot of people might just skip it all together because of this. If you're unsure about how much information to include in the mail it's better that you include to much than to little.
Another important thing to remember is to summarize your problem on the subject line. A subject like "HELP MEEEE!!!" or "What is the problem here?" will be ignored by the majority of the readers.
Chapitre 46. Obtaining PHP
This section has details about PHP download locations, and OS issues.
- 1. Where can I obtain PHP?
- 2. Are pre-compiled binary versions available?
- 3. Where can I get libraries needed to compile some of the optional PHP extensions?
- 4. How do I get these libraries to work?
- 5. I got the latest version of the PHP source code from the CVS repository on my Windows machine, what do I need to compile it?
- 6. Where do I find the Browser Capabilities File?
You can download PHP from any of the members of the PHP network of sites. These can be found at http://www.php.net/. You can also use anonymous CVS to get the absolute latest version of the source. For more information, go to http://cvs.php.net/.
We only distribute precompiled binaries for Windows systems, as we are not able to compile PHP for every major Linux/Unix platform with every extension combination. Also note, that many Linux distributions come with PHP built in these days. Windows binaries can be downloaded from our Downloads page, for Linux binaries, please visit your distributions website.
Note : Those marked with * are not thread-safe libraries, and should not be used with PHP as a server module in the multi-threaded Windows web servers (IIS, Netscape). This does not matter in Unix environments, yet.
LDAP (Unix/Win) : Netscape Directory (LDAP) SDK 1.1.
Berkeley DB2 (Unix/Win) : http://www.sleepycat.com/.
Sybase-CT* (Linux, libc5) : Available locally.
You will need to follow instructions provided with the library. Some of these libraries are detected automatically when you run the 'configure' script of PHP (such as the GD library), and others you will have to enable using '--with-EXTENSION' options to 'configure'. Run 'configure --help' for a listing of these.
5. I got the latest version of the PHP source code from the CVS repository on my Windows machine, what do I need to compile it?
First, you will need Microsoft Visual C++ v6 (v5 may do it also, but we do it with v6), and you will need some support files. See the manual section about building PHP from source on Windows.
You can find a browscap.ini file at http://www.cyscape.com/asp/browscap/.
Chapitre 47. Database issues
This section holds common questions about relation between PHP and databases. Yes, PHP can access virtually any database available today.
- 1. I heard it's possible to access Microsoft SQL Server from PHP. How?
- 2. Can I access Microsoft Access databases?
- 3. I upgraded to PHP 4, and now mysql keeps telling me "Warning: MySQL: Unable to save result set in ...". What's up?
- 4. After installing shared MySQL support, Apache dumps core as soon as libphp4.so is loaded. Can this be fixed?
- 5. Why do I get an error that looks something like this: "Warning: 0 is not a MySQL result index in <file> on line <x>" or "Warning: Supplied argument is not a valid MySQL result resource in <file> on line <x>?
On Windows machines, you can simply use the included ODBC support and the correct ODBC driver.
On Unix machines, you can use the Sybase-CT driver to access Microsoft SQL Servers because they are (at least mostly) protocol-compatible. Sybase has made a free version of the necessary libraries for Linux systems. For other Unix operating systems, you need to contact Sybase for the correct libraries. Also see the answer to the next question.
Yes. You already have all the tools you need if you are running entirely under Windows 9x/Me, or NT/2000, where you can use ODBC and Microsoft's ODBC drivers for Microsoft Access databases.
If you are running PHP on a Unix box and want to talk to MS Access on a Windows box you will need Unix ODBC drivers. OpenLink Software has Unix-based ODBC drivers that can do this. There is a free pilot program where you can download an evaluation copy that doesn't expire and prices start at $675 for the commercial supported version.
Another alternative is to use an SQL server that has Windows ODBC drivers and use that to store the data, which you can then access from Microsoft Access (using ODBC) and PHP (using the built in drivers), or to use an intermediary file format that Access and PHP both understand, such as flat files or dBase databases. On this point Tim Hayes from OpenLink software writes:
Using another database as an intermediary is not a good idea, when you can
use ODBC from PHP straight to your database - i.e. with OpenLink's drivers. If
you do need to use an intermediary file format, OpenLink have now released
Virtuoso (a virtual database engine) for NT, Linux and other unix platforms.
Please visit our website for a free download. |
One option that has proven successful is to use MySQL and its MyODBC drivers on Windows and synchronizing the databases. Steve Lawrence writes:
Install MySQL on your platform according to instructions with MySQL. Latest available from www.mysql.com (get it from your mirror!). No special configuration required except when you set up a database, and configure the user account, you should put % in the host field, or the host name of the Windows computer you wish to access MySQL with. Make a note of your server name, username, and password.
Download the MyODBC for Windows driver from the MySQL site. Latest release is myodbc-2_50_19-win95.zip (NT available too, as well as source code). Install it on your Windows machine. You can test the operation with the utilities included with this program.
Create a user or system dsn in your ODBC administrator, located in the control panel. Make up a dsn name, enter your hostname, user name, password, port, etc for you MySQL database configured in step 1.
Install Access with a full install, this makes sure you get the proper add-ins.. at the least you will need ODBC support and the linked table manager.
Now the fun part! Create a new access database. In the table window right click and select Link Tables, or under the file menu option, select Get External Data and then Link Tables. When the file browser box comes up, select files of type: ODBC. Select System dsn and the name of your dsn created in step 3. Select the table to link, press OK, and presto! You can now open the table and add/delete/edit data on your MySQL server! You can also build queries, import/export tables to MySQL, build forms and reports, etc.
Tips and Tricks:
You can construct your tables in Access and export them to MySQL, then link them back in. That makes table creation quick.
When creating tables in Access, you must have a primary key defined in order to have write access to the table in access. Make sure you create a primary key in MySQL before linking in access
If you change a table in MySQL, you have to re-link it in Access. Go to tools>add-ins>linked table manager, cruise to your ODBC DSN, and select the table to re-link from there. you can also move your dsn source around there, just hit the always prompt for new location checkbox before pressing OK.
3. I upgraded to PHP 4, and now mysql keeps telling me "Warning: MySQL: Unable to save result set in ...". What's up?
Most likely what has happened is, PHP 4 was compiled with the '--with-mysql' option, without specifying the path to MySQL. This means PHP is using its built-in MySQL client library. If your system is running applications, such as PHP 3 as a concurrent Apache module, or auth-mysql, that use other versions of MySQL clients, then there is a conflict between the two differing versions of those clients.
Recompiling PHP 4, and adding the path to MySQL to the flag, '--with-mysql=/your/path/to/mysql' usually solves the problem.
4. After installing shared MySQL support, Apache dumps core as soon as libphp4.so is loaded. Can this be fixed?
If your MySQL libs are linked against pthreads this will happen. Check using ldd. If they are, grab the MySQL tarball and compile from source, or recompile from the source rpm and remove the switch in the spec file that turns on the threaded client code. Either of these suggestions will fix this. Then recompile PHP with the new MySQL libs.
5. Why do I get an error that looks something like this: "Warning: 0 is not a MySQL result index in <file> on line <x>" or "Warning: Supplied argument is not a valid MySQL result resource in <file> on line <x>?
You are trying to use a result identifier that is 0. The 0 indicates that your query failed for some reason. You need to check for errors after submitting a query and before you attempt to use the returned result identifier. The proper way to do this is with code similar to the following:
$result = mysql_query("SELECT * FROM tables_priv");
if (!$result) {
echo mysql_error();
exit;
} |
$result = mysql_query("SELECT * FROM tables_priv")
or die("Bad query: ".mysql_error()); |
Chapitre 48. Installation
This section holds common questions about the way to install PHP. PHP is available for almost any OS (except maybe for MacOS before OSX), and almost any web server.
To install PHP, follow the instructions in the INSTALL file located in the distribution. Windows users should also read the install.txt file. There are also some helpful hints for Windows users here.
- 1. Unix/Windows: Where should my php.ini file be located?
- 2. Unix: I installed PHP, but every time I load a document, I get the message 'Document Contains No Data'! What's going on here?
- 3. Unix: I installed PHP using RPMS, but Apache isn't processing the PHP pages! What's going on here?
- 4. Unix: I installed PHP 3 using RPMS, but it doesn't compile with the database support I need! What's going on here?
- 5. Unix: I patched Apache with the FrontPage extensions patch, and suddenly PHP stopped working. Is PHP incompatible with the Apache FrontPage extensions?
- 6. Unix/Windows: I have installed PHP, but when I try to access a PHP script file via my browser, I get a blank screen.
- 7. Unix/Windows: I have installed PHP, but when try to access a PHP script file via my browser, I get a server 500 error.
- 8.
Some operating systems: I have installed PHP without errors,
but when I try to start apache I get undefined symbol errors:
[mybox:user /src/php4] root# apachectl configtest apachectl: /usr/local/apache/bin/httpd Undefined symbols: _compress _uncompress
- 9.
Windows: I have installed PHP, but when I to access
a PHP script file via my browser, I get the error:
cgi error: The specified CGI application misbehaved by not returning a complete set of HTTP headers. The headers it did return are:
- 10. Windows: I've followed all the instructions, but still can't get PHP and IIS to work together!
By default on UNIX it should be in /usr/local/lib which is <install-path>/lib. Most people will want to change this at compile-time with the --with-config-file-path flag. You would, for example, set it with something like:
--with-config-file-path=/etc |
On Windows the default path for the php.ini file is the Windows directory. If you're using the Apache webserver, php.ini is first searched in the Apaches install directory, e.g. c:\program files\apache group\apache. This way you can have different php.ini files for different versions of Apache on the same machine.
See also the chapter about the configuration file.
2. Unix: I installed PHP, but every time I load a document, I get the message 'Document Contains No Data'! What's going on here?
This probably means that PHP is having some sort of problem and is core-dumping. Look in your server error log to see if this is the case, and then try to reproduce the problem with a small test case. If you know how to use 'gdb', it is very helpful when you can provide a backtrace with your bug report to help the developers pinpoint the problem. If you are using PHP as an Apache module try something like:
Stop your httpd processes
gdb httpd
Stop your httpd processes
> run -X -f /path/to/httpd.conf
Then fetch the URL causing the problem with your browser
> run -X -f /path/to/httpd.conf
If you are getting a core dump, gdb should inform you of this now
type: bt
You should include your backtrace in your bug report. This should be submitted to http://bugs.php.net/
If your script uses the regular expression functions (ereg() and friends), you should make sure that you compiled PHP and Apache with the same regular expression package. This should happen automatically with PHP and Apache 1.3.x
3. Unix: I installed PHP using RPMS, but Apache isn't processing the PHP pages! What's going on here?
Assuming you installed both Apache and PHP from RPM packages, you need to uncomment or add some or all of the following lines in your http.conf file:
# Extra Modules AddModule mod_php.c AddModule mod_php3.c AddModule mod_perl.c # Extra Modules LoadModule php_module modules/mod_php.so LoadModule php3_module modules/libphp3.so /* for PHP 3 */ LoadModule php4_module modules/libphp4.so /* for PHP 4 */ LoadModule perl_module modules/libperl.so |
AddType application/x-httpd-php3 .php3 /* for PHP 3 */ AddType application/x-httpd-php .php /* for PHP 4 */ |
4. Unix: I installed PHP 3 using RPMS, but it doesn't compile with the database support I need! What's going on here?
Due to the way PHP 3 built, it is not easy to build a complete flexible PHP RPM. This issue is addressed in PHP 4. For PHP 3, we currently suggest you use the mechanism described in the INSTALL.REDHAT file in the PHP distribution. If you insist on using an RPM version of PHP 3, read on...
The RPM packagers are setting up the RPMS to install without database support to simplify installations and because RPMS use /usr/ instead of the standard /usr/local/ directory for files. You need to tell the RPM spec file which databases to support and the location of the top-level of your database server.
This example will explain the process of adding support for the popular MySQL database server, using the mod installation for Apache.
Of course all of this information can be adjusted for any database server that PHP supports. We will assume you installed MySQL and Apache completely with RPMS for this example as well.
First remove mod_php3 :
rpm -e mod_php3
Then get the source rpm and INSTALL it, NOT --rebuild
rpm -Uvh mod_php3-3.0.5-2.src.rpm
Then edit the /usr/src/redhat/SPECS/mod_php3.spec file
In the %build section add the database support you want, and the path.
For MySQL you would add
The %build section will look something like this:--with-mysql=/usr \
./configure --prefix=/usr \ --with-apxs=/usr/sbin/apxs \ --with-config-file-path=/usr/lib \ --enable-debug=no \ --enable-safe-mode \ --with-exec-dir=/usr/bin \ --with-mysql=/usr \ --with-system-regex
Once this modification is made then build the binary rpm as follows:
rpm -bb /usr/src/redhat/SPECS/mod_php3.spec
Then install the rpm
rpm -ivh /usr/src/redhat/RPMS/i386/mod_php3-3.0.5-2.i386.rpm
5. Unix: I patched Apache with the FrontPage extensions patch, and suddenly PHP stopped working. Is PHP incompatible with the Apache FrontPage extensions?
No, PHP works fine with the FrontPage extensions. The problem is that the FrontPage patch modifies several Apache structures, that PHP relies on. Recompiling PHP (using 'make clean ; make') after the FP patch is applied would solve the problem.
6. Unix/Windows: I have installed PHP, but when I try to access a PHP script file via my browser, I get a blank screen.
Do a 'view source' in the web browser and you will probably find that you can see the source code of your PHP script. This means that the web server did not send the script to PHP for interpretation. Something is wrong with the server configuration - double check the server configuration against the PHP installation instructions.
7. Unix/Windows: I have installed PHP, but when try to access a PHP script file via my browser, I get a server 500 error.
Something went wrong when the server tried to run PHP. To get to see a sensible error message, from the command line, change to the directory containing the PHP executable (php.exe on Windows) and run php -i. If PHP has any problems running, then a suitable error message will be displayed which will give you a clue as to what needs to be done next. If you get a screen full of html codes (the output of the phpinfo() function) then PHP is working, and your problem may be related to your server configuration which you should double check.
8. Some operating systems: I have installed PHP without errors, but when I try to start apache I get undefined symbol errors:
[mybox:user /src/php4] root# apachectl configtest apachectl: /usr/local/apache/bin/httpd Undefined symbols: _compress _uncompress |
This has actually nothing to do with PHP, but with the MySQL client libraries. Some need --with-zlib, others do not. This is also covered in the MySQL FAQ.
9. Windows: I have installed PHP, but when I to access a PHP script file via my browser, I get the error:
cgi error: The specified CGI application misbehaved by not returning a complete set of HTTP headers. The headers it did return are: |
This error message means that PHP failed to output anything at all. To get to see a sensible error message, from the command line, change to the directory containing the PHP executable (php.exe on Windows) and run php -i. If PHP has any problems running, then a suitable error message will be displayed which will give you a clue as to what needs to be done next. If you get a screen full of html codes (the output of the phpinfo() function) then PHP is working.
Once PHP is working at the command line, try accessing the script via the browser again. If it still fails then it could be one of the following:
File permissions on your PHP script, php.exe, php4ts.dll, php.ini or any PHP extensions you are trying to load are such that the anonymous internet user ISUR_<machinename> cannot access them.
The script file does not exist (or possibly isn't where you think it is relative to your web root directory). Note that for IIS you can trap this error by ticking the 'check file exists' box when setting up the script mappings in the Internet Services Manager. If a script file does not exist then the server will return a 404 error instead. There is also the additional benefit that IIS will do any authentication required for you based on the NTLanMan permissions on your script file.
Make sure any user who needs to run a PHP script has the rights to run php.exe! IIS uses an anonymous user which is added at the time IIS is installed. This user needs rights to php.exe. Also, any authenticated user will also need rights to execute php.exe. And for IIS4 you need to tell it that PHP is a script engine.
Chapitre 49. Build Problems
This section gathers most common errors that occur at build time.
- 1. I got the latest version of PHP using the anonymous CVS service, but there's no configure script!
- 2. I'm having problems configuring PHP to work with Apache. It says it can't find httpd.h, but it's right where I said it is!
- 3. When I run configure, it says that it can't find the include files or library for GD, gdbm, or some other package!
- 4. When it is compiling the file language-parser.tab.c, it gives me errors that say yytname undeclared.
- 5. When I run make, it seems to run fine but then fails when it tries to link the final application complaining that it can't find some files.
- 6. When linking PHP, it complains about a number of undefined references.
- 7. I can't figure out how to build PHP with Apache 1.3.
- 8. I have followed all the steps to install the Apache module version on UNIX, and my PHP scripts show up in my browser or I am being asked to save the file.
- 9. It says to use: --activate-module=src/modules/php4/libphp4.a, but that file doesn't exist, so I changed it to --activate-module=src/modules/php4/libmodphp4.a and it doesn't work!? What's going on?
- 10. When I try to build Apache with PHP as a static module using --activate-module=src/modules/php4/libphp4.a it tells me that my compiler is not ANSI compliant.
- 11. When I try to build PHP using --with-apxs I get strange error messages.
- 12. During make, I get errors in microtime, and a lot of RUSAGE_ stuff.
- 13. I want to upgrade my PHP. Where can I find the ./configure line that was used to build my current PHP installation?
- 14. When building PHP with the GD library it either gives strange compile errors or segfaults on execution.
1. I got the latest version of PHP using the anonymous CVS service, but there's no configure script!
You have to have the GNU autoconf package installed so you can generate the configure script from configure.in. Just run ./buildconf in the top-level directory after getting the sources from the CVS server. (Also, unless you run configure with the --enable-maintainer-mode option, the configure script will not automatically get rebuilt when the configure.in file is updated, so you should make sure to do that manually when you notice configure.in has changed. One symptom of this is finding things like @VARIABLE@ in your Makefile after configure or config.status is run.)
2. I'm having problems configuring PHP to work with Apache. It says it can't find httpd.h, but it's right where I said it is!
You need to tell the configure/setup script the location of the top-level of your Apache source tree. This means that you want to specify --with-apache=/path/to/apache and not --with-apache=/path/to/apache/src.
3. When I run configure, it says that it can't find the include files or library for GD, gdbm, or some other package!
You can make the configure script looks for header files and libraries in non-standard locations by specifying additional flags to pass to the C preprocessor and linker, such as:
CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure |
env CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure |
4. When it is compiling the file language-parser.tab.c, it gives me errors that say yytname undeclared.
You need to update your version of Bison. You can find the latest version at ftp://ftp.gnu.org/pub/gnu/bison/.
5. When I run make, it seems to run fine but then fails when it tries to link the final application complaining that it can't find some files.
Some old versions of make that don't correctly put the compiled versions of the files in the functions directory into that same directory. Try running cp *.o functions and then re-running make to see if that helps. If it does, you should really upgrade to a recent version of GNU make.
Take a look at the link line and make sure that all of the appropriate libraries are being included at the end. Common ones that you might have missed are '-ldl' and any libraries required for any database support you included.
If you're linking with Apache 1.2.x, did you remember to add the appropriate information to the EXTRA_LIBS line of the Configuration file and re-rerun Apache's Configure script? See the INSTALL file that comes with the distribution for more information.
Some people have also reported that they had to add '-ldl' immediately following libphp4.a when linking with Apache.
This is actually quite easy. Follow these steps carefully:
Grab the latest Apache 1.3 distribution from http://www.apache.org/dist/.
Ungzip and untar it somewhere, for example /usr/local/src/apache-1.3.
Compile PHP by first running ./configure --with-apache=/<path>/apache-1.3 (substitute <path> for the actual path to your apache-1.3 directory.
Type make followed by make install to build PHP and copy the necessary files to the Apache distribution tree.
Change directories into to your /<path>/apache-1.3/src directory and edit the Configuration file. Add to the file: AddModule modules/php4/libphp4.a.
Type: ./Configure followed by make.
You should now have a PHP-enabled httpd binary!
Note: You can also use the new Apache ./configure script. See the instructions in the README.configure file which is part of your Apache distribution. Also have a look at the INSTALL file in the PHP distribution.
8. I have followed all the steps to install the Apache module version on UNIX, and my PHP scripts show up in my browser or I am being asked to save the file.
This means that the PHP module is not getting invoked for some reason. Three things to check before asking for further help:
Make sure that the httpd binary you are running is the actual new httpd binary you just built. To do this, try running: /path/to/binary/httpd -l
If you don't see mod_php4.c listed then you are not running the right binary. Find and install the correct binary.
Make sure you have added the correct Mime Type to one of your Apache .conf files. It should be: AddType application/x-httpd-php3 .php3 (for PHP 3)
or AddType application/x-httpd-php .php (for PHP 4)
Also make sure that this AddType line is not hidden away inside a <Virtualhost> or <Directory> block which would prevent it from applying to the location of your test script.
Finally, the default location of the Apache configuration files changed between Apache 1.2 and Apache 1.3. You should check to make sure that the configuration file you are adding the AddType line to is actually being read. You can put an obvious syntax error into your httpd.conf file or some other obvious change that will tell you if the file is being read correctly.
9. It says to use: --activate-module=src/modules/php4/libphp4.a, but that file doesn't exist, so I changed it to --activate-module=src/modules/php4/libmodphp4.a and it doesn't work!? What's going on?
Note that the libphp4.a file is not supposed to exist. The apache process will create it!
10. When I try to build Apache with PHP as a static module using --activate-module=src/modules/php4/libphp4.a it tells me that my compiler is not ANSI compliant.
This is a misleading error message from Apache that has been fixed in more recent versions.
There are three things to check here. First, for some reason when Apache builds the apxs Perl script, it sometimes ends up getting built without the proper compiler and flags variables. Find your apxs script (try the command which apxs, it's sometimes found in /usr/local/apache/bin/apxs or /usr/sbin/apxs. Open it and check for lines similar to these:
my $CFG_CFLAGS_SHLIB = ' '; # substituted via Makefile.tmpl my $CFG_LD_SHLIB = ' '; # substituted via Makefile.tmpl my $CFG_LDFLAGS_SHLIB = ' '; # substituted via Makefile.tmpl |
my $CFG_CFLAGS_SHLIB = '-fpic -DSHARED_MODULE'; # substituted via Makefile.tmpl my $CFG_LD_SHLIB = 'gcc'; # substituted via Makefile.tmpl my $CFG_LDFLAGS_SHLIB = q(-shared); # substituted via Makefile.tmpl |
my $CFG_LIBEXECDIR = 'modules'; # substituted via APACI install |
my $CFG_LIBEXECDIR = '/usr/lib/apache'; # substituted via APACI install |
During the make portion of installation, if you encounter problems that look similar to this:
microtime.c: In function `php_if_getrusage': microtime.c:94: storage size of `usg' isn't known microtime.c:97: `RUSAGE_SELF' undeclared (first use in this function) microtime.c:97: (Each undeclared identifier is reported only once microtime.c:97: for each function it appears in.) microtime.c:103: `RUSAGE_CHILDREN' undeclared (first use in this function) make[3]: *** [microtime.lo] Error 1 make[3]: Leaving directory `/home/master/php-4.0.1/ext/standard' make[2]: *** [all-recursive] Error 1 make[2]: Leaving directory `/home/master/php-4.0.1/ext/standard' make[1]: *** [all-recursive] Error 1 make[1]: Leaving directory `/home/master/php-4.0.1/ext' make: *** [all-recursive] Error 1 |
Your system is broken. You need to fix your /usr/include files by installing a glibc-devel package that matches your glibc. This has absolutely nothing to do with PHP. To prove this to yourself, try this simple test:
$ cat >test.c <<X #include <sys/resource.h> X $ gcc -E test.c >/dev/null |
13. I want to upgrade my PHP. Where can I find the ./configure line that was used to build my current PHP installation?
Either you look at config.nice file, in the source tree of your current PHP installation or, if this is not available, you simply run a
<?php phpinfo(); ?> |
Chapitre 50. Using PHP
This section gathers most common errors you can face, while writing PHP scripts.
- 1. I would like to write a generic PHP script that can handle data coming from any form. How do I know which POST method variables are available?
- 2. I need to convert all single-quotes (') to a backslash followed by a single-quote. How can I do this with a regular expression?
- 3.
When I do the following, the output is printed in
the wrong order:
what's going on?function myfunc($argument) { echo $argument + 10; } $variable = 10; echo "myfunc($variable) = " . myfunc($variable); - 4.
Hey, what happened to my newlines?
<pre> <?php echo "This should be the first line."; ?> <?php echo "This should show up after the new line above."; ?> </pre>
- 5. I get the message 'Warning: Cannot send session cookie - headers already sent...' or 'Cannot add header information - headers already sent...'.
- 6. I need to access information in the request header directly. How can I do this?
- 7. When I try to use authentication with IIS I get 'No Input file specified'.
- 8. My PHP script works on IE and Lynx, but on Netscape some of my output is missing. When I do a "View Source" I see the content in IE but not in Netscape.
- 9. How am I supposed to mix XML and PHP? It complains about my <?xml> tags!
- 10. How can I use PHP with FrontPage or some other HTML editor that insists on moving my code around?
- 11. Where can I find a complete list of pre-set variables available to me, and why are these not documented in the PHP documentation?
- 12. I'm trying to access one of the standard CGI variables (such as $DOCUMENT_ROOT or $HTTP_REFERER) in a user-defined function, and it can't seem to find it. What's wrong?
1. I would like to write a generic PHP script that can handle data coming from any form. How do I know which POST method variables are available?
Make sure that the track_vars feature is enabled in your php.ini file. Since PHP 4.0.3, this feature is always on. When track_vars is on, it creates some associative arrays, the most important here is: $_POST (this used to be called $HTTP_POST_VARS in PHP versions prior 4.1.0). So, to write a generic script to handle POST method variables you would need something similar to the following:
foreach ($_POST as $var => $value) {
echo "$var = $value<br>\n";
} |
2. I need to convert all single-quotes (') to a backslash followed by a single-quote. How can I do this with a regular expression?
First off, take a look at the addslashes() function. It will do exactly what you want. You should also have a look at the magic_quotes_gpc directive in your php.ini file.
3. When I do the following, the output is printed in the wrong order:
function myfunc($argument)
{
echo $argument + 10;
}
$variable = 10;
echo "myfunc($variable) = " . myfunc($variable); |
To be able to use the results of your function in an expression (such as concatenating it with other strings in the example above), you need to return the value, not echo() it.
4. Hey, what happened to my newlines?
<pre> <?php echo "This should be the first line."; ?> <?php echo "This should show up after the new line above."; ?> </pre> |
In PHP, the ending for a block of code is either "?>" or "?>\n" (where \n means a newline). So in the example above, the echoed sentences will be on one line, because PHP omits the newlines after the block ending. This means that you need to insert an extra newline after each block of PHP code to make it print out one newline.
Why does PHP do this? Because when formatting normal HTML, this usually makes your life easier because you don't want that newline, but you'd have to create extremely long lines or otherwise make the raw page source unreadable to achieve that effect.
5. I get the message 'Warning: Cannot send session cookie - headers already sent...' or 'Cannot add header information - headers already sent...'.
The functions header(), setcookie() and the session functions need to add headers to the output stream. But headers can only be sent before all other content, check if your script is sending headers after having already sent content.
The getallheaders() function will do this if you are running PHP as an Apache module. So, the following bit of code will show you all the request headers:
$headers = getallheaders();
foreach ($headers as $name => $content) {
echo "headers[$name] = $content<br>\n";
} |
The security model of IIS is at fault here. This is a problem common to all CGI programs running under IIS. A workaround is to create a plain HTML file (not parsed by PHP) as the entry page into an authenticated directory. Then use a META tag to redirect to the PHP page, or have a link to the PHP page. PHP will then recognize the authentication correctly. With the ISAPI module, this is not a problem. This should not effect other NT web servers. For more information, see: http://support.microsoft.com/support/kb/articles/q160/4/22.asp.
8. My PHP script works on IE and Lynx, but on Netscape some of my output is missing. When I do a "View Source" I see the content in IE but not in Netscape.
Netscape is more strict regarding html tags (such as tables) then IE. Running your html output through a html validator, such as validator.w3.org, might be helpful. For example, a missing </table> might cause this.
Also, both IE and Lynx ignore any NULs (\0) in the HTML stream, Netscape does not. The best way to check for this is to compile the command line version of PHP (also known as the CGI version) and run your script from the command line. In *nix, pipe it through od -c and look for any \0 characters. If you are on Windows you need to find an editor or some other program that lets you look at binary files. When Netscape sees a NUL in a file it will typically not output anything else on that line whereas both IE and Lynx will.
You need to turn off the short tags by setting short_tags to 0 in your php.ini file, or by using the appropriate Apache directive. You could even use a <File> section to do this selectively.
10. How can I use PHP with FrontPage or some other HTML editor that insists on moving my code around?
One of the easiest things to do is to enable using ASP tags in your PHP code. This allows you to use the ASP-style <% and %> code delimiters. Some of the popular HTML editors handle those more intelligently (for now). To enable the ASP-style tags, you need to set the asp_tags php.ini variable, or use the appropriate Apache directive.
11. Where can I find a complete list of pre-set variables available to me, and why are these not documented in the PHP documentation?
The best way is to stick a <?php phpinfo(); ?> part on a page and load it up. This will show you all sorts of information about your PHP setup, including a list of both environment variables and also special variables set by your web server. This list can't really be documented in the PHP documentation because it will change from one server to another.
12. I'm trying to access one of the standard CGI variables (such as $DOCUMENT_ROOT or $HTTP_REFERER) in a user-defined function, and it can't seem to find it. What's wrong?
Environment variables are normal global variables, so you must either declare them as global variables in your function (by using "global $DOCUMENT_ROOT;", for example) or by using the global variable array (ie, "$GLOBALS["DOCUMENT_ROOT"]".
Chapitre 51. PHP and HTML
PHP and HTML interact a lot: PHP can generate HTML, and HTML can pass information to PHP.
- 1. What encoding/decoding do I need when I pass a value through a form/URL?
- 2. I'm trying to use an <input type="image"> tag, but the $foo.x and $foo.y variables aren't available. Where are they?
- 3. How do I create arrays in a HTML <form>?
- 4. How do I get all the results from a select multiple HTML tag?
There are several stages for which encoding is important. Assuming that you have a string $data, which contains the string you want to pass on in a non-encoded way, these are the relevant stages:
HTML interpretation. In order to specify a random string, you must include it in double quotes, and htmlspecialchars the whole value.
URL: A URL consists of several parts. If you want your data to be interpreted as one item, you must encode it with urlencode().
Note : It is wrong to urlencode() $data, because it's the browsers responsibility to urlencode() the data. All popular browsers do that correctly. Note that this will happen regardless of the method (i.e., GET or POST). You'll only notice this in case of GET request though, because POST requests are usually hidden.
Note : The data is shown in the browser as intended, because the browser will interpret the HTML escaped symbols.
Upon submitting, either via GET or POST, the data will be urlencoded by the browser for transferring, and directly urldecoded by PHP. So in the end, you don't need to do any urlencoding/urldecoding yourself, everything is handled automagically.
Note : In fact you are faking a HTML GET request, therefore it's necessary to manually urlencode() the data.
Note : You need to htmlspecialchars() the whole URL, because the URL occurs as value of an HTML-attribute. In this case, the browser will first un-htmlspecialchars() the value, and then pass the URL on. PHP will understand the URL correctly, because you urlencoded() the data.
You'll notice that the & in the URL is replaced by &. Although most browsers will recover if you forget this, this isn't always possible. So even if your URL is not dynamic, you need to htmlspecialchars() the URL.
2. I'm trying to use an <input type="image"> tag, but the $foo.x and $foo.y variables aren't available. Where are they?
When submitting a form, it is possible to use an image instead of the standard submit button with a tag like:
<input type="image" src="image.gif" name="foo"> |
Because $foo.x and $foo.y are invalid variable names in PHP, they are automagically converted to $foo_x and $foo_y. That is, the periods are replaced with underscores.
To get your <form> result sent as an array to your PHP script you name the <input>, <select> or <textarea> elements like this:
<input name="MyArray[]"> <input name="MyArray[]"> <input name="MyArray[]"> <input name="MyArray[]"> |
<input name="MyArray[]"> <input name="MyArray[]"> <input name="MyOtherArray[]"> <input name="MyOtherArray[]"> |
<input name="AnotherArray[]"> <input name="AnotherArray[]"> <input name="AnotherArray[email]"> <input name="AnotherArray[phone]"> |
Note : Specifying an arrays key is optional in HTML. If you do not specify the keys, the array gets filled in the order the elements appear in the form. Our first example will contain keys 0, 1, 2 and 3.
See also Array Functions and Variables from outside PHP.
The select multiple tag in an HTML construct allows users to select multiple items from a list. These items are then passed to the action handler for the form. The problem is that they are all passed with the same widget name. ie.
<select name="var" multiple> |
var=option1 var=option2 var=option3 |
<select name="var[]" multiple> |
Note that if you are using JavaScript the [] on the element name might cause you problems when you try to refer to the element by name. Use it's numerical form element ID instead, or enclose the variable name in single quotes and use that as the index to the elements array, for example:
variable = documents.forms[0].elements['var[]']; |
Chapitre 52. PHP and COM
PHP can be used to access COM and DCOM objects on Win32 platforms.
- 1. I have built a DLL to calculate something. Is there any way to run this DLL under PHP ?
- 2. What does 'Unsupported variant type: xxxx (0xxxxx)' mean ?
- 3. Is it possible manipulate visual objects in PHP ?
- 4. Can I store a COM object in a session ?
- 5. How can I trap COM errors ?
- 6. Can I generate DLL files from PHP scripts like i can in Perl ?
- 7. What does 'Unable to obtain IDispatch interface for CLSID {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}' mean ?
- 8. How can I run COM object from remote server ?
- 9. I get 'DCOM is disabled in C:\path...\scriptname.php on line 6', what can I do ?
- 10. Is it possible to load/manipulate an ActiveX object in a page with PHP ?
- 11. Is it possible to get a running instance of a component ?
- 12. Is there a way to handle an event sent from COM object ?
- 13. I'm having problems when trying to invoke a method of a COM object which exposes more than one interface. What can I do ?
- 14. So PHP works with COM, how about COM+ ?
- 15. If PHP can manipulate COM objects, can we imagine to use MTS to manage components resources, in conjunction with PHP ?
If this is a simple DLL there is no way yet to run it from PHP. If the DLL contains a COM server you may be able to access it if it implements the IDispatch interface.
There are dozens of VARIANT types and combinations of them. Most of them are already supported but a few still have to be implemented. Arrays are not completely supported. Only single dimensional indexed only arrays can be passed between PHP and COM. If you find other types that aren't supported, please report them as a bug (if not already reported) and provide as much information as available.
Generally it is, but as PHP is mostly used as a web scripting language it runs in the web servers context, thus visual objects will never appear on the servers desktop. If you use PHP for application scripting e.g. in conjunction with PHP-GTK there is no limitation in accessing and manipulating visual objects through COM.
No, you can't. COM instances are treated as resources and therefore they are only available in a single script's context.
Currently it's not possible to trap COM errors beside the ways provided by PHP itself (@, track_errors, ..), but we are thinking of a way to implement this.
No, unfortunately there is no such tool available for PHP.
7. What does 'Unable to obtain IDispatch interface for CLSID {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}' mean ?
This error can have multiple reasons:
the CLSID is wrong
the requested DLL is missing
the requested component doesn't implement the IDispatch interface
Exactly like you run local objects. You only have to pass the IP of the remote machine as second parameter to the COM constructor.
Make sure that you have set com.allow_dcom=true in your php.ini.
Edit your php.ini and set com.allow_dcom=true.
This has nothing to do with PHP. ActiveX objects are loaded on client side if they are requested by the HTML document. There is no relation to the PHP script and therefore there is no direct server side interaction possible.
This is possible with the help of monikers. If you want to get multiple references to the same word instance you can create that instance like shown:
$word = new COM("C:\docs\word.doc"); |
This will create a new instance if there is no running instance available or it will return a handle to the running instance, if available.
13. I'm having problems when trying to invoke a method of a COM object which exposes more than one interface. What can I do ?
The answer is as simple as unsatisfying. I don't know exactly but i think you can do nothing. If someone has specific information about this, please let me know :)
COM+ extends COM by a framework for managing components through MTS and MSMQ but there is nothing special that PHP has to support to use such components.
15. If PHP can manipulate COM objects, can we imagine to use MTS to manage components resources, in conjunction with PHP ?
PHP itself doesn't handle transactions yet. Thus if an error occurs no rollback is initiated. If you use components that support transactions you will have to implement the transaction management yourself.
Chapitre 53. PHP and other languages
PHP is the best language for web programing, but what about other languages?
ASP is not really a language in itself, it's an acronym for Active Server Pages, the actual language used to program ASP with is Visual Basic Script or JScript. The biggest drawback of ASP is that it's a proprietary system that is natively used only on Microsoft Internet Information Server (IIS). This limits it's availability to Win32 based servers. There are a couple of projects in the works that allows ASP to run in other environments and webservers: InstantASP from Halcyon (commercial), Chili!Soft ASP from Chili!Soft (commercial) and OpenASP from ActiveScripting.org (free). ASP is said to be a slower and more cumbersome language than PHP, less stable as well. Some of the pros of ASP is that since it primarily uses VBScript it's relatively easy to pick up the language if you're already know how to program in Visual Basic. ASP support is also enabled by default in the IIS server making it easy to get up and running. The components built in ASP are really limited, so if you need to use "advanced" features like interacting with FTP servers, you need to buy additional components.
Yes, asp2php is the one most often referred to.
PHP is commonly said to be faster and more efficient for complex programming tasks and trying out new ideas. PHP is generally referred to as more stable and less resource intensive as well. Cold Fusion has better error handling, database abstraction and date parsing although database abstraction is addressed in PHP 4. Another thing that is listed as one of Cold Fusion's strengths is its excellent search engine, but it has been mentioned that a search engine is not something that should be included in a web scripting language. PHP runs on almost every platform there is; Cold Fusion is only available on Win32, Solaris, Linux and HP/UX. Cold Fusion has a good IDE and is generally easier to get started with, whereas PHP initially requires more programming knowledge. Cold Fusion is designed with non-programmers in mind, while PHP is focused on programmers.
A great summary by Michael J Sheldon on this topic has been posted to the PHP mailing list. A copy can be found here.
The biggest advantage of PHP over Perl is that PHP was designed for scripting for the web where Perl was designed to do a lot more and can because of this get very complicated. The flexibility / complexity of Perl makes it easier to write code that another author / coder has a hard time reading. PHP has a less confusing and stricter format without losing flexibility. PHP is easier to integrate into existing HTML than Perl. PHP has pretty much all the 'good' functionality of Perl: constructs, syntax and so on, without making it as complicated as Perl can be. Perl is a very tried and true language, it's been around since the late eighties, but PHP is maturing very quickly.
Chapitre 54. Migrating from PHP 2 to PHP 3
PHP has already a long history behind him: Legendary PHP 1.0, PHP/FI, PHP 3.0 and PHP 4.0.
PHP/FI 2.0 is no longer supported. Please see appropriate manual section for information about migration from PHP/FI 2.0.
If you are still working with PHP 2, we strongly recommend you to upgrade straight to PHP 4.
Chapitre 55. Migrating from PHP 3 to PHP 4
PHP has already a long history behind him : Legendary PHP 1.0, PHP/FI, PHP 3.0 and PHP 4.0.
PHP 4 was designed to be as compatible with earlier versions of PHP as possible and very little functionality was broken in the process. If you're really unsure about compatibility you should install PHP 4 in a test environment and run your scripts there.
Also see the appropriate migration appendix of this manual.
Chapitre 56. Miscellaneous Questions
There can be some questions we can't put into other categories. Here you can find them.
- 1. Where did the pop-ups go on the website? Can I have the code for that?
- 2. How can I handle the bz2 compressed manuals on Windows?
The yellow pop-up windows on the old site were pretty cool, but were very difficult to maintain (since some companies seem to enjoy changing the way their browsers work with every new release).
All the code for previous versions of the website is still available through CVS. Specifically, the last version of shared.inc (that had all the Javascript and DHTML to do the popups) is available here.
If you don't have an archiver-tool to handle bz2 files download the commandline tool from Redhat (please find further information below).
If you would not like to use a command line tool, you can try free tools like Stuffit Expander, UltimateZip, 7-Zip, or Quick Zip. If you have tools like WinRAR or Power Archiver, you can easily decompress the bz2 files with it. If you use Windows Commander, a bz2 plugin for that program is available freely from the Windows Commander site.
The bzip2 commandline tool from Redhat:
Win2k Sp2 users grab the latest version 1.0.2, all other Windows user should grab version 1.00. After downloading rename the executable to bzip2.exe. For convenience put it into a directory in your path, e.g. C:\Windows where C represents your windows installation drive.
Note: lang stands for your language and x for the desired format, e.g.: pdf. To uncompress the php_manual_lang.x.bz2 follow these simple instructions:
open a command prompt window
cd to the folder where you stored the downloaded php_manual_lang.x.bz2
invoke bzip2 -d php_manual_lang.x.bz2, extracting php_manual_lang.x in the same folder
In case you downloaded the php_manual_lang.tar.bz2 with many html-files in it, the procedure is the same. The only difference is that you got a file php_manual_lang.tar. The tar format is known to be treated with most common archivers on Windows like e.g. WinZip.
VII. Appendices
Annexe A. Histoire de PHP
L'évolution de PHP s'est faite en quelques années. Devenir un des langages les plus importants du web ne fut pas une évolution simple. Pour ceux que ça intéresse, voici comment PHP a évolué jusqu'à aujourd'hui.
Histoire de PHP
PHP/FI
PHP a pris la suite d'un langage plus ancien, appelé PHP/FI. PHP/FI a été créé par Rasmus Lerdorf, en 1995. C'était initialement une librairie de scripts Perl, dont il se servait pour noter les accès à CV en ligne. Il donna le nom de 'Personnal Home Page Tools' à cette librairie. Au fur et à mesure qu'il ajoutait de nouvelles fonctionnalités, Rasmus a transformé la librairie en une implémentation en C, capable de communiquer avec les bases de données, et de créer des applications dynamiques et simples pour le web. Rasmus décida alors de publier son code, pour que tout le monde puisse l'utiliser et en profiter. Cela appela aussi aux contributions et aux améliorations du code.
PHP/FI, qui signifie Personal Home Page / Forms Interpreter, (Home Page personnelle, Interpreteur de Formulaire), incluait plusieurs fonctionnalités de base que nous connaissons encore aujourd'hui. Il avait ces variables qui ressemblent au Perl, un système d'interprétation automatique des variables de formulaires, et une syntaxe qui s'intègre facilement dans HTML.La syntaxe elle-même était similaire à celle du Perl mais beaucoup plus limitée. Elle était simple et un peu incohérente.
En 1997, PHP/FI 2.0,la seconde version en langage C, avait déjà une audience estimée de plusieurs milliers d'utilisateurs dans le monde, et environs 50,000 noms de domaine indiquaient qu'ils avaient installé PHP. Cela représentait environs 1% des noms de domaines sur l'Internet. Même si le nombre de contributeur était plutôt élevé, PHP était toujours le projet d'un seul homme.
PHP/FI 2.0 fut publié officiellement en novembre 1997, après avoir passé l'essentiel de sa vie en version beta. Peu de temps après, une version alpha de PHP 3.0 était publié.
PHP 3
PHP 3.0 fut la première version du langage tel que nous le connaissons actuellement. Il fut créé par Andi Gutmans et Zeev Suraski en 1997, sous forme de réécriture complète de PHP/FI, lorsqu'ils s'aperçurent que PHP/FI était sous performant pour leur application de commerce électronique. Dans un effort de coopération, et de compatibilité avec les anciennes versions de PHP/FI, Andi, Rasmus et Zeev décidèrent de coopérer et d'annoncer PHP 3.0 comme le successeur officiel de PHP/FI. Le développement de PHP/FI 2.0 fut complètement arrêté.
Une des améliorations notables de PHP 3.0 fut ses capacités d'extensions. En plus de fournir une solide infrastructure aux utilisateurs finaux, des accès à de nombreuses bases de données et protocoles, PHP 3.0 proposait une API modulaire, qui attira des douzaines de développeurs. Ceux-ci réalisèrent et partagèrent de nouvelles extensions. Sans doute, ce fut la clé du succès retentissant de PHP 3.0. Les autres améliorations de PHP 3.0 furent le support de la syntaxe objet, et une syntaxe de langage plus robuste et cohérente.
Le nouveau langage fut publié sous un nouveau nom, qui indiquait clairement que le projet n'était plus un projet personnel, comme l'était PHP/FI 2.0. Il fut nommé 'PHP' avec une nouvelle signification : 'PHP: Hypertext Preprocessor'. C'est un acronyme récursif, c'est à dire qu'il se définit lui-même. En français, cela donne : 'Le préprocesseur Hypertexte, c'est PHP'.
A la fin de 1998, PHP avait conquis une base de plusieurs dizaines de milliers d'utilisateurs, et des centaines de milliers de sites indiquaient qu'ils l'utilisaient. Au plus fort de son utilisation, PHP 3.0 était installé sur 10% du parc mondial de serveurs web mondial.
PHP 3.0 fut officiellement publié en Juin 1998, après 9 mois de tests.
PHP 4
Durant l'hiver 1998, juste après la publication de PHP 3.0, Andi Gutmans et Zeev Suraski commencèrent la réécriture du moteur interne de PHP à la base. L'objectif était d'améliorer les performances de PHP avec les applications complexes, et améliorer la modularité du code. Ces applications étaient rendues possibles par la syntaxe de PHP 3.0, mais le logiciel n'était pas conçu pour supporter efficacement ces applications.
Le nouveau moteur, appelé 'Zend Engine' (combinaison des noms de Zeev et Andi), atteint ces objectifs avec succès, et la première version fut publiée vers la mi-1999. PHP 4.0, s'appuyant sur ce moteur et amélioré par un grand nombre de nouvelles fonctionnalités fut publié officiellement en mai 2000, presque 2 ans après son prédécesseur. En plus de performances nettement plus élevées, PHP 4.0 apportait le support de nombreux serveurs web, les sessions HTTP, la bufferisation de sortie, une sécurité accrue des informations visiteurs et plusieurs nouvelles structures de langage.
PHP 4 est actuellement la dernière version de PHP. Le projet de PHP 5.0 a déjà débuté, afin d'améliorer le moteur Zend, et y intégrer des capacités objets améliorées.
Actuellement, PHP est utilisé par des centaines de milliers de développeurs, et plusieurs millions de sites web indiquent qu'ils sont configurés avec PHP, ce qui représente environs 20% des noms de domaines sur Internet.
L'équipe de développement de PHP inclue des douzaines de développeurs, et d'autres équipes travaillent à des projets liés tels que PEAR ou la documentation.
Quelques projets liés à PHP
PEAR
PEAR, signifie 'PHP Extension and Application Repository' (initialement, PHP Extension and Add-on Repository) est la première version de classe de base en PHP, et deviendra à terme le moyen privilégié de distribuer PHP et les modules C.
PEAR a été conçu durant les débats tenus lors des PHP Developers' Meeting (PDM) (Rencontres de développeurs PHP), qui ont eu lieu en Janvier 2000 à Tel Aviv. Il a été crée à l'initiative de Stig S. Bakken, et dédié à sa première fille, Malin Bakken.
Depuis l'an 2000, PEAR a grossi jusqu'à devenir un projet significatif avec un groupe de développeur compétents, qui travaillent à mettre en place une librairie complète, réutilisable et commune à la communauté PHP entière. PEAR inclus une vaste sélection de classes de bases pour réaliser une couche d'abstraction de bases de données, du cache, des calculs mathématiques et des transactiosn de commerce électronique.
Equipe d'assurance Qualité
L'équipe d'assurance Qualité de PHP a été mise en place durant l'été 2000, en réponse aux critiques reçues par PHP 3.0, qui n'était pas suffisamment testé sur des environnements de productions. L'équipe est constitué de d'un groupe de développeurs de haut niveau, qui ont une bonne connaissance des sources PHP. Ces développeurs passent le plus clair de leur temps à localiser et supprimer les bugs trouvés dans PHP. De plus, il y a bien d'autres membres du groupe PHP qui testent et fournissent un compte rendu fidèle de l'utilisation de PHP sur différentes plate formes.
PHP-GTK
PHP-GTK est la solution PHP pour écrire des applications avec interface, coté client. Andrei Zmievski se rappelle de la création de PHP-GTK:
La programmation d'interface GUI a toujours été une passion pour moi, et je pensais que Gtk+ était une excellente librairie, hormis le fait qu'elle était écrite en C, ce qui était plutôt laborieux. Après avoir assisté aux implémentations de PyGtk et GTK-Perl, j'ai décidé de voir si PHP pouvait disposer de sa propre interface avec Gtk+, même minimale. J'ai commencé au mois d'aoÛt 2000, lorsque j'avais un peu plus de temps libre, et j'ai réalisé les premières expérimentations. Mon guide principal fut l'implémentation de PyGtk, qui était plutôt complète et avait une interface orientée objet. James Henstridge, l'auteur de PyGtk, fut d'une aide précieuse au démarrage du projet.
Réécrire toutes les interfaces de Gtk+ à la main était hors de question et j'ai pensé à réaliser un générateur de code, exactement comme PyGtk l'avait fait. Le générateur de code était un programme PHP qui lisait un ensemble de fichiers .defs, contenant les classes, constantes et méthodes Gtk+, puis générait le code d'interface de PHP. Ce qui ne pouvait pas être généré automatiquement était traités à la main, dans le fichier .overrides.
Travailler sur le générateur de code et sur l'infrastructure pris un peu de temps, car je n'avais pas beaucoup de temps à consacrer à PHP-GTK durant l'automne 2000. Après avoir montré PHP-GTK à Frank Kromann, il s'y intéressa, et commença à m'aider sur le générateur et l'implémentation Win32. Lorsque nous écrivîmes le premier programme 'Hello World', ce fut extrêmement excitant. Cela a pris encore quelques mois pour avoir une version initiale. Elle fut publiée en mars 2001. Cela a encore pris quelques mois pour que le projet soit dans une forme présentable. Ce projet fut rapidement présenté sur SlashDot.
Anticipant que PHP serait un projet à part entière, j'ai installé des listes de diffusion et un serveur CVS indépendants, de même que le site gtk.php.net, avec l'aide de Colin Viebrock. La documentation demandait aussi de l'aide, et James Moore vient me porter une aide précieuse.
Depuis sa publication PHP-GTK a gagné en popularité. Nous avons notre propre équipe de documentation, et le manuel s'améliore de plus en plus. Des extensions ont été écrites pour PHP-GTK et des applications de plus en plus importantes sont concues.
Livres traitant de PHP
Comme PHP a évolué, il a été reconnu comme une plate forme de développement populaire. Un des signes qui ne trompe pas est le nombre de livres dédié à PHP a évolué paralellement.
Autant que nous le sachions, le premier livre dédié à PHP a été 'php- dynamische webauftritte professionell realisieren' - un livre en allemand, écrit par Egon Schmid, Christian Cartus et Richard Blume. Le premier livre en anglais sur PHP fut publié juste après : 'Core PHP Programming' par Leon Atkinson. Ces deux livres couvraient PHP 3.0.
Même si ces deux livres restent uniques dans leur genre, ils furent rapidement suivis par un grand nombre d'autres livres, de différents éditeurs. Il y a plus de 40 livres en anglais, 50 en allemand et plus de 20 en français. De plus, on peut maintenant trouver des livres sur PHP en espagnol, coréen, japonais et hébreux.
Clairement, ce nombre grandissant de livres, écrit par différents auteurs, publiés par différents éditeurs et leur disponibilité en différentes langues est un témoingnage du succès planétaire de PHP.
Publications about PHP
Autant que nous le sachions, le premier article consacré à PHP dans un magasine papier fut publié dans un magazine Francais, vers la fin 1998 et couvrait PHP 3.0. Comme tous les livres, ce fut le premier d'une longue série d'articles publiés dans différents magazines.
Des articles sur PHP ont été publiés dans Dr. Dobbs, Linux Enterprise, Linux Magazine et bien d'autres. Des articles sur la migration d'applications PHP vers un environnement Windows existe dans la librarie MSDN de Microsoft.
Annexe B. Migration de PHP 3.0 à PHP 4.0
Ce qui a changé en PHP 4.0
PHP 4.0 et le moteur Zend ont significativement amélioré les performances et les possibilités de PHP, tout en assurant une compatibilité ascendante maximale. Le maximum de codes existants sous PHP 3.0 fonctionneront sous PHP 4.0. La migration de votre code de PHP 3.0 vers PHP 4.0 sera beaucoup plus facile que celle de PHP/FI 2.0 vers 3.0. Un grand nombre de scripts seront prêts sans modifications, mais il est bon que vous connaissiez les quelques différences, et que vous testiez vos applications avant d'effecteur le changement de cadre de production. Les indications suivantes vous mettront sur la voie.
Utiliser PHP 3 et PHP 4 simultanément
Les systèmes d'exploitation récents disposent de capacités de versioning et de scoping. Ces fonctionnalités rendent possible l'installation de PHP 3 et PHP 4 comme modules Apache, simultanément.
Ceci a été fait sur les plate-formes suivantes :
Linux avec les binutils récents (testé avec binutils 2.9.1.0.25)
Solaris 2.5 ou plus récent
FreeBSD (testé avec 3.2, 4.0)
Pour l'activer, configurez PHP 3 et PHP 4 pour qu'ils utilisent APXS (--with-apxs) et les extensions nécessaires (--enable-versioning). En dehors de cela, toutes les instructions d'installation habituelles s'appliquent. Par exemple :
Migration des fichiers de configuration
Le fichier de configuration global, php3.ini, a été renommé en php.ini.
Pour les fichiers de configuration Apache, il y a eu des modifications plus importantes. Les types MIME reconnus par le module PHP ont été modifiés.
application/x-httpd-php3 --> application/x-httpd-php application/x-httpd-php3-source --> application/x-httpd-php-source |
Vous pouvez faire fonctionner vos deux versions de PHP avec le même fichier de configuration Apache (suivant la version qui est déjà compilée sur le serveur), en utilisant la syntaxe suivante :
AddType application/x-httpd-php3 .php3 AddType application/x-httpd-php3-source .php3s AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps |
De plus, les directives de nom de PHP pour Apache ont aussi été modifiées.
Depuis PHP 4.0, il n'y a que 4 directives Apache qui se rapportent à PHP :
php_value [PHP directive name] [value] php_flag [PHP directive name] [On|Off] php_admin_value [PHP directive name] [value] php_admin_flag [PHP directive name] [On|Off] |
Il y a deux différences entre les options Admin et les autres valeurs :
Les options Admin ne peuvent être placées que des le fichier de configuration général (i.e., httpd.conf).
Les valeurs Standard ne peuvent pas contrôler certaines directives PHP. Par exemple, le safe mode (si vous pouviez modifier les configurations dans le fichier .htaccess, cela annulerait toute la sécurité du safe mode. A l'inverse, les valeurs Admin peuvent modifier n'importe quelle directive PHP.
Pour rendre le processus de transition plus agréable, PHP 4.0 est distribué avec des scripts qui convertissent automatiquement vos configuration Apache et vos fichiers .htaccess pour qu'ils puissent fonctionner aussi bien avec PHP 3 que PHP 4. Ces scripts ne convertissent PAS les lignes concernant les types MIME. Vous devez le faire vous-même.
Pour convertir votre fichier de configuration Apache, exécutez le script apconf-conv.sh (disponible dans le dossier scripts/apache/). Par exemple :
Votre configuration originale sera sauvée dans le fichier httpd.conf.orig.
Pour convertir vos fichiers .htaccess, exécutez le script aphtaccess-conv.sh (disponible dans le dossier scripts/apache/). Par exemple :
De la même façon, votre vieux fichier .htaccess sera sauvé sous le nom .htaccess.orig.
Les scripts de conversion requièrent l'installation préalable de awk.
Comportement de l'analyseur
L'analyse et l'éxecution sont désormais deux étapes complètement dissociées, et l'éxécution intervient lorsque le code, ainsi que tous ses inclusions et pré-requis, ont été complètement analysés et validés.
Une des nouvelles conditions introduites est que les fichiers inclus et requis (include() et require()) doivent être syntaxiquement complets. Vous ne pouvez plus répartir différents cas de votre code dans plusieurs fichiers. Vous ne pouvez plus commencer une boucle for ou while, une condition if ou un cas switch dans un fichier, et finir la boucle ou placer les cas else, endif, case ou break dans un autre fichier.
Il est toujours valable d'inclure du code supplémentaire depuis une boucle ou dans une condition, mais les accolades de bloc {...}, et les éléments de la boucle doivent être dans le même fichier ou chaîne évaluée avec eval().
Cela ne devrait pas perturber trop de monde, car étaler son code de cette façon est plutôt un style à éviter.
Une autre nouveauté est qu'il est plus possible de faire retourner une valeur avec un fichier requis (require()) (mais c'est plutôt rare en PHP 3.0). Retourner une valeur avec un fichier inclus (include()) est toujours possible.
Rapport d'erreur
Changement de configuration
Avec PHP 3.0, le niveau de rapport d'erreur était obtenu en ajoutant les constantes numériques de chaque niveau de rapport. Généralement, on utilisait 15 pour afficher toutes les erreurs, et 7 pour afficher toutes les erreurs hormis les alertes simples.
PHP 4.0 dispose d'un nombre significativement plus grand de niveaux de rapport d'erreur, et l'analyseur comprend désormais les constantes, lors des modifications.
Le niveau de rapport d'erreur doit désormais être explicitement configuré en supprimant les niveaux dont vous ne voulez pas du niveau maximal, grâce à la fonction de OU exclusif. Ça a l'air compliqué? Supposons que vous souhaitiez afficher toutes les erreurs, hormis les alertes de style, qui sont repérées par la constante : E_NOTICE. Il suffit d'ajouter la valeur suivante dans le fichier php.ini: error_reporting = E_ALL & ~ ( E_NOTICE ). Si vous voulez supprimer en plus les alertes, vous pouvez ajouter la constante appropriée, en la combinant avec l'opérateur OU logique '|': error_reporting= E_ALL & ~ ( E_NOTICE | E_WARNING ).
| Avertissement |
L'utilisation des vieilles valeurs de 7 et 15 est une très mauvaise idée, car elles ne prennent pas en compte les nouvelles classes d'erreurs, y compris certaines erreurs d'analyse. Cela peut conduire à de très étranges résultats, où le script n'affiche plus rien, malgré une erreur d'analyse. Cela a conduit à un grand nombre de rapport d'erreur dans le passé, alors que les programmeurs n'étaient tout simplement pas capables de repérer l'accolade manquante, car l'analyseur avait la consigne de cacher ces erreurs. Vérifier votre niveau d'erreur doit être le premier réflexe lorsque vos scripts meurent silencieusement. Le moteur Zend est considéré actuellement comme suffisamment mature pour ne plus causer ce genre de problème aujourd'hui. |
Nouveaux messages d'erreurs
Un grand nombre de scripts PHP PHP 3.0 utilisent des structures qui doivent être considérées comme un très mauvais style, même s'il effectue bien la tâche qui lui est affectée, car ils ne sont pas robustes. PHP 4.0 affichera de nombreux messages d'erreurs dans des situations où PHP 3.0 restera coi. La solution de facilité consiste à supprimer les messages de niveau E_NOTICE, mais c'est une meilleure idée de corriger le code à la place.
Le cas le plus courant qui génèrera des messages d'alertes est l'utilisation de constantes sans guillemets comme index de tableaux. PHP 3.0, comme PHP 4.0, finiront par les interpréter littéralement comme des chaînes, si aucune constante n'est définie à la place. Mais si jamais une telle constante est définie dans une autre partie du code, cela risque de produire des résultats étonnants. Cela peut devenir un trou de sécurité si un pirate arrive à redéfinir les constantes de telle manière que le script lui donne accès à un niveau de droits supérieur. PHP 4.0 vous signalera tout oubli de guillemets comme par exemple dans : $HTTP_SERVER_VARS[REQUEST_METHOD]. Modifier ce code en $HTTP_SERVER_VARS['REQUEST_METHOD'] rendra l'analyseur heureux, et améliorera grandement votre style et la sécurité du code.
PHP 4.0 vous signalera les variables ou les éléments de tableaux non initialisés.
Initialiseur
Les variables statiques et les membres de classes n'acceptent plus que des initialiseurs scalaires, tandis que PHP 3.0 acceptait aussi les expressions. Cela est dÛ, encore une fois, à la séparation de l'analyse et de l'exécution : aucun code ne peut être exécuté tant que l'analyse n'est pas terminée.
Pour les classes, il vaut mieux initialiser les membres dans le constructeur. Pour les variables statiques, une valeur fixe et simple est la seule chose qui viennent à l'esprit.
empty("0")
L'évolution la plus polémique est celle de empty(). Une chaîne contenant seulement le caractère '0' (zéro) est maintenant considérée comme vide, alors qu'elle ne l'était pas en PHP 3.0.
Ce nouveau comportement prend tout son sens dans les applications web, puisque tous les résultats de champs de type input sont de type chaîne de caractères, même si un nombre est demandé, et ce, grâce aux capacités de conversion automatique de PHP. D'un autre côté, cela peut casser votre code d'une manière très subtile, menant droit au comportement erratique, difficilement repérable si vous ne savez pas ce qui vous attend.
Fonctions manquantes
Bien que PHP 4.0 dispose de nombreuses nouvelles fonctionnalités fonctions et extensions, vous vous rencontrer des fonctions PHP 3.0 qui manquent. Un petit nombre de fonctions de base n'ont pu être portées en PHP 4.0, maintenant que l'analyse et l'éxécution ont été séparées. D'autres fonctions, et mêmes des extensions entières sont maintenant obsolètes, remplacées par de nouvelles fonctions plus puissantes ou plus efficaces. Certaines fonctions n'ont tout simplement pas été portées pour le moment ou pour des raisons de licences.
Fonctions manquantes pour des raisons de structure
Comme PHP 4.0 sépare l'analyse et l'éxécution, il n'est plus possible de modifier le comportement de l'analyseur (intégré dans le moteur Zend) durant l'éxécution, puisque toute l'analyse a eu lieu, et est terminée. La fonction short_tags() a cessé d'exister. Vous pouvez toujours modifier le comportement de l'analyseur avec le fichier php.ini.
Une autre fonctionnalité qui a disparu est le débuggeur de PHP 3.0, comme décrit dans un autre appendice. Un nouveau débuggeur est promis par Zend, mais il n'a pas encore montré le bout de son nez.
Fonctions et extensions obsolètes
Les extensions Adabas et Solid n'existent plus. Elles sont intégrées dans les fonctions ODBC Unifié.
Nouveau statut pour unset()
unset(), bient que toujours disponible, a été implémenté légèrement différemment en PHP 4.0, et elle n'est plus vraiment une 'fonction'.
Cela n'a pas de conséquence directe sur le comportement de unset(), mais utiliser cette fonction pour faire un test avec function_exists() retournera FALSE comme il se doit avec les fonction bas niveau comme echo().
Une autre application pratique disparue est qu'il n'est plus possible d'appeler unset() indirectement, c'est-à-dire que $func="unset"; $func($somevar) ne fonctionne plus.
Extensions PHP 3.0
Les extensions écrites pour PHP 3.0 ne fonctionnent plus avec PHP 4.0, ni les exécutables, ni les codes sources. Il n'est pas difficile de porter les extensions de PHP 3.0 à 4.0 si vous avez accès aux sources originales. Une description détaillée du processus de portage ne fait pas partie de cet appendice (pour le moment).
Substitution de variables dans les chaînes
PHP 4.0 dispose d'un nouveau mécanisme de substitution des variables dans les chaînes. Vous pouvez désormais accéder aux membres d'objets et aux tableaux multidimensionnels dans une chaîne.
Pour cela, il suffit de placer la variable entre accolades, le signe $ suivant immédiatement la première accolade : {$variable['a']}
Pour utiliser la valeur d'un membre d'objet dans une chaîne, il suffit d'écrire : "text {$obj->member} text"; alors qu'en PHP 3.0, il fallait faire comme ceci : "texte".$objet->membre." texte".
Cette technique rend le code beaucoup plus lisible, mais risque de poser des problèmes dans certains scripts PHP 3.0. Vous pouvez facilement traquer ce problème en recherche les séquences {$ dans votre code, et en les remplaçant par \{$ avec votre outil de remplacement habituel.
Cookies
PHP 3.0 avait la mauvaise habitude d'envoyer les cookies dans l'ordre inverse de celui du code (l'ordre des appels à setcookie()). PHP 4.0 rétablit l'ordre naturel en les envoyant dans le même ordre que vous même.
Cela peut aussi prendre à contre-pied certains programmes, mais ce comportement était tellement étrange qu'il méritait un tel traitement un jour ou l'autre, pour éviter d'autres problèmes ultérieurs.
Annexe C. Migration de PHP/FI 2.0 à PHP 3.0
A propos des incompatibilités en 3.0
PHP 3.0 a été entièrement réécrit. Le nouvel analyseur syntaxique est beaucoup plus robuste et cohérent qu'en version 2.0. Il est aussi nettement plus rapide et utilise encore moins de mémoire. Cependant, ces améliorations n'ont pu être possible qu'au prix de modifications parfois importantes, tant au niveau des syntaxes, qu'au niveau des fonctionnalités.
De plus, l'équipe de développement PHP a essayé de nettoyer la syntaxe et les sémantiques, ce qui a aussi causé quelques incompatibilités. A long terme, nous pensons que ces modifications seront pour le bien de tous.
Ce chapitre va tenter de vous montrer les incompatibilités que vous pourriez rencontrer lors de votre migration de PHP/FI 2.0 à PHP 3.0 et de vous aider à les résoudre. Les nouvelles fonctionnalités ne sont pas signalées, à moins que cela ne soit nécessaire.
Un programme de conversion automatique de vos vieux script PHP/FI 2.0 existe. Il est disponible dans le dossier de convertisseur de la distribution PHP 3.0. Ce programme ne fait que repérer les modifications de syntaxe et ne vous épargnera pas une relecture attentive du script.
Balises PHP
La première chose que vous remarquerez probablement est que les balises de PHP start et end ont changé. L'ancienne forme <? ?> a été remplacée par trois nouvelles balises possibles :
Syntaxe if..endif
La syntaxe alternative pour écrire des instructions if/elseif/else, avec if(); elseif(); else; endif; ne pouvait pas être conservée sans ajouter beaucoup de complexité à l'analyseur syntaxique. De ce fait, cette syntaxe à changée :
Syntaxe while
Tout comme pour if..endif, la syntaxe des boucles while..endwhile a changée :
| Avertissement |
Attention : si vous utilisez la vieille syntaxe while..endwhile en PHP 3.0, vous obtiendrez une boucle sans fin ! |
Types d'expression
PHP/FI 2.0 utilisait le membre à gauche dans les expressions, pour déterminer le type de résultat attendu. PHP 3.0 prend en compte les deux côtés de l'expression et cela peut produire des résultats inattendus avec les scripts 2.0.
Considérez les lignes suivantes:
En PHP/FI 2.0, cet exemple va afficher les indices des $a. En PHP 3.0, l'exemple ne va rien afficher du tout. La raison est qu'en PHP 2.0, puisque l'argument de gauche est de type chaîne, une comparaison de chaîne était effectuée et, effectivement, "" n'est pas "", ce qui conduit la boucle à continuer. En PHP 3, lorsqu'une chaîne est comparée avec un entier, la comparaison est de type chaîne (la chaîne est convertie en entier). Ce qui revient à faire la comparaison entre (atoi("")) qui vaut 0 et la variable qui vaut aussi 0 et comme 0==0, la boucle ne commence même pas.La correction de ceci est simple : il suffit de remplacer les commandes while par:
Les messages d'erreur ont changé
Les messages d'erreur en PHP 3.0 sont généralement plus précis que ceux de la version 2.0., mais vous ne verrez plus la portion de code qui a causé l'erreur. A la place, un numéro de ligne et un nom de fichier sera retourné.
Evaluation rapide des booléens
En PHP 3., l'évaluation des est court-circuité. Cela signifie dans une expression telle que ((1 || test_me())), la fonction test_me() ne sera pas exécutée, car cela ne changera pas le résultat.
C'est une amélioration mineure, mais qui peut avoir des effets secondaires importants.
La valeur TRUE/FALSE comme retour de fonctions
La plupart des fonctions internes de PHP ont été réécrite pour qu'elle retourne TRUE en cas de succès, et FALSE en cas d'erreur, au contraire des fonctions qui retournaient 0 et -1 en PHP/FI 2.0. Le nouveau comportement est beaucoup plus logique, comme par exemple $fp = fopen("/your/file") or fail("fichier non trouvé!");. Etant donné que PHP/FI 2.0 n'a pas de règle claire à propos de ce que les fonctions doivent retourner en cas d'échec, la plupart des scripts devront probablement être vérifié manuellement, après avoir utilisé le convertisseur 2.0 à 3.0.
Diverses incompatibilités
Le module PHP 3.0 pour Apache n'accepte plus les versions d'Apache antérieure à la version 1.2. Apache 1.2 ou plus récent est nécessaire.
echo() n'utilise plus de chaîne de formatage. Il faut utiliser printf() à la place.
En PHP/FI 2.0, un effet secondaire de l'implémentation faisait que $foo[0] était la même chose que $foo. Ce n'est plus vrai en PHP 3.0.
Lire un tableau avec $array[] n'est plus valable.
Ainsi, il n'est plus possible de passer en revue un tableau avec des boucles telles que $data = $array[]. Utilisez current() et next() à la place.
Ainsi, $array1[] = $array2 n'ajoute pas les valeurs de $array2 à $array1, mais crée un nouvel élément dans $array1 et y affecte $array2 comme dernier élément. Voir aussi les tableaux multidimensionnels.
"+" n'est plus utilisable comme opérateur de concaténation de chaîne. A la place, il convertit les arguments en nombres et effectue une addition numérique. Utilisez "." à la place.
Exemple C-11. Migration depuis 2.0: concaténation de chaînes
En PHP 2.0 cela retournerait 11, en PHP 3.0 cela va retourner 2. A la place, faites :
Cela va afficher 2, tant en PHP 2.0 qu'en 3.0.
|
Annexe D. Débuggeur PHP
A propos du débuggeur
PHP 3 inclut le support d'un serveur de débuggage.
PHP 4 n'inclut aucun support de débuggage.
Utiliser le débuggeur PHP
Le débuggeur PHP sert à repérer les bugs récalcitrants. Le débuggeur fonctionne en se connectant à un port TCP à chaque démarrage de PHP. Tous les messages d'erreur seront envoyés sur cette connexion. Cette page est faite pour un "serveur de débuggage", qui peut fonctionner avec un IDE ou un éditeur programmable (tel que Emacs).
Comment paramétrer le débuggeur :
Réservez un port TCP pour le débuggeur dans le fichier de configuration (debugger.port) et activez-le (debugger.enabled).
Configurer un client TCP sur ce port (par exemple socket -l -s 1400 sous UNIX).
Dans votre code, placez la ligne "debugger_on(host)", où host est l'IP ou le nom de l'hôte qui supporte le client TCP.
Protocole du débuggeur
Le protocole de débugage PHP 3 fonctionne ligne par ligne. Chaque ligne a un type type et plusieurs lignes composent un message Chaque message commence avec une ligne du type start et se termine avec une ligne de type end. PHP peut envoyer des lignes de plusieurs messages simultanément.
Voici un exemple de ligne à ce format :
- date
Les dates sont au format ISO 8601 (yyyy-mm-dd)
- time
Les heures, y compris les micro-secondes: hh:mm:uuuuuu
- host
Le nom DNS ou adresse IP de l'hôte qui a généré l'erreur.
- pid
PID (process id) sur l'hôte host, qui a généré l'erreur.
- type
Type de la ligne. Indique au programme client comment traiter les données suivantes :
Tableau D-1. Types des lignes du Débuggeur
Nom Signification start Indique au programme client que le message du débuggeur commence ici. Le contenu de data sera un type d'erreur, comme listé ci-dessous. message Le message d'erreur PHP 3. location Nom du fichier et numéro de ligne, où l'erreur est survenue. La première occurrence de location contiendra toujours la localisation générale. data contiendra : file:line. Il y a toujours une indication de location après un message et après chaque function. frames Nombre de frames dans le dump de la pile. S'il y a 4 frames, attendez vous à des informations sur 4 niveaux de fonctions. Si la ligne "frame" n'existe pas, la profondeur doit être 0 (une erreur est survenue au niveau général). function Nom de la fonction qui a généré l'erreur. Elle sera répétée à chaque niveau de la pile d'appel. end Indique au client que le message du débuggeur se termine ici. - data
Ligne de données.
Tableau D-2. Types d'erreur du débuggeur
| Débuggeur | Interne PHP 3 |
|---|---|
| alerte (warning) | E_WARNING |
| erreur | E_ERROR |
| analyse (parse) | E_PARSE |
| note (notice) | E_NOTICE |
| core-error | E_CORE_ERROR |
| core-warning | E_CORE_WARNING |
| inconnue | (toutes les autres) |
Exemple D-1. Exemple de message du débuggeur
|
Annexe E. Développement PHP
Créer une fonction PHP 3
Prototypes de fonctions
Toutes les fonctions suivent le schéma suivant :
void php3_foo(INTERNAL_FUNCTION_PARAMETERS) {
} |
Arguments de fonctions
Les arguments sont toujours de type val. Ce type contient un membre de type union, qui indique le type reél d'argument. De cette façon, si votre fonction prend deux arguments, elle ressemble à ceci :
Lorsque vous modifiez l'un des paramètres, qu'ils soient envoyés par référence ou par valeur, vous pouvez le passer à pval_destructor pour le réinitialiser, ou, s'il s'agit d'un tableau et que vous voulez ajouter des valeurs, vous pouvez utiliser des fonctions similaires à celles qui sont dans internal_functions.h, qui manipule return_value comme tableau.
Par ailleurs, si vous modifiez un paramètre en IS_STRING, assurez-vous que vous avez bien assigné un nouvelle chaîne avec estrdup() et une nouvelle longueur de chaîne. Seulement après, vous pouvez modifier le type en IS_STRING. Si vous modifiez une chaîne en IS_STRING ou IS_ARRAY vous devez d'abord appeler le destructeur pval_destructor.
Fonctions à nombre d'arguments variable
Une fonction peut prendre un nombre variable d'arguments. Si votre fonction peut prendre deux ou trois arguments, utiliser la syntaxe suivante :
Utiliser les arguments d'une fonction
De type de chaque argument est stocké dans le champs pval. Ce champs peut prendre les valeurs suivantes :
Tableau E-1. Types de données interne PHP
| IS_STRING | Chaîne de caractères |
| IS_DOUBLE | Nombre à virgule flottante, en précision double |
| IS_LONG | Entier long |
| IS_ARRAY | Tableau |
| IS_EMPTY | Aucune |
| IS_USER_FUNCTION | ?? |
| IS_INTERNAL_FUNCTION | ?? (Si ce type ne peut pas être passé à une fonction, effacez-le) |
| IS_CLASS | ?? |
| IS_OBJECT | ?? |
Si vous recevez un argument d'un type, et que vous voulez l'utiliser avec un autre type, ou si vous voulez simplement forcer le type, vous pouvez utiliser l'une des fonctions de conversion suivantes :
convert_to_long(arg1); convert_to_double(arg1); convert_to_string(arg1); convert_to_boolean_long(arg1); /* Si la chaîne est "" ou "0" elle devient 0, 1 sinon */ convert_string_to_number(arg1); /* Convertit une chaîne en LONG ou DOUBLE suivant la chaîne */ |
Ces fonctions convertissent sur place : elles ne retournent aucune valeur.
La valeur de l'argument est enregistrée dans une union. Les membres sont :
IS_STRING: arg1->value.str.val
IS_LONG: arg1->value.lval
IS_DOUBLE: arg1->value.dval
Gestion de la mémoire dans une fonction
Toute la mémoire nécessaire à une fonction doit être allouée avec emalloc() ou estrdup(). Ces fonctions ont le goÛt et l'odeur des fonctions C classiques malloc() et strdup(). La mémoire doit être libérée avec efree().
Il y a deux types de mémoire dans ce programme : la mémoire qui est retournée à l'analyseur, et la mémoire qui nécessaire pour le stockage temporaire dans la fonction. Lorsque vous assignez une chaîne dans une variable qui est retournée à l'analyseur, assurez-vous de bien allouer la mémoire avec emalloc() ou estrdup(). Cette mémoire ne doit JAMAIS être libérée, sauf si vous réécrivez votre original plus loin, dans la même fonction (mais ce n'est pas de la programmation propre).
Pour tous vos besoins en mémoire temporaire/permanante dont vous avez besoin dans vos fonctions/librairies, vous devez utiliser les fonctions emalloc(), estrdup() et efree(). Elles se comportent EXACTEMENT comme leurs homologues. Tout ce qui est créé avec emalloc() ou estrdup() doit être libéré avec efree() à un moment ou un autre, à moins que ce ne soit utile ailleurs dans le programme; sinon, il va y avoir une fuite de mémoire. La signification de "Elles se comportent EXACTEMENT comme leurs homologues" est que si vous libérez une variable qui n'a pas été créée avec emalloc() ou estrdup(), vous courez droit à au crash ("segmentation fault"). Soyez alors extrêmement prudent, et libérez toute votre mémoire inutilisée.
Si vous compilez avec "-DDEBUG", PHP 3 affichera la liste de tous les appels à emalloc() et estrdup() mais jamais à efree() lorsque celui-ci intervient dans un script spécifié.
Affecter une variable dans la table des symboles
Un grand nombre de macros sont disponibles pour rendre plus facile l'insertion de variables dans la table des symboles :
SET_VAR_STRING(name,value)
SET_VAR_DOUBLE(name,value)
SET_VAR_LONG(name,value)
Gestion de la mémoire
Soyez prudent. La valeur doit être placée dans une portion de mémoire créée avec malloc(), sinon le gestionnaire de mémoire essayera de libérer le pointeur plus tard. Ne passez aucune mémoire allouée statiquement à SET_VAR_STRING.
Les tables des symboles de PHP 3 est une table de hash. A n'importe quel moment, &symbol_table est un pointeur sur la table principale, et active_symbol_table pointe sur la table actuellement utilisée. (ces deux tables peuvent être identiques au démarrage, ou différent, suivant que vous êtes dans une fonction ou non).
Les exemples suivants utilisent 'active_symbol_table'. Vous devriez la remplacer par &symbol_table si vous voulez travailler sur la table principale. De plus, les mêmes fonctions peuvent être appliquées à des tableaux, comme expliqué ci-dessous.
Si vous voulez définir un nouveau tableau dans la table des symboles, utilisez le code suivant.
D'abord, vous devez vérifier qu'il n'existe pas, avec hash_exists() ou hash_find().
Puis, initialisez le tableau :
Voici comment ajouter deux nouvelles entrées dans ce tableau :
Exemple E-6. Ajout d'entrées dans un tableau.
|
hash_next_index_insert() utiliser plus ou moins la même logique que "$foo[] = bar;" in PHP 2.0.
Si vous construisez un tableau, pour le retourner, vous pouvez l'initialiser comme ceci :
if (array_init(return_value) == FAILURE) { échec...; } |
puis ajouter les valeurs grâces aux macros:
add_next_index_long(return_value,long_value); add_next_index_double(return_value,double_value); add_next_index_string(return_value,estrdup(string_value)); |
Bien sÛr, si l'ajout n'est pas fait juste après l'initialisation, vous devrez d'abord rechercher le tableau :
pval *arr;
if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE)
{ introuvable... }
else
{ utilisez arr->value.ht... } |
Notez que hash_find reçoit un pointeur sur un pointeur sur pval, et pas un pointeur sur pval.
Toutes les fonctions d'accès aux hash retourne TRUE (SUCCES) ou FALSE (FAILURE), excepté hash_exists(), qui retourne un booléen.
Retourne une valeur simple
Un grand nombre de macros sont disponible pour simplifier le retour des valeurs.
La macro RETURN_* fixe la valeur de retour, et termine la fonction :
RETURN
RETURN_FALSE
RETURN_TRUE
RETURN_LONG(l)
RETURN_STRING(s,dup) Si dup est TRUE, duplique la chaîne.
RETURN_STRINGL(s,l,dup) retourne la chaîne (s) en spécifiant la longueur (l).
RETURN_DOUBLE(d)
La macro RETVAL_* macros fixe la valeur de retour, mais ne termine pas la fonction.
RETVAL_FALSE
RETVAL_TRUE
RETVAL_LONG(l)
RETVAL_STRING(s,dup) Si dup est TRUE, duplique la chaîne
RETVAL_STRINGL(s,l,dup) retourne la chaîne (s) en spécifiant la longueur (l).
RETVAL_DOUBLE(d)
Les macros ci-dessus vont utiliser estrdup() sur les arguments passés. Cela vous permet de libérer tranquillement les arguments après avoir appelé cette fonction, ou bien, utiliser de la mémoire allouée statiquement.
Si votre fonction retourne un booléen de succès/erreur, utilisez toujours RETURN_TRUE et RETURN_FALSE respectivement.
Retourner des valeurs complexes
Votre fonction peut aussi retourner des valeurs complexes, tels que des objets ou tableaux.
Retourner un objet:
Appeler object_init(return_value).
Remplissez les valeurs. Les fonctions utilisables sont listées ci dessous.
Eventuellement, enregistrez les fonctions pour cet objet. Afin de lire des valeurs de cet objet, la fonction doit lire dans "this", dans la table de symbole active active_symbol_table. Son type doit être IS_OBJECT, et c'est une table de hash basique. (i.e., vous pouvez utiliser les fonctions habituelles de .value.ht). L'enregistrement reél peut être fait comme suit :
add_method( return_value, function_name, function_ptr );
Les fonctions d'accès aux objets sont :
add_property_long( return_value, property_name, l ) - Ajoute un membre nommé 'property_name', de type long, égal à 'l'
add_property_double( return_value, property_name, d ) - Idem, ajoute un double
add_property_string( return_value, property_name, str ) - Idem, ajoute une chaîne
add_property_stringl( return_value, property_name, str, l ) - Idem, ajoute une chaîne de longueur 'l'.
Retournez un tableau :
Appelez array_init(return_value).
Remplissez les valeurs. Les fonctions disponibles sont listées ci-dessous.
Les fonctions utilisées pour accéder à un tableau sont :
add_assoc_long(return_value,key,l) - Ajoute une entrée associative avec la clé 'key' et la valeur 'l', de type long
add_assoc_double(return_value,key,d) - Ajoute une entrée associative avec la clé 'key' et la valeur 'l', de type double
add_assoc_string(return_value,key,str,duplicate)
add_assoc_stringl(return_value,key,str,length,duplicate) spécifie la taille d'une chaîne
add_index_long(return_value,index,l) - Ajoute une entrée d'index index' avec la valeur 'l', de type long
add_index_double(return_value,index,d)
add_index_string(return_value,index,str)
add_index_stringl(return_value,index,str,length) - spécifie la longueur de la chaîne.
add_next_index_long(return_value,l) - ajoute une entrée tableau, dans le prochain offset libre, de longueur 'l', de type long
add_next_index_double(return_value,d)
add_next_index_string(return_value,str)
add_next_index_stringl(return_value,str,length) - spécifie la taille d'une chaîne
Utiliser la liste des ressources
PHP 3.0 dispose de standards pour traiter un certains nombre de ressources. Ils remplacent tous les listes de PHP 2.0.
Fonctions accessibles :
php3_list_insert(ptr, type) - retourne l'identifiant 'id' de la nouvelle ressource insérée.
php3_list_delete(id) - efface la ressource d'identifiant id
php3_list_find(id,*type) - retourne le pointeur de la ressource d'identifiant id, et modifie le type 'type'
La liste standard de code ressemble à ceci :
Exemple E-8. Utiliser une ressource existante
|
Utiliser la table des ressources persistantes.
PHP 3.0 dispose d'une lieu de stockage des ressources persistantes (i.e., les ressources qui doivent être conservées d'un hit à l'autre). Le premier module a utiliser cette capacité a été MySQL, et mSQL suivi, ce qui fait que l'on peut se faire une impression du fonctionnement de cette fonction avec mysql.c. Les fonctions ressemblent à ceci :
| php3_mysql_do_connect |
| php3_mysql_connect() |
| php3_mysql_pconnect() |
L'idée conductrice de ces modules est la suivante :
Programmez tout votre module pour qu'il travaille avec les ressources standard, comme mentionné dans la section (9).
Ajoutez une autre fonction de connexion, qui vérifie d'abord que la ressource existe dans la liste des ressources persistantes. Si c'est le cas, enregistrez cette ressource comme pour les ressources standard (et grâce à la première étape, cela va fonctionner immédiatement). Si la ressource n'existe pas, créez la, ajoutez la à la liste de ressources persistantes, et ajoutez la à la liste de ressources, ce qui fait que le code va fonctionner, et que le prochain appel renverra une ressource existante. Vous devez enregistrer ces fonctions avec un type différent (LE_MYSQL_LINK pour les liens non persistants, et LE_MYSQL_PLINK pour les liens persistants).
Si vous jetez un oeil dans mysql.c, vous verrez que, hormis la fonction de connexion complexe, rien n'a du être changé dans le module.
La même interface existe pour la liste des ressources standard, et pour la liste des ressources persistantes, seule la 'list' est remplacée par 'plist':
php3_plist_insert(ptr, type) - retourne l'identifiant 'id' de la nouvelle ressource insérée.
php3_plist_delete(id) - efface la ressource d'identifiant id
php3_plist_find(id,*type) - retourne le pointeur de la ressource d'identifiant id, et modifie le type 'type'
Cependant, il est probable que ces fonctions seront inutiles pour vous, lorsque vous essayerez d'implémentez un module persistant. Typiquement, on utiliser le fait que la liste de ressources persistantes est une table de hash. Par exemple, dans les modules MySQL/mSQL, lors d'un appel à pconnect(), la fonction construit une chaîne avec l'hôte/utilisateur/mot_de_passe, et l'utilise pour enregistrer dans la table de hash. Au prochain appel, avec les mêmes hôte/utilisateur/mot_de_passe, la même clé sera générée, et la ressource associée sera retrouvée.
Jusqu'à ce que la documentation s'étoffe, jetez un oeil aux fichiers mysql.c ou msql.c pour voir comment implémentez vos accès aux ressources persistantes.
Une chose importante à noter : les ressources qui sont enregistrées dans la liste de ressource persistante ne DOIVENT PAS être allouée avec le gestionnaire de mémoire PHP, c'est-à-dire qu'elles ne doivent pas être créée avec emalloc(), estrdup(), etc. Au contraire, il faut utiliser les fonctions standard malloc(), strdup(), etc. La raison est for simple : à la fin de la requête, la mémoire sera supprimée par le gestionnaire. Etant donné que les liens persistants doivent être conservés, il ne faut pas utiliser le gestionnaire de mémoire.
Lorsque vous enregistrez une ressource qui sera placé dans la liste de ressources persistantes, il faut ajouter les destructeurs dans les deux listes de ressources, persistantes ou pas. Le destructeur de la liste de ressources non persistantes ne doit rien faire du tout, tandis que celui de la liste de ressources persistantes doit libérer proprement toutes les ressources acquises (mémoire, lien SQL...). Commep pour les ressources non persistantes vous DEVEZ ajouter un destructeur, même s'il ne fait rien. N'oubliez pas que emalloc() et compagnie ne doivent pas être utilisé en conjonction avec la liste de ressources persistantes, et donc, vous ne devez pas utiliser efree() non plus.
Ajouter des directives de configuration à l'exécution
De nombreuses caractéristiques de PHP 3 peuvent être configurée à l'éxécution. Ces directives peuvent apparaître dans le fichier php3.ini, ou, dans le cas du module Apache, dans le fichier .conf. L'avantage de l'avoir dans le fichier .conf, est que ces caractéristiques peuvent être configurées dossier par dossier. Cela signifie qu'un dossier peut avoir un safe mode exec dir, tandis qu'un autre en aura un autre. Cette granularité de la configuration peut être extrêmement pratique lorsque le serveur supporte plusieurs serveurs virtuels.
Les étapes de configuration d'une nouvelle directive sont :
Ajouter la directive à la structure php3_ini_structure dans le fichier mod_php3.h.
Dans main.c, éditez la fonction php3_module_startup et ajoutez l'appel aproprié à cfg_get_string() ou cfg_get_long().
Ajoutez la directive, ses restrictions et un commentaire dans la structure php3_commands du fichier mod_php3.c. Notez la partie restrictions RSRC_CONF sont des directives qui ne peuvent être disponibles que dans le fichier de configuration Apache. Toutes les directives OR_OPTIONS peuvent être placées n'importe où, y compris dans un fichier .htaccess.
Soit dans php3take1handler(), soit dans php3flaghandler(), ajoutez l'entrée appropriée pour votre directive.
Dans la section de configuration, de _php3_info(), dans le fichier functions/info.c, vous devez ajouter votre configuration.
Finalement, vous devez utiliser votre configuration quelque part. Elle sera accessible par php3_ini.directive.
Appeler des fonctions utilisateurs
Pour appeler des fonctions utilisateurs depuis une fonction interne, vous devez utiliser la fonction call_user_function().
call_user_function() retourne SUCCESS en cas de succès, et FAILURE en cas d'échec, ou si la fonction n'a pas été trouvée. Vous devez vérifier cette valeur. Si la réponse est SUCCESS, vous êtes responsable de la destruction de retval (ou alors, retournez la comme valeur de réponse de votre fonction). Si la réponse est FAILURE, la valeur de retval est indéfinie, et vous ne devez pas y toucher.
Toutes les fonctions internes qui appellent une fonction utilisateur, DOIVENT être réentrante. En particulier, elles ne doivent pas utiliser de valeurs globales, ou de variables statiques.
call_user_function() prend 6 arguments :
pval *object
Un pointeur sur un objet sur lequel la fonction est invoquée. Il devrait être à NULL, si on invoque une fonction globale. Si il n'est pas à NULL (ie, il pointe sur un objet), l'argument function_table est ignorée, et la liste des fonctions sera lue dans l'objet, plutôt que dans l'argument. L'objet PEUT être modifié par la fonction qui est appelée (la fonction y aura accès via $this). Si, vous quelque raison, vous ne le voulez pas, envoyez une copie de l'objet à la place.
pval *function_name
Le nom de la fonction à appeler. Elle doit être de type pval, IS_STRING, avec les valeurs de function_name.str.val et function_name.str.len correctes. function_name est modifié par call_user_function() - il est converti en minuscule. Si vous voulez préserver la casse, envoyez une copie du nom de la fonction.
pval *retval
Un pointeur sur une structure pval, dans laquelle la valeur de retour de la fonction sera placée. La structure doit avoir été allouée au préalable, - call_user_function() ne l'allouera pas.
pval *params[]
Un tableau de pointeur sur les valeurs qui vont être passées comme arguments à la fonction. Le premier argument est à l'offset 0, le second à l'offset 1,... Le tableau est un tableau de pointeurs sur pval; Les pointeurs sont envoyés tels quels à la fonction, ce qui signifie que si la fonction modifie les arguments, les valeurs originales seront modifiées. Si vous voulez l'éviter, passez une copie à la place.
Rapport d'erreurs
Pour signaler les erreurs d'une fonction interne, vous devez appelez la fonction php3_error(). Cette fonction prend deux arguments au moins : le niveau de l'erreur, et le message d'erreur, sous forme de chaîne de caractères. Tous les arguments suivants sont des paramètres de formats de chaîne. Les niveaux d'erreurs sont :
E_NOTICE
Les notes ne sont pas affichées par défaut, et indique que le script a rencontré quelque chose qui peut être une erreur, mais peut aussi être un événement normal dans la vie du script. Par exemple, essayer d'accéder à une valeur qui n'a pas été déclarée, ou appeler stat() sur un fichier qui n'existe pas.
E_WARNING
Les alertes sont affichées par défaut, mais n'interrompent pas l'éxécution du script. Elles indiquent un problème qui doit être intercepté par le script avant que l'appel. Par exemple, appeler ereg() avec une regex invalide.
E_ERROR
Les erreurs sont aussi affichées par défaut, et l'exécution du script est interrompue. Elles indiquent des erreurs qui ne peuvent pas être ignorées, comme des problèmes d'allocation de mémoire, par exemple.
E_PARSE
Les erreurs d'analyse de doivent être générées que par l'analyseur. Elles ne sont citées ici que dans le but d'être exhaustif.
E_CORE_ERROR
Elles sont similaires aux erreurs E_ERROR, mais elles sont générées par le code de PHP. Les fonctions ne doivent pas générer ce genre d'erreur.
E_CORE_WARNING
Elles sont similaires à E_WARNING, mais elles sont générées par le code de PHP. Les fonctions ne doivent pas générer ce genre d'erreur.
E_COMPILE_ERROR
Elles sont similaires à E_ERROR, mais elles sont générées par Zend Scripting Engine. Les fonctions ne doivent pas générer ce genre d'erreur.
E_COMPILE_WARNING
Elles sont similaires à E_WARNING, mais elles sont générées par Zend Scripting Engine. Les fonctions ne doivent pas générer ce genre d'erreur.
E_USER_ERROR
E_USER_ERROR est comparable à E_ERROR. Elle est générée en PHP par l'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur.
E_USER_WARNING
E_USER_WARNING est comparable à E_WARNING. Elle est générée en PHP par l'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur.
E_USER_NOTICE
E_USER_WARNING est comparable à E_NOTICE. Elle est générée en PHP par l'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur.
Annexe F. Liste d'alias
Voici la liste des aliases. Tous les alias sont listés ci-dessous. C'est une très mauvaise habitude d'utiliser ces alias, car ils risquent à tous moment de disparaître, rendus obsolète sans préavis, ou bien par un simple changement de nom, ce qui rend votre script inutilisable avec des versions plus récentes de PHP. Préférez toujours les versions officielles. En fait, cette liste est surtout destinées à ceux qui doivent mettre à jour leur scripts avec les syntaxes plus récentes.
Cette liste est en phase avec PHP 4.0.6.
Tableau F-1. Aliases
| Alias | Fonction principale | Extension mère |
|---|---|---|
| rtrim | chop() | Syntaxe de base |
| close | closedir() | Syntaxe de base |
| sizeof | count() | Syntaxe de base |
| pos | current() | Syntaxe de base |
| fputs | fwrite() | Syntaxe de base |
| dir | getdir() | Syntaxe de base |
| show_source | highlight_file () | Syntaxe de base |
| join | implode() | Syntaxe de base |
| ini_alter | ini_set() | Syntaxe de base |
| is_float | is_double() | Syntaxe de base |
| is_real | is_double() | Syntaxe de base |
| is_int | is_long() | Syntaxe de base |
| is_integer | is_long() | Syntaxe de base |
| is_writeable | is_writable() | Syntaxe de base |
| rewind | rewinddir() | Syntaxe de base |
| magic_quotes_runtime | set_magic_quotes_runtime() | Syntaxe de base |
| strchr | strstr() | Syntaxe de base |
| cv_add | ccvs_add() | CCVS |
| cv_auth | ccvs_auth() | CCVS |
| cv_command | ccvs_command() | CCVS |
| cv_count | ccvs_count() | CCVS |
| cv_delete | ccvs_delete() | CCVS |
| cv_done | ccvs_done() | CCVS |
| cv_init | ccvs_init() | CCVS |
| cv_lookup | ccvs_lookup() | CCVS |
| cv_new | ccvs_new() | CCVS |
| cv_report | ccvs_report() | CCVS |
| cv_return | ccvs_return() | CCVS |
| cv_reverse | ccvs_reverse() | CCVS |
| cv_sale | ccvs_sale() | CCVS |
| cv_status | ccvs_status() | CCVS |
| cv_textvalue | ccvs_textvalue() | CCVS |
| cv_void | ccvs_void() | CCVS |
| com_get | com_propget() | COM |
| com_propset | com_propput() | COM |
| com_set | com_propput() | COM |
| add_root | domxml_add_root() | DOM XML |
| attributes | domxml_attributes() | DOM XML |
| name | domxml_attrname() | DOM XML |
| children | domxml_children() | DOM XML |
| children | domxml_children() | DOM XML |
| dumpmem | domxml_dumpmem() | DOM XML |
| domxml_getattr | domxml_get_attribute() | DOM XML |
| getattr | domxml_get_attribute() | DOM XML |
| get_attribute | domxml_get_attribute() | DOM XML |
| dtd | domxml_intdtd() | DOM XML |
| lastchild | domxml_last_child() | DOM XML |
| last_child | domxml_last_child() | DOM XML |
| new_child | domxml_new_child() | DOM XML |
| new_xmldoc | domxml_new_xmldoc() | DOM XML |
| node | domxml_node() | DOM XML |
| parent | domxml_parent() | DOM XML |
| root | domxml_root() | DOM XML |
| domxml_setattr | domxml_set_attribute() | DOM XML |
| setattr | domxml_set_attribute() | DOM XML |
| set_attribute | domxml_set_attribute() | DOM XML |
| set_content | domxml_set_content() | DOM XML |
| unlink | domxml_unlink_node() | DOM XML |
| xpath_eval | xpath_eval() | DOM XML |
| xpath_eval_expression | xpath_eval_expression() | DOM XML |
| xpath_init | xpath_init() | DOM XML |
| xpath_new_context | xpath_new_context() | DOM XML |
| xptr_new_context | xpath_new_context() | DOM XML |
| fbsql | fbsql_db_query() | FrontBase |
| imap_fetchtext | imap_body() | IMAP |
| imap_create | imap_createmailbox() | IMAP |
| imap_header | imap_headerinfo() | IMAP |
| imap_listmailbox | imap_list() | IMAP |
| imap_getmailboxes | imap_list_full() | IMAP |
| imap_scanmailbox | imap_listscan() | IMAP |
| imap_scan | imap_listscan() | IMAP |
| imap_listsubscribed | imap_lsub() | IMAP |
| imap_getsubscribed | imap_lsub_full() | IMAP |
| imap_rename | imap_renamemailbox() | IMAP |
| ldap_close | ldap_unbind() | LDAP |
| ming_setcubicthreshold | ming_setcubicthreshold() | Ming (Flash) |
| ming_setscale | ming_setscale() | Ming (Flash) |
| swfaction | swfaction_init() | Ming (Flash) |
| getheight | swfbitmap_getheight() | Ming (Flash) |
| getwidth | swfbitmap_getwidth() | Ming (Flash) |
| swfbitmap | swfbitmap_init() | Ming (Flash) |
| addaction | swfbutton_addaction() | Ming (Flash) |
| addshape | swfbutton_addshape() | Ming (Flash) |
| swfbutton | swfbutton_init() | Ming (Flash) |
| swfbutton_keypress | swfbutton_keypress() | Ming (Flash) |
| setaction | swfbutton_setaction() | Ming (Flash) |
| setdown | swfbutton_setdown() | Ming (Flash) |
| sethit | swfbutton_sethit() | Ming (Flash) |
| setover | swfbutton_setover() | Ming (Flash) |
| setup | swfbutton_setup() | Ming (Flash) |
| addcolor | swfdisplayitem_addcolor() | Ming (Flash) |
| move | swfdisplayitem_move() | Ming (Flash) |
| moveto | swfdisplayitem_moveto() | Ming (Flash) |
| multcolor | swfdisplayitem_multcolor() | Ming (Flash) |
| rotate | swfdisplayitem_rotate() | Ming (Flash) |
| rotateto | swfdisplayitem_rotateto() | Ming (Flash) |
| scale | swfdisplayitem_scale() | Ming (Flash) |
| scaleto | swfdisplayitem_scaleto() | Ming (Flash) |
| setdepth | swfdisplayitem_setdepth() | Ming (Flash) |
| setmatrix | swfdisplayitem_setmatrix() | Ming (Flash) |
| setname | swfdisplayitem_setname() | Ming (Flash) |
| setratio | swfdisplayitem_setratio() | Ming (Flash) |
| skewx | swfdisplayitem_skewx() | Ming (Flash) |
| skewxto | swfdisplayitem_skewxto() | Ming (Flash) |
| skewy | swfdisplayitem_skewy() | Ming (Flash) |
| skewyto | swfdisplayitem_skewyto() | Ming (Flash) |
| swffill | swffill_init() | Ming (Flash) |
| moveto | swffill_moveto() | Ming (Flash) |
| rotateto | swffill_rotateto() | Ming (Flash) |
| scaleto | swffill_scaleto() | Ming (Flash) |
| skewxto | swffill_skewxto() | Ming (Flash) |
| skewyto | swffill_skewyto() | Ming (Flash) |
| getascent | swffont_getascent() | Ming (Flash) |
| getdescent | swffont_getdescent() | Ming (Flash) |
| getleading | swffont_getleading() | Ming (Flash) |
| getwidth | swffont_getwidth() | Ming (Flash) |
| swffont | swffont_init() | Ming (Flash) |
| addentry | swfgradient_addentry() | Ming (Flash) |
| swfgradient | swfgradient_init() | Ming (Flash) |
| getshape1 | swfmorph_getshape1() | Ming (Flash) |
| getshape2 | swfmorph_getshape2() | Ming (Flash) |
| swfmorph | swfmorph_init() | Ming (Flash) |
| add | swfmovie_add() | Ming (Flash) |
| swfmovie | swfmovie_init() | Ming (Flash) |
| labelframe | swfmovie_labelframe() | Ming (Flash) |
| nextframe | swfmovie_nextframe() | Ming (Flash) |
| output | swfmovie_output() | Ming (Flash) |
| remove | swfmovie_remove() | Ming (Flash) |
| save | swfmovie_save() | Ming (Flash) |
| savetofile | swfmovie_savetofile() | Ming (Flash) |
| setbackground | swfmovie_setbackground() | Ming (Flash) |
| setdimension | swfmovie_setdimension() | Ming (Flash) |
| setframes | swfmovie_setframes() | Ming (Flash) |
| setrate | swfmovie_setrate() | Ming (Flash) |
| streammp3 | swfmovie_streammp3() | Ming (Flash) |
| addfill | swfshape_addfill() | Ming (Flash) |
| drawarc | swfshape_drawarc() | Ming (Flash) |
| drawcircle | swfshape_drawcircle() | Ming (Flash) |
| drawcubic | swfshape_drawcubic() | Ming (Flash) |
| drawcubicto | swfshape_drawcubicto() | Ming (Flash) |
| drawcurve | swfshape_drawcurve() | Ming (Flash) |
| drawcurveto | swfshape_drawcurveto() | Ming (Flash) |
| drawglyph | swfshape_drawglyph() | Ming (Flash) |
| drawline | swfshape_drawline() | Ming (Flash) |
| drawlineto | swfshape_drawlineto() | Ming (Flash) |
| swfshape | swfshape_init() | Ming (Flash) |
| movepen | swfshape_movepen() | Ming (Flash) |
| movepento | swfshape_movepento() | Ming (Flash) |
| setleftfill | swfshape_setleftfill() | Ming (Flash) |
| setline | swfshape_setline() | Ming (Flash) |
| setrightfill | swfshape_setrightfill() | Ming (Flash) |
| add | swfsprite_add() | Ming (Flash) |
| swfsprite | swfsprite_init() | Ming (Flash) |
| labelframe | swfsprite_labelframe() | Ming (Flash) |
| nextframe | swfsprite_nextframe() | Ming (Flash) |
| remove | swfsprite_remove() | Ming (Flash) |
| setframes | swfsprite_setframes() | Ming (Flash) |
| addstring | swftext_addstring() | Ming (Flash) |
| getascent | swftext_getascent() | Ming (Flash) |
| getdescent | swftext_getdescent() | Ming (Flash) |
| getleading | swftext_getleading() | Ming (Flash) |
| getwidth | swftext_getwidth() | Ming (Flash) |
| swftext | swftext_init() | Ming (Flash) |
| moveto | swftext_moveto() | Ming (Flash) |
| setcolor | swftext_setcolor() | Ming (Flash) |
| setfont | swftext_setfont() | Ming (Flash) |
| setheight | swftext_setheight() | Ming (Flash) |
| setspacing | swftext_setspacing() | Ming (Flash) |
| addstring | swftextfield_addstring() | Ming (Flash) |
| align | swftextfield_align() | Ming (Flash) |
| swftextfield | swftextfield_init() | Ming (Flash) |
| setbounds | swftextfield_setbounds() | Ming (Flash) |
| setcolor | swftextfield_setcolor() | Ming (Flash) |
| setfont | swftextfield_setfont() | Ming (Flash) |
| setheight | swftextfield_setheight() | Ming (Flash) |
| setindentation | swftextfield_setindentation() | Ming (Flash) |
| setleftmargin | swftextfield_setleftmargin() | Ming (Flash) |
| setlinespacing | swftextfield_setlinespacing() | Ming (Flash) |
| setmargins | swftextfield_setmargins() | Ming (Flash) |
| setname | swftextfield_setname() | Ming (Flash) |
| setrightmargin | swftextfield_setrightmargin() | Ming (Flash) |
| msql_affected_rows | msql_affected_rows() | mSQL |
| msql_createdb | msql_create_db() | mSQL |
| msql | msql_db_query() | mSQL |
| msql_dropdb | msql_drop_db() | mSQL |
| msql_fieldflags | msql_field_flags() | mSQL |
| msql_fieldlen | msql_field_len() | mSQL |
| msql_fieldname | msql_field_name() | mSQL |
| msql_fieldtable | msql_field_table() | mSQL |
| msql_fieldtype | msql_field_type() | mSQL |
| msql_freeresult | msql_free_result() | mSQL |
| msql_listdbs | msql_list_dbs() | mSQL |
| msql_listfields | msql_list_fields() | mSQL |
| msql_listtables | msql_list_tables() | mSQL |
| msql_numfields | msql_num_fields() | mSQL |
| msql_numrows | msql_num_rows() | mSQL |
| msql_dbname | msql_result() | mSQL |
| msql_tablename | msql_result() | mSQL |
| msql_selectdb | msql_select_db() | mSQL |
| msql_regcase | sql_regcase() | mSQL |
| i18n_convert | mb_convert_encoding() | Chaînes de caractères multi-octets |
| i18n_ja_jp_hantozen | mb_convert_kana() | Chaînes de caractères multi-octets |
| i18n_mime_header_decode | mb_decode_mimeheader() | Chaînes de caractères multi-octets |
| i18n_discover_encoding | mb_detect_encoding() | Chaînes de caractères multi-octets |
| i18n_mime_header_encode | mb_encode_mimeheader() | Chaînes de caractères multi-octets |
| i18n_http_input | mb_http_input() | Chaînes de caractères multi-octets |
| i18n_http_output | mb_http_output() | Chaînes de caractères multi-octets |
| i18n_internal_encoding | mb_internal_encoding() | Chaînes de caractères multi-octets |
| mbstrcut | mb_strcut() | Chaînes de caractères multi-octets |
| mbstrlen | mb_strlen() | Chaînes de caractères multi-octets |
| mbstrpos | mb_strpos() | Chaînes de caractères multi-octets |
| mbstrrpos | mb_strrpos() | Chaînes de caractères multi-octets |
| mbsubstr | mb_substr() | Chaînes de caractères multi-octets |
| mysql_createdb | mysql_create_db() | MySQL |
| mysql | mysql_db_query() | MySQL |
| mysql_dropdb | mysql_drop_db() | MySQL |
| mysql_fieldflags | mysql_field_flags() | MySQL |
| mysql_fieldlen | mysql_field_len() | MySQL |
| mysql_fieldname | mysql_field_name() | MySQL |
| mysql_fieldtable | mysql_field_table() | MySQL |
| mysql_fieldtype | mysql_field_type() | MySQL |
| mysql_freeresult | mysql_free_result() | MySQL |
| mysql_listdbs | mysql_list_dbs() | MySQL |
| mysql_listfields | mysql_list_fields() | MySQL |
| mysql_listtables | mysql_list_tables() | MySQL |
| mysql_numfields | mysql_num_fields() | MySQL |
| mysql_numrows | mysql_num_rows() | MySQL |
| mysql_db_name | mysql_result() | MySQL |
| mysql_dbname | mysql_result() | MySQL |
| mysql_tablename | mysql_result() | MySQL |
| mysql_selectdb | mysql_select_db() | MySQL |
| oci8close | ocicloselob() | oci8 |
| oci8append | ocicollappend() | oci8 |
| oci8assign | ocicollassign() | oci8 |
| oci8assignelem | ocicollassignelem() | oci8 |
| oci8getelem | ocicollgetelem() | oci8 |
| oci8max | ocicollmax() | oci8 |
| oci8size | ocicollsize() | oci8 |
| oci8trim | ocicolltrim() | oci8 |
| oci8free | ocifreecoll() | oci8 |
| oci8free | ocifreedesc() | oci8 |
| oci8ocifreecursor | ocifreestatement() | oci8 |
| oci8load | ociloadlob() | oci8 |
| oci8save | ocisavelob() | oci8 |
| oci8savefile | ocisavelobfile() | oci8 |
| oci8writetofile | ociwritelobtofile() | oci8 |
| oci8writetemporary | ociwritetemporarylob() | oci8 |
| odbc_do | odbc_exec() | oci8 |
| odbc_field_precision | odbc_field_len() | oci8 |
| pdf_add_outline | pdf_add_bookmark() | |
| pg_clientencoding | pg_client_encoding() | PostgreSQL |
| pg_setclientencoding | pg_set_client_encoding() | PostgreSQL |
| recode | recode_string() | GNU Recode |
| orbit_caught_exception | satellite_caught_exception() | Satellite |
| orbit_exception_id | satellite_exception_id() | Satellite |
| orbit_exception_value | satellite_exception_value() | Satellite |
| orbit_get_repository_id | satellite_get_repository_id() | Satellite |
| orbit_load_idl | satellite_load_idl() | Satellite |
| snmpwalkoid | snmprealwalk() | SNMP |
| mssql_affected_rows | sybase_affected_rows() | Sybase |
| mssql_close | sybase_close() | Sybase |
| mssql_connect | sybase_connect() | Sybase |
| mssql_data_seek | sybase_data_seek() | Sybase |
| mssql_fetch_array | sybase_fetch_array() | Sybase |
| mssql_fetch_field | sybase_fetch_field() | Sybase |
| mssql_fetch_object | sybase_fetch_object() | Sybase |
| mssql_fetch_row | sybase_fetch_row() | Sybase |
| mssql_field_seek | sybase_field_seek() | Sybase |
| mssql_free_result | sybase_free_result() | Sybase |
| mssql_get_last_message | sybase_get_last_message() | Sybase |
| mssql_min_error_severity | sybase_min_error_severity() | Sybase |
| mssql_min_message_severity | sybase_min_message_severity() | Sybase |
| mssql_num_fields | sybase_num_fields() | Sybase |
| mssql_num_rows | sybase_num_rows() | Sybase |
| mssql_pconnect | sybase_pconnect() | Sybase |
| mssql_query | sybase_query() | Sybase |
| mssql_result | sybase_result() | Sybase |
| mssql_select_db | sybase_select_db() | Sybase |
| mssql_affected_rows | sybase_affected_rows() | Sybase |
| mssql_close | sybase_close() | Sybase |
| mssql_connect | sybase_connect() | Sybase |
| mssql_data_seek | sybase_data_seek() | Sybase |
| mssql_fetch_array | sybase_fetch_array() | Sybase |
| mssql_fetch_field | sybase_fetch_field() | Sybase |
| mssql_fetch_object | sybase_fetch_object() | Sybase |
| mssql_fetch_row | sybase_fetch_row() | Sybase |
| mssql_field_seek | sybase_field_seek() | Sybase |
| mssql_free_result | sybase_free_result() | Sybase |
| mssql_get_last_message | sybase_get_last_message() | Sybase |
| mssql_min_client_severity | sybase_min_client_severity() | Sybase |
| mssql_min_server_severity | sybase_min_server_severity() | Sybase |
| mssql_num_fields | sybase_num_fields() | Sybase |
| mssql_num_rows | sybase_num_rows() | Sybase |
| mssql_pconnect | sybase_pconnect() | Sybase |
| mssql_query | sybase_query() | Sybase |
| mssql_result | sybase_result() | Sybase |
| mssql_select_db | sybase_select_db() | Sybase |
| gzputs | gzwrite() | Zlib |
Annexe G. Mot réservés en PHP
Cette annexes est une liste d'identifiant prédéfinis en PHP. Aucun des identifiants utilisés ici ne doit être repris comme nom de variable ou de fonction dans vos scripts. Ces identifiants incluent des mots clés, des constantes, des classes, et es variables prédéfinies. Ces listes ne sont pas complètes ou exhaustives.
Liste de mots-clé
Ces mots ont un sens spécial en PHP. Certains représentent des objets qui ressemblent à des fonctions, d'autres à des contantes, et ainsi de suite, mais ils n'en sont pas vraiment : ce sont des structures de langage. Vous ne pourrez pas les utiliser comme constantes, nom de classe ou fonctions. Vous pouvez les utiliser comme noms de variables, mais cela risque de vous mener des confusions.
Variables prédéfinies
Variables de serveur : $_SERVER
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_SERVER_VARS.
$_SERVER is an array containing information such as headers, paths, and script locations. The entries in this array are created by the webserver. There is no guarantee that every webserver will provide any of these; servers may omit some, or provide others not listed here. That said, a large number of these variables are accounted for in the CGI 1.1 specification, so you should be able to expect those.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_SERVER; pour y accéder, comme vous le faisiez avec $HTTP_SERVER_VARS.
$HTTP_SERVER_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_SERVER et $HTTP_SERVER_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
You may or may not find any of the following elements in $_SERVER. Note that few, if any, of these will be available (or indeed have any meaning) if running PHP on the command line.
- 'PHP_SELF'
Le nom du fichier du script en cour d'éxécution, par rapport au document root. Par exemple, $_SERVER['PHP_SELF'] dans le script situé à l'adresse http://www.monsite.com/test.php/foo.bar sera /test.php/foo.bar.
Si PHP fonctionne en ligne de commande, cette variable n'est pas disponible.
- 'argv'
Tableau des arguments passées 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 : i.e. 'CGI/1.1'.
- 'SERVER_NAME'
Le nom du serveur hôte qui éxécute le script suivant. Si le script est exécuté sur un hôte virtuel, ce sera la valeur définie pour cet hôte virtuel.
- '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 : i.e. 'HTTP/1.0';
- 'REQUEST_METHOD'
Méthode de requête utilisée pour accéder à la page; i.e. 'GET', 'HEAD', 'POST', 'PUT'.
- '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.
- 'HTTP_ACCEPT'
Contenu de l'en-tête Accept: de la requête courante, s'il y en a une.
- 'HTTP_ACCEPT_CHARSET'
Contenu de l'en-tête Accept-Charset: de la requête courante, s'elle existe. Par exemple : 'iso-8859-1,*,utf-8'.
- 'HTTP_ACCEPT_ENCODING'
Contenu de l'en-tête Accept-Encoding: de la requête courante, si elle existe. Par exemple : 'gzip'.
- 'HTTP_ACCEPT_LANGUAGE'
Contenu de l'en-tête Accept-Language: de la requête courante, si elle existe. Par exemple : 'fr'.
- 'HTTP_CONNECTION'
Contenu de l'en-tête Connection: de la requête courante, si elle existe. Par exemple : 'Keep-Alive'.
- 'HTTP_HOST'
Contenu de l'en-tête Host: de la requête courante, si elle existe.
- 'HTTP_REFERER'
L'adresse de la page (si elle existe) qui a conduit le client à la page courante. Cette valeur est affectée par le client, et tous les clients ne le font pas. Certains navigateur permettent même de modifier la valeur de HTTP_REFERER, sous forme de fonctionnalité. En bref, ce n'est pas une valeur de confiance.
- 'HTTP_USER_AGENT'
Contenu de l'en-tête User_Agent: de la requête courante, si elle existe. C'est une chaîne qui décrit le client HTML utilisé pour voir la page courante. Par exemple : Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Entre autres choses, vous pouvez utiliser cette valeur avec get_browser() pour optimiser votre page en fonction des capacités du client.
- 'REMOTE_ADDR'
L'adresse IP du client qui demande la page courante.
- 'REMOTE_PORT'
Le port utilisé par la machine cliente pour communiquer avec le serveur web.
- 'SCRIPT_FILENAME'
Le chemin absolu jusqu'au script courant.
- 'SERVER_ADMIN'
La valeur donnée à la directive SERVER_ADMIN (pour Apache), dans le fichier de configuration. Si le script est exécuté par un hôte virtuel, ce sera la valeur définie par l'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é.
- '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 fichier (pas le document root-) jusqu'au script courant, une fois que le serveur a fait une chemin traduction virtuel->réel.
- 'SCRIPT_NAME'
Contient le nom du script courant. Cela sert lorsque les pages doivent s'appeler elles-mêmes.
- 'REQUEST_URI'
L'URI qui a été fourni pour accéder à cette page. Par exemple : '/index.html'.
Variables d'environnement : $_ENV
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_ENV_VARS.
Cette variable est importée dans l'espace de nom global de PHP, depuis l'environnement dans lequel l'exécutable PHP fonctionne. De nombreuses valeur 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. Reportez vous à la documentation de votre shell pour connaître une liste de variables prédéfinies.
Les autres variables d'environnement incluent les variables CGI, placées ici, indépendemment du fait que PHP fonctionne en tant que CGI ou bien que module du serveur.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_ENV; pour y accéder, comme vous le faisiez avec $HTTP_ENV_VARS.
$HTTP_ENV_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_ENV et $HTTP_ENV_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
HTTP Cookies: $_COOKIE
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_COOKIE_VARS.
Un tableau associatif des valeurs passées au script courant via les cookies HTTP. Elle est automatiquement global dans tous les contextes d'exécution.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_COOKIE; pour y accéder, comme vous le faisiez avec $HTTP_COOKIE_VARS.
$HTTP_COOKIE_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_COOKIE et $HTTP_COOKIE_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
HTTP GET variables: $_GET
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_GET_VARS.
Un tableau associatif des valeurs passées au script courant via le protocole HTTP et la méthode GET. Elle est automatiquement globale dans tous les contextes d'exécution.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_GET; pour y accéder, comme vous le faisiez avec $HTTP_GET_VARS.
$HTTP_GET_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_GET et $HTTP_GET_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
HTTP POST variables: $_POST
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_POST_VARS.
Un tableau associatif des valeurs passées au script courant via le protocole HTTP et la méthode POST. Elle est automatiquement globale dans tous les contextes d'exécution.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_POST; pour y accéder, comme vous le faisiez avec $HTTP_POST_VARS.
$HTTP_POST_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_POST et $HTTP_POST_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
Variable de téléchargement de fichier via HTTP : $_FILES
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_POST_FILES.
Un tableau associatif des valeurs téléchargées au script courant via le protocole HTTP et la méthode POST. Elle est automatiquement globale dans tous les contextes d'exécution.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_FILES; pour y accéder, comme vous le faisiez avec $HTTP_POST_FILES.
$HTTP_POST_FILES contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_FILES et $HTTP_POST_FILES. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
Variables de requête : $_REQUEST
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle n'avait pas d'équivalent.
Un tableau associatif constitué du contenu des variables $_GET, $_POST, $_COOKIE, et $_FILES.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_REQUEST; pour y accéder.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_REQUEST. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
Session variables: $_SESSION
Note : Introduite en 4.1.0. Dans les versions plus anciennes, elle s'appelait $HTTP_SESSION_VARS.
Un tableau associatif des valeurs stockées dans les sessions, et accessible au script courant. Elle est automatiquement globale dans tous les contextes d'exécution. Voyez l'extension Sessions pour plus de détails sur comment est utilisée cette variable.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $_SESSION; pour y accéder, comme vous le faisiez avec $HTTP_SESSION_VARS.
$HTTP_SESSION_VARS contient les mêmes informations, mais n'est pas autoglobale.
Si la directive register_globals est active, alors ces variables seront aussi rendues directement accessible dans le contexte d'exécution global. C'est à dire séparément des tableaux $_SESSION et $HTTP_SESSION_VARS. Pour plus d'informations sur la sécurité de cette configuration, voyez le chapitre Utiliser la directive Register Globals. Ces variables globales individuelles ne sont pas des globales.
Variables globales: $GLOBALS
Note : $GLOBALS est disponible depuis PHP 3.0.0.
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.
Cette variable est une 'superglobal', ou globale automatique. Cela signifie qu'elle est simplement disponible dans tous les contextes d'exécution (fonctions ou méthodes). Vous n'avez pas besoin de faire global $GLOBALS; pour y accéder.
Le dernier message d'erreur : $php_errormsg
$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).
Classes prédéfinies
Classes standards
Ces classes sont définies dans le jeu de classe standard de PHP, inclus dans toute version de PHP.
- Directory
La classe qui permet d'instantier dir().
- stdClass
Classes définies par Ming
Ces classes sont définies dans l'extension Ming et ne seront pas disponibles si PHP a été compilé pour être exécuté dynamiquement, ou bien si elles n'ont pas été compilées dans PHP.
- swfshape
- swffill
- swfgradient
- swfbitmap
- swftext
- swftextfield
- swffont
- swfdisplayitem
- swfmovie
- swfbutton
- swfaction
- swfmorph
- swfsprite
Classes définies par Oracle 8
Ces classes sont définies dans l'extension Oracle 8 et ne seront pas disponibles si PHP a été compilé pour être exécuté dynamiquement, ou bien si elles n'ont pas été compilées dans PHP.
- OCI-Lob
- OCI-Collection
Classes définies par qtdom
Ces classes sont définies dans l'extension qtdom et ne seront pas disponibles si PHP a été compilé pour être exécuté dynamiquement, ou bien si elles n'ont pas été compilées dans PHP.
- QDomDocument
- QDomNode
Annexe H. Types des ressources PHP
Voici la liste des fonctions qui créent, utilisent ou détruisent les ressources PHP. Vous pouvez déterminer si une variable contient une ressource avec la fonction is_resource(), et le type d'une ressource que vous utilisez avec la fonction get_resource_type().
Tableau H-1. Types de ressource
| Ressource | Construite par | Utilisé par | Détruite par | Définition |
|---|---|---|---|---|
| aspell | aspell_new() | aspell_check(), aspell_check_raw(), aspell_suggest() | None | Dictionnaire Aspell |
| bzip2 | bzopen() | bzerrno(), bzerror(), bzerrstr(), bzflush(), bzread(), bzwrite() | bzclose() | Fichier bzip2 |
| COM | com_load() | com_invoke(), com_propget(), com_get(), com_propput(), com_set(), com_propput() | None | Référence sur un object COM |
| VARIANT | ||||
| cpdf | cpdf_open() | cpdf_page_init(), cpdf_finalize_page(), cpdf_finalize(), cpdf_output_buffer(), cpdf_save_to_file(), cpdf_set_current_page(), cpdf_begin_text(), cpdf_end_text(), cpdf_show(), cpdf_show_xy(), cpdf_text(), cpdf_set_font(), cpdf_set_leading(), cpdf_set_text_rendering(), cpdf_set_horiz_scaling(), cpdf_set_text_rise(), cpdf_set_text_matrix(), cpdf_set_text_pos(), cpdf_set_text_pos(), cpdf_set_word_spacing(), cpdf_continue_text(), cpdf_stringwidth(), cpdf_save(), cpdf_translate(), cpdf_restore(), cpdf_scale(), cpdf_rotate(), cpdf_setflat(), cpdf_setlinejoin(), cpdf_setlinecap(), cpdf_setmiterlimit(), cpdf_setlinewidth(), cpdf_setdash(), cpdf_moveto(), cpdf_rmoveto(), cpdf_curveto(), cpdf_lineto(), cpdf_rlineto(), cpdf_circle(), cpdf_arc(), cpdf_rect(), cpdf_closepath(), cpdf_stroke(), cpdf_closepath_fill_stroke(), cpdf_fill_stroke(), cpdf_clip(), cpdf_fill(), cpdf_setgray_fill(), cpdf_setgray_stroke(), cpdf_setgray(), cpdf_setrgbcolor_fill(), cpdf_setrgbcolor_stroke(), cpdf_setrgbcolor(), cpdf_add_outline(), cpdf_set_page_animation(), cpdf_import_jpeg(), cpdf_place_inline_image(), cpdf_add_annotation() | cpdf_close() | Document PDF avec la librairie CPDF |
| cpdf outline | ||||
| curl | curl_init() | curl_init(), curl_exec() | curl_close() | Session Curl |
| dbm | dbmopen() | dbmexists(), dbmfetch(), dbminsert(), dbmreplace(), dbmdelete(), dbmfirstkey(), dbmnextkey() | dbmclose() | Lien vers une base de données DBM |
| dba | dba_popen() | dba_delete(), dba_exists(), dba_fetch(), dba_firstkey(), dba_insert(), dba_nextkey(), dba_optimize(), dba_replace(), dba_sync() | dba_close() | Lien vers une base de données DBA |
| dba persistent | dba_open() | dba_delete(), dba_exists(), dba_fetch(), dba_firstkey(), dba_insert(), dba_nextkey(), dba_optimize(), dba_replace(), dba_sync() | None | Lien persistant vers une base de données DBA |
| dbase | dbase_open() | dbase_pack(), dbase_add_record(), dbase_replace_record(), dbase_delete_record(), dbase_get_record(), dbase_get_record_with_names(), dbase_numfields(), dbase_numrecords() | dbase_close() | Lien vers une base de données dbase |
| dbx_link_object | dbx_connect() | dbx_query() | dbx_close() | Connexion dbx |
| dbx_result_object | dbx_query() | () | None | Résultat dbx |
| domxml attribute | ||||
| domxml document | ||||
| domxml node | ||||
| xpath context | ||||
| xpath object | ||||
| fbsql database | fbsql_select_db() | () | None | Base de données fbsql |
| fbsql link | fbsql_change_user(), fbsql_connect() | fbsql_autocommit(), fbsql_change_user(), fbsql_create_db(), fbsql_data_seek(), fbsql_db_query(), fbsql_drop_db(), (), fbsql_select_db(), fbsql_errno(), fbsql_error(), fbsql_insert_id(), fbsql_list_dbs() | fbsql_close() | Lien vers une base de données fbsql |
| fbsql plink | fbsql_change_user(), fbsql_pconnect() | fbsql_autocommit(), fbsql_change_user(), fbsql_create_db(), fbsql_data_seek(), fbsql_db_query(), fbsql_drop_db(), (), fbsql_select_db(), fbsql_errno(), fbsql_error(), fbsql_insert_id(), fbsql_list_dbs() | None | Lien persistant vers une base de données fbsql |
| fbsql result | fbsql_db_query(), fbsql_list_dbs(), fbsql_query(), fbsql_list_fields(), fbsql_list_tables(), fbsql_tablename() | fbsql_affected_rows(), fbsql_fetch_array(), fbsql_fetch_assoc(), fbsql_fetch_field(), fbsql_fetch_lengths(), fbsql_fetch_object(), fbsql_fetch_row(), fbsql_field_flags(), fbsql_field_name(), fbsql_field_len(), fbsql_field_seek(), fbsql_field_table(), fbsql_field_type(), fbsql_next_result(), fbsql_num_fields(), fbsql_num_rows(), fbsql_result(), fbsql_num_rows() | fbsql_free_result() | Résultat fbsql |
| fdf | fdf_open() | fdf_create(), fdf_save(), fdf_get_value(), fdf_set_value(), fdf_next_field_name(), fdf_set_ap(), fdf_set_status(), fdf_get_status(), fdf_set_file(), fdf_get_file(), fdf_set_flags(), fdf_set_opt(), fdf_set_submit_form_action(), fdf_set_javascript_action() | fdf_close() | Fichier FDF |
| ftp | ftp_connect() | ftp_login(), ftp_pwd(), ftp_cdup(), ftp_chdir(), ftp_mkdir(), ftp_rmdir(), ftp_nlist(), ftp_rawlist(), ftp_systype(), ftp_pasv(), ftp_get(), ftp_fget(), ftp_put(), ftp_fput(), ftp_size(), ftp_mdtm(), ftp_rename(), ftp_delete(), ftp_site() | ftp_quit() | Connexion FTP |
| gd | imagecreate(), imagecreatefromgif(), imagecreatefromjpeg(), imagecreatefrompng(), imagecreatefromwbmp(), imagecreatefromstring(), imagecreatetruecolor() | imagearc(), imagechar(), imagecharup(), imagecolorallocate(), imagecolorat(), imagecolorclosest(), imagecolorexact(), imagecolorresolve(), imagegammacorrect(), imagegammacorrect(), imagecolorset(), imagecolorsforindex(), imagecolorstotal(), imagecolortransparent(), imagecopy(), imagecopyresized(), imagedashedline(), imagefill(), imagefilledpolygon(), imagefilledrectangle(), imagefilltoborder(), imagegif(), imagepng(), imagejpeg(), imagewbmp(), imageinterlace(), imageline(), imagepolygon(), imagepstext(), imagerectangle(), imagesetpixel(), imagestring(), imagestringup(), imagesx(), imagesy(), imagettftext(), imagefilledarc(), imageellipse(), imagefilledellipse(), imagecolorclosestalpha(), imagecolorexactalpha(), imagecolorresolvealpha(), imagecopymerge(), imagecopymergegray(), imagecopyresampled(), imagetruecolortopalette(), imagesetbrush(), imagesettile(), imagesetthickness() | imagedestroy() | Image GD |
| gd font | imageloadfont() | imagechar(), imagecharup(), imagefontheight() | None | Police pour GD |
| gd PS encoding | ||||
| gd PS font | imagepsloadfont() | imagepstext(), imagepsslantfont(), imagepsextendfont(), imagepsencodefont(), imagepsbbox() | imagepsfreefont() | Police PostScript pour GD |
| GMP integer | gmp_init() | gmp_intval(), gmp_strval(), gmp_add(), gmp_sub(), gmp_mul(), gmp_div_q(), gmp_div_r(), gmp_div_qr(), gmp_div(), gmp_mod(), gmp_divexact(), gmp_cmp(), gmp_neg(), gmp_abs(), gmp_sign(), gmp_fact(), gmp_sqrt(), gmp_sqrtrm(), gmp_perfect_square(), gmp_pow(), gmp_powm(), gmp_prob_prime(), gmp_gcd(), gmp_gcdext(), gmp_invert(), gmp_legendre(), gmp_jacobi(), gmp_random(), gmp_and(), gmp_or(), gmp_xor(), gmp_setbit(), gmp_clrbit(), gmp_scan0(), gmp_scan1(), gmp_popcount(), gmp_hamdist() | None | Nombre GMP |
| hyperwave document | hw_cp(), hw_docbyanchor(), hw_getremote(), hw_getremotechildren() | hw_children(), hw_childrenobj(), hw_getparents(), hw_getparentsobj(), hw_getchildcoll(), hw_getchildcollobj(), hw_getremote(), hw_getsrcbydestobj(), hw_getandlock(), hw_gettext(), hw_getobjectbyquerycoll(), hw_getobjectbyquerycollobj(), hw_getchilddoccoll(), hw_getchilddoccollobj(), hw_getanchors(), hw_getanchorsobj(), hw_inscoll(), hw_pipedocument(), hw_unlock() | hw_deleteobject() | Objet Hyperwave |
| hyperwave link | hw_connect() | hw_children(), hw_childrenobj(), hw_cp(), hw_deleteobject(), hw_docbyanchor(), hw_docbyanchorobj(), hw_errormsg(), hw_edittext(), hw_error(), hw_getparents(), hw_getparentsobj(), hw_getchildcoll(), hw_getchildcollobj(), hw_getremote(), hw_getremotechildren(), hw_getsrcbydestobj(), hw_getobject(), hw_getandlock(), hw_gettext(), hw_getobjectbyquery(), hw_getobjectbyqueryobj(), hw_getobjectbyquerycoll(), hw_getobjectbyquerycollobj(), hw_getchilddoccoll(), hw_getchilddoccollobj(), hw_getanchors(), hw_getanchorsobj(), hw_mv(), hw_incollections(), hw_info(), hw_inscoll(), hw_insdoc(), hw_insertdocument(), hw_insertobject(), hw_mapid(), hw_modifyobject(), hw_pipedocument(), hw_unlock(), hw_who(), hw_getusername() | hw_close(), hw_free_document() | Lien vers un serveur Hyperwave |
| hyperwave link persistent | hw_pconnect() | hw_children(), hw_childrenobj(), hw_cp(), hw_deleteobject(), hw_docbyanchor(), hw_docbyanchorobj(), hw_errormsg(), hw_edittext(), hw_error(), hw_getparents(), hw_getparentsobj(), hw_getchildcoll(), hw_getchildcollobj(), hw_getremote(), hw_getremotechildren(), hw_getsrcbydestobj(), hw_getobject(), hw_getandlock(), hw_gettext(), hw_getobjectbyquery(), hw_getobjectbyqueryobj(), hw_getobjectbyquerycoll(), hw_getobjectbyquerycollobj(), hw_getchilddoccoll(), hw_getchilddoccollobj(), hw_getanchors(), hw_getanchorsobj(), hw_mv(), hw_incollections(), hw_info(), hw_inscoll(), hw_insdoc(), hw_insertdocument(), hw_insertobject(), hw_mapid(), hw_modifyobject(), hw_pipedocument(), hw_unlock(), hw_who(), hw_getusername() | None | Lien persistant vers un serveur Hyperwave |
| icap | icap_open() | icap_fetch_event(), icap_list_events(), icap_store_event(), icap_snooze(), icap_list_alarms(), icap_delete_event() | icap_close() | Lien vers un serveur icap |
| imap | imap_open() | imap_append(), imap_body(), imap_check(), imap_createmailbox(), imap_delete(), imap_deletemailbox(), imap_expunge(), imap_fetchbody(), imap_fetchstructure(), imap_headerinfo(), imap_header(), imap_headers(), imap_listmailbox(), imap_getmailboxes(), imap_get_quota(), imap_status(), imap_listsubscribed(), imap_set_quota(), imap_set_quota(), imap_getsubscribed(), imap_mail_copy(), imap_mail_move(), imap_num_msg(), imap_num_recent(), imap_ping(), imap_renamemailbox(), imap_reopen(), imap_subscribe(), imap_undelete(), imap_unsubscribe(), imap_scanmailbox(), imap_mailboxmsginfo(), imap_fetchheader(), imap_uid(), imap_msgno(), imap_search(), imap_fetch_overview() | imap_close() | Lien vers un serveur mail (IMAP, POP3) |
| imap chain persistent | ||||
| imap persistent | ||||
| ingres | ingres_connect() | ingres_query(), ingres_num_rows(), ingres_num_fields(), ingres_field_name(), ingres_field_type(), ingres_field_nullable(), ingres_field_length(), ingres_field_precision(), ingres_field_scale(), ingres_fetch_array(), ingres_fetch_row(), ingres_fetch_object(), ingres_rollback(), ingres_commit(), ingres_autocommit() | ingres_close() | Lien vers une base de données ingresII |
| ingres persistent | ingres_pconnect() | ingres_query(), ingres_num_rows(), ingres_num_fields(), ingres_field_name(), ingres_field_type(), ingres_field_nullable(), ingres_field_length(), ingres_field_precision(), ingres_field_scale(), ingres_fetch_array(), ingres_fetch_row(), ingres_fetch_object(), ingres_rollback(), ingres_commit(), ingres_autocommit() | None | Lien persistant vers une base de données ingresII |
| interbase blob | ||||
| interbase link | ibase_connect() | ibase_query(), ibase_prepare(), ibase_trans() | ibase_close() | Lien vers une base de données Interbase |
| interbase link persistent | ibase_pconnect() | ibase_query(), ibase_prepare(), ibase_trans() | None | Lien persistant vers une base de données Interbase |
| interbase query | ibase_prepare() | ibase_execute() | ibase_free_query() | Requête Interbase |
| interbase result | ibase_query() | ibase_fetch_row(), ibase_fetch_object(), ibase_field_info(), ibase_num_fields() | ibase_free_result() | Résultat Interbase |
| interbase transaction | ibase_trans() | ibase_commit() | ibase_rollback() | Transaction Interbase |
| java | ||||
| ldap link | ldap_connect(), ldap_search() | ldap_count_entries(), ldap_first_attribute(), ldap_first_entry(), ldap_get_attributes(), ldap_get_dn(), ldap_get_entries(), ldap_get_values(), ldap_get_values_len(), ldap_next_attribute(), ldap_next_entry() | ldap_close() | Lien vers un serveur LDAP |
| ldap result | ldap_read() | ldap_add(), ldap_compare(), ldap_bind(), ldap_count_entries(), ldap_delete(), ldap_errno(), ldap_error(), ldap_first_attribute(), ldap_first_entry(), ldap_get_attributes(), ldap_get_dn(), ldap_get_entries(), ldap_get_values(), ldap_get_values_len(), ldap_get_option(), ldap_list(), ldap_modify(), ldap_mod_add(), ldap_mod_replace(), ldap_next_attribute(), ldap_next_entry(), ldap_mod_del(), ldap_set_option(), ldap_unbind() | ldap_free_result() | Résultat de recherche LDAP |
| ldap result entry | ||||
| mcal | mcal_open(), mcal_popen() | mcal_create_calendar(), mcal_rename_calendar(), mcal_rename_calendar(), mcal_delete_calendar(), mcal_fetch_event(), mcal_list_events(), mcal_append_event(), mcal_store_event(), mcal_delete_event(), mcal_list_alarms(), mcal_event_init(), mcal_event_set_category(), mcal_event_set_title(), mcal_event_set_description(), mcal_event_set_start(), mcal_event_set_end(), mcal_event_set_alarm(), mcal_event_set_class(), mcal_next_recurrence(), mcal_event_set_recur_none(), mcal_event_set_recur_daily(), mcal_event_set_recur_weekly(), mcal_event_set_recur_monthly_mday(), mcal_event_set_recur_monthly_wday(), mcal_event_set_recur_yearly(), mcal_fetch_current_stream_event(), mcal_event_add_attribute(), mcal_expunge() | mcal_close() | Lien vers un serveur Mcal |
| SWFAction | ||||
| SWFBitmap | ||||
| SWFButton | ||||
| SWFDisplayItem | ||||
| SWFFill | ||||
| SWFFont | ||||
| SWFGradient | ||||
| SWFMorph | ||||
| SWFMovie | ||||
| SWFShape | ||||
| SWFSprite | ||||
| SWFText | ||||
| SWFTextField | ||||
| mnogosearch agent | ||||
| mnogosearch result | ||||
| msql link | msql_connect() | msql(), msql_create_db(), msql_createdb(), msql_drop_db(), msql_drop_db(), msql_select_db(), msql_select_db() | msql_close() | Lien vers une base de données mSQL |
| msql link persistent | msql_pconnect() | msql(), msql_create_db(), msql_createdb(), msql_drop_db(), msql_drop_db(), msql_select_db(), msql_select_db() | None | Lien persistant vers une base de données mSQL |
| msql query | msql_query() | msql(), msql_affected_rows(), msql_data_seek(), msql_dbname(), msql_fetch_array(), msql_fetch_field(), msql_fetch_object(), msql_fetch_row(), msql_fieldname(), msql_field_seek(), msql_fieldtable(), msql_fieldtype(), msql_fieldflags(), msql_fieldlen(), msql_num_fields(), msql_num_rows(), msql_numfields(), msql_numrows(), msql_result() | msql_free_result(), msql_free_result() | Résultat mSQL |
| mssql link | mssql_connect() | mssql_query(), mssql_select_db() | mssql_close() | Lien vers une base de données Microsft SQL Server |
| mssql link persistent | mssql_pconnect() | mssql_query(), mssql_select_db() | None | Lien persistant vers une base de données Microsft SQL Server |
| mssql result | mssql_query() | mssql_data_seek(), mssql_fetch_array(), mssql_fetch_field(), mssql_fetch_object(), mssql_fetch_row(), mssql_field_length(), mssql_field_name(), mssql_field_seek(), mssql_field_type(), mssql_num_fields(), mssql_num_rows(), mssql_result() | mssql_free_result() | Résultat Microsft SQL Server |
| mysql link | mysql_connect() | mysql_affected_rows(), mysql_change_user(), mysql_create_db(), mysql_data_seek(), mysql_db_name(), mysql_db_query(), mysql_drop_db(), mysql_errno(), mysql_error(), mysql_insert_id(), mysql_list_dbs(), mysql_list_fields(), mysql_list_tables(), mysql_query(), mysql_result(), mysql_select_db(), mysql_tablename(), mysql_get_host_info(), mysql_get_proto_info(), mysql_get_server_info() | mysql_close() | Lien vers une base de données MySQL |
| mysql link persistent | mysql_pconnect() | mysql_affected_rows(), mysql_change_user(), mysql_create_db(), mysql_data_seek(), mysql_db_name(), mysql_db_query(), mysql_drop_db(), mysql_errno(), mysql_error(), mysql_insert_id(), mysql_list_dbs(), mysql_list_fields(), mysql_list_tables(), mysql_query(), mysql_result(), mysql_select_db(), mysql_tablename(), mysql_get_host_info(), mysql_get_proto_info(), mysql_get_server_info() | None | Lien persistant vers une base de données MySQL |
| mysql result | mysql_db_query(), mysql_list_dbs(), mysql_list_fields(), mysql_list_tables(), mysql_query() | mysql_data_seek(), mysql_db_name(), mysql_fetch_array(), mysql_fetch_assoc(), mysql_fetch_field(), mysql_fetch_lengths(), mysql_fetch_object(), mysql_fetch_row(), mysql_fetch_row(), mysql_field_flags(), mysql_field_name(), mysql_field_len(), mysql_field_seek(), mysql_field_table(), mysql_field_type(), mysql_num_fields(), mysql_num_rows(), mysql_result(), mysql_tablename() | mysql_free_result() | Résultat MySQL |
| oci8 collection | ||||
| oci8 connection | ocilogon(), ociplogon(), ocinlogon() | ocicommit(), ociserverversion(), ocinewcursor(), ociparse(), ocierror() | ocilogoff() | Lien vers une base de données Oracle |
| oci8 descriptor | ||||
| oci8 server | ||||
| oci8 session | ||||
| oci8 statement | ocinewdescriptor() | ocirollback(), ocinewdescriptor(), ocirowcount(), ocidefinebyname(), ocibindbyname(), ociexecute(), ocinumcols(), ociresult(), ocifetch(), ocifetchinto(), ocifetchstatement(), ocicolumnisnull(), ocicolumnname(), ocicolumnsize(), ocicolumntype(), ocistatementtype(), ocierror() | ocifreestatement() | Curseur Oracle |
| odbc link | odbc_connect() | odbc_autocommit(), odbc_commit(), odbc_error(), odbc_errormsg(), odbc_exec(), odbc_tables(), odbc_tableprivileges(), odbc_do(), odbc_prepare(), odbc_columns(), odbc_columnprivileges(), odbc_procedurecolumns(), odbc_specialcolumns(), odbc_rollback(), odbc_setoption(), odbc_gettypeinfo(), odbc_primarykeys(), odbc_foreignkeys(), odbc_procedures(), odbc_statistics() | odbc_close() | Lien vers une base de données ODBC |
| odbc link persistent | odbc_connect() | odbc_autocommit(), odbc_commit(), odbc_error(), odbc_errormsg(), odbc_exec(), odbc_tables(), odbc_tableprivileges(), odbc_do(), odbc_prepare(), odbc_columns(), odbc_columnprivileges(), odbc_procedurecolumns(), odbc_specialcolumns(), odbc_rollback(), odbc_setoption(), odbc_gettypeinfo(), odbc_primarykeys(), odbc_foreignkeys(), odbc_procedures(), odbc_statistics() | None | Lien persistant vers une base de données ODBC |
| odbc result | odbc_prepare() | odbc_binmode(), odbc_cursor(), odbc_execute(), odbc_fetch_into(), odbc_fetch_row(), odbc_field_name(), odbc_field_num(), odbc_field_type(), odbc_field_len(), odbc_field_precision(), odbc_field_scale(), odbc_longreadlen(), odbc_num_fields(), odbc_num_rows(), odbc_result(), odbc_result_all(), odbc_setoption() | odbc_free_result() | Résultat ODBC |
| velocis link | ||||
| velocis result | ||||
| OpenSSL key | openssl_get_privatekey(), openssl_get_publickey() | openssl_sign(), openssl_seal(), openssl_open(), openssl_verify() | openssl_free_key() | Clé de cryptage OpenSSL |
| OpenSSL X.509 | openssl_x509_read() | openssl_x509_parse(), openssl_x509_checkpurpose() | openssl_x509_free() | Clé publique |
| oracle cursor | ora_open() | ora_bind(), ora_columnname(), ora_columnsize(), ora_columntype(), ora_error(), ora_errorcode(), ora_exec(), ora_fetch(), ora_fetch_into(), ora_getcolumn(), ora_numcols(), ora_numrows(), ora_parse() | ora_close() | Curseur oracle |
| oracle link | ora_logon() | ora_do(), ora_error(), ora_errorcode(), ora_rollback(), ora_commitoff(), ora_commiton(), ora_open(), ora_commit() | ora_logoff() | Lien vers une base de données oracle |
| oracle link persistent | ora_plogon() | ora_do(), ora_error(), ora_errorcode(), ora_rollback(), ora_commitoff(), ora_commiton(), ora_open(), ora_commit() | None | Lien persistant vers une base de données oracle |
| pdf document | pdf_new() | pdf_add_bookmark(), pdf_add_launchlink(), pdf_add_locallink(), pdf_add_note(), pdf_add_pdflink(), pdf_add_weblink(), pdf_arc(), pdf_attach_file(), pdf_begin_page(), pdf_circle(), pdf_clip(), pdf_closepath(), pdf_closepath_fill_stroke(), pdf_closepath_stroke(), pdf_concat(), pdf_continue_text(), pdf_curveto(), pdf_end_page(), pdf_endpath(), pdf_fill(), pdf_fill_stroke(), pdf_findfont(), pdf_get_buffer(), pdf_get_image_height(), pdf_get_image_width(), pdf_get_parameter(), pdf_get_value(), pdf_lineto(), pdf_moveto(), pdf_open_ccitt(), pdf_open_file(), pdf_open_image_file(), pdf_place_image(), pdf_rect(), pdf_restore(), pdf_rotate(), pdf_save(), pdf_scale(), pdf_setdash(), pdf_setflat(), pdf_setfont(), pdf_setgray(), pdf_setgray_fill(), pdf_setgray_stroke(), pdf_setlinecap(), pdf_setlinejoin(), pdf_setlinewidth(), pdf_setmiterlimit(), pdf_setpolydash(), pdf_setrgbcolor(), pdf_setrgbcolor_fill(), pdf_setrgbcolor_stroke(), pdf_set_border_color(), pdf_set_border_dash(), pdf_set_border_style(), pdf_set_char_spacing(), pdf_set_duration(), pdf_set_font(), pdf_set_horiz_scaling(), pdf_set_parameter(), pdf_set_text_pos(), pdf_set_text_rendering(), pdf_set_value(), pdf_set_word_spacing(), pdf_show(), pdf_show_boxed(), pdf_show_xy(), pdf_skew(), pdf_stringwidth(), pdf_stroke(), pdf_translate(), pdf_open_memory_image() | pdf_close(), pdf_delete() | Document PDF |
| pdf image | pdf_open_image(), pdf_open_image_file(), pdf_open_memory_image() | pdf_get_image_height(), pdf_get_image_width(), pdf_open_ccitt(), pdf_place_image() | pdf_close_image() | Image dans un document PDF |
| pdf object | ||||
| pdf outline | ||||
| pgsql large object | pg_getlastoid(), pg_loimport(), pg_loimport() | pg_loopen(), pg_getlastoid(), pg_locreate(), pg_loexport(), pg_loread(), pg_loreadall(), pg_lounlink(), pg_lowrite() | pg_loclose() | Objet de grande taille PostGreSQL |
| pgsql link | pg_connect() | pg_cmdtuples(), pg_dbname(), pg_end_copy(), pg_errormessage(), pg_host(), pg_locreate(), pg_loexport(), pg_loimport(), pg_loopen(), pg_lounlink(), pg_options(), pg_port(), pg_put_line(), pg_set_client_encoding(), pg_client_encoding(), pg_trace(), pg_untrace(), pg_tty() | pg_close() | Lien vers une base de données PostGreSQL |
| pgsql link persistent | pg_pconnect() | pg_cmdtuples(), pg_dbname(), pg_end_copy(), pg_errormessage(), pg_host(), pg_locreate(), pg_loexport(), pg_loimport(), pg_loopen(), pg_lounlink(), pg_options(), pg_port(), pg_put_line(), pg_set_client_encoding(), pg_client_encoding(), pg_trace(), pg_untrace(), pg_tty() | None | Lien persistant vers une base de données PostGreSQL |
| pgsql result | pg_exec() | pg_fetch_array(), pg_fetch_object(), pg_fieldisnull(), pg_fetch_row(), pg_fieldname(), pg_fieldnum(), pg_fieldprtlen(), pg_fieldsize(), pg_fieldtype(), pg_getlastoid(), pg_numfields(), pg_result(), pg_numrows() | pg_freeresult() | Résultat PostGreSQL |
| pgsql string | ||||
| printer | ||||
| printer brush | ||||
| printer font | ||||
| printer pen | ||||
| pspell | pspell_new(), pspell_new_config(), pspell_new_personal() | pspell_add_to_personal(), pspell_add_to_session(), pspell_check(), pspell_clear_session(), pspell_config_ignore(), pspell_config_mode(), pspell_config_personal(), pspell_config_repl(), pspell_config_runtogether(), pspell_config_save_repl(), pspell_save_wordlist(), pspell_store_replacement(), pspell_suggest() | None | Dictionnaire Pspell |
| pspell config | pspell_config_create() | pspell_new_config() | None | Configuration Pspell |
| Sablotron XSLT | xslt_create() | xslt_closelog(), xslt_openlog(), xslt_run(), xslt_set_sax_handler(), xslt_errno(), xslt_error(), xslt_fetch_result(), xslt_free() | xslt_free() | Analyseur XSLT |
| shmop | shmop_open() | shmop_read(), shmop_write(), shmop_size(), shmop_delete() | shmop_close() | |
| sockets file descriptor set | socket() | accept_connect(), bind(), connect(), listen(), read(), write() | close() | Socket |
| sockets i/o vector | ||||
| dir | dir() | readdir(), rewinddir() | closedir() | Dossier |
| file | fopen() | feof(), fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), flock(), fpassthru(), fputs(), fwrite(), fread(), fseek(), ftell(), fstat(), ftruncate(), set_file_buffer(), rewind() | fclose() | Fichier |
| pipe | popen() | feof(), fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), fpassthru(), fputs(), fwrite(), fread() | pclose() | Processus |
| socket | fsockopen() | fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), fpassthru(), fputs(), fwrite(), fread() | fclose() | Socket |
| stream | ||||
| sybase-db link | sybase_connect() | sybase_query(), sybase_select_db() | sybase_close() | Lien vers une base de données Sybase avec la librairie db |
| sybase-db link persistent | sybase_pconnect() | sybase_query(), sybase_select_db() | None | Lien persistant vers une base de données Sybase avec la librairie db |
| sybase-db result | sybase_query() | sybase_data_seek(), sybase_fetch_array(), sybase_fetch_field(), sybase_fetch_object(), sybase_fetch_row(), sybase_field_seek(), sybase_num_fields(), sybase_num_rows(), sybase_result() | sybase_free_result() | Résultat Sybase avec la librairie DB |
| sybase-ct link | sybase_connect() | sybase_affected_rows(), sybase_query(), sybase_select_db() | sybase_close() | Lien vers une base de données Sybase avec la librairie CT |
| sybase-ct link persistent | sybase_pconnect() | sybase_affected_rows(), sybase_query(), sybase_select_db() | None | Lien persistant vers une base de données Sybase avec la librairie CT |
| sybase-ct result | sybase_query() | sybase_data_seek(), sybase_fetch_array(), sybase_fetch_field(), sybase_fetch_object(), sybase_fetch_row(), sybase_field_seek(), sybase_num_fields(), sybase_num_rows(), sybase_result() | sybase_free_result() | Résultat Sybase avec la librairie CT |
| sysvsem | sem_get() | sem_acquire() | sem_release() | Sémaphore Système V |
| sysvshm | shm_attach() | shm_remove(), shm_put_var(), shm_get_var(), shm_remove_var() | shm_detach() | Mémoire partagée Système V |
| wddx | wddx_packet_start() | wddx_add_vars() | wddx_packet_end() | Paquet wddx |
| xml | xml_parser_create() | xml_set_object(), xml_set_element_handler(), xml_set_character_data_handler(), xml_set_processing_instruction_handler(), xml_set_default_handler(), xml_set_unparsed_entity_decl_handler(), xml_set_notation_decl_handler(), xml_set_external_entity_ref_handler(), xml_parse(), xml_get_error_code(), xml_error_string(), xml_get_current_line_number(), xml_get_current_column_number(), xml_get_current_byte_index(), xml_parse_into_struct(), xml_parser_set_option(), xml_parser_get_option() | xml_parser_free() | Analyseur syntaxique XML |
| zlib | gzopen() | gzeof(), gzgetc(), gzgets(), gzgetss(), gzpassthru(), gzputs(), gzread(), gzrewind(), gzseek(), gztell(), gzwrite() | gzclose() | Fichier compressé Gzip |
| ZZIP Directory | ||||
| ZZIP Entry |
Annexe I. List of Parser Tokens
Various parts of the PHP language are represented internally by stuff like T_SR. PHP outputs identifiers like this one in parse errors, like "Parse error: unexpected T_SR, expecting ',' or ';' in script.php on line 10."
You're supposed to know that T_SR means >>. For everybody who doesn't know that, here is a table with those identifiers, PHP-syntax and references to the appropriate places in the manual.
Tableau I-1. Tokens
| Token | Syntax | Reference |
|---|---|---|
| T_AND_EQUAL | &= | assignment operators |
| T_ARRAY | array() | array(), array syntax |
| T_ARRAY_CAST | (array) | type-casting |
| T_AS | as | foreach |
| T_BAD_CHARACTER | anything below ASCII 32 except \t (0x09), \n (0x0a) and \r (0x0d) | |
| T_BOOLEAN_AND | && | logical operators |
| T_BOOLEAN_OR | || | logical operators |
| T_BOOL_CAST | (bool) or (boolean) | type-casting |
| T_BREAK | break; | break |
| T_CASE | case | switch |
| T_CHARACTER | ||
| T_CLASS | class | classes and objects |
| T_CLOSE_TAG | ?> or %> | |
| T_COMMENT | // or # | comments |
| T_CONCAT_EQUAL | .= | assignment operators |
| T_CONST | const | |
| T_CONSTANT_ENCAPSED_STRING | "foo" or 'bar' | string syntax |
| T_CONTINUE | continue | |
| T_CURLY_OPEN | ||
| T_DEC | -- | incrementing/decrementing operators |
| T_DECLARE | declare | declare |
| T_DEFAULT | default | switch |
| T_DIV_EQUAL | /= | assignment operators |
| T_DNUMBER | 0.12, etc | floating point numbers |
| T_DO | do | do..while |
| T_DOLLAR_OPEN_CURLY_BRACES | ${ | complex variable parsed syntax |
| T_DOUBLE_ARROW | => | array syntax |
| T_DOUBLE_CAST | (real), (double) or (float) | type-casting |
| T_ECHO | echo | echo() |
| T_ELSE | else | else |
| T_ELSEIF | elseif | elseif |
| T_EMPTY | empty | empty() |
| T_ENCAPSED_AND_WHITESPACE | ||
| T_ENDDECLARE | enddeclare | declare, alternative syntax |
| T_ENDFOR | endfor | for, alternative syntax |
| T_ENDFOREACH | endforeach | foreach, alternative syntax |
| T_ENDIF | endif | if, alternative syntax |
| T_ENDSWITCH | endswitch | switch, alternative syntax |
| T_ENDWHILE | endwhile | while, alternative syntax |
| T_END_HEREDOC | heredoc syntax | |
| T_EVAL | eval() | eval() |
| T_EXIT | exit or die | exit(), die() |
| T_EXTENDS | extends | extends, classes and objects |
| T_FILE | __FILE__ | constants |
| T_FOR | for | for |
| T_FOREACH | foreach | foreach |
| T_FUNCTION | function or cfunction | functions |
| T_GLOBAL | global | variable scope |
| T_IF | if | if |
| T_INC | ++ | incrementing/decrementing operators |
| T_INCLUDE | include() | include() |
| T_INCLUDE_ONCE | include_once() | include_once() |
| T_INLINE_HTML | ||
| T_INT_CAST | (int) or (integer) | type-casting |
| T_ISSET | isset() | isset() |
| T_IS_EQUAL | == | comparison operators |
| T_IS_GREATER_OR_EQUAL | >= | comparison operators |
| T_IS_IDENTICAL | === | comparison operators |
| T_IS_NOT_EQUAL | != or <> | comparison operators |
| T_IS_NOT_IDENTICAL | !== | comparison operators |
| T_SMALLER_OR_EQUAL | <= | comparison operators |
| T_LINE | __LINE__ | constants |
| T_LIST | list() | list() |
| T_LNUMBER | 123, 012, 0x1ac, etc | integers |
| T_LOGICAL_AND | and | logical operators |
| T_LOGICAL_OR | or | logical operators |
| T_LOGICAL_XOR | xor | logical operators |
| T_MINUS_EQUAL | -= | assignment operators |
| T_ML_COMMENT | /* and */ | comments |
| T_MOD_EQUAL | %= | assignment operators |
| T_MUL_EQUAL | *= | assignment operators |
| T_NEW | new | classes and objects |
| T_NUM_STRING | ||
| T_OBJECT_CAST | (object) | type-casting |
| T_OBJECT_OPERATOR | -> | classes and objects |
| T_OLD_FUNCTION | old_function | old_function |
| T_OPEN_TAG | <?php, <? or <% | escaping from HTML |
| T_OPEN_TAG_WITH_ECHO | <?= or <%= | escaping from HTML |
| T_OR_EQUAL | |= | assignment operators |
| T_PAAMAYIM_NEKUDOTAYIM | :: | :: |
| T_PLUS_EQUAL | += | assignment operators |
| T_PRINT | print() | print() |
| T_REQUIRE | require() | require() |
| T_REQUIRE_ONCE | require_once() | require_once() |
| T_RETURN | return | returing values |
| T_SL | << | bitwise operators |
| T_SL_EQUAL | <<= | assignment operators |
| T_SR | >> | bitwise operators |
| T_SR_EQUAL | >>= | assignment operators |
| T_START_HEREDOC | <<< | heredoc syntax |
| T_STATIC | static | variable scope |
| T_STRING | ||
| T_STRING_CAST | (string) | type-casting |
| T_STRING_VARNAME | ||
| T_SWITCH | switch | switch |
| T_UNSET | unset() | unset() |
| T_UNSET_CAST | (unset) | (not documented; casts to NULL) |
| T_USE | use | (not implemented) |
| T_VAR | var | classes and objects |
| T_VARIABLE | $foo | variables |
| T_WHILE | while | while, do..while |
| T_WHITESPACE | ||
| T_XOR_EQUAL | ^= | assignment operators |
| T_FUNC_C | __FUNCTION__ | constants, since PHP 4.3.0 |
| T_CLASS_C | __CLASS__ | constants, since PHP 4.3.0 |
Annexe J. About the manual
Formats
The PHP manual is provided in several formats. These formats can be divided into two groups: online readable formats, and downloadable packages.
Note : Some publishers have made available printed versions of this manual. We cannot recommend any of those, as they tend to become out-of-date very quickly.
You can read the manual online at http://www.php.net/ and on the numerous mirror sites. For best performance, you should choose the mirror site closest to you. You can view the manual in either its plain (print-friendly) HTML format or an HTML format that integrates the manual into the look and feel of the PHP website itself.
An advantage of the online manual over most of the offline formats is the integration of user-contributed notes. An obvious disadvantage is that you have to be online to view the manual in the online formats.
There are several offline formats of the manual, and the most appropriate format for you depends on what operating system you use and your personal reading style. For information on how the manual is generated in so many formats, read the 'How we generate the formats' section of this appendix.
The most cross-platform formats of the manual are the HTML and plain-text versions. The HTML format is provided both as a single HTML file and as a package of individual files for each section (which results in a collection of several thousand files). The HTML and plaintext formats are provided as tar files compressed using the bzip2 archiver.
Another popular cross-platform format, and the format most suited to printing, is PDF (also known as Adobe Acrobat). But before you rush to download this format and hit the Print button, be warned that the manual is nearly 2000 pages long, and constantly being revised.
Note : If you do not already have a program capable of viewing PDF format files, you may need to download Adobe Acrobat Reader.
For owners of Palm-compatible handhelds, the Palm document and iSilo formats are ideal for this platform. You can bring your handheld with you on your daily commute and use a DOC or iSilo reader to brush up on your PHP knowledge, or just use it as a quick reference.
For Windows platforms, the Windows HTML Help version of the manual soups up the HTML format for use with the Windows HTML Help application. This version provides full-text search, a full index, and bookmarking. Many popular Windows PHP development environments also integrate with this version of the documentation to provide easy access.
Note : A Visual Basic for Linux project is in the planning stage, which will include the development of a CHM Creator and Viewer for Linux. See their SourceForge.net page if you are interested in the progress.
About user notes
The user-contributed notes play an important role in the development of this manual. By allowing readers of the manual to contribute examples, caveats, and further clarifications from their browser, we are able to incorporate that feedback into the main text of the manual. And until the notes have been incorporated, they can be viewed in their submitted form online and in some of the offline formats.
Note : The user-contributed notes are not moderated before they appear online, so the quality of the writing or code examples, and even the veracity of the contribution, cannot be guaranteed. (Not that there is any guarantee of the quality or accuracy of the manual text itself.)
How to find more information about PHP
This manual does not attempt to provide instruction about general programming practices. If you are a first-time, or even just a beginning, programmer, you may find it difficult to learn how to program in PHP using just this manual. You may want to seek out a text more oriented towards beginners. You can find a list of PHP-related books at http://www.php.net/books.php.
There are a number of active mailing lists for discussion of all aspects of programming with PHP. If you find yourself stuck on a problem for which you can't find your own solution, you may be able to get help from someone on these lists. You can find a list of the mailing lists at http://www.php.net/support.php, as well as links to the mailing list archives and other online support resources. Furthermore, at http://www.php.net/links.php there is a list of websites devoted to PHP articles, forums, and code galleries.
How to help improve the documentation
There are three ways you can help to improve this documentation.
If you find errors in this manual, in any language, please report them using the bug system at http://bugs.php.net/. Classify the bug as "Documentation Problem". You can also submit problems related to specific manual formats here.
Note : Please don't abuse the bug system by submitting requests for help. Use the mailing lists or community sites mentioned earlier, instead.
By contributing notes, you can provide additional examples, caveats, and clarifications for other readers. But do not submit bug reports using the annotation system please. You can read more about annotations in the 'About user notes' section of this appendix.
If you know English and some foreign language, you may also help out in the translations. If you would like to start a new translation, or help in a translation project, please read http://cvs.php.net/co.php/phpdoc/howto/howto.html.tar.gz.
How we generate the formats
This manual is written in XML using the DocBook XML DTD, using DSSSL (Document Style and Semantics Specification Language) for formatting, and experimentally the XSLT (Extensible Stylesheet Language Transformations) for maintenance and formatting.
Using XML as a source format gives us the ability to generate many output formats from the source files, while only maintaining one source document for all formats. The tools used for formatting HTML and TeX versions are Jade, written by James Clark and The Modular DocBook Stylesheets written by Norman Walsh. We use Microsoft HTML Help Workshop to generate the Windows HTML Help format of the manual, and of course PHP itself to do some additional conversions and formatting.
You can download the manual in various languages and formats, including plain text, plain HTML, PDF, PalmPilot DOC, PalmPilot iSilo and Windows HTML Help, from http://www.php.net/docs.php. The manuals are updated automatically as the text is updated.
You can find more information about downloading the XML source code of this documentation at http://cvs.php.net/. The documentation is stored in the phpdoc module.
Translations
The PHP manual is not only available in various formats, it is also available in various languages. The text of the manual is first written in english, then teams of people across the world take care of translating it to their native language. If a translation for a specified function or chapter has not yet been made, the build system of the manual falls back to the english version of it.
Peoples involved in the translations start from the XML source code available from http://cvs.php.net/ and from it they translate to thier mother language. They do not use the HTML, the plain text, or the PDF version. It is the build system which takes care of the conversions from XML to human readable formats.
Note : If you would like to help translating the documentation to your native language, please get in touch with the translation/documentation team subscribing to the phpdoc mailinglist: send an empty mail to phpdoc-subscribe@lists.php.net. The mailing list address is phpdoc@lists.php.net. State in the message that you are interested in translating the manual to a language and someone will get back to you, helping you start a new language translation or reach the already active documentation team for your language.
At the moment the manual is available, partly or not, in the following languages: Brazilian Portuguese, Czech, Dutch, Finnish, French, German, Hungarian, Italian, Japanese, Korean, Polish, Romanian, Russian, Spanish, Turkish.
They all can be downloaded here: http://www.php.net/docs.php.