Merge branch 'master' of https://git.unicaen.fr/lib/unicaen/code

doc/Documentation.md

+# UnicaenCode
+
+## Description
+
+UnicaenCode est un module de la biliothèque Unicaen, dédiée au
+développement avec le Zend Framework 2+. Le module est intégré à la
+[Zend Developer Toolbar](/develop/zend-debug), qu'il conviendra
+d'installer préalablement pour un usage optimal 8-).
+
+Son but est de fournir un ensemble de services facilitant le
+développement d'applications. Parmis ces outils :
+
+  - la coloration syntaxique de code source affichée sur une page HTML, 
+  - des mécanismes avancés d'introspection de code source, 
+  - un système de templates permettant d'auto-générer des fichiers de
+    code source dont l'écriture est rébarbative (certains traits,
+    interfaces, etc.).
+  - Enfin, UnicaenCode propose un système de bac à sable où, au sein de
+    son application, on peut exécuter des morceaux de code pour tester
+    diverses fonctionnalités.
+
+## Installation
+
+Sa placer à la racine du projet, puis utiliser composer pour installer
+le plugin :
+
+    composer require-dev unicaen/unicaen-code:dev-trunk
+
+\<note tip\> Le fichier `composer.json` sera mis à jour et le plugin
+sera téléchargé dans le dossier `vendor/`. \</note\>
+
+UnicaenCode est destiné au développement d'application et n'a pas
+vocation à être déployé sur un serveur de production. Aussi, plutôt que
+de simplement déclarer le module, il est préférable de faire comme suit
+:
+
+Dans le fichier de configuration de l'application
+(`application.config.php`), ajouter
+
+``` php
+$env = getenv('APP_ENV') ?: 'production';
+if ( 'development' == $env ) {
+    $modules[] = 'UnicaenCode';
+}
+```
+
+Ainsi, le module ne sera lancé que si l'application est sur un serveur
+de développement. Pour rappel, la variable APP\_ENV se configure dans le
+fichier *.htaccess* ou bien dans le *virtualHost* correspondant à votre
+application (`SetEnv "APP_ENV" "development"`).
+
+Enfin, vous devrez créer deux répertoires dans votre projet :
+
+  - un au même niveau que config, vendor, module, public, etc qui
+    s'appellera `code` 
+  - et son sous-répertoire `template`
+
+\<WRAP center round tip 80%\> Vous pouvez très bien positionner ces
+répertoires ailleurs. Il faudra dans ce cas positionner un fichier
+`unicaen-code.global.php` dans `config/autoload` doté du contenu suivant
+:
+
+``` php
+if (defined('APPLICATION_PATH')){
+    $settings = [
+        'view-dirs'     => [APPLICATION_PATH . '/code'],
+        'template-dirs' => [APPLICATION_PATH . '/code/template'],
+        'generator-output-dir' => '/tmp/UnicaenCode',
+        'namespaces'           => [
+             'services'  => [
+                'Application\Service',
+             ],
+             'forms'     => [
+                'Application\Form',
+             ],
+             'hydrators' => [
+                'Application\Hydrator',
+             ],
+             'entities'  => [
+                'Application\Entity\Db',
+             ],
+        ],
+    ];
+}else{
+    $settings = [];
+}
+
+return [
+    'unicaen-code' => $settings,
+];
+```
+
+Tout est personnalisable. Par exemple, si tous vos services n'ont pas
+pour namespace Application\\Service, vous pouvez ajouter d'autres
+namespaces (par exemple Import\\Service si vous avez des services dans
+un autre module qu'Application appelé Import) et ainsi de suite.
+\</WRAP\>
+
+\<WRAP center round alert 80%\> Assurez-vous bien que la constante
+globale `APPLICATION_PATH` a bien été définie comme suit dans votre
+fichier `/public/index.php` :
+
+`define('APPLICATION_PATH', realpath(__DIR__ . "/.."));` \</WRAP\>
+
+# Utilisation
+
+## Mode Bac à sable
+
+Le mode Bac à sable permet d'exécuter de tester des fonctionnalités en
+cours de développement. Concrètement, il suffit d'ajouter un fichier php
+au répertoire `/code` (cf. paramètre `view-dir` de la configuration).
+
+Ce fichier est une vue qui sera accessible via le menu Unicaen de la
+Developer Toolbar : ![](/develop/unicaen2/zdt-uc.png)
+
+### Variables
+
+Dans ces scripts qui sont en fait des vues du modèle MVC, certaines
+variables présentées par le bloc de phpDoc suivant :
+
+``` php
+/**
+ * @var $this \Zend\View\Renderer\PhpRenderer
+ * @var $controller \Zend\Mvc\Controller\AbstractController
+ * @var $viewName string
+ */
+```
+
+\<WRAP center round tip 80%\> Ce bloc pourra être écrit en entête de
+chaque fichier pour que l'auto-complétion soit activée... \</WRAP\>
+
+## Util
+
+La classe `Util` comporte un certains nombre de méthodes statiques
+permettant de réaliser, entres autres, les opérations suivantes :
+
+### Util::sqlLog($display=true)
+
+A partir de l'éxécution de cette méthode, toutes les requêtes SQL
+exécutées par Doctrine sont comptabilisées et affichées si désiré.
+Cela permet, par exemple, de connaître le nombre de requêtes générées
+afin de les réduire ou les optimiser.
+
+### Util::sqlCount
+
+permet d'afficher le nombre de requêtes exécutées depuis l'appel à
+sqlLog.
+
+### Util::\*Dump (\* = php, sql, css, javascript, html ou xml)
+
+permet d'afficher avec coloration syntaxique du code transmis sous forme
+de chaîne de caractères.
+
+\<WRAP center round tip 80%\> Petit bonus : le SQL est également indenté
+car Doctrine génère des requêtes mono-lignes. De plus, sqlDump accepte
+un `Doctrine\ORM\QueryBuilder` comme paramètre d'entrée\!\! \</WRAP\>
+
+### Util::varDump
+
+est une variante de var\_dump, à ceci prêt qu'elle affiche les objets de
+manière moins verbeuse.
+
+## Introspection
+
+Le service d'introspection est accessible de la manière suivante :
+
+``` php
+$sIntrospection = $controller->getServiceLocator()->get('UnicaenCode\Introspection');
+/* @var $sIntrospection \UnicaenCode\Service\Introspection */
+```
+
+Il permet de lister les services d'un projet selon certains critères
+ainsi que les entités Doctrine.
+
+## Générateur de code
+
+Le générateur de code est accessible de la manière suivante :
+
+``` php
+$sCodeGenerator = $controller->getServiceLocator()->get('UnicaenCode\CodeGenerator');
+/* @var $sCodeGenerator \UnicaenCode\Service\CodeGenerator */
+```
+
+Il permet de générer du code à partir de patron (templates) disponibles
+dans le dossier `/code/template`.
+
+On peut ainsi dire au générateur d'utiliser un patron particulier, puis
+on lui passe les paramètres nécessaires. Enfin, le générateur pourra
+sortir
+
+  - soit une chaîne de caractères pour, par exemple, l'afficher au moyen
+    d'un `Util::phpDump`, 
+  - soit directement l'enregistrer sur le disque dur de votre machine.
+
+Voici un exemple de template qui permet de générer un trait d'accès à
+une entité dans un objet, avec sa propriété et ses accesseurs:
+
+``` php
+<?php
+
+namespace Application\Traits;
+
+use <entityPath>\<entityClass>;
+
+/**
+ * Description of <entityClass>AwareTrait
+ *
+ * @author Laurent LÉCLUSE <laurent.lecluse at unicaen.fr>
+ */
+trait <entityClass>AwareTrait
+{
+    /**
+     * @var <entityClass>
+     */
+    protected $<entityParam>;
+
+    /**
+     * @param <entityClass> $<entityParam>
+     * @return self
+     */
+    public function set<entityClass>(<entityClass> $<entityParam> = null)
+    {
+        $this-><entityParam> = $<entityParam>;
+
+        return $this;
+    }
+
+    /**
+     * @return <entityClass>
+     */
+    public function get<entityClass>()
+    {
+        return $this-><entityParam>;
+    }
+}
+```
+
+Vous noterez que les paramètres sont écris de la manière suivante :
+`<parametre>`.
+
+Et voici le code, placé par exemple dans un script du bac-à-sable, qui
+permet de générer les traits de toutes les entités Doctrine du projet et
+de les enregistrer dans `/tmp/entityTraits`:
+
+``` php
+<h1>Génération des aware traits de getters/setters d'entités</h1>
+<?php
+
+use UnicaenCode\Util;
+
+$outputdir = '/tmp/entityTraits/';
+
+$sIntrospection = $controller->getServiceLocator()->get('UnicaenCode\Introspection');
+/* @var $sIntrospection \UnicaenCode\Service\Introspection */
+
+$sCodeGenerator = $controller->getServiceLocator()->get('UnicaenCode\CodeGenerator');
+/* @var $sCodeGenerator \UnicaenCode\Service\CodeGenerator */
+
+$entities = $sIntrospection->getEntities();
+
+$sCodeGenerator->setTemplate('EntityTrait');
+foreach( $entities as $entity ){
+
+    $entityPath  = Util::namespaceClass($entity);
+    $entityClass = Util::baseClassName($entity);
+    $entityParam = lcfirst($entityClass);
+
+    $sCodeGenerator->setParams( compact('entityPath', 'entityClass', 'entityParam') );
+    $sCodeGenerator->generateToFile($outputdir, $entityClass.'AwareTrait.php');
+}
+?>
+Résultats dans <b><?php echo $outputdir ?></b>
+```