PHP

Note: ce que j'écris ici se rapporte surtout à la documentation technique de librairies et applications Open Source et/ou commerciales, et pas de la documentation pour les utilisateurs.

Écrire de la doc, la hantise du programmeur? Ca dépend beaucoup de comment on s'y prend. Je connais bien trop de librairies Open Source qui n'ont pas de documentation, si ce n'est la inline doc avec les descriptions des fonctions et méthodes - et la plupart du temps, ces informations sont absolument inutiles. Le résultat est que même si on utilise un générateur de documentation comme phpDocumentor, on a une belle documentation cliquable et tout, mais quand on veut savoir comment utiliser telle ou telle fonction, on n'y trouve que des banalités. Or, c'est une bonne documentation qui va garantir la longévité et le succès d'une librairie ou application.

Pour ceux qui ne connaissent pas, Anthéa est mon site perso (le nom vient d'un personnage d'un livre que j'ai commencé à écrire il y a quelques années), qui a la particularité d'être très large: 5800 pixels pour être exact

J'ai fait une assez grande mise à jour, en rajoutant près de 10 projets anciens et récents à la section références, et j'ai rajouté la section des liens. J'ai aussi retravaillé la liste des références et la mise en page du détail d'une référence. Pour ça, le XSLT est quand-même vachement pratique - rapide, flexible... très sympa. Anthéa fonctionne avec patPortal*, et pour utiliser du XSL, c'est super facile. Dans le fichier XML définissant les contenus d'une page, il suffit de rajouter la composante XSL et de la configurer:


<page:area id="content">
    <component:components>
        <component:component name="XSL">
            <component:params>
                <component:param name="xmlfile">
                    data/projects.xml
                </component:param>
                <component:param name="xslfile">
                    templates/XSL/projectList.xsl
                </component:param>
            </component:params>
        </component:component>
    </component:components>
</page:area>


Le contenu que va générer la composante XSL sera donc inséré dans la partie 'content' de la page. Pour placer le contenu d'une partie de page, il suffit de placer la variable correspondante dans le template du framework du site (patTemplate). Dans Anthéa, ça donne ceci:


<!-- 
    extrait du template framework.tmpl,
    contenant la structure HTML du site
-->
<div id="contentFrame">
    <table cellpadding="0" cellspacing="0" border="0">
        <tr valign="top">
            <td width="513">
                <div style="width:513px;">
                    <div id="content">
                        {AREA_CONTENT}
                    </div>
                </div>
            </td>
            <td>
                <div id="nav">
                    <div style="padding:15px;">
                        {AREA_NAVIGATION}
                    </div>
                </div>
            </td>
        </tr>
    </table>
</div>


Le contenu est inséré à la place de la variable {AREA_CONTENT}. On peut définir autant de composantes qu'on veut dans une même partie de page, leurs contenus sont ajoutées entre elles dasn l'ordre ou elles sont définies dans le XML. On peut donc se construire les pages de toutes pièces

*: patPortal est un nouveau projet de php-tools, mais qui n'a pas encore été publié. C'est un framework MVC développé par Stéphane, et qui a la grande particularité d'abstraire a peu près tout ce qui peut l'être... il est possible de télécharger la version CVS actuelle sous snaps.php-tools.net.

La nouvelle édition du International PHP Magazine est un petit coup de maître, vu qu'on y a fait une combo x 3: vous y trouverez l'article 'Go OO!' de Stéphane, l'article 'Painless Holiday Calculation with PEAR:: Date_Holidays' de Carsten et mon article 'Web Forms & a Cuppa Tea Please'

Traduction du billet 'php-tools.net relaunch plans' de php-tools:

Nous avons décidé de faire une remise à neuf du site php-tools.net, et aimerions savoir si vous avez des idées comment nous pouvons l'améliorer. Nous savons déjà assez bien ce que nous allons faire, mais vous pouvez encore nous aider. Dites-nous simplement ce qui vous plaisait le moins et le plus sur le site actuel, et quelles fonctions vous manquaient le plus. Envoyez-moi un mail à argh [@] php-tools [.] net avec vous idées / critiques / demandes de fonctionnalités.

Merci d'avance de toute l'équipe!

Traduction du billet 'All new pat channel server' de php-tools:

Depuis que Greg Beaver a inventé la classe PEAR_Server et que Davey Shafik a crée un package très pratique pour mettre en place sa propre interface pour un serveur de canaux PEAR, ça nous démangeait d'en faire un pour pat. Stéphane a installé l'interface sur pear.php-tools.net, et après que mes yeux de designer ont arrêté de saigner en voyant la mise en page par défaut de la bête (@Davey: je sais que ce n'est qu'un exemple ), j'ai fait un petit design pour pat et c'est parti.

Pour l'instant seulement quatre de nos librairies sont disponibles par notre canal, mais nous allons ajouter les autres au fur et à mesure.

Vous pouvez trouver plus d'infos sur PEAR_Server dans le blog de Greg, ainsi que sur l'interface de Davey dans son blog.

Traduction du billet 'New releases of patConfiguration and patTemplate' de php-tools:

Hier Stéphane a publié patTemplate 3.1.0a1, la premiere version alpha de la branche 3.1 de la librairie. Cette version ajoute des dizaines de nouvelles fonctions, et même si elle est encore alpha elle est déjà très stable. Stéphane l'utilise même dans un de ses projets avec près de 400.000 visiteurs par jour.

La version v2.0.0b2 de patConfiguration contient principalement des corrections, et est censée être la dernière version avant la publication de la premiere version estampillée stable.

Si vous utilisez une de ces librairies et ces versions, testez-les et signalez tous les bogues que vous trouvez. Si vous utilisez PEAR 1.4.0, vous pouvez aussi les installer par notre serveur de canaux.

Hier j'ai reçu la confirmation que mon article sur patForms (en) va paraître dans le prochain numéro (03.05) du International PHP Magazine (en). Pour ceux qui ne connaissent pas encore patForms, c'est une librairie qui permet de générer des formulaires. Ce qui la démarque des autres, c'est avant tout sa simplicité et le fait qu'on a le contrôle total de la mise en page et du visuel du formulaire. patForms est un projet de l'équipe de PHP Application Tools (en), développé par Stéphane (en), gERD (en|de) et moi-même.

Mon article est scindé en deux parties, et la première partie qui va sortir bientôt présente l'architecture et les possiblilités de base façon tutoriel avec beaucoup d'exemples. Dans la deuxième partie, j'insisterai sur la gestion des évènements, les observateurs, filtres et autres. Pour découvrir patForms c'est l'idéal, surtout que la seule source d'informations à l'heure actuelle est la collection d'exemples (en), qui est très fournie et bien documentée.

Et pourquoi encore une libraire de gestion de formulaires, me direz-vous - il est vrai qu'il y en a beaucoup, mais j'en avais marre de me battre avec des solutions jamais optimales, et je trouve que même des outils très plébiscités comme PEAR::QuickForm sont trop hermétiques et pas assez flexibles. Pourquoi? Parce-que je veux que ce soit intuitif. Si il faut que je tape 60+ de lignes de code super-cryptique juste pour afficher trois champs de formulaire, non merci. Et c'est là la vraie force de patForms: c'est super simple à utiliser - voilà tout ce qu'il faut pour créer un formulaire qui se valide tout seul:


// inclure les classes nécessaires
require_once 'pat/patForms.php';
require_once 'pat/patForms/Parser.php';
require_once 'pat/patErrorManager.php';

// définir les options essentielles
patForms_Parser::setNamespace( "patForms" );
patForms_Parser::setCacheDir( "cache" );

// créer l'objet formulaire à partir d'un template
$form =& patForms_Parser::createFormFromTemplate(
   'SimpleRenderer',
   'templates/form.fhtml',
   'templates/form.html'
);

// dire au formulaire de se valider tout seul
$form->setAutoValidate( 'save' );

// afficher le formulaire
echo $form->renderForm();

// le formulaire a-t-il été envoyé?
if( $form->isSubmitted() ) {
   // des erreurs de validation?
   $errors = $form->getValidationErrors();
   if( $errors ) {
      // afficher les erreurs
   } else {
      // faire qq-chose avec les données
      $values = $form->getValues();
   }
}


L'intéressant ici, c'est surtout le template de formulaire Le parseur de patForms permet de générer un objet patForms à partir d'un fichier html ou encore un template patTemplate. Dans ce cas-ci, c'est un ficheir html qui pourrait avoir le contenu suivant:


<html>
   <head>
      <title>Faut être logué...</title>
   </head>
   <body>
   <patForms:Form name="foo">
      <patForms:Hidden name="caché" default="zutaseluikilalu"/>

      <div id="login">
         Pseudo: <patForms:String name="username" required="yes" size="8" maxlength="8"/><br/>
         Passe: <patForms:String name="password" type="password" required="yes" size="6" maxlength="6"/><br/>
      </div>
   </patForms:Form>
   </body>
</html>


On peut donc écrire ses formulaires comme on le faisait avec un formulaire traditionnel, et ainsi avoir le contrôle complet du visuel. Bien sûr patForms offre aussi des méthodes simples pour créer des formulaires de manière dynamique, le parseur n'est qu'un addon.

Allez hop, j'en retourne à mes occupations mondaines - plus précisément la préparation des crèpes au sarrazin

Traduction du billet 'patConfiguration 2.0.0b1 released' de php-tools:

Stéphane a publié la première beta publique de son lecteur de configurations patConfiguration. À partir de cette version, la classe est basée sur des drivers avec une architecture unifiée pour lire les configurations à partir de fichiers XML, INI et WDDX avec la même interface.

Le driver XML est le plus puissant, puisqu'il permet de définier commetn les balises doivent être traitées. Il est ainsi par ex. possible de définir une balise <foo one="1" bar="totmato"/> pour qu'elle soit automatiquement convertie en tableau avec les attributs comme clés et valeurs. Bien sûr on peut aussi choisir pour chaque attribut quel type de variable y est stocké pour que les valeurs soient automatiquement convertis en valeurs booléennes, nombres, chaînesde caractère et même des objets.

Pour cela, patConfiguration propose une balise spéciale très simple:

<!-- définir un espace de nom -->
<define ns="boutique">
    <!-- définir une balise dans un espace de nom -->
    <define tag="articles" type="array"/>

    <!-- définir une balise sans nom (tableau indexé) -->
    <define tag="article" name="_none" type="array">
        <!-- définir trois attributs pour cette balise -->
        <define attribute="vendeur" type="string"/>
        <define attribute="titre" type="string"/>
        <define attribute="prix" type="float" default="99.99"/>
    </define>
</define>

Maintenant que les balises sont définies et que patConfiguration sait comment les integréter, on peut les utliser dans la configuration XML:

<boutique:articles>
    <boutique:article titre="Hache médiévale" vendeur="Argh"/>
    <boutique:article titre="Oeuf de dragon" vendeur="Merlin" prix="500"/>
</boutique:articles>

Lire cette configuration à partir d'un fichier est très simple:

<?php
$conf = new patConfiguration(
                            array(
                                'configDir' => './config'
                                )
                            );
// parse config file
$conf->loadConfig('example_define_basic.xml');

$config = $conf->getConfigValue('articles');
?>

Si vous êtes inquiet que le temps que de parser des fichiers XML à chaque requête ralentit votre application, vous pouvez activer le système de cache qui rend le chargement encore plus rapide que de stocker la configuration dans un fichier PHP. Si vous voulez utiliser les définitions des balises dans plusieurs fichiers, vous pouvez utiliser des entités externes ou des balises xInclude - patConfiguration gère les deux, même sous PHP4.

Après chargement avec patConfiguration, voilà le tableau résultant de notre exemple:
Array
(
    [0] => Array
        (
            [vendeur] => Argh
            [titre] => Hache Médiévale
            [prix] => 99.99
         )

    [1] => Array
        (
            [vendeur] => Merlin
            [titre] => Oeuf de dragon
            [prix] => 500
         )
)

patConfiguration permet en outre d'accéder à la configuration complète, ou juste des parties en utilisant une mixture de la syntaxe d'accès aux tableaux dans PHP et de syntaxe de chemins à la JavaScript (boutique.articles[0], par ex.) Pour voir la liste complète des possibilités qu'offre patConfiguration, il y a les exemples en ligne ou vous pouvez télécharger le package entier par notre site.

Si vous utilisez déjà PEAT 1.4.0, vous pouvez aussi l'installer par notre serveur de canaux:
$ pear channel-discover pear.php-tools.net
$ pear install --alldeps pat/patConfiguration

En cas de bogue, utilisez notre patBugzilla.

Traduction du billet 'Welcome to patPortal, Wiegi' de php-tools:

Depuis hier, Daniel a rejoint l'équipe de php-tools. Participant à la traditionnelle soirée programmation chaque mardi, il a d'ailleurs faite une entrée haute en couleurs en contribuant une nouveau filtre de réponse à patPortal. patPortal est un système de création d'applications Web basé sur un ensemble de composantes interconnectées. La grande particularité du projet est le très haut niveau d'abstraction - en effet, on n'accède par ex. jamais directement aux données d'une requête (GET, POST...), seulement par le biais d'un objet de requête. Le grand avantage étant que la même interface peut être utilisée pour des applications basées sur le protocole HTTP, sur des requêtes SOAP ou encore des applications CLI (ligne de commande).

Le même principe s'applique donc aux réponses - toutes les données sortantes de l'application passent par un objet de réponse. Le filtre de réponse de Daniel, StripWhitespace, permet d'enlever les espaces des données sortantes avant qu'elles ne soient envoyées.

Bienvenue donc à Daniel! Vous pouvez le joindre par son adresse wiegi[at]php-tools[dot]net (en anglais, de préférence, vu qu'il est allemand comme tout le reste de l'équipe - sans me compter moi, bien sûr...).

Traduction du billet 'New release of PEAR:: Date_Holidays' de php-tools:

Carsten a publié une nouvelle version de Date_Holidays, la v0.13.0. Cette librairie disponible dans PEAR est spécialisée pour les calculs de jours fériés ou autres jours spéciaux.

Carsten est aussi en train d'écrire un article à ce sujet pour le prochain numéro du International PHP-Magazine, ce qui lui a donné l'idée pour quelques nouvelles fonctionnalités:

• Il a adapté les calculs existants et ajouté un nouveau driver qui calcule les anniversaires des gens qui ont bien voulu nous donner leur date de naissance (voir mon billet précédent à ce sujet).
• Il a ajouté des objects filtre qui permettent de filtrer les dates calculées à l'aide de blacklists, whitelists et filtres composites.

Stéphane a une fois de plus pu contribuer en conseils et relecture de l'article

Pour tous ceux qui ont déjà été confronté au calcul de dates un peu spéciales, cette librairie et l'article à paraître sont un bon point de départ pour se rendre la vie plus facile. D'après le International PHP Magazine, l'article de Carsten sera disponible online un peu après la parution du magazine.

Traduction du billet 'The day you were born ...' de php-tools:

Pour tous ceux d'entre vous qui font partie des développeurs PEAR: Carsten aimerait que vous lui donniez votre date et lieu de naissance pour son projet Date_Holidays. Il est en train de programmer un Driver pour calculer les anniversaires de tous les contributeurs de php.net dans le cadre d'un article qu'il écrit pour le magazine PHP international.

Il a besoin de votre:

- nom
- date de naissance
- pays

Envoyez-lui un email avec ces informations à l'adresse suivante: luckec -at- php -dot- net. Merci d'avance!

Traduction du billet 'Services_Ebay 0.11.0 released' de php-tools:

Stéphane a publié une nouvelle version de Services_Ebay, avec deux nouvelles fonctionnalités et plusieurs méthodes. La première fonctionnalité est le système de cache des réponses du WebService d'eBay: intégré dans les modèles de classes de Services_Ebay, ceci permet de mettre les réponses des requêtes faites à eBay dans un cache local pour éviter les temps de transfert souvent assez longs de ces requêtes.

L'utilisation du cache est très simple:

<?php
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// choisir le cache local sous forme de fichiers
$userCache = Services_Ebay::loadCache('Filesystem', array('path' => './cache'));

// le fichier cache expirera après 15 minutes
$userCache->setExpiry('Static', 15);

// utiliser ce cache pour tous les modèles utilisateur
Services_Ebay_Model_User::setCache($userCache);

// charger un modèle d'utilisateur
$user = Services_Ebay::loadModel('User', 'superman-74', $session);

if ($user->isCached()) {
echo 'donées dans le cache';
print_r($user->toArray());
} else {
echo 'requête des donées online';
$user->Get();

print_r($user->toArray());
}
?>

Après avoir instancié un nouveau cache, on définit la durée de validité des données enregistrées. Pour l'instant, il est seulement possible de définir une durée fixe, mais comme les vérifications de durée sont des objets, il est facile d'en ajouter d'autres. Stéphane compte ajouter un objet de vérifiaction de validité qui diminuera automatiquement la durée du cache plus la fin de l'enchère approche. Il pense aussi ajouter un cache qui enregistre les données dans une base de données au lieu de fichiers, pour permettre un stockage plus flexible.

La deuxième fonctionnalité (avec un peu d'aide du fabuleux Adam Trachtenberg) est l'implémentation de la recherche de produits. Disponible sur eBay sous forme de fomrulaires permettant de rechercher des produits par une série de critères de recherche, Services_Ebay permet maintenant d'y accéder de manière très simple. eBay offre deux manières d'y accéder:

• par GetProductFinder, qui livre du XML contentant les informations nécessaires sous forme brute (champs de formulaire et valeurs pour la catégorie de produits choisie)
• pat getProductFinderXSL qui livre la feuille de style XSL qu'eBay utilise pour le rendu du HTML à partir des données XML brutes.

Comme l'accès à ces données se fait par un modèle dans Services_Ebay, il est tres simple d'y accéder:

<?php
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);
$ebay = new Services_Ebay($session);

// charger la feuille de style (enregistrée localement, ce serait trop
// long de la charger a chaque fois)
$xsl = file_get_contents('product_finder.xsl');

// charger la recherche de produits et l'afficher
list($productFinder) = $ebay->GetProductFinder(1909);
echo $productFinder->render($xsl);
}
?>
Ce petit bout de code affiche un formulaire incluant un peu de javascript, permettant à l'utilisateur de choisir ses produits à partir des critères disponibles.

