Vous êtes sur la page 1sur 1137

CakePHP Cookbook Documentation

Version 2.x

Cake Software Foundation

01 April 2016

Table des matires

Pour Commencer
1
Tutoriel dun Blog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Blog Tutoriel - Ajouter la logique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Installation
Conditions requises . . . . . . . . . .
Licence . . . . . . . . . . . . . . . .
Tlcharger CakePHP . . . . . . . . .
Permissions . . . . . . . . . . . . . .
Configuration . . . . . . . . . . . . .
Dveloppement . . . . . . . . . . . .
Production . . . . . . . . . . . . . . .
Installation avance et URL Rewriting
A vous de jouer ! . . . . . . . . . . .

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

31
31
31
32
32
32
33
34
34
43

Dbuter avec CakePHP


45
Quest ce que CakePHP ? Pourquoi lUtiliser ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Comprendre le systme M-V-C (Model-View-Controller) . . . . . . . . . . . . . . . . . . . . . . 46
O obtenir de laide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Controllers (Contrleurs)
Le Controller App . . . . . . . .
Les paramtres de requte . . . .
Les Actions du Controller . . . .
Request Life-cycle callbacks . .
Les Mthodes du Controller . . .
Les attributs du Controller . . .
En savoir plus sur les controllers

Views (Vues)

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

51
51
52
52
54
54
62
64
87
i

Templates de Vues . . . . . . .
Utiliser les Blocs de Vues . . . .
Layouts . . . . . . . . . . . . .
Elements . . . . . . . . . . . . .
Crer vos propres classes de vue
API de View . . . . . . . . . . .
En savoir plus sur les vues . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

87
89
92
94
97
97
100

Models (Modles)
205
Comprendre les Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Pour en savoir plus sur les Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Librairies du Coeur
Usage Gnral . . . . . . . .
Behaviors (Comportements)
Components (Composants) .
Helpers (Assistants) . . . . .
Utilitaires . . . . . . . . . .

.
.
.
.
.

345
345
504
533
587
682

Plugins
Comment Installer des Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comment Utiliser des Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comment Crer des Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

799
799
801
803

Shells, Tasks & Outils de Console


La console de CakePHP . . . . . . . . . . . .
Crer un Shell . . . . . . . . . . . . . . . . .
Les tches Shell . . . . . . . . . . . . . . . .
Invoquer dautres shells partir de votre shell
Niveaux de sortie de la Console . . . . . . . .
Style de sortie . . . . . . . . . . . . . . . . .
Configurer les options et gnrer de laide . .
Routing dans shells / CLI . . . . . . . . . . .
API de Shell . . . . . . . . . . . . . . . . . .
Plus de sujets . . . . . . . . . . . . . . . . .

10 Dveloppement
Configuration . . . .
Routing . . . . . . .
Sessions . . . . . . .
Exceptions . . . . . .
Gestion des Erreurs .
Debugger . . . . . .
Testing . . . . . . . .
REST . . . . . . . .
Filtres du Dispatcher

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

809
809
811
813
814
814
815
816
823
824
827

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

849
849
863
881
887
895
897
900
925
929

11 Dploiement
935
Vrifier votre scurit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
ii

Dfinir le document root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935


Mise jour de core.php . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
Amliorer les performances de votre application . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
12 Authentification Simple et Autorisation de lApplication
Crer le code li de tous les users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Authentification (Connexion et Deconnexion) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Autorisation (Qui est autoris accder quoi) . . . . . . . . . . . . . . . . . . . . . . . . . . .

937
937
940
942

13 Application Simple contrle par Acl


Prparer notre Application . . . . . . . .
Prparer lajout dAuth . . . . . . . . . .
Initialiser les tables Acl dans la BdD . . .
Agir comme un requteur . . . . . . . . .
Crer les ACOs (Access Control Objects)

.
.
.
.
.

945
945
947
949
949
951

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

14 Application Simple contrle par Acl - partie 2


Un outil automatique pour la cration des ACOs .
Configurer les permissions . . . . . . . . . . . .
Connexion . . . . . . . . . . . . . . . . . . . . .
Dconnexion . . . . . . . . . . . . . . . . . . .
Cest fini ! . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

953
953
954
955
956
956

15 Tutoriels et exemples
Tutoriel dun Blog . . . . . . . . . . . . . . . . . . . . .
Blog Tutoriel - Ajouter la logique . . . . . . . . . . . . .
Authentification Simple et Autorisation de lApplication
Application Simple contrle par Acl . . . . . . . . . . .
Application Simple contrle par Acl - partie 2 . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

957
957
966
978
986
993

16 Contribuer
Documentation . . . . . . . . . . . . . .
Tickets . . . . . . . . . . . . . . . . . . .
Code . . . . . . . . . . . . . . . . . . . .
Normes de codes . . . . . . . . . . . . .
Guide de Compatibilit Rtroactive . . . .
Le processus de dveloppement CakePHP

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

997
997
1006
1006
1009
1020
1023

17 Annexes
2.8 Guide de Migration . . . . . . . .
2.7 Guide de Migration . . . . . . . .
2.6 Guide de Migration . . . . . . . .
2.5 Guide de Migration . . . . . . . .
2.4 Guide de Migration . . . . . . . .
2.3 Guide de Migration . . . . . . . .
2.2 Guide de Migration . . . . . . . .
2.1 Guide de Migration . . . . . . . .
2.0 Guide de Migration . . . . . . . .
Migration de la version 1.2 vers la 1.3

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

1025
. 1025
. 1027
. 1029
. 1032
. 1037
. 1043
. 1050
. 1056
. 1067
. 1099

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

iii

Informations gnrales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117


18 Indices et tables

1119

Index

1121

iv

CHAPITRE 1

Pour Commencer

Le framework CakePHP fournit une base robuste pour votre application. Il peut grer tous les aspects, de
la requte initiale de lutilisateur et son cheminement jusquau rendu final de la page web. Et puisque le
framework suit les principes du MVC, il vous permet de facilement personnaliser et offre la plupart des
aspects de votre application.
Le framework fournit aussi une structure organisationnelle basique, des noms de fichier jusquaux noms
des tables de la base de donnes, en gardant toute votre application cohrente et logique. Ce concept est
simple mais puissant. Suivez les conventions et vous saurez toujours exactement o les choses se trouvent
et comment elles sont organises.
La meilleure faon de dcouvrir et dapprendre CakePHP est de sassoir et de construire quelque chose.
Pour commencer, nous construirons une application simple de blog.

Tutoriel dun Blog


Bienvenue sur CakePHP. Vous consultez probablement ce tutoriel parce que vous voulez en apprendre plus
propos du fonctionnement de CakePHP. Cest notre but damliorer la productivit et de rendre le dveloppement plus agrable : nous esprons que vous le dcouvrirez au fur et mesure que vous plongerez dans le
code.
Ce tutoriel vous accompagnera travers la cration dune simple application de blog. Nous rcuprerons et
installerons CakePHP, crerons et configurerons une base de donnes et ajouterons suffisamment de logique
applicative pour lister, ajouter, diter et supprimer des posts.
Voici ce dont vous aurez besoin :
1. Un serveur web fonctionnel. Nous supposerons que vous utilisez Apache, bien que les instructions
pour utiliser dautres serveurs doivent tre assez semblables. Nous aurons peut-tre besoin de jouer un
peu sur la configuration du serveur, mais la plupart des personnes peuvent faire fonctionner CakePHP
sans aucune configuration pralable.
2. Un serveur de base de donnes. Dans ce tutoriel, nous utiliserons MySQL. Vous aurez besoin dun
minimum de connaissance en SQL afin de crer une base de donnes : CakePHP prendra les rnes
partir de l.
1

CakePHP Cookbook Documentation, Version 2.x

3. Des connaissances de base en PHP. Plus vous aurez dexprience en programmation orient objet,
mieux ce sera ; mais nayez crainte, mme si vous tes adepte de la programmation procdurale.
4. Enfin, vous aurez besoin de connaissances de base propos du motif de conception MVC. Un bref
aperu de ce motif dans le chapitre Comprendre le systme M-V-C (Model-View-Controller). Ne vous
inquitez pas : il ny a quune demi-page de lecture.
Maintenant, lanons-nous !

Obtenir CakePHP
Tout dabord, rcuprons une copie rcente de CakePHP.
Pour obtenir la dernire version, allez sur le site GitHub du projet
https ://github.com/cakephp/cakephp/tags et tlchargez la dernire version de la 2.0.
Vous
pouvez
aussi
cloner
le
dpt
git://github.com/cakephp/cakephp.git

en

utilisant

git 1 .

CakePHP

git clone

Peu importe comment vous lavez tlcharg, placez le code lintrieur du DocumentRoot de votre
serveur. Une fois termin, votre rpertoire dinstallation devrait ressembler quelque chose comme cela :
/chemin_du_document_root
/app
/lib
/plugins
/vendors
.htaccess
index.php
README

A prsent, il est peut-tre temps de voir un peu comment fonctionne la structure de fichiers de CakePHP :
lisez le chapitre Structure du dossier de CakePHP.
Permissions du rpertoire Tmp
Ensuite vous devrez mettre le rpertoire app/tmp en criture pour le serveur web. La meilleur faon de
le faire est de trouver sous quel utilisateur votre serveur web tourne. Vous pouver mettre <?php echo
exec(whoami); ?> lintrieur de tout fichier PHP que votre serveur web execute. Vous devriez
voir afficher un nom dutilisateur. Changez le possesseur du rpertoire app/tmp pour cet utilisateur. La
commande finale que vous pouvez lancer (dans *nix) pourrait ressembler ceci :
$ chown -R www-data app/tmp

Si pour une raison ou une autre, CakePHP ne peut crire dans ce rpertoire, vous verrez des avertissements
et des exceptions attrapes vous disant que les donnes de cache nont pas pu tre crites.
1. http ://git-scm.com/

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

Crer la base de donnes du blog


Maintenant, mettons en place la base de donnes pour notre blog. Si vous ne lavez pas dj fait, crez une
base de donnes vide avec le nom de votre choix pour lutiliser dans ce tutoriel. Pour le moment, nous allons
juste crer une simple table pour stocker nos posts. Nous allons galement insrer quelques posts des fins
de tests. Excutez les requtes SQL suivantes dans votre base de donnes :
/* D'abord, crons la table des posts : */
CREATE TABLE posts (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(50),
body TEXT,
created DATETIME DEFAULT NULL,
modified DATETIME DEFAULT NULL
);
/* Puis insrons quelques posts pour les tests : */
INSERT INTO posts (title, body, created)
VALUES ('Le titre', 'Voici le contenu du post.', NOW());
INSERT INTO posts (title, body, created)
VALUES ('Encore un titre', 'Et le contenu du post qui suit.', NOW());
INSERT INTO posts (title, body, created)
VALUES ('Le retour du titre', 'C\'est trs excitant, non ?', NOW());

Le choix des noms pour les tables et les colonnes ne sont pas arbitraires. Si vous respectez les conventions
de nommage de CakePHP pour les bases de donnes et les classes (toutes deux expliques au chapitre
Conventions de CakePHP), vous tirerez profit dun grand nombre de fonctionnalits automatiques et vous
viterez des tapes de configurations. CakePHP est suffisamment souple pour implmenter les pires schmas
de bases de donnes, mais respecter les conventions vous fera gagner du temps.
Consultez le chapitre Conventions de CakePHP pour plus dinformations, mais il suffit de comprendre que
nommer notre table posts permet de la relier automatiquement notre model Post, et quavoir des champs
modified et created permet de les avoir grs automagiquement par CakePHP.

Configurer la base de donnes CakePHP


En avant : indiquons CakePHP o se trouve notre base de donnes et comment sy connecter. Pour la
plupart dentre vous, cest la premire et dernire fois que vous configurerez quelque chose.
Une copie du fichier de configuration CakePHP pour la base de donnes se trouve dans
/app/Config/database.php.default. Faites une copie de ce fichier dans le mme rpertoire mais
nommez le database.php.
Le fichier de configuration devrait tre assez simple : remplacez simplement les valeurs du tableau
$default par celles qui correspondent votre installation. Un exemple de tableau de configuration complet pourrait ressembler ce qui suit :
public $default = array(
'datasource' => 'Database/Mysql',
'persistent' => false,
'host' => 'localhost',

Tutoriel dun Blog

CakePHP Cookbook Documentation, Version 2.x

'port' => '',


'login' => 'cakeBlog',
'password' => 'c4k3-rUl3Z',
'database' => 'cake_blog_tutorial',
'schema' => '',
'prefix' => '',
'encoding' => 'utf8'
);

Une fois votre nouveau fichier database.php sauvegard, vous devriez tre en mesure douvrir votre
navigateur internet et de voir la page daccueil de CakePHP. Elle devrait galement vous indiquer que votre
fichier de connexion a t trouv, et que CakePHP peut sy connecter avec succs.
Note : Rappelez-vous que vous aurez besoin davoir PDO, et pdo_mysql activs dans votre php.ini.

Configuration facultative
Il y a quelques autres lments qui peuvent tre configurs. La plupart des dveloppeurs configurent les
lments de cette petite liste, mais ils ne sont pas obligatoires pour ce tutoriel. Le premier consiste dfinir
une chane de caractres personnalise (ou grain de sel) afin de scuriser les hashs. Le second consiste
dfinir un nombre personnalis (ou graine) utiliser pour le chiffrage.
Le grain de sel est utilis pour gnrer des hashes. Changez la valeur par dfaut de Security.salt
dans /app/Config/core.php la ligne 187. La valeur de remplacement doit tre longue, difficile
deviner et aussi alatoire que possible :
/**
* Une chane alatoire utilise dans les mthodes de hachage scurises.
*/
Configure::write('Security.salt', 'pl345e-P45s_7h3*S@l7!');

La graine cipher est utilise pour le chiffrage/dchiffrage des chanes de caractres. Changez la valeur
par dfaut de Security.cipherSeed dans /app/Config/core.php la ligne 192. La valeur de
remplacement doit tre un grand nombre entier alatoire :
/**
* Une chane alatoire de chiffre utilise pour le chiffrage/dchiffrage
* des chanes de caractres.
*/
Configure::write('Security.cipherSeed', '7485712659625147843639846751');

Une note sur mod_rewrite


Occasionnellement, les nouveaux utilisateurs peuvent avoir des problmes de mod_rewrite. Par exemple si
la page daccueil de CakePHP a lair bizarre (pas dimages ou de styles CSS), cela signifie probablement
que mod_rewrite ne fonctionne pas sur votre systme. Merci de vous rfrer la section suivante sur lURL
rewriting pour que votre serveur web fonctionne :

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

URL Rewriting
Apache et mod_rewrite (et .htaccess)

Alors que CakePHP est construit pour travailler avec mod_rewrite et habituellement il lest nous avons
remarqu que certains utilisateurs se battent pour obtenir un bon fonctionnement sur leurs systmes.
Ici il y a quelques trucs que vous pourriez essayer pour que cela fonctionne correctement. Premirement,
regardez votre fichier httpd.conf (Assurez-vous que vous avez dit le httpd.conf du systme plutt que celui
dun utilisateur- ou le httpd.conf dun site spcifique).
Ces fichiers peuvent varier selon les diffrentes distributions et les versions dApache. Vous pouvez allez
voir http ://wiki.apache.org/httpd/DistrosDefaultLayout pour plus dinformations.
1. Assurez-vous quun .htaccess est permis et que AllowOverride est dfini All pour le bon DocumentRoot. Vous devriez voir quelque chose comme :
# Chaque rpertoire auquel Apache a accs peut tre configur avec
# respect pour lesquels les services et les fonctionnalits sont
# autoriss et/ou dsactivs dans ce rpertoire (et ses sous-rpertoires).
#
# Premirement, nous configurons "par dfault" pour tre un ensemble
# trs restrictif de fonctionnalits.
#
<Directory />
Options FollowSymLinks
AllowOverride All
#
Order deny,allow
#
Deny from all
</Directory>

Pour les utilisateurs qui ont apache 2.4 et suprieur, vous devez modifier le fichier de configuration
pour votre httpd.conf ou la configuration de lhte virtuel pour ressembler ce qui suit :
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Require all granted
</Directory>

2. Assurez-vous que vous avez charg correctement mod_rewrite. Vous devriez voir quelque chose
comme :
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Dans la plupart des systmes, ceux-ci vont tre comments donc vous aurez juste besoin de retirer les
symboles # en dbut de ligne.
Aprs que vous avez fait des changements, re-dmarrez Apache pour tre sr que les paramtres soient
actifs.
Vrifiez que vos fichiers .htaccess sont effectivement dans le bon rpertoire.
Cela peut arriver pendant la copie parce que certains systmes dexploitation traitent les fichiers qui
commencent par . en cach et du coup ne les voient pas pour les copier.

Tutoriel dun Blog

CakePHP Cookbook Documentation, Version 2.x

3. Assurez-vous que votre copie de CakePHP vient de la section des tlchargements du site de notre
dpt Git, et a t dzipp correctement en vrifiant les fichiers .htaccess.
Le rpertoire root de CakePHP (a besoin dtre copi dans votre document, cela redirige tout vers
votre app CakePHP) :
<IfModule mod_rewrite.c>
RewriteEngine on
[L]
RewriteRule
^$ app/webroot/
RewriteRule
(.*) app/webroot/$1 [L]
</IfModule>

Le rpertoire app de CakePHP (sera copi dans le rpertoire suprieur de votre application avec Bake) :
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule
^$
webroot/
RewriteRule
(.*) webroot/$1
</IfModule>

[L]
[L]

Le rpertoire webroot de CakePHP (sera copi dans le webroot de votre application avec Bake) :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,L]
</IfModule>

Si votre site CakePHP a toujours des problmes avec mod_rewrite, essayez de modifier les
paramtres pour les Htes Virtuels. Si vous tes sur Ubuntu, modifiez le fichier /etc/apache2/sitesavailable/default (lendroit dpend de la distribution). Dans ce fichier, assurez-vous que
AllowOverride None a t chang en AllowOverride All, donc vous devez avoir :
<Directory />
Options FollowSymLinks
AllowOverride All
</Directory>
<Directory /var/www>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order Allow,Deny
Allow from all
</Directory>

Si vous tes sur Mac OSX, une autre solution est dutiliser loutil virtualhostx 2 pour faire un Hte
Virtuel pour pointer vers votre dossier.
Pour beaucoup de services dhbergement (GoDaddy, 1and1), votre serveur web est en fait dj distribu partir dun rpertoire utilisateur qui utilise dj mod_rewrite. Si vous installez CakePHP dans
un rpertoire utilisateur (http ://exemple.com/~username/cakephp/), ou toute autre structure dURL
qui utilise dj mod_rewrite, vous aurez besoin dajouter les requtes (statements) RewriteBase aux
fichiers .htaccess que CakePHP utilise (/.htaccess, /app/.htaccess, /app/webroot/.htaccess).
2. http ://clickontyler.com/virtualhostx/

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

Ceci peut tre ajout dans la mme section que la directive RewriteEngine, donc par exemple, votre
fichier .htaccess dans webroot ressemblerait ceci :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/cake/app
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,L]
</IfModule>

Les dtails de ces changements dpendront de votre configuration, et pourront inclure des choses
supplmentaires qui ne sont pas lies CakePHP. Merci de vous renseigner sur la documentation en
ligne dApache pour plus dinformations.
4. (Optionel) Pour amliorer la configuration de production, vous devriez empcher les assets invalides
dtre parss par CakePHP. Modifiez votre webroot .htaccess pour quelque chose comme :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/cake/app
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !^/(app/webroot/)?(img|css|js)/(.*)$
RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

Ce qui est au-dessus va simplement empcher les assets incorrects dtre envoys index.php et la
place dafficher la page 404 de votre serveur web.
De plus, vous pouvez crer une page HTML 404 correspondante, ou utiliser la page 404 de CakePHP
intgre en ajoutant une directive ErrorDocument :
ErrorDocument 404 /404-not-found

De belles URLs sur nginx

nginx ne fait pas usage de fichiers .htaccess comme Apache et Lighttpd, il est donc ncessaire de crer les
URLs rcrites disponibles dans la configuration du site. selon votre configuration, vous devrez modifier
cela, mais tout le moins, vous aurez besoin de PHP fonctionnant comme une instance FastCGI.
server {
listen
80;
server_name www.example.com;
rewrite ^(.*) http://example.com$1 permanent;
}
server {
listen
80;
server_name example.com;
# root directive should be global
root
/var/www/example.com/public/app/webroot/;

Tutoriel dun Blog

CakePHP Cookbook Documentation, Version 2.x

index

index.php;

access_log /var/www/example.com/log/access.log;
error_log /var/www/example.com/log/error.log;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
include /etc/nginx/fastcgi_params;
try_files $uri =404;
fastcgi_pass
127.0.0.1:9000;
fastcgi_index
index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}

Si pour une raison exotique vous ne pouvez pas changer votre rpertoire racine et devez lancer votre projet
partir dun sous-dossier comme example.com/subfolder/, vous devrez injecter /webroot dans chaque
requte.
location ~ ^/(subfolder)/(.*)? {
index index.php;
set $new_uri /$1/webroot/$2;
try_files $new_uri $new_uri/ /$1/index.php?$args;
... php handling ...
}

Note : Les rcentes configurations de PHP-FPM sont dfinies pour couter sur le socket php-fpm au lieu
du port TCP 9000 sur ladresse 127.0.0.1. Si vous obtenez une erreur 502 de mauvaise passerelle avec la
configuration du dessus, essayez de remplacer le port TCP du fastcgi_pass par le chemin du socket (ex :
fastcgi_pass unix :/var/run/php5-fpm.sock ;).

Rewrites dURL sur IIS7 (serveurs Windows)

IIS7 ne supporte pas nativement les fichiers .htaccess. Bien quil existe des add-ons qui peuvent ajouter
ce support, vous pouvez aussi importer les rgles des .htaccess dans IIS pour utiliser les rewrites natifs de
CakePHP. Pour ce faire, suivez ces tapes :
1. Utilisez linstalleur de la plateforme Web de Microsoft 3 pour installer lURL Rewrite Module 2.0 4
ou tlchargez le directement (32-bit 5 / 64-bit 6 ).
2. Crez un nouveau fichier dans votre dossier CakePHP, appel web.config.
3.
4.
5.
6.

http ://www.microsoft.com/web/downloads/platform.aspx
http ://www.iis.net/downloads/microsoft/url-rewrite
http ://www.microsoft.com/en-us/download/details.aspx ?id=5747
http ://www.microsoft.com/en-us/download/details.aspx ?id=7435

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

3. Utilisez Notepad ou tout autre diteur XML-safe, copiez le code suivant dans votre nouveau fichier
web.config...
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Rewrite requests to test.php"
stopProcessing="true">
<match url="^test.php(.*)$" ignoreCase="false" />
<action type="Rewrite" url="app/webroot/test.php{R:1}" />
</rule>
<rule name="Exclude direct access to app/webroot/*"
stopProcessing="true">
<match url="^app/webroot/(.*)$" ignoreCase="false" />
<action type="None" />
</rule>
<rule name="Rewrite routed access to assets(img, css, files, js, favicon)"
stopProcessing="true">
<match url="^(img|css|files|js|favicon.ico)(.*)$" />
<action type="Rewrite" url="app/webroot/{R:1}{R:2}"
appendQueryString="false" />
</rule>
<rule name="Rewrite requested file/folder to index.php"
stopProcessing="true">
<match url="^(.*)$" ignoreCase="false" />
<action type="Rewrite" url="index.php"
appendQueryString="true" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>

Une fois que le fichier web.config est cr avec les bonnes rgles de rcriture des liens de IIS, les liens
CakePHP, les CSS, le JavaScript, et le reroutage devraient fonctionner correctement.
URL-Rewriting sur lighttpd

Lighttpd ne supporte pas les fonctions .htaccess, par consquent vous pouvez retirer tous les fichiers .htaccess. Dans la configuration lighttpd, assurez-vous dactiver mod_rewrite. Ajoutez une ligne :
url.rewrite-if-not-file =(
"^([^\?]*)(\?(.+))?$" => "/index.php?url=$1&$3"
)

Rgles de rewrite URL pour Hiawatha

La rgle ncessaire UrlToolkit (pour le rewriting URL) pour utiliser CakePHP avec Hiawatha est :

Tutoriel dun Blog

CakePHP Cookbook Documentation, Version 2.x

UrlToolkit {
ToolkitID = cakephp
RequestURI exists Return
Match .* Rewrite /index.php
}

Je ne veux / ne peux utiliser lURL rewriting

Si vous ne voulez ou ne pouvez pas utiliser lURL rewriting sur votre serveur web, rfrez-vous la section
core configuration.
Maintenant continuez sur Blog Tutoriel - Ajouter la logique pour commencer construire votre premire
application CakePHP.

Blog Tutoriel - Ajouter la logique


Crer un model Post
La classe Model est le pain quotidien des applications CakePHP. En crant un model CakePHP qui interagira
avec notre base de donnes, nous aurons mis en place les fondations ncessaires pour faire plus tard nos
oprations de lecture, dinsertion, ddition et de suppression.
Les fichiers des classes Model de CakePHP se trouvent dans /app/Model, et le fichier que nous allons
crer maintenant sera enregistr dans /app/Model/Post.php. Le fichier complet devrait ressembler
ceci
class Post extends AppModel {
}

La convention de nommage est vraiment trs importante dans CakePHP. En nommant notre model Post,
CakePHP peut automatiquement dduire que ce model sera utilis dans le controller PostsController, et sera
li la table posts de la base de donnes.
Note : CakePHP crera dynamiquement un objet model pour vous, sil ne trouve pas le fichier correspondant
dans /app/Model. Cela veut aussi dire que si vous navez pas nomm correctement votre fichier (par ex.
post.php ou posts.php au lieu de Post.php), CakePHP ne reconnatra pas votre configuration et utilisera ses
objets model par dfaut.
Pour plus dinformations sur les models, comme les prfixes des tables, les callbacks, et la validation, consultez le chapitre Models (Modles) du manuel.

Crer un controller Posts


Nous allons maintenant crer un controller pour nos posts. Le controller est lendroit o sexcutera toute la
logique mtier pour lintraction du processus de post. En un mot, cest lendroit o vous jouerez avec les

10

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

models et o les tches lies aux posts sexcutent. Nous placerons ce nouveau controller dans un fichier appel PostsController.php lintrieur du dossier /app/Controller. Voici quoi devrait ressembler le controller de base
class PostsController extends AppController {
public $helpers = array('Html', 'Form');
}

Maintenant, ajoutons une action notre controller. Les actions reprsentent souvent une simple fonction ou une interface dans une application. Par exemple, quand les utilisateurs requtent
www.exemple.com/posts/index (qui est la mme chose que www.exemple.com/posts/), ils pourraient sattendre voir une liste de posts. Le code pour cette action devrait ressembler quelque chose comme a
class PostsController extends AppController {
public $helpers = array('Html', 'Form');
public function index() {
$this->set('posts', $this->Post->find('all'));
}
}

En dfinissant la fonction index() dans notre PostsController, les utilisateurs peuvent accder cette
logique en demandant www.exemple.com/posts/index. De la mme faon, si nous devions dfinir une fonction appele foobar(), les utilisateurs pourrait y accder en demandant www.exemple.com/posts/foobar.
Avertissement : Vous pourriez tre tent de nommer vos controllers et vos actions dune certaine
manire pour obtenir une certaine URL. Rsistez cette tentation. Suivez les conventions CakePHP
(le nom des controllers au pluriel, etc.) et nommez vos actions de faon lisible et comprhensible. Vous
pouvez lier les URLs votre code en utilisant ce quon appelle des routes, on le verra plus tard.
La seule instruction que cette action utilise est set(), pour transmettre les donnes du controller la vue
(que nous crerons la prochaine tape). La ligne dfinit la variable de vue appele posts qui est gale
la valeur de retour de la mthode find(all) du model Post. Notre model Post est automatiquement
disponible via $this->Post, parce que nous avons suivi les conventions de nommage de CakePHP.
Pour en apprendre plus sur les controllers de CakePHP, consultez le chapitre Controllers (Contrleurs).

Crer les Vues des Posts


Maintenant que nous avons nos donnes en provenance du model, ainsi que la logique applicative et les flux
dfinis par notre controller, nous allons crer une vue pour laction index que nous avons cr ci-dessus.
Les vues de CakePHP sont juste des fragments de prsentation assaisonne, qui sintgrent au sein dun
layout applicatif. Pour la plupart des applications, elles sont un mlange de HTML et PHP, mais les vues
peuvent aussi tre constitues de XML, CSV ou mme de donnes binaires.
Un Layout est un code de prsentation, encapsul autour dune vue. Ils peuvent tre dfinis et interchangs,
mais pour le moment, utilisons juste celui par dfaut.

Blog Tutoriel - Ajouter la logique

11

CakePHP Cookbook Documentation, Version 2.x

Vous souvenez-vous, dans la dernire section, comment nous avions assign la variable posts la vue en
utilisant la mthode set() ? Cela devrait transmettre les donnes la vue qui ressemblerait quelque chose
comme cela
// print_r($posts) affiche:
Array
(
[0] => Array
(
[Post] => Array
(
[id] => 1
[title] => Le titre
[body] => Voici le contenu du post.
[created] => 2008-02-13 18:34:55
[modified] =>
)
)
[1] => Array
(
[Post] => Array
(
[id] => 2
[title] => Encore un titre
[body] => Et le contenu du post qui suit.
[created] => 2008-02-13 18:34:56
[modified] =>
)
)
[2] => Array
(
[Post] => Array
(
[id] => 3
[title] => Le retour du titre
[body] => C'est trs excitant, non ?
[created] => 2008-02-13 18:34:57
[modified] =>
)
)
)

