CakePHP, les conventions de nommage

Cet article aborde les conventions de nommage de la version 1.x de CakePHP !

Ce billet est le premier d’une série qui abordera quelques unes des spécificités et des fonctionnalités du framework que nous avons choisi d’utiliser pour la création d’Opencomp : CakePHP.

Nous allons parler aujourd’hui des conventions de nommage de CakePHP. En effet, comme CakePHP suit le modèle MVC, un certain nombre de règles doivent être respectées pour que le framework puisse trouver les différents fichiers qui composent un module. Ces différents fichiers vont donc devoir adopter certaines conventions de nommage.

Les conventions : d’une manière générale

L’ensemble des noms de classes sont CamelCased, cela signifie que les espaces sont supprimés et que chaque lettre débutant un mot est inscrite en majuscules. Par exemple, la classe « Ma belle classe » s’écrirait MaBelleClasse.

Pour les noms de fichiers, cela diffère légèrement. Les espaces sont pris en compte et sont remplacés par des underscores (_) et tout est inscrit en minuscules. Par exemple « Mon joli modèle » donnera une fois transformé en nom de fichier mon_joli_modele.php.

Attention, il ne faut pas utiliser d’accents, ni dans les noms de classes, ni dans les noms de fichiers !

Les conventions : de façon plus spécifique

Les modèles

Les noms des classes modèles s’inscrivent toujours au singulier. Ainsi si on a un module cheval, on aura le fichier de modèle horse.php minimal suivant.

class Horse extends AppModel
{
    var $name = 'Horse';

    //Vous taperez ici la logique ayant trait au traitement des données
    //Les vérifications avant l'enregistrement en base de données par exemple
}

Les contrôleurs

Les noms des fichiers de contrôleurs doivent toujours être au pluriel et se terminer par _controller.php. De plus, comme CakePHP est un framework anglais, je vous recommande de donner des noms anglais à vos classes car par exemple, le modèle chevaux_controller.php ne sera pas reconnu par CakePHP qui attendra chevals_controller.php. Preférez donc dans cet exemple précis horses_controller.php.

Un contrôleur contiendra différentes méthodes, c’est à dire différentes actions qui pourront être exécutées pour un même module. Si nous continuons avec notre exemple. Nous pouvons vouloir ajouter de nouveaux chevaux dans notre base de données, modifier, supprimer ou encore consulter la liste des chevaux existants. Il va donc falloir créer différentes méthodes. Par exemple, vous pourrez avoir les méthodes index(), ajouterNouveau(), modifier() et supprimer() dans votre contrôleur horses_controller.php, qui aura alors l’aspect suivant :

class HorsesController extends AppController
{
    //Cette ligne n'est pas obligatoire, mais elle permet d'améliorer
    //la compatibilité avec les version anciennes de PHP.
    var $name = 'Horses';

    function index() 
    {
        //On placera ici la logique permettant de consulter
        //la liste des chevaux dans la base de données

        //La méthode index() est appelée lorsque l'utilisateur
        //accède au module sans demander une méthode particulière.  
    }

    function ajouterNouveau() 
    {
        //On placera ici la logique permettant d'ajouter
        //un nouveau cheval dans la base de données 
    }

    function modifier() 
    {
        //On placera ici la logique permettant de modifier
        //un cheval existant dans la base de données    
    }

    function supprimer() 
    {
        //On placera ici la logique permettant de supprimer
        //un cheval de la base de données   
    }
}

Les vues

Comme vous pouvez avoir différentes vues pour un même module (ajout, modification, suppression, listage), vous devez tout d’abord créer un répertoire qui contiendra ces différentes vues dans app/views/. La encore, le nom du dossier doit être au pluriel. Ainsi, pour reprendre l’exemple précédent, vous devrez nommer le dossier de vues relatives au module horse de la même manière que le contrôleur, c’est à dire au pluriel : horses.
Vous aurez donc app/views/horses/.

Ensuite, comme vous pouvez avoir plusieurs méthodes dans un même contrôleur, vous pouvez créer les vues de ces différentes méthodes en créant un fichier du même nom que la méthode en y ajoutant .ctp dans le dossier app/views/<nom du module>/.

Là encore, les noms de fichiers sont en minuscules, sans accents et les espaces sont remplacés par des underscores.

Si vous avez les méthodes index(), ajouterNouveau(), modifier() et supprimer() dans votre contrôleur horses_controller.php, vous aurez alors la structure suivante :

app/views/horses/index.ctp
app/views/horses/ajouter_nouveau.ctp
app/views/horses/modifier.ctp
app/views/horses/supprimer.ctp

Récapitulons !

J’en ai sans doute perdu plus d’un en route et un petit récap sur ces histoires de conventions ne ferrait pas de mal !
Voici donc un tableau récapitulatif toujours par rapport à notre exemple avec les chevaux :