Notes pour les débutants
De Patchwork.
Sommaire
|
Introduction
Ces notes représentent mes débuts avec patchwork. Vous allez trouver certainement pas mal de redondances avec des parties comme Documentation et Exemples. A travers ces notes, j'essaie de répondre tout d'abord à mes propres questionnements et me constituer mes premiers repères. Souvent quand on débute, on est confronté à des notions qui ne semblent pas très claires, il faut refaire la même manipulation plusieurs fois, on oublie vite : une question à laquelle on a répondu ce matin peut revenir en fin de journée voire quelques minutes après (pour moi c'est toujours le cas)... Donc, par honnêteté envers tout débutant ou spécialiste, je transcrirai toutes les questions (même si elles vous paraîtront les plus nulles, les plus évidentes) que je me suis posées, et que je continuerai certainement à me poser tant que je ne maitriserai pas notre objet de discussion. Veuillez être indulgents avec le jeune néophyte que je suis...
Environnement de travail
Le but est de préparer votre machine de travail pour tester les exemples présentés dans la section Exemple. Donc on aura besoin de :
- serveur web compatible PHP (capable d'interpréter des scripts PHP) : Apache
- un système de gestion de base de données : MySQL
- un outil d'interaction avec MySQL : phpMyAdmin
Ces trois logiciels peuvent être installer séparément, mais il existe des outils qui prennent en charge l'intégralité de nos besoins :
- Linux => LAMP, ...
- Windows => WAMP, EASYPHP, ...
Installation LAMP
Installation WAMP
Editeur de texte
À détailler plus et expliquer le pourquoi du comment...
Notepad++ est déconseillé, car il gère bizarrement UTF-8
Architecture des applications
Par où et comment commencer ?
Au sein du répertoire /var/www créer deux sous-répertoires : htdocs et patchwork, ce qui vous donne :
- /var/www/htdocs
- /var/www/patchwork
Au sein du répertoire /var/www/patchwork créer deux sous-répertoires kernel et cache, ce qui vous donne :
- /var/www/patchwork/kernel
- /var/www/patchwork/cache
Dans le répertoire kernel que vous venez de créer faites une copie de la dernière version de patchwork du dépôt GIT Dépôt GIT
Retour au répertoire cache, où on va créer deux sous-répertoires common et un autre répertoire qu'on va appeler test qui va contenir notre application test, on obtient donc :
- /var/www/patchwork/cache/common
- /var/www/patchwork/cache/test : chaque fois que le répertoire test sera évoqué il s'agira bien de celui décrit par ce chemin absolu (sauf mention particulière).
Le répertoire test va contenir tous les exemples que vous allez essayer de reproduire. Avant d'aller un peu plus loin, il faut comprendre qu'à chaque fois que vous voulez créer une application : monApplic1, monApplic2, ... Il faut lui créer son propre dossier dans le répertoire /var/www/patchwork/cache ce qui doit donner :
- /var/www/patchwork/cache/monApplic1
- /var/www/patchwork/cache/monAplic2
- Ainsi de suite ...
Dans le répertoire common créer la suite des sous-répertoires suivants data, queue, pTask et pMail qui correspondent à l'arborescence suivante :
- /var/www/patchwork/cache/common/data/queue
- /var/www/patchwork/cache/common/data/queue/pTask
- /var/www/patchwork/cache/common/data/queue/pMail
Maintenant concentrons-nous sur l'application test (et placez-vous dans votre répertoire test). A l'aide de votre éditeur préféré créer un fichier config.patchwork.php. C'est le seul fichier dont la présence est obligatoire pour chaque application (voir Structure de fichiers dans Documentation). Mettez y :
<?php #patchwork ../common
Créer un sous-répertoire public dans lequel vous aller créer de nouveau un autre dossier nommé __ (double underscore, voir Structure de fichiers dans Documentation). Si vous avez bien suivi, vous allez avoir l'arborescence suivante :
- /var/www/patchwork/cache/test/config.patchwork.php
- /var/www/patchwork/cache/test/public/__
Vous pouvez (quoique vous n'en aurez pas besoin pour le moment) créer aussi le sous-répertoire class dans lequel vous créerez un dossier agent
- /var/www/patchwork/cache/test/class/agent
Je sais que vous êtes impatients de tester votre premier exemple, c'est bon on y arrive ! Pour cela, éditer un fichier index.ptl dans lequel vous allez juste copier/coller l'exemple Afficher une variable générée dans le template (voir Exemples)
Il nous reste une dernière étape avant de s'attaquer au navigateur ! Placez-vous dans le répertoire /var/www/htdocs et créez un dossier mesApplic au sein de ce dossier éditer un fichier test.php. Que va contenir ce fichier ? Pour le savoir, allez éditer le fichier /var/www/patchwork/kernel/example/index.php copiez son contenu mettez le dans votre test.php. Vous voyez ce qui vous reste à faire ? Deux lignes à modifier :
- La première est : $a = /var/www/patchwork/cache/test;
A quoi cela rime-t-il ? Par défaut le dossier cache de chaque application monApplic se trouve dans /var/www/patchwork/kernel/variations/monApplic et il s'appelle zcache(voir Le dossier zcache). Et comme on veut qu'il soit plutôt dans /var/www/patchwork/cache/monApplic, alors on édite le fichier monApplic.php et on lui apporte la modification voulue
- La deuxième : $a = ' /var/www/patchwork/kernel/bootstrapper.php '
ça mérite une explication ....
- Ne pas fermer la balise ouvrante php, car ça ne sert à rien et c'est source d'erreur
C'est tout bon, dans votre navigateur demandez l'URL : localhost/mesApplic/test, ça devrait afficher le fameux : Hello World Si maintenant vous explorer le dossier de votre application test vous verrez qu'un dossier zcache vient de se créer dedans (ce mécanisme a besoin de quelques explications, on y reviendra un peu plus bas Le dossier zcache, mais ne nous attardons pas pour le moment).
Aiguillage des requêtes
A ce stade je me pose déja quelques questions :
- pourquoi avoir demander l'URL localhost/mesApplic/test et non /localhost/mesApplic/test/index.ptl ?
Chaque fichier toto.ptl se trouvant dans /public/__/ et d'extension .ptl une fois exécuté, son résultat est accessible dans le navigateur à l'adresse 'localhost/test/toto sans extention .ptl
- Alors pourquoi dans ce cas ne pas avoir demander localhost/mesApplic/test/index ?
Il s'agit tout simplement d'une convention patchwork, quand le fichier s'appelle index.ptl, on peut s'en passer de son nom, d'où l'URL localhost/mesApplic/test.
Pour résumer, si dans /public/__/ vous avez par exemple deux fichiers indexBis.ptl et index.ptl ce dernier vous pouvez l'atteindre de deux façons, par contre pour atteindre le premier il faut demander l'URL localhost/mesApplic/test/indexBis
Continuons avec nos exemples
Affichage de variables
Prenons maintenant l'exemple Afficher une variable générée par l'agent (voir Exemples). Pour cela on a besoin d'éditer un fichier newExample.php dans lequel on placera le contenu de notre exemple. Afin de respecter la convention de nommage (voir Structure de fichiers dans Documentation) ce fichier doit être placé dans le dossier /test/class/agent.
Je pense maintenant que vous savez où placer le fichier de template associé à notre exemple. Mais quel nom lui donner ? C'est simple, il faut l'appeler newExemple.ptl.
Quelle URL demander au navigateur ? On demande localhost/test/newExemple et non /localhost/test/newExemple.php
Les tableaux
Si vous avez bien compris, vous n'aurez aucun souci avec les deux exemples les tableaux simples et les tableau complexes de Exemples.
Affichage par catégorie
Jusqu'à présent votre /test/config.patchwork.php était vide, comme il vous ai demandé dans l'exemple, rajoutez la ligne suivante :
$CONFIG += array('DNS' => 'mysqli://root@localhost/nomDeVotreDB')
A développer plus...
Superposition des classes (SC) et Héritage multiple d'application (HMA)
- Une application test peut dériver de plusieurs autres applications appli1, appli2, ... c'est ce qu'on appel l'héritage multiple d'application. Cela est définie dans le fichier
config.pathwork.php de l'application test à l'aide de la directive #patchwork et se fait comme suit :
#patchwork /var/www/patchwork/cache/appli1 #patchwork leCheminVersappli2/appli2
ça mérite plus d'explications : pourquoi ? à quoi cela sert ? ne peut-on pas faire autrement ? Mieux vaut un exemple bien détaillé que tout ce blabla ... !
Notre application test est entrain de s'exécuter, au moment où on a besoin de la définition d'une classe maClasse, c'est la fonction __autoload() qui intervient. Le mécanisme de recherche (de la définition de la classe maClasse) se déroule de la manière suivante :
D'abord la définition est cherchée dans le fichier /test/class/maClasse.php. Ensuite si elle n'est pas trouvée, la fonction __autoload() passe à un niveau dessous dans le graphe d'héritage des applications parentes et continue la recherche ainsi de suite jusqu'à trouver la définition.
Le graphe d'héritage d'application ? Comme on l'a dit, une application peut dériver de plusieurs autres. Pour éviter des conflits liés à l'héritage multiple, patchwork garanti la linéarité du graphe de l'héritage (donc ce graphe est totalement ordonné : prédécesseur/successeur, voir Conventions)... Peut-être que ce n'est pas trop clair encore ... ? !!!
- Au sein d'une application on peut définir diverses classes, chacune de ces classes peut étendre une classe classMère d'une ou de plusieurs applications parentes, et cela sans changer de nom de la classe mère classMère. C'est ce que l'on appelle la superposition de classe, concrètement c'est le faite qu'une classe B peut bénéficier des propriétés d'une classe A qui est en dessous dans le graphe d'héritage (une classe B de l'appli successeur utilise le code d'une classe A dans l'une des appli ascendantes, sauf que là pour B, on veut le même nom A) :
Supposons que notre application dérive de certaines autres applications, nous voulons utiliser le code d'une classe (étendre cette classe) classMère (qui est définie dans l'une des applications parentes) dans notre nouvelle application et cela sans changer de nom, donc en gardant le nom classMère. Avec la notion de superposition de classe, cela devient très simple, il suffit de commencer au début du fichier de la nouvelle classe par le mot clé : class classMère extends Self { ...ici ajouter le code supplémentaire qu'apporte votre nouvelle classe ...}.
Pareil, ça manque d'explications : pourquoi on veut pas changer de nom de la classe (parce qu'on veut pas gérer un nom de plus ! Oui, justement pourquoi ? ) ? Donc, un exemple bien clair sera très apprécié !
L'environnement de développement pStudio
Commencez par rajouter au fichier config.patchwork.php de votre application les deux directives suivantes :
#patchwork /var/www/patchwork/kernel/variations/pStudio
#patchwork /var/www/patchwork/kernel/variations/pStudio/pieces/codemirror
Dans votre navigateur demandez l'URL localhost/mesApplic/monAppli/pStudio
Vous obtenez ainsi un environnement de développement : A gauche vous avez le graphe d'héritage multiple linéarisé de votre application monAppli qui vous éclaircira un peu plus sur la notion HMA et SC.
Remarque : Comme on aimerai avoir l'environnement pStudio pour toutes nos futures applications, on va plutôt mettre les deux précédentes directives dans le fichier config.patchwork.php de l'application common et non dans chaque fichier config.patchwork.php de toute nouvelle application ! Et maintenant, grâce à l'HMA et la SC, il suffit pour chaque application de rajouter dans son config.patchwork.php la directive :
#patchwork /var/www/patchwork/cache/common (ça traduit le fait que notre application dérive de l'application common) ... ça vous éclairci encore plus les notions de HMA et SC ?!!!
Le dossier zcache
....
Remarque : F5 vs CTRL+F5
- F5 essaie d'utiliser le contenu du cache autant que possible ==> donc cela peut donner la même page même si le contenu a été modifié.
- CTRL+F5 abandonne le contenu du cache et récupère le contenu du serveur à nouveau (force une actualisation du cache) ==> donc on obtient le nouveau contenu en cas de modifications.
La fonction d'édition E()
... Surtout très utile pour déboguer ...
La séquence d'initialisation de patchwork
Supposons que l'URL de mon application est la suivante : http://SiteBidule.com/index.php
Dans le fichier httpd.conf du serveur, est indiqué le chemin du documentRoot qui est le suivant : /var/www/$HOST/htdocs/ donc c'est ici que le serveur va trouver le fichier index.php, ici $HOST = SiteBidule.com. Rappelez-vous, ce fichier est similaire au fichier test.php où vous avez renseigné deux lignes (voir la fin de la section Par où et comment commencer ?) :
1) 1ère ligne décrit le chemin de l'application du plus haut niveau = $monAppliPATH
2) 2éme ligne décrit le chemin de l'application du plus bas niveau = $patchworkPATH
- Si le cache est vide : Voici la liste des instructions exécutées dans l'ordre :
require $patchwork.bootstrapper (à détailler ...)
get lock : verrouillage (à détailler ...)
Chargement du fichier common.php, il contient tous les scripts généraux
Chargement du graphe d'héritage d'application ($monAppliPATH renvoie à config.patchwork.php avec ses directives) qui sera sous forme d'un tableau de classes ordonnées (linéarisation)
preconfig de bas en haut (dans l'ordre inverse de celui du graphe d'héritage, de $patchworkPATH --->$monAppliPATH) config de haut en bas
postconfig de bas en haut
Tout cela sera donc mis en cache et stocké dans le fichier $monAppliPATH/.patchwork
- Si le cache n'est pas vide : Il suffit d'un seul include (qui est donc rapide) pour récupérer le contenu du cache.
Remarque : Les classes qui sont souvent sollicitées (qu'on charge régulièrement) telles que agent, loop_sql, ... leurs codes sources sont dans le fichier 'kernel/class/patchwork.php'
Conventions
- Convention de nommage : le fichier .php de la classe toto_titi se trouve dans class/toto/titi.php (relativement au chemin de chaque application)
Le fichier class/agent/news.php contient le code source de la classe agent_news
Le fichier class/agent/widget/news.php contient le code de la classe agent_widget_news ainsi de suite ...
- Dans le graphe d'héritage multiple : au dessus (resp. en dessous) désigne le niveau successeur (resp. prédécesseur) ce qui concorde avec l'environnement de déveleppement pStudio
Faire attention, quand on parle de prédécesseur il ne faut pas s'astreindre juste à l'application d'en dessous, il s'agit d'explorer tout l'arbre d'ascendants de proche en proche (père > grand-père > ...> niveau 0 = patchwork)
Bibliographie
- PHP
http://www.apprendre-php.com/tutoriels/
- APACHE (Cache)
