Wiki - 1 output

Notifications

Welcome into the it.rocks framework wiki.

Connected user

Structure du projet et décryptage de l'application carnet d'adresses
add

Structure du projet et décryptage de l'application carnet d'adresses

Close

Nous aborderons ici quelques principes de base du framework it.rocks, en lien avec l’application exemple Carnet d’adresse.

Structure d’un projet it.rocks
Une fois votre projet initialisé par la commande php init.php nickname addresses , les fichiers et dossiers suivants, qui permettent au projet de s’exécuter, sont disponibles :
- Fichiers à la racine :
  - composer : les fichiers de configuration (.json), d’installation (.lock) et le logiciel de gestion de dépendances composer lui-même (.phar).
  - loc.php : ce fichier comporte les réglages locaux de votre application. Tenu en dehors de votre dépôt de versions, il vous permet de configurer des réglages propres à votre serveur de développement, de pré-production ou de production, bref tout réglage qui peut varier suivant l’environnement dans lequel est exécuté votre application.
  - pwd.php : le fichier comportant tous les mots de passes utilisés dans l’application. Les isoler dans ce fichier indépendant pourra permettre d’en centraliser le stockage et l’éventuel cryptage, et de le tenir en dehors de votre versionning (pwd.php est ignoré pour git dans le fichier .gitignore).
  - update : indique à it.rocks qu’une mise à jour du logiciel est à appliquer. Ce fichier vide appartenant à l’utilisateur www-data responsable de l’exécution du serveur web doit être créé à chaque mise à jour du logiciel, pour que it.rocks mette à jour les caches de l’application et tienne compte correctement de l’ensemble des dernières modifications. Il est purgé dès que la mise à jour est réalisée, après un clic dans l’application par exemple.
- Dossiers :
  - cache : contient les fichiers de cache de l’application, gérés par it.rocks. Peut être réinitialisé en en vidant le contenu et en créant le fichier flag update
  - itrocks/framework : La configuration standard et le code source du Framework et des modules proposés en standard.
  - nickname/addresses : C’est le dossier contenant votre application carnet d’adresses. Les fichiers de classes doivent être stockées dans le dossier correspondant à leur espace de nommage, démarrant forcément par Nickname\Addresses, comme c’est le cas de la classe application Nickname\Addresses\Application stockée dans le fichier nickname/addresses/Application.php
  - vendor : les modules logiciels développés par des tiers hors Framework it.rocks doivent être stockés ici. Lors de l’initialisation de votre projet, les logiciels tiers nécessaires au bon fonctionnement de it.rocks ont été téléchargés et installés ici. Utilisez le gestionnaire de dépendances composer pour gérer vos dépendances.
- Fichier launcher :
  - ../addresses.php Ce script est celui que vous devrez appeler, par exemple via http://localhost/addresses avec la configuration via Apache proposée dans notre tutoriel sous une installation standard sous Ubuntu / Apache. Il exécute en fait simplement itrocks/framework/index.php, il peut être adapté si vous stockez votre projet dans un autre dossier par exemple.
Fichiers de votre projet
- nickname/addresses/Application.php : la classe Application, même si elle est vide, est obligatoire pour que votre projet fonctionne.
- nickname/addresses/Address.php : votre classe métier permet de manipuler les données de votre application, ici une adresse.
- nickname/addresses/Application_home.html : ici un template HTML qui permet de modifier la page d’accueil. Ce fichier peut être supprimé pour afficher la page d’accueil par défaut.
- nickname/addresses/config.php : le fichier de configuration de votre application permet d’activer et configurer ses fonctionnalités : plugins, menus, etc.
Nommage des classes et des fichiers

it.rocks est un framework dédié à la programmation orientée objets. Toutes vos données, vos traitements, etc., seront à programmer sous forme d’objets.

En terme de convention de nommage, it.rocks propose de nommer vos classes avec un namespace identifiant son auteur et le projet dans laquelle elle est stockée, puis éventuellement le module, sous-module, etc.