Cette nouvelle version est aussi la première publication incluant des parties contribuées par Carsten Lucke. Carsten a ajouté des méthodes spécifiques pour les enchères et utilisateurs Néerlandais, ainsi que les modèles nécessaires.

Traduction du billet 'Tutorial for Services_Ebay' de php-tools:

Adam Trachtenberg, responsable technique chez eBay, a écrit un tutoriel d'introduction à Services_Ebay, la librairie d'accès aux WebServices d'eBay écrite par Stéphane.

Bien que relativement court, ce tutoriel aborde des aspects intéressants de la librairie en montrant les possibilités qu'offre la surcharge ('overloading' en anglais) d'objets. Il montre aussi comment définir ses propres modèles en les utilisant comme couche de présentation avec la méthode __toString().

Pour démarrer avec Services_Ebay, ce tutoriel est une bonne référence.

Traduction du billet 'International PHP 2005 Conference - Spring Edition' de php-tools:

Stéphane va tenir deux séances à la Conférence Internationale PHP de cette année qui se tiendra à Amsterdam:

1. Go OO! - Real-life patterns in PHP5
   Cette séance montrera comment on peut utiliser les nouvelles possibilités de programmation orientée objet avec PHP5, ainsi que les interfaces de la nouvelle librairie SPL.