Les fichiers des vues de CakePHP sont stocks dans /app/View lintrieur dun dossier dont le nom
correspond celui du controller (nous aurons crer un dossier appel Posts dans ce cas). Pour mettre en
forme les donnes de ces posts dans un joli tableau, le code de notre vue devrait ressembler quelque chose
comme cela
<!-- File: /app/View/Posts/index.ctp -->
<h1>Blog posts</h1>
<table>
<tr>

12

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

<th>Id</th>
<th>Titre</th>
<th>Cr le</th>
</tr>
<!-- Here is where we loop through our $posts array, printing out post info -->
<?php foreach ($posts as $post): ?>
<tr>
<td><?php echo $post['Post']['id']; ?></td>
<td>
<?php echo $this->Html->link($post['Post']['title'],
array('controller' => 'posts', 'action' => 'view', $post['Post']['id'])); ?>
</td>
<td><?php echo $post['Post']['created']; ?></td>
</tr>
<?php endforeach; ?>
<?php unset($post); ?>
</table>

Vous avez sans doute remarqu lutilisation dun objet appel $this->Html. Cest une instance de la
classe CakePHP HtmlHelper. CakePHP est livr avec un ensemble de helpers (des assistants) pour les
vues, qui ralisent en un clin dil des choses comme le linking (mettre les liens dans un texte), laffichage
des formulaires, du JavaScript et de lAJAX. Vous pouvez en apprendre plus sur la manire de les utiliser
dans le chapitre Helpers (Assistants), mais ce quil est important de noter ici, cest que la mthode link()
gnrera un lien HTML partir dun titre (le premier paramtre) et dune URL (le second paramtre).
Lorsque vous indiquez des URLs dans CakePHP, il est recommand dutiliser les tableaux. Ceci est expliqu
dans le chapitre des Routes. Utiliser les tableaux dans les URLs vous permet de tirer profit des capacits de
CakePHP r-inverser les routes. Vous pouvez aussi utiliser les URLs relatives depuis la base de lapplication comme suit /controller/action/param1/param2.
A ce stade, vous devriez tre en mesure de pointer votre navigateur sur la page
http ://www.exemple.com/posts/index. Vous devriez voir votre vue, correctement formate avec le
titre et le tableau listant les posts.
Si vous avez essay de cliquer sur lun des liens que nous avons crs dans cette vue (le lien sur le titre
dun post mne lURL : /posts/view/un_id_quelconque), vous avez srement t inform par CakePHP
que laction na pas encore t dfinie. Si vous navez pas t inform, soit quelque chose sest mal pass,
soit en fait vous aviez dj dfini laction, auquel cas vous tes vraiment sournois ! Sinon, nous allons la
crer sans plus tarder dans le Controller Posts
// File: /app/Controller/PostsController.php
class PostsController extends AppController {
public $helpers = array('Html', 'Form');
public function index() {
$this->set('posts', $this->Post->find('all'));
}
public function view($id = null) {
if (!$id) {

Blog Tutoriel - Ajouter la logique

13

CakePHP Cookbook Documentation, Version 2.x

throw new NotFoundException(__('Invalid post'));


}
$post = $this->Post->findById($id);
if (!$post) {
throw new NotFoundException(__('Invalid post'));
}
$this->set('post', $post);
}
}

Lappel de set() devrait vous tre familier. Notez que nous utilisons findById() plutt que
find(all) parce que nous voulons seulement rcuprer les informations dun seul post.
Notez que notre action view prend un paramtre : lID du post que nous aimerions voir. Ce paramtre est
transmis laction grce lURL demande. Si un utilisateur demande /posts/view/3, alors la valeur 3 est
transmise la variable $id.
Nous faisons aussi une petite vrification derreurs pour nous assurer quun utilisateur accde bien lenregsitrement. Si un utilisateur requte /posts/view, nous lancerons un NotFoundException et laisserons le Gestionnaire dErreur de CakePHP ErrorHandler prendre le dessus. Nous excutons aussi une
vrification similaire pour nous assurer que lutilisateur a accde un enregistrement qui existe.
Maintenant, crons la vue pour
/app/View/Posts/view.ctp.

notre

nouvelle

action

view

et

plaons-la

dans

<!-- Fichier : /app/View/Posts/view.ctp -->


<h1><?php echo h($post['Post']['title']); ?></h1>
<p><small>Cr le : <?php echo $post['Post']['created']; ?></small></p>
<p><?php echo h($post['Post']['body']); ?></p>

Vrifiez que cela fonctionne en testant les liens de la page /posts/index ou en affichant manuellement un
post via /posts/view/1.

Ajouter des Posts


Lire depuis la base de donnes et nous afficher les posts est un bon dbut, mais lanons-nous dans lajout de
nouveaux posts.
Premirement, commenons par crer une action add() dans le PostsController
class PostsController extends AppController {
public $helpers = array('Html', 'Form', 'Flash');
public $components = array('Flash');
public function index() {
$this->set('posts', $this->Post->find('all'));
}

14

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

public function view($id) {


if (!$id) {
throw new NotFoundException(__('Invalid post'));
}
$post = $this->Post->findById($id);
if (!$post) {
throw new NotFoundException(__('Invalid post'));
}
$this->set('post', $post);
}
public function add() {
if ($this->request->is('post')) {
$this->Post->create();
if ($this->Post->save($this->request->data)) {
$this->Flash->success(__('Your post has been saved.'));
return $this->redirect(array('action' => 'index'));
}
$this->Flash->error(__('Unable to add your post.'));
}
}
}

Note : $this->request->is() prend un unique argument, qui peut tre la METHOD request (get,
put, post, delete) ou toute identifier de request (ajax). Ce nest pas une faon de vrifier une data
poste spcifique. Par exemple, $this->request->is(book) ne retournera pas true si les data du
book ont t postes.

Note : Vous avez besoin dinclure le component Flash (FlashComponent) et le helper Flash (FlashHelper)
dans chaque controller que vous utiliserez. Si ncessaire, incluez-les dans le controller principal (AppController) pour quils soient accessibles tous les controllers.
Voici ce que fait laction add() : si la requte HTTP est de type POST, essayez de sauvegarder les donnes
en utilisant le model Post. Si pour une raison quelconque, la sauvegarde a choue, affichez simplement la
vue. Cela nous donne une chance de voir les erreurs de validation de lutilisateur et dautres avertissements.
Chaque requte de CakePHP contient un objet CakeRequest qui est accessible en utilisant
$this->request. Cet objet contient des informations utiles sur la requte qui vient dtre reue,
et permet de contrler les flux de votre application. Dans ce cas, nous utilisons la mthode
CakeRequest::is() pour vrifier que la requte est de type POST.
Lorsquun utilisateur utilise un formulaire pour poster des donnes dans votre application, ces informations
sont disponibles dans $this->request->data. Vous pouvez utiliser les fonctions pr() ou debug()
pour les afficher si vous voulez voir quoi cela ressemble.
Nous utilisons la mthode FlashComponent::success() du component Flash (FlashComponent)
pour dfinir un message dans une variable session et qui sera affich dans la page juste aprs la redirection.
Dans le layout, nous trouvons la fonction FlashHelper::render() qui permet dafficher et de nettoyer
la variable correspondante. La mthode Controller::redirect du controller permet de rediriger vers

Blog Tutoriel - Ajouter la logique

15

CakePHP Cookbook Documentation, Version 2.x

une autre URL. Le paramtre array(action => index) sera traduit vers lURL /posts (dans
notre cas laction index du controller Posts). Vous pouvez vous rfrer la fonction Router::url()
dans lAPI 7 pour voir les diffrents formats dURL accepts dans les diffrentes fonctions de CakePHP.
Lappel de la mthode save() vrifiera les erreurs de validation et interrompra lenregistrement si une
erreur survient. Nous verrons la faon dont les erreurs sont traites dans les sections suivantes.
Nous appelons la mthode create() en premier afin de rinitialiser ltat du model pour sauvegarder
les nouvelles informations. Cela ne cre pas rellement un enregistrement dans la base de donnes mais
rinitialise Model : :$id et dfinit Model : :$data en se basant sur le champ par dfaut dans votre base de
donnes.

Valider les donnes


Cake place la barre trs haute pour briser la monotonie de la validation des champs de formulaires. Tout le
monde dteste le dvelopement de formulaires interminables et leurs routines de validations. Cake rend tout
cela plus facile et plus rapide.
Pour tirer profit des fonctionnalits de validation, vous devez utiliser le helper Form (FormHelper) dans
vos vues. FormHelper est disponible par dfaut dans toutes les vues avec la variables $this->Form.
Voici le code de notre vue add (ajout)
<!-- Fichier : /app/View/Posts/add.ctp -->
<h1>Ajouter un post</h1>
<?php
echo $this->Form->create('Post');
echo $this->Form->input('title');
echo $this->Form->input('body', array('rows' => '3'));
echo $this->Form->end('Sauvegarder le post');
?>

Nous utilisons le FormHelper pour gnrer la balise douverture dune formulaire HTML. Voici le code
HTML gnr par $this->Form->create()
.. code-block:: html

<form id=PostAddForm method=post action=/posts/add>


Si create() est appele sans aucun paramtre, CakePHP suppose que vous construisez un formulaire qui
envoie les donnes en POST laction add() (ou edit() quand id est dans les donnes du formulaire)
du controller actuel.
La mthode $this->Form->input() est utilise pour crer des lments de formulaire du mme nom.
Le premier paramtre dit CakePHP quels champs ils correspondent et le second paramtre vous permet
de spcifier un large ventail doptions - dans ce cas, le nombre de lignes du textarea. Il y a un peu dintrospection et dautomagie ici : input() affichera diffrents lments de formulaire selon le champ spcifi
du model.
7. http ://api.cakephp.org

16

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

Lappel de la mthode $this->Form->end() gnre un bouton de soumission et ajoute la balise de


fermeture du formulaire. Si une chane de caractres est passe comme premier paramtre de la mthode
end(), le helper Form affichera un bouton de soumission dont le nom correspond celle-ci. Encore une
fois, rfrez-vous au chapitre Helpers (Assistants) pour en savoir plus sur les helpers.
A prsent, revenons en arrire et modifions notre vue /app/View/Posts/index.ctp pour ajouter un
lien Ajouter un post. Ajoutez la ligne suivante avant <table>
<?php echo $this->Html->link(
'Ajouter un Post',
array('controller' => 'posts', 'action' => 'add')
); ?>

Vous vous demandez peut-tre : comment je fais pour indiquer CakePHP mes exigences de validation ?
Les rgles de validation sont dfinies dans le model. Retournons donc notre model Post et procdons
quelques ajustements
class Post extends AppModel {
public $validate = array(
'title' => array(
'rule' => 'notBlank'
),
'body' => array(
'rule' => 'notBlank'
)
);
}

Le tableau $validate indique CakePHP comment valider vos donnes lorsque la mthode save()
est appele. Ici, jai spcifi que les deux champs body et title ne doivent pas tre vides. Le moteur
de validation de CakePHP est puissant, il dispose dun certain nombre de rgles intgres (code de carte
bancaire, adresse emails, etc.) et dune souplesse pour ajouter vos propres rgles de validation. Pour plus
dinformations sur cette configuration, consultez le chapitre Validation des Donnes.
Maintenant que vos rgles de validation sont en place, utilisez lapplication pour essayer dajouter un post
avec un titre et un contenu vide afin de voir comment cela fonctionne. Puisque que nous avons utilis la
mthode FormHelper::input() du helper Form pour crer nos lments de formulaire, nos messages derreurs de validation seront affichs automatiquement.

Editer des Posts


Ldition de posts : nous y voil. Vous tes un pro de CakePHP maintenant, vous devriez donc avoir adopt
le principe. Crez dabord laction puis la vue. Voici quoi laction edit() du controller Posts (PostsController) devrait ressembler
public function edit($id = null) {
if (!$id) {
throw new NotFoundException(__('Invalid post'));
}
$post = $this->Post->findById($id);

Blog Tutoriel - Ajouter la logique

17

CakePHP Cookbook Documentation, Version 2.x

if (!$post) {
throw new NotFoundException(__('Invalid post'));
}
if ($this->request->is(array('post', 'put'))) {
$this->Post->id = $id;
if ($this->Post->save($this->request->data)) {
$this->Flash->success(__('Your post has been updated.'));
return $this->redirect(array('action' => 'index'));
}
$this->Flash->error(__('Unable to update your post.'));
}
if (!$this->request->data) {
$this->request->data = $post;
}
}

Cette action sassure dabord que lutilisateur a essay daccder un enregistrement existant. Sil ny a pas
de paramtre $id pass, ou si le post nexiste pas, nous lanons une NotFoundException pour que le
gestionnaire dErreurs ErrorHandler de CakePHP sen occupe.
Ensuite laction vrifie si la requte est une requte POST ou PUT. Si elle lest, alors nous utilisons les
donnes POST pour mettre jour notre enregistrement Post, ou sortir et montrer les erreurs de validation
lutilisateur.
Sil ny a pas de donnes dfinies dans $this->request->data, nous le dfinissons simplement dans
le post rcupr prcdemment.
La vue ddition devrait ressembler quelque chose comme cela :
<!-- Fichier: /app/View/Posts/edit.ctp -->
<h1>Editer le post</h1>
<?php
echo $this->Form->create('Post');
echo $this->Form->input('title');
echo $this->Form->input('body', array('rows' => '3'));
echo $this->Form->input('id', array('type' => 'hidden'));
echo $this->Form->end('Save Post');
?>

Cette vue affiche le formulaire ddition (avec les donnes pr-remplies) avec les messages derreur de
validation ncessaires.
Une chose noter ici : CakePHP supposera que vous ditez un model si le champ id est prsent dans le
tableau de donnes. Sil nest pas prsent (ce qui revient notre vue add), CakePHP supposera que vous
insrez un nouveau model lorsque save() sera appele.
Vous pouvez maintenant mettre jour votre vue index avec des liens pour diter des posts :
<!-- Fichier: /app/View/Posts/index.ctp

