Conventions

Afin de pérenniser EtuUTT et de pouvoir garder ce projet sain et propre, il faut que chaque développeur ayant l'occasion de modifier le code le fasse comme tous les précédents.

Pour cela, il existe des normes et des conventions d'organisation, de codage et de mise en place pour essayer d'uniformiser les manières de développer.

Le code et PHP-FIG

PHP-FIG est l'abbréviation de PHP Framework Interop Group (http://www.php-fig.org), un groupe de développeurs qui a voulu amener dans le monde de PHP des conventions de codages que chacun pourra utiliser.

Ces conventions sont appelées les PSR. Il en existe quatres, de plus en plus contraignantes :

- PSR-0 : Autoloading Standard
- PSR-1 : Basic coding standard
- PSR-2 : Coding Style Guide
- PSR-3 : Logger interface

Chacune des convention hérite des contraintes de la précédente et en ajoute.

Symfony suit la convetion PSR-2 au moment où j'écris ces lignes (avril 2013). PSR-3 n'étant pas spécialement utile à EtuUTT, nous nous contenterons de PSR-2.

En d'autres mots, il y a trois conventions que vous devez suivre :

• https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
• https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
• https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

Ces conventions sont nécessaires à la bonne conduite du projet, essayez de les suivre le plus possible.

Les modules et les bundles

Création

Etant donné que les modules seront normalement créés grâce à la ligne de commande, il n'y a a priori pas de convention précise quant à leur développement. Cependant, si vous souhaitez créer un module à la main, le meilleur moyen est de copier un module déjà existant et de modifier ses namespaces et ses classes pour ne rien oublier.

Organisation

La convention de Symfony nous propose de ne rien mettre mise à part la classe de base dans le dossier racine du bundle. Les dossiers et les namespaces nous aidant beaucoup pour cela, il faut suivre cette convention.

- Les contrôleurs sont stockées dans ``Controller``
- Les extensions du conteneur de services sont stockées dans ``DependencyInjection``
- Les entités sont stockées dans ``Entity``
- Les vues sont stockées dans ``Resources/views``
- La documentation est stockée dans ``Resources/doc``
- La configuration est stockée dans ``Resources/config``
- Les traductions sont stockées dans ``Resources/translations``
- Les extensions Twig sont stockées dans ``Twig`` et sont suffixées de ``Extension``
- Les traductions sont stockées dans ``Resources/translations``
- Les commandes sont stockées dans ``Command``
- Les types de champs de formulaires sont stockés dans ``Form``
- Les classes outils (classes généralistes utiles partout) sont stockés dans ``Util``
- Les helpers de notifications (classes d'affichages de notifications, cf 3.) sont stockées dans ``Notification/Helper``
- Les listeners sont stockées dans ``Listener``
- Les tests sont stockés dans ``Tests`` et suffixés de Test.php

Ensuite, si vous avez des éléments ne correspondant pas à cette liste, n'hésitez pas à créer un dossier plus spécifique (par exemple, il existe Imap, Ldap, ... dans le EtuUserBundle).

Les entités

Les entités correspondent à des tables dans la base de donnée. Or, pour s'organiser le mieux possible, il est de bonne augure de donner des noms évocateurs à ces tables.

Pour cela, une convention existe : prenez le nom de l'entité au pluriel, mettez la en minuscule et avec des underscores pour séparer les mots et préfixez-lui "etu_". Par exemple : Issue devient etu_issues.

Pour les entités dépendantes en relation OneToMany à d'autres entités, il faut là aussi préfixer le nom de l'entité pour montrer le lien entre les tables. Ici, par exemple, un commentaire sur un bug correspond à un lien OneToMany entre Issue et Comment. L'entité Comment aura donc pour nom de table etu_issues_comments.

Note : Pour modifier les nom des tables créées, utilisez les annotations :

.. code:: php

namespace Acme\DemoBundle\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Table(name="table_name")
 * @ORM\Entity
 */
class Entity
{
    // ...
}