Le nom complet (= avec son namespace) de la classe permet au Framework de la localiser pour la charger en mémoire automatiquement lorsque vous en avez besoin. Ainsi la classe Nickname\Addresses\Application, par exemple, est stockée dans le fichier nickname/addresses/Application.php. Il est important de procéder ainsi pour l’ensemble de vos classes, pour qu’elles soient retrouvées. De manière générale il a été choisi de nommer les dossiers entièrement en minuscules, et le fichier contenant la classe avec les majuscules au même endroit que dans le nom de la classe.

Décryptage du fichier de configuration addresses.php

Découpons ce fichier par sections :
```
<?php
namespace Nickname\Addresses;
```
La première ligne du fichier indique le namespace dans le quel se situe votre projet.
```
use ITRocks\Framework\Configuration;
use ITRocks\Framework\Dao;
use ITRocks\Framework\Dao\Mysql\Link;
use ITRocks\Framework\Plugin\Priority;
use ITRocks\Framework\Widget\Menu;
```
Viennent ensuite autant de clauses use que nécessaire, si vous souhaitez résumer l’accès aux classes dans ce fichier.
```
global $loc, $pwd;
require __DIR__ . '/../../loc.php';
require __DIR__ . '/../../pwd.php';
```
Ces lignes ne doivent pas être modifiées : elles permettent d’inclure le fichier de configuration locale et celui centralisant les mots de passes, utilisé dans votre configuration et celle des projets dont hérite votre projet.
```
require __DIR__ . '/../../itrocks/framework/config.php';
```
Assure que la configuration de it.rocks soit également chargée, votre projet se basant directement sur le framework.

Il faut noter qu’un projet développé avec it.rocks suit une logique d’héritage de projets comparable à l’héritage en programmation orientée objets. Si notre projet Nickname\Addresses héritait d’un autre projet, il faudrait inclure son fichier de configuration ici, à la place de 'itrocks/framework/config.php' .
```
$config['Nickname/Addresses'] = [
```
La configuration se voit ajoutée cette nouvelle section, correspondant à votre projet. Plusieurs configurations de plusieurs projets pouvant cohabiter, chacun est identifié de manière unique par le pseudonyme de son auteur et le nom du projet, pour en assurer là aussi l’unicité.
```
	Configuration::APP         => Application::class,
```
Indique quelle classe est la classe principale de l’application. Cette ligne doit rester inchangée, la classe référencée est bien entendu Nickname\Addresses\Application .
```
	Configuration::ENVIRONMENT => $loc[Configuration::ENVIRONMENT],
```
Permet d’indiquer que votre projet tourne en environnement de development, de test ou de production. Ce réglage dépendant de là où est installée votre application, la valeur est stockée dans le fichier non versionné loc.php.
```
	Configuration::EXTENDS_APP => 'ITRocks/Framework',
```
On indique ici de quelle application hérite votre application, dans le cas présent on hérite directement du framework it.rocks, on indique donc ici l’indice de sa configuration. En interne, pour établir la configuration de votre application, it.rocks cumulera par un merge récursif le tableau $config'ITRocks/Framework' et votre configuration $config'Nickname/Addresses' . Pour tout le reste de votre configuration, il est donc inutile de rappeler des réglages standard déjà effectués, comme on le verra ci-dessous.
```
	Priority::NORMAL => [
```
it.rocks a une architecture globalement basée sur l’inclusion de modules, ou plugins. On classe chaque plugin par priorité de chargement dans plusieurs sous-tableaux du fichier de configuration. Les priorités acceptées sont top_core, core, lowest, lower, low, normal, high, higher, highest , et permettront de classer les plugins les uns par rapport aux autres, ce qui est important pour résoudre les éventuels conflits que pourraient induire des plugins agissant sur les mêmes fonctionnalités du Framework.
Pour hériter la configuration d’un plugin déjà configuré dans l’application étendue, il est important de placer la configuration de ce plugin dans le même niveau que dans l’application parente. Ici on étendra la configuration du plugin Dao déjà activé dans la configuration de it.rocks, et on activera un nouveau plugin Menu . On ne touche pas à la configuration des autres plugins configurés dans itrocks/framework/config.php, ils seront donc chargés avec la configuration par défaut de it.rocks.