(lien d\'dition ajout) -->

<h1>Blog posts</h1>

18

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

<p><?php echo $this->Html->link("Ajouter un Post", array('action' => 'add')); ?></p>


<table>
<tr>
<th>Id</th>
<th>Title</th>
<th>Action</th>
<th>Created</th>
</tr>
<!-- Ici se trouve la boucle de notre tableau $posts, impression de l\'info du post -->
<?php foreach ($posts as $post): ?>
<tr>
<td><?php echo $post['Post']['id']; ?></td>
<td>
<?php echo $this->Html->link(
$post['Post']['title'],
array('action' => 'view', $post['Post']['id'])
); ?>
</td>
<td>
<?php echo $this->Html->link(
'Editer',
array('action' => 'edit', $post['Post']['id'])
); ?>
</td>
<td>
<?php echo $post['Post']['created']; ?>
</td>
</tr>
<?php endforeach; ?>
</table>

Supprimer des Posts


A prsent, mettons en place un moyen de supprimer les posts pour les utilisateurs. Dmarrons avec une
action delete() dans le controller Posts (PostsController)
public function delete($id) {
if ($this->request->is('get')) {
throw new MethodNotAllowedException();
}
if ($this->Post->delete($id)) {
$this->Flash->success(
__('Le post avec id : %s a t supprim.', h($id))
);
} else {
$this->Flash->error(
__('Le post avec l\'id: %s n\'a pas pu tre supprim.', h($id))
);

Blog Tutoriel - Ajouter la logique

19

CakePHP Cookbook Documentation, Version 2.x

}
return $this->redirect(array('action' => 'index'));
}

Cette logique supprime le Post spcifi par $id, et utilise $this->Flash->success() pour afficher
lutilisateur un message de confirmation aprs lavoir redirig sur /posts. Si lutilisateur tente une suppression en utilisant une requte GET, une exception est leve. Les exceptions manques sont captures par
le gestionnaire dexceptions de CakePHP et un joli message derreur est affich. Il y a plusieurs Exceptions
intgres qui peuvent tre utilises pour indiquer les diffrentes erreurs HTTP que votre application pourrait
rencontrer.
Etant donn que nous excutons juste un peu de logique et de redirection, cette action na pas de vue. Vous
voudrez peut-tre mettre jour votre vue index avec des liens pour permettre aux utilisateurs de supprimer
des Posts, ainsi :
<!-- Fichier: /app/View/Posts/index.ctp -->
<h1>Blog posts</h1>
<p><?php echo $this->Html->link(
'Ajouter un Post',
array('action' => 'add')
); ?></p>
<table>
<tr>
<th>Id</th>
<th>Titre</th>
<th>Actions</th>
<th>Cr le</th>
</tr>

<!-- Ici, nous bouclons sur le tableau $post afin d'afficher les informations des posts -->
<?php foreach ($posts as $post): ?>
<tr>
<td><?php echo $post['Post']['id']; ?></td>
<td>
<?php echo $this->Html->link(
$post['Post']['title'],
array('action' => 'view', $post['Post']['id'])
); ?>
</td>
<td>
<?php echo $this->Form->postLink(
'Supprimer',
array('action' => 'delete', $post['Post']['id']),
array('confirm' => 'Etes-vous sr ?'));
?>
<?php echo $this->Html->link(
'Editer',
array('action' => 'edit', $post['Post']['id'])
); ?>
</td>

20

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

<td>
<?php echo $post['Post']['created']; ?>
</td>
</tr>
<?php endforeach; ?>
</table>

Utiliser postLink() permet de crer un lien qui utilise du Javascript pour supprimer notre post en faisant
une requte POST. Autoriser la suppression par une requte GET est dangereux cause des robots dindexation qui peuvent tous les supprimer.
Note : Ce code utilise aussi le helper Form pour demander lutilisateur une confirmation avant de
supprimer le post.

Routes
Pour certains, le routage par dfaut de CakePHP fonctionne suffisamment bien. Les dveloppeurs qui sont
sensibles la facilit dutilisation et la compatibilit avec les moteurs de recherches apprcieront la manire
dont CakePHP lie des URLs des actions spcifiques. Nous allons donc faire une rapide modification des
routes dans ce tutoriel.
Pour plus dinformations sur les techniques de routages, consultez le chapitre Configuration des Routes.
Par dfaut, CakePHP effectue une redirection dune personne visitant la racine de votre site (par ex :
http ://www.exemple.com) vers le controller Pages (PagesController) et affiche le rendu de la vue appele
home. Au lieu de cela, nous voudrions la remplacer avec notre controller Posts (PostsController).
Le routage de CakePHP se trouve dans /app/Config/routes.php. Vous devrez commenter ou supprimer la ligne qui dfinit la route par dfaut. Elle ressemble cela
Router::connect(
'/',
array('controller' => 'pages', 'action' => 'display', 'home')
);

Cette ligne connecte lURL / la page daccueil par dfaut de CakePHP. Nous voulons que cette URL soit
connecte notre propre controller, remplacez donc la ligne par celle-ci
Router::connect('/', array('controller' => 'posts', 'action' => 'index'));

Cela devrait connecter les utilisateurs demandant / laction index() de notre controller Posts
(PostsController).
Note : CakePHP peut aussi faire du reverse routing (ou routage invers). Par exemple, pour la route
dfinie plus haut, en ajoutant array(controller => posts, action => index)
la fonction retournant un tableau, lURL / sera utilise. Il est dailleurs bien avis de toujours utiliser un
tableau pour les URLs afin que vos routes dfinissent o vont les URLs, mais aussi pour sassurer quelles
aillent dans la mme direction.

Blog Tutoriel - Ajouter la logique

21

CakePHP Cookbook Documentation, Version 2.x

Conclusion
Crer des applications de cette manire vous apportera, paix, honneur, amour et argent au-del mme de vos
fantasmes les plus fous. Simple nest ce pas ? Gardez lesprit que ce tutoriel tait trs basique. CakePHP
a beaucoup plus de fonctionnalits offrir et il est aussi souple dans dautres domaines que nous navons
pas souhait couvrir ici pour simplifier les choses. Utilisez le reste de ce manuel comme un guide pour
dvelopper des applications plus riches en fonctionnalits.
Maintenant que vous avez cr une application CakePHP basique, vous tes prt pour les choses srieuses.
Commencez votre propre projet et lisez le reste du Cookbook et lAPI 8 .
Si vous avez besoin daide, il y a plusieurs faons dobtenir de laide - merci de regarder la page O obtenir
de laide Bienvenue sur CakePHP !
Prochaines lectures suggres
Voici les diffrents chapitres que les gens veulent souvent lire aprs :
1. Layouts : Personnaliser les Layouts de votre application.
2. Elements : Inclure et r-utiliser les portions de vues.
3. Scaffolding : Construire une bauche dapplication sans avoir coder.
4. Gnration de code avec Bake Gnrer un code CRUD basique.
5. Authentification Simple et Autorisation de lApplication : Tutoriel sur lenregistrement et la connexion
dutilisateurs.

Lectures supplmentaires
Une requte CakePHP typique
Nous avons dcouvert les ingrdients de bases de CakePHP, regardons maintenant comment chaque objet travaille avec les autres pour rpondre une requte simple. Poursuivons sur notre exemple original
de requte, imaginons que notre ami Ricardo vient de cliquer sur le lien Achetez un Cake personnalis
maintenant ! sur la page daccueil dune application CakePHP.
Figure : 2. Typical CakePHP Request.
Noir = lment obligatoire, Gris = lment optionnel, Bleu = rappel (callback)
1. Ricardo clique sur le lien pointant vers http ://www.exemple.com/cakes/buy et son navigateur envoie
une requte au serveur Web.
2. Le routeur analyse lURL afin dextraire les paramtres de cette requte : le controller, laction et tout
argument qui affectera la logique mtier pendant cette requte.
3. En utilisant les routes, lURL dune requte est lie une action dun controller (une mthode dune
classe controller spcifique). Dans notre exemple, il sagit de la mthode buy() du Controller Cakes.
La fonction de rappel du controller, beforeFilter(), est appele avant que toute logique de laction du
controller ne soit excute.
8. http ://api.cakephp.org

22

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

F IGURE 1.1 Diagramme reprsentant une requte CakePHP typique.

Blog Tutoriel - Ajouter la logique

23

CakePHP Cookbook Documentation, Version 2.x

4. Le controller peut utiliser des models pour accder aux donnes de lapplication. Dans cet exemple,
le controller utilise un model pour rcuprer les derniers achats de Ricardo depuis la base de donnes.
Toute mthode de rappel du model, tout behavior ou toute source de donnes peut sappliquer pendant
cette opration. Bien que lutilisation du model ne soit pas obligatoire, tous les controllers CakePHP
ncessitent au dpart, au moins un model.
5. Une fois que le model a rcupr les donnes, elles sont retournes au controller. Des fonctions de
rappel du model peuvent sexcuter.
6. Le controller peut faire usage de components pour affiner les donnes ou pour effectuer dautres
oprations (manipulation de session, authentification ou envoi de mails par exemple).
7. Une fois que le controller a utilis les models et components pour prparer suffisamment les donnes,
ces donnes sont passes la vue grce la mthode set(). Les mthodes de rappel (callbacks) du controller peuvent tre appliques avant lenvoi des donnes. La logique de la vue est excute, laquelle
peut inclure lutilisation delements et/ou de helpers. Par dfaut, la vue est rendue travers un layout
(mise en page).
8. Dautres fonctions de rappel (callbacks) du controller (comme afterFilter) peuvent tre excutes. La vue complte et finale est envoye au navigateur de Ricardo.
Conventions de CakePHP
Nous sommes de grands fans des conventions plutt que de la configuration. Bien que cela rclame un peu
de temps pour apprendre les conventions de CakePHP, terme vous gagnerez du temps : en suivant les
conventions, vous aurez des fonctionnalits automatiques et vous vous librerez du cauchemar de la maintenance par lanalyse des fichiers de configuration. Les conventions sont aussi l pour crer un environnement
de dveloppement uniforme, permettant dautres dveloppeurs de sinvestir dans le code plus facilement.
Les conventions de CakePHP ont t cres partir de nombreuses annes dexprience dans le dveloppement Web et de bonnes pratiques. Alors que nous vous conseillons dutiliser ces conventions lors de vos
dveloppements CakePHP, nous devons mentionner que la plupart de ces principes sont facilement contournables - ce qui est particulirement utile lorsque vous travaillez avec danciennes applications.
Les conventions des Controllers

Les noms des classes de controller sont au pluriel, CamelCased et se terminent par Controller.
PeopleController et LatestArticlesController sont des exemples respectant cette convention.
La premire mthode que vous crivez pour un controller devrait tre index(). Lorsquune requte pointe
vers un controller sans action, le comportement par dfaut de CakePHP est dexcuter la fonction index()
de ce controller. Ainsi, la requte http ://www.exemple.com/apples/ renvoie la fonction index() de
ApplesController, alors que http ://www.exemple.com/apples/view renvoie vers la fonction view()
de ApplesController.
Vous pouvez aussi changer la visibilit des mthodes des controllers dans CakePHP en prfixant les noms
de mthode des controllers avec des underscores. Si une mthode du controller a t prfixe avec un underscore, la mthode ne sera pas accessible directement partir du web mais est disponible pour une utilisation
interne. Par exemple :

24

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

class NewsController extends AppController {


public function latest() {
$this->_findNewArticles();
}
protected function _findNewArticles() {
// Logique pour trouver les derniers articles de nouvelles
}
}

Alors que la page http ://www.exemple.com/news/latest/ est accessible pour lutilisateur comme dhabitude,
quelquun qui essaie daller sur la page http ://www.example.com/news/_findNewArticles/ aura une erreur,
car la mthode est prcde dun underscore. Vous pouvez aussi utiliser les mots-cls de visibilit de PHP
pour indiquer si la mthode peut ou non tre accessible partir dune URL. Les mthodes non-publiques ne
sont pas accessibles.
Considrations URL pour les noms de Controller Comme vous venez de voir, un controller mot
unique renvoie facilement vers un chemin URL en minuscules. Par exemple, ApplesController
(qui serait dfini dans le nom de fichier ApplesController.php) est accessible ladresse http ://exemple.com/apples.
Les controllers multiples mots peuvent tre de forme inflect qui correspondent au nom du controller :
/redApples
/RedApples
/Red_apples
/red_apples
iront tous vers lindex du controller RedApples. Cependant, la convention est que vos URLs soient en minuscules et avec des underscores, cest pourquoi /red_apples/go_pick est la forme correcte pour accder
laction RedApplesController::go_pick.
Pour plus dinformations sur les URLs de CakePHP et la gestion des paramtres, allez voir Configuration
des Routes.
Conventions des Fichiers et des Noms de Classe

En gnral, les noms de fichiers correspondent aux noms des classes cest--dire en CamelCase. Donc si vous
avez une classe MaChouetteClasse, alors dans Cake, le fichier devra tre nomm MaChouetteClasse.php.
Voici des exemples de la manire dont on nomme les fichiers, pour chacun des diffrents types de classes
que vous utiliseriez habituellement dans une application CakePHP :
La classe controller BisousEtCalinsController devra se trouver dans un fichier nomm BisousEtCalinsController.php.
La classe Component (Composant) MonSuperComponent devra se trouver dans un fichier nomm MonSuperComponent.php.
La classe Model ValeurOption devra se trouver dans un fichier nomm ValeurOption.php.
La classe Behavior (Comportement) SpecialementFunkableBehavior devra se trouver dans un fichier
nomm SpecialementFunkableBehavior.php.
La classe View (Vue) SuperSimpleView devra se trouver dans un fichier nomm SuperSimpleView.ctp.
Blog Tutoriel - Ajouter la logique

25

CakePHP Cookbook Documentation, Version 2.x

La classe Helper (Assistant) LeMeilleurQuiSoitHelper devra se trouver dans un fichier nomm


LeMeilleurQuiSoitHelper.php.
Chaque fichier sera situ dans le rpertoire appropri dans votre dossier app.
Conventions pour les Models et les Sources de donnes

Les noms de classe de model sont au singulier et en CamelCase. Person, BigPerson et ReallyBigPerson en
sont des exemples.
Les noms de tables correspondant aux models CakePHP sont au pluriel et utilisent le caractre soulign
(underscore). Les tables correspondantes aux models mentionns ci-dessus seront donc respectivement :
people, big_people, et really_big_people.
Note des traducteurs francophones : seul le dernier mot est au pluriel et tous les pluriels franais ne seront
pas compris par CakePHP sans lui indiquer prcisment (par exemple cheval/chevaux). Voir pour cela le
chapitre sur les inflexions.
Pour vous assurer de la syntaxe des mots pluriels et singuliers, vous pouvez utiliser la bibliothque utilitaire
Inflector. Voir la documentation sur Inflector pour plus dinformations.
Les noms des champs avec deux mots ou plus doivent tre avec des underscores comme ici : first_name.
Les cls trangres des relations hasMany, belongsTo ou hasOne sont reconnues par dfaut grce au nom
(singulier) du model associ, suivi de _id. Donc, si un Cuisinier hasMany Cake, la table cakes se rfrera
un cuisinier de la table cuisiniers via une cl trangre cuisinier_id. Pour une table avec un nom de plusieurs
mots comme type_categories, la cl trangre sera type_categorie_id.
Les tables de jointure utilises dans les relations hasAndBelongsToMany (HABTM) entre models doivent
tre nommes daprs le nom des tables des models quelles unissent, par ex des users qui sont lis par une
relation HABTM avec des groups seraient joints par une table groups_users et ces noms doivent tre dans
lordre alphabtique (pommes_zebres plutt que zebres_pommes).
Toutes les tables avec lesquelles les models de CakePHP interagissent ( lexception des tables de jointure),
ncessitent une cl primaire simple pour identifier chaque ligne de manire unique. Si vous souhaitez modliser une table qui na pas de cl primaire sur un seul champ, la convention de CakePHP veut quune cl
primaire sur un seul champ soit ajoute la table.
Si le nom de la cl primaire nest pas id, vous devez dfinir lattribut Model.primaryKey.
CakePHP naccepte pas les cls primaires composes. Dans lventualit o vous voulez manipuler directement les donnes de votre table de jointure, cela veut dire que vous devez soit utiliser les appels directs
query, soit ajouter une cl primaire pour tre en mesure dagir sur elle comme un model normal. Exemple :
CREATE TABLE posts_tags (
id INT(10) NOT NULL AUTO_INCREMENT,
post_id INT(10) NOT NULL,
tag_id INT(10) NOT NULL,
PRIMARY KEY(id
);

26

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

Plutt que dutiliser une cl auto-incrmente comme cl primaire, vous pouvez aussi utiliser un champ
char(36). CakePHP utilisera alors un UUID de 36 caractres (String : :uuid) lorsque vous sauvegardez un
nouvel enregistrement en utilisant la mthode Model : :save.
Conventions des vues

Les fichiers de vue sont nomms daprs les fonctions du controller quelles affichent, sous une forme avec
underscores. La fonction soyezPret() de la classe PersonnesController cherchera un gabarit de vue dans :
/app/View/Personnes/soyez_pret.ctp.
Le schma classique est /app/View/Controller/nom_de_fonction_avec_underscore.ctp.
En utilisant les conventions CakePHP dans le nommage des diffrentes parties de votre application, vous
gagnerez des fonctionnalits sans les tracas et les affres de la configuration. Voici un exemple rcapitulant
les conventions abordes :
Nom de la table dans la base de donnes : personnes
Classe du Model : Personne, se trouvant dans /app/Model/Personne.php
Classe du Controller : PersonnesController, se trouvant dans /app/Controller/PersonnesController.php
Template de Vue : se trouve dans /app/View/Personnes/index.ctp
En utilisant ces conventions, CakePHP sait quune requte de type http ://exemple.com/personnes/ sera
lie un appel la fonction index() du Controller PersonnesController, dans lequel le model Personne est
automatiquement disponible (et automatiquement li la table personnes dans la base) et rendue dans un
fichier. Aucune de ces relations na t configure par rien dautre que la cration des classes et des fichiers
dont vous aviez besoin de toute faon.
Maintenant que vous avez t initi aux fondamentaux de CakePHP, vous devriez essayer de drouler le
tutoriel du Blog CakePHP Tutoriel dun Blog pour voir comment les choses sarticulent.
Structure du dossier de CakePHP
Aprs avoir tlcharg et extrait CakePHP, voici les fichiers et rpertoires que vous devriez voir :
app
lib
vendors
plugins
.htaccess
index.php
README
Vous remarquerez trois dossiers principaux :
Le dossier app sera celui o vous exercerez votre magie : cest l que vous placerez les fichiers de votre
application.
Le dossier lib est lendroit o nous avons exerc notre propre magie. Engagez-vous personnellement ne
pas modifier les fichiers dans ce dossier. Nous ne pourrons pas vous aider si vous avez modifi le cur
du framework. A la place, regardez dans les Extensions de lApplication modifies.
Enfin, le dossier vendors est lendroit o vous placerez vos librairies PHP tierces dont vous avez besoin
pour vos applications CakePHP.

Blog Tutoriel - Ajouter la logique

27

CakePHP Cookbook Documentation, Version 2.x

Le dossier App

Le rpertoire app de CakePHP est lendroit o vous raliserez la majorit du dveloppement de votre application. Regardons de plus prs les dossier lintrieur de app.
Config Contient les (quelques) fichiers de configuration utiliss par CakePHP. Informations de connexion
la base de donnes, dmarrage, fichiers de configuration de base et tous fichiers du mme genre
doivent tre rangs ici.
Console Contient les commandes de la console et les Tasks de la console pour votre application. Ce rpertoire peut aussi contenir un rpertoire Templates pour personnaliser la sortie de bake. Pour plus
dinformations, regardez Shells, Tasks & Outils de Console.
Controller Contient vos Controllers et leurs Components.
Lib Contient les librairies qui ne proviennent pas de librairies externes. Cela vous permet de sparer les
librairies internes de votre organisme des librairies externes.
Locale Stocke les fichiers pour linternationalisation.
Model Pour les Models, Behaviors et Sources de Donnes de votre application.
Plugin Contient les packages des Plugins.
Test Ce rpertoire contient tous les cas de test, et les fixtures de test pour votre application. Le rpertoire
Test/Case devra reflter votre application et contenir un ou plusieurs cas de test par classe dans
votre application. Pour plus dinformations sur les cas de test et les fixtures de test, rfrez-vous la
documentation Testing.
tmp Cest ici que CakePHP enregistre les donnes temporaires. La manire dont sont stockes les donnes
actuelles dpend de la configuration que vous avez effectue, mais ce rpertoire est habituellement
utilis pour dposer les descriptions de models, les logs et parfois les informations de session.
Assurez-vous que ce dossier existe et quil est en criture, autrement la performance de votre application sera svrement impacte. En mode debug, CakePHP vous avertira si ce nest pas le cas.
Vendor Toute classe ou librairie tierce doit tre mise ici, de sorte quil sera facile dy accder par la fonction App : :import(vendor,name). Les observateurs aviss noteront que cela semble redondant avec
le rpertoire vendors la racine de larborescence. Nous aborderons les diffrences entre les deux
lorsque nous discuterons de la gestion multi-applications et des configurations systmes plus complexes.
View Les fichiers de prsentation sont placs ici : lments, pages derreur, helpers, layouts et vues.
webroot Dans un environnement de production, ce dossier doit tre la racine de votre application. Les
sous-rpertoires sont utiliss pour les feuilles de style CSS, les images et les fichiers Javascript.
Structure de CakePHP
CakePHP dispose de classes de Controllers (Contrleurs), de Models (Modles), et de Views (Vues), mais il
dispose de classes et objets supplmentaires qui rendent le dveloppement en MVC plus rapide et amusant.
Les Components (Composants), Behaviors (Comportements) et Helpers (Assistants) sont des classes qui
offrent une extensibilit et une rutilisation, permettant dajouter rapidement des fonctionnalits aux classes
MVC de base de vos applications. A ce stade de lecture, nous survolerons ces concepts, mais vous pourrez
dcouvrir comment utiliser ces outils en dtails plus tard.

28

Chapitre 1. Pour Commencer

CakePHP Cookbook Documentation, Version 2.x

Extensions de lApplication

Controllers, Helpers et Models ont chacun une classe parente, que vous pouvez utiliser pour dfinir des modifications impactant toute lapplication. AppController
(disponible
dans
/app/Controller/AppController.php),
AppHelper
(disponible dans /app/View/Helper/AppHelper.php) et AppModel (disponible dans
/app/Model/AppModel.php) sont de bons choix pour crire les mthodes que vous souhaitez
partager entre tous vos controllers, helpers ou models.
Bien quelles ne soient pas une classe ou un fichier, les Routes jouent un rle important dans les requtes
faites CakePHP. La dfinition des routes indique CakePHP comment lier les URLs aux actions des controllers. Le comportement par dfaut suppose que lURL /controller/action/var1/var2 renvoie
vers Controller::action($var1, $var2) et son action action qui prend deux paramtres
($var1, $var2). Mais vous pouvez utiliser les routes pour personnaliser les URLs et la manire dont elles
sont interprtes par votre application.
Il peut tre judicieux de regrouper certaines fonctionnalits. Un Greffon ou Plugin est un ensemble de
models, de controllers et de vues qui accomplissent une tche spcifique pouvant stendre plusieurs
applications. Un systme de gestion des utilisateurs ou un blog simplifi pourraient tre de bons exemples
de plugins CakePHP.
Extensions du Controller (Components)

Un Component (Composant) est une classe qui sintgre dans la logique du controller. Si vos controllers
ou vos applications doivent partager une logique, alors crer un Component est une bonne solution. A titre
dexemple, la classe intgre EmailComponent rend triviale la cration et lenvoi de courriels. Plutt que
dcrire une mthode dans un seul controller qui effectue ce traitement, vous pouvez empaqueter ce code et
ainsi le partager.
Les controllers sont galement quips de fonctions de rappel (callbacks). Ces fonctions sont votre disposition au cas o vous avez besoin dajouter du code entre les diffrentes oprations internes de CakePHP.
Les callbacks disponibles sont :
afterFilter(), excute aprs la logique du controller, y compris laffichage de la vue.
beforeFilter(), excute avant toute action dun controller.
beforeRender(), excute aprs toute action dun controller mais avant que la vue soit rendue.
Extensions du Model (Behaviors)

De mme, les Behaviors fonctionnent comme des passerelles pour ajouter une fonctionnalit commune
aux models. Par exemple, si vous stockez les donnes dun utilisateur dans une structure en arbre, vous
pouvez spcifier que votre model Utilisateur se comporte comme un arbre, et il acqurera automatiquement
la capacit de suppression, dajout, et de dplacement des noeuds dans votre structure en arbre sous-jacente.
Les models sont aussi soutenus par une autre classe nomme une DataSource (source de donnes). Il sagit
dune couche dabstraction qui permet aux models de manipuler diffrents types de donnes de manire
cohrente. La plupart du temps la source principale de donnes dans CakePHP est une base de donnes,
vous pouvez cependant crire des Sources de Donnes supplmentaires pour reprsenter des flux RSS, des
fichiers CSV, des entres LDAP ou des vnements iCal. Les Sources de Donnes vous permettent dassocier
Blog Tutoriel - Ajouter la logique

29

CakePHP Cookbook Documentation, Version 2.x

des enregistrements issus de sources diffrentes : plutt que dtre limit des jointures SQL, les Sources
de Donnes vous permettent de dire votre model LDAP quil est associ plusieurs vnements iCal.
Tout comme les controllers, les models ont des callbacks :
beforeFind()
afterFind()
beforeValidate()
afterValidate()
beforeSave()
afterSave()
beforeDelete()
afterDelete()
Les noms de ces mthodes devraient tre suffisamment explicites pour que vous compreniez leurs rles.
Vous obtiendrez plus de dtails dans le chaptre sur les models.
Extension de la Vue (Helpers)

Un Helper (Assistant) est une classe dassistance pour les vues. De mme que les components sont utiliss
par plusieurs controllers, les helpers permettent diffrentes vues daccder et de partager une mme logique
de prsentation. Lun des helpers intgrs Cake, AjaxHelper, facilite les requtes AJAX dans les vues.
La plupart des applications ont des portions de code pour les vues qui sont rptitives. CakePHP facilite la
rutilisabilit de ce code grce aux Layouts (mises en pages) et aux Elements. Par dfaut, toutes les vues
affiches par un controller ont le mme layout. Les elements sont utiliss lorsque de petites portions de
contenu doivent apparatre dans plusieurs vues.

30

Chapitre 1. Pour Commencer

CHAPITRE 2

Installation

CakePHP est rapide et facile installer. Les conditions minimum requises sont un serveur web et une copie
de CakePHP, cest tout ! Bien que ce manuel se focalise principalement sur la configuration avec Apache
(parce que cest le plus utilis couramment), vous pouvez configurer CakePHP pour lancer une diversit de
serveurs web tels que lighttpd ou Microsoft IIS.

Conditions requises
HTTP Server. Par exemple : Apache. mod_rewrite est prfrable, mais en aucun cas ncessaire.
PHP 5.3.0 ou plus (CakePHP version 2.6 et les versions infrieures supportent PHP 5.2.8 ou plus)..
Techniquement, un moteur de base de donnes nest pas ncessaire, mais nous imaginons que la plupart des
applications vont en utiliser un. CakePHP supporte une diversit de moteurs de stockage de donnes :
MySQL (4 ou plus)
PostgreSQL
Microsoft SQL Server
SQLite
Note : Tous les drivers intgrs requirent PDO. Vous devez vous assurer que vous avez les bonnes extensions PDO installes.

Licence
CakePHP est licenci sous la licence MIT. Cela signifie que vous tes libre de modifier, distribuer et reproduire le code source sous la condition que les informations de copyright restent intactes. Vous tes aussi
libres dincorporer CakePHP dans toute code source dapplication commerciale ou ferme.

31

CakePHP Cookbook Documentation, Version 2.x

Tlcharger CakePHP
Il y a deux faons dobtenir une copie rcente de CakePHP. Vous pouvez soit tlcharger une copie archive
de (zip/tar.gz/tar.bz2) partir du site web principal, soit faire un check out du code sur dpt de git.
Pour tlcharger la dernire version majeure de CakePHP, visitez le site web principal http ://cakephp.org et
suivez le lien Tlcharger maintenant.
Toutes les versions actuelles de CakePHP sont hberges sur Github 1 . Github hberge CakePHP lui-mme
ainsi que plusieurs autres plugins pour CakePHP. Les versions de CakePHP sont disponibles sur Tlchargements Github 2 .
Sinon, vous pouvez obtenir du code frais avec tous les correctifs de bug et jour des amliorations de
dernire minute. Celui-ci peut tre accessible partir de github en clonant le rpertoire de Github 3
git clone -b 2.x git://github.com/cakephp/cakephp.git

Permissions
CakePHP utilise le rpertoire app/tmp pour un certain nombre doprations. Les descriptions de Model,
les vues mises en cache, et les informations de session en sont juste quelques exemples.
De mme, assurez-vous que le rpertoire app/tmp et tous ses sous-rpertoires dans votre installation cake
sont en criture pour lutilisateur du serveur web.
Un problme habituel est que les rpertoires app/tmp et les sous-rpertoires doivent tre accessible en criture la fois pour le serveur web et et pour lutilisateur des lignes de commande. Sur un systme UNIX,
si votre serveur web est diffrent partir de lutilisateur en ligne de commande, vous pouvez lancer les
commandes suivantes juste une fois dans votre projet pour vous assurer que les permissions sont bien configures :

HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | h


setfacl -R -m u:${HTTPDUSER}:rwx app/tmp
setfacl -R -d -m u:${HTTPDUSER}:rwx app/tmp

Configuration
Configurer CakePHP est aussi simple que de le flanquer dans le document root de votre serveur web, ou aussi
complexe et flexible que vous le souhaitez. Cette section couvrira les trois types principaux dinstallation de
CakePHP : dveloppement, production, et avanc.
Dveloppement : Facile mettre en oeuvre, mais les URLs de lapplication contiennent le nom du rpertoire dinstallation de CakePHP et cest moins scuris.
Production : Ncessite dtre habilit configurer le Document Root du serveur, URLs propres, trs
scuris.
1. http ://github.com/cakephp/cakephp
2. https ://github.com/cakephp/cakephp/tags
3. http ://github.com/cakephp/cakephp

32

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

Avanc : Avec un peu de configuration, vous permet de placer les rpertoires cls de CakePHP diffrents
endroits du systme de fichiers, avec la possibilit de partager un seul rpertoire de la librairie centrale
CakePHP entre plusieurs applications.

Dveloppement
Une installation dveloppement est la mthode la plus rapide pour lancer CakePHP. Cet exemple vous aidera installer une application CakePHP et la rendre disponible ladresse
http ://www.example.com/cake_2_0/. Nous considrons pour les besoins de cet exemple que votre document root pointe sur /var/www/html.
Dcompressez le contenu de larchive CakePHP dans /var/www/html. Vous avez maintenant un dossier
dans votre document root, nomm daprs la version que vous avez tlcharge (par exemple : cake_2.0.0).
Renommez ce dossier en cake_2_0. Votre installation dveloppement devrait ressembler quelque
chose comme cela dans votre systme de fichiers :
/var/www/html/
cake_2_0/
app/
lib/
plugins/
vendors/
.htaccess
index.php
README

Si votre serveur web est configur correctement, vous devriez trouver maintenant votre application CakePHP
accessible ladresse http ://www.exemple.com/cake_2_0/.

Utiliser un CakePHP pour de multiples applications


Si vous dveloppez un certain nombre dapplications il peut sembler tre sens de partager le mme coeur
de CakePHP. Il y a peu de faon daccomplir cela. Souvent, le plus facile est dutiliser le include_path
de PHP. Pour commencer, copiez CakePHP dans un rpertoire. Pour cet exemple, nous utiliserons
/home/mark/projects :
git clone git://github.com/cakephp/cakephp.git /home/mark/projects/cakephp

Cela copiera CakePHP dans votre rpertoire /home/mark/projects. Si vous ne voulez pas utiliser
git, vous pouvez tlcharger un zipball et les tapes restantes seront les mmes. Ensuite, vous devrez localiser et modifier votre php.ini. Sur les systmes *nix, il se trouve souvent dans /etc/php.ini, mais
en utilisant php -i et en regardant Loaded Configuration File (Fichier de Configuration Charg). Une
fois que vous avez trouv le bon fichier ini, modifier la configuration de include_path pour inclure
/home/mark/projects/cakephp/lib. Un exemple ressemblerait cela :
include_path = .:/home/mark/projects/cakephp/lib:/usr/local/php/lib/php

Dveloppement

33

CakePHP Cookbook Documentation, Version 2.x

Aprs avoir redmarr votre serveur web, vous devriez voir les changements dans phpinfo().
Note : Si vous tes sur Windows, les chemins dinclusion sont spars par des ; au lieu de :
Une fois que vous avez configur votre include_path, vos applications devraient tre capable de trouver
automatiquement CakePHP.

Production
Une installation production est une faon plus flexible de lancer CakePHP. Utiliser cette mthode permet
tout un domaine dagir comme une seule application CakePHP. Cet exemple vous aidera installer CakePHP
nimporte o dans votre systme de fichiers et le rendre disponible ladresse : http ://www.exemple.com.
Notez que cette installation demande davoir les droits pour modifier le DocumentRoot sur le serveur web
Apache.
Dcompressez les contenus de larchive CakePHP dans un rpertoire de votre choix. Pour les besoins de cet
exemple, nous considrons que vous avez choisi dinstaller CakePHP dans /cake_install. Votre installation
de production devrait ressembler quelque chose comme ceci dans votre systme de fichiers :
/cake_install/
app/
webroot/ (ce rpertoire est dfini comme rpertoire
``DocumentRoot``)
lib/
plugins/
vendors/
.htaccess
index.php
README

Les dveloppeurs utilisant Apache devraient rgler la directive DocumentRoot pour le domaine :
DocumentRoot /cake_install/app/webroot

Si votre serveur web est configur correctement, vous devriez maintenant accder votre application
CakePHP accessible ladresse : http ://www.exemple.com.

Installation avance et URL Rewriting


Installation avance
Installer CakePHP avec linstalleur PEAR
CakePHP publie un package PEAR que vous pouvez installer en utilisant linstallateur PEAR. Linstallation
avec linstallateur PEAR peut simplifier le partage des librairies de CakePHP dans plusieurs applications.
Pour installer CakePHP avec PEAR, vous devrez faire comme suit :

34

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

pear channel-discover pear.cakephp.org


pear install cakephp/CakePHP

Note : Sur certains systmes, linstallation de librairies avec PEAR ncessitera la commande sudo.
Aprs avoir install CakePHP avec PEAR, si PEAR est configur correctement, vous devriez pouvoir
utiliser la commande cake pour crer une nouvelle application. Puisque CakePHP sera localis dans
linclude_path de PHP, vous naurez pas besoin de faire dautres changements.
Installer CakePHP avec Composer
Composer est un outil de gestion de dpendances pour PHP 5.3+. Il rgle plusieurs problmes que linstallateur PEAR a, et simplifie la gestion de plusieurs versions de librairies. Packagist 4 est le dpt principal
des packages installables avec Composer. Puisque CakePHP publie aussi les versions dans Packagist, vous
pouvez installer CakePHP en utilisant Composer 5 . Avant dinstaller CakePHP, vous devrez configurer un
fichier composer.json. Un fichier composer.json pour une application CakePHP ressemblerait ce qui
suit :
{
"name": "example-app",
"require": {
"cakephp/cakephp": "2.8.*"
},
"config": {
"vendor-dir": "Vendor/"
}
}

Sauvegardez ce JSON dans composer.json dans le rpetoire APP de votre projet. Ensuite, tlchargez
le fichier composer.phar dans votre projet. Aprs avoir tlcharg composer, installez CakePHP. Dans le
mme rpertoire que votre fichier composer.json, lancez ce qui suit :
$ php composer.phar install

Une fois que Composer a termin son excution, vous devriez avoir une structure de rpertoire qui ressemble
:
example-app/
composer.phar
composer.json
Vendor/
bin/
autoload.php
composer/
cakephp/
4. https ://packagist.org/
5. http ://getcomposer.org

Installation avance et URL Rewriting

35

CakePHP Cookbook Documentation, Version 2.x

Vous tes maintenant prt gnrer le reste du squelette de votre application :


$ Vendor/bin/cake bake project <path to project>

Par dfaut bake va mettre en dur CAKE_CORE_INCLUDE_PATH. Pour rendre votre application plus
portable, vous devrez modifier webroot/index.php, en changeant CAKE_CORE_INCLUDE_PATH en
un chemin relatif :
define(
'CAKE_CORE_INCLUDE_PATH',
APP . '/Vendor/cakephp/cakephp/lib'
);

Note : Si vous pensez crer des tests unitaires pour votre application, vous devrez aussi faire les changements ci-dessus dans webroot/test.php.
Si vous installez dautres librairies avec Composer, vous devrez configurer lautoloader et rgler un problme
dans lautoloader de Composer. Dans votre fichier Config/bootstrap.php, ajoutez ce qui suit :
// Charger l'autoload de Composer.
require APP . 'Vendor/autoload.php';
// Retire et rajoute l'autoloader de CakePHP puisque Composer pense que
// c'est le plus important.
// See http://goo.gl/kKVJO7
spl_autoload_unregister(array('App', 'load'));
spl_autoload_register(array('App', 'load'), true, true);

Vous devriez maintenant avoir une application CakePHP fonctionnelle avec CakePHP install via Composer.
Assurez-vous de garder les fichiers composer.json et composer.lock.json avec le reste de votre code source.
Partager les librairies de CakePHP pour plusieurs applications
Il peut y avoir des situations o vous voulez placer les rpertoires de CakePHP diffrents endroits du
systme de fichiers. Cela est peut tre d des restrictions de lhte partag, ou peut-tre souhaitez-vous
juste que quelques-unes de vos apps puissent partager les mmes librairies de CakePHP. Cette section dcrit
comment dployer vos rpertoires de CakePHP travers le systme de fichiers.
Premirement, ralisez quil y a trois parties principales dune application Cake :
1. Les librairies du coeur de CakePHP, dans /lib/Cake.
2. Le code de votre application, dans /app.
3. Le webroot de lapplication, habituellement dans /app/webroot.
Chacun de ces rpertoires peut tre situ nimporte o dans votre systme de fichier, avec lexception de webroot, qui a besoin dtre acessible pour votre serveur web. Vous pouvez mme dplacer le dossier webroot
en-dehors du dossier app tant que vous dtes CakePHP o vous le mettez.
Pour configurer votre installation de CakePHP, vous aurez besoin de faire quelques changements aux fichiers
suivants.
/app/webroot/index.php
36

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

/app/webroot/test.php (si vous utilisez la fonctionnalit de Testing.)


Il y a trois constantes que vous devrez modifier : ROOT, APP_DIR, et CAKE_CORE_INCLUDE_PATH.
ROOT doit tre dfinie vers le chemin du rpertoire qui contient le dossier app.
APP_DIR doit tre dfinie comme le nom (de base) de votre dossier app.
CAKE_CORE_INCLUDE_PATH doit tre dfinie comme le chemin du dossier des librairies de CakePHP.
Testons cela avec un exemple pour que vous puissiez voir quoi peut ressembler une installation avance
en pratique. Imaginez que je souhaite configurer CakePHP pour travailler comme ce qui suit :
Les librairies du coeur de CakePHP seront places dans /usr/lib/cake.
Le rpertoire webroot de lapplication sera /var/www/monsite/.
Le rpertoire app de mon application sera /home/me/monapp.
Etant donn ce type de configuration, jaurai besoin de modifier mon fichier webroot/index.php (qui finira
dans /var/www/mysite/index.php, dans cet exemple) pour ressembler ce qui suit :
// /app/webroot/index.php (partiel, commentaires retirs)
if (!defined('ROOT')) {
define('ROOT', DS . 'home' . DS . 'me');
}
if (!defined('APP_DIR')) {
define ('APP_DIR', 'myapp');
}
if (!defined('CAKE_CORE_INCLUDE_PATH')) {
define('CAKE_CORE_INCLUDE_PATH', DS . 'usr' . DS . 'lib');
}

Il est recommand dutiliser la constante DS plutt que des slashes pour dlimiter des chemins de fichier.
Cela empche les erreurs de fichiers manquants que vous pourriez obtenir en rsultats en utilisant le mauvais
dlimiteur, et cela rend votre code plus portable.
Apache et mod_rewrite (et .htaccess)
Cette section a t dplace vers URL rewriting.

URL Rewriting
Apache et mod_rewrite (et .htaccess)
Alors que CakePHP est construit pour travailler avec mod_rewrite et habituellement il lest nous avons
remarqu que certains utilisateurs se battent pour obtenir un bon fonctionnement sur leurs systmes.
Ici il y a quelques trucs que vous pourriez essayer pour que cela fonctionne correctement. Premirement,
regardez votre fichier httpd.conf (Assurez-vous que vous avez dit le httpd.conf du systme plutt que celui
dun utilisateur- ou le httpd.conf dun site spcifique).
Ces fichiers peuvent varier selon les diffrentes distributions et les versions dApache. Vous pouvez allez
voir http ://wiki.apache.org/httpd/DistrosDefaultLayout pour plus dinformations.

Installation avance et URL Rewriting

37

CakePHP Cookbook Documentation, Version 2.x

1. Assurez-vous quun .htaccess est permis et que AllowOverride est dfini All pour le bon DocumentRoot. Vous devriez voir quelque chose comme :
# Chaque rpertoire auquel Apache a accs peut tre configur avec
# respect pour lesquels les services et les fonctionnalits sont
# autoriss et/ou dsactivs dans ce rpertoire (et ses sous-rpertoires).
#
# Premirement, nous configurons "par dfault" pour tre un ensemble
# trs restrictif de fonctionnalits.
#
<Directory />
Options FollowSymLinks
AllowOverride All
#
Order deny,allow
#
Deny from all
</Directory>

Pour les utilisateurs qui ont apache 2.4 et suprieur, vous devez modifier le fichier de configuration
pour votre httpd.conf ou la configuration de lhte virtuel pour ressembler ce qui suit :
<Directory /var/www/>
Options FollowSymLinks
AllowOverride All
Require all granted
</Directory>

2. Assurez-vous que vous avez charg correctement mod_rewrite. Vous devriez voir quelque chose
comme :
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Dans la plupart des systmes, ceux-ci vont tre comments donc vous aurez juste besoin de retirer les
symboles # en dbut de ligne.
Aprs que vous avez fait des changements, re-dmarrez Apache pour tre sr que les paramtres soient
actifs.
Vrifiez que vos fichiers .htaccess sont effectivement dans le bon rpertoire.
Cela peut arriver pendant la copie parce que certains systmes dexploitation traitent les fichiers qui
commencent par . en cach et du coup ne les voient pas pour les copier.
3. Assurez-vous que votre copie de CakePHP vient de la section des tlchargements du site de notre
dpt Git, et a t dzipp correctement en vrifiant les fichiers .htaccess.
Le rpertoire root de CakePHP (a besoin dtre copi dans votre document, cela redirige tout vers
votre app CakePHP) :
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule
^$ app/webroot/
[L]
RewriteRule
(.*) app/webroot/$1 [L]
</IfModule>

Le rpertoire app de CakePHP (sera copi dans le rpertoire suprieur de votre application avec Bake) :

38

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule
^$
webroot/
RewriteRule
(.*) webroot/$1
</IfModule>

[L]
[L]

Le rpertoire webroot de CakePHP (sera copi dans le webroot de votre application avec Bake) :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,L]
</IfModule>

Si votre site CakePHP a toujours des problmes avec mod_rewrite, essayez de modifier les
paramtres pour les Htes Virtuels. Si vous tes sur Ubuntu, modifiez le fichier /etc/apache2/sitesavailable/default (lendroit dpend de la distribution). Dans ce fichier, assurez-vous que
AllowOverride None a t chang en AllowOverride All, donc vous devez avoir :
<Directory />
Options FollowSymLinks
AllowOverride All
</Directory>
<Directory /var/www>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order Allow,Deny
Allow from all
</Directory>

Si vous tes sur Mac OSX, une autre solution est dutiliser loutil virtualhostx 6 pour faire un Hte
Virtuel pour pointer vers votre dossier.
Pour beaucoup de services dhbergement (GoDaddy, 1and1), votre serveur web est en fait dj distribu partir dun rpertoire utilisateur qui utilise dj mod_rewrite. Si vous installez CakePHP dans
un rpertoire utilisateur (http ://exemple.com/~username/cakephp/), ou toute autre structure dURL
qui utilise dj mod_rewrite, vous aurez besoin dajouter les requtes (statements) RewriteBase aux
fichiers .htaccess que CakePHP utilise (/.htaccess, /app/.htaccess, /app/webroot/.htaccess).
Ceci peut tre ajout dans la mme section que la directive RewriteEngine, donc par exemple, votre
fichier .htaccess dans webroot ressemblerait ceci :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/cake/app
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,L]
</IfModule>

Les dtails de ces changements dpendront de votre configuration, et pourront inclure des choses
supplmentaires qui ne sont pas lies CakePHP. Merci de vous renseigner sur la documentation en
ligne dApache pour plus dinformations.
6. http ://clickontyler.com/virtualhostx/

Installation avance et URL Rewriting

39

CakePHP Cookbook Documentation, Version 2.x

4. (Optionel) Pour amliorer la configuration de production, vous devriez empcher les assets invalides
dtre parss par CakePHP. Modifiez votre webroot .htaccess pour quelque chose comme :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/cake/app
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !^/(app/webroot/)?(img|css|js)/(.*)$
RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

Ce qui est au-dessus va simplement empcher les assets incorrects dtre envoys index.php et la
place dafficher la page 404 de votre serveur web.
De plus, vous pouvez crer une page HTML 404 correspondante, ou utiliser la page 404 de CakePHP
intgre en ajoutant une directive ErrorDocument :
ErrorDocument 404 /404-not-found

De belles URLs sur nginx


nginx ne fait pas usage de fichiers .htaccess comme Apache et Lighttpd, il est donc ncessaire de crer les
URLs rcrites disponibles dans la configuration du site. selon votre configuration, vous devrez modifier
cela, mais tout le moins, vous aurez besoin de PHP fonctionnant comme une instance FastCGI.
server {
listen
80;
server_name www.example.com;
rewrite ^(.*) http://example.com$1 permanent;
}
server {
listen
80;
server_name example.com;
# root directive should be global
root
/var/www/example.com/public/app/webroot/;
index index.php;
access_log /var/www/example.com/log/access.log;
error_log /var/www/example.com/log/error.log;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
include /etc/nginx/fastcgi_params;
try_files $uri =404;
fastcgi_pass
127.0.0.1:9000;
fastcgi_index
index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

40

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

}
}

Si pour une raison exotique vous ne pouvez pas changer votre rpertoire racine et devez lancer votre projet
partir dun sous-dossier comme example.com/subfolder/, vous devrez injecter /webroot dans chaque
requte.
location ~ ^/(subfolder)/(.*)? {
index index.php;
set $new_uri /$1/webroot/$2;
try_files $new_uri $new_uri/ /$1/index.php?$args;
... php handling ...
}

Note : Les rcentes configurations de PHP-FPM sont dfinies pour couter sur le socket php-fpm au lieu
du port TCP 9000 sur ladresse 127.0.0.1. Si vous obtenez une erreur 502 de mauvaise passerelle avec la
configuration du dessus, essayez de remplacer le port TCP du fastcgi_pass par le chemin du socket (ex :
fastcgi_pass unix :/var/run/php5-fpm.sock ;).

Rewrites dURL sur IIS7 (serveurs Windows)


IIS7 ne supporte pas nativement les fichiers .htaccess. Bien quil existe des add-ons qui peuvent ajouter
ce support, vous pouvez aussi importer les rgles des .htaccess dans IIS pour utiliser les rewrites natifs de
CakePHP. Pour ce faire, suivez ces tapes :
1. Utilisez linstalleur de la plateforme Web de Microsoft 7 pour installer lURL Rewrite Module 2.0 8
ou tlchargez le directement (32-bit 9 / 64-bit 10 ).
2. Crez un nouveau fichier dans votre dossier CakePHP, appel web.config.
3. Utilisez Notepad ou tout autre diteur XML-safe, copiez le code suivant dans votre nouveau fichier
web.config...
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Rewrite requests to test.php"
stopProcessing="true">
<match url="^test.php(.*)$" ignoreCase="false" />
<action type="Rewrite" url="app/webroot/test.php{R:1}" />
</rule>
<rule name="Exclude direct access to app/webroot/*"
stopProcessing="true">
7.
8.
9.
10.

http ://www.microsoft.com/web/downloads/platform.aspx
http ://www.iis.net/downloads/microsoft/url-rewrite
http ://www.microsoft.com/en-us/download/details.aspx ?id=5747
http ://www.microsoft.com/en-us/download/details.aspx ?id=7435

Installation avance et URL Rewriting

41

CakePHP Cookbook Documentation, Version 2.x

<match url="^app/webroot/(.*)$" ignoreCase="false" />


<action type="None" />
</rule>
<rule name="Rewrite routed access to assets(img, css, files, js, favicon)"
stopProcessing="true">
<match url="^(img|css|files|js|favicon.ico)(.*)$" />
<action type="Rewrite" url="app/webroot/{R:1}{R:2}"
appendQueryString="false" />
</rule>
<rule name="Rewrite requested file/folder to index.php"
stopProcessing="true">
<match url="^(.*)$" ignoreCase="false" />
<action type="Rewrite" url="index.php"
appendQueryString="true" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>

Une fois que le fichier web.config est cr avec les bonnes rgles de rcriture des liens de IIS, les liens
CakePHP, les CSS, le JavaScript, et le reroutage devraient fonctionner correctement.
URL-Rewriting sur lighttpd
Lighttpd ne supporte pas les fonctions .htaccess, par consquent vous pouvez retirer tous les fichiers .htaccess. Dans la configuration lighttpd, assurez-vous dactiver mod_rewrite. Ajoutez une ligne :
url.rewrite-if-not-file =(
"^([^\?]*)(\?(.+))?$" => "/index.php?url=$1&$3"
)

Rgles de rewrite URL pour Hiawatha


La rgle ncessaire UrlToolkit (pour le rewriting URL) pour utiliser CakePHP avec Hiawatha est :
UrlToolkit {
ToolkitID = cakephp
RequestURI exists Return
Match .* Rewrite /index.php
}

Je ne veux / ne peux utiliser lURL rewriting


Si vous ne voulez ou ne pouvez pas utiliser lURL rewriting sur votre serveur web, rfrez-vous la section
core configuration.

42

Chapitre 2. Installation

CakePHP Cookbook Documentation, Version 2.x

A vous de jouer !
Ok, voyons voir CakePHP en action. Selon la configuration que vous utilisez, vous pouvez pointer votre
navigateur vers http ://exemple.com/ ou http ://exemple.com/cake_install/. A ce niveau, vous serez sur la
page home par dfaut de CakePHP, et un message qui vous donnera le statut de la connexion de votre base
de donnes courante.
Flicitations ! Vous tes prt crer votre premire application CakePHP.
Cela ne fonctionne pas ? Si vous avez une erreur lie au timezone de PHP, dcommentez la ligne dans
app/Config/core.php :
/**
* Dcommentez cette ligne et corrigez votre serveur de timezone pour rgler
* toute erreur lie la date & au temps.
*/
date_default_timezone_set('UTC');

A vous de jouer !

43

CakePHP Cookbook Documentation, Version 2.x

44

Chapitre 2. Installation

CHAPITRE 3

Dbuter avec CakePHP

Bienvenue dans le CookBook, le manuel du framework dapplications web, CakePHP. Avec CakePHP,
dvelopper cest du gteau !
Lire ce manuel suppose que vous ayez une connaissance gnrale de PHP et une connaissance de base
de la programmation oriente-objet (POO). Certaines fonctionnalits livres avec le framework entranent
lutilisation de technologies diffrentes - comme SQL, JavaScript et XML - que ce manuel ne tente pas
dexpliquer, il indique seulement de quelle manire elles sont utilises dans ce contexte.

Quest ce que CakePHP ? Pourquoi lUtiliser ?


CakePHP 1 est un framework 2 pour PHP 3 gratuit 4 , open-source 5 , de dveloppement rapide 6 . Cest une
structure fondamentale pour les programmeurs pour crer des applications web. Notre principal objectif est
de vous permettre de travailler dune manire structure et rapide sans perte de flexibilit.
CakePHP rompt la monotonie du dveloppement web. Il vous offre tous les outils ncessaires pour ne coder
que ce dont vous avez rellement besoin : la logique spcifique de votre application.
Au lieu de rinventer la roue chaque fois que vous dmarrez un nouveau projet, rcuprez une copie de
CakePHP et concentrez-vous sur la logique de votre application.
CakePHP dispose dune quipe de dveloppement 7 et dune communaut actives, qui donnent au projet une
forte valeur ajoute. En plus de vous viter de r-inventer la roue, lutilisation de CakePHP implique que le
coeur de votre application est bien test et quil peut tre constamment amlior.
Voici un aperu rapide des caractristiques que vous apprcierez en utilisant CakePHP :
Communaut active et sympathique :ref :cakephp-official-communities.
1.
2.
3.
4.
5.
6.
7.

http ://www.cakephp.org/
http ://en.wikipedia.org/wiki/Application_framework
http ://www.php.net/
http ://en.wikipedia.org/wiki/MIT_License
http ://en.wikipedia.org/wiki/Open_source
http ://en.wikipedia.org/wiki/Rapid_application_development
http ://github.com/cakephp/cakephp/contributors

45

CakePHP Cookbook Documentation, Version 2.x

Systme de licence souple 8 .


Compatible avec les versions PHP 5.2.8 et suprieures.
Fonctions CRUD 9 . (create, read, update, delete) intgres pour les interactions avec la base de donnes.
Scaffolding 10 (maquettage rapide) dapplication.
Gnration de code.
Architecture MVC 11 .
Dispatcheur de requtes avec des URLs propres et personnalisables grce un systme de routes.
Validation intgre des donnes 12 .
Systme de template 13 rapide et souple (syntaxe PHP avec des Helpers).
Helpers (assistants) de vue pour AJAX, JavaScript, formulaires HTML...
Components (composants) intgrs : Email, Cookie, Security, Session et Request Handling.
Systme de contrle daccs ACL 14 flexible.
Nettoyage des donnes.
Systme de cache 15 souple.
Localisation et internationalisation.
Fonctionne sur nimporte quelle arborescence de site web, avec un zest de configuration Apache 16 pas
trs complique.

Comprendre le systme M-V-C (Model-View-Controller)


CakePHP suit le motif de conception logicielle MVC 17 . Programmer en utilisant MVC spare votre application en 3 couches principales :

La couche Model
La couche Model reprsente la partie de lapplication qui excute la logique mtier. Cela signifie quelle
est responsable de rcuprer les donnes, de les convertir selon des concepts chargs de sens pour votre
application, tels que le traitement, la validation, lassociation et beaucoup dautres tches concernant la
manipulation des donnes.
A premire vue, lobjet Model peut tre vu comme la premire couche dinteraction avec nimporte quelle
base de donnes que vous pourriez utiliser pour votre application. Mais plus globalement, il fait partie des
concepts majeurs autour desquels vous allez excuter votre application.
Dans le cas dun rseau social, la couche Model soccupe des tches comme de sauvegarder des donnes, de
sauvegarder des associations damis, denregistrer et de rcuprer les photos des utilisateurs, de trouver des
suggestions de nouveaux amis, etc ... Tandis que les objets Models seront Ami, User, Commentaire,
Photo.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

46

http ://en.wikipedia.org/wiki/MIT_License
http ://en.wikipedia.org/wiki/Create,_read,_update_and_delete
http ://en.wikipedia.org/wiki/Scaffold_(programming)
http ://en.wikipedia.org/wiki/Model-view-controller
http ://en.wikipedia.org/wiki/Data_validation
http ://en.wikipedia.org/wiki/Web_template_system
http ://en.wikipedia.org/wiki/Access_control_list
http ://en.wikipedia.org/wiki/Web_cache
http ://httpd.apache.org/
http ://en.wikipedia.org/wiki/Model-view-controller

Chapitre 3. Dbuter avec CakePHP

CakePHP Cookbook Documentation, Version 2.x

La couche Vue
La Vue retourne une prsentation des donnes venant du model. Etant spare par les Objets Model, elle est
responsable de lutilisation des informations dont elle dispose pour produire une interface de prsentation
de votre application.
Par exemple, de la mme manire que la couche Model retourne un ensemble de donnes, la Vue utilise
ces donnes pour fournir une page HTML les contenant. Ou un rsultat XML format pour que dautres
lutilisent.
La couche Vue nest pas seulement limite au HTML ou la rpresentation en texte de donnes. Elle peut
aussi tre utilise pour offrir une grande varit de formats en fonction de vos besoins, comme les vidos, la
musique, les documents et tout autre format auquel vous pouvez penser.

La couche Controller
La couche Controller gre les requtes des utilisateurs. Elle est responsable de retourner une rponse avec
laide mutuelle des couches Model et Vue.
Les Controllers peuvent tre imagins comme des managers qui ont pour mission que toutes les ressources
souhaites pour accomplir une tche soient dlgues aux travailleurs corrects. Il attend des requtes
des clients, vrifie leur validit selon lauthentification et les rgles dautorisation, dlguent les donnes
rcupres et traites par le Model, et slectionne les type de prsentation correctes que le client accepte,
pour finalement dlguer le processus daffichage la couche Vue.

Cycle de la requte CakePHP

Figure : 1 : Une requte MVC basique


Figure : 1 Montre la gestion typique dune requte client dans CakePHP
Le cycle dune requte CakePHP typique dbute avec une requte utilisateur qui demande une page ou une
ressource dans votre application. Cette requte est dabord traite par le dispatcheur, qui va slectionner

Comprendre le systme M-V-C (Model-View-Controller)

47

CakePHP Cookbook Documentation, Version 2.x

lobjet controller correct traitant la requte.


Une fois que la requte arrive au controller, celui-ci va communiquer avec la couche Model pour traiter
la rcupration de donnes ou les oprations de sauvegarde qui seraient ncessaires. Cette communication
termine, le controller va donner lobjet vue correct, la tche de gnrer une sortie rsultant des donnes
fournies par le model.
Finalement, quand cette sortie est gnre, elle est immdiatement rendue lutilisateur.
Presque chaque requte de votre application va suivre ce schma classique. Nous ajouterons des dtails plus
tard qui sont spcifiques CakePHP, donc gardez cela lesprit pour la suite.

Bnfices
Pourquoi utiliser CakePHP ? Parce que cest un logiciel vraiment construit selon le patron MVC, qui transforme une application en un dossier labor maintenable, modulable et rapide. Elaborer les tches de lapplication en sparant les models, vues et controllers, allgent votre application. De nouvelles fonctionnalits
sont ajoutes facilement, et les amliorations sur les vieilles fonctionnalits se font en un clin dil. La
conception modulable et spare permet aussi aux dveloppeurs et designeurs de travailler simultanment,
avec la possibilit de prototyper 18 rapidement : La sparation permet aussi aux dveloppeurs de faire des
changements dans une seule partie de lapplication sans affecter les autres.
Si vous navez jamais construit une application de cette manire, cela prend quelques temps pour shabituer,
mais nous sommes confiants quune fois votre premire application construite avec CakePHP, vous ne
voudrez plus faire dune autre faon.
Pour commencer votre premire application CakePHP, Essayez le tutoriel du Blog maintenant

O obtenir de laide
Le site officiel de CakePHP
http ://www.cakephp.org
Le site officiel de CakePHP est toujours un endroit patant visiter. Il propose des liens vers des outils frquemment utiliss par le dveloppeur, des didacticiels vido, des possibilits de faire un don et des
tlchargements.

Le Cookbook
http ://book.cakephp.org
Ce manuel devrait probablement tre le premier endroit o vous rendre pour obtenir des rponses. Comme
pour beaucoup dautres projets open source, nous accueillons de nouvelles personnes rgulirement. Fates
tout votre possible pour rpondre vos questions vous-mme dans un premier temps. Les rponses peuvent
venir lentement, mais elles resteront longtemps et vous aurez ainsi allg notre charge de travail en support
utilisateur. Le manuel et lAPI ont tous deux une version en ligne.
18. http ://en.wikipedia.org/wiki/Software_prototyping

48

Chapitre 3. Dbuter avec CakePHP

CakePHP Cookbook Documentation, Version 2.x

La Boulangerie
http ://bakery.cakephp.org
La Boulangerie (Bakery) est une chambre de compensation pour tout ce qui concerne CakePHP. Vous y
trouverez des tutoriels, des tudes de cas et des exemples de code. Lorsque vous serez familiariss avec
CakePHP, connectez-vous pour partager vos connaissances avec la communaut et obtenez en un instant la
gloire et la fortune.

LAPI
http ://api.cakephp.org/
Allez droit au but et atteignez le graal des dveloppeurs, lAPI CakePHP (Application Programming Interface) est la documentation la plus complte sur tous les dtails essentiels au fonctionnement interne du
framework. Cest une rfrence directe au code, donc apportez votre chapeau hlice.

Les cas de Test


Si vous avez toujours le sentiment que linformation fournie par lAPI est insuffisante, regardez le code des
cas de test fournis avec CakePHP. Ils peuvent servir dexemples pratiques pour lutilisation dune fonction
et de donnes membres dune classe.
lib/Cake/Test/Case

Le canal IRC
Canaux IRC sur irc.freenode.net :
#cakephp Discussion gnrale.
#cakephp-docs Documentation.
#cakephp-bakery Bakery.
#cakephp-fr Canal francophone.
Si vous tes paum, poussez un hurlement sur le canal IRC de CakePHP. Une personne de lquipe de
dveloppement 19 sy trouve habituellement, en particulier durant les heures du jour pour les utilisateurs
dAmrique du Nord et du Sud. Nous serions ravis de vous couter, que vous ayez besoin dun peu daide,
que vous vouliez trouver des utilisateurs dans votre rgion ou que vous souhaitiez donner votre nouvelle
marque de voiture sportive.

Communauts Officiels CakePHP


CakePHP Google Group 20
CakePHP a aussi son groupe officiel sur Google Groups. Il y a des centaines de personne qui discutent des
projets CakePHP, qui saident les uns les autres, rsolvent des problmes, qui construisent des projets et
19. https ://github.com/cakephp ?tab=members
20. http ://groups.google.com/group/cake-php

O obtenir de laide

49

CakePHP Cookbook Documentation, Version 2.x

partagent leurs ides. Cela peut tre une grande ressource pour trouver des rponses archives, des questions frquemment poses et obtenir des rponses aux problmes urgents. Rejoignez dautres utilisateurs de
CakePHP dans les communauts suivantes.

Stackoverflow
http ://stackoverflow.com/ 21
Tagge vos questions avec cakephp et la version spcifique que vous utilisez pour permettre aux utilisateurs
existant de stackoverflow de trouver vos questions.

Where to get Help in your Language


French
French CakePHP Community 22

21. http ://stackoverflow.com/questions/tagged/cakephp/


22. http ://cakephp-fr.org

50

Chapitre 3. Dbuter avec CakePHP

CHAPITRE 4

Controllers (Contrleurs)

Les Controllers sont le C dans MVC. Aprs que le routage a t appliqu et que le bon controller a t
trouv, laction de votre controller est appele. Votre controller devra grer linterprtation des donnes
requtes, sassurer que les bons models sont appels et que la bonne rponse ou vue est rendue. Les controllers peuvent tre imagins comme un homme au milieu entre le Model et la Vue. Le mieux est de garder
des controllers peu chargs, et des models plus fournis. Cela vous aidera rutiliser plus facilement votre
code et facilitera le test de votre code.
Habituellement, les controllers sont utiliss pour grer la logique autour dun seul model. Par exemple, si
vous construisez un site pour grer une boulangerie en-ligne, vous aurez sans doute un RecettesController
qui gre vos recettes et un IngredientsController qui gre vos ingrdients. Cependant, il est aussi possible
davoir des controllers qui fonctionnent avec plus dun model. Dans CakePHP, un controller est nomm
daprs le model principal quil gre.
Les controllers de votre application sont des classes qui tendent la classe CakePHP AppController, qui
hrite elle-mme de la classe Controller du cur. La classe AppController peut tre dfinie dans
/app/Controller/AppController.php et elle devrait contenir les mthodes partages par tous les
controllers de votre application.
Les controllers peuvent inclure un certain nombre de mthodes qui grent les requtes. Celles-ci sont appeles des actions. Par dfaut, chaque mthode publique dans un controller est une action accessible via une
URL. Une action est responsable de linterprtation des requtes et de la cration de la rponse. Habituellement, les rponses sont sous forme de vue rendue, mais il y a aussi dautres faons de crer des rponses.

Le Controller App
Comme indiqu dans lintroduction, la classe AppController est la classe mre de tous les controllers
de votre application. AppController tend elle-mme la classe Controller incluse dans la librairie
du cur de CakePHP. AppController est dfinie dans /app/Controller/AppController.php
comme ceci :
class AppController extends Controller {
}

51

CakePHP Cookbook Documentation, Version 2.x

Les attributs et mthodes de controller crs dans AppController seront disponibles dans tous les controllers de votre application. Les Components (que vous dcouvrirez plus loin) sont mieux appropris pour
du code utilis dans la plupart (mais pas ncessairement tous) des controllers.
Bien que les rgles habituelles dhritage de la programmation oriente objet soient appliques, CakePHP
excute galement un travail supplmentaire si des attributs spcifiques des controllers sont fournis, comme
les components ou helpers utiliss par un controller. Dans ces situations, les valeurs des tableaux de
AppController sont fusionnes avec les tableaux de la classe controller enfant. Les valeurs dans la
classe enfant vont toujours surcharger celles dans AppController.
Note : CakePHP fusionne les variables suivantes de la classe AppController avec celles des controllers
de votre application :
$components
$helpers
$uses
Noubliez pas dajouter les helpers Html et Form si vous avez dfini la proprit $helpers dans votre
classe AppController.
Pensez aussi appeler les fonctions de rappel (callbacks) de AppController dans celles du controller enfant
pour de meilleurs rsultats :
public function beforeFilter() {
parent::beforeFilter();
}

Les paramtres de requte


Quand une requte est fate dans une application CakePHP, Les classes Router et Dispatcher de
CakePHP utilisent la Configuration des Routes pour trouver et crer le bon controller. La requte de donnes
est encapsule dans un objet request. CakePHP met toutes les informations importantes de la requte dans
la proprit $this->request. Regardez la section CakeRequest pour plus dinformations sur lobjet
request de CakePHP.

Les Actions du Controller


Les actions du Controller sont responsables de la conversion des paramtres de la requte dans une rponse
pour le navigateur/utilisateur faisant la requte. CakePHP utilise les conventions pour automatiser le processus et retirer quelques codes boiler-plate que vous auriez besoin dcrire autrement.
Par convention, CakePHP rend une vue avec une version inflecte du nom de laction.
Revenons notre boulangerie en-ligne par exemple, notre RecipesController pourrait contenir les actions view(), share(), et search(). Le controller serait trouv dans
/app/Controller/RecettesController.php et contiendrait :

52

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

# /app/Controller/RecettesController.php
class RecettesController extends AppController {
public function view($id) {
//la logique de l'action va ici..
}
public function share($client_id, $recette_id) {
//la logique de l'action va ici..
}
public function search($query) {
//la logique de l'action va ici..
}
}

Les fichiers de vue pour ces actions seraient app/View/Recettes/view.ctp,


app/View/Recettes/share.ctp, et app/View/Recettes/search.ctp. Le nom du
fichier de vue est par convention le nom de laction en minuscules et avec des underscores.
Les actions du Controller utilisent gnralement set() pour crer un contexte que View utilise pour rendre
la vue. Du fait des conventions que CakePHP utilise, vous navez pas crer et rendre la vue manuellement.
Au lieu de a, une fois quune action du controller est termine, CakePHP va grer le rendu et la livraison
de la Vue.
Si pour certaines raisons, vous voulez viter le comportement par dfaut, les deux techniques suivantes ne
vont pas appliquer le comportement de rendu par dfaut de la vue.
Si vous retournez une chane de caractres, ou un objet qui peut tre converti en une chane de caractres
partir dune action du controller, elle sera utilise comme contenu de rponse.
Vous pouvez retourner un objet CakeResponse avec la rponse compltement cre.
Quand vous utilisez les mthodes du controller avec requestAction(), vous voudrez souvent retourner
les donnes qui ne sont pas des chanes de caractre. Si vous avez des mthodes du controller qui sont
utilises pour des requtes web normales + requestAction, vous devrez vrifier le type de requte avant de
retourner :
class RecipesController extends AppController {
public function popular() {
$popular = $this->Recipe->popular();
if (!empty($this->request->params['requested'])) {
return $popular;
}
$this->set('popular', $popular);
}
}

Le controller ci-dessus est un exemple montrant comment la mthode peut tre utilise avec
requestAction() et des requtes normales. Retourner un tableau de donnes une requte nonrequestAction va entraner des erreurs et devra tre vit. Regardez la section sur requestAction()
pour plus dastuces sur lutilisation de requestAction().
Afin que vous utilisiez efficacement le controller dans votre propre application, nous couvrons certains des
attributs et mthodes du coeur fournis par les controllers de CakePHP.
Les Actions du Controller

53

CakePHP Cookbook Documentation, Version 2.x

Request Life-cycle callbacks


class Controller
Les controllers de CakePHP sont livrs par dfaut avec des mthodes de rappel (ou callback) que vous
pouvez utiliser pour insrer de la logique juste avant ou juste aprs que les actions du controller soient
effectues :
Controller::beforeFilter()
Cette fonction est excute avant chaque action du controller. Cest un endroit pratique pour vrifier
le statut dune session ou les permissions dun utilisateur.
Note : La mthode beforeFilter() sera appele pour les actions manquantes et les actions de scaffolding.
Controller::beforeRender()
Cette mthode est appele aprs laction du controller mais avant que la vue ne soit rendue. Ce callback nest pas souvent utilis, mais peut-tre ncessaire si vous appellez render() manuellement
la fin dune action donne.
Controller::afterFilter()
Cette mthode est appele aprs chaque action du controller, et aprs que laffichage soit termin.
Cest la dernire mthode du controller qui est excute.
En plus des callbacks des controllers, les Components (Composants) fournissent aussi un ensemble similaire
de callbacks.

Les Mthodes du Controller


Pour une liste complte des mthodes de controller avec leurs descriptions, consultez lAPI de CakePHP 1 .

Interactions avec les vues


Les Controllers interagissent avec les vues de plusieurs faons. Premirement, ils sont capables de passer
des donnes aux vues, en utilisant set(). Vous pouvez aussi dcider quelle classe de vue utiliser, et quel
fichier de vue doit tre rendu partir du controller.
Controller::set(string $var, mixed $value)
La mthode set() est la voie principale utilise pour transmettre des donnes de votre controller
votre vue. Une fois set() utilise, la variable de votre controller devient accessible par la vue :
// Dans un premier temps vous passez les donnes depuis le controller:
$this->set('couleur', 'rose');
// Ensuite vous pouvez les utiliser dans la vue de cette manire:
?>
1. http ://api.cakephp.org/2.4/class-Controller.html

54

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Vous avez slectionn un glaage <?php echo $couleur; ?> pour le gteau.

La mthode set() peut galement prendre un tableau associatif comme premier paramtre. Cela
peut souvent tre une manire rapide daffecter en une seule fois un jeu complet dinformations la
vue :
$data = array(
'couleur' => 'rose',
'type' => 'sucre',
'prix_de_base' => 23.95
);
// donne $couleur, $type, et $prix_de_base
// disponible dans la vue:
$this->set($data);

Lattribut $pageTitle nexiste plus. Utilisez set() pour dfinir le titre :


$this->set('title_for_layout', 'Ceci est la page titre');

Depuis 2.5 la variable $title_for_layout est dprcie, utilisez les blocks de vues la place.
Controller::render(string $view, string $layout)
La mthode render() est automatiquement appele la fin de chaque action excute par le controller. Cette mthode excute toute la logique lie la prsentation (en utilisant les variables transmises via la mthode set()), place le contenu de la vue lintrieur de son $layout et transmet
le tout lutilisateur final.
Le fichier de vue utilis par dfaut est dtermin par convention. Ainsi, si laction search() de notre
controller RecettesController est demande, le fichier de vue situ dans /app/view/recettes/search.ctp
sera utilis :
class RecettesController extends AppController {
// ...
public function search() {
// Rend la vue dans /View/Recettes/search.ctp
$this->render();
}
// ...
}

Bien que CakePHP appelle cette fonction automatiquement la fin de chaque action ( moins que
vous nayez dfini $this->autoRender false), vous pouvez lutiliser pour spcifier un fichier
de vue alternatif en prcisant le nom dune action dans le controller, via le paramtre $view.
Si $view commence avec un / on suppose que cest un fichier de vue ou un lment dont le chemin
est relatif au dossier /app/View. Cela permet un affichage direct des lments, ce qui est trs pratique lors dappels AJAX.
// Rend un lment dans /View/Elements/ajaxreturn.ctp
$this->render('/Elements/ajaxreturn');

Le paramtre $layout vous permet de spcifier le layout de la vue qui est rendue.

Les Mthodes du Controller

55

CakePHP Cookbook Documentation, Version 2.x

Rendre une vue spcifique


Dans votre controller, vous pourriez avoir envie de rendre une vue diffrente de celle rendue par dfaut.
Vous pouvez faire cela en appelant directement render(). Une fois que vous avez appel render()
CakePHP nessaiera pas de re-rendre la vue :
class PostsController extends AppController {
public function mon_action() {
$this->render('fichier_personnalise');
}
}

Cela
rendrait
app/View/Posts/fichier_personnalise.ctp
app/View/Posts/mon_action.ctp.

au

lieu

Vous pouvez aussi rendre les vues des plugins en utilisant la syntaxe suivante
$this->render(PluginName.PluginController/custom_file). Par exemple :

de
:

class PostsController extends AppController {


public function my_action() {
$this->render('Users.UserDetails/custom_file');
}
}

Cela rendrait la vue app/Plugin/Users/View/UserDetails/custom_file.ctp

Contrle de Flux
Controller::redirect(mixed $url, integer $status, boolean $exit)
La mthode de contrle de flux que vous utiliserez le plus souvent est redirect(). Cette mthode
prend son premier paramtre sous la forme dune URL relative votre application CakePHP. Quand
un utilisateur a ralis un paiement avec succs, vous aimeriez le rediriger vers un cran affichant le
reu.
public function regler_achats() {
// Placez ici la logique pour finaliser l'achat...
if ($success) {
return $this->redirect(
array('controller' => 'paiements', 'action' => 'remerciements')
);
} else {
return $this->redirect(
array('controller' => 'paiements', 'action' => 'confirmations')
);
}
}

Vous pouvez aussi utiliser une URL relative ou absolue avec $url :
$this->redirect('/paiements/remerciements');
$this->redirect('http://www.exemple.com');

56

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Vous pouvez aussi passer des donnes laction :


$this->redirect(array('action' => 'editer', $id));

Le second paramtre de la fonction redirect() vous permet de dfinir un code de statut HTTP
accompagnant la redirection. Vous aurez peut-tre besoin dutiliser le code 301 (document dplac de
faon permanente) ou 303 (voir ailleurs), en fonction de la nature de la redirection.
Cette mthode ralise un exit() aprs la redirection, tant que vous ne mettez pas le troisime
paramtre false.
Si vous avez besoin de rediriger la page appelante, vous pouvez utiliser :
$this->redirect($this->referer());

Cette mthode supporte aussi les paramtres nomms de base. Si vous souhaitez tre redirig sur une
URL comme : http://www.example.com/commandes/confirmation/produit:pizza/quantite:
vous pouvez utiliser :
$this->redirect(array(
'controller' => 'commandes',
'action' => 'confirmation',
'produit' => 'pizza',
'quantite' => 5
));

Un exemple dutilisation des requtes en chanes et hashs ressemblerait ceci :


$this->redirect(array(
'controller' => 'commandes',
'action' => 'confirmation',
'?' => array(
'produit' => 'pizza',
'quantite' => 5
),
'#' => 'top'
));

LURL gnr serait : http://www.example.com/commandes/confirmation?produit=pizza&qua


Controller::flash(string $message, string|array $url, integer $pause, string $layout)
Tout comme redirect(), la mthode flash() est utilise pour rediriger un utilisateur vers une
autre page la fin dune opration. La mthode flash() est toutefois diffrente en ce sens quelle
affiche un message avant de diriger lutilisateur vers une autre url.
Le premier paramtre devrait contenir le message qui sera affich et le second paramtre une URL
relative votre application CakePHP. CakePHP affichera le $message pendant $pause secondes
avant de rediriger lutilisateur.
Si vous souhaitez utiliser un template particulier pour messages flash, vous pouvez spcifier le nom
du layout dans le paramtre $layout.
Pour dfinir des messages flash dans une page, regardez du ct de la mthode
SessionComponent::setFlash() du component Session (SessionComponent).

Les Mthodes du Controller

57

CakePHP Cookbook Documentation, Version 2.x

Callbacks
En plus des Request Life-cycle callbacks, CakePHP supporte aussi les callbacks lis au scaffolding.
Controller::beforeScaffold($method)
$method nom de la mthode appele, par exemple index, edit, etc.
Controller::afterScaffoldSave($method)
$method nom de la mthode appele, soit edit soit update.
Controller::afterScaffoldSaveError($method)
$method nom de la mthode appele, soit edit soit update.
Controller::scaffoldError($method)
$method nom de la mthode appele, par exemple index, edit, etc...

Autres Mthodes utiles


Controller::constructClasses()
Cette mthode charge en mmoire les models ncessaires au controller. Cette procdure de chargement est normalement effectue par CakePHP, mais cette mthode est garder sous le coude quand
vous avez besoin daccder certains controllers dans une autre perspective. Si vous avez besoin de CakePHP dans un script utilisable en ligne de commande ou dautres utilisations externes,
constructClasses() peut devenir pratique.
Controller::referer(mixed $default = null, boolean $local = false)
Retourne lURL rfrente de la requte courante. Le paramtre $default peut tre utilis pour
fournir une URL par dfaut utiliser si HTTP_REFERER ne peut pas tre lu par les headers. Donc,
au lieu de faire ceci :
class UtilisateursController extends AppController {
public function delete($id) {
// le code de suppression va ici, et ensuite...
if ($this->referer() != '/') {
return $this->redirect($this->referer());
}
return $this->redirect(array('action' => 'index'));
}
}

vous pouvez faire ceci :


class UtilisateursController extends AppController {
public function delete($id) {
// le code de suppression va ici, et ensuite...
return $this->redirect($this->referer(array('action' => 'index')));
}
}

Si $default nest pas dfini, la fonction se met par dfaut sur la racine (root) de votre domaine /.
Le paramtre $local, si il est dfini true, restreint les URLs se rfrant au serveur local.

58

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Controller::disableCache()
Utilise pour indiquer au navigateur de lutilisateur de ne pas mettre en cache le rsultat de la requte
courante. Ceci est diffrent du systme de cache de vue couvert dans le chapitre suivant.
Les en-ttes HTTP envoys cet effet sont :
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Last-Modified: [current datetime] GMT
Cache-Control: no-store, no-cache, must-revalidate
Cache-Control: post-check=0, pre-check=0
Pragma: no-cache

Controller::postConditions(array $data, mixed $op, string $bool, boolean $exclusive)


Utilisez cette mthode pour transformer des donnes de formulaire, transmises par POST (depuis
les inputs du Helper Form), en des conditions de recherche pour un model. Cette fonction offre un
raccourci apprciable pour la construction de la logique de recherche. Par exemple, un administrateur
aimerait pouvoir chercher des commandes dans le but de connatre les produits devant tre emballs.
Vous pouvez utiliser les Helpers Form et Html pour construire un formulaire rapide bas sur le model
Commande. Ensuite une action du controller peut utiliser les donnes postes par ce formulaire pour
construire automatiquement les conditions de la recherche :
public function index() {
$conditions = $this->postConditions($this->request->data);
$commandes = $this->Commande->find('all', compact('conditions'));
$this->set('commandes', $orders);
}

Si $this->data[Commande][destination] vaut Boulangerie du village, postConditions convertit cette condition en un tableau compatible avec la mthode Model->find(). Soit dans
notre cas, array("Commande.destination" => "Boulangerie du village").
Si vous voulez utiliser un oprateur SQL diffrent entre chaque terme, remplacez-le en utilisant le
second paramtre :
/*
Contenu de $this->request->data
array(
'Commande' => array(
'nb_items' => '4',
'referrer' => 'Ye Olde'
)
)
*/
// Rcuprons maintenant les commandes qui ont au moins 4 items et
contenant 'Ye Olde'
$conditions = $this->postConditions(
$this->request->data,
array(
'nb_items' => '>=',
'referrer' => 'LIKE'
)
);
$commandes = $this->Commande->find('all', compact('conditions'));

Les Mthodes du Controller

59

CakePHP Cookbook Documentation, Version 2.x

Le troisime paramtre vous permet de dire CakePHP quel oprateur boolen SQL utiliser entre les
conditions de recherche. Les chanes comme AND, OR et XOR sont des valeurs possibles.
Enfin, si le dernier paramtre est dfini vrai et que $op est un tableau, les champs non-inclus dans
$op ne seront pas inclus dans les conditions retournes.
Controller::paginate()
Cette mthode est utilise pour paginer les rsultats retourns par vos models. Vous pouvez dfinir
les tailles de la page, les conditions utiliser pour la recherche de ces donnes et bien plus encore.
Consultez la section pagination pour plus de dtails sur lutilisation de la pagination.
Controller::requestAction(string $url, array $options)
Cette fonction appelle laction dun controller depuis tout endroit du code et retourne les donnes associes cette action. L$url passe est une adresse relative votre application CakePHP (/nomducontroleur/nomaction/parametres). Pour passer des donnes supplmentaires au controller destinataire,
ajoutez le tableau $options.
Note :
Vous pouvez utiliser requestAction() pour rcuprer lintgralit de laffichage dune vue en passant la valeur return dans les options : requestAction($url,
array(return)). Il est important de noter que faire un requestAction en utilisant return
partir dune mthode dun controller peut entraner des problmes de fonctionnement dans les script
et tags CSS.
Avertissement : Si elle est utilise sans cache, la mthode requestAction() peut engendrer
des faibles performances. Il est rarement appropri de lutiliser dans un controller ou un model.
requestAction() est plutt utilise en conjonction avec des lments (mis en cache) - comme
moyen de rcuprer les donnes pour un lment avant de lafficher. Prenons lexemple de la mise en
place dun lment derniers commentaires dans le layout. Nous devons dabord crer une mthode
de controller qui retourne les donnes :
// Controller/CommentsController.php
class CommentsController extends AppController {
public function latest() {
if (empty($this->request->params['requested'])) {
throw new ForbiddenException();
}
return $this->Comment->find(
'all',
array('order' => 'Comment.created DESC', 'limit' => 10)
);
}
}

Vous devriez toujours inclure des vrifications pour vous assurer que vos mthodes de requestAction sont en fait originaires de requestAction(). Ne pas le faire va autoriser les mthodes requestAction() tre directement accessible dune URL, ce qui nest gnralement pas
souhait.
Si nous crons un lment simple pour appeler cette fonction :
// View/Elements/latest_comments.ctp

60

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

$comments = $this->requestAction('/comments/latest');
foreach ($comments as $comment) {
echo $comment['Comment']['title'];
}

On peut ensuite placer cet lment nimporte o pour obtenir la sortie en utilisant :
echo $this->element('latest_comments');

Ecrit de cette manire, ds que llment est affich, une requte sera faite au controller pour obtenir
les donnes, les donnes seront traites, et retournes. Cependant, compte tenu de lavertissement
ci-dessus il vaut mieux utiliser des lments mis en cache pour anticiper des traitements inutiles. En
modifiant lappel llment pour quil ressemble ceci :
echo $this->element('latest_comments', array(), array('cache' => true));

Lappel requestAction() ne sera pas effectu tant que le fichier de vue de llment en cache
existe et est valide.
De plus, requestAction() prend dsormais des URLs bases sur des tableau dans le style de
cake :
echo $this->requestAction(
array('controller' => 'articles', 'action' => 'featured'),
array('return')
);

Cela permet lappel de requestAction() dviter lutilisation de Router : :url ce qui peut
amliorer la performance. Les urls bases sur des tableaux sont les mmes que celles utilises par
HtmlHelper::link() avec une seule diffrence. Si vous utilisez des paramtres nomms ou
passs dans vos urls, vous devez les mettre dans un second tableau et les inclure dans la cl correcte. La raison de cela est que requestAction() fusionne seulement le tableau des arguments
nomms avec les membres du tableau de Controller::params et ne place pas les arguments
nomms dans la cl named. Des parties supplmentaires dans le tableau $option vont aussi tre
disponibles dans le tableau Controller : :params de laction requte
echo $this->requestAction('/articles/featured/limit:3');
echo $this->requestAction('/articles/view/5');

En array dans requestAction serait ainsi :


echo $this->requestAction(
array('controller' => 'articles', 'action' => 'featured'),
array('named' => array('limit' => 3))
);
echo $this->requestAction(
array('controller' => 'articles', 'action' => 'view'),
array('pass' => array(5))
);

Note : Contrairement aux autres places o les URLs en tableau sont analogues aux URLs en chane
de caractre, requestAction les traite diffremment.

Les Mthodes du Controller

61

CakePHP Cookbook Documentation, Version 2.x

Quand vous utilisez une url en tableau en conjonction avec requestAction(), vous devez spcifier tous les paramtres dont vous aurez besoin dans laction requte. Ceci inclut les paramtres
comme $this->request->data. En plus de passer tous les paramtres requis, les paramtres
nomms et passs doivent tre faits dans le second tableau comme vu ci-dessus.
Controller::loadModel(string $modelClass, mixed $id)
La fonction loadModel() devient pratique quand vous avez besoin dutiliser un model qui nest
pas le model du controller par dfaut ou un de ses models associs :
$this->loadModel('Article');
$recentArticles = $this->Article->find(
'all',
array('limit' => 5, 'order' => 'Article.created DESC')
);
$this->loadModel('User', 2);
$user = $this->User->read();

Les attributs du Controller


Pour une liste complte des attributs du controller et ses descriptions, regardez lAPI de CakePHP 2 .
property Controller::$name
Lattribut $name doit tre dfini selon le nom du controller. Habituellement, cest juste la forme
plurielle du model principal que le controller utilise. Cette proprit nest pas requise, mais vite
CakePHP dinflecter dessus :
// Exemple d'utilisation d'attribut $name du controller
class RecipesController extends AppController {
public $name = 'Recipes';
}

$components, $helpers et $uses


Les autres attributs les plus souvent utiliss permettent dindiquer CakePHP quels $helpers,
$components et models vous utiliserez avec le controller courant. Utiliser ces attributs rend ces classes
MVC, fournies par $components et $uses, disponibles pour le controller, sous la forme de variables
de classe ($this->ModelName, par exemple) et celles fournies par $helpers, disponibles pour la vue
comme une variable rfrence lobjet ($this->{$helpername}).
Note : Chaque controller a dj accs, par dfaut, certaines de ces classes, donc vous navez pas besoin
de les redfinir.
property Controller::$uses
Les controllers ont accs par dfaut leur model primaire respectif. Notre controller Recettes aura
2. http ://api.cakephp.org/2.4/class-Controller.html

62

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

donc accs son model Recette, disponible via $this->Recette, et notre controller Produits proposera un accs son model via $this->Produit. Cependant, quand vous autorisez un controller
accder dautres models via la variable $uses, le nom du model primaire du controller courant
doit galement tre inclu. Ceci est illustr dans lexemple ci-dessous.
Si vous ne souhaitez pas utiliser un Model dans votre controller, dfinissez public $uses =
array(). Cela vous permettra dutiliser un controller sans avoir besoin dun fichier Model correspondant. Cependant, les models dfinis dans AppController seront toujours chargs. Vous
pouvez aussi utiliser false pour ne charger absolument aucun model. Mme ceux dfinis dans
AppController.
Modifi dans la version 2.1 : $uses a maintenant une nouvelle valeur par dfaut, il gre aussi false
diffremment.
property Controller::$helpers
Les Helpers HtmlHelper, FormHelper et SessionHelper sont toujours accessibles par dfaut, tout comme le SessionComponent. Mais si vous choisissez de dfinir votre propre tableau
$helpers dans AppController, assurez-vous dy inclure HtmlHelper et FormHelper si vous
voulez quils soient toujours disponibles par dfaut dans vos propres controllers. Pour en savoir plus
au sujet de ces classes, regardez leurs sections respectives plus loin dans le manuel.
Jetons maintenant un il sur la faon dindiquer un Controller CakePHP que vous avez dans
lide dutiliser dautres classes MVC :
class RecipesController extends AppController {
public $uses = array('Recipe', 'User');
public $helpers = array('Js');
public $components = array('RequestHandler');
}

Toutes ces variables sont fusionnes avec leurs valeurs hrites, par consquent ce nest pas ncessaire
de re-dclarer (par exemple) le helper FormHelper ou tout autre dclar dans votre controller App.
property Controller::$components
Le tableau de components vous permet de dfinir quel Components (Composants) un controller va
utiliser. Comme les $helpers et $uses, les components dans vos controllers sont fusionns avec
ceux dans AppController. Comme pour les $helpers, vous pouvez passer les paramtres dans
les components. Regardez Configuration des Components pour plus dinformations.

Autres Attributs
Tandis que vous pouvez vrifier les dtails pour tous les attributs des controllers dans lAPI 3 , il y a dautres
attributs du controller qui mritent leurs propres sections dans le manuel.
3. http ://api.cakephp.org

Les attributs du Controller

63

CakePHP Cookbook Documentation, Version 2.x

En savoir plus sur les controllers


Les Objets Request et Response
Les objets request et response sont nouveaux depuis CakePHP 2.0. Dans les versions prcdentes,
ces objets taient reprsents travers des tableaux, et les mthodes lies taient utilises travers
RequestHandlerComponent, Router, Dispatcher et Controller. Il ny avait pas dobjet global qui reprenait les informations de la requte. Depuis CakePHP 2.0, CakeRequest et
CakeResponse sont utiliss pour cela.

CakeRequest
CakeRequest est lobjet requte utilis par dfaut dans CakePHP. Il centralise un certain nombre
de fonctionnalits pour interroger et interagir avec les donnes demandes. Pour chaque requte, un
CakeRequest est cre et passe en rfrence aux diffrentes couches de lapplication que la requte
de donnes utilise. Par dfaut CakeRequest est assigne $this->request, et est disponible dans
les Controllers, Vues et Helpers. Vous pouvez aussi y accder dans les Components en utilisant la rfrence
du controller. Certaines des tches incluses que CakeRequest permet :
Transformer les tableaux GET, POST, et FILES en structures de donnes avec lesquelles vous tes familiers.
Fournir une introspection de lenvironnement se rapportant la demande. Des choses comme les envois
den-ttes (headers), ladresse IP du client et les informations des sous-domaines/domaines sur lesquels
le serveur de lapplication tourne.
Fournit un accs aux paramtres de la requte la fois en tableaux indics et en proprits dun objet.
Accder aux paramtres de la requte
CakeRequest propose plusieurs interfaces pour accder aux paramtres de la requte. La premire est par
des tableaux indexs, la seconde est travers $this->request->params, et la troisime est par des
proprits dobjets :
$this->request['controller'];
$this->request->controller;
$this->request->params['controller']

Tout ce qui est au-dessus retournera la mme valeur. Plusieurs faons daccder aux paramtres ont t faites
pour faciliter la migration des applications existantes. Tous les lments de route Les Elments de Route sont
accessibles travers cette interface.
En plus des lments de routes Les Elments de Route, vous avez souvent besoin daccder aux arguments
passs Arguments Passs et aux paramtres nomms Paramtres Nomms. Ceux-ci sont aussi tous les deux
disponibles dans lobjet request :
// Arguments passs
$this->request['pass'];
$this->request->pass;
$this->request->params['pass'];

64

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

// Paramtres nomms
$this->request['named'];
$this->request->named;
$this->request->params['named'];

Tous ceux-ci vous fourniront un accs aux arguments passs et aux paramtres nomms. Il y a de nombreux
paramtres importants et utiles que CakePHP utilise en interne, ils sont aussi trouvables dans les paramtres
de la requte :
plugin Le plugin grant la requte, va tre nul quand il ny a pas de plugins.
controller Le controller gre la requte courante.
action Laction gre la requte courante.
prefix Le prfixe pour laction courante. Voir Prefix de Routage pour plus dinformations.
bare Prsent quand la requte vient de requestAction() et inclut loption bare. Les requtes vides
nont pas de layout de rendu.
requested Prsent et mis true quand laction vient de requestAction().
Accder aux paramtres Querystring
Les paramtres Querystring peuvent tre lus en utilisant CakeRequest::$query :
// l'URL est /posts/index?page=1&sort=title
$this->request->query['page'];
// Vous pouvez aussi y accder par un tableau
// accesseur BC, va tre dprci dans les versions futures
$this->request['url']['page'];

Vous pouvez soit directement accder la proprit $query, soit vous pouvez utiliser
CakeRequest::query() pour lire lURL requte sans erreur. Toute cl qui nexiste pas va
retourner null :
$foo = $this->request->query('value_that_does_not_exist');
// $foo === null

Accder aux donnes POST


Toutes les donnes POST peuvent tre atteintes travers CakeRequest::$data. Nimporte quelle
forme de tableau qui contient un prfixe data, va avoir sa donne prfixe retire. Par exemple :
// Un input avec un nom attribute gal 'data[MyModel][title]'
// est accessible
$this->request->data['MyModel']['title'];

Vous pouvez soit accder directement la proprit $data, soit vous pouvez utiliser
CakeRequest::data() pour lire le tableau de donnes sans erreurs. Toute cl nexistant pas va
retourner null :

En savoir plus sur les controllers

65

CakePHP Cookbook Documentation, Version 2.x

$foo = $this->request->data('Value.that.does.not.exist');
// $foo == null

Accder aux donnes PUT ou POST


Introduit dans la version 2.2.
Quand vous construisez des services REST, vous acceptez souvent des donnes requtes sur des requtes PUT et DELETE. Depuis 2.2, toute donne de corps de requte
application/x-www-form-urlencoded va automatiquement tre parse et dfinie dans
$this->data pour les requtes PUT et DELETE. Si vous acceptez les donnes JSON ou XML,
regardez ci-dessous comment vous pouvez accder aux corps de ces requtes.
Accder aux donnes XML ou JSON
Les applications employant REST changent souvent des donnes dans des organes post non encodes en URL. Vous pouvez lire les donnes entrantes dans nimporte quel format en utilisant
CakeRequest::input(). En fournissant une fonction de dcodage, vous pouvez recevoir le contenu
dans un format dserializ :
// Obtenir les donnes encodes JSON soumises par une action PUT/POST
$data = $this->request->input('json_decode');

Puisque certaines mthodes de desrialization ont besoin de paramtres supplmentaires quand elles sont
appeles, comme le paramtre de type tableau pour json_decode ou si vous voulez convertir les XML
en objet DOMDocument, CakeRequest::input() supporte aussi le passement dans des paramtres
supplmentaires :
// Obtenir les donnes encodes en Xml soumises avec une action PUT/POST
$data = $this->request->input('Xml::build', array('return' => 'domdocument'));

Accder aux informations du chemin


CakeRequest fournit aussi des informations utiles sur les chemins dans votre application.
CakeRequest::$base et CakeRequest::$webroot sont utiles pour gnrer des URLs, et dterminer si votre application est ou nest pas dans un sous-dossier.
Inspecter la requte
Dans les anciennes versions, dtecter les diffrentes conditions de la requte ncssitait
RequestHandlerComponent. Ces mthodes ont t dplaces dans CakeRequest, ce qui offre une nouvelle interface tout le long, compatible avec les utilisations anciennes :
$this->request->is('post');
$this->request->isPost(); // dprci

66

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Les deux mthodes appeles vont retourner la mme valeur. Pour linstant, les mthodes sont toujours
disponibles dans RequestHandlerComponent, mais sont deprcies et seront retires dans 3.0.0.
Vous pouvez aussi facilement tendre les dtecteurs de la requte qui sont disponibles, en utilisant
CakeRequest::addDetector() pour crer de nouveaux types de dtecteurs. Il y a quatre diffrents
types de dtecteurs que vous pouvez crer :
Comparaison avec valeur denvironnement - Une comparaison de la valeur denvironnement, compare
une valeur attrape partir de env() pour une valeur connue, la valeur denvironnement est vrifie
quitablement avec la valeur fournie.
La comparaison de la valeur model - La comparaison de la valeur model vous autorise comparer une
valeur attrape partir de env() avec une expression rgulire.
Comparaison base sur les options - La comparaison base sur les options utilise une liste doptions pour
crer une expression rgulire. De tels appels pour ajouter un dtecteur doptions dj dfini, va fusionner
les options.
Les dtecteurs de Callback - Les dtecteurs de Callback vous permettront de fournir un type callback
pour grer une vrification. Le callback va recevoir lobjet requte comme seul paramtre.
Quelques exemples seraient :
// Ajouter un dtecteur d'environnement.
$this->request->addDetector(
'post',
array('env' => 'REQUEST_METHOD', 'value' => 'POST')
);
// Ajouter un dtecteur de valeur model.
$this->request->addDetector(
'iphone',
array('env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i')
);
// Ajouter un dtecteur d'options
$this->request->addDetector('internalIp', array(
'env' => 'CLIENT_IP',
'options' => array('192.168.0.101', '192.168.0.100')
));
// Ajouter un dtecteur de callback. Peut soit tre une fonction anonyme
// ou un callback rgulier.
$this->request->addDetector(
'awesome',
array('callback' => function ($request) {
return isset($request->awesome);
})
);

CakeRequest
inclut
aussi
des
mthodes
comme
CakeRequest::domain(),
CakeRequest::subdomains() et CakeRequest::host() qui facilitent la vie des applications avec sous-domaines.
Vous pouvez utiliser plusieurs dtecteurs intgrs :
is(get) Vrifie si la requte courante est un GET.
is(put) Vrifie si la requte courante est un PUT.
is(post) Vrifie si la requte courante est un POST.
En savoir plus sur les controllers

67

CakePHP Cookbook Documentation, Version 2.x

is(delete) Vrifie si la requte courante est un DELETE.


is(head) Vrifie si la requte courante est un HEAD.
is(options) Vrifie si la requte courante est OPTIONS.
is(ajax) Vrifie si la requte courante vient dun X-Requested-With = XMLHttpRequest.
is(ssl) Vrifie si la requte courante est via SSL.
is(flash) Vrifie si la requte courante a un User-Agent de Flash.
is(mobile) Vrifie si la requte courante vient dune liste courante de mobiles.

CakeRequest et RequestHandlerComponent
Puisque plusieurs des fonctionnalits offertes par CakeRequest taient lapanage de
RequestHandlerComponent, une reflexion tait ncessaire pour savoir si il tait toujours ncessaire.
Dans 2.0, RequestHandlerComponent agit comme un sugar daddy en fournissant une couche de
facilit au-dessus de loffre utilitaire de CakeRequest. RequestHandlerComponent permet par
exemple de changer les layouts et vues bass sur les types de contenu ou ajax. Cette sparation des utilitaires
entre les deux classes vous permet de plus facilement choisir ce dont vous avez besoin.
Interagir avec les autres aspects de la requte
Vous pouvez utiliser CakeRequest pour voir une quantit de choses sur la requte. Au-del des dtecteurs,
vous pouvez galement trouver dautres informations sur les diverses proprits et mthodes.
$this->request->webroot contient le rpertoire webroot.
$this->request->base contient le chemin de base.
$this->request->here contient ladresse complte de la requte courante.
$this->request->query contient les paramtres de la chane de requte.
API de CakeRequest
class CakeRequest
CakeRequest encapsule la gestion des paramtres de la requte, et son introspection.
CakeRequest::domain($tldLength = 1)
Retourne le nom de domaine sur lequel votre application tourne.
CakeRequest::subdomains($tldLength = 1)
Retourne un tableau avec le sous-domaine sur lequel votre application tourne.
CakeRequest::host()
Retourne lhte o votre application tourne.
CakeRequest::method()
Retourne la mthode HTTP o la requte a t faite.
CakeRequest::onlyAllow($methods)
Dfinit les mthodes HTTP autorises, si elles ne correspondent pas, elle va lancer une MethodNotAllowedException. La rponse 405 va inclure len-tte Allow ncessaire avec les mthodes passes.
Introduit dans la version 2.3.
Obsolte depuis la version 2.5 : Utilisez CakeRequest::allowMethod() la place.
68

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

CakeRequest::allowMethod($methods)
Dfinit les mthodes HTTP autorises, si cela ne correspond pas, une exception MethodNotAllowedException sera lance. La rponse 405 va inclure len-tte ncessaire Allow avec les mthodes
passes.
Introduit dans la version 2.5.
CakeRequest::referer($local = false)
Retourne ladresse de rfrence de la requte.
CakeRequest::clientIp($safe = true)
Retourne ladresse IP du visiteur courant.
CakeRequest::header($name)
Vous permet daccder tout en-tte HTTP_* utilis pour la requte :
$this->request->header('User-Agent');

Retournerait le user agent utilis pour la requte.


CakeRequest::input($callback[, $options ])
Rcupre les donnes dentre pour une requte, et les passe optionnellement travers une fonction
qui dcode. Utile lors des interactions avec une requte de contenu de corps XML ou JSON. Les
paramtres supplmentaires pour la fonction dcodant peuvent tre passs comme des arguments de
input() :
$this->request->input('json_decode');

CakeRequest::data($name)
Fournit une notation en point pour accder aux donnes requtes. Permet la lecture et la modification
des donnes requtes, les appels peuvent aussi tre chans ensemble :
// Modifier une donne requte, ainsi vous pouvez pr-enregistrer certains champs.
$this->request->data('Post.title', 'New post')
->data('Comment.1.author', 'Mark');
// Vous pouvez aussi lire des donnes.
$value = $this->request->data('Post.title');

CakeRequest::query($name)
Fournit un accs aux donnes requtes de lURL avec notation en point :
// l\'URL est /posts/index?page=1&sort=title
$value = $this->request->query('page');

Introduit dans la version 2.3.


CakeRequest::is($type)
Vrifie si la requte remplit certains critres ou non. Utilisez les rgles de dtection dj construites
ainsi que toute rgle supplmentaire dfinie dans CakeRequest::addDetector().
CakeRequest::addDetector($name, $options)
Ajoute un dtecteur pour tre utilis avec CakeRequest::is(). Voir Inspecter la requte pour
plus dinformations.

En savoir plus sur les controllers

69

CakePHP Cookbook Documentation, Version 2.x

CakeRequest::accepts($type = null)
Trouve quels types de contenu le client accepte ou vrifie si ils acceptent un type particulier de contenu.
Rcupre tous les types :
<?php
$this->request->accepts();

Vrifie pour un unique type :


$this->request->accepts('application/json');

static CakeRequest::acceptLanguage($language = null)


Obtenir toutes les langues acceptes par le client, ou alors vrifier si une langue spcifique est accepte.
Obtenir la liste des langues acceptes :
CakeRequest::acceptLanguage();

Vrifier si une langue spcifique est accepte :


CakeRequest::acceptLanguage('es-es');

CakeRequest::param($name)
Lit les valeurs en toute scurit dans $request->params. Celle-ci enlve la ncessit dappeler
isset() ou empty() avant lutilisation des valeurs de param.
Introduit dans la version 2.4.
property CakeRequest::$data
Un tableau de donnes POST. Vous pouvez utiliser CakeRequest::data() pour lire cette proprit dune manire qui supprime les erreurs notice.
property CakeRequest::$query
Un tableau des paramtres de chane requts.
property CakeRequest::$params
Un tableau des lments de route et des paramtres requts.
property CakeRequest::$here
Retourne lURL requte courante.
property CakeRequest::$base
Le chemin de base de lapplication, normalement /, moins que votre application soit dans un sousrpertoire.
property CakeRequest::$webroot
Le webroot courant.

CakeResponse
CakeResponse est la classe de rponse par dfaut dans CakePHP. Elle encapsule un nombre de fonctionnalits et de caractristiques pour la gnration de rponses HTTP dans votre application. Elle aide

70

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

aussi tester puisquelle peut tre mocked/stubbed, vous permettant dinspecter les en-ttes qui vont tre
envoys. Comme CakeRequest, CakeResponse consolide un certain nombre de mthodes quon pouvait trouver avant dans Controller, RequestHandlerComponent et Dispatcher. Les anciennes
mthodes sont dprcies en faveur de lutilisation de CakeResponse.
CakeResponse fournit une interface pour envelopper les tches de rponse communes lies, telles que :
Envoyer des en-ttes pour les redirections.
Envoyer des en-ttes de type de contenu.
Envoyer tout en-tte.
Envoyer le corps de la rponse.
Changer la classe de rponse
CakePHP utilise CakeResponse par dfaut. CakeResponse est flexible et transparente pour lutilisation de la classe. Si vous avez besoin de la remplacer avec une classe spcifique de lapplication, vous pouvez
lcraser et remplacer CakeResponse avec votre propre classe en remplaant la classe CakeResponse
utilise dans app/webroot/index.php.
Cela fera que tous les controllers dans votre application utiliseront VotreResponse au lieu
de CakeResponse. Vous pouvez aussi remplacer linstance de rponse de la configuration
$this->response dans vos controllers. Ecraser lobjet rponse est porte de main pour les tests car il
vous permet dcraser les mthodes qui interagissent avec header(). Voir la section sur CakeResponse et
les tests pour plus dinformations.
Grer les types de contenu
Vous pouvez contrler le Content-Type des rponses de votre application en utilisant
CakeResponse::type(). Si votre application a besoin de grer les types de contenu qui
ne sont pas construits dans CakeResponse, vous pouvez faire correspondre ces types avec
CakeResponse::type() comme ceci :
// Ajouter un type vCard
$this->response->type(array('vcf' => 'text/v-card'));
// Configurer la rponse de Type de Contenu pour vcard.
$this->response->type('vcf');

Habituellement, vous voudrez faire correspondre des types de contenu supplmentaires dans le callback
beforeFilter() de votre controller, afin que vous puissiez tirer parti de la fonctionnalit de vue de
commutation automatique de RequestHandlerComponent, si vous lutilisez.
Envoyer des fichiers
Il y a des fois o vous voulez envoyer des fichiers en rponses de vos requtes. Avant la version 2.3, vous
pouviez utiliser MediaView pour faire cela. Depuis 2.3, MediaView est dprcie et vous pouvez utiliser
CakeResponse::file() pour envoyer un fichier en rponse :

En savoir plus sur les controllers

71

CakePHP Cookbook Documentation, Version 2.x

public function sendFile($id) {


$file = $this->Attachment->getFile($id);
$this->response->file($file['path']);
//Retourne un objet reponse pour viter que le controller n'essaie de
// rendre la vue
return $this->response;
}

Comme montr dans lexemple ci-dessus, vous devez passer le chemin du fichier la mthode.
CakePHP va envoyer le bon en-tte de type de contenu si cest un type de fichier connu list
dans CakeResponse::$_mimeTypes. Vous pouvez ajouter des nouveaux types avant dappeler
CakeResponse::file() en utilisant la mthode CakeResponse::type().
Si vous voulez, vous pouvez aussi forcer un fichier tre tlcharg au lieu dtre affich dans le navigateur
en spcifiant les options :
$this->response->file(
$file['path'],
array('download' => true, 'name' => 'foo')
);

Envoyer une chane en fichier


Vous pouvez rpondre avec un fichier qui nexiste pas sur le disque, par exemple si vous voulez gnrer un
pdf ou un ics la vole et voulez servir la chane gnre en fichier, vous pouvez faire cela en utilisant :
public function sendIcs() {
$icsString = $this->Calendar->generateIcs();
$this->response->body($icsString);
$this->response->type('ics');
//Force le tlchargement de fichier en option
$this->response->download('filename_for_download.ics');
//Retourne l'object pour viter au controller d'essayer de rendre
// une vue
return $this->response;
}

Dfinir les en-ttes


Le rglage des en-ttes est fait avec la mtode CakeResponse::header(). Elle peut tre appele avec
quelques paramtres de configurations :
// Rgler un unique en-tte
$this->response->header('Location', 'http://example.com');
// Rgler plusieurs en-ttes
$this->response->header(array(
'Location' => 'http://example.com',

72

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

'X-Extra' => 'My header'


));
$this->response->header(array(
'WWW-Authenticate: Negotiate',
'Content-type: application/pdf'
));

Rgler le mme header() de multiples fois entranera lcrasement des prcdentes valeurs,
un peu comme les appels rguliers den-tte. Les en-ttes ne sont aussi pas envoys quand
CakeResponse::header() est appele ; la place, ils sont simplement conservs jusqu ce que la
rponse soit effectivement envoye.
Introduit dans la version 2.4.
Vous pouvez maintenant utiliser la mthode pratique CakeResponse::location() pour directement
dfinir ou rcuprer len-tte de localisation du redirect.
Interagir avec le cache du navigateur
Vous avez parfois besoin de forcer les navigateurs ne pas mettre en cache les rsultats de laction dun
controller. CakeResponse::disableCache() est justement prvu pour cela :
public function index() {
// faire quelque chose.
$this->response->disableCache();
}

Avertissement : En utilisant disableCache() avec downloads partir de domaines SSL pendant que vous
essayez denvoyer des fichiers Internet Explorer peut entraner des erreurs.
Vous pouvez aussi dire aux clients que vous voulez quils mettent en cache des rponses. En utilisant
CakeResponse::cache() :
public function index() {
//faire quelque chose
$this->response->cache('-1 minute', '+5 days');
}

Ce qui est au-dessus dira aux clients de mettre en cache la rponse rsultante pendant 5 jours, en esprant
acclrer lexprience de vos visiteurs. CakeResponse::cache() dfinit valeur Last-Modified en
premier argument. Expires, et max-age sont dfinis en se basant sur le second paramtre. Le Cache-Control
est dfini aussi public.
Rglage fin du Cache HTTP
Une des faons les meilleures et les plus simples de rendre votre application plus rapide est dutiliser le
cache HTTP. Avec la mise en cache des models, vous navez qu aider les clients dcider si ils doivent
utiliser une copie mise en cache de la rponse en configurant un peu les en-ttes comme les temps modifis,
les balises dentit de rponse et autres.
En savoir plus sur les controllers

73

CakePHP Cookbook Documentation, Version 2.x

Oppos lide davoir coder la logique de mise en cache et de sa nullit (rafrachissement) une fois
que les donnes ont chang, HTPP utilise deux models, lexpiration et la validation qui habituellement sont
beaucoup plus simples que davoir grer le cache soi-mme.
En dehors de lutilisation de CakeResponse::cache() vous pouvez aussi utiliser plusieurs autres
mthodes pour affiner le rglage des en-ttes de cache HTTP pour tirer profit du navigateur ou linverse
du cache du proxy.
Len-tte de Cache Control

Introduit dans la version 2.1.


Utilis sous le model dexpiration, cet en-tte contient de multiples indicateurs qui peuvent changer la faon
dont les navigateurs ou les proxies utilisent le contenu mis en cache. Un en-tte Cache-Control peut
ressembler ceci :
Cache-Control: private, max-age=3600, must-revalidate

La classe CakeResponse vous aide configurer cet en-tte avec quelques mthodes utiles
qui vont produire un en-tte final valide Cache Control. Premirement il y a la mthode
CakeResponse::sharable(), qui indique si une rponse peut tre considre comme partageable
pour diffrents utilisateurs ou clients. Cette mthode contrle gnralement la partie public ou private
de cet en-tte. Dfinir une rponse en priv indique que tout ou une partie de celle-ci est prvue pour un
unique utilisateur. Pour tirer profit des mises en cache partages, il est ncessaire de dfinir la directive de
contrle en publique.
Le deuxime paramtre de cette mthode est utilis pour spcifier un max-age pour le cache, qui est le
nombre de secondes aprs lesquelles la rponse nest plus considre comme rcente :
public function view() {
...
// Dfini le Cache-Control en public pour 3600 secondes
$this->response->sharable(true, 3600);
}
public function mes_donnees() {
...
// Dfini le Cache-Control en private pour 3600 secondes
$this->response->sharable(false, 3600);
}

CakeResponse expose des mthodes spares pour la dfinition de chaque component dans len-tte
Cache-Control.
Len-tte dExpiration

Introduit dans la version 2.1.

74

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Aussi sous le model dexpiration de cache, vous pouvez dfinir len-tte Expires, qui selon la spcification
HTTP est la date et le temps aprs que la rponse ne soit plus considre comme rcente. Cet en-tte peut
tre dfini en utilisant la mthode CakeResponse::expires() :
public function view() {
$this->response->expires('+5 days');
}

Cette mthode accepte aussi une instance DateTime ou toute chane de caractre qui peut tre parse par
la classe DateTime.
Len-tte Etag

Introduit dans la version 2.1.


Cache validation dans HTTP est souvent utilis quand le contenu change constamment et demande lapplication de gnrer seulement les contenus rponse si le cache nest plus rcent. Sous ce model, le client
continue de stocker les pages dans le cache, mais au lieu de lutiliser directement, il demande lapplication
chaque fois si les ressources ont chang ou non. Cest utilis couramment avec des ressources statiques
comme les images et autres choses.
Len-tte etag() (appel balise dentit) est une chane de caractre qui identifie de faon unique les
ressources requtes. Il est trs semblable la somme de contrle dun fichier ; la mise en cache permettra
de comparer les sommes de contrle pour savoir si elles correspondent ou non.
Pour rellement tirer profit de lutilisation de cet en-tte, vous devez soit appeler manuellement la mthode
CakeResponse::checkNotModified(), soit avoir le RequestHandlerComponent inclus dans
votre controller :
public function index() {
$articles = $this->Article->find('all');
$this->response->etag($this->Article->generateHash($articles));
if ($this->response->checkNotModified($this->request)) {
return $this->response;
}
...
}

Len-tte Last-Modified

Introduit dans la version 2.1.


Toujours dans le cadre du model de validation du cache HTTP, vous pouvez dfinir len-tte
Last-Modified pour indiquer la date et le temps pendant lequel la ressource a t modifie pour la
dernire fois. Dfinir cet en-tte aide la rponse de CakePHP pour mettre en cache les clients si la rponse a
t modifie ou nest pas base sur leur cache.
Pour rellement tirer profit de lutilisation de cet en-tte, vous devez soit appeler manuellement la mthode
CakeResponse::checkNotModified(), soit avoir le RequestHandlerComponent inclus dans
votre controller :
En savoir plus sur les controllers

75

CakePHP Cookbook Documentation, Version 2.x

public function view() {


$article = $this->Article->find('first');
$this->response->modified($article['Article']['modified']);
if ($this->response->checkNotModified($this->request)) {
return $this->response;
}
...
}

Len-tte Vary

Dans certains cas, vous voudrez offrir diffrents contenus en utilisant la mme URL. Cest souvent le cas
quand vous avez une page multilingue ou que vous rpondez avec diffrents HTMLs selon le navigateur qui
requte la ressource. Dans ces circonstances, vous pouvez utiliser len-tte Vary :
$this->response->vary('User-Agent');
$this->response->vary('Accept-Encoding', 'User-Agent');
$this->response->vary('Accept-Language');

CakeResponse et les tests


Probablement lune des plus grandes victoires de CakeResponse vient de comment il facilite les tests des
controllers et des components. Au lieu davoir des mthodes rpandues travers plusieurs objets, vous avez
un seul objet pour mocker pendant que les controllers et les components dlguent CakeResponse. Cela
vous aide rester plus prs dun test unitaire et facilite les tests des controllers :
public function testSomething() {
$this->controller->response = $this->getMock('CakeResponse');
$this->controller->response->expects($this->once())->method('header');
// ...
}

De plus, vous pouvez faciliter encore plus lexcution des tests partir dune ligne de commande, pendant
que vous pouvez mocker pour viter les erreurs denvois den-ttes qui peuvent arriver en essayant de
configurer les en-ttes dans CLI.
API de CakeResponse
class CakeResponse
CakeResponse fournit un nombre de mthodes utiles pour interagir avec la rponse que vous envoyez
un client.
CakeResponse::header($header = null, $value = null)
Vous permet de configurer directement un ou plusieurs en-ttes envoyer avec la rponse.
CakeResponse::location($url = null)
Vous permet de dfinir directement len-tte de localisation du redirect envoyer avec la rponse :

76

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

// Dfinit la localisation du redirect


$this->response->location('http://example.com');
// Rcupre l'en-tte de localisation du redirect actuel
$location = $this->response->location();

Introduit dans la version 2.4.


CakeResponse::charset($charset = null)
Configure le charset qui sera utilis dans la rponse.
CakeResponse::type($contentType = null)
Configure le type de contenu pour la rponse. Vous pouvez soit utiliser un alias de type de contenu
connu, soit le nom du type de contenu complet.
CakeResponse::cache($since, $time = +1 day)
Vous permet de configurer les en-ttes de mise en cache dans la rponse.
CakeResponse::disableCache()
Configure les en-ttes pour dsactiver la mise en cache des clients pour la rponse.
CakeResponse::sharable($public = null, $time = null)
Configure len-tte Cache-Control pour tre soit public soit private et configure optionnellement une directive de la ressource un max-age.
Introduit dans la version 2.1.
CakeResponse::expires($time = null)
Permet de configurer len-tte Expires une date spcifique.
Introduit dans la version 2.1.
CakeResponse::etag($tag = null, $weak = false)
Configure len-tte Etag pour identifier de manire unique une ressource de rponse.
Introduit dans la version 2.1.
CakeResponse::modified($time = null)
Configure len-tte Last-modified une date et un temps donn dans le format correct.
Introduit dans la version 2.1.
CakeResponse::checkNotModified(CakeRequest $request)
Compare les en-ttes mis en cache pour lobjet request avec len-tte mis en cache de la rponse et
dtermine si il peut toujours tre considr comme rcent. Dans ce cas, il supprime tout contenu de
rponse et envoie len-tte 304 Not Modified.
Introduit dans la version 2.1.
CakeResponse::compress()
Dmarre la compression gzip pour la requte.
CakeResponse::download($filename)
Vous permet denvoyer la rponse en pice jointe et de configurer le nom de fichier.
CakeResponse::statusCode($code = null)
Vous permet de configurer le code de statut pour la rponse.

En savoir plus sur les controllers

77

CakePHP Cookbook Documentation, Version 2.x

CakeResponse::body($content = null)
Configurer le contenu du body pour la rponse.
CakeResponse::send()
Une fois que vous avez fini de crer une rponse, appeler send() enverra tous les en-ttes configurs
ainsi que le body. Ceci est fait automatiquement la fin de chaque requte par Dispatcher.
CakeResponse::file($path, $options = array())
Vous permet de dfinir un fichier pour laffichage ou le tlchargement.
Introduit dans la version 2.3.

Scaffolding
Obsolte depuis la version 2.5 : Le scaffolding dynamique sera retir et remplac dans 3.0
Une application scaffolding (chafaudage en Franais) est une technique permettant au dveloppeur de
dfinir et crer une application qui peut construire, afficher, modifier et dtruire facilement des objets. Le
Scaffolding dans CakePHP permet galement aux dveloppeurs de dfinir comment les objets sont lis entre
eux, et de crer ou casser ces liens.
Pour crer un scaffold, vous navez besoin que dun model et de son controller. Dclarez la variable $scaffold
dans le controller, et lapplication est dj prte tourner !
Le scaffolding par CakePHP est vraiment bien imagin. Il vous permet de mettre en place une application
basique CRUD (Cration, Vue, Edition et Destruction) en quelques minutes. Il est si bien fait que vous aurez
envie de lutiliser dans toutes vos applications. Attention ! Nous pensons aussi que le scaffolding est utile,
mais veuillez raliser que ce nest... quun chafaudage ! Cest une structure trs simple mettre en oeuvre,
et il vaut mieux ne lutiliser quau dbut dun projet. Il na pas t conu pour tre flexible, mais uniquement
pour tre un moyen temporaire de mettre en place votre application. A partir du moment o vous voudrez
adapter les fonctions et les vues associes, il vous faudra dsactiver le scaffolding et crire votre propre
code. bake console de CakePHP, que vous pourrez apprendre connatre dans la prochaine section, est une
bonne alternative : il va gnrer tout le code quivalent ce que ferait le scaffolding.
Le Scaffolding est utiliser au tout dbut du dveloppement dune application Internet. Le schma de votre
base de donnes est encore susceptible de changer, ce qui est tout faire normal ce stade du processus de
cration. Ceci a un inconvnient : un dveloppeur dteste crer des formulaires dont il ne verra jamais lutilisation relle. Cest pour rduire le stress du dveloppeur que le Scaffolding a t introduit dans CakePHP.
Il analyse les tables de votre base et cre de faon simple une liste des enregistrements, avec les boutons
dajout, de suppression et de modification, des formulaires pour ldition et une vue pour afficher un enregistrement en particulier.
Pour ajouter le Scaffolding dans votre application, ajoutez la variable $scaffold dans votre controller
class CategoriesController extends AppController {
public $scaffold;
}

En supposant que vous avez bien cre un model Category dans le bon dossier
(app/Model/Category.php), vous pouvez aller sur http ://exemple.com/categories pour voir
votre nouveau scaffold.

78

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Note : Crer des mthodes dans un controller contenant la variable $scaffold peut donner des rsultats
inattendus. Par exemple, si vous crez une mthode index() dans ce controller, votre mthode remplacera
celle rendue normalement par la fonctionnalit de scaffold
Le Scaffolding prend bien en compte les relations contenues dans votre model. Ainsi, si votre model Category a une relation belongsTo avec le model User, vous verrez les identifiants des users dans laffichage
de vos catgories. Puisque scaffolding connat les associations entre models, vous ne verrez pas denregistrements lis dans les vues via scaffold jusqu ce que vous ajoutiez manuellement un code dassociation
au model. Par exemple, si le model Group hasMany User et que User belongsTo Group, vous devrez
ajouter manuellement le code suivant dans vos models User et Group. Avant de faire cela, la vue affiche un
select vide pour le Group dans le Nouveau formulaire User ; after populated avec les IDs ou noms partir
de la table du Group dans le Nouveau formulaire User :
// Dans Group.php
public $hasMany = 'User';
// Dans User.php
public $belongsTo = 'Group';

Si vous prfrez voir autre chose en plus des identifiants (par exemple les prnoms des users), vous
pouvez affecter la variable $displayField dans le model. Voyons comment dfinir la variable
$displayField dans la classe des users, afin que le prnom soit montr en lieu et place de lunique
identifiant. Cette astuce permet de rendre le scaffolding plus lisible dans de nombreux cas :
class User extends AppModel {
public $displayField = 'first_name';
}

Crer une interface admin simplifie avec scaffolding


Si vous avez activ le routage admin dans votre app/Config/core.php, avec
Configure::write(Routing.prefixes, array(admin));, vous pouvez utiliser
le scaffolding (chafaudage) pour gnrer une interface dadministration.
Une fois que vous avez activ le routage admin, assignez votre prfixe dadministration la variable de
scaffolding :
public $scaffold = 'admin';

Vous serez maintenant capable daccder aux actions scaffoldes


http://example.com/admin/controller/index
http://example.com/admin/controller/view
http://example.com/admin/controller/edit
http://example.com/admin/controller/add
http://example.com/admin/controller/delete

Cest une mthode facile pour crer rapidement une interface dadministration simple. Gardez lesprit
que vous ne pouvez pas avoir de mthodes de scaffolding la fois dans la partie admin et dans la partie non-admin en mme temps. Comme avec le scaffolding normal, vous pouvez surcharger les mthodes
individuelles et les remplacer par vos propres mthodes :
En savoir plus sur les controllers

79

CakePHP Cookbook Documentation, Version 2.x

public function admin_view($id = null) {


// du code ici
}

Une fois que vous avez remplac une action de scaffolding, vous devrez crer une vue pour cette action.
Personnaliser les vues obtenues par le Scaffolding
Si vous dsirez un rendu un peu diffrent de vos vues obtenues par le Scaffolding, vous pouvez crer des
mises en pages personnalises. Nous continuons de vous recommander de ne pas utiliser cette technique
pour produire vos sites, mais pouvoir modifier les vues peut tre utile pour leur dveloppement.
La personnalisation des vues scaffoldes pour un controller spcifique (PostsController dans notre exemple)
doit tre place comme ceci :
app/View/Posts/scaffold.index.ctp
app/View/Posts/scaffold.form.ctp
app/View/Posts/scaffold.view.ctp

Les vues scaffoldes personnalises pour tous les controllers doivent tre places comme ceci :
app/View/Scaffolds/index.ctp
app/View/Scaffolds/form.ctp
app/View/Scaffolds/view.ctp

Le Controller Pages
Le cur de CakePHP est livr avec un controller par dfaut PagesController.php. Cest un
controller simple et optionnel qui permet de rendre un contenu statique. La page daccueil que vous
voyez juste aprs linstallation est dailleurs gnre laide de ce controller. Ex : Si vous crivez
un fichier de vue app/View/Pages/a_propos.ctp, vous pouvez y accder en utilisant lurl
http://exemple.com/pages/a_propos. Vous pouvez modifier le controller Pages selon vos besoins.
Quand vous cuisinez une application avec lutilitaire console de CakePHP, le controller Pages est copi dans votre dossier app/Controller/ et vous pouvez le
modifier selon vos besoins. Ou vous pouvez simplement copier le fichier partir de
lib/Cake/Console/Templates/skel/Controller/PagesController.php.
Modifi dans la version 2.1 : Avec CakePHP 2.0, le controller Pages tait une partie de lib/Cake. Depuis
2.1, le controller Pages ne fait plus partie du coeur, mais se situe dans le dossier app.
Avertissement : Ne modifiez directement AUCUN fichier du dossier lib/Cake pour viter les problmes lors des mises jour du coeur dans le futur.

80

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

Components (Composants)
Les Components (Composants) sont des regroupements de logique applicative qui sont partags entre les
controllers. CakePHP est galement livr avec un fantastique ensemble de components, que vous pouvez
utiliser pour vous aider. Si vous vous surprenez vouloir copier et coller des choses entre vos controllers,
alors vous devriez envisager de regrouper plusieurs fonctionnalits dans un Component. Crer des components permet de garder un code de controller propre et de rutiliser du code entre diffrents projets.
Chacun de ces components dorigine est dtaill dans son chapitre spcifique. Regardez Components (Composants). Cette section dcrit la faon de configurer et dutiliser les components et la faon de crer vos
propres components.
Configuration des Components
De nombreux components du cur ncessitent une configuration. Quelques exemples : Authentification et
Cookie. Toute configuration pour ces components, et pour les components en gnral, se fait dans le tableau
des $components de la mthode beforeFilter() de vos controllers :
class PostsController extends AppController {
public $components = array(
'Auth' => array(
'authorize' => array('controller'),
'loginAction' => array(
'controller' => 'users',
'action' => 'login'
)
),
'Cookie' => array('name' => 'CookieMonster')
);

La portion de code prcdente est un exemple de configuration dun component avec le tableau
$components. Tous les components du coeur permettent aux paramtres dtre configurs dans la mthode de votre controller beforeFilter(). Cest utile quand vous avez besoin dassigner les rsultats
dune fonction la proprit dun component. Ceci peut aussi tre exprim comme ceci :
public function beforeFilter() {
$this->Auth->authorize = array('controller');
$this->Auth->loginAction = array(
'controller' => 'users',
'action' => 'login'
);
$this->Cookie->name = 'CookieMonster';
}

Cest possible, cependant, que le component ncessite certaines options de configuration avant que le controller beforeFilter() soit lanc. Pour cela, certains components permettent aux options de configuration dtre dfinies dans le tableau $components :

En savoir plus sur les controllers

81

CakePHP Cookbook Documentation, Version 2.x

public $components = array(


'DebugKit.Toolbar' => array('panels' => array('history', 'session'))
);

Consultez la documentation approprie pour connatre les options de configuration que chaque component
fournit.
Un paramtre commun utiliser est loption className, qui vous autorise les alias des components. Cette
fonctionnalit est utile quand vous voulez remplacer $this->Auth ou une autre rfrence de Component
commun avec une implmentation sur mesure :
// app/Controller/PostsController.php
class PostsController extends AppController {
public $components = array(
'Auth' => array(
'className' => 'MyAuth'
)
);
}
// app/Controller/Component/MyAuthComponent.php
App::uses('AuthComponent', 'Controller/Component');
class MyAuthComponent extends AuthComponent {
// Ajouter votre code pour surcharger le AuthComponent du coeur
}

Ce quil y a au-dessous donnerait un alias MyAuthComponent $this->Auth dans vos controllers.


Note : Faire un alias un component remplace cette instance nimporte o o le component est utilis, en
incluant lintrieur des autres Components.

Utiliser les Components


Une fois que vous avez inclus quelques components dans votre controller, les utiliser est trs simple. Chaque
component que vous utilisez est enregistr comme proprit dans votre controller. Si vous avez charg la
SessionComponent et le CookieComponent dans votre controller, vous pouvez y accder comme
ceci :
class PostsController extends AppController {
public $components = array('Session', 'Cookie');
public function delete() {
if ($this->Post->delete($this->request->data('Post.id')) {
$this->Session->setFlash('Post deleted.');
return $this->redirect(array('action' => 'index'));
}
}

Note : Puisque les Models et les Components sont tous deux ajouts aux controllers en tant que proprit,

82

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

ils partagent le mme espace de noms. Assurez vous de ne pas donner le mme nom un component et
un model.

Charger les components la vole

Vous navez parfois pas besoin de rendre le component accessible sur chaque action. Dans ce cas l, vous
pouvez charger la vole en utilisant la Component Collection. A partir de lintrieur dun controller, vous
pouvez faire comme ce qui suit :
$this->OneTimer = $this->Components->load('OneTimer');
$this->OneTimer->getTime();

Note : Gardez lesprit que le chargement dun component la vole ne va pas appeler la mthode initialize.
Si le component que vous appelez a cette mthode, vous devrez lappeler manuellement aprs le chargement.

Callbacks des Components


Les components vous offrent aussi quelques callbacks durant leur cycle de vie qui vous permettent daugmenter le cycle de la requte. Allez voir lapi API de Component pour plus dinformations sur les callbacks
possibles des components.
Crer un Component
Supposons que notre application en ligne ait besoin de raliser une opration mathmatique complexe dans
plusieurs sections diffrentes de lapplication. Nous pourrions crer un component pour hberger cette
logique partage afin de lutiliser dans plusieurs controllers diffrents.
La premire tape consiste crer un nouveau fichier et une classe pour le component. Crez le fichier
dans app/Controller/Component/MathComponent.php. La structure de base pour le component ressemblerait quelque chose comme cela :
class MathComponent extends Component {
public function faireDesOperationsComplexes($montant1, $montant2) {
return $montant1 + $montant2;
}
}

Note : Tous les components comme Math doivent tendre Component. Ne pas le faire vous enverra une
exception.

Inclure votre component dans vos controllers

Une fois notre component termin, nous pouvons lutiliser au sein des controllers de lapplication en plaant
son nom (sans la partie Component) dans le tableau $components du controller. Le controller sera
En savoir plus sur les controllers

83

CakePHP Cookbook Documentation, Version 2.x

automatiquement pourvu dun nouvel attribut nomm daprs le component, travers lequel nous pouvons
accder une instance de celui-ci :
/* Rend le nouveau component disponible par $this->Math
ainsi que le component standard $this->Session */
public $components = array('Math', 'Session');

Les Components dclars dans AppController seront fusionns avec ceux dclars dans vos autres
controllers. Donc il ny a pas besoin de re-dclarer le mme component deux fois.
Quand vous incluez des Components dans un Controller, vous pouvez aussi dclarer un ensemble de
paramtres qui seront passs la mthode initialize() du Component. Ces paramtres peuvent alors tre
pris en charge par le Component :
public $components = array(
'Math' => array(
'precision' => 2,
'generateurAleatoire' => 'srand'
),
'Session', 'Auth'
);

Lexemple ci-dessus passerait le tableau contenant precision et generateurAleatoire comme second


paramtre au MathComponent::__construct(). Par convention, si les cls du tableau correspondent aux proprits publiques du component, les proprits seront dfinies avec les valeurs de ces cls.
Utiliser dautres Components dans votre Component

Parfois un de vos components a besoin dutiliser un autre component. Dans ce cas, vous pouvez inclure
dautres components dans votre component exactement de la mme manire que dans vos controllers - en
utilisant la variable $components :
// app/Controller/Component/CustomComponent.php
class CustomComponent extends Component {
// l'autre component que votre component utilise
public $components = array('Existing');
public function initialize($controller) {
$this->Existing->foo();
}
public function bar() {
// ...
}
}
// app/Controller/Component/ExistingComponent.php
class ExistingComponent extends Component {
public function initialize($controller) {
$this->Parent->bar();
}

84

Chapitre 4. Controllers (Contrleurs)

CakePHP Cookbook Documentation, Version 2.x

public function foo() {


// ...
}
}

Note : Au contraire dun component inclus dans un controller, aucun callback ne sera attrap pour un
component inclus dans un component.

API de Component
class Component
La classe de base de Component vous offre quelques mthodes pour le chargement facile des
autres Components travers ComponentCollection comme nous lavons trait avec la gestion
habituelle des paramtres. Elle fournit aussi des prototypes pour tous les callbacks des components.
Component::__construct(ComponentCollection $collection, $settings = array())
Les Constructeurs pour la classe de base du component. Tous les paramtres se trouvent dans
$settings et ont des proprits publiques. Ils vont avoir leur valeur change pour correspondre
aux valeurs de $settings.
Les Callbacks

Component::initialize(Controller $controller)
Est appele avant la mthode du controller beforeFilter.
Component::startup(Controller $controller)
Est appele aprs la mthode du controller beforeFilter mais avant que le controller nexcute laction
prvue.
Component::beforeRender(Controller $controller)
Est appele aprs que le controller excute la logique de laction requte, mais avant le rendu de la
vue et le layout du controller.
Component::shutdown(Controller $controller)
Est appele avant que la sortie soit envoye au navigateur.
Component::beforeRedirect(Controller $controller, $url, $status=null, $exit=true)
Est invoque quand la mthode de redirection du controller est appele, mais avant toute action qui
suit. Si cette mthode retourne false, le controller ne continuera pas de rediriger la requte. Les variables $url, $status et $exit ont la mme signification que pour la mthode du controller. Vous pouvez
aussi retourner une chane de caractre qui sera interprte comme une URL pour rediriger ou retourner un array associatif avec la cl url et ventuellement status et exit.

En savoir plus sur les controllers

85

CakePHP Cookbook Documentation, Version 2.x

86

Chapitre 4. Controllers (Contrleurs)

CHAPITRE 5

Views (Vues)

Les Views (Vues) sont le V dans MVC. Les vues sont charges de gnrer la sortie spcifique requise par la
requte. Souvent, cela est fait sous forme HTML, XML ou JSON, mais le streaming de fichiers et la cration
de PDFs que les utilisateurs peuvent tlcharger sont aussi de la responsabilit de la couche View.
CakePHP a quelques classes de vue dj construites pour grer les scnarios de rendu les plus communs :
Pour crer des services web XML ou JSON, vous pouvez utiliser Vues JSON et XML.
Pour servir des fichiers protgs, ou gnrer des fichiers dynamiquement, vous pouvez utiliser Envoyer
des fichiers.
Pour crer plusieurs vues pour un thme, vous pouvez utiliser Thmes.

Templates de Vues
La couche view de CakePHP cest la faon dont vous parlez vos utilisateurs. La plupart du temps, vos vues
afficheront des documents (X)HTML pour les navigateurs, mais vous pourriez aussi avoir besoin de fournir
des donnes AMF un objet Flash, rpondre une application distante via SOAP ou produire un fichier
CSV pour un utilisateur.
Les fichiers de vue de CakePHP sont crits en pur PHP et ont par dfaut .ctp (Cakephp TemPlate) comme
extension. Ces fichiers contiennent toute la logique de prsentation ncessaire lorganisation des donnes
reues du controller, dans un format qui satisfasse laudience que vous recherchez. Si vous prfrez utiliser
un langage de template comme Twig, ou Smarty, une sous-classe de View fera le pont entre votre language
de template et CakePHP.
Un fichier de vue est stock dans /app/View/, dans un sous-dossier portant le nom du controller qui utilise ce fichier. Il a un nom de fichier correspondant son action. Par exemple, le
fichier de vue pour laction view() du controller Products devra normalement se trouver dans
/app/View/Products/view.ctp.
La couche vue de CakePHP peut tre constitue dun certain nombre de parties diffrentes. Chaque partie a
diffrent usages qui seront prsents dans ce chapitre :
views : Les Views sont la partie de la page qui est unique pour laction lance. Elles sont la substance de
la rponse de votre application.

87

CakePHP Cookbook Documentation, Version 2.x

elements : morceaux de code de view plus petits, rutilisables. Les lments sont habituellement rendus
dans les vues.
layouts : fichiers de vue contenant le code de prsentation qui se retrouve dans plusieurs interfaces de
votre application. La plupart des vues sont rendues lintrieur dun layout.
helpers : ces classes encapsulent la logique de vue qui est requise de nombreux endroits de la couche
view. Parmi dautres choses, les helpers de CakePHP peuvent vous aider crer des formulaires, des
fonctionnalits AJAX, paginer les donnes du model ou dlivrer des flux RSS.

Vues tendues
Introduit dans la version 2.1.
Une vue tendue vous permet denrouler une vue dans une autre. En combinant cela avec view blocks, cela
vous donne une faon puissante pour garder vos vues DRY. Par exemple, votre application a une sidebar qui
a besoin de changer selon la vue spcifique en train dtre rendue. En tendant un fichier de vue commun,
vous pouvez viter de rpeter la balise commune pour votre sidebar, et seulement dfinir les parties qui
changent :
// app/View/Common/view.ctp
<h1><?php echo $this->fetch('title'); ?></h1>
<?php echo $this->fetch('content'); ?>
<div class="actions">
<h3>Related actions</h3>
<ul>
<?php echo $this->fetch('sidebar'); ?>
</ul>
</div>

Le fichier de vue ci-dessus peut tre utilis comme une vue parente. Il sattend ce que la vue ltendant
dfinisse des blocks sidebar et title. Le block content est un block spcial que CakePHP cre. Il
contiendra tous les contenus non capturs de la vue tendue. En admettant que notre fichier de vue a une
variable $post avec les donnes sur notre post. Notre vue pourrait ressembler ceci :
<?php
// app/View/Posts/view.ctp
$this->extend('/Common/view');
$this->assign('title', $post);
$this->start('sidebar');
?>
<li>
<?php
echo $this->Html->link('edit', array(
'action' => 'edit',
$post['Post']['id']
)); ?>
</li>
<?php $this->end(); ?>

88

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

// Le contenu restant sera disponible en tant que block 'content'


// dans la vue parente.
echo h($post['Post']['body']);

Lexemple ci-dessus vous montre comment vous pouvez tendre une vue, et remplir un ensemble de bloc.
Tout contenu qui ne serait pas dj dans un bloc dfini, sera captur et plac dans un block spcial appel
content. Quand une vue contient un appel vers un extend(), lexcution continue jusqu la fin de la
vue actuelle. Une fois termin, la vue tendue va tre gnre. En appelant extend() plus dune fois dans
un fichier de vue, le dernier appel va outrepasser les prcdents :
$this->extend('/Common/view');
$this->extend('/Common/index');

Le code prcdent va dfinir /Common/index.ctp comme tant la vue parente de la vue actuelle.
Vous pouvez imbriquer les vues autant que vous le voulez et que cela vous est ncessaire. Chaque vue peut
tendre une autre vue si vous le souhaitez. Chaque vue parente va rcuprer le contenu de la vue prcdente
en tant que bloc content.
Note : Vous devriez viter dutiliser content comme nom de block dans votre application. CakePHP
lutilise pour dfinir le contenu non-captur pour les vues tendues.

Utiliser les Blocs de Vues


Introduit dans la version 2.1.
Les blocs de vue remplacent les $scripts_for_layout et fournissent une API flexible qui vous permet
de dfinir des slots (emplacements), ou blocs, dans vos vues / layouts qui peuvent tre dfinies ailleurs. Par
exemple, les blocs pour implmenter des choses telles que les sidebars, ou des rgions pour charger des
ressources dans len-tte / pied de page du layout. Un block peut tre dfini de deux manires. Soit en tant
que block capturant, soit en le dclarant explicitement. Les mthodes start(), append() et end()
vous permettent de travailler avec les blocs capturant :
// Creer le block sidebar.
$this->start('sidebar');
echo $this->element('sidebar/recent_topics');
echo $this->element('sidebar/recent_comments');
$this->end();

// Le rattacher a la sidebar plus tard.


$this->append('sidebar');
echo $this->element('sidebar/popular_topics');
$this->end();

Vous pouvez aussi le rattacher lintrieur dun block en utilisant start() plusieurs fois. La mthode
assign() peut tre utilise pour nettoyer ou outrepasser un block nimporte quel moment :

Utiliser les Blocs de Vues

89

CakePHP Cookbook Documentation, Version 2.x

// Nettoyer le contenu prcedent de la sidebar.


$this->assign('sidebar', '');

Dans 2.3, certaines nouvelles mthodes ont t ajoutes pour travailler avec les blocs. Le prepend() pour
ajouter du contenu avant un block existant :
// Ajoutez avant la sidebar
$this->prepend('sidebar', 'ce contenu va au-dessus de la sidebar');

La mthode startIfEmpty() peut tre utilise pour commencer un bloc seulement si il est vide ou non
dfini. Si le block existe dj, le contenu captur va tre cart. Cest utile quand vous voulez dfinir le
contenu par dfaut de faon conditionnel pour un bloc, qui ne doit pas dj exister :
// Dans un fichier de vue.
// Cre un block de navbar
$this->startIfEmpty('navbar');
echo $this->element('navbar');
echo $this->element('notifications');
$this->end();
// Dans une vue/layout parente
<?php $this->startIfEmpty('navbar'); ?>
<p>Si le block n est pas dfini pour l instant - montrer ceci la place</p>
<?php $this->end(); ?>
// Quelque part plus loin dans la vue/layout parent
echo $this->fetch('navbar');

Dans lexemple ci-dessus, le block navbar va seulement contenir le contenu ajout dans la premire section. Puisque le block a t dfini dans la vue enfant, le contenu par dfaut avec la balise <p> sera cart.
Note : Vous devriez viter dutiliser content comme nom de bloc. Celui-ci est utilis par CakePHP en
interne pour tendre les vues, et le contenu des vues dans le layout.

Afficher les Blocs


Introduit dans la version 2.1.
Vous pouvez afficher les blocs en utilisant la mthode fetch(). Cette dernire va, de manire scurise,
gnrer un bloc, en retournant si le bloc nexiste pas :
echo $this->fetch('sidebar');

Vous pouvez galement utiliser fetch pour afficher du contenu, sous conditions, qui va entourer un block
existant. Ceci est trs utile dans les layouts, ou dans les vues tendues lorsque vous voulez, sous conditions,
afficher des en-ttes ou autres balises :

90

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

// dans app/View/Layouts/default.ctp
<?php if ($this->fetch('menu')): ?>
<div class="menu">
<h3>Menu options</h3>
<?php echo $this->fetch('menu'); ?>
</div>
<?php endif; ?>

Depuis 2.3.0, vous pouvez aussi fournir une valeur par dfaut pour un bloc qui ne devrait pas avoir de
contenu. Cela vous permet dajouter facilement du contenu placeholder, pour des dclarations vides. Vous
pouvez fournir une valeur par dfaut en utilisant le 2me argument :
<div class="shopping-cart">
<h3>Your Cart</h3>
<?php echo $this->fetch('cart', 'Votre cart est vide'); ?>
</div>

Modifi dans la version 2.3 : Largument $default a t ajout dans 2.3.

Utiliser des Blocks pour les Fichiers de Script et les CSS


Introduit dans la version 2.1.
Les Blocks remplacent la variable de layout $scripts_for_layout qui est dprcie. A la place, vous
devrez utiliser les blocks. HtmlHelper lie dans les blocks de vues avec les mthodes script(), css(),
et meta() qui chacune met jour un block avec le mme nom quand loption inline = false est
utilise :
<?php
// dans votre fichier de vue
$this->Html->script('carousel', array('inline' => false));
$this->Html->css('carousel', array('inline' => false));
?>
// dans votre fichier de layout.
<!DOCTYPE html>
<html lang="en">
<head>
<title><?php echo $this->fetch('title'); ?></title>
<?php echo $this->fetch('script'); ?>
<?php echo $this->fetch('css'); ?>
</head>
// rest du layout suit

Le HtmlHelper vous permet aussi de contrler vers quels blocks vont les scripts :
// dans votre vue
$this->Html->script('carousel', array('block' => 'scriptBottom'));
// dans votre layout
echo $this->fetch('scriptBottom');

Utiliser les Blocs de Vues

91

CakePHP Cookbook Documentation, Version 2.x

Layouts
Un layout contient le code de prsentation qui entoure une vue. Tout ce que vous voulez voir dans toutes
vos vues devra tre plac dans un layout.
Le fichier de layout par dfaut de CakePHP est plac dans /app/View/Layouts. Si vous voulez changer
entirement le look de votre application, alors cest le bon endroit pour commencer, parce que le code de
vue de rendu du controller est plac lintrieur du layout par dfaut quand la page est rendue.
Les autres fichiers de layout devront tre placs dans /app/View/Layouts. Quand vous crez un layout,
vous devez dire CakePHP o placer la sortie pour vos vues. Pour ce faire, assurez-vous que votre layout
contienne $this->fetch(content). Voici un exemple de ce quoi un layout pourrait ressembler :
<!DOCTYPE html>
<html lang="en">
<head>
<title><?php echo $this->fetch('title'); ?></title>
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<!-- Include external files and scripts here (See HTML helper for more info.) -->
echo $this->fetch('meta');
echo $this->fetch('css');
echo $this->fetch('script');
?>
</head>
<body>
<!-- Si vous voulez afficher une sorte de menu pour toutes vos vues, mettez
le ici -->
<div id="header">
<div id="menu">...</div>
</div>
<!-- Voil l'endroit ou je souhaite que mes vues soient affiches -->
<?php echo $this->fetch('content'); ?>
<!-- Ajoute un footer sur chaque page affiche -->
<div id="footer">...</div>
</body>
</html>

Note : Avant la version 2.1, la mthode fetch() ntait pas disponible, fetch(content) remplace
$content_for_layout et les lignes fetch(meta), fetch(css) et fetch(script)
taient contenues dans la variable $scripts_for_layout dans la version 2.0.
Les blocks script, css et meta contiennent tout contenu dfini dans les vues en utilisant le helper HTML
intgr. Il est utile pour inclure les fichiers JavaScript et les CSS partir des vues.
Note : Quand vous utilisez HtmlHelper::css() ou HtmlHelper::script() dans les fichiers de
vues, spcifiez false dans loption inline option pour placer la source html dans un block avec le mme
nom. (Regardez lAPI pour plus de dtails sur leur utilisation).

92

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

Le block content contient les contenus de la vue rendue.


$title_for_layout contient le titre de la page. Cette variable est gnre automatiquement, mais vous
pouvez la surcharger en la configurant dans votre controller/view.
Note : $title_for_layout est dprci depuis 2.5, utilisez $this->fetch(title) dans votre
layout et $this->assign(title, page title) la place.
Vous pouvez crer autant de layouts que vous souhaitez : placez les juste dans le rpertoire
app/View/Layouts, et passez de lun lautre depuis les actions de votre controller en utilisant la
proprit $layout de votre controller ou de votre vue :
// A partir d'un controller
public function admin_view() {
// stuff
$this->layout = 'admin';
}
// A partir d'un fichier de vue
$this->layout = 'loggedin';

Par exemple, si une section de mon site incorpore un plus petit espace pour une bannire publicitaire, je
peux crer un nouveau layout avec le plus petit espace de publicit et le spcifier comme un layout pour
toutes les actions du controller en utilisant quelque chose comme :
class UsersController extends AppController {
public function view_active() {
$this->set('title_for_layout', 'Voir les Utilisateurs actifs');
$this->layout = 'default_small_ad';
}
public function view_image() {
$this->layout = 'image';
//sort une image de l\'utilisateur
}
}

CakePHP dispose de deux fonctionnalits de layout dans le coeur (en plus du layout default de CakePHP)
que vous pouvez utiliser dans votre propre application : ajax et flash. Le layout AJAX est pratique pour
laborer des rponses AJAX - cest un layout vide (la plupart des appels ajax ne ncessitent quun peu de
balise en retour, et pas une interface de rendu complte). Le layout flash est utilis pour les messages montrs
par la mthode Controller::flash().
Trois autres layouts, xml, js, et rss, existent dans le coeur permettant de servir rapidement et facilement du
contenu qui nest pas du text/html.

Utiliser les layouts partir de plugins


Introduit dans la version 2.1.

Layouts

93

CakePHP Cookbook Documentation, Version 2.x

Si vous souhaitez utiliser un layout qui existe dans un plugin, vous pouvez utiliser la syntaxe de plugin. Par
exemple pour utiliser le layout de contact partir du plugin Contacts :
class UsersController extends AppController {
public function view_active() {
$this->layout = 'Contacts.contact';
}
}

Elements
Beaucoup dapplications ont des petits blocks de code de prsentation qui doivent tre rpliqus dune
page une autre, parfois des endroits diffrents dans le layout. CakePHP peut vous aider rpter des
parties de votre site web qui doivent tre rutilises. Ces parties rutilisables sont appeles des Elements.
Les publicits, les boites daides, les contrles de navigation, les menus supplmentaires, les formulaires
de connexion et de sortie sont souvent intgrs dans CakePHP en elements. Un element est tout btement
une mini-vue qui peut tre inclue dans dautres vues, dans les layouts, et mme dans dautres elements. Les
elements peuvent tre utiliss pour rendre une vue plus lisible, en plaant le rendu dlments rptitifs dans
ses propres fichiers. Ils peuvent aussi vous aider rutiliser des fragments de contenu dans votre application.
Les elements se trouvent dans le dossier /app/View/Elements/, et ont une extension .ctp. Ils sont
affichs en utilisant la mthode element de la vue :
echo $this->element('helpbox');

Passer des Variables lintrieur dun Element


Vous pouvez passer des donnes dans un element grce au deuxime argument de element :
echo $this->element('helpbox', array(
"helptext" => "Oh, this text is very helpful."
));

Dans le fichier element, toutes les variables passs sont disponibles comme des membres du paramtre du
tableau (de la mme manire que Controller::set() fonctionne dans le controller avec les fichiers
de vues). Dans lexemple ci-dessus, le fichier /app/View/Elements/helpbox.ctp peut utiliser la
variable $helptext :
// A l'intrieur de app/View/Elements/helpbox.ctp
echo $helptext; //outputs "Oh, this text is very helpful."

La mthode View::element() supporte aussi les options pour lelement. Les options supportes sont
cache et callbacks. Un exemple :
echo $this->element('helpbox', array(
"helptext" => "Ceci est pass l'element comme $helptext",
"foobar" => "Ceci est pass l'element via $foobar",
),

94

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

array(
// utilise la configuration de cache "long_view"
"cache" => "long_view",
// dfini true pour avoir before/afterRender appel pour l'element
"callbacks" => true
)
);

La mise en cache delement est facilite par la classe Cache. Vous pouvez configurer les elements devant
tre stocks dans toute configuration de Cache que vous avez dfini. Cela vous donne une grande flexibilit
pour choisir o et combien de temps les elements sont stocks. Pour mettre en cache les diffrentes versions
du mme element dans une application, fournissez une valeur unique de la cl cache en utilisant le format
suivant :
$this->element('helpbox', array(), array(
"cache" => array('config' => 'short', 'key' => 'unique value')
)
);

Vous pouvez tirer profit des elements en utilisant requestAction(). La fonction requestAction()
rcupre les variables de vues partir dune action dun controller et les retourne en tableau. Cela permet
vos elements de fonctionner dans un style MVC pur. Crez une action du controller qui prpare les variables de la vue pour vos elements, ensuite appelez requestAction() depuis lintrieur du deuxime
paramtre de element() pour alimenter en variables de vues lelement depuis votre controller.
Pour ce faire, ajoutez quelque chose comme ce qui suit dans votre controller, en reprenant lexemple du
Post :
class PostsController extends AppController {
// ...
public function index() {
$posts = $this->paginate();
if ($this->request->is('requested')) {
return $posts;
}
$this->set('posts', $posts);
}
}

Et ensuite dans lelement, nous pouvons accder au model des posts pagins. Pour obtenir les cinq derniers
posts dans une liste ordonne, nous ferions ce qui suit :
<h2>Derniers Posts</h2>
<?php
$posts = $this->requestAction(
'posts/index/sort:created/direction:asc/limit:5'
);
?>
<ol>
<?php foreach ($posts as $post): ?>
<li><?php echo $post['Post']['title']; ?></li>
<?php endforeach; ?>
</ol>

Elements

95

CakePHP Cookbook Documentation, Version 2.x

Mise en cache des Elements


Vous pouvez tirer profit de la mise en cache de vue de CakePHP si vous fournissez un paramtre cache. Si
dfini true, cela va mettre en cache lelement dans la configuration default de Cache. Sinon, vous pouvez
dfinir la configuration de cache devant tre utilise. Regardez La mise en cache pour plus dinformations
sur la faon de configurer Cache. Un exemple simple de mise en cache dun element serait par exemple :
echo $this->element('helpbox', array(), array('cache' => true));

Si vous rendez le mme element plus dune fois dans une vue et que vous avez activ la mise en cache,
assurez-vous de dfinir le paramtre key avec un nom diffrent chaque fois. Cela vitera que chaque
appel successif ncrase le rsultat de la mise en cache du prcdent appel de element(). Par exemple :
echo $this->element(
'helpbox',
array('var' => $var),
array('cache' => array('key' => 'first_use', 'config' => 'view_long')
);
echo $this->element(
'helpbox',
array('var' => $differenVar),
array('cache' => array('key' => 'second_use', 'config' => 'view_long')
);

Ce qui est au-dessus va senqurir que les deux rsultats delement sont mis en cache sparment. Si vous
voulez que tous les elements mis en cache utilisent la mme configuration du cache, vous pouvez sauvegarder quelques rptitions, en configurant View::$elementCache dans la configuration de Cache que
vous souhaitez utiliser. CakePHP va utiliser cette configuration, quand aucune nest donne.

Requter les Elements partir dun Plugin


2.0
Pour charger un element dun plugin, utilisez loption plugin (retir de loption data dans 1.x) :
echo $this->element('helpbox', array(), array('plugin' => 'Contacts'));

2.1
Si vous utilisez un plugin et souhaitez utiliser les elements partir de lintrieur dun plugin, utilisez juste
la syntaxe de plugin habituelle. Si la vue est rendue pour un controller/action dun plugin, le nom du plugin
va automatiquement tre prfix pour tous les elements utiliss, moins quun autre nom de plugin ne soit
prsent. Si lelement nexiste pas dans le plugin, il ira voir dans le dossier principal APP.
echo $this->element('Contacts.helpbox');

Si votre vue fait parti dun plugin, vous pouvez ne pas mettre le nom du plugin. Par exemple, si vous tes
dans le ContactsController du plugin Contacts :
96

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

echo $this->element('helpbox');
// et
echo $this->element('Contacts.helpbox');

Sont quivalents et rsulteront au mme element rendu.


Modifi dans la version 2.1 : Loption $options[plugin] a t dprci et le support pour
Plugin.element a t ajout.

Crer vos propres classes de vue


Vous avez peut-tre besoin de crer vos propres classes de vue pour activer des nouveaux types de donnes
de vue, ou ajouter de la logique supplmentaire de rendu de vue personnalise. Comme la plupart des
components de CakePHP, les classes de vue ont quelques conventions :
Les fichiers de classe de View doivent tre mis dans App/View. Par exemple
App/View/PdfView.php.
Les classes de View doivent tre suffixes avec View. Par exemple PdfView.
Quand vous rfrencez les noms de classe de vue, vous devez omettre le suffixe View. Par exemple
$this->viewClass = Pdf;.
Vous voudrez aussi tendre View pour vous assurer que les choses fonctionnent correctement :
// dans App/View/PdfView.php
App::uses('View', 'View');
class PdfView extends View {
public function render($view = null, $layout = null) {
// logique personnalise ici.
}
}

Remplacer la mthode render vous laisse le contrle total sur la faon dont votre contenu est rendu.

API de View
class View
Les mthodes de View sont accessibles dans toutes les vues, element et fichiers de layout. Pour appeler toute
mthode de view, utilisez $this->method()
View::set(string $var, mixed $value)
Les Views ont une mthode set() qui est analogue set() qui se trouvent dans les objets du
controller. Utiliser set() partir de votre fichier de vue va ajouter les variables au layout et aux elements qui seront rendus plus tard. Regarder Les Mthodes du Controller pour plus dinformations sur
lutilisation de set().
Dans votre fichier de vue, vous pouvez faire :
$this->set('activeMenuButton', 'posts');

Crer vos propres classes de vue

97

CakePHP Cookbook Documentation, Version 2.x

Ensuite dans votre fichier de layout la variable $activeMenuButton sera disponible et contiendra
la valeur posts.
View::get(string $var, $default = null)
Rcupre la valeur dune viewVar avec le nom de $var.
Depuis 2.5 vous pouvez fournir une valeur par dfaut dans le cas o la variable nest pas dj dfinie.
Modifi dans la version 2.5 : Largument $default a t ajout dans 2.5.
View::getVar(string $var)
Rcupre la valeur de viewVar avec le nom $var.
Obsolte depuis la version 2.3 : Utilisez View::get() la place.
View::getVars()
Rcupre une liste de toutes les variables de view disponibles dans le cadre de rendu courant. Retourne
un tableau des noms de variable.
View::element(string $elementPath, array $data, array $options = array())
Rend un element ou une vue partielle. Regardez la section sur Elements pour plus dinformations et
dexemples.
View::uuid(string $object, mixed $url)
Gnre un ID de DOM unique pour un objet non pris au hasard, bas sur le type dobjet et lURL.
Cette mthode est souvent utilise par les helpers qui ont besoin de gnrer un ID de DOM unique
pour les elements comme le JsHelper :
$uuid = $this->uuid(
'form',
array('controller' => 'posts', 'action' => 'index')
);
//$uuid contains 'form0425fe3bad'

View::addScript(string $name, string $content)


Ajoute du contenu au buffer des scripts internes. Ce buffer est rendu disponible dans le layout dans
$scripts_for_layout. Cette mthode est utile quand vous crez des helpers qui ont besoin
dajouter du JavaScript ou du CSS directement au layout. Gardez lesprit que les scripts ajouts
partir du layout, ou des elements du layout ne seront pas ajouts $scripts_for_layout.
Cette mthode est plus souvent utilise de lintrieur des helpers, comme pour les helpers JSHelper
et HTMLHelper.
Obsolte depuis la version 2.1 : Utilisez les fonctionnalits Utiliser les Blocs de Vues la place.
View::blocks()
Rcupre les noms de tous les blocks dfinis en tant que tableau.
View::start($name)
Commence un block de capture pour un block de vue. Regardez la section Utiliser les Blocs de Vues
pour avoir des exemples.
Introduit dans la version 2.1.
View::end()
Termine le block de capture ouvert le plus en haut. Regardez la section sur les Utiliser les Blocs de
Vues pour avoir des exemples.
Introduit dans la version 2.1.
98

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

View::append($name, $content)
Ajoute dans le block avec $name. Regardez la section sur les Utiliser les Blocs de Vues pour des
exemples.
Introduit dans la version 2.1.
View::prepend($name, $content)
Ajoute avant dans le block avec $name. Regardez la section Utiliser les Blocs de Vues pour des
exemples.
Introduit dans la version 2.3.
View::startIfEmpty($name)
Commence un block si il est vide. Tout le contenu dans le block va tre captur et cart si le block
est dj dfini.
Introduit dans la version 2.3.
View::assign($name, $content)
Assigne la valeur dun block. Cela va surcharger tout contenu existant. Regardez la section sur les
Utiliser les Blocs de Vues pour des exemples.
Introduit dans la version 2.1.
View::fetch($name, $default = )
Rcupre la valeur dun block. Si un block est vide ou non dfini, va tre retourn. Regardez la
section sur les Utiliser les Blocs de Vues pour des exemples.
Introduit dans la version 2.1.
View::extend($name)
Etend la vue/element/layout courant avec celle contenu dans $name. Regardez la section sur les Vues
tendues pour les exemples.
Introduit dans la version 2.1.
property View::$layout
Dfinit le layout qui va entourer la vue courante.
property View::$elementCache
La configuration de cache utilise pour les elements de cache. Dfinir cette proprit va changer la
configuration par dfaut utilise pour mettre en cache les elements. Celle par dfaut peut tre surcharge en utilisant loption cache dans la mthode element.
property View::$request
Une instance de CakeRequest. Utilisez cette instance pour accder aux informations qui concernent
la requte courante.
property View::$output
Contient le dernier contenu rendu dune view, ou dun fichier de view, ou dun contenu de layout.
Obsolte depuis la version 2.1 : Utilisez $view->Blocks->get(content); la place.
property View::$Blocks
Une instance de ViewBlock. Utilis pour fournir la fonctionnalit des blocks de view dans le rendu
de view.
Introduit dans la version 2.1.

API de View

99

CakePHP Cookbook Documentation, Version 2.x

En savoir plus sur les vues


Thmes
Vous pouvez profiter des thmes, ce qui facilite le changement du visuel et du ressenti de votre page rapidement et facilement.
Pour utiliser les thmes, spcifiez le nom du thme dans votre controller :
class ExempleController extends AppController {
public $theme = 'Exemple';
}

Modifi dans la version 2.1 : Les versions antrieures 2.1 ont besoin de dfinir $this->viewClass =
Theme. 2.1 enlve cette condition puisque la classe normale View supporte les thmes.
Vous pouvez galement dfinir ou modifier le nom du thme dans une action ou dans les fonctions de
callback beforeFilter ou beforeRender :
$this->theme = 'AutreExemple';

Les fichiers de vue du thme ont besoin dtre dans le dossier /app/View/Themed/. Dans le dossier
du thme, crez un dossier utilisant le mme nom que le nom de votre thme. Par exemple, Le thme cidessus serait trouv dans /app/View/Themed/AutreExemple. Il est important de se souvenir que
CakePHP attend des noms de thme en CamelCase. Au-del de a, la structure de dossier dans le dossier
/app/View/Themed/Exemple/ est exactement le mme que /app/View/.
Par exemple, le fichier de vue pour une action edit dun controller Posts se trouvera dans
/app/View/Themed/Exemple/Posts/edit.ctp. Les fichiers de Layout se trouveront dans
/app/View/Themed/Exemple/Layouts/.
Si un fichier de vue ne peut pas tre trouv dans le thme, CakePHP va essayer de localiser le fichier de vue
dans le dossier /app/View/. De cette faon, vous pouvez crer des fichiers de vue master et simplement
les remplacer au cas par cas au sein de votre dossier de thme.
Assets du thme
Les thmes peuvent contenir des assets statiques ainsi que des fichiers de vue. Un thme peut inclure tout
asset ncessaire dans son rpertoire webroot. Cela permet un packaging facile et une distribution des thmes.
Pendant le dveloppement, les requtes pour les assets du thme seront grs par Dispatcher. Pour
amliorer la performance des environnements de production, il est recommand, soit que vous fassiez un
lien symbolique, soit que vous copiez les assets du thme dans le webroot de application. Voir ci-dessous
pour plus dinformations.
Pour utiliser le nouveau webroot du thme, crez des rpertoires comme :
``app/View/Themed/<nomDuTheme>/webroot<chemin_vers_fichier>``

dans votre thme. Le Dispatcher se chargera de trouver les assets du thme corrects dans vos chemins de
vue.

100

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

Tous les helpers integrs dans CakePHP ont intgrs lexistence des thmes et vont crer des chemins daccs
corrects automatiquement. Comme pour les fichiers de vue, si un fichier nest pas dans le dossier du thme,
il sera par dfaut dans le dossier principal webroot
//Quand dans un thme avec un nom de 'purple_cupcake'
$this->Html->css('main.css');
//cre un chemin comme
/theme/purple_cupcake/css/main.css
//et fait un lien vers
app/View/Themed/PurpleCupcake/webroot/css/main.css

Augmenter la performance des assets du plug-in et du thme

Cest un fait bien connu que de servir les assets par le biais de PHP est assur dtre plus lent que de servir ces
assets sans invoquer PHP. Et tandis que lquipe du coeur a pris des mesures pour rendre le plugin et lasset
du thme servis aussi vite que possible, il peut y avoir des situations o plus de performance est requis. Dans
ces situations, il est recommand soit que vous fassiez un lien symbolique soit que vous fassiez une copie
sur les assets du plug-in/thme vers des rpertoires dans app/webroot avec des chemins correspondant
ceux utiliss par cakephp.
app/Plugin/DebugKit/webroot/js/my_file.js devient app/webroot/DebugKit/js/my_file.js.
app/View/Themed/Navy/webroot/css/navy.css devient app/webroot/theme/Navy/css/navy.css

Vues Media
class MediaView
Obsolte depuis la version 2.3 : Utilisez Envoyer des fichiers la place.
Les vues Media vous permettent denvoyer des fichiers binaires lutilisateur. Par exemple, vous souhaiteriez avoir un rpertoire de fichiers en dehors de webroot pour empcher les utilisateurs de faire un lien
direct sur eux. Vous pouvez utiliser la vue Media pour tirer le fichier partir dun fichier spcial dans /app/,
vous permettant damliorer lauthentification avant la livraison du fichier lutilisateur.
Pour utiliser la vue Media, vous avez besoin de dire votre controller dutiliser la classe MediaView au lieu
de la classe View par dfaut. Aprs a, passez juste les paramtres en plus pour spcifier o votre fichier se
trouve :
class ExempleController extends AppController {
public function download() {
$this->viewClass = 'Media';
// Download app/outside_webroot_dir/example.zip
$params = array(
'id'
=> 'example.zip',
'name'
=> 'example',
'download' => true,
'extension' => 'zip',
'path'
=> APP . 'outside_webroot_dir' . DS
);

En savoir plus sur les vues

101

CakePHP Cookbook Documentation, Version 2.x

$this->set($params);
}
}

Ici vous trouvez un exemple de rendu dun fichier qui a un type mime qui nest pas inclu dans le tableau
$mimeType de MediaView. Nous utilisons aussi un chemin relatif qui va tre par dfaut dans votre dossier
app/webroot :
public function download() {
$this->viewClass = 'Media';
// Render app/webroot/files/example.docx
$params = array(
'id'
=> 'example.docx',
'name'
=> 'example',
'extension' => 'docx',
'mimeType' => array(
'docx' => 'application/vnd.openxmlformats-officedocument' .
'.wordprocessingml.document'
),
'path'
=> 'files' . DS
);
$this->set($params);
}

Paramtres configurables
id LID est le nom du fichier tel quil rside sur le serveur de fichiers, y compris lextension de fichier.
name Le nom vous permet de spcifier un nom de fichier alternatif envoyer lutilisateur. Spcifiez le
nom sans lextension du fichier.
download Une valeur bolenne indiquant si les en-ttes doivent tre dfinis pour forcer le tlchargement.
extension Lextension du fichier. Ceci est en correspondance avec une liste interne de types mime acceptables. Si le type MIME spcifi nest pas dans la liste (ou envoy dans le tableau de paramtres
mimeType), le fichier ne sera pas tlcharg.
path Le nom du dossier, y compris le sparateur de rpertoire finale. Le chemin doit tre absolu, mais peut
tre par rapport au dossier app/webroot.
mimeType Un tableau avec des types MIME supplmentaires fusionner avec une liste interne dans MediaView de types mime acceptables.
cache Une valeur boolenne ou entire - Si la valeur est vraie, elle permettra aux navigateurs de mettre en
cache le fichier (par dfaut false si non dfinie), sinon rglez le sur le nombre de secondes dans le
futur pour lorsque le cache expirera.

Vues JSON et XML


Deux nouvelles classes de vue dans CakePHP 2.1. Les vues XmlView et JsonView vous laissent crer
facilement des rponses XML et JSON, et sont intgres avec RequestHandlerComponent.

102

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

En activant RequestHandlerComponent dans votre application, et en activant le support pour les extensions xml et/ou json, vous pouvez automatiquement vous appuyer sur les nouvelles classes de vue.
XmlView et JsonView feront rfrence aux vues de donnes pour le reste de cette page.
Il y a deux faons de gnrer des vues de donnes. La premire est en utilisant la cl _serialize, et la
seconde en crant des fichiers de vue normaux.
Activation des vues de donnes dans votre application
Avant que vous puissiez utiliser les classes de vue de donnes, vous aurez besoin de faire un peu de configuration :
1. Activez les extensions json et/ou xml avec Router::parseExtensions(). Cela permettra au
Router de grer les multiples extensions.
2. Ajoutez le RequestHandlerComponent la liste de components de votre controller. Cela activera automatiquement le changement de la classe de vue pour les types de contenu.
Introduit dans la version 2.3 : La mthode RequestHandlerComponent::viewClassMap() a t
ajoute pour lier les types aux viewClasses. La configuration de viewClassMap ne va pas fonctionner avec
les versions prcdentes.
Aprs avoir ajout Router::parseExtensions(json); votre fichier de routes, CakePHP
changera automatiquement les classes de vue quand une requte sera faite avec lextension .json, ou
quand len-tte Accept sera application/json.
Utilisation des vues de donnes avec la cl _serialize
La cl _serialize est une variable de vue spciale qui indique quel autre(s) variable(s) de vue devraient
tre srialise(s) quand on utilise la vue de donnes. Cela vous permet de sauter la dfinition des fichiers de
vue pour vos actions de controller si vous navez pas besoin de faire un formatage avant que vos donnes ne
soient converties en json/xml.
Si vous avez besoin de faire tout type de formatage ou de manipulation de vos variables de vue avant la
gnration de la rponse, vous devrez utiliser les fichiers de vue. La valeur de _serialize peut tre soit
une chane de caractre, soit un tableau de variables de vue srialiser :
class PostsController extends AppController {
public $components = array('RequestHandler');
public function index() {
$this->set('posts', $this->Paginator->paginate());
$this->set('_serialize', array('posts'));
}
}

Vous pouvez aussi dfinir _serialize en tableau de variables de vue combiner :


class PostsController extends AppController {
public $components = array('RequestHandler');
public function index() {

En savoir plus sur les vues

103

CakePHP Cookbook Documentation, Version 2.x

// some code that created $posts and $comments


$this->set(compact('posts', 'comments'));
$this->set('_serialize', array('posts', 'comments'));
}
}

Dfinir _serialize en tableau a le bnfice supplmentaire dajouter automatiquement un elment de


top-niveau <response> en utilisant XmlView. Si vous utilisez une valeur de chane de caractre pour
_serialize et XmlView, assurez-vous que vos variables de vue aient un elment unique de top-niveau.
Sans un elment de top-niveau, le Xml ne pourra tre gnr.
Utilisation dune vue de donnes avec les fichiers de vue
Vous devriez utiliser les fichiers de vue si vous avez besoin de faire des manipulations du contenu de votre
vue avant de crer la sortie finale. Par exemple, si vous avez des posts, qui ont un champ contenant du HTML
gnr, vous aurez probablement envie domettre ceci partir dune rponse JSON. Cest une situation o
un fichier de vue est utile :
// Code du controller
class PostsController extends AppController {
public function index() {
$this->set(compact('posts', 'comments'));
}
}
// Code de la vue - app/View/Posts/json/index.ctp
foreach ($posts as &$post) {
unset($post['Post']['generated_html']);
}
echo json_encode(compact('posts', 'comments'));

Vous pouvez faire des manipulations encore beaucoup plus complexes, comme utiliser les helpers pour
formater.
Note : Les classes de vue de donnes ne supportent pas les layouts. Elles supposent que le fichier de vue va
afficher le contenu srialis.
class XmlView
Une classe de vue pour la gnration de vue de donnes Xml. Voir au-dessus pour savoir comment
vous pouvez utiliser XmlView dans votre application
Par dfaut quand on utilise _serialize, XmlView va enrouler vos variables de vue srialises
avec un noeud <response>. Vous pouvez dfinir un nom personnalis pour ce noeud en utilisant la
variable de vue _rootNode.
Introduit dans la version 2.3 : La fonctionnalit _rootNode a t ajoute.
class JsonView
Une classe de vue pour la gnration de vue de donnes Json. Voir au-dessus pour savoir comment
vous pouvez utiliser XmlView dans votre application.

104

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

JSONP response
Introduit dans la version 2.4.
Quand vous utilisez JsonView, vous pouvez utiliser la variable de vue spciale _jsonp pour permettre de
retourner une rponse JSONP. La dfinir true fait que la classe de vue vrifie si le paramtre de chaine
de la requte nomme callback est dfinie et si cest la cas, permet denrouler la rponse json dans le nom
de la fonction fournie. Si vous voulez utiliser un nom personnalis de paramtre de requte la place de
callback, dfinissez _jsonp avec le nom requis la place de true.

Helpers (Assistants)
Les Helpers (Assistants) sont des classes comme les components, pour la couche de prsentation de votre
application. Ils contiennent la logique de prsentation qui est partage entre plusieurs vues, elements ou
layouts. Ce chapitre vous montrera comment crer vos propres helpers et soulignera les tches basiques que
les helpers du cur de CakePHP peuvent vous aider accomplir.
CakePHP dispose dun certain nombre de helpers qui aident la cration des vues. Ils aident la cration
de balises bien-formates (y compris les formulaires), aident la mise en forme du texte, les dures et les
nombres, et peuvent mme acclrer la fonctionnalit AJAX. Pour plus dinformations sur les helpers inclus
dans CakePHP, regardez le chapitre pour chaque helper :
CacheHelper
class CacheHelper(View $view, array $settings = array())
Le helper Cache permet la mise en cache des layouts (mises en page) et des vues permettant de gagner du
temps pour la rcupration de donnes rptitives. Le systme de cache des vues de CakePHP parse les
layout et les vues comme de simple fichier PHP + HTML. Il faut noter que le helper Cache fonctionne de
faon assez diffrente des autres helpers. Il ne possde pas de mthodes appeles directement. A la place,
une vue est marque de tags, indiquant quels blocs de contenus ne doivent pas tre mis en cache. Le Helper
Cache utilise alors les callbacks du helper pour traiter le fichier et ressortir pour gnrer le fichier de cache.
Quand une URL est appele, CakePHP vrifie si cette requte a dj t mise en cache. Si cest le cas, le
processus de distribution de lURL est abandonn. Chacun des blocs non mis en cache sont rendus selon le
processus normal, et la vue est servie. Cela permet de gagner beaucoup de temps pour chaque requte vers
une URL mise en cache, puisquun minimum de code est excut. Si CakePHP ne trouve pas une vue mise
en cache, ou si le cache a expir pour lURL appele, le processus de requte normal se poursuit.
Utilisation du Helper

Il y a deux tapes franchir avant de pouvoir utiliser le Helper Cache. Premirement dans votre
APP/Config/core.php d-commenter lappel Configure write pour Cache.check. Ceci dira
CakePHP de regarder dans le cache, et de gnrer laffichage des fichiers en cache lors du traitement des
demandes.
Une fois que vous avez dcomment la ligne Cache.check vous devez ajouter le helper votre tableau
$helpers de votre controller :
En savoir plus sur les vues

105

CakePHP Cookbook Documentation, Version 2.x

class PostsController extends AppController {


public $helpers = array('Cache');
}

Vous devrez aussi ajouter CacheDispatcher vos filtres de dispatcher dans votre bootstrap :
Configure::write('Dispatcher.filters', array(
'CacheDispatcher'
));

Introduit dans la version 2.3 : Si vous avez une configuration avec des domaines ou des langages multiples,
vous pouvez utiliser Configure : :write(Cache.viewPrefix, YOURPREFIX) ; pour stocker les fichiers de
vue prfixs mis en cache.
Options de configuration supplmentaires Le Helper Cache (CacheHelper) dispose de plusieurs options
de configuration additionnelles que vous pouvez utiliser pour ajuster et rgler ces comportements. Ceci est
ralis a travers la variable $cacheAction dans vos controllers. $cacheAction doit tre rgler par un
tableau qui contient laction que vous voulez cacher, et la dure en seconde durant laquelle vous voulez que
cette vue soit cache. La valeur du temps peut tre exprim dans le format strtotime(). (ex. 1 hour,
ou 3 minutes).
En utilisant lexemple dun controller darticles ArticlesController, qui reoit beaucoup de trafic qui ont
besoins dtre mise en cache :
public $cacheAction = array(
'view' => 36000,
'index' => 48000
);

Ceci mettra en cache laction view 10 heures et laction index 13 heures. En plaant une valeur usuelle de
strtotime() dans $cacheAction vous pouvez mettre en cache toutes les actions dans le controller :
public $cacheAction = "1 hour";

Vous pouvez aussi activer les callbacks controller/component pour les vues caches cres avec
CacheHelper. Pour faire cela, vous devez utiliser le format de tableau pour $cacheAction et crer
un tableau comme ceci :
public $cacheAction = array(
'view' => array('callbacks' => true, 'duration' => 21600),
'add' => array('callbacks' => true, 'duration' => 36000),
'index' => array('callbacks' => true, 'duration' => 48000)
);

En paramtrant callbacks => true vous dites au CacheHelper (Assistant Cache) que vous voulez que
les fichiers gnrs crent les components et les models pour le controller. De manire additionnelle, lance la
mthode initialize du component, le beforeFilter du controller, et le dmarrage des callbacks de component.
Note : Dfinir callbacks => true fait chouer en partie le but de la mise en cache. Cest aussi la raison pour
laquelle ceci est dsactiv par dfaut.

106

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

Marquer les contenus Non-Cachs dans les Vues

Il y aura des fois o vous ne voudrez par mettre en cache une vue intgrale. Par exemple, certaines parties
dune page peuvent tre diffrentes, selon que lutilisateur est actuellement identifi ou quil visite votre site
en tant quinvit.
Pour indiquer que des blocs de contenu ne doivent pas tre mis en cache, entourez-les par < !nocache>
< !/nocache> comme ci-dessous :
<!--nocache-->
<?php if ($this->Session->check('User.name')) : ?>
Bienvenue, <?php echo h($this->Session->read('User.name')); ?>.
<?php else: ?>
<?php echo $html->link('Login', 'users/login')?>
<?php endif; ?>
<!--/nocache-->

Note : Vous ne pouvez pas utiliser les tags nocache dans les lments. Puisquil ny a pas de callbacks
autour des lments, ils ne peuvent tre cachs.
Il est noter, quune fois une action mise en cache, la mthode du controller correspondante ne sera plus
appele. Quand un fichier cache est cr, lobjet request, et les variables de vues sont srialises avec
serialize() de PHP.
Avertissement : Si vous avez des variables de vues qui contiennent des contenus inserialisable comme
les objets SimpleXML, des gestionnaires de ressource (resource handles), ou des classes closures Il se
peut que vous ne puissiez pas utiliser la mise en cache des vues.

Nettoyer le Cache

Il est important de se rappeler que CakePHP va nettoyer le cache si un model utilis dans la vue mise en
cache a t modifi. Par exemple, si une vue mise en cache utilise des donnes du model Post et quil y a
eu une requte INSERT, UPDATE, ou DELETE sur Post, le cache de cette vue est nettoy, et un nouveau
contenu sera gnr la prochaine requte.
Note : Ce systme de nettoyage automatique requiert que le nom du controller/model fasse partie de lURL.
Si vous avez utilis le routing pour changer vos URLs cela ne fonctionnera pas.
Si vous avez besoin de nettoyer le cache manuellement, vous pouvez le faire en appelant Cache : :clear().
Cela nettoiera toutes les donnes mises en cache, lexception des fichiers de vues mis en cache. Si vous
avez besoin de nettoyer les fichiers de vues, utilisez clearCache().
Flash
class FlashHelper(View $view, array $config = array())

En savoir plus sur les vues

107

CakePHP Cookbook Documentation, Version 2.x

FlashHelper fournit une faon de rendre les messages flash qui sont dfinis dans $_SESSION par FlashComponent. FlashComponent et FlashHelper utilisent principalement des elements pour rendre les messages
flash. Les elements flash se trouvent dans le rpertoire app/View/Elements/Flash. Vous remarquerez
que le template de lApp de CakePHP est livr avec deux elements flash : success.ctp et error.ctp.
FlashHelper remplace la mthode flash() de SessionHelper et doit tre utilis la place de cette
mthode.
Rendre les Messages Flash

Pour afficher un message flash, vous pouvez simplement utiliser la mthode render() du FlashHelper :
<?php echo $this->Flash->render() ?>

Par dfaut, CakePHP utilise une cl flash pour les messages flash dans une session. Mais si vous spcifiez
une cl lors de la dfinition du message flash dans FlashComponent, vous pouvez spcifier la cl flash
rendre :
<?php echo $this->Flash->render('other') ?>

Vous pouvez aussi surcharger toutes les options qui sont dfinies dans FlashComponent :
// Dans votre Controller
$this->Flash->set('The user has been saved.', array(
'element' => 'success'
));
// Dans votre View: Va utiliser great_success.ctp au lieu de success.ctp
<?php echo $this->Flash->render('flash', array(
'element' => 'great_success'
));

Note : Par dfaut, CakePHP nchappe pas le HTML dans les messages flash. Si vous utilisez une requte
ou des donnes dutilisateur dans vos messages flash, vous devez les chapper avec h lors du formatage de
vos messages.
Pour plus dinformations sur le tableau doptions disponibles, consultez la section FlashComponent.
FormHelper
class FormHelper(View $view, array $settings = array())
Le Helper Form prend en charge la plupart des oprations lourdes en cration du formulaire. Le Helper
Form se concentre sur la possibilit de crer des formulaires rapidement, dune manire qui permettra de
rationaliser la validation, la re-population et la mise en page (layout). Le Helper Form est aussi flexible
- Il va faire peu prs tout pour vous en utilisant les conventions, ou vous pouvez utiliser des mthodes
spcifiques pour ne prendre uniquement que ce dont vous avez besoin.

108

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

Cration de Formulaire

La premire mthode dont vous aurez besoin dutiliser pour prendre pleinement avantage du Helper Form
(Helper Formulaire) est create(). Cette mthode affichera un tag douverture de formulaire.
FormHelper::create(string $model = null, array $options = array())
Tous les paramtres sont optionnels. Si create() est appele sans paramtres, CakePHP supposera
que vous voulez crer un formulaire en rapport avec le controller courant, ou lURL actuelle. La
mthode par dfaut pour les formulaires est POST. Llment du formulaire est galement renvoy
avec un DOM ID. Cet identifiant est cr partir du nom du model, et du nom du controller en
notation CamelCase (les majuscules dlimitent les mots). Si jappelle create() dans une vue de
UsersController, jobtiendrai ce genre de rendu dans ma vue :
<form id="UserAddForm" method="post" action="/users/add">

Note :
Vous pouvez aussi passer false pour $model. Ceci placera vos donne de formulaire dans le tableau : $this->request->data (au lieu du sous
tableau :$this->request->data[Model]). Cela peut tre pratique pour des formulaires courts qui ne reprsenteraient rien dans votre base de donnes.
La mthode create() nous permet galement de personnaliser plusieurs paramtres. Premirement,
vous pouvez spcifier un nom de model. Ce faisant, vous modifiez le contexte de ce formulaire. Tous
les champs seront supposs dpendre de ce model (sauf si spcifi), et tous les models devront tre
lis lui. Si vous ne spcifiez pas de model, CakePHP supposera que vous utilisez le model par dfaut
pour le controller courant.
// si vous tes sur /recipes/add
echo $this->Form->create('Recipe');

Affichera :
<form id="RecipeAddForm" method="post" action="/recipes/add">

Ce formulaire enverra les donnes votre action add() de RecipesController (RecettesController)


. Cependant, vous pouvez utiliser la mme logique pour crer et modifier des formulaires. Le helper
Form utilise la proprit $this->request->data pour dtecter automatiquement sil faut crer
un formulaire dajout ou de modification. Si $this->request->data contient un tableau nomm
daprs le model du formulaire , et que ce tableau contient une valeur non nulle pour la cl primaire
du model, alors le FormHelper crera un formulaire de modification pour cet enregistrement prcis.
Par exemple, si on va ladresse http ://site.com/recipes/edit/5, nous pourrions avoir cela :
// Controller/RecipesController.php:
public function edit($id = null) {
if (empty($this->request->data)) {
$this->request->data = $this->Recipe->findById($id);
} else {
// La logique de sauvegarde se fera ici
}
}
// View/Recipes/edit.ctp:

En savoir plus sur les vues

109

CakePHP Cookbook Documentation, Version 2.x

// Puisque $this->request->data['Recipe']['id'] = 5,
// nous aurons un formulaire d'dition
<?php echo $this->Form->create('Recipe'); ?>

Affichera :
<form id="RecipeEditForm" method="post" action="/recipes/edit/5">
<input type="hidden" name="_method" value="PUT" />

Note : Comme cest un formulaire de modification, un champ cach (hidden) est cr pour rcrire
la mthode HTTP par dfaut
A la cration de formulaires pour les models dans des plugins. Nous devrons toujours utiliser la
syntaxe de plugin la cration dun formulaire. Cela assurera que le formulaire est correctement
gnr :
echo $this->Form->create('ContactManager.Contact');

Le tableau $options est lendroit o la plupart des paramtres de configurations sont stocks. Ce
tableau spcial peut contenir un certain nombre de paires cl-valeur qui peuvent affecter la manire
dont le formulaire sera cr.
Modifi dans la version 2.0.
LUrl par dfaut pour tous les formulaires, est maintenant lUrl incluant passed, named, et les
paramtres de requte (querystring). Vous pouvez redfinir cette valeur par dfaut en fournissant
$options[url] en second paramtre de $this->Form->create().
Options pour create() Il y plusieurs options pour create() :
$options[type] Cette cl est utilise pour spcifier le type de formulaire crer. Les valeurs que
peuvent prendre cette variable sont post, get, file, put et delete.
Choisir post ou get changera la mthode de soumission du formulaire en fonction de votre choix.
echo $this->Form->create('User', array('type' => 'get'));

Affichera :
<form id="UserAddForm" method="get" action="/users/add">

En spcifiant file cela changera la mthode de soumission post, et ajoutera un enctype


multipart/form-data dans le tag du formulaire. Vous devez lutiliser si vous avez des demandes de
fichiers dans votre formulaire. Labsence de cet attribut enctype empchera le fonctionnement de lenvoi de fichiers.
echo $this->Form->create('User', array('type' => 'file'));

Affichera :
<form id="UserAddForm" enctype="multipart/form-data"
method="post" action="/users/add">

Quand vous utilisez put ou delete, votre formulaire aura un fonctionnement quivalent un formulaire
de type post, mais quand il sera envoy, la mthode de requte HTTP sera respectivement rcrite avec
PUT ou DELETE. Cela permettra CakePHP de crer son propre support REST dans les navigateurs
web.
110

Chapitre 5. Views (Vues)

CakePHP Cookbook Documentation, Version 2.x

$options[action] La cl action vous permet de dfinir vers quelle action de votre controller
pointera le formulaire. Par exemple, si vous voulez que le formulaire appelle laction login() de votre
controller courant, vous creriez le tableau $options comme ceci
echo $this->Form->create('User', array('action' => 'login'));

Affichera :
<form id="UserLoginForm" method="post" action="/users/login">
</form>

$options[url] Si laction que vous dsirez appeler avec le formulaire nest pas dans le controller
courant, vous pouvez spcifier une URL dans le formulaire en utilisant la cl url de votre tableau $options. LURL ainsi fournie peut tre relative votre application CakePHP
echo $this->Form->create(null, array(
'url' => array('controller' => 'recipes', 'action' => 'add')
));

Affichera :
<form method="post" action="/recipes/add">

ou pointer vers un domaine extrieur :


echo $this->Form->create(null, array(
'url' => 'http://www.google.com/search',
'type' => 'get'
));

Affichera :
<form method="get" action="http://www.google.com/search">

Regardez aussi la mthode HtmlHelper::url() pour plus dexemples sur les diffrents types
dURLs.
$options[default] Si la variable default est dfinie false, laction de soumission du formulaire est change de telle manire que le bouton submit (de soumission) ne soumet plus le formulaire.
Si le formulaire a t cr pour tre soumis par AJAX, mettre la variable default FALSE supprime
le comportement par dfaut du formulaire, ainsi vous pouvez collecter les donnes et les soumettre par
AJAX la place.
$options[inputDefaults] Vous pouvez dclarer un jeu doptions par dfaut pour input()
avec la cl inputDefaults pour personnaliser vos input par dfaut :
echo $this->Form->create('User', array(
'inputDefaults' => array(
'label' => false,
'div' => false
)
));

Tous les input crs partir de ce point hriteraient des options dclares dans inputDefaults. Vous pouvez
redfinir le defaultOptions en dclarant loption dans lappel input() :

En savoir plus sur les vues

111

CakePHP Cookbook Documentation, Version 2.x

// Pas de div, Pas de label


echo $this->Form->input('password');
// a un lment label
echo $this->Form->input('username', array('label' => 'Username'));

Fermer le Formulaire

FormHelper::end($options = null, $secureAttributes = array())


Le FormHelper inclut galement une mthode end() qui complte le marquage du formulaire. Souvent, end() affiche juste la base fermante du formulaire, mais lutilisation de end()
permet galement au FormHelper dajouter les champs caches dont le component Security
SecurityComponent besoin. :
<?php echo $this->Form->create(); ?>
<!-- Ici les lments de Formulaire -->
<?php echo $this->Form->end(); ?>

Si une chane est fournie comme premier argument end(), le FormHelper affichera un bouton submit
nomm en consquence en mme temps que la balise de fermeture du formulaire.
echo $this->Form->end('Termine');

Affichera :
<div class="submit">
<input type="submit" value="Termine" />
</div>
</form>

Vous pouvez spcifier des p