Titre

rnb-php

Auteurs

Rui Nibau

Date

09 janvier 2011

Version

3.0

Statut

actif

Licence

Creative Commons Paternité-Partage à l'identique

La documentation est en cours de rédaction.

Présentation

rnb-php est une manière pratique d'organiser des objets ou fonctionnalités développés pour certains depuis 2005, et la plupart dans le cadre de la publication du site http://omacronides.com.

La librairie pourrait être divisée en deux parties : La première regroupe des utilitaires pour manipuler les données (dates, chaînes de caractères, tableaux), centraliser / harmoniser l'écriture ou la lecture sur le disque dur, gérer de manière sécurisée les requêtes HTTP, etc. La seconde, la plus importante, concerne des outils de publication web décrits dans les chapitres suivants.

Beaucoup de ces objets, pour ne pas dire la plupart, travaillent avec des formats de données « plats », et plus particulièrement deux d'entre eux : xml et json. Le premier a tendance à être abandonné au profit du second, pour une raison simple : que les données puissent être manipulées par des objets équivalents dans d'autres langages, en l'occurrence le javascript ; et il est relativement plus aisée de manipuler du json que du xml en javascript.

La classe rnb

La classe rnb est une classe centrale pour le fonctionnement de la librairie. Il est obligatoire de l'inclure dans un projet si l'on souhaite utiliser les différents modules. Elle fournit quelques méthodes statiques pour charger aisément des classes, stocker des instances ou des données (Registry) ainsi que quelques outils de debug. Le fichier en lui-même possède aussi des interfaces de comportement génériques utilisés par les modules.

include_once("path/to/rnb-php/rnb.php");

Les interfaces

• Config : Interface pour les objets possédant un tableau de configuration.
• Data : Interface pour un objet de gestion de données.
• Node : Interface pour les objets destinés à appartenir à une structure hiérarchique.
• Reader : Interface pour les objet chargés de lire des données.
• Render : Interface pour les objets destinés à rendre des données.
• Response : Interface pour les objets destinés à envoyer une réponse à une requête HTTP.
• Writer : Interface pour les objets qui doivent enregistrer des données.

Les classes abstraites

• Converter : classe abstraite à étendre par un objet qui doit convertir des données entre 2 formats.
• FileIO : classe abstraite à étendre par des objets qui peuvent recevoir ou écrire des données dans des fichiers.
• FileIO_Receiver : classe abstraite à étendre par des objets qui possèdent un objet FileIO.

Common

Le package common regroupe les objets utiles dans l'ensemble de la librairie. Ils sont automatiquement chargés la première fois qu'on les utilise.

Une première série d'objets apporte des fonctionnalités supplémentaires à la manipulation d'objets PHP existants :

• dt : collection de méthode pour manipuler les dates
• str : collection de méthodes pour manipuler les chaînes de caractères.
• io : collection de méthodes pour gérer la lecture / écriture de données dans des fichiers.

D'autres objets apportent des types ou des comportements de base :