Côté connexion à la base de données : it.rocks utilise par défaut la classe de lien, qu’on appelle Data_Link, permettant de se connecter à une base de données MySQL locale en utilisant InnoDB. On peut accéder aux fonctions du lien principal aux données via les méthodes statiques de la classe Dao.
Les réglages sont dans itrocks/framework/config.php pour Dao, ils peuvent être cumulés où écrasés par ceux présent dans votre fichier de configuration nickname/addresses/config.php. Ici il n’est pas besoin de modifier les réglages par défaut.
```
		Menu::class => [
			Menu::TITLE => [SL, 'Home', '#main'],
			'Address book' => [
				'/Nickname/Addresses/Addresses' => 'Addresses'
			]
		]
```
Ici vient la configuration du menu de votre application, utilisant le widget Menu proposé en standard par it.rocks :
- Le premier élément doit être un Menu::TITLE associant un sous-tableau de trois éléments : le chemin d’accès de la fonctionnalité activée lorsqu’on clique sur le titre du menu, le texte du titre en lui-même, et l’id de l’élément HTML dans lequel on doit afficher le résultat de l’appel à la fonctionnalité. #main est l’id de la zone principale de l’application.
- Les éléments suivants sont des blocs de fonctionnalité. L’indice, comme Address book ici, est le titre de chaque bloc.
- Suit pour chaque bloc le sous-tableau contenant toutes les lignes de menu. Ici nous n’en avons qu’une seule : l’URI appelée /Nickname/Addresses/Addresses demande la liste des adresses en indice, la valeur comporte le titre de cette ligne de menu, tel qu’affiché.
Liens et appels des fonctionnalités de l’application

En résumé, les liens vers les fonctionnalités de votre application seront généralement sous la forme suivante : le chemin d’accès à la classe métier sur laquelle on travaille, identique au namespace au sens du slash près, le slash / étant plus adapté aux URI pour les liens internet que le backslach \ utilisé par PHP, suivi d’un slash et du nom de la fonctionnalité appelée, éventuellement précédé de l’identifiant de l’objet concerné. Quelques informations concernant cette URI :
- Le nom de classe peut être décliné au pluriel, comme c’est le cas de l’exemple. A défaut de pluriel définis clairement dans la classe (voir l’annotation @set), des règles basique de syntaxe anglo-saxonne sont utilisées par it.rocks pour “deviner” quel sera le singulier du nom de classe. Ici avec Nickname/Addresses/Addresses it.rocks détermine automatiquement que l’on veut voir la liste des Nickname\Addresses\Address disponibles.
- Ce nom de fonctionnalité peut être omis, la fonctionnalité par défaut sera alors appelée. C’est le cas dans l’exemple ici : on appelle simplement le nom d’une classe métier au pluriel, la fonctionnalité par défaut dataList, qui affiche une liste d’objets, correspondant à ce cas de figure est alors appelée.
  Quelques exemples d’appels disponibles en standard pour la classe Address :
  - /Nickname/Addresses/Addresses : la liste des adresses, le nom de la fonctionnalité n’étant pas précisé.
  - /Nickname/Addresses/Addresses/dataList : la liste des adresses, la fonctionnalité étant indiquée explicitement.
  - /Nickname/Addresses/Address/1 : affiche l’adresse avec le contrôleur de vue standard output .
  - /Nickname/Addresses/Address/1/output : aura un comportement identique, la fonctionnalité étant indiquée explicitement.
  - /Nickname/Addresses/Address/1/edit : affiche l’adresse dans son formulaire de modification standard edit .
  - /Nickname/Addresses/Address : affiche le formulaire de saisie d’une nouvelle adresse.
  - /Nickname/Addresses/Address/add : aura un comportement identique, la fonctionnalité étant indiquée explicitement.
