Hoa

Manuel d'apprentissage
⁂
Aspect framework

Dans cette section nous expliquons comment créer une application basée sur Hoa, en ré-utilisant tous les outils et automatismes à notre disposition.

Table des matières

  1. Aspect framework, un proof-of-concept
  2. Créer une application
    1. Où est Hoa ?
    2. Commandes dédiées à l'application
  3. Tester l'application

Aspect framework, un proof-of-concept

Hoa se définit avant tout comme un ensemble de bibliothèques. Toutefois, pour engager le développement avec Hoa, il est nécessaire de proposer des mécanismes dignes d'un framework afin de faciliter son apprentissage, son utilisation et ses contributions. C'est pourquoi Hoa propose un aspect framework qui doit être vu comme une démonstration de faisabilité, ou un proof-of-concept.

Nous noterons que l'aspect framework est évidemment tourné vers un usage intensif des bibliothèques, i.e. que nous ne proposerons pas d'« outils boîte-noires » sur lesquelles l'utilisateur n'a aucun contrôle. La philosophie de Hoa est tournée vers les bibliothèques, i.e. vers le fait que l'utilisateur sait et comprend parfalient ce qu'il fait. Ces bibliothèques fonctionnent bien ensemble, ce qui entraîne une modularité qui peut s'apparenter à des comportements rencontrés dans des frameworks, mais nous saurons toujours ce que nous faisons. Le fait que nous puissons créer ses propres bibliothèques et composants facilite la réutilisation et le partage de son travail, qui sont des aspects importants des frameworks.

Enfin, Hoa met particulièrement l'accent sur l'hackability (la bidouillabilité), i.e. que tout est modifiable (sans pour autant observer une régression des fonctionnalités). Nous saurons alors capable de construire une application avec nos propres spécificités, mécanismes, outils et fonctionnements.

Créer une application

Créer une application est très simple. Hoa propose deux mécanismes : le premier à travers Mercurial, le second à travers une archive exécutable Phar. Ainsi, première solution :

$ mkdir -p ~/Development/MyApp/
$ cd !!$
$ hg clone http://hg.hoa-project.net/Framework .
$ hoa tree --list-directory
~/Development/MyApp/
|-- Application/
|   |-- Public/
|-- Data/
|   |-- Bin/
|   |   |-- Command/
|   |-- Etc/
|   |   |-- Configuration/
|   |   |-- Locale/
|   |-- Lost+found/
|   |-- Module/
|   |-- Temporary/
|   |-- Variable/
|   |   |-- Cache/
|   |   |-- Database/
|   |   |-- Log/
|   |   |-- Private/
|   |   |-- Run/
|   |   |-- Test/
|   |   |   |-- Dictionary/
|   |   |   |-- Repository/
|-- Stub/

Ou alors avec une archive exécutable :

$ mkdir -p ~/Development/MyApp/
$ cd !!$
$ wget http://download.hoa-project.net/Framework/Hoa_Framework.next.phar
$ php Hoa_Framework.next.phar
Usage   : Hoa_Framework.next.phar <options>
Options :
    -m, --metadata  : Print all metadata.
    -s, --signature : Print signature.
    -p, --phar      : Phar informations.
    -e, --extract   : Extract application in the current directory.
    -h, --help      : This help.
    -?, --help      : This help.
$ php Hoa_Framework.next.phar --extract
Extracted in ~/Development/MyApp

Nous retrouvons l'architecture du dossier Data/ que propose l'abstraction hoa://, tout comme pour le dossier Application/. Nous noterons que Hoa est absent du framework !

Nous allons maintenant préciser à l'application où se trouve Hoa et créer notre propre script dédié à notre application.

Où est Hoa ?

Dans le dossier Data/Bin/, nous trouvons les scripts whereishoa et whereishoa.bat. Attention, si vous n'utilisez pas une installation « standard » de PHP, vous devrez retoucher la première ligne de whereishoa ou la variable PHP de whereishoa.bat.

Ce script va modifier trois fichiers :

Le fichier le plus important est bien entendu Data/Core.link.php, qui, lorsqu'il est inclu, liera notre application avec Hoa. Plusieurs avantages apparaissent : peu importe où est installé Hoa, notre application va toujours inclure Data/Core.link.php et nous n'aurons qu'à relancer Data/Bin/whereishoa pour la lier à Hoa ; ce qui implique que notre application pourra choisir entre plusieurs versions de Hoa si plusieurs existent. Enfin l'application peut même choisir d'embarquer Hoa ou pas, le choix pouvant être laissé à l'utilisateur lors de l'installation s'il souhaite utiliser la version embarquée de Hoa ou sa propre installation. Bref, nous aurons compris que le fichier Data/Core.link.php agit comme un routeur vers Hoa et que nous n'aurons jamais à modifier notre application si nous déplaçons ou modifie Hoa.

Lors de la création d'une application, tout est configuré pour chercher Hoa dans le dossier /usr/local/lib/hoa ; ce qui implique que si Hoa est présent dans ce dossier, pas besoin de lancer le script, sinon :

$ Data/Bin/whereishoa
** Where is Hoa **

Ready to redefine the path to Hoa?
We need to redefine it in:
  • the Core.link.php file;
  • the configuration file;
  • the configuration cache file.

There we go [y/n]? y

A very simple question: where is Hoa so?
> ▋

Si le système et les droits le permettent, le fichier Data/Core.link.php sera un lien symbolique au lieu d'être un fichier PHP comportant une instruction require (comportement par défaut).

Commandes dédiées à l'application

Nous avons vu que les scripts hoa et hoa.bat de Hoa sont très pratiques. Nous aimerions pouvoir en faire autant pour notre application, et qui plus est, avec des commandes personnalisées ! Nous remarquons que les scripts myapp et myapp.bat sont présents dans le dossier Data/Bin/. Ces scripts étendent les scripts hoa et hoa.bat de Hoa (nous retrouvons donc les mêmes commandes) et sont dédiés à notre application car ils la connaissent. Pour personnaliser notre application, il nous suffit de les renommer (nous utiliserons myapp dans tous les exemples). Libre à nous de placer ces scripts dans le $PATH par la suite.

$ Data/Bin/myapp
// Homescreen.
$ mv !! !!:s/myapp/gordonsapp
mv Data/Bin/myapp Data/Bin/gordonsapp
$ !!$
Data/Bin/gordonsapp
// Homescreen.

Pour se persuader de la différence entre hoa (dans Hoa) et myapp (dans notre application), il suffit de résoudre le chemin hoa://Data/. Le résultat attendu est n'importe où pour hoa (comme il ne connaît pas notre application), et le bon chemin pour myapp car il connaît notre application ; ainsi :

$ hoa protocol:resolve hoa://Data
// Somewhere, in a galaxy far, far away…
$ myapp protocol:resolve hoa://Data
hoa://Data is equivalent to:
~/Development/MyApp/Data/

Nous verrons plus tard comment écrire des commandes uniquement accessibles depuis notre application et pas depuis Hoa, tout comme écrire des bibliothèques réservées à notre application et non pas à Hoa (donc à toutes nos applications).

Tester l'application

L'application contient déjà un dossier Application/Public/ avec un fichier index.php. Nous allons le tester immédiatement. Si aucune erreur n'apparaît, c'est que tout est bien fonctionnel.

Nous pourrons exécuter notre index de cette manière :

$ php Application/Public/index.php
Hello you! I'm your first Hoa-based application \o/.

Toutes mes félicitations ! Vous avez installé Hoa et vous avez créé votre première application avec vos propres scripts !