• DataNode : objet permettant de construire une structure de données hiérarchisées, avec noeuds enfants et parent de même type (implémentation par défaut de l'interface Node) (voir Ecriture d'un objet dans différents langages).
• DataObject : objet permettant de stocker une série de données (implémentation par défaut de l'interface Data).
• Loader : objet de gestion de chargement de classes.
• Observable : classe à étendre permettant d'adopter un modèle d'écoute / émission d'événements.

Cache

Après avoir utilisé certaines solutions toutes faites, j'ai décidé d'écrire une classe extrêmement simple permettant de mettre en cache du contenu généré dynamiquement. Elle possède des fonctionnalités de base pour :

• Activer / désactiver la mise en cache.
• Définir le temps de mise en cache.
• Encoder le nom des fichiers.
• Sérialiser le contenu des fichiers.

CodeToDoc

codetodoc est un module qui permet de générer une documentation de code javascript à partir des commentaires.

• codedoc.php : script à utiliser en ligne de commande pour générer la documentation d'une série de fichiers.
• CodeToDoc : convertisseur des commentaires d'un fichier javascript en documentation.
• CodeBlock : objet représentant un bloc de commentaires.
• CodeReader : lecteur des commentaires d'un fichier javascript, renvoyant un objet structuré hiérarchiquement.
• CodeRender : Rendre l'objet de lecture renvoyé par CodeReader, soit en html, soit en syntaxe wiki.
• CodeTplRender : une extension de TPL_Render mettant à disposition quelques méthodes de formatage spécifiques, comme la création d'une signature de méthode.

Controleur de requêtes

La classe Controller permet de définir un comportement de réponse à des requêtes HTTP, en manipulant des objets HTTP_Request et HTTP_Response et en instanciant notamment un objet de rendu .

Données

Col : gestion de listes

Col est une classe définissant le comportement d'un objet chargé de gérer des données constituées d'un ensemble d'items. Le contenu de chaque item est décrit par une série de champs ; l'API permet ensuite d'effectuer des requêtes sur les items ou d'en créer.

{
    "name" : "collection"
    "description" : "Collection d'items",
    "type" : "object",
    "properties": {
        "metas": {
            "description": "Données décrivant la collection.",
                   "type": "object",
             "properties": {
                "name" : {
                    "description": "Nom de la collection",
                          "type" : "string",
                      "required" : true
                },
                "description": {
                    "description": "Description de la collection",
                           "type": "string",
                       "optional": true
                },
                "date": {
                    "description": "Date de création de la collection",
                           "type": "date",
                       "optional": true
                },
                "updated" : {
                    "description": "Date de mise à jour de la collection",
                           "type": "date",
                       "optional": true
                }
            }
        },
        "infos" : {
            "description": "Informations complémentaires, sur la manière de rendre la collection par exemple.",
                   "type": "object",
               "optional": true
        },
        "fields" : {
            "description": "Champs de la collection.",
                   "type": "object",
                  "items": { "$ref" : "/docs/field/schema.json" }
        },
        "items" : {
            "description": "Items de la collection.",
                   "type": "object"
        }
    }
}

Les données sont récupérées / enregistrées grâce à des fournisseurs de données (DataProvider) qu'il faut enregistrer au niveau de la classe. 3 fournisseurs sont présents par défaut, pour gérer le format json, le format xml et le format texte.

Doc : format de fichier

Doc est une classe qui définit l'API d'un objet chargé d'accéder à trois types d'informations :

• Un titre (chaîne de caractère)
• Une série d'en-têtes (couple libellé - valeur sur une seule ligne)
• Une série de champs (couple libellé - valeur)

Ces informations sont gérées par des fournisseurs de données (DataProvider) à enregistrer au niveau de la classe. 3 fournisseurs sont enregsitrés par défaut, pour les formats txt, json et xml. Voilà par exemple comment se présente un fichier au format txt :

Header-Name: Header-Value
======================================================
Title
======================================================

:field1: Field 1 value.

:field2: Field 2 value.
         Can be multiline.

:field3: Field 3 value

La syntaxe des en-têtes a été ajouté pour permettre à des fichiers au format texte d'être gérés par le logiciel Zim. Celle du libellé des champs est inspirée de la syntaxe des attributs utilisée par AsciiDoc.

Field : gestion de champs

La classe abstraite Field permet de définir des objets caractérisant un type de donnée ou « champ » puis de lire ou de manipuler cette donnée. Les objets sont caractérisés par un nom, une série d'attributs, un format d'affichage ou la présence / absence de sous-champs.

Il existe des objets prédéfinis pour les dates, les listes, les noms propres, les images, les urls, les nombres, les chaînes de caractères, les textes (multiligne).

{
    "name": "field",
    "description": "Description d'un objet champ",
    "properties": {
        "name": {
            "type": "string",
            "description": "Nom du champ",
            "required": true
        },
        "label": {
            "type": "string",
            "description": "Libellé du champ",
            "required": true
        },
        "type": {
            "type": "string",
            "description" : "Type du champ (string|date|number|...) (string par défaut)",
            "optional": true,
            "default": "string"
        },
        "subfields": {
            "type": "array",
            "description": "Liste des sous-champs",
            "items": { "type": "string" },
            "optional": true
        },
        "separator": {
            "type": "string",
            "description": "Séparateur des sous-champs, s'il y en a (espace par défaut)",
            "optional": true
        },
        "format": {
            "type": "array",
            "description": "Format des sous-champs, s'il y en a",
            "items": { "type": "string" },
            "requires": "subfields",
            "optional": true
        },
        "multiple": {
            "type": "boolean",
            "description" : "s'il s'agit d'un champ multiple (array) (false par défaut)",
            "optional": true,
            "default": false
        },
        "tokenlist": {
            "type": "boolean",
            "description": "s'il s'agit d'une tokenlist - items séparés par une virgule (false par défaut). Les éventuels subFields décrivent alors un unique item.",
            "optional": true,
            "default": false
        }
    }
}

FlatDB

FlatDB est une classe qui permet de gérer une collection de documents enregistrés sous forme de fichiers plats. Elle est configurable par un fichier au format json ou xml où l'on définit des champs décrivant les documents, champs qui peuvent être représentés par :

• La hiérarchie de dossiers dans lesquels sont rangés les documents.
• Le nom des documents.
• Tout ou partie du contenu des documents.

FlatDB possède ensuite une API pour effectuer des requêtes sur ces champs, et donc pour récupérer une série de contenus ou un document unique.

On peut aussi définir un gestionnaire de document Doc afin de personnaliser la manière dont sont récupérées les données dans le document lui-même.

{
    "desription": "Objet de configuration d'une base de données.",
    "type": "object",
    "properties": {
        "metas": {
            "description": "Descriptions de la base de données",
            "properties" : {
                "fieldSeparator" : {
                    "description": "Symbole de séparation des champs dans le nom des fichiers",
                           "type": "string",
                       "optional": true,
                        "default": "_"
                },
                "fileExtension": {
                    "description": "Extension des fichiers de la base de données",
                           "type": "string",
                       "optional": true,
                        "default": "txt"
                },
                "indexFormat": {
                    "description": "Format de l'index de la base de données.",
                           "type": "string",
                       "optional": true,
                        "default": "json"
                },
                "sortField": {
                    "description": "Nom du champ servant de tri par défaut",
                           "type": "string",
                       "optional": true,
                        "default": "id"
                },
                "sortSens": {
                    "description": "Sens du tri par défaut.",
                           "type": "string",
                           "enum": ["", "r"],
                       "optional": true,
                        "default": ""
                }
            }
        },
        "fields" : {
            "description": "Liste des champs.",
                   "type": "object",
                  "items": { "$ref" : "/docs/field/schema.json" }
        },
        "infos" : {
            "description": "Informations complémentaires.",
                  "type" : "object",
               "optional": true
            "properties": {
                "datas": {
                    "description": "Liste de données à ajouter à chaque docuement",
                           "type": "object"
                       "optional": true
                },
                "storage": {
                    "description": "Liste des champs à indexer présents en différents lieu du stockage d'un document",
                           "type": "object",
                       "optional": true
                     "properties": {
                        "folder": {
                            "description": "Liste des champs stockés en tant que nom de dossier",
                            "type": "array"
                        },
                        "file": {
                            "description": "Liste des champs stockés edans le nom du fichier",
                            "type": "array"
                        },
                        "content": {
                            "description": "Liste des champs stockés dans le contenu du fichier",
                            "type": "array"
                        }
                    }
                },
                "mode": {
                    "Description": "Modes de consultation des données.",
                           "type": "object",
                       "optional": true
                }
            }
        }
    }
}

Http

• HTTP_Request : objet permettant de gérer une requête HTTP.
• HTTP_Response : objet permettant de structurer une réponse HTTP.

Render

Le package render est issu de la séparation entre logique de réponse et logique de construction du contenu de la réponse à une requête HTTP. La réponse est maintenant gérée par un objet dédié, tout comme la construction du contenu, qui dépend de la nature du format de la réponse :

• HTML_Render : objet permettant de constuire une page web.
• JSON_Render : classe permettant le rendu de données sous forme d'objet JSON.
• TPL_Render : voir ci-dessous.
• XML_Render : gestionnaire d'un objet DOMDocument. La classe RSS_Render qui l'étend permet de rendre le contenu d'un flux RSS.

TPL_Render : moteur de modèles

TPL_Render (ancien module Template) est un constructeur de contenu un peu plus complexe que les autres. Il existe d'innombrables moteurs de modèles en PHP, la plupart trop complexes pour des besoins de base, d'où la création de cette classe :

• Elle ne possède aucune méthode pour manipuler / modifier des données ; l'objet n'est là que pour les afficher. Si on a besoin de tester une donnée, d'effectuer des boucles dans un tableau, etc., il suffit d'écrire du PHP.
• Elle ne définit pas non plus de balises ou de syntaxe supplémentaires alourdissant l'interprétation du code ; la seule petite concession est l'utilisation d'une double accolade pour remplacer un echo ou la strucrture {% … %} pour insérer du code PHP. Ces 2 notations peuvent être remplacées par une notation PHP.

<!DOCTYPE html>
<html>
    <head>
        <title>{{ $title }}</title>
    </head>
    <body>
        <h1>{{ $header }}</h1>
        <ul>
        {% foreach ($list as $item): %}
            <li>{{ $item }}</li>
        {% endforeach; %}
        </ul>
    </body>
</html>

$myTemplate = new TPL_Render($config);
$myTemplate->set("title", "Ma super page");
$myTemplate->set("header", "Mon super titre");
$myTemplate->set("list", array("item 1", "item 2", "item 3"));
$output = $myTemplate->render();

<!DOCTYPE html>
<html>
    <head>
        <title>Ma super page</title>
    </head>
    <body>
        <h1>Mon super titre</h1>
        <ul>
            <li>item 1</li>
            <li>item 2</li>
            <li>item 3</li>
        </ul>
    </body>
</html>

L'objet possède quelques autres petites fonctionnalités, comme la possibilité d'inclure un autre fichier template, mais pour le reste, le code PHP dicte sa loi !

StxManager

A l'origine, le projet était simplement destiné à convertir une syntaxe wiki en HTML. Au fil des extensions et des factorisations de code, il est devenu quelque chose de plus générique, permettant de fournir des objets de lecture et d'écriture de différents formats de données. StxManager s'articule ainsi autour de processeurs de syntaxes (StxProcessor) qui peuvent être de deux types :

• Un lecteur (Reader), chargé de transformer un document en un objet DataNode en fonction des règles de syntaxe du format lu.
• Un objet de rendu (Writer), capable de récupérer un objet DataNode pour le transformer en un format cible.

$node = $myStxReader->read($input);
$output = $myStxWriter->write($node);

Ces processeurs contiennent des gestionnaires de syntaxe (StxElement), un pour chaque règle de syntaxe supportée ; ils peuvent aussi posséder des extension (StxExtention) afin d'effectuer des traitements autre que la lecture / écriture d'une règle de syntaxe.

Enfin, on peut écrire des convertisseurs (Converter) qui se chargent de faire le lien entre un « reader » et un « writer » :

$output = $myStxConverter->convert($input);

Lire une syntaxe wiki

La lecture d'une syntaxe wiki par défaut se fait par la classe WikiReader. Elle prend en charge tous les éléments de cette syntaxe.

// Importation du lecteur wiki
include_once('StxManager/stx/wiki/Wiki_StxReader.php');
// Création d'un objet de lecture
$reader = new Wiki_StxReader();
// Création d'un objet DataNode à partir d'une chaîne wiki
$outlineNode = $reader->read($wikiString);

La classe possède 3 extensions par défaut :

• WikiToc pour créer une table des matières
• WikiLoad pour charger le contenu de fichiers externes
• WikiAttr pour gérer la déclaration d'attributs

Rendre du HTML

L'écriture d'une syntaxe HTML se fait grâce à la classe HTML_StxRender.

// Importation du writer HTML
include_once('StxManager/stx/html/HTML_StxRender.php');
// Création d'un objet d'écriture
$writer = new HTML_StxRender();
// Ecriture d'une chaîne HTML à partir d'un objet DataNode
$htmlString = $writer->render($outlineNode);

La classe possède 2 extensions :

• HtmlToc pour créer une table des matières.
• HtmlAttr pour rendre les attributs d'éléments.

Tellico

Le module tellico regroupe une série de classes permettant de manipuler les fichiers de l'application Tellico.

• TellicoReader : classe pour lire un fichier Tellico et récupérer les données sous forme de tableau PHP.
• TellicoToCol : classe pour transformer les données d'un fichier Tellico en données d'un objet Col.
• TellicoToFlatDB : classe pour transformer les données d'un fichier Tellico en données gérables par un objet FlatDB.

Historique

2012-01

• Controller : restructuration de la gestion de contrôle avec des « routes ».
• StxManager : révision de la gestion de la syntaxe pour audio et vidéo.
• Col : possibilité de gérer des collections au format texte.
• FlatDB : gestion de collections (Col).
• Auth : gestionnaire d'indentification.
• Déplacement de Col, Doc et Field dans un package « data ».
• Simplification des objets pour utiliser les interfaces génériques.
• clean, debug, enommage d'objets et fonctionnalités secondaires.

2011-08

• codetodoc : nouveau module pour générer la document d'un code javascript.
• Changement d'API de Render::render : la méthode de l'interface doit maintenant recevoir un paramètre.
• Renommage : WikiReader => Wiki_StxReader
• Renommage : HtmlWriter => Html_StxRender
• WikiParagraphReader : span à chaque saut de ligne facultatif
• Restructuration importante de StxManager : réduction du nombre de classes pour gérer des éléments de syntaxe. Les données des syntaxes sont maintenant stockés dans des fichiers json, utilisables ailleurs.
• StxManager : syntaxe d'une checklist, inspirée par celle utilisée dans Zim

2011-07

• StxManager : gestion du line break
• StxManager - HtmlPreRender : option pour injecter une balise code.
• Field étend maintenant l'objet DataObject.
• WikiReader : la syntaxe pour les figures passe de « --- » à « ---- ».
• Controller : gestion de l'en-tête HTTP
• Controller / Dispatcher : changement de structure ; le package cms n'est plus nécessaire.
• Corrections pour éviter les avertissements en standard strict
• Déplacement de Error dans le package common.

2011-01 : rnb-php 3.0

Restruction importante du paquetage

• Logique de contrôle dans un paquetage dédié.
• Fusion de Service avec le controller.
• Deconnexion de la logique « render » et « response ».
• Requêtes « ET/OU » sur les collections.
• Changement dans la lecture des données.
• Module tellico.

2010-11

• Evolution majeure de FlatDB, qui devient une variation de Collection.
• Corrections de bugs.

2010-04

• Format json pour la gestion des données.
• Système des références dans StxManager.

2009-10 : rnb-php 2.0

Intégration des projets annexes (FlatDB, FlatCMS) en tant que modules de rnb-php.

• Evolution de Template.
• Système des extensions pour StxManager.

2009-03

Doc2html devient StxManager, outil plus générique.

2008-02 / 2008-06 : rnb-php 1.0

Première version avec la structure définitive sous forme de modules.

• Création de FlatCMS, futur CMS.
• Version initiale de FlatDB.
• Création de Collection.
• Création deTemplate.

2006-09

• Evolution des scripts à l'origine de FlatDB.
• Création de Cache.

2006-06

• Meilleure gestion du format xml.
• Evolution de doc2html.

2006-01

• Evolution des scripts de publication.
• Syntaxe des tableaux dans doc2html.

2005-09

Première version dérivée du code de Autoit-CMS.

• doc2html (futur StxManager) dérivé du code d'Autoit-CMS et du wiki2whtml de Dotclear.
• Gestion de publication de fichiers xml (futurs FlatDB).