Le but de ce mode de fonctionnement est qu’on puisse utiliser intuitivement les URI, et qu’elles indiquent au développeur et à l’utilisateur avancé où on se trouve. Ainsi it.rocks ne nécessite pas de configurer des “routes”, à l’instar de ce font d’autres framework tels que Symfony, privilégiant ainsi une standardisation des liens entre les fonctionnalités de votre logiciel, qui se veulent systématiquement explicites et conformes à la structure de l’application. Les routes sont implicites.

Bien sûr, vous verrez par la suite que ce comportement peut être modifié, comme beaucoup de comportements standard du Framework.

La classe Nickname\Addresses\Application

Le fichier de cette classe, conformément aux conventions de stockage des fichiers de classes, est nickname/addresses/Application.php.
```
<?php
namespace Nickname\Addresses;
 
use ITRocks\Framework;
 
/**
 * The addresses application
 */
class Application extends Framework\Application
{
 
}
```
Cette classe est obligatoire pour que votre application soit reconnue comme telle et fonctionne ici. On rappelle ici de quelle application la votre hérite, en l’occurrence directement de l’application Framework it.rocks.

Le template HTML Application_home.html

Une application it.rocks respecte en gros le modèle MVC. On sépare donc :
- les modèles : classes décrivant vos données, et donnant des informations sur leur lien avec leur stockage. Dans it.rocks on rendra indépendants les modèles de classes métier de leur stockage, mais on y décrira simplement leurs données et les règles de gestion à appliquer, certaines étant utilisées – entre autres – par les classes de liens avec les données pour prendre des décisions sur la manière de stocker les donneés en base.
- Les vues : décomposées dans it.rocks en :
  - un moteur de vue d’une part – le principal permettant la visualisation en HTML, d’autres moteurs pouvant être utilisés pour d’autres formats de visualisation tels que des fichiers PDF ou Excel par exemple -,
  - les classes de vues préparant les données pour la visualisation et appelant le moteur de template, qui utilise le template de vue HTML,
  - les templates de vue HTML proposent la maquette de la vue finale indiquant au moteur où placer les données préparées.
- Les contrôleurs : ces classes décodent les données envoyées par l’utilisateur en entrée, appellent les lectures et écritures de données, calculs et autre processus, et enfin exécutent la vue résultante à renvoyer à l’utilisateur.
Pour l’application on considérera donc que la classe Application est le modèle.
Aucun contrôleur pour la fonctionnalité home n’ayant été développé, c’est le contrôleur par défaut qui est appelé notamment pour afficher la page d’accueil principale de l’application.

Le fichier Application_home.html contient par contre un template où l’on a personnalisé l’écran d’accueil, sur la base des données envoyées par la vue par défaut, à savoir l’objet application principale.
```

 
	Hello, world !
 

```
Le balisage BEGIN END indique au moteur de template que seul le contenu à l’intérieur de ces balises va être envoyé au navigateur. S’agissant de la page d’accueil, première page de l’application, le template contenant principal fourni par it.rocks, le fichier itrocks/framework/main.html, va être utilisé comme cadre. C’est donc ce main.html qui est affiché à l’écran, dans lequel la donnée content est remplacée par le contenu entre BEGIN et END de Application_home.html.

Ce principe permet de ne maintenir qu’à un seul endroit – dans main.html – l’entête et le pied des pages HTML constituant votre application, tant qu’ils restent identiques.

La classe métier Nickname\Addresses\Address