2. Component and event-driven architectures in PHP5
   Cette séance montrera des nouveaux concepts de programmation évenementielle pour rendre vos applications plus flexibles par l'ajout d'une gestion d'évènements.

Stéphane fera aussi un 'Power Workshop' d'une journée intitulé 'XML and Web services with PHP5 and PEAR' avec Tobias Schlitt, et qui approfondira l'utilisation de WebServices avec PHP et les librairies disponibles dans PEAR.

Traduction du billet 'PEAR is getting event support' de php-tools:

Bertrand Mansion (en) a proposé une nouvelle librairie pour inclusion dans PEAR, Event_Dispatcher (en). Celle-ci offre une gestion simple d'évènements facile à intégrer dans une application PHP. Bertrand a déjà démarré l'appel au vote (en), mais comme nous utilisons déjà cette technique dans patPortal (en), et Stéphane dans son boulot chez 1et1 allemagne (de), il l'a essayé:

L'architecture de la librairie est assez simple: la classe Event_Dispatcher peut contenir des observateurs (appels natifs PHP) pour divers types de notifications. Ces observateurs sont informés de chaque évènement par une notification sous la forme d'un objet (la notification) très simple qui contient des informations sur l'évènement. Dans la vie de tous les jours, cette technique permet d'ajouter des fonctionalités à une application existante sans avoir à modifier le code source. Dans le site de 1et1 dont s'occupe Stéphane, il envoie une notification à chaque commande (évènement onOrder) en y ajoutant l'objet gérant la commande comme information. De cette manière, il est facile d'intégrer nombre d'objects pour par ex. écrire des logs, mettre à jour des cookies ou d'envoyer des suivis à des partenaires affiliés.

L'architecture simple de Event_Dispatcher est un atout, mais on arrive vite à des limites - dans ses essais, Stéphane a trouvé quelques lacunes. La première chose est qu'un observateur ne peut pas annuler (arrêter) un évènement: cela permettrait par ex. d'ajouter une ultime vérification avant que la commande d'un client ne soit envoyée, et d'annuler la commande le cas échéant. La deuxième chose est que la remontée d'évènements ('event bubbling' en anglais) n'est pas possible: cela permettrait des niveaux illimités de gestion dévènements, chaque évènement pouvant remonter toute la hiérarchie des observateurs. Enfin, il n'est pas possible de définir une classe sur mesure pour les notifications (ce qui peut être nécessaire selon le type d'informations qu'on veut y stocker).

Stéphane a implémenté toutes ces fonctionnalités dans le code de Bertrand, en espérant qu'il voudra bien inclure ces changements dans la version officielle de Event_Dispatcher lors de sa publication (si elle est acceptée par la communauté des développeurs de PEAR... votez!).