Une mise-à-jour est prévue le 9 juillet entre 13:00 et 14:00. Le service sera inaccessible ou instable pendant cette période. Merci de votre compréhension.

README.md 4.39 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
Bundle PlantUML
===============

Ce bundle permet de générer des diagrammes de classe à partir des sources d'une application PHP.

Il utilise à la fois l'[API de Reflection de PHP](http://php.net/manual/fr/book.reflection.php) et les métadonnées
de [Doctrine ORM](http://www.doctrine-project.org/projects/orm.html).

Le rendu se fait avec [PlantUML](http://plantuml.com/).

Installation
============

Installer le package via composer :

    composer require --dev irstea/plantuml-bundle

Lister le bundle dans le kernel de Symfony :

    // bundles en environnement dev et test
    if (in_array($this->getEnvironment(), array('dev', 'test'))) {
        // ...
        $bundles[] = new Irstea\PlantUmlBundle\IrsteaPlantUmlBundle();
        // ...
    }

Les dépendances sont dans les dépôts standards de Debian :

    sudo apt-get install default-jre-headless

PlantUML peut se télécharger depuis leur site web.

Principe
========

Le bundle permet de générer plusieurs graphes différents, c-à-d plusieurs vues différentes des modèles. Il faut décrire
ces vues dans la configuration.

Pour chaque graphe, le bundle par d'une collection de classe de départ, qu'il va analyser, regrouper et décorer.
Certains décorateurs permet de "découvrir" nouvelles classes, par exemple par héritage, associations, ...

Pour chaque vue, il faut définir :
* comment trouver les classes de départ,
* quelles classes tracer et comment les regrouper,
* quelles classes décorer.

Cela correspondent respectiviement aux sections `sources`, `layout` et `decoration` de la configuration de chaque graphe.

Sources
-------

Il y a deux façons de trouver les classes à tracer :
* `entities` : utilise les entités trouvées par le manager désigné par `entity_manager`.
* `classes` : charge toutes les classes trouvées dans les répertoires listés par `directories`.

Les sections `include`ou `exclude` permettent de raffiner la sélection.

Layout
------

Le paramètre `namespaces` permet choisir quel style de namespace doit être utiliser  .
* `php`: utilise les namespaces PHP.
* `flat`:  n'utilise pas de namespaces.
* `bundles`: regroupe les classes par bundle Symfony.
* `entities`: regroupe les classes par "alias" Doctrine.

Les sections `include`ou `exclude` permettent de filtrer quelles classes seront filtrées et parcourues.

Décoration
----------

La décoration consiste à afficher des informations sur chacune des classes. Certains décorateur ajoutent des informations
dans la classe, d'autres ajoutent des liens avec d'autres classes. Sans décorateur, chaque classe ne serait qu'une boîte
avec un nom, et rien d'autre.

Les décorateurs suivants sont basés sur la Reflection du PHP :

* inheritance : affiche les liens d'héritage de classe.
* traits : affiche les liens d'utilisation de trait.
* interfaces : affiche les liens d'implémentation d'interface.
* attributes : liste les attributs.
* methods : liste les méthodes.

Les décorateurs suivants sont basés sur les métadonnées Doctrine ; ils sont ignorés si la classe n'est pas une entité :

* entity : affiche le type d'entité.
* associations : affiche les associations d'entités.
* fields : affiche les définitions des champs (=colonnes) de l'entité.

Les sections `include`ou `exclude` permettent de filtrer quelles classes seront décorées.

Fonctionnement include/exclude
------------------------------

Les 3 sections peuvent contenir des sections `include` et `exclude`, qui permet de filter les classes par namespace ou répertoire.
Les filtres s'appliquent aux répertoires/namespaces et tous leurs sous-niveaux.

Le fonctionnement est le suivant :
* les sections vides ou absentes n'ont absolument aucun effet.
* S'il y a une section `include`, seuls les répertoires/namespaces listés seront acceptés.
* S'il y a une section `exclude`, les répertoires/namespaces listés seront ignorés.
* Si les deux sections sont présentes, une classe est acceptée si elle est validé par `include` *ET* qu'elle n'est pas ignoré par un `exclude`.

Usage
=====

Génération du source du diagramme
---------------------------------

La génération se fait par un seule commande, qui pour l'instant ne fait qu'envoyer un fichier sur la sortie standard:

    app/console irstea:plantuml:generate mongraph >mongraph.puml

Rendu graphique
---------------

Le rendu graphique se fait avec PlantUML, par exemple, pour générer un SVG :

Raidelet Nicolas's avatar
Raidelet Nicolas committed
119
    app/console irstea:plantuml:render -o output_dir mongraph