Cette classe, stockée dans le fichier nickname/addresses/Address.php, décrit les données dont sont composées un objet adresse.
```
namespace Nickname\Addresses;
```
Comme pour toutes les classes de votre application, le script PHP commence par le namespace où elle est stockée, ici dans le namespace racine de votre application Nickname\Addresses .
```
/**
 * This stores contact information and address
 *
 * @business
 * @representative first_name, last_name
 */
class Address
{
```
Il est de bon ton de bien documenter vos classes. Les annotations pour phpDocumentor sont les bienvenues. it.rocks dispose de plus d’un système intégré de gestion d’annotations, dont de nombreuses permettent de définir des règles de gestion de vos classes qui seront interprétées et utilisées à l’exécution du logiciel.
Par exemple ici l’annotation @representative permet d’établir la liste des propriétés de la classe dont les valeurs seront considérées comme représentatives de l’objet, donc aidant à son identification.
Ainsi vous remarquerez si vous affichez la liste des adresses dans l’application que seules les colonnes first name et last name sont affichées. Le contrôleur de vue dataList par défaut de it.rocks a utilisé l’annotation @representative pour limiter le nombre de colonnes affichées si l’utilisateur n’a pas personnalisé sa sélection.
L’annotation @business indique qu’il s’agit là d’une classe métier, dans le sens que les données vont être stockées dans la base de données principale.
```
	/**
	 * @var string
	 */
	public $first_name;
```
Pour les premières propriétés first_name et last_name de votre adresse, on utilise une annotation phpDocumentor classique, @var, qui précise le type de donnée à stocker dans la propriété, ici string pour une chaîne de caractères. Cette annotation est également communément utilisée par les IDE tels que Eclipse PDT ou PhpStorm pour aider au développement. Elle est également utilisée par l’ORM it.rocks pour générer automatiquement la structure de base de données nécessaire au stockage correct de votre donnée. Ainsi, avec les seules informations contenues dans votre classe Address et ses annotations, une table addresses sera créée comportant les champs correspondant aux propriétés. Le type string supporte une chaîne jusqu’à 255 caractères.
```
	/**
	 * @multiline
	 * @var string
	 */
	public $address;
```
Une autre annotation ici, @multiline, précise que l’utilisateur pourra saisir plusieurs lignes pour la propriété address . Si cette annotation ne change cette fois-ci rien à la façon de stocker la donnée en base – ce sera toujours une chaîne jusqu’à 255 caractères – les moteurs de vues sauront par contre que cette donnée peut s’afficher ou se saisir sur plusieurs lignes. Ainsi en HTML le champs de saisie de cette propriété sera un élément TEXTAREA à la place d’un INPUT pour une propriété qui n’aurait pas cette annotation.
```
	/**
	 * This is mandatory for all business objects, always get a view as string
	 *
	 * @return string
	 */
	public function __toString()
	{
		return trim($this->first_name . SP . $this->last_name);
	}
```
La méthode magique __toString de PHP doit absolument être précisée, car elle est souvent utilisée par les moteurs de templates qui génèreraient une erreur sans sa présence. On reprend souvent ici les champs de l’annotation @representative, pour décrire comment représenter un objet dans les vues, à destination des utilisateurs. Ici on affiche le prénom et le nom, séparés d’un espace si les deux sont bien renseignés.

Note : le but de it.rocks étant de limiter la saisie de code redondant ou inutile, l’implémentation systématique de __toString sera abandonnée à l’avenir au profit d’un fonctionnement standard par défaut, qui devrait satisfaire la plupart des cas par une présentation identique à celle implémentée explicitement ici pour la classe Address.

Pour poursuivre

Pour poursuivre cette prise en main de it.rocks par l’exemple, vous pouvez aller au chapitre suivant :
Développement de votre deuxième application : une base de données de films

Vous pouvez également creuser en détail l’ensemble des fonctionnalités disponibles dans it.rocks, pour en savoir plus notamment sur celles abordées ici, dans le Manuel de référence.