Você está na página 1de 270

CakePHP Cookbook Documentation

Verso 3.x

Cake Software Foundation

02 February, 2016

Contedo

CakePHP num piscar de olhos


Convenes Sobre Configurao .
A camada Model . . . . . . . . .
A camada View . . . . . . . . . .
A camada Controller . . . . . . .
Ciclo de Requisies do CakePHP
Apenas o Comeo . . . . . . . . .
Leitura adicional . . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

1
1
1
2
2
3
4
4

Guia de Incio Rpido


11
Tutorial - Criando um Bookmarker - Parte 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Tutorial - Criando um Bookmarker - Parte 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.0 - Guia de migrao


Requerimentos . . . . . . . . . . . . . . . .
Ferramenta de atualizao . . . . . . . . . . .
Layout do diretrio da aplicao . . . . . . .
O CakePHP deve ser instalado via Composer
Namespaces . . . . . . . . . . . . . . . . . .
Constantes removidas . . . . . . . . . . . . .
Configurao . . . . . . . . . . . . . . . . .
Novo ORM . . . . . . . . . . . . . . . . . .
Bsico . . . . . . . . . . . . . . . . . . . . .
Debug . . . . . . . . . . . . . . . . . . . . .
Especificaes/Configuraes de objetos . . .
Cache . . . . . . . . . . . . . . . . . . . . .
Core . . . . . . . . . . . . . . . . . . . . . .
Console . . . . . . . . . . . . . . . . . . . .
Shell / Tarefa . . . . . . . . . . . . . . . . .
Eventos . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

25
25
25
25
26
26
26
26
27
27
27
27
27
28
29
30
31
i

Log . . . . . . . . . .
Roteamento . . . . . .
Rede . . . . . . . . . .
Sesses . . . . . . . .
Network\Http . . . . .
Network\Email . . . .
Controller . . . . . . .
Controller\Components
Model . . . . . . . . .
Sute de Testes . . . . .
View . . . . . . . . . .
View\Helper . . . . . .
I18n . . . . . . . . . .
Localizao . . . . . .
Testes . . . . . . . . .
Utilitrios . . . . . . .
4

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

31
32
34
34
35
35
35
37
39
40
41
43
47
49
49
49

Tutoriais & Exemplos


Tutorial - Criando um Bookmarker - Parte 1 . . . . . . .
Tutorial - Criando um Bookmarker - Parte 2 . . . . . . .
Tutorial - Criando um Blog - Parte 1 . . . . . . . . . . .
Tutorial - Criando um Blog - Parte 2 . . . . . . . . . . .
Tutorial - Criando um Blog - Parte 3 . . . . . . . . . . .
Tutorial - Criando um Blog - Autenticao e Autorizao

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

53
53
59
67
70
81
88

Contribuindo
Documentao . . . . . . . .
Tickets . . . . . . . . . . . .
Cdigo . . . . . . . . . . . .
Padres de cdigo . . . . . .
Guia de retrocompatibilidade

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

97
97
97
97
98
98

Instalao
Requisitos . . . . . . . . . .
Instalando o CakePHP . . .
Permisses . . . . . . . . .
Servidor de Desenvolvimento
Produo . . . . . . . . . .
Aquecendo . . . . . . . . .
Reescrita de URL . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

99
99
100
101
101
102
102
103

Configurao
109
Additional Class Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Roteamento
111
Connecting Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Objetos de requisio e resposta


113
Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

ii

10 Controllers (Controladores)
O App Controller . . . . . . . . . . . . . . .
Fluxo de requisies . . . . . . . . . . . . .
Mtodos (actions) de controllers . . . . . . .
Redirecionando para outras pginas . . . . .
Carregando models adicionais . . . . . . . .
Paginando um model . . . . . . . . . . . . .
Configurando components para carregar . . .
Configurando helpers para carregar . . . . . .
Ciclo de vida de callbacks em uma requisio
Mais sobre controllers . . . . . . . . . . . . .
11 Views (Visualizao)
Using View Blocks .
Layouts . . . . . . .
Elements . . . . . . .
More About Views .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

115
115
116
117
120
121
122
122
123
123
124

.
.
.
.

127
127
127
127
127

12 Models (Modelos)
133
Exemplo rpido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Mais informao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
13 Authentication

143

14 Bake Console
145
Instalao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
15 Caching

147

16 Console e Shells
O Console do CakePHP . . . . . . . . . . .
Criando uma Shell . . . . . . . . . . . . .
Tasks de Shell . . . . . . . . . . . . . . . .
Invocando outras Shells a partir da sua Shell
Recenendo Input de usurios . . . . . . . .
Criando Arquivos . . . . . . . . . . . . . .
Sada de dados do Console . . . . . . . . .
Opes de configurao e Gerao de ajuda
Roteamento em Shells / CLI . . . . . . . .
Mtodos enganchados . . . . . . . . . . . .
Mais tpicos . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

17 Debugging
18 Implantao
Atualizar config/app.php . . . . . . . . .
Checar a segurana . . . . . . . . . . . .
Definir a raiz do documento . . . . . . . .
Aprimorar a performance de sua aplicao

149
149
150
152
154
154
154
155
157
165
165
165
169

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

171
171
172
172
172

iii

19 Email

173

20 Erros & Excees

175

21 Sistema de eventos

177

22 Internacionalizao e Localizao

179

23 Logging

181

24 Formulrios sem models

183

25 Pagination

185

26 Plugins

187

27 REST

189

28 Segurana
191
Segurana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Cross Site Request Forgery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
29 Sessions

193

30 Testing
Instalando o PHPUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configurao do banco de dados test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controller Integration Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

195
195
196
196

31 Validao

197

32 App Class

199

33 Collections (Colees)

201

34 Arquivos & Pastas

203

35 Hash

205

36 Http Client

207

37 Inflector

209

38 Nmero

211

39 Objetos de Registro

213

40 Texto

215

41 Tempo

217

iv

42 Xml

219

43 Constantes e Funes

221

44 Debug Kit
Instalao . . . . . . . . . . . . . .
Armazenamento do DebugKit . . .
Uso da barra de ferramentas . . . .
Usando o painel History . . . . . . .
Desenvolvendo seus prprios painis

223
223
223
224
224
224

45 Migrations

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

227

46 Apndices
229
Guia de Migrao para a verso 3.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Informaes Gerais . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
PHP Namespace Index

259

ndice

261

vi

CAPTULO 1

CakePHP num piscar de olhos

O CakePHP concebido para tornar tarefas de desenvolvimento web mais simples e fceis. Por fornecer
uma caixa de ferramentas completa para voc poder comear, o CakePHP funciona bem em conjunto ou
isoladamente.
O objetivo desta anlise introduzir os conceitos gerais presentes no CakePHP, e lhe dar uma rpida viso
geral de como estes conceitos so implementados. Se voc est vido para comear um projeto, voc pode
comear com o tutorial, ou mergulhar na documentao.

Convenes Sobre Configurao


O CakePHP prov uma estrutura organizacional bsica que cobre nomenclaturas de classes, nomenclaturas
de arquivos, nomenclaturas de banco de dados, e outras convenes. Apesar das convenes levarem algum
tempo para serem assimiladas, ao segu-las o CakePHP evita configurao desnecessrio e cria uma estrutura
de aplicao uniforme que faz trabalhar com vrios projetos uma tarefa suave. O captulo de convenes
cobre as variadas convenes que o CakePHP utiliza.

A camada Model
A camada Model representa a parte da sua aplicao que implementa a lgica de negcio. Ela responsvel por recuperar dados e convert-los nos conceitos significativos primrios na sua aplicao. Isto inclui
processar, validar, associar ou qualquer outra tarefa relacionada manipulao de dados.
No caso de uma rede social, a camada Model deveria tomar cuidado de tarefas como salvar os dados do
usurio, salvar as associaes entre amigos, salvar e recuperar fotos de usurios, localizar sugestes para
novos amigos, etc. Os objetos de modelo podem ser pensados como Friend, User, Comment, ou
Photo. Se ns quisssemos carregar alguns dados da nossa tabela users poderiamos fazer:
use Cake\ORM\TableRegistry;
$users = TableRegistry::get('Users');
$query = $users->find();

CakePHP Cookbook Documentation, Verso 3.x

foreach ($query as $row) {


echo $row->username;
}

Voc pode notar que no precisamos escrever nenhum cdigo antes de podermos comear a trabalhar com
nossos dados. Por usar convenes, o CakePHP ir utilizar classes padro para tabelas e entidades ainda no
definidas.
Se ns quisssemos criar um usurio e salv-lo (com validao) fariamos algo assim:
use Cake\ORM\TableRegistry;
$users = TableRegistry::get('Users');
$user = $users->newEntity(['email' => 'mark@example.com']);
$users->save($user);

A camada View
A View renderiza uma apresentao de dados modelados. Estando separada dos objetos da Model, responsvel por utilizar a informao que tem disponvel para produzir qualquer interface de apresentao que a
sua aplicao possa precisar.
Por exemplo, a view pode usar dados da model para renderizar uma pgina HTML que os conhtenha, ou um
resultado formatado como XML:
// No arquivo view, ns renderizaremos um 'elemento' para cada usurio.
<?php foreach ($users as $user): ?>
<div class="user">
<?= $this->element('user', ['user' => $user]) ?>
</div>
<?php endforeach; ?>

A camada View prov alguma variedade de extenses como Elements e View Cells (Clulas de Visualizao)
para permitir que voc reutilize sua lgica de apresentao.
A camada View no est limitada somente a HTML ou apresentao textual dos dados. Ela pode ser usada
para entregar formatos de dado comuns como JSON, XML, e atravs de uma arquitetura encaixvel qualquer
outro formato que voc venha precisar.

A camada Controller
A camada Controller manipula requisies dos usurios. responsvel por renderizar uma resposta com o
auxlio de ambas as camadas, Model e View respectivamente.
Um controller pode ser visto como um gerente que certifica-se que todos os recursos necessrios para completar uma tarefa sejam delegados aos trabalhadores corretos. Ele aguarda por peties dos clientes, checa
suas validades de acordo com autenticao ou regras de autorizao, delega requisies ou processamento
de dados da camada Model, selecciona o tipo de dados de apresentao que os clientes esto aceitando, e

Captulo 1. CakePHP num piscar de olhos

CakePHP Cookbook Documentation, Verso 3.x

finalmente delega o processo de renderizao para a camada View. Um exemplo de controller para registro
de usurio seria:
public function add()
{
$user = $this->Users->newEntity();
if ($this->request->is('post')) {
$user = $this->Users->patchEntity($user, $this->request->data);
if ($this->Users->save($user, ['validate' => 'registration'])) {
$this->Flash->success(__('Voc est registrado.'));
} else {
$this->Flash->error(__('Houve algum problema.'));
}
}
$this->set('user', $user);
}

Voc pode perceber que ns nunca renderizamos uma view explicitamente. As convenes do CakePHP
tomaro cuidado de selecionar a view correta e renderiz-la como os dados definidos com set().

Ciclo de Requisies do CakePHP


Agora que voc familiar com as diferentes camadas no CakePHP, vamos revisar como um cclo de requisio funciona no CakePHP:

Ciclo de Requisies do CakePHP

CakePHP Cookbook Documentation, Verso 3.x

O cclo de requisio tpico do CakePHP comea com um usurio solicitando uma pgina ou recurso na sua
aplicao. Em alto nvel cada requisio vai atravs dos seguintes passos:
1. A requisio primeiramente processada pela suas rotas.
2. Depois da requisio ter sido roteada, o despachante ir selecionar o objeto de controller correto para
manipul-la.
3. A action do controller chamada e o controller interage com os models e components requisitados.
4. O controller delega a criao de resposta view para gerar os dados de sada resultantes dos dados do
model.

Apenas o Comeo
Esperamos que essa rpida viso geral tenha despertado seu interesse. Alguns outros grandes recursos no
CakePHP so:
Framework de cache que integra com Memcached, Redis e outros backends.
Poderosas ferramentas de gerao de cdigo para voc sair em disparada.
Framework de teste integrado para voc assegurar-se que seu cdigo funciona perfeitamente.
Os prximos passos bvios so baixar o CakePHP, ler o tutorial e construir algo fantstico.

Leitura adicional
Onde Conseguir Ajuda
O website oficial do CakePHP
http://www.cakephp.org
O website oficial do CakePHP sempre um timo lugar para visitar. Ele prov links para ferramentas
comunmente utilizadas por desenvolvedores, screencasts, oportunidades de doao e downloads.
O Cookbook
http://book.cakephp.org
Esse manual deveria ser o primeiro lugar para onde voc iria afim de conseguir respostas. Assim como
muitos outros projetos de cdigo aberto, ns conseguimos novos colaboradores regularmente. Tente o seu
melhor para responder suas questes por si s. Respostas vo vir lentamente, e provavelmente continuaro
longas. Voc pode suavizar nossa carga de suporte. Tanto o manual quanto a API possuem um componente
online.

Captulo 1. CakePHP num piscar de olhos

CakePHP Cookbook Documentation, Verso 3.x

A Bakery
http://bakery.cakephp.org
A padaria do CakePHP um local para todas as coisas relacionadas ao CakePHP. Visite-a para tutoriais, estudos de caso e exemplos de cdigo. Uma vez que voc tenha se familiarizado com o CakePHP,
autentique-se e compartilhe seu conhecimento com a comunidade, ganhe instantaneamente fama e fortuna.
A API
http://api.cakephp.org/
Diretamente ao ponto, dos desenvolvedores do ncleo do CakePHP, a API (Application Programming Interface) do CakePHP a mais compreensiva documentao sobre os detalhes tcnicos e minuciosos sobre do
funcionamento interno do framework.
Os Testes de Caso
Se voc sente que a informao provida pela API no suficiente, verifique os cdigos de testes de caso do
CakePHP. Eles podem servir como exemplos prticos para funes e e utilizao de dados referentes a uma
classe.:
tests/TestCase/

O canal de IRC
Canal de IRC na irc.freenode.net:
#cakephp Discusso geral
#cakephp-docs Documentao
#cakephp-bakery Bakery
#cakephp-fr Canal francs.
Se voc est travado, nos faa uma visita no canal de IRC do CakePHP. Algum do time de desenvolvimento1
normalmente est conectado, especiamente nos horrios diurnos da Amrica do Sul e Amrica do Norte.
Ns apreciaramos ouv-lo se voc precisar de ajuda, se quiser encontrar usurios da sua rea ou ainda se
quiser doar seu novo carro esporte.
Grupo oficial de discusso do CakePHP
Grupo de discusso do Google2
1
2

https://github.com/cakephp?tab=members
http://groups.google.com/group/cake-php

Leitura adicional

CakePHP Cookbook Documentation, Verso 3.x

O CakePHP tambm possui seu grupo de discusso oficial no Google Grupos. Existem milhares de pessoas
discutindo projetos CakePHP, ajudando uns aos outros, resolvendo problemas, construindo projetos e compartilhando idias. Pode ser uma grande fonte para encontrar respostas arquivadas, perguntas frequentes e
conseguir respostas para problemas imediatos. Junte-se a outros usurios do CakePHP e comece a conversar.
Stackoverflow
http://stackoverflow.com/3
Marque suas questes com a tag cakephp e especifique a verso que voc est utilizando para permitir que
usurios do stackoverflow achem suas questes.
Onde conseguir ajuda em sua lngua
Francs

Comunidade CakePHP francesa4


Portugus brasileiro

Comunidade CakePHP brasileira5

Convenes do CakePHP
Ns somos grandes fs de conveno sobre configurao. Apesar de levar um pouco de tempo para aprender
as convenes do CakePHP, voc economiza tempo a longo prazo. Ao seguir as convenes, voc ganha
funcionalidades instantaneamente e liberta-se do pesadelo de manuteno e rastreamento de arquivos de
configurao. Convenes tambm prezam por uma experincia de desenvolvimento uniforme, permitindo
que outros desenvolvedores ajudem mais facilmente.
Convenes para Controllers
Os nomes das classes de Controllers so pluralizados, CamelCased, e terminam em Controller.
PeopleController e LatestArticlesController so exemplos de nomes convencionais para
controllers.
Mtodos pblicos nos Controllers so frequentemente referenciados como actions acessveis atravs
de um navegador web. Por exemplo, o /articles/view mapeia para o mtodo view() do
ArticlesController sem nenhum esforo. Mtodos privados ou protegidos no podem ser acessados
pelo roteamento.
3

http://stackoverflow.com/questions/tagged/cakephp/
http://cakephp-fr.org
5
http://cakephp-br.org
4

Captulo 1. CakePHP num piscar de olhos

CakePHP Cookbook Documentation, Verso 3.x

Consideraes de URL para nomes de Controller

Como voc acabou de ver, controllers singulares mapeiam facilmente um caminho simples, todo em minsculo. Por exemplo, ApplesController (o qual deveria ser definido no arquivo de nome ApplesController.php) acessado por http://example.com/apples.
Controllers com mltiplas palavras podem estar em qualquer forma flexionada igual ao nome do controller,
ento:
/redApples
/RedApples
/Red_apples
/red_apples
Todos resolvero para o index do controller RedApples. Porm, a forma correta que suas URLs sejam
minsculas e separadas por sublinhado, portanto /red_apples/go_pick a forma correta de acessar a action
RedApplesController::go_pick.
When you create links using this->Html->link(), you can use the following conventions for the url
array:
$this->Html->link('link-title', [
'prefix' => 'MyPrefix' // CamelCased
'plugin' => 'MyPlugin', // CamelCased
'controller' => 'ControllerName', // CamelCased
'action' => 'actionName' // camelBacked
]

Para mais informaes sobre o manuseio de URLs e parmetros do CakePHP, veja Connecting Routes.
Convenes para nomes de Classes e seus nomes de arquivos
No geral, nomes de arquivos correspondem aos nomes das classes, e seguem os padres PSR-0 ou PSR-4
para auto-carregamento. A seguir seguem exemplos de nomes de classes e de seus arquivos:
A classe de Controller KissesAndHugsController deveria ser encontrada em um arquivo nomeado
KissesAndHugsController.php
A classe de Component MyHandyComponent deveria ser encontrada em um arquivo nomeado MyHandyComponent.php
A classe de Table OptionValuesTable deveria ser encontrada em um arquivo nomeado OptionValuesTable.php.
A classe de Entity OptionValue deveria ser encontrada em um arquivo nomeado OptionValue.php.
A classe de Behavior EspeciallyFunkableBehavior deveria ser encontrada em um arquivo nomeado
EspeciallyFunkableBehavior.php
A classe de View SuperSimpleView deveria ser encontrada em um arquivo nomeado SuperSimpleView.php

Leitura adicional

CakePHP Cookbook Documentation, Verso 3.x

A classe de Helper BestEverHelper deveria ser encontrada em um arquivo nomeado BestEverHelper.php


Cada arquivo deveria estar localizado no diretrio/namespace apropriado de sua aplicao.
Convenes para Models e Databases
Os nomes de classe de Tables so pluralizadas e CamelCased. People, BigPeople, and ReallyBigPeople so
todos exemplos convencionais de models.
Os nomes de Tables correspondentes aos models do CakePHP so pluralizadas e separadas por sublinhado. As tables sublinhadas para os models mencionados acima seriam people, big_people, e
really_big_people, respectively.
Voc pode utilizar a biblioteca utility Cake\Utility\Inflector para checar o singular/plural de
palavras. Veja o Inflector para mais informaes. Recomenda-se que as tables sejam criadas e mantidas
na lngua inglesa.
Campos com duas ou mais palavras so separados por sublinhado: first_name.
Chaves estrangeiras nos relacionamentos hasMany, belongsTo ou hasOne so reconhecidas por padro como
o nome (singular) da table relacionada seguida por _id. Ento se Bakers hasMany Cakes, a table cakes
ir referenciar-se para a table bakers atravs da chave estrangeira baker_id. Para uma tabela como category_types a qual o nome contm mais palavras, a chave estrangeira seria a category_type_id.
tables de unio, usadas no relacionamento BelongsToMany entre models, devem ser nomeadas depois das
tables que ela est unindo, ordenadas em ordem alfabtica (apples_zebras ao invs de zebras_apples).
Convenes para Views
Arquivos de template views so nomeadas seguindo as funes que a exibem do controller, separadas por sublinhado.
A funo getReady() da classe PeopleController
buscar por um template view em src/Template/People/get_ready.ctp.
O padro
src/Template/Controller/underscored_function_name.ctp.
Por nomear as partes de sua aplicao utilizando as convenes do CakePHP, voc ganha funcionalidades
sem luta e sem amarras de configurao. Aqui est um exemplo final que enlaa as convenes juntas:
Table: people
Classe Table: PeopleTable, encontrada em src/Model/Table/PeopleTable.php
Classe Entity: Person, encontrada em src/Model/Entity/Person.php
Classe Controller: PeopleController, encontrada em src/Controller/PeopleController.php
View template, encontrado em src/Template/People/index.ctp
Utilizando estas convenes, o CakePHP sabe que uma requisio para http://example.com/people/ mapeia
para uma chamada da funo index() do PeopleController, onde o model Person automaticamente
disponbilizado (e automaticamente amarrado table people no banco de dados), e ento renderiza-se um
arquivo view template. Nenhuma destes relacionamentos foi configurado de qualquer forma se no por criar
classes e arquivos que voc precisaria criar de qualquer forma.
8

Captulo 1. CakePHP num piscar de olhos

CakePHP Cookbook Documentation, Verso 3.x

Agora que voc foi introduzido aos fundamentos do CakePHP, voc pode tentar seguir atravs do Tutorial Criando um Blog - Parte 1 para ver como as coisas se encaixam juntas.

Estrutura de pastas do CakePHP


Depois de voc ter baixado e extrado o CakePHP, a esto os arquivos e pastas que voc deve ver:
bin
config
logs
plugins
src
tests
tmp
vendor
webroot
.htaccess
composer.json
index.php
README.md
Voc notar alguns diretrios principais:
The bin folder holds the Cake console executables.
O diretrio config contem os (poucos) Configurao arquivos de configurao que o CakePHP utiliza. Detalhes de conexo com banco de dados, inicializao, arquivos de configurao do ncleo da
aplicao, e relacionados devem ser postos aqui.
O diretrio logs ser normalmente onde seus arquivos de log ficaro, dependendo das suas configuraes.
O diretrio plugins ser onde Plugins que sua aplicao utiliza sero armazenados.
O diretrio src ser onde voc far sua mgica: onde os arquivos da sua aplicao sero colocados.
O diretrio tests ser onde voc colocar os testes de caso para sua aplicao.
O diretrio tmp ser onde o CakePHP armazenar dados temporrios. O modo como os dados sero
armazenados depende da configurao do CakePHP, mas esse diretrio comunmente usado para
armazenar descries de modelos e algumas vezes informao de sesso.
O diretrio vendor ser onde o CakePHP e outras dependncias da aplicao sero instalados. Faa
uma nota pessoal para no editar arquivos deste diretrio. Ns no podemos ajudar se voc tiv-lo
feito.

Leitura adicional

CakePHP Cookbook Documentation, Verso 3.x

O diretrio webroot ser a raz pblica de documentos da sua aplicao. Ele contem todos os arquivos
que voc gostaria que fossem pblicos.
Certifique-se que os diretrios tmp e logs existem e so passveis de escrita, seno a performance de
sua aplicao ser severamente impactada. Em modo de debug, o CakePHP ir alert-lo se este for o
caso.
O diretrio src
O diretrio src do CakePHP onde voc far a maior parte do desenvolvimento de sua aplicao. Vamos
ver mais de perto a estrutura de pastas dentro de src.
Console Contm os comandos e tarefas de console para sua aplicao. Para mais informaes veja Console
e Shells.
Controller Contm os controllers de sua aplicao e seus componentes.
Locale Armazena arquivos textuais para internacionalizao.
Model Contm as tables, entities e behaviors de sua aplicao.
View Classes de apresentao so alocadas aqui: cells, helpers, e arquivos view.
Template Arquivos de apresentao so alocados aqui: elements, pginas de erro, layouts, e templates
view.

10

Captulo 1. CakePHP num piscar de olhos

CAPTULO 2

Guia de Incio Rpido

A melhor forma de viver experincias e aprender sobre CakePHP sentar e construir algo. Para comear
ns iremos construir uma aplicao simples de blog.

Tutorial - Criando um Bookmarker - Parte 1


Esse tutorial vai guiar voc atravs da criao de uma simples aplicao de marcao (bookmarker). Para
comear, ns vamos instalar o CakePHP, criar nosso banco de dados, e usar as ferramentas que o CakePHP
fornece para obter nossa aplicao de p rpido.
Aqui est o que voc vai precisar:
1. Um servidor de banco de dados. Ns vamos usar o servidor MySQL neste tutorial. Voc precisa
saber o suficiente sobre SQL para criar um banco de dados: O CakePHP vai tomar as rdeas a partir
da. Por ns estarmos usando o MySQL, tambm certifique-se que voc tem a extenso pdo_mysql
habilitada no PHP.
2. Conhecimento bsico sobre PHP.
Vamos comear!

Instalao do CakePHP
A maneira mais fcil de instalar o CakePHP usando Composer, um gerenciador de dependncias para o
PHP. uma forma simples de instalar o CakePHP a partir de seu terminal ou prompt de comando. Primeiro,
voc precisa baixar e instalar o Composer. Se voc tiver instalada a extenso cURL do PHP, execute o
seguinte comando:
curl -s https://getcomposer.org/installer | php

Ao invs disso, voc tambm pode baixar o arquivo composer.phar do site1 oficial.
1

https://getcomposer.org/download/

11

CakePHP Cookbook Documentation, Verso 3.x

Em seguida, basta digitar a seguinte linha no seu terminal a partir do diretrio onde se localiza o arquivo
composer.phar para instalar o esqueleto de aplicaes do CakePHP no diretrio bookmarker.
php composer.phar create-project --prefer-dist cakephp/app bookmarker

A vantagem de usar Composer que ele ir completar automaticamente um conjunto importante de tarefas,
como configurar as permisses de arquivo e criar a sua config/app.php.
H outras maneiras de instalar o CakePHP. Se voc no puder ou no quiser usar Composer, veja a seo
Instalao.
Independentemente de como voc baixou o CakePHP, uma vez que sua instalao for concluda, a estrutura
dos diretrios deve ficar parecida com o seguinte:
/bookmarker
/bin
/config
/logs
/plugins
/src
/tests
/tmp
/vendor
/webroot
.editorconfig
.gitignore
.htaccess
.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md

Agora pode ser um bom momento para aprender sobre como a estrutura de diretrios do CakePHP funciona:
Confira a seo Estrutura de pastas do CakePHP.

Verificando nossa instalao


Podemos checar rapidamente que a nossa instalao est correta, verificando a pgina inicial padro. Antes
que voc possa fazer isso, voc vai precisar iniciar o servidor de desenvolvimento:
bin/cake server

Isto ir iniciar o servidor embutido do PHP na porta 8765. Abra http://localhost:8765 em seu
navegador para ver a pgina de boas-vindas. Todas as verificaes devem estar checadas corretamente, a
no ser a conexo com banco de dados do CakePHP. Se no, voc pode precisar instalar extenses do PHP
adicionais, ou definir permisses de diretrio.

Criando o banco de dados


Em seguida, vamos criar o banco de dados para a nossa aplicao. Se voc ainda no tiver feito isso,
crie um banco de dados vazio para uso nesse tutorial, com um nome de sua escolha, por exemplo,
12

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

cake_bookmarks. Voc pode executar o seguinte SQL para criar as tabelas necessrias:
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) NOT NULL,
password VARCHAR(255) NOT NULL,
created DATETIME,
modified DATETIME
);
CREATE TABLE bookmarks (
id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
title VARCHAR(50),
description TEXT,
url TEXT,
created DATETIME,
modified DATETIME,
FOREIGN KEY user_key (user_id) REFERENCES users(id)
);
CREATE TABLE tags (
id INT AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(255),
created DATETIME,
modified DATETIME,
UNIQUE KEY (title)
);
CREATE TABLE bookmarks_tags (
bookmark_id INT NOT NULL,
tag_id INT NOT NULL,
PRIMARY KEY (bookmark_id, tag_id),
INDEX tag_idx (tag_id, bookmark_id),
FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id)
);

Voc deve ter notado que a tabela bookmarks_tags utilizada uma chave primria composta. O CakePHP
suporta chaves primrias compostas quase todos os lugares, tornando mais fcil construir aplicaes multiarrendados.
Os nomes de tabelas e colunas que usamos no foram arbitrrias. Usando convenes de nomenclatura
do CakePHP, podemos alavancar o desenvolvimento e evitar ter de configurar o framework. O CakePHP
flexvel o suficiente para acomodar at mesmo esquemas de banco de dados legados inconsistentes, mas
aderir s convenes vai lhe poupar tempo.

Configurando o banco de dados


Em seguida, vamos dizer ao CakePHP onde o nosso banco de dados est como se conectar a ele. Para
muitos, esta ser a primeira e ltima vez que voc vai precisar configurar qualquer coisa.
A configurao bem simples: basta alterar os valores do array Datasources.default no arquivo
Tutorial - Criando um Bookmarker - Parte 1

13

CakePHP Cookbook Documentation, Verso 3.x

config/app.php pelos que se aplicam sua configurao. A amostra completa da gama de configuraes
pode ser algo como o seguinte:
return [
// Mais configurao acima.
'Datasources' => [
'default' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'persistent' => false,
'host' => 'localhost',
'username' => 'cakephp',
'password' => 'AngelF00dC4k3~',
'database' => 'cake_bookmarks',
'encoding' => 'utf8',
'timezone' => 'UTC',
'cacheMetadata' => true,
],
],
// Mais configurao abaixo.
];

Depois de salvar o seu arquivo config/app.php, voc deve notar que a mensagem CakePHP is able to
connect to the database tem uma marca de verificao.
Nota:
Uma cpia do arquivo de configurao padro do CakePHP encontrado em config/app.default.php.

Gerando o cdigo base


Devido a nosso banco de dados seguir as convenes do CakePHP, podemos usar o bake console para gerar
rapidamente uma aplicao bsica . Em sua linha de comando execute:
bin/cake bake all users
bin/cake bake all bookmarks
bin/cake bake all tags

Isso ir gerar os controllers, models, views, seus casos de teste correspondentes, e fixtures
para os nossos users, bookmarks e tags.
Se voc parou seu servidor, reinicie-o e v para
http://localhost:8765/bookmarks.
Voc dever ver uma aplicao que d acesso bsico, mas funcional a tabelas de banco de dados. Adicione
alguns users, bookmarks e tags.

Adicionando criptografia de senha


Quando voc criou seus users, voc deve ter notado que as senhas foram armazenadas como texto simples.
Isso muito ruim do ponto de vista da segurana, por isso vamos consertar isso.

14

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

Este tambm um bom momento para falar sobre a camada de modelo. No CakePHP, separamos os mtodos
que operam em uma coleo de objetos, e um nico objeto em diferentes classes. Mtodos que operam na
recolha de entidades so colocadas na classe Table, enquanto as caractersticas pertencentes a um nico
registro so colocados na classe Entity.
Por exemplo, a criptografia de senha feita no registro individual, por isso vamos implementar esse comportamento no objeto entidade. Dada a circunstncia de ns querermos criptografar a senha cada vez que
definida, vamos usar um mtodo modificador/definidor. O CakePHP vai chamar mtodos de definio
baseados em convenes a qualquer momento que uma propriedade definida em uma de suas entidades.
Vamos adicionar um definidor para a senha. Em src/Model/Entity/User.php adicione o seguinte:
namespace App\Model\Entity;
use Cake\ORM\Entity;
use Cake\Auth\DefaultPasswordHasher;
class User extends Entity
{
// Code from bake.
protected function _setPassword($value)
{
$hasher = new DefaultPasswordHasher();
return $hasher->hash($value);
}
}

Agora atualize um dos usurios que voc criou anteriormente, se voc alterar sua senha, voc deve ver um
senha criptografada ao invs do valor original nas pginas de lista ou visualizao. O CakePHP criptografa
senhas com bcrypt2 por padro. Voc tambm pode usar sha1 ou md5 caso venha a trabalhar com um banco
de dados existente.

Recuperando bookmarks com uma tag especfica


Agora que estamos armazenando senhas com segurana, podemos construir algumas caractersticas mais
interessantes em nossa aplicao. Uma vez que voc acumulou uma coleo de bookmarks, til ser capaz
de pesquisar atravs deles por tag. Em seguida, vamos implementar uma rota, a ao do controller, e um
mtodo localizador para pesquisar atravs de bookmarks por tag.

Idealmente, ns teramos uma URL que se parece com http://localhost:8765/bookmarks/tagged/funny/ca


Isso deveria nos permitir a encontrar todos os bookmarks que tm as tags funny, cat e gifs. Antes de
podermos implementar isso, vamos adicionar uma nova rota. Em config/routes.php, adicione o seguinte na
parte superior do arquivo:
Router::scope(
'/bookmarks',
['controller' => 'Bookmarks'],
function ($routes) {
$routes->connect('/tagged/*', ['action' => 'tags']);
2

http://codahale.com/how-to-safely-store-a-password/

Tutorial - Criando um Bookmarker - Parte 1

15

CakePHP Cookbook Documentation, Verso 3.x

}
);

O acima define uma nova rota que liga o caminho /bookmarks/tagged/*,


a BookmarksController::tags().
Ao definir rotas, voc pode isolar como
suas URLs parecero,
de como eles so implementadas.
Se fssemos visitar
http://localhost:8765/bookmarks/tagged,
deveriamos
ver
uma
pgina
de
erro informativa do CakePHP. Vamos implementar esse mtodo ausente agora.
Em
src/Controller/BookmarksController.php adicione o seguinte:
public function tags()
{
$tags = $this->request->params['pass'];
$bookmarks = $this->Bookmarks->find('tagged', [
'tags' => $tags
]);
$this->set(compact('bookmarks', 'tags'));
}

Criando o mtodo localizador


No CakePHP ns gostamos de manter as nossas aes do controller enxutas, e colocar a maior parte da
lgica de nossa aplicao nos modelos. Se voc fosse visitar a URL /bookmarks/tagged agora, voc
veria um erro sobre o mtodo findTagged no estar implementado ainda, ento vamos fazer isso. Em
src/Model/Table/BookmarksTable.php adicione o seguinte:
public function findTagged(Query $query, array $options)
{
$fields = [
'Bookmarks.id',
'Bookmarks.title',
'Bookmarks.url',
];
return $this->find()
->distinct($fields)
->matching('Tags', function ($q) use ($options) {
return $q->where(['Tags.title IN' => $options['tags']]);
});
}

Ns implementamos um mtodo localizador customizado. Este um conceito muito poderoso no


CakePHP que lhe permite construir consultas reutilizveis. Em nossa pesquisa, ns alavancamos o mtodo
matching() que nos habilita encontrar bookmarks que tm uma tag correspondente.

Criando a view
Agora, se voc visitar a URL /bookmarks/tagged, o CakePHP ir mostrar um erro e deix-lo saber
que voc ainda no fez um arquivo view. Em seguida, vamos construir o arquivo view para a nossa ao
tags. Em src/Template/Bookmarks/tags.ctp coloque o seguinte contedo:

16

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

<h1>
Bookmarks tagged with
<?= $this->Text->toList($tags) ?>
</h1>
<section>
<?php foreach ($bookmarks as $bookmark): ?>
<article>
<h4><?= $this->Html->link($bookmark->title, $bookmark->url) ?></h4>
<small><?= h($bookmark->url) ?></small>
<?= $this->Text->autoParagraph($bookmark->description) ?>
</article>
<?php endforeach; ?>
</section>

O CakePHP espera que os nossos templates sigam a conveno de nomenclatura onde o nome do template
a verso minscula e grifada do nome da ao do controller.
Voc pode perceber que fomos capazes de utilizar as variveis $tags e bookmarks em nossa view.
Quando usamos o mtodo set() em nosso controller, automaticamente definimos variveis especficas
que devem ser enviadas para a view. A view vai tornar todas as variveis passadas disponveis nos templates
como variveis locais.
Em nossa view, usamos alguns dos helpers nativos do CakePHP. Helpers so usados para criar lgica reutilizvel para a formatao de dados, a criao de HTML ou outra sada da view.
Agora voc deve ser capaz de visitar a URL /bookmarks/tagged/funny e ver todas os bookmarks
com a tag funny.
At agora, ns criamos uma aplicao bsica para gerenciar bookmarks, tags e users. No entanto, todos
podem ver as tags de toda a gente. No prximo captulo, vamos implementar a autenticao e restringir os
bookmarks visveis para somente aqueles que pertencem ao usurio atual.
Agora v a Tutorial - Criando um Bookmarker - Parte 2 para continuar a construir sua aplicao ou
mergulhe na documentao para saber mais sobre o que CakePHP pode fazer por voc.

Tutorial - Criando um Bookmarker - Parte 2


Depois de terminar a primeira parte deste tutorial, voc deve ter uma aplicao muito bsica. Neste captulo
iremos adicionar autenticao e restringir as bookmarks para que cada usurio possa ver/modificar somente
aquelas que possuam.

Adicionando login
No CakePHP, a autenticao feita por Components (Componentes). Os Components podem ser considerados como formas de criar pedaos reutilizveis de cdigo relacionado a controllers com uma caracterstica
especfica ou conceito. Os components tambm podem ligar-se ao evento do ciclo de vida do controller e
interagir com a sua aplicao. Para comear, vamos adicionar o AuthComponent a nossa aplicao. Ns
vamos querer muito que cada mtodo exija autenticao, por isso vamos acrescentar o AuthComponent em
nosso AppController:
Tutorial - Criando um Bookmarker - Parte 2

17

CakePHP Cookbook Documentation, Verso 3.x

// Em src/Controller/AppController.php
namespace App\Controller;
use Cake\Controller\Controller;
class AppController extends Controller
{
public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'authenticate' => [
'Form' => [
'fields' => [
'username' => 'email',
'password' => 'password'
]
]
],
'loginAction' => [
'controller' => 'Users',
'action' => 'login'
]
]);
// Permite a ao display, assim nosso pages controller
// continua a funcionar.
$this->Auth->allow(['display']);
}
}

Acabamos de dizer ao CakePHP que queremos carregar os components Flash e Auth. Alm disso, temos
a configurao personalizada do AuthComponent, assim a nossa tabela users pode usar email como username. Agora, se voc for a qualquer URL, voc vai ser chutado para /users/login, que ir mostrar uma
pgina de erro j que no escrevemos o cdigo ainda. Ento, vamos criar a ao de login:
// Em src/Controller/UsersController.php
public function login()
{
if ($this->request->is('post')) {
$user = $this->Auth->identify();
if ($user) {
$this->Auth->setUser($user);
return $this->redirect($this->Auth->redirectUrl());
}
$this->Flash->error('Your username or password is incorrect.');
}
}

E em src/Template/Users/login.ctp adicione o seguinte:

18

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

<h1>Login</h1>
<?= $this->Form->create() ?>
<?= $this->Form->input('email') ?>
<?= $this->Form->input('password') ?>
<?= $this->Form->button('Login') ?>
<?= $this->Form->end() ?>

Agora que temos um simples formulrio de login, devemos ser capazes de efetuar login com um dos users
que tenham senha criptografada.
Nota: Se nenhum de seus users tem senha criptografada, comente a linha loadComponent(Auth).
Ento v e edite o user, salvando uma nova senha para ele.
Agora voc deve ser capaz de entrar. Se no, certifique-se que voc est usando um user que tenha senha
criptografada.

Adicionando logout
Agora que as pessoas podem efetuar o login, voc provavelmente vai querer fornecer uma maneira de encerrar a sesso tambm. Mais uma vez, no UsersController, adicione o seguinte cdigo:
public function logout()
{
$this->Flash->success('You are now logged out.');
return $this->redirect($this->Auth->logout());
}

Agora voc pode visitar /users/logout para sair e ser enviado pgina de login.

Ativando inscries
Se voc no estiver logado e tentar visitar / usurios / adicionar voc vai ser expulso para a pgina de login.
Devemos corrigir isso se quisermos que as pessoas se inscrevam em nossa aplicao. No UsersController
adicione o seguinte:
public function beforeFilter(\Cake\Event\Event $event)
{
$this->Auth->allow(['add']);
}

O texto acima diz ao AuthComponent que a ao add no requer autenticao ou autorizao. Voc pode
querer dedicar algum tempo para limpar a /users/add e remover os links enganosos, ou continuar para a
prxima seo. Ns no estaremos construindo a edio do usurio, visualizao ou listagem neste tutorial,
ento eles no vo funcionar, j que o AuthComponent vai negar-lhe acesso a essas aes do controller.

Tutorial - Criando um Bookmarker - Parte 2

19

CakePHP Cookbook Documentation, Verso 3.x

Restringindo acesso
Agora que os usurios podem conectar-se, ns vamos querer limitar os bookmarks que podem ver para
aqueles que fizeram. Ns vamos fazer isso usando um adaptador de autorizao. Sendo os nossos requisitos bastante simples, podemos escrever um cdigo em nossa BookmarksController. Mas antes
de fazer isso, vamos querer dizer ao AuthComponent como nossa aplicao vai autorizar aes. Em seu
AppController adicione o seguinte:
public function isAuthorized($user)
{
return false;
}

Alm disso, adicione o seguinte configurao para Auth em seu AppController:


'authorize' => 'Controller',

Seu mtodo initialize agora deve parecer com:


public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'authorize'=> 'Controller',//added this line
'authenticate' => [
'Form' => [
'fields' => [
'username' => 'email',
'password' => 'password'
]
]
],
'loginAction' => [
'controller' => 'Users',
'action' => 'login'
],
'unauthorizedRedirect' => $this->referer()
]);
// Permite a ao display, assim nosso pages controller
// continua a funcionar.
$this->Auth->allow(['display']);
}

Vamos usar como padro, negao do acesso, e de forma incremental conceder acesso onde faa sentido.
Primeiro, vamos adicionar a lgica de autorizao para os bookmarks. Em seu BookmarksController
adicione o seguinte:
public function isAuthorized($user)
{
$action = $this->request->params['action'];
// As aes add e index so permitidas sempre.
if (in_array($action, ['index', 'add', 'tags'])) {

20

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

return true;
}
// Todas as outras aes requerem um id.
if (empty($this->request->params['pass'][0])) {
return false;
}
// Checa se o bookmark pertence ao user atual.
$id = $this->request->params['pass'][0];
$bookmark = $this->Bookmarks->get($id);
if ($bookmark->user_id == $user['id']) {
return true;
}
return parent::isAuthorized($user);
}

Agora, se voc tentar visualizar, editar ou excluir um bookmark que no pertena a voc, voc deve ser
redirecionado para a pgina de onde veio. No entanto, no h nenhuma mensagem de erro sendo exibida,
ento vamos corrigir isso a seguir:
// In src/Template/Layout/default.ctp
// Under the existing flash message.
<?= $this->Flash->render('auth') ?>

Agora voc deve ver as mensagens de erro de autorizao.

Corrigindo a view de listagem e formulrios


Enquanto view e delete esto trabalhando, edit, add e index tem alguns problemas:
1. Ao adicionar um bookmark, voc pode escolher o user.
2. Ao editar um bookmark, voc pode escolher o user.
3. A pgina de listagem mostra os bookmarks de outros users.
Vamos enfrentar o formulrio de adio em primeiro lugar. Para comear remova o input(user_id)
a partir de src/Template/Bookmarks/add.ctp. Com isso removido, ns tambm vamos atualizar o mtodo
add:
public function add()
{
$bookmark = $this->Bookmarks->newEntity();
if ($this->request->is('post')) {
$bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->data);
$bookmark->user_id = $this->Auth->user('id');
if ($this->Bookmarks->save($bookmark)) {
$this->Flash->success('The bookmark has been saved.');
return $this->redirect(['action' => 'index']);
}
$this->Flash->error('The bookmark could not be saved. Please, try again.');
}
$tags = $this->Bookmarks->Tags->find('list');

Tutorial - Criando um Bookmarker - Parte 2

21

CakePHP Cookbook Documentation, Verso 3.x

$this->set(compact('bookmark', 'tags'));
}

Ao definir a propriedade da entidade com os dados da sesso, ns removemos qualquer possibilidade do


user modificar de que outro user um bookmark seja. Ns vamos fazer o mesmo para o formulrio edit e
action edit. Sua ao edit deve ficar assim:
public function edit($id = null)
{
$bookmark = $this->Bookmarks->get($id, [
'contain' => ['Tags']
]);
if ($this->request->is(['patch', 'post', 'put'])) {
$bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->data);
$bookmark->user_id = $this->Auth->user('id');
if ($this->Bookmarks->save($bookmark)) {
$this->Flash->success('The bookmark has been saved.');
return $this->redirect(['action' => 'index']);
}
$this->Flash->error('The bookmark could not be saved. Please, try again.');
}
$tags = $this->Bookmarks->Tags->find('list');
$this->set(compact('bookmark', 'tags'));
}

View de listagem
Agora, ns precisamos apenas exibir bookmarks para o user logado. Ns podemos fazer isso ao atualizar a
chamada para paginate(). Altere sua ao index:
public function index()
{
$this->paginate = [
'conditions' => [
'Bookmarks.user_id' => $this->Auth->user('id'),
]
];
$this->set('bookmarks', $this->paginate($this->Bookmarks));
}

Ns tambm devemos atualizar a action tags() e o mtodo localizador relacionado, mas vamos deixar
isso como um exerccio para que voc conclua por s.

Melhorando a experincia com as tags


Agora, adicionar novas tags um processo difcil, pois o TagsController probe todos os acessos. Em
vez de permitir o acesso, podemos melhorar a interface do usurio para selecionar tags usando um campo
de texto separado por vrgulas. Isso permitir dar uma melhor experincia para os nossos usurios, e usar
mais alguns grandes recursos no ORM.

22

Captulo 2. Guia de Incio Rpido

CakePHP Cookbook Documentation, Verso 3.x

Adicionando um campo computado


Porque ns queremos uma maneira simples de acessar as tags formatados para uma entidade, podemos
adicionar um campo virtual/computado para a entidade. Em src/Model/Entity/Bookmark.php adicione o
seguinte:
use Cake\Collection\Collection;
protected function _getTagString()
{
if (isset($this->_properties['tag_string'])) {
return $this->_properties['tag_string'];
}
if (empty($this->tags)) {
return '';
}
$tags = new Collection($this->tags);
$str = $tags->reduce(function ($string, $tag) {
return $string . $tag->title . ', ';
}, '');
return trim($str, ', ');
}

Isso vai nos deixar acessar a propriedade computada $bookmark->tag_string. Vamos usar essa propriedade em inputs mais tarde. Lembre-se de adicionar a propriedade tag_string a lista _accessible
em sua entidade.
Em src/Model/Entity/Bookmark.php adicione o tag_string ao _accessible desta forma:
protected $_accessible = [
'user_id' => true,
'title' => true,
'description' => true,
'url' => true,
'user' => true,
'tags' => true,
'tag_string' => true,
];

Atualizando as views
Com a entidade atualizado, podemos adicionar uma nova entrada para as nossas tags. Nas views add e edit,
substitua tags._ids pelo seguinte:
<?= $this->Form->input('tag_string', ['type' => 'text']) ?>

Persistindo a string tag


Agora que podemos ver as tags como uma string existente, vamos querer salvar os dados tambm. Por
marcar o tag_string como acessvel, o ORM ir copiar os dados do pedido em nossa entidade. Podemos

Tutorial - Criando um Bookmarker - Parte 2

23

CakePHP Cookbook Documentation, Verso 3.x

usar um mtodo beforeSave para analisar a cadeia tag e encontrar/construir as entidades relacionadas.
Adicione o seguinte em src/Model/Table/BookmarksTable.php:
public function beforeSave($event, $entity, $options)
{
if ($entity->tag_string) {
$entity->tags = $this->_buildTags($entity->tag_string);
}
}
protected function _buildTags($tagString)
{
$new = array_unique(array_map('trim', explode(',', $tagString)));
$out = [];
$query = $this->Tags->find()
->where(['Tags.title IN' => $new]);
// Remove tags existentes da lista de novas tags.
foreach ($query->extract('title') as $existing) {
$index = array_search($existing, $new);
if ($index !== false) {
unset($new[$index]);
}
}
// Adiciona tags existentes.
foreach ($query as $tag) {
$out[] = $tag;
}
// Adiciona novas tags.
foreach ($new as $tag) {
$out[] = $this->Tags->newEntity(['title' => $tag]);
}
return $out;
}

Embora esse cdigo seja um pouco mais complicado do que o que temos feito at agora, ele ajuda a mostrar
o quo poderosa a ORM do CakePHP . Voc pode facilmente manipular resultados da consulta usando os
mtodos de Collections (Colees), e lidar com situaes em que voc est criando entidades sob demanda
com facilidade.

Terminando
Ns expandimos nossa aplicao bookmarker para lidar com situaes de autenticao e controle de autorizao/acesso bsico. Ns tambm adicionamos algumas melhorias agradveis UX, aproveitando os
recursos FormHelper e ORM.
Obrigado por dispor do seu tempo para explorar o CakePHP. Em seguida, voc pode saber mais sobre o
Models (Modelos), ou voc pode ler os /topics.

24

Captulo 2. Guia de Incio Rpido

CAPTULO 3

3.0 - Guia de migrao

Esta pgina resume as alteraes do CakePHP 2.x e ir auxiliar na migrao do seu projeto para a verso 3.0,
e tambm ser uma referncia para atualiz-lo quanto s principais mudanas do branch 2.x. Certifique-se
de ler tambm as outras pginas nesse guia para conhecer todas as novas funcionalidades e mudanas na
API.

Requerimentos
O CakePHP 3.x suporta o PHP 5.4.16 e acima.
O CakePHP 3.x precisa da extenso mbstring.
O CakePHP 3.x precisa da extenso intl.
Aviso: O CakePHP 3.0 no ir funcionar se voc no atender aos requisitos acima.

Ferramenta de atualizao
Enquanto este documento cobre todas as alteraes e melhorias feitas no CakePHP 3.0, ns tambm criamos
uma aplicao de console para ajudar voc a completar mais facilmente algumas das alteraes mecnicas
que consomem tempo. Voc pode pegar a ferramenta de atualizao no github1 .

Layout do diretrio da aplicao


O Layout do diretrio da aplicao mudou e agora segue o PSR-42 . Voc deve usar o projeto do esqueleto
da aplicao3 como um ponto de referncia quando atualizar sua aplicao.
1

https://github.com/cakephp/upgrade
http://www.php-fig.org/psr/psr-4/
3
https://github.com/cakephp/app
2

25

CakePHP Cookbook Documentation, Verso 3.x

O CakePHP deve ser instalado via Composer


Como o CakePHP no pode mais ser instalado facilmente via PEAR, ou em um diretrio compartilhado,
essas opes no so mais suportadas. Ao invs disso, voc deve usar o Composer4 para instalar o CakePHP
em sua aplicao.

Namespaces
Todas as classes do core do CakePHP agora usam namespaces e seguem as especificaes de autoload (autocarregamento) do PSR-4. Por exemplo src/Cache/Cache.php tem o namespace Cake\Cache\Cache.
Constantes globais e mtodos de helpers como __() e debug() no usam namespaces por questes de
convenincia.

Constantes removidas
As seguintes constantes obsoletas foram removidas:
IMAGES
CSS
JS
IMAGES_URL
JS_URL
CSS_URL
DEFAULT_LANGUAGE

Configurao
As configuraes no CakePHP 3.0 esto significativamente diferentes que nas verses anteriores. Voc deve
ler a documentao Configurao para ver como a configurao feita.
Voc no pode mais usar o App::build() para configurar caminhos adicionais de classes. Ao invs
disso, voc deve mapear caminhos adicionais usando o autoloader da sua aplicao. Veja a seo Caminhos
de Classes Adicionais para mais informaes.
Trs novas variveis de configurao fornecem o caminho de configurao para plugins, views
e arquivos de localizao. Voc pode adicionar vrios caminhos em App.paths.templates,
App.paths.plugins, App.paths.locales para configurar mltiplos caminhos para templates,
plugins e arquivos de localizao respectivamente.
A chave de configurao www_root mudou para wwwRoot devido a consistncia. Por favor, ajuste seu arquivo de configurao app.php assim como qualquer uso de Configure::read(App.wwwRoot).
4

26

http://getcomposer.org

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

Novo ORM
O CakePHP 3.0 possui um novo ORM que foi refeito do zero. O novo ORM significativamente diferente
e incompatvel com o anterior. Migrar para o novo ORM necessita de alteraes extensas em qualquer
aplicao que esteja sendo atualizada. Veja a nova documentao Models (Modelos) para informaes de
como usar o novo ORM.

Bsico
O LogError() foi removido, ele no tinha vantagens e era raramente ou mesmo, nunca usado.
As seguintes funes globais foram removidas: config(), cache(), clearCache(),
convertSlashes(), am(), fileExistsInPath(), sortByKey().

Debug
A funo Configure::write(debug, $bool) no suporta mais 0/1/2. Um boleano simples usado para mudar o modo de debug para ligado ou desligado.

Especificaes/Configuraes de objetos
Os objetos usados no CakePHP agora tem um sistema consistente de armazenamento/recuperao
de configurao-de-instncia.
Os cdigos que anteriormente acessavam, por exemplo
$object->settings, devem ser atualizados para usar $object->config() alternativamente.

Cache
Memcache foi removido, use Cake\Cache\Cache\Engine\Memcached alternativamente.
Cache engines so carregados sob demanda no primeiro uso.
Cake\Cache\Cache::engine() foi adicionado.
Cake\Cache\Cache::enabled() foi adicionado.
Cache.disable.

Substituindo a opo de configurao

Cake\Cache\Cache::enable() foi adicionado.


Cake\Cache\Cache::disable() foi adicionado.
Configurao de cache agora imutvel. Se voc precisa alterar a configurao, ser necessrio
desfazer-se da configurao e recri-la. Isso previne problemas de sincronizao com as opes de
configurao.

Novo ORM

27

CakePHP Cookbook Documentation, Verso 3.x

Cache::set() foi removido. recomendado criar mltiplas configuraes de cache para substituir
ajustes de configurao em tempo de execuo anteriormente possveis com Cache::set().
Todas as subclasses CacheEngine agora implementam um mtodo config().
Cake\Cache\Cache::readMany(),
Cake\Cache\Cache::deleteMany(),
Cake\Cache\Cache::writeMany() foram adicionados.

Todos os mtodos Cake\Cache\Cache\CacheEngine agora so responsveis por manipular o prefixo


chave configurado. O Cake\Cache\CacheEngine::write() no mais permite definir a durao na
escrita, a durao captada pela configurao de tempo de execuo do mecanismo de cache. Chamar um
mtodo cache com uma chuva vazia ir lanar uma InvalidArgumentException ao invs de retornar
false.

Core
App
App::pluginPath() foi removido. Use CakePlugin::path() alternativamente.
App::build() foi removido.
App::location() foi removido.
App::paths() foi removido.
App::load() foi removido.
App::objects() foi removido.
App::RESET foi removido.
App::APPEND foi removido.
App::PREPEND foi removido.
App::REGISTER foi removido.

Plugin
O Cake\Core\Plugin::load() no configura a carga automtica a menos que voc defina a
opo autoload como true.
Quanto estiver carregando plugins voc no pode mais fornecer um callable.
Quanto estiver carregando plugins voc no pode mais fornecer um array de arquivos de configurao
para carregar.

Configure
O Cake\Configure\PhpReader foi renomeado para Cake\Core\Configure\EnginePhpConfig

28

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

O Cake\Configure\IniReader foi renomeado para Cake\Core\Configure\EngineIniConfig


O
Cake\Configure\ConfigReaderInterface
Cake\Core\Configure\ConfigEngineInterface

foi

renomeado

para

O Cake\Core\Configure::consume() foi adicionado.


O Cake\Core\Configure::load() agora espera o nome de arquivo sem o sufixo de extenso
como isso pode ser derivado do mecanismo. Ex.: para usar o PhpConfig use app para carregar
app.php.
Definir
uma
varivel
$config
no
arquivo
PHP
config
est
obsoleto.
Cake\Core\Configure\EnginePhpConfig agora espera que o arquivo de configurao
retorne um array.
Um novo mecanismo de configurao Cake\Core\Configure\EngineJsonConfig foi adicionado.

Object
A classe Object foi removida. Ela anteriormente continha um monte de mtodos que eram utilizados em
vrios locais no framework. O mais til destes mtodos foi extraido como um trait. Voc pode usar o
Cake\Log\LogTrait para acessar o mtodo log(). O Cake\Routing\RequestActionTrait
fornece o mtodo requestAction().

Console
O executvel cake foi movido do diretrio app/Console para o diretrio bin dentro do esqueleto da
aplicao. Voc pode agora invocar o console do CakePHP com bin/cake.

TaskCollection Substitudo
Essa classe foi renomeada para Cake\Console\TaskRegistry. Veja a seo em Objetos de Registro para mais informaes sobre funcionalidades fornecidas pela nova classe. Voc pode usar o cake
upgrade rename_collections para ajuda ao atualizar seu cdigo. Tarefas no tem mais acesso a
callbacks, como nunca houve nenhum callback para se usar.

Shell
O Shell::__construct()
Cake\Console\ConsoleIo.

foi

alterado.

Ele

agora

usa

uma

instncia

de

O Shell::param() foi adicionado como um acesso conveniente aos parmetros.


Adicionalmente todos os mtodos shell sero transformados em camel case quando invocados. Por exemplo,
se voc tem um mtodo hello_world() dentro de um shell e chama ele com bin/cake my_shell
hello_world, voc ter que renomear o mtodo para helloWorld. No h necessidade de mudanas
no modo que voc chama os mtodos/comandos.
Console

29

CakePHP Cookbook Documentation, Verso 3.x

ConsoleOptionParser
O ConsoleOptionParser::merge() foi adicionado para mesclar os parsers.

ConsoleInputArgument
O ConsoleInputArgument::isEqualTo() foi adicionado para comparar dois argumentos.

Shell / Tarefa
Os Shells e Tarefas foram movidas de Console/Command e Console/Command/Task para Shell
e Shell/Task, respectivamente.

ApiShell Removido
O ApiShell foi removido pois ele no fornecia nenhum beneficio alm do prprio arquivo fonte e da documentao/API5 online.

SchemaShell Removido
O SchemaShell foi removido como ele nunca foi uma implementao completa de migrao de banco de dados e surgiram ferramentas melhores como o Phinx6 . Ele foi substitudo pelo CakePHP Migrations Plugin7
que funciona como um empacotamento entre o CakePHP e o Phinx8 .

ExtractTask
O bin/cake i18n extract no inclui mais mensagens de validao sem traduo. Se voc
quiser mensagens de validao traduzidas voc deve encapsula-las com chamadas __() como qualquer
outro contedo.

BakeShell / TemplateTask
O Bake no faz mais parte do fonte do ncleo e suplantado pelo CakePHP Bake Plugin9
Os templates do Bake foram movidos para src/Template/Bake.
A sintaxe dos templates do Bake agora usam tags estilo erb (<% %>) para denotar lgica de template,
permitindo cdigo php ser tratado como texto plano.
O comando bake view foi renomeado para bake template.
5

http://api.cakephp.org/
https://phinx.org/
7
https://github.com/cakephp/migrations
8
https://phinx.org/
9
https://github.com/cakephp/bake
6

30

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

Eventos
O mtodo getEventManager(), foi removido de todos os objetos que continham. Um mtodo
eventManager() agora fornecido pelo EventManagerTrait. O EventManagerTrait contm a lgica de instanciao e manuteno de uma referncia para um gerenciador local de eventos.
O subsistema Event teve um monte de funcionalidades opcionais removidas. Quando despachar eventos
voc no poder mais usar as seguintes opes:
passParams Essa opo est agora ativada sempre implicitamente. Voc no pode desliga-la.
break Essa opo foi removida. Voc deve agora parar os eventos.
breakOn Essa opo foi removida. Voc deve agora parar os eventos.

Log
As configuraes do Log agora no imutveis. Se voc precisa alterar a configurao voc deve
primeiro derrubar a configurao e ento recria-la. Isso previne problemas de sincronizao com
opes de configurao.
Os mecanismos de Log agora so carregados tardiamente aps a primeira escrita nos logs.
O Cake\Log\Log::engine() foi adicionado.
Os seguintes mtodos foram removidos de Cake\Log\Log :: defaultLevels(), enabled(),
enable(), disable().
Voc no pode mais criar nveis personalizados usando Log::levels().
Quando configurar os loggers voc deve usar levels ao invs de types.
Voc no pode mais especificar nveis personalizados de log. Voc deve usar o conjunto padro de
nveis de log. Voc deve usar escopos de log para criar arquivos de log personalizados ou manipulaes especficas para diferentes sees de sua aplicao. Usando um nvel de log no padro ir
lanar uma exceo.
O Cake\Log\LogTrait foi adicionado. Voc pode usar este trait em suas classes para adicionar
o mtodo log().
O escopo de log passado para Cake\Log\Log::write() agora encaminhado para o mtodo
write() dos mecanismos de log de maneira a fornecer um melhor contexto para os mecanismos.
Os mecanismos de Log agora so necessrios para implementar Psr\Log\LogInterface
invs do prprio LogInterface do Cake.
Em geral, se voc herdou o
Cake\Log\Engine\BaseEngine voc s precisa renomear o mtodo write() para
log().
O Cake\Log\Engine\FileLog agora grava arquivos em ROOT/logs no lugar de
ROOT/tmp/logs.

Eventos

31

CakePHP Cookbook Documentation, Verso 3.x

Roteamento
Parmetros Nomeados
Os parmetros nomeados foram removidos no 3.0. Os parmetros nomeados foram adicionados no 1.2.0
como uma verso bonita de parmetros de requisio. Enquanto o benefcio visual discutvel, os problemas criados pelos parmetros nomeados no so.
Os parmetros nomeados necessitam manipulao especial no CakePHP assim como em qualquer biblioteca
PHP ou JavaScript que necessite interagir com eles, os parmetros nomeados no so implementados ou
entendidos por qualquer biblioteca exceto o CakePHP. A complexidade adicionada e o cdigo necessrio
para dar suporte aos parmetros nomeados no justificam a sua existncia, e eles foram removidos. No lugar
deles, voc deve agora usar o padro de parmetros de requisio (querystring) ou argumentos passados
configurados nas rotas. Por padro o Router ir tratar qualquer parmetro adicional ao Router::url()
como argumentos de requisio.
Como muitas aplicaes ainda precisaro analisar URLs contendo parmetros nomeados, o
Cake\Routing\Router::parseNamedParams() foi adicionado para permitir compatibilidade
com URLs existentes.

RequestActionTrait
O Cake\Routing\RequestActionTrait::requestAction() teve algumas de suas
opes extras alteradas:
o options[url] agora options[query].
o options[data] agora options[post].
os parmetros nomeados no so mais suportados.

Roteador
Os parmetros nomeados foram removidos, veja acima para mais informaes.
A opo full_base foi substituda com a opo _full.
A opo ext foi substituda com a opo _ext.
As opes _scheme, _port, _host, _base, _full, _ext foram adicionadas.
As URLs em strings no so mais modificados pela adio de plugin/controller/nomes de prefixo.
A manipulao da rota padro de fallback foi removida. Se nenhuma rota combinar com o conjunto de parmetros, o / ser retornado.
As classes de rota so responsveis por toda gerao de URLs incluindo parmetros de requisio
(query string). Isso faz com que as rotas sejam muito mais poderosas e flexveis.
Parmetros
persistentes
foram
removidos.
Eles
foram
substitudos
pelo
Cake\Routing\Router::urlFilter() que permite um jeito mais flexvel para mudar
URLs sendo roteadas reversamente.
32

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

O
Router::parseExtensions()
foi
removido.
Use
o
Cake\Routing\Router::extensions() no lugar.
Esse mtodo deve ser chamado
antes das rotas serem conectadas. Ele no ir modificar rotas existentes.
O
Router::setExtensions()
foi
removido.
Cake\Routing\Router::extensions() no lugar.

Use

O Router::resourceMap() foi removido.


A opo [method] foi renomeada para _method.
A habilidade de combinar cabealhos arbitrrios com parmetros no estilo [] foi removida. Se voc
precisar combinar/analisar em condies arbitrrias considere usar classes personalizadas de roteamento.
O Router::promote() foi removido.
O Router::parse() ir agora lanar uma exceo quando uma URL no puder ser atendida por
nenhuma rota.
O Router::url() agora ir lanar uma exceo quando nenhuma rota combinar com um conjunto
de parmetros.
Os escopos de rotas foram adicionados. Escopos de rotas permitem voc manter seu arquivo de rotas
limpo e dar dicas de rotas em como otimizar anlise e reverso de rotas de URL.

Route
O CakeRoute foi renomeado para Route.
A assinatura de match() mudou para match($url, $context = []).
Cake\Routing\Route::match() para mais informaes sobre a nova assinatura.

Veja

Configurao de Filtros do Despachante Mudaram


Os filtros do despachante no so mais adicionados em sua aplicao usando o Configure.
Voc deve agora anexa-los com Cake\Routing\DispatcherFactory.
Isso significa que sua aplicao usava Dispatcher.filters, voc deve usar agora o mtodo
Cake\Routing\DispatcherFactory::add().
Alm das mudanas de configurao, os filtros do despachante tiveram algumas convenes atualizadas e
novas funcionalidades. Veja a documentao em Filtros do Dispatcher para mais informaes.

FilterAssetFilter
Os itens de plugins e temas manipulados pelo AssetFilter no so mais lidos via include, ao invs
disso eles so tratados como arquivos de texto plano. Isso corrige um nmero de problemas com
bibliotecas javascript como TinyMCE e ambientes com short_tags ativadas.
O suporte para a configurao Asset.filter e ganchos foram removidos. Essa funcionalidade
pode ser facilmente substituda com um plugin ou filtro de despachante.
Roteamento

33

CakePHP Cookbook Documentation, Verso 3.x

Rede
Requisio
O CakeRequest foi renomeada para Cake\Network\Request.
O Cake\Network\Request::port() foi adicionado.
O Cake\Network\Request::scheme() foi adicionado.
O Cake\Network\Request::cookie() foi adicionado.
O Cake\Network\Request::$trustProxy foi adicionado. Isso torna mais fcil colocar aplicaes CakePHP atrs de balanceadores de carga.
O Cake\Network\Request::$data no mais mesclado com a chave de dados prefixada, pois
esse prefixo foi removido.
O Cake\Network\Request::env() foi adicionado.
O Cake\Network\Request::acceptLanguage() mudou de um mtodo esttico para noesttico.
O detector de requisio para dispositivos mveis foi removido do ncleo. Agora o app template
adiciona detectores para dispositivos mveis usando a biblioteca MobileDetect.
O mtodo onlyAllow() foi renomeado para allowMethod() e no aceita mais argumentos
var. Todos os nomes de mtodos precisam ser passados como primeiro argumento, seja como string
ou como array de strings.

Resposta
O mapeamento do mimetype text/plain para extenso csv foi removido. Como consequncia o
Cake\Controller\Component\RequestHandlerComponent no define a extenso para
csv se o cabealho Accept tiver o mimetype text/plain que era um problema comum quando
recebia uma requisio XHR do jQuery.

Sesses
A classe de sesso no mais esttica, agora a sesso (session) pode ser acessada atravs do objeto de
requisio (request). Veja a documentao em Sessions para ver como usar o objeto de sesso.
O Cake\Network\Session e classes de sesso relacionadas foram movidas para o namespace
Cake\Network.
O SessionHandlerInterface foi removido em favor ao fornecido pelo prprio PHP.
A propriedade Session::$requestCountdown foi removida.
O funcionalidade de sesso checkAgent foi removida. Ela causava um monte de bugs quando
quadros do chrome e o flash player estavam envolvidos.

34

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

A conveno de nome para a tabela de sesso no banco de dados agora sessions ao invs de
cake_sessions.
O cookie de tempo limite da sesso atualizado automaticamente em conjunto com o tempo limite
dos dados de sesso.
O caminho padro para o cookie de sesso agora o caminho base da aplicao, ao invs de /. Alm
disso, uma nova varivel de configurao Session.cookiePath foi adicionada para facilitar a
personalizao do caminho para os cookies.
Um novo mtodo conveniente Cake\Network\Session::consume() foi adicionado para permitir a leitura e excluso de dados de sesso em um nico passo.
O valor padro do argumento $renew de Cake\Network\Session::clear() mudou de
true para false.

Network\Http
O HttpSocket agora Cake\Network\Http\Client.
O HttpClient foi reescrito do zero. Ele tem uma API mais simples/fcil de usar, suporta novos sistemas
de autenticao como OAuth, e uploads de arquivos. Ele usa as API de stream do PHP de modo que
no h requerimentp para o cURL. Veja a documentao Http Client para mais informaes.

Network\Email
O Cake\Network\Email\Email::config() agora usado para definir perfis de configurao. Isso substitui as classes EmailConfig nas verses anteriores.
O Cake\Network\Email\Email::profile() substitui o config() como modo de modificar opes de configurao por instncia.
O Cake\Network\Email\Email::drop() foi adicionado para permitir a remoo de configuraes de email.
O Cake\Network\Email\Email::configTransport() foi adicionado para permitir a
definio de configuraes de transporte. Essa mudana retira as opes de transporte dos perfis
de entrega e permite a voc reusar facilmente os transportes atravs de perfis de e-mails.
O Cake\Network\Email\Email::dropTransport() foi adicionado para permitir a remoo de configuraes de transporte.

Controller
Controller
As propriedades $helpers e $components agora esto mescladas com todas classes pai, no
apenas a AppController e o plugin de AppController. As propriedades so mescladas de modo
Network\Http

35

CakePHP Cookbook Documentation, Verso 3.x

diferente agora tambm. No lugar de todas as configuraes em todas as classes serem mescladas juntas, as configuraes definidas nas classes filho sero usadas. Isso quer dizer que se voc tem alguma
configuraes definida no seu AppController, e alguma configurao definida em uma a subclasse,
apenas a configurao na subclasse ser usada.
O Controller::httpCodes() foi removido, use o Cake\Network\Response::httpCodes()
no lugar.
O
Controller::disableCache()
foi
Cake\Network\Response::disableCache() no lugar.

removido,

use

O Controller::flash() foi removido. Esse mtodo era raramente usado em aplicaes reais e
no tinha mais propsito algum.
O Controller::validate() e Controller::validationErrors() foram removidos.
Eles eram restos dos dias do 1.x onde as preocupaes com os models + controllers eram muito mais
entrelaados.
O Controller::loadModel() agora carrega uma tabela de objetos.
A propriedade Controller::$scaffold foi removida. O scaffolding dinmico foi removido do
ncleo do CakePHP. Um plugin de scaffolding melhorado, chamado CRUD, pode ser encontrado em:
https://github.com/FriendsOfCake/crud
A propriedade Controller::$ext foi removida. Voc deve agora estender e sobrescrever a propriedade View::$_ext se voc deseja usar uma extenso de arquivo de viso no padro.
A propriedade Controller::$methods foi removida.
Voc deve usar o
Controller::isAction() para determinar quando ou no um nome de mtodo uma
ao. Essa mudana foi feita para permitir personalizaes mais fceis do que vai contar ou no
como uma ao.
A propriedade Controller::$Components foi removida e substituda pelo _components.
Se voc precisar carregar componentes em tempo de execuo voc deve usar o
$this->loadComponent() em seu controller.
A assinatura do Cake\Controller\Controller::redirect() mudou para
Controller::redirect(string|array $url, int $status = null).
O terceiro argumento $exit foi removido. O mtodo no pode mais enviar resposta e sair do script, no
lugar ele retorna uma instncia de Response com os cabealhos apropriados definidos.
As propriedades mgicas base, webroot, here, data, action, e params foram removidas.
Voc deve acessar todas essas propriedades em $this->request no lugar.
Mtodos de controlar prefixados com sublinhado como _someMethod() no so mais tratados
como mtodos privados. Use as palavras chaves de visibilidade apropriadas no lugar. Somente mtodos pblicos podem ser usados como ao de controllers.

Scaffold Removido
O scaffolding dinmico no CakePHP foi removido do ncleo do CakePHP. Ele no era usado com frequncia, e no era voltado para uso em produo. Um plugin melhorado de scaffolding, chamado CRUD, pode
ser encontrado em: https://github.com/FriendsOfCake/crud
36

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

ComponentCollection Substitudo
Essa classe foi renomeada para Cake\Controller\ComponentRegistry. Veja a seo em Objetos
de Registro para mais informaes sobre as funcionalidades fornecidas pela nova classe. Voc pode usar o
cake upgrade rename_collections para ajudar voc a atualizar o seu cdigo.

Components
A propriedade _Collection agora _registry.
Cake\Controller\ComponentRegistry agora.

Ela contm uma instncia do

Todos components devem agora usar o mtodo config() para obter/definir configuraes.
A configurao padro para components deve ser definido na propriedade $_defaultConfig.
Essa propriedade automaticamente mesclada com qualquer configurao fornecida pelo construtor.
Opes de configurao no so mais definidas como propriedades pblicas.
O mtodo Component::initialize() no mais um event listener (ouvinte de eventos). Ao invs disso, ele um gancho ps-construtor como o Table::initialize() e
Controller::initialize(). O novo mtodo Component::beforeFilter() ligado
ao mesmo evento que o Component::initialize() costumava ser. O mtodo de inicializao
deve ter a seguinte assinatura initialize(array $config).

Controller\Components
CookieComponent
Ele usa o Cake\Network\Request::cookie() para ler os dados de cookies, isso facilita os
testes, e permite o ControllerTestCase definir os cookies.
Os Cookies encriptados pelas verses anteriores do CakePHP usando o mtodo cipher(), agora
no podem ser lidos, pois o Security::cipher() foi removido. Voc precisar reencriptar os
cookies com o mtodo rijndael() ou aes() antes de atualizar.
O CookieComponent::type() foi removido e substitudo com dados de configurao acessados
atravs de config().
O write() no aceita mais os parmetros encryption ou expires. Os dois agora so gerenciados atravs de dados de configurao. Veja CookieComponent para mais informaes.
O caminho padro para os cookies agora o caminho base da aplicao, ao invs de /.

AuthComponent
O Default agora o hasher de senhas padro usado pelas classes de autenticao. Ele usa exclusivamente o algoritmo de hash bcrypt. Se voc desejar continuar usando o hash SHA1 usado no 2.x,
use passwordHasher => Weak nas configuraes de seu autenticador.

Controller\Components

37

CakePHP Cookbook Documentation, Verso 3.x

O novo FallbackPasswordHasher foi adicionado para ajudar os usurios migrar senhas antigas
de um algoritmo para o outro. Veja a documentao do AuthComponent para mais informaes.
A classe BlowfishAuthenticate foi removida. Apenas use FormAuthenticate.
A classe BlowfishPasswordHasher foi removida. Use o DefaultPasswordHasher no
lugar.
O mtodo loggedIn() foi removido. Use o user() no lugar.
As opes de configurao no so mais definidas como propriedades pblicas.
Os mtodos allow() e deny() no aceitam mais var args. Todos os nomes de mtodos precisam
ser passados como primeiro argumento, seja como string ou array de strings.
O mtodo login() foi removido e substitudo por setUser(). Para logar um usurio agora voc
deve chamar identify() que retorna as informaes do usurio caso identificado com sucesso e
ento usar setUser() para salvar as informaes na sesso de maneira persistente entre as requisies.
O BaseAuthenticate::_password() foi removido. Use a classe PasswordHasher no
lugar.
O BaseAuthenticate::logout() foi removido.
O AuthComponent agora dispara dois eventos Auth.afterIdentify e Auth.logout
aps um usurio ser identificado e antes de um usurio ser deslogado respectivamente. Voc
pode definir funes de callback para esses eventos retornando um array mapeado no mtodo
implementedEvents() de sua classe de autenticao.
Classes relacionadas a ACL foram movidas para um plugin separado. Hashers de senha, fornecedores de
Autenticao e Autorizao foram movidos para o namespace \Cake\Auth. Voc DEVE mover seus
fornecedores e hashers para o namespace App\Auth tambm.

RequestHandlerComponent
Os seguintes mtodos foram removidos do componente RequestHandler:
isAjax(),
isFlash(), isSSL(), isPut(), isPost(), isGet(), isDelete(). Use o mtodo
Cake\Network\Request::is() no lugar com o argumento relevante.
O
RequestHandler::setContent()
Cake\Network\Response::type() no lugar.

foi

removido,

use

O
RequestHandler::getReferer()
Cake\Network\Request::referer() no lugar.

foi

removido,

use

removido,

use

O
RequestHandler::getClientIP()
Cake\Network\Request::clientIp() no lugar.

foi

O RequestHandler::getAjaxVersion() foi removido.


O RequestHandler::mapType() foi removido, use Cake\Network\Response::mapType()
no lugar.
As opes de configurao no so mais definidas como propriedades pblicas.
38

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

SecurityComponent
Os seguintes mtodos e as propriedades relacionadas foram removidas do componente Security: requirePost(), requireGet(), requirePut(), requireDelete(). Use o
Cake\Network\Request::allowMethod() no lugar.
SecurityComponent::$disabledFields()
SecurityComponent::$unlockedFields().

foi

removido,

use

As funes relacionadas ao CSRF no SecurityComponent foram extradas e movidas em separado no


CsrfComponent. Isso permite que voc use a proteo CSRF facilmente sem ter que usar preveno
de adulterao de formulrios.
As opes de configurao no so mais definidas como propriedades pblicas.
Os mtodos requireAuth() e requireSecure() no aceitam mais var args. Todos os
nomes de mtodos precisam ser passados como primeiro argumento, seja como string ou array de
strings.

SessionComponent
O SessionComponent::setFlash() est obsoleto. Voc deve usar o Flash no lugar.

Error
ExceptionRenderers
personalizados
agora
espera-se
que
retornem
ou
um
objeto
Cake\Network\Response ou uma string quando renderizando erros. Isso significa que qualquer
mtodo que manipule excees especficas devem retornar uma resposta ou valor de string.

Model
A camada de model do 2.x foi completamente reescrita e substituda. Voc deve revisar o Guia de atualizao para o novo ORM para saber como usar o novo ORM.
A classe Model foi removida.
A classe BehaviorCollection foi removida.
A classe DboSource foi removida.
A classe Datasource foi removida.
As vrias classes de fonte de dados foram removidas.

ConnectionManager
O ConnectionManager
Cake\Datasource.

Model

(gerenciador

de

conexo)

foi

movido

para

namespace

39

CakePHP Cookbook Documentation, Verso 3.x

O ConnectionManager teve os seguintes mtodos removidos:


sourceList
getSourceName
loadDataSource
enumConnectionObjects
O Database\ConnectionManager::config() foi adicionado e agora o nico jeito de configurar conexes.
O Database\ConnectionManager::get()
getDataSource().

foi

adicionado.

Ele

substitui

O Database\ConnectionManager::configured() foi adicionado.


Ele junto com
config() substitui o sourceList() e enumConnectionObjects() com uma API mais
padro e consistente.
O ConnectionManager::create() foi removido.
config($name, $config) e get($name).

Ele pode ser substitudo por

Behaviors
Os mtodos de comportamentos (behaviors) prefixados com sublinhado como _someMethod() no
so mais tratados como mtodos privados. Use as palavras chaves de visibilidade.

TreeBehavior
O TreeBehavior foi completamente reescrito para usar o novo ORM. Embora ele funcione do mesmo modo
que no 2.x, alguns mtodos foram renomeados ou removidos:
TreeBehavior::children() agora uma busca personalizada find(children).
TreeBehavior::generateTreeList()
find(treeList).

agora

uma

busca

personalizada

TreeBehavior::getParentNode() foi removido.


TreeBehavior::getPath() agora uma busca personalizada find(path).
TreeBehavior::reorder() foi removido.
TreeBehavior::verify() foi removido.

Sute de Testes
Casos de Teste
O _normalizePath() foi adicionado para permitir testes de comparao de caminhos para executar em todos os sistemas operacionais, independente de sua configurao (\ no Windows vs / no
40

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

UNIX, por exemplo).


Os seguintes mtodos de assero foram removidos j que eles estavam h muito obsoletos e foram substitudos pelo seu equivalente no PHPUnit:
assertEqual() substitudo por assertEquals()
assertNotEqual() substitudo por assertNotEquals()
assertIdentical() substitudo por assertSame()
assertNotIdentical() substitudo por assertNotSame()
assertPattern() substitudo por assertRegExp()
assertNoPattern() substitudo por assertNotRegExp()
assertReference() substitudo por assertSame()
assertIsA() substitudo por assertInstanceOf()
Note que alguns mtodos tiveram a ordem dos argumentos trocada, ex.
$expected) deve ser agora assertEquals($expected, $is).

assertEqual($is,

Os seguintes mtodos de assero esto obsoletos e sero removidos no futuro:


assertWithinMargin() substitudo por assertWithinRange()
assertTags() substitudo por assertHtml()
Em ambas as substituies dos mtodos tambm mudaram a ordem dos argumentos para manter a consistncia na API com $expected como primeiro argumento.
Os seguintes mtodos de assero foram adicionados:
assertNotWithinRange() em contrapartida ao assertWithinRange()

View
Temas so agora Plugins Bsicos
Ter os temas e plugins de modo a criar components modulares da aplicao se provou limitado e confuso. No
CakePHP 3.0, temas no residem mais dentro da aplicao. Ao invs disso, eles so plugins independentes.
Isso resolveu alguns problemas com temas:
Voc no podia colocar temas nos plugins.
Temas no podiam fornecer helpers (helpers), ou classes de viso personalizadas.
Esses dois problemas foram resolvidos ao converter os temas em plugins.

Pasta das views renomeada


As pastas contendo os arquivos de views agora ficam em src/Template no lugar de src/View. Isso foi feito
para separar os arquivos de viso dos arquivos contendo classes php. (ex. helpers, Classes de viso).
View

41

CakePHP Cookbook Documentation, Verso 3.x

As seguintes pastas de Viso foram renomeadas para evitar coliso de nomes com nomes de controllers:
Layouts agora Layout
Elements agora Element
Errors agora Error
Emails agora Email (o mesmo para Email dentro de Layout)

Coleo de Helpers Substituda


Essa classe foi renomeada para Cake\View\HelperRegistry. Veja a seo em Objetos de Registro para mais informaes sobre as funcionalidades fornecidas pela nova classe. Voc pode usar o cake
upgrade rename_collections para ajudar voc a atualizar seu cdigo.

Classe View
A chave plugin foi removida do argumento $options de Cake\View\View::element().
Especifique o nome do elemento como AlgumPlugin.nome_do_elemento no lugar.
O View::getVar() foi removido, use o Cake\View\View::get() no lugar.
O View::$ext foi removido e no lugar uma propriedade protegida View::$_ext foi adicionada.
O View::addScript() foi removido. Use o Using View Blocks no lugar.
As propriedades mgicas base, webroot, here, data, action, e params foram removidas.
Ao invs disso, voc deve acessar todas essas propriedades no $this->request.
O View::start() no se liga mais a um bloco existente. Ao invs disso ele ir sobrescrever o
contedo do bloco quando o end() for chamado. Se voc precisa combinar o contedo de um bloco
voc dever buscar o contedo do bloco quando chamar o start uma segunda vez, ou usar o modo de
captura de append().
O View::prepend() no tem mais um modo de captura.
O View::startIfEmpty() foi removido. Agora que o start() sempre sobrescreve, o startIfEmpty
no tem mais propsito.
A propriedade View::$Helpers foi removida e substituda com _helpers. Se voc precisar
carregar helpers em tempo de execuo voc deve usar o $this->addHelper() em seus arquivos
de viso.
O View agora ir lanar Cake\View\Exception\MissingTemplateException quando
templates estiverem faltando, ao invs de MissingViewException.

ViewBlock
O ViewBlock::append() foi removido, use o Cake\ViewViewBlock::concat() no lugar. Entretanto o View::append() ainda existe.

42

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

JsonView
Agora os dados JSON tero as entidades HTML codificadas por padro. Isso previne possveis problemas de XSS quando o contedo de viso JSON est encapsulado em arquivos HTML.
O Cake\View\JsonView agora suporta a varivel de viso _jsonOptions. Isso permite a voc
configurar as opes de mscara de bits usadas ao gerar JSON.

XmlView
A Cake\View\XmlView agora suporta a varivel de viso _xmlOptions. Isso permite a voc
configurar as opes usadas quando gerar XML.

View\Helper
A propriedade $settings agora chamada $_config e deve ser acessada atravs do mtodo
config().
As opes de configurao no so mais definidas como propriedades pblicas.
O Helper::clean() foi removido. Ele nunca foi robusto o suficiente para prevenir completamente XSS. Ao invs disso voc deve escapar o contedo com h ou ou usar uma biblioteca dedicada
como o htmlPurifier.
O Helper::output() foi removido. Esse mtodo estava obsoleto no 2.x.
Os mtodos Helper::webroot(),
Helper::url(),
Helper::assetUrl(),
Helper::assetTimestamp()
foram
movidos
para
o
novo
ajudante
Cake\View\Helper\UrlHelper.
O Helper::url() est agora disponvel como
Cake\View\Helper\UrlHelper::build().
Os Assessores Mgicos a propriedades obsoletas foram removidos. A seguinte propriedade agora
deve ser acessada a partir do objeto de requisio:
base
here
webroot
data
action
params

Helpers
A classe Helper teve os seguintes mtodos removidos:
Helper::setEntity()

View\Helper

43

CakePHP Cookbook Documentation, Verso 3.x

Helper::entity()
Helper::model()
Helper::field()
Helper::value()
Helper::_name()
Helper::_initInputField()
Helper::_selectedArray()
Esses mtodos eram partes usadas apenas pelo FormHelper, e parte de uma funcionalidade de persistncia
de campos que se mostrou problemtica com o tempo. O FormHelper no precisa mais destes mtodos e a
complexidades que eles provm no mais necessria.
Os seguintes mtodos foram removidos:
Helper::_parseAttributes()
Helper::_formatAttribute()
Esses mtodos podem agora ser encontrados na classe StringTemplate que os helpers usam com frequncia. Veja o StringTemplateTrait para um jeito fcil de integrar os templates de string em seus
prprios helpers.

FormHelper
O FormHelper foi completamente reescrito para o 3.0. Ele teve algumas grandes mudanas:
O FormHelper trabalha junto com o novo ORM. Mas tambm possui um sistema extensvel para
integrar com outros ORMs e fontes de dados.
O FormHelper possui um sistema de widgets extensvel que permite a voc criar novos widgets de
entrada personalizados e expandir facilmente aqueles inclusos no framework.
Os Templates de String so a fundao deste ajudante. Ao invs de encher de arrays por toda parte,
a maioria do HTML que o FormHelper gera pode ser personalizado em um lugar central usando
conjuntos de templates.
Alm dessas grandes mudanas, foram feitas algumas mudanas menores que causaram rompendo algumas
coisas da verso anterior. Essas mudanas devem simplificar o HTML que o FormHelper gera e reduzir os
problemas que as pessoas tinham no passado:
O prefixo data[ foi removido de todas as entradas geradas. O prefixo no tem mais propsito.
Os vrios mtodos de entradas independentes, como text(), select() e outros, no geram mais
atributos id.
A opo inputDefaults foi removida de create().
As opes default e onsubmit do create() foram removidas. No lugar voc deve usar
JavaScript event binding ou definir todos os cdigos js necessrios para o onsubmit.
O end() no gerar mais botes. Voc deve criar botes com button() ou submit().
44

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

O FormHelper::tagIsInvalid() foi removido. Use isFieldError() no lugar.


O FormHelper::inputDefaults() foi removido.
definir/expandir os templates que o FormHelper usa.

Voc pode usar templates() para

As opes wrap e class foram removidas do mtodo error().


A opo showParents foi removida do select().
As opes div, before, after, between e errorMessage foram removidas do input().
Voc pode usar templates para atualizar o HTML envoltrio. A opo templates permite voc
sobrescrever os templates carregados para uma entrada.
As opes separator, between, e legend foram removidas do radio(). Voc pode usar
templates para mudar o HTML envoltrio agora.
O parmetro format24Hours foi removido de hour(). Ele foi substitudo pela opo format.
Os parmetros minYear e maxYear foram removidos do year(). Ambos podem ser fornecidos
como opes.
Os parmetros dateFormat e timeFormat foram removidos do datetime(). Voc pode usar
o template para definir a ordem que as entradas devem ser exibidas.
O submit() teve as opes div, before e after removidas. Voc pode personalizar o template
submitContainer para modificar esse contedo.
O mtodo inputs() no aceita mais legend e fieldset no parmetro $fields, voc
deve usar o parmetro $options. Ele tambm exige que o parmetro $fields seja um array.
O parmetro $blacklist foi removido, a funcionalidade foi substituda pela especificao de
field => false no parmetro $fields.
O parmetro inline foi removido do mtodo postLink(). Voc deve usar a opo block no lugar.
Definindo block => true ir emular o comportamento anterior.
O parmetro timeFormat para hour(), time() e dateTime() agora 24 por padro, em
cumprimento ao ISO 8601.
O argumento $confirmMessage de Cake\View\Helper\FormHelper::postLink() foi
removido. Voc deve usar agora a chave confirm no $options para especificar a mensagem.
As entradas do tipo Checkbox e radio so agora renderizadas dentro de elementos do tipo label por
padro. Isso ajuda a aumentar a compatibilidade com bibliotecas CSS populares como Bootstrap10 e
Foundation11 .
As tags de template agora so todas camelBacked (primeira letra minscula e inicio de novas palavras
em maisculo). As tags pr-3.0 formstart, formend, hiddenblock e inputsubmit so
agora formStart, formEnd, hiddenBlock e inputSubmit. Certifique-se de altera-las se
elas estiverem personalizando sua aplicao.
recomendado que voc revise a documentao Form para mais detalhes sobre como usar o FormHelper
no 3.0.
10
11

http://getbootstrap.com/
http://foundation.zurb.com/

View\Helper

45

CakePHP Cookbook Documentation, Verso 3.x

HtmlHelper
O HtmlHelper::useTag() foi removido, use tag() no lugar.
O HtmlHelper::loadConfig() foi removido. As tags podem ser personalizadas usando
templates() ou as configuraes de templates.
O segundo parmetro $options para HtmlHelper::css() agora sempre ir exigir um array.
O primeiro parmetro $data para HtmlHelper::style() agora sempre ir exigir um array.
O parmetro inline foi removido dos mtodos meta(), css(), script() e scriptBlock(). Ao invs
disso, voc deve usar a opo block. Definindo block => true ir emular o comportamento
anterior.
O HtmlHelper::meta() agora exige que o $type seja uma string. Opes adicionais podem
ser passadas como $options.
O HtmlHelper::nestedList() agora exige que o $options seja um array. O quarto argumento para o tipo tag foi removido e incluido no array $options.
O argumento $confirmMessage de Cake\View\Helper\HtmlHelper::link() foi removido. Voc deve usar agora a chave confirm no $options para especificar a menssagem.

PaginatorHelper
O link() foi removido. Ele no era mais usado internamente pelo ajudante. Ele era pouco usado
em cdigos de usurios e no se encaixava mais nos objetivos do ajudante.
O next() no tem mais as opes class ou tag. Ele no tem mais argumentos desabilitados. Ao
invs disso so usados templates.
O prev() no tem mais as opes class ou tag. Ele no tem mais argumentos desabilitados. Ao
invs disso so usados templates.
O first() no tem mais as opes after, ellipsis, separator, class ou tag.
O last() no tem mais as opes after, ellipsis, separator, class ou tag.
O numbers() no tem mais as opes separator, tag, currentTag, currentClass, class, tag e
ellipsis. Essas opes so agora facilitadas pelos templates. Ele tambm exige que agora o parmetro
$options seja um array.

O espao reservado de estilo %page% foi removido de Cake\View\Helper\PaginatorHelper::counter()


Use o espao reservado de estilo {{page}} no lugar.
O url() foi renomeada para generateUrl() para evitar coliso de declarao de mtodo com
Helper::url().
Por padro todos os links e textos inativos so encapsulados em elementos <li>. Isso ajuda a fazer o CSS
mais fcil de escrever, e aumenta a compatibilidade com frameworks de CSS populares.
Ao invs de vrias opes em cada mtodo, voc deve usar a funcionalidade de templates. Veja a documentao PaginatorHelper Templates para informaes de como se usar templates.

46

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

TimeHelper
TimeHelper::__set(), TimeHelper::__get(), e TimeHelper::__isset() foram
removidos. Eles eram mtodos mgicos para atributos obsoletos.
O TimeHelper::serverOffset() foi removido. Ele provia prticas incorretas de operaes
com tempo.
O TimeHelper::niceShort() foi removido.

NumberHelper
O NumberHelper::format() agora exige que $options seja um array.

SessionHelper
O SessionHelper est obsoleto. Voc pode usar $this->request->session() diretamente, e a funcionalidade de mensagens flash foi movida para Flash.

JsHelper
O JsHelper e todos motores associados foram removidos. Ele podia gerar somente um subconjunto
muito pequeno de cdigos JavaScript para biblioteca selecionada e consequentemente tentar gerar
todo cdigo JavaScript usando apenas o ajudante se tornava um impedimento com frequncia.
recomendado usar diretamente sua biblioteca JavaScript preferida.

CacheHelper Removido
O CacheHelper foi removido. A funcionalidade de cache que ele fornecia no era padro, limitada e incompatvel com layouts no-HTML e views de dados. Essas limitaes significavam que uma reconstruo
completa era necessria. O ESI (Edge Side Includes) se tornou uma maneira padronizada para implementar
a funcionalidade que o CacheHelper costumava fornecer. Entretanto, implementando Edge Side Includes12
em PHP tem vrias limitaes e casos. Ao invs de construir uma soluo ruim, recomendado que os
desenvolvedores que precisem de cache de resposta completa use o Varnish13 ou Squid14 no lugar.

I18n
O subsistema de internacionalizao foi completamente reescrito. Em geral, voc pode esperar o mesmo
comportamento que nas verses anteriores, especialmente se voc est usando a famlia de funes __().
12

http://en.wikipedia.org/wiki/Edge_Side_Includes
http://varnish-cache.org
14
http://squid-cache.org
13

I18n

47

CakePHP Cookbook Documentation, Verso 3.x

Internamente, a classe I18n usa Aura\Intl, e mtodos apropriados so expostos para dar acesso a
funes especficas da biblioteca. Por esta razo a maior parte dos mtodos dentro de I18n foram removidos ou renomeados.
Devido ao uso do ext/intl, a classe L10n foi removida completamente. Ela fornecia dados incompletos
e desatualizados em comparao com os dados disponveis na classe Locale do PHP.
O idioma padro da aplicao no ser mais alterado automaticamente pelos idiomas aceitos pelo navegador
nem por ter o valor Config.language definido na sesso do navegador. Voc pode, entretanto, usar um
filtro no despachante para trocar o idioma automaticamente a partir do cabealho Accept-Language
enviado pelo navegador:
// No config/bootstrap.php
DispatcherFactory::addFilter('LocaleSelector');

No h nenhum substituto incluso para selecionar automaticamente o idioma a partir de um valor configurado na sesso do usurio.
A funo padro para formatao de mensagens traduzidas no mais a sprintf, mas a mais avanada
e funcional classe MessageFormatter. Em geral voc pode reescrever os espaos reservados nas mensagens como segue:
// Antes:
__('Hoje um dia %s na %s', 'Ensolarado', 'Espanha');
// Depois:
__('Hoje um dia {0} na {1}', 'Ensolarado', 'Espanha');

Voc pode evitar ter de reescrever suas mensagens usando o antigo formatador sprintf:
I18n::defaultFormatter('sprintf');

Adicionalmente, o valor Config.language foi removido e ele no pode mais ser usado para controlar o
idioma atual da aplicao. Ao invs disso, voc pode usar a classe I18n:
// Antes
Configure::write('Config.language', 'fr_FR');
// Agora
I18n::locale('en_US');

Os mtodos abaixo foram movidos:


De Cake\I18n\Multibyte::utf8() para Cake\Utility\Text::utf8()
De Cake\I18n\Multibyte::ascii() para Cake\Utility\Text::ascii()
De
Cake\I18n\Multibyte::checkMultibyte()
Cake\Utility\Text::isMultibyte()

para

Como agora o CakePHP requer a extenso mbstring, a classe Multibyte foi removida.
As mensagens de erro por todo o CakePHP no passam mais atravs das funes de internacionalizao. Isso foi feito para simplificar o ncleo do CakePHP e reduzir a sobrecarga. As mensagens

48

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

apresentadas aos desenvolvedores so raramente, isso quando, so de fato traduzidas - de modo que
essa sobrecarga adicional trs pouco beneficio.

Localizao
Agora o construtor de Cake\I18n\L10n recebe uma instncia de Cake\Network\Request
como argumento.

Testes
O TestShell foi removido. O CakePHP, o esqueleto da aplicao e novos plugins cozinhados,
todos usam o phpunit para rodar os testes.
O webrunner (webroot/test.php) foi removido. A adoo do CLI aumentou grandemente desde o
release inicial do 2.x. Adicionalmente, os CLI de execuo oferecem integrao superior com IDEs
e outras ferramentas automticas.
Se voc sentir necessidade de um jeito de executar os testes a partir de um navegador, voc deve
verificar o VisualPHPUnit15 . Ele oferece muitas funcionalidades adicionais que o antigo webrunner.
O ControllerTestCase est obsoleto e ser removido no CakePHP 3.0.0. Ao invs disso, voc
deve usar a nova funcionalidade Controller Integration Testing.
As Fixtures devem agora ser referenciadas usando sua forma no plural:
// No lugar de
$fixtures = ['app.artigo'];
// Voc deve usar
$fixtures = ['app.artigos'];

Utilitrios
Classe Set Removida
A classe Set foi removida, agora voc deve usar a classe Hash no lugar dela.

Pastas & Arquivos


As classes de pastas e arquivos foram renomeadas:
O Cake\Utility\File foi renomeado para Cake\Filesystem\File
O Cake\Utility\Folder foi renomeado para Cake\Filesystem\Folder
15

https://github.com/NSinopoli/VisualPHPUnit

Localizao

49

CakePHP Cookbook Documentation, Verso 3.x

Inflexo
O valor padro para o argumento $replacement do Cake\Utility\Inflector::slug()
foi alterado do sublinhado (_) para o trao (-). Usando traos para separar palavras nas URLs a
escolha popular e tambm recomendada pelo Google.
As transliteraes para Cake\Utility\Inflector::slug() foram alteradas. Se voc usa
transliteraes personalizadas voc ter que atualizar seu cdigo. No lugar de expresses regulares,
as transliteraes usam simples substituies de string. Isso rendeu melhorias de performance significativas:
// No lugar de
Inflector::rules('transliteration', [
'/|/' => 'ae',
'//' => 'aa'
]);
// Voc deve usar
Inflector::rules('transliteration', [
'' => 'ae',
'' => 'ae',
'' => 'aa'
]);

Os conjuntos distintos de regras de no-inflexes e irregulares para pluralizao e singularizao foram removidos. No lugar agora temos uma lista comum para cada. Quando usar
Cake\Utility\Inflector::rules() com o tipo singular e plural voc no poder mais
usar chaves como uninflected e irregular no array de argumentos $rules.
Voc pode adicionar / sobrescrever a lista de regras de no-inflexionados e irregulares usando
Cake\Utility\Inflector::rules() com valores uninflected e irregular para o argumento $type.

Sanitize
A classe Sanitize foi removida.

Segurana
O Security::cipher() foi removido. Ele era inseguro e promovia prticas ruins de criptografia.
Voc deve usar o Security::encrypt() no lugar.
O valor de configurao Security.cipherSeed no mais necessrio. Com a remoo de
Security::cipher() ele no tem utilidade.
A retrocompatibilidade do Cake\Utility\Security::rijndael() para valores encriptados antes do CakePHP 2.3.1 foi removido.
Voc deve reencriptar os valores usando
Security::encrypt() e uma verso recente do CakePHP 2.x antes de migrar.
A habilidade para gerar um hash do tipo blowfish foi removido. Voc no pode mais usar
o tipo blowfish em Security::hash(). Deve ser usado apenas o password_hash() do
50

Captulo 3. 3.0 - Guia de migrao

CakePHP Cookbook Documentation, Verso 3.x

PHP e password_verify() para gerar e verificar hashes blowfish. A compabilidade da biblioteca


ircmaxell/password-compat16 que instalado junto com o CakePHP fornece essas funes para verses de PHP menor que 5.5.
O OpenSSL usado agora no lugar do mcrypt ao encriptar/desencriptar dados. Esse alterao fornece
uma melhor performance e deixa o CakePHP a prova de futuros abandonos de suporte das distribuies ao mcrypt.
O Security::rijndael() est obsoleto e apenas disponvel quando se usa o mcrypt.
Aviso: Dados encriptados com Security::encrypt() em verses anteriores no so compatveis com a
implementao openssl. Voc deve definir a implementao como mcrypt quando fizer atualizao.

Data e Hora
O CakeTime foi renomeado para Cake\I18n\Time.
O CakeTime::serverOffset() foi removido. Ele provia prticas incorretas de operaes com
tempo.
O CakeTime::niceShort() foi removido.
O CakeTime::convert() foi removido.
O CakeTime::convertSpecifiers() foi removido.
O CakeTime::dayAsSql() foi removido.
O CakeTime::daysAsSql() foi removido.
O CakeTime::fromString() foi removido.
O CakeTime::gmt() foi removido.
O CakeTime::toATOM() foi renomeado para toAtomString.
O CakeTime::toRSS() foi renomeado para toRssString.
O CakeTime::toUnix() foi renomeado para toUnixString.
O CakeTime::wasYesterday() foi renomeado para isYesterday para combinar com o
resto da renomeao de mtodos.
O CakeTime::format() no usa mais o formato do sprintf, ao invs disso voc deve usar o
formato i18nFormat.
O Time::timeAgoInWords() agora exige que o $options seja um array.
A classe Time no mais uma coleo de mtodos estticos, ela estende o DateTime para herdar todos
seus mtodos e adicionar funes de formatao baseado em localizao com ajuda da extenso intl.
Em geral, expresses assim:
16

https://packagist.org/packages/ircmaxell/password-compat

Utilitrios

51

CakePHP Cookbook Documentation, Verso 3.x

CakeTime::aMethod($date);

Podem ser migradas reescrevendo para:


(new Time($date))->aMethod();

Nmeros
A biblioteca Number foi reescrita para usar internamente a classe NumberFormatter.
O CakeNumber foi renomeada para Cake\I18n\Number.
O Number::format() agora exige que o $options seja um array.
O Number::addFormat() foi removido.
O Number::fromReadableSize() foi movido para Cake\Utility\Text::parseFileSize().

Validao
A faixa de valores para Validation::range() agora inclusiva se $lower e $upper forem
fornecidos.
O Validation::ssn() foi removido.

Xml
O Xml::build() agora exige que o $options seja um array.
O Xml::build() no aceita mais uma URL. Se voc precisar criar um documento XML a partir
de uma URL, use o

52

Captulo 3. 3.0 - Guia de migrao

CAPTULO 4

Tutoriais & Exemplos

Nesta seo, voc poder caminhar atravs de tpicas aplicaes CakePHP para ver como todas as peas se
encaixam.
Como alternativa, voc pode preferir visitar o repositrio no oficial de plugins para o CakePHP CakePackages1 e a Bakery (Padaria)2 para conhecer aplicaes e componentes existentes.

Tutorial - Criando um Bookmarker - Parte 1


Esse tutorial vai guiar voc atravs da criao de uma simples aplicao de marcao (bookmarker). Para
comear, ns vamos instalar o CakePHP, criar nosso banco de dados, e usar as ferramentas que o CakePHP
fornece para obter nossa aplicao de p rpido.
Aqui est o que voc vai precisar:
1. Um servidor de banco de dados. Ns vamos usar o servidor MySQL neste tutorial. Voc precisa
saber o suficiente sobre SQL para criar um banco de dados: O CakePHP vai tomar as rdeas a partir
da. Por ns estarmos usando o MySQL, tambm certifique-se que voc tem a extenso pdo_mysql
habilitada no PHP.
2. Conhecimento bsico sobre PHP.
Vamos comear!

Instalao do CakePHP
A maneira mais fcil de instalar o CakePHP usando Composer, um gerenciador de dependncias para o
PHP. uma forma simples de instalar o CakePHP a partir de seu terminal ou prompt de comando. Primeiro,
voc precisa baixar e instalar o Composer. Se voc tiver instalada a extenso cURL do PHP, execute o
seguinte comando:
1
2

http://plugins.cakephp.org/
http://bakery.cakephp.org/

53

CakePHP Cookbook Documentation, Verso 3.x

curl -s https://getcomposer.org/installer | php

Ao invs disso, voc tambm pode baixar o arquivo composer.phar do site3 oficial.
Em seguida, basta digitar a seguinte linha no seu terminal a partir do diretrio onde se localiza o arquivo
composer.phar para instalar o esqueleto de aplicaes do CakePHP no diretrio bookmarker.
php composer.phar create-project --prefer-dist cakephp/app bookmarker

A vantagem de usar Composer que ele ir completar automaticamente um conjunto importante de tarefas,
como configurar as permisses de arquivo e criar a sua config/app.php.
H outras maneiras de instalar o CakePHP. Se voc no puder ou no quiser usar Composer, veja a seo
Instalao.
Independentemente de como voc baixou o CakePHP, uma vez que sua instalao for concluda, a estrutura
dos diretrios deve ficar parecida com o seguinte:
/bookmarker
/bin
/config
/logs
/plugins
/src
/tests
/tmp
/vendor
/webroot
.editorconfig
.gitignore
.htaccess
.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md

Agora pode ser um bom momento para aprender sobre como a estrutura de diretrios do CakePHP funciona:
Confira a seo Estrutura de pastas do CakePHP.

Verificando nossa instalao


Podemos checar rapidamente que a nossa instalao est correta, verificando a pgina inicial padro. Antes
que voc possa fazer isso, voc vai precisar iniciar o servidor de desenvolvimento:
bin/cake server

Isto ir iniciar o servidor embutido do PHP na porta 8765. Abra http://localhost:8765 em seu
navegador para ver a pgina de boas-vindas. Todas as verificaes devem estar checadas corretamente, a
no ser a conexo com banco de dados do CakePHP. Se no, voc pode precisar instalar extenses do PHP
adicionais, ou definir permisses de diretrio.
3

54

https://getcomposer.org/download/

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Criando o banco de dados


Em seguida, vamos criar o banco de dados para a nossa aplicao. Se voc ainda no tiver feito isso,
crie um banco de dados vazio para uso nesse tutorial, com um nome de sua escolha, por exemplo,
cake_bookmarks. Voc pode executar o seguinte SQL para criar as tabelas necessrias:
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) NOT NULL,
password VARCHAR(255) NOT NULL,
created DATETIME,
modified DATETIME
);
CREATE TABLE bookmarks (
id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
title VARCHAR(50),
description TEXT,
url TEXT,
created DATETIME,
modified DATETIME,
FOREIGN KEY user_key (user_id) REFERENCES users(id)
);
CREATE TABLE tags (
id INT AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(255),
created DATETIME,
modified DATETIME,
UNIQUE KEY (title)
);
CREATE TABLE bookmarks_tags (
bookmark_id INT NOT NULL,
tag_id INT NOT NULL,
PRIMARY KEY (bookmark_id, tag_id),
INDEX tag_idx (tag_id, bookmark_id),
FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id)
);

Voc deve ter notado que a tabela bookmarks_tags utilizada uma chave primria composta. O CakePHP
suporta chaves primrias compostas quase todos os lugares, tornando mais fcil construir aplicaes multiarrendados.
Os nomes de tabelas e colunas que usamos no foram arbitrrias. Usando convenes de nomenclatura
do CakePHP, podemos alavancar o desenvolvimento e evitar ter de configurar o framework. O CakePHP
flexvel o suficiente para acomodar at mesmo esquemas de banco de dados legados inconsistentes, mas
aderir s convenes vai lhe poupar tempo.

Tutorial - Criando um Bookmarker - Parte 1

55

CakePHP Cookbook Documentation, Verso 3.x

Configurando o banco de dados


Em seguida, vamos dizer ao CakePHP onde o nosso banco de dados est como se conectar a ele. Para
muitos, esta ser a primeira e ltima vez que voc vai precisar configurar qualquer coisa.
A configurao bem simples: basta alterar os valores do array Datasources.default no arquivo
config/app.php pelos que se aplicam sua configurao. A amostra completa da gama de configuraes
pode ser algo como o seguinte:
return [
// Mais configurao acima.
'Datasources' => [
'default' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'persistent' => false,
'host' => 'localhost',
'username' => 'cakephp',
'password' => 'AngelF00dC4k3~',
'database' => 'cake_bookmarks',
'encoding' => 'utf8',
'timezone' => 'UTC',
'cacheMetadata' => true,
],
],
// Mais configurao abaixo.
];

Depois de salvar o seu arquivo config/app.php, voc deve notar que a mensagem CakePHP is able to
connect to the database tem uma marca de verificao.
Nota:
Uma cpia do arquivo de configurao padro do CakePHP encontrado em config/app.default.php.

Gerando o cdigo base


Devido a nosso banco de dados seguir as convenes do CakePHP, podemos usar o bake console para gerar
rapidamente uma aplicao bsica . Em sua linha de comando execute:
bin/cake bake all users
bin/cake bake all bookmarks
bin/cake bake all tags

Isso ir gerar os controllers, models, views, seus casos de teste correspondentes, e fixtures
para os nossos users, bookmarks e tags.
Se voc parou seu servidor, reinicie-o e v para
http://localhost:8765/bookmarks.
Voc dever ver uma aplicao que d acesso bsico, mas funcional a tabelas de banco de dados. Adicione
alguns users, bookmarks e tags.

56

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Adicionando criptografia de senha


Quando voc criou seus users, voc deve ter notado que as senhas foram armazenadas como texto simples.
Isso muito ruim do ponto de vista da segurana, por isso vamos consertar isso.
Este tambm um bom momento para falar sobre a camada de modelo. No CakePHP, separamos os mtodos
que operam em uma coleo de objetos, e um nico objeto em diferentes classes. Mtodos que operam na
recolha de entidades so colocadas na classe Table, enquanto as caractersticas pertencentes a um nico
registro so colocados na classe Entity.
Por exemplo, a criptografia de senha feita no registro individual, por isso vamos implementar esse comportamento no objeto entidade. Dada a circunstncia de ns querermos criptografar a senha cada vez que
definida, vamos usar um mtodo modificador/definidor. O CakePHP vai chamar mtodos de definio
baseados em convenes a qualquer momento que uma propriedade definida em uma de suas entidades.
Vamos adicionar um definidor para a senha. Em src/Model/Entity/User.php adicione o seguinte:
namespace App\Model\Entity;
use Cake\ORM\Entity;
use Cake\Auth\DefaultPasswordHasher;
class User extends Entity
{
// Code from bake.
protected function _setPassword($value)
{
$hasher = new DefaultPasswordHasher();
return $hasher->hash($value);
}
}

Agora atualize um dos usurios que voc criou anteriormente, se voc alterar sua senha, voc deve ver um
senha criptografada ao invs do valor original nas pginas de lista ou visualizao. O CakePHP criptografa
senhas com bcrypt4 por padro. Voc tambm pode usar sha1 ou md5 caso venha a trabalhar com um banco
de dados existente.

Recuperando bookmarks com uma tag especfica


Agora que estamos armazenando senhas com segurana, podemos construir algumas caractersticas mais
interessantes em nossa aplicao. Uma vez que voc acumulou uma coleo de bookmarks, til ser capaz
de pesquisar atravs deles por tag. Em seguida, vamos implementar uma rota, a ao do controller, e um
mtodo localizador para pesquisar atravs de bookmarks por tag.

Idealmente, ns teramos uma URL que se parece com http://localhost:8765/bookmarks/tagged/funny/ca


Isso deveria nos permitir a encontrar todos os bookmarks que tm as tags funny, cat e gifs. Antes de
podermos implementar isso, vamos adicionar uma nova rota. Em config/routes.php, adicione o seguinte na
parte superior do arquivo:
4

http://codahale.com/how-to-safely-store-a-password/

Tutorial - Criando um Bookmarker - Parte 1

57

CakePHP Cookbook Documentation, Verso 3.x

Router::scope(
'/bookmarks',
['controller' => 'Bookmarks'],
function ($routes) {
$routes->connect('/tagged/*', ['action' => 'tags']);
}
);

O acima define uma nova rota que liga o caminho /bookmarks/tagged/*,


a BookmarksController::tags().
Ao definir rotas, voc pode isolar como
suas URLs parecero,
de como eles so implementadas.
Se fssemos visitar
http://localhost:8765/bookmarks/tagged,
deveriamos
ver
uma
pgina
de
erro informativa do CakePHP. Vamos implementar esse mtodo ausente agora.
Em
src/Controller/BookmarksController.php adicione o seguinte:
public function tags()
{
$tags = $this->request->params['pass'];
$bookmarks = $this->Bookmarks->find('tagged', [
'tags' => $tags
]);
$this->set(compact('bookmarks', 'tags'));
}

Criando o mtodo localizador


No CakePHP ns gostamos de manter as nossas aes do controller enxutas, e colocar a maior parte da
lgica de nossa aplicao nos modelos. Se voc fosse visitar a URL /bookmarks/tagged agora, voc
veria um erro sobre o mtodo findTagged no estar implementado ainda, ento vamos fazer isso. Em
src/Model/Table/BookmarksTable.php adicione o seguinte:
public function findTagged(Query $query, array $options)
{
$fields = [
'Bookmarks.id',
'Bookmarks.title',
'Bookmarks.url',
];
return $this->find()
->distinct($fields)
->matching('Tags', function ($q) use ($options) {
return $q->where(['Tags.title IN' => $options['tags']]);
});
}

Ns implementamos um mtodo localizador customizado. Este um conceito muito poderoso no


CakePHP que lhe permite construir consultas reutilizveis. Em nossa pesquisa, ns alavancamos o mtodo
matching() que nos habilita encontrar bookmarks que tm uma tag correspondente.

58

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Criando a view
Agora, se voc visitar a URL /bookmarks/tagged, o CakePHP ir mostrar um erro e deix-lo saber
que voc ainda no fez um arquivo view. Em seguida, vamos construir o arquivo view para a nossa ao
tags. Em src/Template/Bookmarks/tags.ctp coloque o seguinte contedo:
<h1>
Bookmarks tagged with
<?= $this->Text->toList($tags) ?>
</h1>
<section>
<?php foreach ($bookmarks as $bookmark): ?>
<article>
<h4><?= $this->Html->link($bookmark->title, $bookmark->url) ?></h4>
<small><?= h($bookmark->url) ?></small>
<?= $this->Text->autoParagraph($bookmark->description) ?>
</article>
<?php endforeach; ?>
</section>

O CakePHP espera que os nossos templates sigam a conveno de nomenclatura onde o nome do template
a verso minscula e grifada do nome da ao do controller.
Voc pode perceber que fomos capazes de utilizar as variveis $tags e bookmarks em nossa view.
Quando usamos o mtodo set() em nosso controller, automaticamente definimos variveis especficas
que devem ser enviadas para a view. A view vai tornar todas as variveis passadas disponveis nos templates
como variveis locais.
Em nossa view, usamos alguns dos helpers nativos do CakePHP. Helpers so usados para criar lgica reutilizvel para a formatao de dados, a criao de HTML ou outra sada da view.
Agora voc deve ser capaz de visitar a URL /bookmarks/tagged/funny e ver todas os bookmarks
com a tag funny.
At agora, ns criamos uma aplicao bsica para gerenciar bookmarks, tags e users. No entanto, todos
podem ver as tags de toda a gente. No prximo captulo, vamos implementar a autenticao e restringir os
bookmarks visveis para somente aqueles que pertencem ao usurio atual.
Agora v a Tutorial - Criando um Bookmarker - Parte 2 para continuar a construir sua aplicao ou
mergulhe na documentao para saber mais sobre o que CakePHP pode fazer por voc.

Tutorial - Criando um Bookmarker - Parte 2


Depois de terminar a primeira parte deste tutorial, voc deve ter uma aplicao muito bsica. Neste captulo
iremos adicionar autenticao e restringir as bookmarks para que cada usurio possa ver/modificar somente
aquelas que possuam.

Tutorial - Criando um Bookmarker - Parte 2

59

CakePHP Cookbook Documentation, Verso 3.x

Adicionando login
No CakePHP, a autenticao feita por Components (Componentes). Os Components podem ser considerados como formas de criar pedaos reutilizveis de cdigo relacionado a controllers com uma caracterstica
especfica ou conceito. Os components tambm podem ligar-se ao evento do ciclo de vida do controller e
interagir com a sua aplicao. Para comear, vamos adicionar o AuthComponent a nossa aplicao. Ns
vamos querer muito que cada mtodo exija autenticao, por isso vamos acrescentar o AuthComponent em
nosso AppController:
// Em src/Controller/AppController.php
namespace App\Controller;
use Cake\Controller\Controller;
class AppController extends Controller
{
public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'authenticate' => [
'Form' => [
'fields' => [
'username' => 'email',
'password' => 'password'
]
]
],
'loginAction' => [
'controller' => 'Users',
'action' => 'login'
]
]);
// Permite a ao display, assim nosso pages controller
// continua a funcionar.
$this->Auth->allow(['display']);
}
}

Acabamos de dizer ao CakePHP que queremos carregar os components Flash e Auth. Alm disso, temos
a configurao personalizada do AuthComponent, assim a nossa tabela users pode usar email como username. Agora, se voc for a qualquer URL, voc vai ser chutado para /users/login, que ir mostrar uma
pgina de erro j que no escrevemos o cdigo ainda. Ento, vamos criar a ao de login:
// Em src/Controller/UsersController.php
public function login()
{
if ($this->request->is('post')) {
$user = $this->Auth->identify();
if ($user) {
$this->Auth->setUser($user);

60

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

return $this->redirect($this->Auth->redirectUrl());
}
$this->Flash->error('Your username or password is incorrect.');
}
}

E em src/Template/Users/login.ctp adicione o seguinte:


<h1>Login</h1>
<?= $this->Form->create() ?>
<?= $this->Form->input('email') ?>
<?= $this->Form->input('password') ?>
<?= $this->Form->button('Login') ?>
<?= $this->Form->end() ?>

Agora que temos um simples formulrio de login, devemos ser capazes de efetuar login com um dos users
que tenham senha criptografada.
Nota: Se nenhum de seus users tem senha criptografada, comente a linha loadComponent(Auth).
Ento v e edite o user, salvando uma nova senha para ele.
Agora voc deve ser capaz de entrar. Se no, certifique-se que voc est usando um user que tenha senha
criptografada.

Adicionando logout
Agora que as pessoas podem efetuar o login, voc provavelmente vai querer fornecer uma maneira de encerrar a sesso tambm. Mais uma vez, no UsersController, adicione o seguinte cdigo:
public function logout()
{
$this->Flash->success('You are now logged out.');
return $this->redirect($this->Auth->logout());
}

Agora voc pode visitar /users/logout para sair e ser enviado pgina de login.

Ativando inscries
Se voc no estiver logado e tentar visitar / usurios / adicionar voc vai ser expulso para a pgina de login.
Devemos corrigir isso se quisermos que as pessoas se inscrevam em nossa aplicao. No UsersController
adicione o seguinte:
public function beforeFilter(\Cake\Event\Event $event)
{
$this->Auth->allow(['add']);
}

O texto acima diz ao AuthComponent que a ao add no requer autenticao ou autorizao. Voc pode
querer dedicar algum tempo para limpar a /users/add e remover os links enganosos, ou continuar para a
Tutorial - Criando um Bookmarker - Parte 2

61

CakePHP Cookbook Documentation, Verso 3.x

prxima seo. Ns no estaremos construindo a edio do usurio, visualizao ou listagem neste tutorial,
ento eles no vo funcionar, j que o AuthComponent vai negar-lhe acesso a essas aes do controller.

Restringindo acesso
Agora que os usurios podem conectar-se, ns vamos querer limitar os bookmarks que podem ver para
aqueles que fizeram. Ns vamos fazer isso usando um adaptador de autorizao. Sendo os nossos requisitos bastante simples, podemos escrever um cdigo em nossa BookmarksController. Mas antes
de fazer isso, vamos querer dizer ao AuthComponent como nossa aplicao vai autorizar aes. Em seu
AppController adicione o seguinte:
public function isAuthorized($user)
{
return false;
}

Alm disso, adicione o seguinte configurao para Auth em seu AppController:


'authorize' => 'Controller',

Seu mtodo initialize agora deve parecer com:


public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'authorize'=> 'Controller',//added this line
'authenticate' => [
'Form' => [
'fields' => [
'username' => 'email',
'password' => 'password'
]
]
],
'loginAction' => [
'controller' => 'Users',
'action' => 'login'
],
'unauthorizedRedirect' => $this->referer()
]);
// Permite a ao display, assim nosso pages controller
// continua a funcionar.
$this->Auth->allow(['display']);
}

Vamos usar como padro, negao do acesso, e de forma incremental conceder acesso onde faa sentido.
Primeiro, vamos adicionar a lgica de autorizao para os bookmarks. Em seu BookmarksController
adicione o seguinte:

62

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

public function isAuthorized($user)


{
$action = $this->request->params['action'];
// As aes add e index so permitidas sempre.
if (in_array($action, ['index', 'add', 'tags'])) {
return true;
}
// Todas as outras aes requerem um id.
if (empty($this->request->params['pass'][0])) {
return false;
}
// Checa se o bookmark pertence ao user atual.
$id = $this->request->params['pass'][0];
$bookmark = $this->Bookmarks->get($id);
if ($bookmark->user_id == $user['id']) {
return true;
}
return parent::isAuthorized($user);
}

Agora, se voc tentar visualizar, editar ou excluir um bookmark que no pertena a voc, voc deve ser
redirecionado para a pgina de onde veio. No entanto, no h nenhuma mensagem de erro sendo exibida,
ento vamos corrigir isso a seguir:
// In src/Template/Layout/default.ctp
// Under the existing flash message.
<?= $this->Flash->render('auth') ?>

Agora voc deve ver as mensagens de erro de autorizao.

Corrigindo a view de listagem e formulrios


Enquanto view e delete esto trabalhando, edit, add e index tem alguns problemas:
1. Ao adicionar um bookmark, voc pode escolher o user.
2. Ao editar um bookmark, voc pode escolher o user.
3. A pgina de listagem mostra os bookmarks de outros users.
Vamos enfrentar o formulrio de adio em primeiro lugar. Para comear remova o input(user_id)
a partir de src/Template/Bookmarks/add.ctp. Com isso removido, ns tambm vamos atualizar o mtodo
add:
public function add()
{
$bookmark = $this->Bookmarks->newEntity();
if ($this->request->is('post')) {
$bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->data);
$bookmark->user_id = $this->Auth->user('id');
if ($this->Bookmarks->save($bookmark)) {

Tutorial - Criando um Bookmarker - Parte 2

63

CakePHP Cookbook Documentation, Verso 3.x

$this->Flash->success('The bookmark has been saved.');


return $this->redirect(['action' => 'index']);
}
$this->Flash->error('The bookmark could not be saved. Please, try again.');
}
$tags = $this->Bookmarks->Tags->find('list');
$this->set(compact('bookmark', 'tags'));
}

Ao definir a propriedade da entidade com os dados da sesso, ns removemos qualquer possibilidade do


user modificar de que outro user um bookmark seja. Ns vamos fazer o mesmo para o formulrio edit e
action edit. Sua ao edit deve ficar assim:
public function edit($id = null)
{
$bookmark = $this->Bookmarks->get($id, [
'contain' => ['Tags']
]);
if ($this->request->is(['patch', 'post', 'put'])) {
$bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->data);
$bookmark->user_id = $this->Auth->user('id');
if ($this->Bookmarks->save($bookmark)) {
$this->Flash->success('The bookmark has been saved.');
return $this->redirect(['action' => 'index']);
}
$this->Flash->error('The bookmark could not be saved. Please, try again.');
}
$tags = $this->Bookmarks->Tags->find('list');
$this->set(compact('bookmark', 'tags'));
}

View de listagem
Agora, ns precisamos apenas exibir bookmarks para o user logado. Ns podemos fazer isso ao atualizar a
chamada para paginate(). Altere sua ao index:
public function index()
{
$this->paginate = [
'conditions' => [
'Bookmarks.user_id' => $this->Auth->user('id'),
]
];
$this->set('bookmarks', $this->paginate($this->Bookmarks));
}

Ns tambm devemos atualizar a action tags() e o mtodo localizador relacionado, mas vamos deixar
isso como um exerccio para que voc conclua por s.

64

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Melhorando a experincia com as tags


Agora, adicionar novas tags um processo difcil, pois o TagsController probe todos os acessos. Em
vez de permitir o acesso, podemos melhorar a interface do usurio para selecionar tags usando um campo
de texto separado por vrgulas. Isso permitir dar uma melhor experincia para os nossos usurios, e usar
mais alguns grandes recursos no ORM.
Adicionando um campo computado
Porque ns queremos uma maneira simples de acessar as tags formatados para uma entidade, podemos
adicionar um campo virtual/computado para a entidade. Em src/Model/Entity/Bookmark.php adicione o
seguinte:
use Cake\Collection\Collection;
protected function _getTagString()
{
if (isset($this->_properties['tag_string'])) {
return $this->_properties['tag_string'];
}
if (empty($this->tags)) {
return '';
}
$tags = new Collection($this->tags);
$str = $tags->reduce(function ($string, $tag) {
return $string . $tag->title . ', ';
}, '');
return trim($str, ', ');
}

Isso vai nos deixar acessar a propriedade computada $bookmark->tag_string. Vamos usar essa propriedade em inputs mais tarde. Lembre-se de adicionar a propriedade tag_string a lista _accessible
em sua entidade.
Em src/Model/Entity/Bookmark.php adicione o tag_string ao _accessible desta forma:
protected $_accessible = [
'user_id' => true,
'title' => true,
'description' => true,
'url' => true,
'user' => true,
'tags' => true,
'tag_string' => true,
];

Atualizando as views
Com a entidade atualizado, podemos adicionar uma nova entrada para as nossas tags. Nas views add e edit,
substitua tags._ids pelo seguinte:

Tutorial - Criando um Bookmarker - Parte 2

65

CakePHP Cookbook Documentation, Verso 3.x

<?= $this->Form->input('tag_string', ['type' => 'text']) ?>

Persistindo a string tag


Agora que podemos ver as tags como uma string existente, vamos querer salvar os dados tambm. Por
marcar o tag_string como acessvel, o ORM ir copiar os dados do pedido em nossa entidade. Podemos
usar um mtodo beforeSave para analisar a cadeia tag e encontrar/construir as entidades relacionadas.
Adicione o seguinte em src/Model/Table/BookmarksTable.php:
public function beforeSave($event, $entity, $options)
{
if ($entity->tag_string) {
$entity->tags = $this->_buildTags($entity->tag_string);
}
}
protected function _buildTags($tagString)
{
$new = array_unique(array_map('trim', explode(',', $tagString)));
$out = [];
$query = $this->Tags->find()
->where(['Tags.title IN' => $new]);
// Remove tags existentes da lista de novas tags.
foreach ($query->extract('title') as $existing) {
$index = array_search($existing, $new);
if ($index !== false) {
unset($new[$index]);
}
}
// Adiciona tags existentes.
foreach ($query as $tag) {
$out[] = $tag;
}
// Adiciona novas tags.
foreach ($new as $tag) {
$out[] = $this->Tags->newEntity(['title' => $tag]);
}
return $out;
}

Embora esse cdigo seja um pouco mais complicado do que o que temos feito at agora, ele ajuda a mostrar
o quo poderosa a ORM do CakePHP . Voc pode facilmente manipular resultados da consulta usando os
mtodos de Collections (Colees), e lidar com situaes em que voc est criando entidades sob demanda
com facilidade.

Terminando
Ns expandimos nossa aplicao bookmarker para lidar com situaes de autenticao e controle de autorizao/acesso bsico. Ns tambm adicionamos algumas melhorias agradveis UX, aproveitando os
66

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

recursos FormHelper e ORM.


Obrigado por dispor do seu tempo para explorar o CakePHP. Em seguida, voc pode saber mais sobre o
Models (Modelos), ou voc pode ler os /topics.

Tutorial - Criando um Blog - Parte 1


Este tutorial ir orient-lo atravs da criao de um simples blog. Faremos a instalao do CakePHP, criaremos um banco de dados e implementaremos a lgica capaz de listar, adicionar, editar e apagar postagens do
blog.
Aqui est o que voc vai precisar:
1. Um servidor web em funcionamento. Ns iremos assumir que voc esteja usando o Apache, embora
as instrues para outros servidores sejam bem similares. Talvez seja preciso alterar um pouco a
configurao do servidor, mas a maioria das pessoas pode ter o CakePHP instalado e funcionando sem
qualquer trabalho extra. Certifique-se de que voc tem o PHP 5.5.9 ou superior, e que as extenses
mbstring e intl estejam habilitadas no PHP. Caso no saiba a verso do PHP que est instalada, utilize
a funo phpinfo() ou digite php -v no seu terminal de comando.
2. Um servidor de banco de dados. Ns vamos usar o servidor MySQL neste tutorial. Voc precisa saber
o mnimo sobre SQL para ento criar um banco de dados, depois disso o CakePHP vai assumir as
rdeas. J que usaremos o MySQL, tambm certifique-se que a extenso pdo_mysql est habilitada
no PHP.
3. Conhecimento bsico sobre PHP.
Vamos comear!

Instalao do CakePHP
A maneira mais fcil de instalar o CakePHP usando Composer, um gerenciador de dependncias para o
PHP. Se trata de uma forma simples de instalar o CakePHP a partir de seu terminal ou prompt de comando.
Primeiro, voc precisa baixar e instalar o Composer. Se possuir instalada a extenso cURL do PHP, execute
o seguinte comando:
curl -s https://getcomposer.org/installer | php

Voc tambm pode baixar o arquivo composer.phar do site5 oficial do Composer.


Em seguida, basta digitar a seguinte linha de comando no seu terminal a partir do diretrio onde se localiza o
arquivo composer.phar para instalar o esqueleto da aplicao do CakePHP no diretrio [nome_do_app].
php composer.phar create-project --prefer-dist cakephp/app [nome_do_app]

A vantagem de usar o Composer que ele ir completar automaticamente um conjunto importante de tarefas,
como configurar corretamente as permisses de pastas e criar o config/app.php para voc.
5

https://getcomposer.org/download/

Tutorial - Criando um Blog - Parte 1

67

CakePHP Cookbook Documentation, Verso 3.x

H outras maneiras de instalar o CakePHP. Se voc no puder ou no quiser usar o Composer, confira a
seo Instalao.
Independentemente de como voc baixou o CakePHP, uma vez que sua instalao for concluda, a estrutura
dos diretrios deve ficar parecida com o seguinte:
/nome_do_app
/bin
/config
/logs
/plugins
/src
/tests
/tmp
/vendor
/webroot
.editorconfig
.gitignore
.htaccess
.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md

Agora pode ser um bom momento para aprender sobre como a estrutura de diretrios do CakePHP funciona:
Confira a seo Estrutura de pastas do CakePHP.

Permisses dos diretrios tmp e logs


Os diretrios tmp e logs precisam ter permisses adequadas para que possam ser alterados pelo seu servidor
web. Se voc usou o Composer na instalao, ele deve ter feito isso por voc e confirmado com uma
mensagem Permissions set on <folder>. Se voc ao invs disso, recebeu uma mensagem de erro ou se
quiser faz-lo manualmente, a melhor forma seria descobrir por qual usurio o seu servidor web executado
(<?= whoami; ?>) e alterar o proprietrio desses dois diretrios para este usurio. Os comandos
finais a serem executados (em *nix) podem ser algo como:
chown -R www-data tmp
chown -R www-data logs

Se por alguma razo o CakePHP no puder escrever nesses diretrios, voc ser informado por uma advertncia enquanto no estiver em modo de produo.
Embora no seja recomendado, se voc incapaz de redefinir as permisses do seu servidor web, voc
pode simplesmente alterar as permisses de gravao diretamente nos diretrios, executando os seguintes
comandos:
chmod 777 -R tmp
chmod 777 -R logs

68

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Criando o banco de dados do Blog


Em seguida, vamos configurar o banco de dados para o nosso blog. Se voc ainda no tiver feito isto, crie
um banco de dados vazio para usar neste tutorial, com um nome de sua escolha, por exemplo, cake_blog.
Agora, vamos criar uma tabela para armazenar nossos artigos:
/* Primeiro, criamos a tabela articles: */
CREATE TABLE articles (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(50),
body TEXT,
created DATETIME DEFAULT NULL,
modified DATETIME DEFAULT NULL
);

Ns vamos tambm inserir alguns artigos para usarmos em nossos testes. Execute os seguintes comandos
SQL em seu banco de dados:
/* Ento inserimos articles para testes: */
INSERT INTO articles (title,body,created)
VALUES ('The title', 'This is the article body.', NOW());
INSERT INTO articles (title,body,created)
VALUES ('A title once again', 'And the article body follows.', NOW());
INSERT INTO articles (title,body,created)
VALUES ('Title strikes back', 'This is really exciting! Not.', NOW());

Os nomes de tabelas e colunas que usamos no foram arbitrrias. Usando convenes de nomenclatura do
CakePHP, podemos alavancar o desenvolvimento e acelerar a configurao do framework. O CakePHP
flexvel o suficiente para acomodar at mesmo esquemas de banco de dados legados inconsistentes, mas
aderir s convenes vai lhe poupar tempo.

Configurando o banco de dados do Blog


Em seguida, vamos dizer ao CakePHP onde nosso banco de dados est e como se conectar a ele. Para
muitos, esta ser a primeira e ltima vez que ser necessrio configurar algo.
A configurao bem simples e objetiva: basta alterar os valores no array Datasources.default localizado no arquivo config/app.php, pelos valores que se aplicam sua configurao. Um exemplo completo
de configuraes deve se parecer como o seguinte:
return [
// Mais configuraes acima.
'Datasources' => [
'default' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'persistent' => false,
'host' => 'localhost',
'username' => 'cakephp',
'password' => 'AngelF00dC4k3~',
'database' => 'cake_blog',
'encoding' => 'utf8',

Tutorial - Criando um Blog - Parte 1

69

CakePHP Cookbook Documentation, Verso 3.x

'timezone' => 'UTC',


'cacheMetadata' => true,
],
],
// Mais configuraes abaixo.
];

Depois de salvar o arquivo config/app.php, voc deve notar a mensagem CakePHP is able to connect to the
database ao acessar o Blog pelo seu navegador.
Nota:
Uma cpia do arquivo de configurao padro do CakePHP pode ser encontrada em config/app.default.php.

Configuraes opcionais
H alguns outros itens que podem ser configurados. Muitos desenvolvedores completam esta lista de itens,
mas os mesmos no so obrigatrios para este tutorial. Um deles definir uma sequncia personalizada (ou
salt) para uso em hashes de segurana.
A sequncia personalizada (ou salt) utilizada para gerar hashes de segurana. Se voc utilizou o Composer,
ele cuidou disso para voc durante a instalao. Apesar disso, voc precisa alterar a sequncia personalizada
padro editando o arquivo config/app.php. No importa qual ser o novo valor, somente dever ser algo
difcil de descobrir:
'Security' => [
'salt' => 'algum valor longo contendo uma mistura aleatria de valores.',
],

Observao sobre o mod_rewrite


Ocasionalmente, novos usurios iro se atrapalhar com problemas de mod_rewrite. Por exemplo, se a pgina
de boas vindas do CakePHP parecer estranha (sem imagens ou estilos CSS). Isto provavelmente significa
que o mod_rewrite no est funcionando em seu servidor. Por favor, verifique a seo Reescrita de URL
para obter ajuda e resolver qualquer problema relacionado.
Agora continue o tutorial em Tutorial - Criando um Blog - Parte 2 e inicie a construo do seu Blog com o
CakePHP.

Tutorial - Criando um Blog - Parte 2


Criando o model
Aps criar um model (modelo) no CakePHP, ns teremos a base necessria para interagirmos com o banco
de dados e executar operaes.

70

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Os arquivos de classes, correspondentes aos models, no CakePHP esto divididos entre os objetos Table e
Entity. Objetos Table provm acesso coleo de entidades armazenada em uma tabela e so alocados
em src/Model/Table.
O arquivo que criaremos dever ficar salvo em src/Model/Table/ArticlesTable.php:
// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;
class ArticlesTable extends Table
{
public function initialize(array $config)
{
$this->addBehavior('Timestamp');
}
}

Convenes de nomenclatura so muito importantes no CakePHP. Ao nomear nosso objeto como


ArticlesTable, o CakePHP automaticamente deduz que o mesmo utilize o ArticlesController
e seja relacionado tabela articles.
Nota: O CakePHP criar automaticamente um objeto model se no puder encontrar um arquivo correspondente em src/Model/Table. Se voc nomear incorretamente seu arquivo (isto , artciclestable.php ou
ArticleTable.php), o CakePHP no reconhecer suas definies e usar o model gerado como alternativa.
Para mais informaes sobre models, como callbacks e validao, visite o captulo Models (Modelos) do
manual.
Nota: Se voc completou a primeira parte do tutorial e criou a tabela articles, voc pode tomar
proveito da capacidade de gerao de cdigo do bake atravs do console do CakePHP para criar o model
ArticlesTable:
bin/cake bake model Articles

Para mais informaes sobre o bake e suas caractersticas relacionadas a gerao de cdigo, visite o captulo
Gerao de cdigo com o Bake do manual.

Criando o controller
A seguir, criaremos um controller (controlador) para nossos artigos. O controller responsvel pela lgica de
interao da aplicao. o lugar onde voc utilizar as regras contidas nos models e executar tarefas relacionadas aos artigos. Criaremos um arquivo chamado ArticlesController.php no diretrio src/Controller:
// src/Controller/ArticlesController.php
namespace App\Controller;

Tutorial - Criando um Blog - Parte 2

71

CakePHP Cookbook Documentation, Verso 3.x

class ArticlesController extends AppController


{
}

Agora, vamos adicionar uma action (ao) ao nosso controller. Actions frequentemente, representam uma funo ou interface em uma aplicao. Por exemplo, quando os usurios requisitarem
www.example.com/articles/index (sendo o mesmo que www.example.com/articles/), eles esperam ver uma
lista de artigos:
// src/Controller/ArticlesController.php
namespace App\Controller;
class ArticlesController extends AppController
{
public function index()
{
$articles = $this->Articles->find('all');
$this->set(compact('articles'));
}
}

Ao definir a funo index() em nosso ArticlesController, os usurios podem acess-la requisitando www.example.com/articles/index. Similarmente, se definssemos uma funo chamada foobar(),
os usurios poderiam acess-la em www.example.com/articles/foobar.
Aviso: Vocs podem ser tentados a nomear seus controllers e actions para obter uma certa URL. Resista
a essa tentao. Siga as Convenes do CakePHP e crie nomes de action legveis e compreensveis. Voc
pode mapear URLs para o seu cdigo utilizando Roteamento.
A instruo na action usa set() para passar dados do controller para a view. A varivel definida como
articles, sendo igual ao valor retornado do mtodo find(all) do objeto ArticlesTable.
Nota: Se voc completou a primeira parte do tutorial e criou a tabela articles, voc pode tomar
proveito da capacidade de gerao de cdigo do bake atravs do console do CakePHP para criar o controller
ArticlesController:
bin/cake bake controller Articles

Para mais informaes sobre o bake e suas caractersticas sobre gerao de cdigo, visite o captulo Gerao
de cdigo com o Bake do manual.

Criando as views
Agora que ns temos os dados fluindo pelo nosso model, e nossa lgica da aplicao definida em nosso
controller, vamos criar uma view (visualizao) para a action index().
As views do CakePHP so camadas de apresentao que se encaixam nos layouts da aplicao. Para a
maioria das aplicaes, elas so uma mescla entre HTML e PHP, mas tambm podem ser distribudas como
72

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

XML, CSV, ou ainda dados binrios.


Um layout um conjunto de cdigos encontrado ao redor das views. Mltiplos layouts podem
ser definidos, e voc pode alterar entre eles, mas agora, vamos usar o default, localziado em
src/Template/Layout/default.ctp.
Lembra que na ltima sesso atribumos a varivel articles view usando o mtodo set()? Isso levar a
coleo de objetos gerada pela query a ser invocada numa iterao foreach.
Arquivos de template do CakePHP so armazenados em src/Template dentro de uma pasta com o nome do
controller correspondente (ns teremos que criar a pasta Articles nesse caso). Para distribuir os dados de
artigos em uma tabela, precisamos criar uma view assim:
<!-- File: src/Template/Articles/index.ctp -->
<h1>Blog articles</h1>
<table>
<tr>
<th>Id</th>
<th>Title</th>
<th>Created</th>
</tr>

<!-- Aqui onde iremos iterar nosso objeto de solicitao $articles, exibindo informa
<?php foreach ($articles as $article): ?>
<tr>
<td><?= $article->id ?></td>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
</tr>
<?php endforeach; ?>
</table>

Voc deve ter notado o uso de um objeto chamado $this->Html, uma instncia da classe
Cake\View\Helper\HtmlHelper do CakePHP. O CakePHP vem com um conjunto de view helpers
que simplificam tarefas como gerar links e formulrios. Voc pode aprender como us-los em Helpers (Facilitadores), mas aqui importante notar que o mtodo link() ir gerar um link HTML com o referido
ttulo (primeiro parmetro) e URL (segundo parmetro).
Quando se especifca URLs no CakePHP, recomendado o uso do formato de array. Isto ser melhor
explicado posteriormente na seo Rotas. Usando o formato de array para URLs, voc toma vantagem das
capacidades de roteamento reverso do CakePHP. Voc tambm pode especificar URLs relativas a base da
aplicao com o formato /controller/action/param1/param2 ou usar named routes.
Neste ponto, voc pode visitar http://www.example.com/articles/index no seu navegador. Voc deve ver sua
view corretamente formatada listando os artigos.
Se voc clicar no link do ttulo de um artigo listado, provavelmente ser informado pelo CakePHP que a
action ainda no foi definida, ento vamos cri-la no ArticlesController agora:
Tutorial - Criando um Blog - Parte 2

73

CakePHP Cookbook Documentation, Verso 3.x

// src/Controller/ArticlesController.php
namespace App\Controller;
class ArticlesController extends AppController
{
public function index()
{
$this->set('articles', $this->Articles->find('all'));
}
public function view($id = null)
{
$article = $this->Articles->get($id);
$this->set(compact('article'));
}
}

O uso do set() deve parecer familiar. Repare que voc est usando get() ao invs de find(all)
porqu ns queremos a informao de apenas um artigo.
Repare que nossa action recebe um parmetro: o ID do artigo que gostariamos de visualizar. Esse parmetro
entregue para a action atravs da URL solicitada. Se o usurio requisitar /articles/view/3, ento o
valor 3 passado como $id para a action.
Ao usar a funo get(), fazemos tambm algumas verificaes para garantir que o usurio realmente
est acessando um registro existente , se no ou se o $id for indefinido, a funo ir lanar uma
NotFoundException.
Agora vamos criar a view para nossa action em src/Template/Articles/view.ctp
<!-- File: src/Template/Articles/view.ctp -->
<h1><?= h($article->title) ?></h1>
<p><?= h($article->body) ?></p>
<p><small>Criado: <?= $article->created->format(DATE_RFC850) ?></small></p>

Verifique se est tudo funcionando acessando os links em /articles/index ou manualmente solicite a


visualizao de um artigo acessando articles/view/{id}. Lembre-se de substituir {id} por um id
de um artigo.

Adicionando artigos
Primeiro, comece criando a action add() no ArticlesController:
// src/Controller/ArticlesController.php
namespace App\Controller;
use App\Controller\AppController;

74

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

class ArticlesController extends AppController


{
public function initialize()
{
parent::initialize();
$this->loadComponent('Flash'); // Inclui o FlashComponent
}
public function index()
{
$this->set('articles', $this->Articles->find('all'));
}
public function view($id)
{
$article = $this->Articles->get($id);
$this->set(compact('article'));
}
public function add()
{
$article = $this->Articles->newEntity();
if ($this->request->is('post')) {
$article = $this->Articles->patchEntity($article, $this->request->data);
if ($this->Articles->save($article)) {
$this->Flash->success(__('Seu artigo foi salvo.'));
return $this->redirect(['action' => 'index']);
}
$this->Flash->error(__('No possvel adicionar o seu artigo.'));
}
$this->set('article', $article);
}
}

Nota: Voc precisa incluir o Flash component em qualquer controller que v us-lo. Se necessrio,
inclua no AppController e assim o FlashComponent estar disponvel para todos os controllers da
aplicao.
A action add() checa se o mtodo HTTP da solicitao foi POST, e ento tenta salvar os dados utilizando
o model Articles. Se por alguma razo ele no salvar, apenas renderiza a view. Isto nos d a chance de exibir
erros de validao ou outros alertas.
Cada requisio do CakePHP instancia um objeto Request que acessvel usando $this->request.
O objeto contm informaes teis sobre a requisio que foi recebida e pode ser usado para controlar
o fluxo de sua aplicao. Nesse caso, ns usamos o mtodo Cake\Network\Request::is() para
checar se a requisio do tipo HTTP POST.
Quando se usa um formulrio para postar dados, essa informao fica disponvel em
$this->request->data. Voc pode usar as funes pr() ou debug() caso queira verificar
esses dados.
Tutorial - Criando um Blog - Parte 2

75

CakePHP Cookbook Documentation, Verso 3.x

Usamos os mtodos success() e error() do FlashComponent para definir uma mensagem que
ser armazenada numa varivel de sesso. Esses mtodos so gerados usando os recursos de mtodos
mgicos6 do PHP. Mensagens flash sero exibidas na pgina aps um redirecionamento. No layout ns
temos <?= $this->Flash->render() ?> que exibe a mensagem e limpa a varivel de sesso. A
funo do controller Cake\Controller\Controller::redirect redireciona para qualquer outra
URL. O parmetro [action => index] corresponde a URL /articles, isto , a action index()
do ArticlesController. Voc pode consultar a funo Cake\Routing\Router::url() na
API7 e checar os formatos a partir dos quais voc pode montar uma URL.
Chamar o mtodo save() vai checar erros de validao e abortar o processo caso os encontre. Ns vamos
abordar como esses erros so tratados nas sesses a seguir.

Validando artigos
O CakePHP torna mais prtica e menos montona a validao de dados de formulrio.
Para tirar proveito dos recursos de validao, voc vai precisar usar o Form helper em suas views.
O Cake\View\Helper\FormHelper est disponvel por padro em todas as views pelo uso do
$this->Form.
Segue a view correspondente a action add:
<!-- File: src/Template/Articles/add.ctp -->
<h1>Add Article</h1>
<?php
echo $this->Form->create($article);
echo $this->Form->input('title');
echo $this->Form->input('body', ['rows' => '3']);
echo $this->Form->button(__('Salvar artigo'));
echo $this->Form->end();
?>

Ns usamos o FormHelper para gerar a tag de abertura HTML de um formulrio. Segue o HTML gerado
por $this->Form->create():
<form method="post" action="/articles/add">

Se create() chamado sem parmetros fornecidos, assume-se a construo de um formulrio que submete dados via POST para a action add() (ou edit() no caso de um id estar includo nos dados do
formulrio).
O mtodo $this->Form->input() usado para criar elementos do formulrio do mesmo nome. O
primeiro parmetro diz ao CakePHP qual o campo correspondente, e o segundo parmetro permite que
voc especifique um vasto array de opes, nesse, o nmero de linhas para o textarea. input() vai gerar
diferentes elementos de formulrios baseados no tipo de campo especificado no model.
O $this->Form->end() fecha o formulrio, entregando tambm elementos ocultos caso a preveno
contra CSRF/Form Tampering esteja habilitada.
6
7

76

http://php.net/manual/en/language.oop5.overloading.php#object.call
http://api.cakephp.org

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Agora vamos voltar e atualizar nossa view src/Template/Articles/index.ctp para incluir um novo link.
Antes do <table>, adicione a seguinte linha:
<?= $this->Html->link('Adicionar artigo', ['action' => 'add']) ?>

Voc deve estar se perguntando: como eu digo ao CakePHP meus critrios de validao? Regras de validao so definidas no model. Vamos fazer alguns ajustes no nosso model:
// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\Validation\Validator;
class ArticlesTable extends Table
{
public function initialize(array $config)
{
$this->addBehavior('Timestamp');
}
public function validationDefault(Validator $validator)
{
$validator
->notEmpty('title')
->notEmpty('body');
return $validator;
}
}

O mtodo validationDefault() diz ao CakePHP como validar seus dados quando o mtodo save()
for solicitado. Aqui, estamos especificando que tanto o campo body quanto title no devem estar vazios.
O CakePHP possui muitos recursos de validao e um bom nmero de regras pr-determinadas (nmero
de cartes, endereos de email, etc), alm de flexibilidade para adicionar regras de validao customizadas.
Para mais informaes sobre configurao de validaes, visite a documentao em Validao.
Agora que suas regras de validao esto definidas, tente adicionar um artigo sem definir o
campo title e body para ver como a validao funciona. Desde que tenhamos usado o mtodo
Cake\View\Helper\FormHelper::input() do FormHelper para criar nossos elementos, nossas mensagens de alerta da validao sero exibidas automaticamente.

Editando artigos
Edio, a vamos ns! Voc j um profissional do CakePHP agora, ento possivelmente detectou um
padro... Cria-se a action e ento a view. Aqui segue a action edit() que dever ser inserida no
ArticlesController:
// src/Controller/ArticlesController.php
public function edit($id = null)

Tutorial - Criando um Blog - Parte 2

77

CakePHP Cookbook Documentation, Verso 3.x

{
$article = $this->Articles->get($id);
if ($this->request->is(['post', 'put'])) {
$this->Articles->patchEntity($article, $this->request->data);
if ($this->Articles->save($article)) {
$this->Flash->success(__('Seu artigo foi atualizado.'));
return $this->redirect(['action' => 'index']);
}
$this->Flash->error(__('Seu artigo no pde ser atualizado.'));
}
$this->set('article', $article);
}

Essa action primeiramente certifica-se que o registro apontado existe. Se o parmetro $id no foi passado
ou se o registro inexistente, uma NotFoundException lanada pelo ErrorHandler do CakePHP.
Em seguida, a action verifica se a requisio POST ou PUT e caso seja, os dados so usados para atualizar a entidade de artigo em questo ao usar o mtodo patchEntity(). Ento finalmente usamos o
ArticlesTable para salvar a entidade.
Segue a view correspondente a action edit:
<!-- File: src/Template/Articles/edit.ctp -->
<h1>Edit
<?php
echo
echo
echo
echo
echo
?>

Article</h1>
$this->Form->create($article);
$this->Form->input('title');
$this->Form->input('body', ['rows' => '3']);
$this->Form->button(__('Salvar artigo'));
$this->Form->end();

Essa view retorna o formulrio de edio com os dados populados, juntamente com qualquer mensagem de
erro proveniente de validaes.
O CakePHP ir determinar se o save() vai inserir ou atualizar um registro baseado nos dados da entidade.
Voc pode atualizar sua view index com os links para editar artigos:
<!-- File: src/Template/Articles/index.ctp

(edit links added) -->

<h1>Blog articles</h1>
<p><?= $this->Html->link("Adicionar artigo", ['action' => 'add']) ?></p>
<table>
<tr>
<th>Id</th>
<th>Ttulo</th>
<th>Criado</th>
<th>Aes</th>
</tr>
<!-- Aqui onde iremos iterar nosso objeto de solicitao $articles, exibindo informaes

78

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

<?php foreach ($articles as $article): ?>


<tr>
<td><?= $article->id ?></td>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Html->link('Editar', ['action' => 'edit', $article->id]) ?>
</td>
</tr>
<?php endforeach; ?>
</table>

Deletando artigos
A seguir, vamos criar uma forma de deletar artigos.
ArticlesController:

Comece com uma action delete() no

// src/Controller/ArticlesController.php
public function delete($id)
{
$this->request->allowMethod(['post', 'delete']);
$article = $this->Articles->get($id);
if ($this->Articles->delete($article)) {
$this->Flash->success(__('O artigo com id: {0} foi deletado.', h($id)));
return $this->redirect(['action' => 'index']);
}
}

Essa lgica deleta o artigo especificado pelo $id e usa $this->Flash->success() para exibir uma
mensagem de confirmao aps o redirecionamento para /articles. Tentar excluir um registro usando
uma requisio GET, far com que o allowMethod() lance uma exceo. Excees so capturadas pelo
gerenciador de excees do CakePHP e uma pgina de erro exibida. Existem muitos Exceptions embutidos
que podem indicar variados erros HTTP que sua aplicao possa precisar.
Por estarmos executando apenas lgica e redirecionando, essa action no tem uma view. Vamos atualizar
nossa view index com links para excluir artigos:
<!-- File: src/Template/Articles/index.ctp (delete links added) -->
<h1>Blog articles</h1>
<p><?= $this->Html->link('Adicionar artigo', ['action' => 'add']) ?></p>
<table>
<tr>
<th>Id</th>

Tutorial - Criando um Blog - Parte 2

79

CakePHP Cookbook Documentation, Verso 3.x

<th>Ttulo</th>
<th>Criado</th>
<th>Aes</th>
</tr>

<!-- Aqui onde iremos iterar nosso objeto de solicitao $articles, exibindo informa
<?php foreach ($articles as $article): ?>
<tr>
<td><?= $article->id ?></td>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Form->postLink(
'Deletar',
['action' => 'delete', $article->id],
['confirm' => 'Tem certeza?'])
?>
<?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
</td>
</tr>
<?php endforeach; ?>
</table>

Usar View\Helper\FormHelper::postLink() vai criar um link que usa JavaScript para criar uma
requisio POST afim de deletar um artigo.
Aviso: Permitir que registros sejam deletados usando requisies GET perigoso, pois rastreadores na
web podem acidentalmente deletar todo o seu contedo.

Nota: Esse cdigo da view tambm usa o FormHelper para confirmar a action atravs de JavaScript.

Rotas
Para muitos o roteamento padro do CakePHP funciona bem o suficiente. Desenvolvedores que consideram
facilidade de uso e SEO iro apreciar a forma como o CakePHP mapeia determinadas URLs para actions
especficas. Vamos realizar uma pequena mudana nas rotas neste tutorial.
Para mais informaes sobre tcnicas avanadas de roteamento, visite Connecting Routes.
Por padro, o CakePHP responde a uma requisio pela raz do seu site usando o PagesController, ao
renderizar uma view chamada home.ctp. Alternativamente, ns vamos substituir esse comportamento pelo
ArticlesController ao criar uma regra de roteamento.
A configurao de rotas do CakePHP pode ser encontrada em config/routes.php. Voc deve comentar ou

80

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

remover a linha que define o roteamento padro:


$routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);

Essa linha conecta a URL / com a pgina padro do CakePHP. Ns queremos que ela conecte-se ao nosso
prprio controller, ento a substitua por esta:
$routes->connect('/', ['controller' => 'Articles', 'action' => 'index']);

Isso ir conectar requisies por / a action index() do nosso ArticlesController


Nota: O CakePHP aproveita-se do uso de roteamento reverso. Se com a rota anterior definida voc
gerar um link com a seguinte estrutura de array: [controller => Articles, action
=> index], a URL resultante ser /. Portanto, uma boa ideia sempre usar arrays para URLs, pois
assim suas rotas definem o endereo gerado e certificam-se que os links apontem sempre para o mesmo
lugar.

Concluso
Simples, no ? Tenha em mente que esse foi um tutorial bsico. O CakePHP tem muito mais recursos a
oferecer. No abordamos outros tpicos aqui para manter a simplicidade. Use o restante do manual como
um guia para criar aplicaes mais ricas.
Agora que voc criou uma aplicao bsica no CakePHP, voc pode continuar no Tutorial - Criando
um Blog - Parte 3, ou comear seu prprio projeto. Voc tambm pode folhear os /topics ou a API
<http://api.cakephp.org/3.0> para aprender mais sobre o CakePHP.
Se voc precisar de ajuda, h muitas formas de conseguir, por favor, visite a pgina Onde Conseguir Ajuda
e bem-vindo(a) ao CakePHP!
Leitura complementar
Existem tpicos comuns que as pessoas que esto estudando o CakePHP normalmente visitam a seguir:
1. Layouts: Customizando o layout da aplicao
2. Elements: Incluso e reutilizao de elementos na view
3. Gerao de cdigo com o Bake: Gerando cdigo CRUD
4. Tutorial - Criando um Blog - Autenticao e Autorizao: Tutorial de autorizao e autenticao

Tutorial - Criando um Blog - Parte 3


Criar uma arvore de Categoria
Vamos continuar o nosso aplicativo de blog e imaginar que queremos categorizar os nossos artigos. Queremos que as categorias sejam ordenadas, e para isso, vamos usar o comportamento de rvore para nos ajudar
a organizar as categorias.
Tutorial - Criando um Blog - Parte 3

81

CakePHP Cookbook Documentation, Verso 3.x

Mas primeiro, precisamos modificar nossas tabelas.

Migrao de Plugin
Ns vamos usar o plugin de migraes para criar uma tabela em nosso banco de dados. Se voc tem
a tabela articles no seu banco de dados, apague. Agora abra o arquivo composer.json do seu aplicativo.
Normalmente, voc veria que o plugin de migrao j est requisitando. Se no, addicione atrves da
execuo:
composer require cakephp/migrations:~1.0

O plugin de migrao agora est na pasta de sua aplicao.


Tambm,
Plugin::load(Migrations); para o arquivo bootstrap.php do seu aplicativo.

adicionar

Uma vez que o plugin est carregado, execute o seguinte comando para criar um arquivo de migrao:

bin/cake bake migration CreateArticles title:string body:text category_id:integer created m

Um arquivo de migrao ser gerado na pasta /config/Migrations com o seguinte:


<?php
use Migrations\AbstractMigration;
class CreateArticlesTable extends AbstractMigration
{
public function change()
{
$table = $this->table('articles');
$table->addColumn('title', 'string', [
'default' => null,
'limit' => 255,
'null' => false,
]);
$table->addColumn('body', 'text', [
'default' => null,
'null' => false,
]);
$table->addColumn('category_id', 'integer', [
'default' => null,
'limit' => 11,
'null' => false,
]);
$table->addColumn('created', 'datetime', [
'default' => null,
'null' => false,
]);
$table->addColumn('modified', 'datetime', [
'default' => null,
'null' => false,
]);
$table->create();

82

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

}
}

Executar outro comando para criar uma tabela de categorias. Se voc precisar especificar um comprimento
de campo, voc pode faz-lo dentro de colchetes no tipo de campo, ou seja:

bin/cake bake migration CreateCategories parent_id:integer lft:integer[10] rght:integer[10]

Isso ir gerar o seguinte arquivo no config/Migrations:


<?php
use Migrations\AbstractMigration;
class CreateCategoriesTable extends AbstractMigration
{
public function change()
{
$table = $this->table('categories');
$table->addColumn('parent_id', 'integer', [
'default' => null,
'limit' => 11,
'null' => false,
]);
$table->addColumn('lft', 'integer', [
'default' => null,
'limit' => 10,
'null' => false,
]);
$table->addColumn('rght', 'integer', [
'default' => null,
'limit' => 10,
'null' => false,
]);
$table->addColumn('name', 'string', [
'default' => null,
'limit' => 100,
'null' => false,
]);
$table->addColumn('description', 'string', [
'default' => null,
'limit' => 255,
'null' => false,
]);
$table->addColumn('created', 'datetime', [
'default' => null,
'null' => false,
]);
$table->addColumn('modified', 'datetime', [
'default' => null,
'null' => false,
]);
$table->create();
}

Tutorial - Criando um Blog - Parte 3

83

CakePHP Cookbook Documentation, Verso 3.x

Agora que os arquivos de migrao esto criadas, voc pode edit-los antes de criar suas tabelas. Precisamos
mudar o null => false para o campo parent_id com null => true porque uma categoria de nvel
superior tem null no parent_id
Execute o seguinte comando para criar suas tabelas:
bin/cake migrations migrate

Modificando as Tabelas
Com nossas tabelas configuradas, agora podemos nos concentrar em categorizar os nossos artigos.
Supomos que voc j tem os arquivos (Tabelas, controladores e modelos dos artigos) da parte 2. Ento
vamos adicionar as referncias a categorias.
Precisamos associar os artigos e categorias juntos
src/Model/Table/ArticlesTable.php e adicione o seguinte:

nas

tabelas.

Abra

arquivo

// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;
class ArticlesTable extends Table
{
public function initialize(array $config)
{
$this->addBehavior('Timestamp');
// Just add the belongsTo relation with CategoriesTable
$this->belongsTo('Categories', [
'foreignKey' => 'category_id',
]);
}
}

Gerar cdigo esqueleto por categorias


Crie todos os arquivos pelo comando bake:
bin/cake bake model Categories
bin/cake bake controller Categories
bin/cake bake template Categories

A ferramenta bake criou todos os seus arquivos em um piscar de olhos. Voc pode fazer uma leitura rpida
se quiser familiarizar como o CakePHP funciona.
Nota: Se voc estiver no Windows lembre-se de usar em vez de /.

84

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

Voc
vai
precisar
editar
src/Template/Categories/edit.ctp:

seguinte

em

src/Template/Categories/add.ctp

echo $this->Form->input('parent_id', [
'options' => $parentCategories,
'empty' => 'No parent category'
]);

Anexar rvore de compartamento para CategoriesTable


O TreeBehavior ajuda voc a gerenciar as estruturas de rvore hierrquica na tabela do banco de dados. Usa
a lgica MPTT para gerenciar os dados. Estruturas de rvore MPTT so otimizados para l, o que muitas
vezes torna uma boa opo para aplicaes pesadas, como ler blogs.
Se voc abrir o arquivo src/Model/Table/CategoriesTable.php, voc ver que o TreeBehavior foi anexado a
sua CategoriesTable no mtodo initialize(). Bake acrescenta esse comportamento para todas as tabelas que
contm lft e colunas rght:
$this->addBehavior('Tree');

Com o TreeBehavior anexado voc vai ser capaz de acessar alguns recursos como a reordenao das categorias. Vamos ver isso em um momento.
Mas, por agora, voc tem que remover as seguintes entradas em seus Categorias de adicionar e editar arquivos de modelo:
echo $this->Form->input('lft');
echo $this->Form->input('rght');

Alm disso, voc deve desabilitar ou remover o requirePresence do validador, tanto para a lft e rght nas
colunas em seu modelo CategoriesTable:
public function validationDefault(Validator $validator)
{
$validator
->add('id', 'valid', ['rule' => 'numeric'])
->allowEmpty('id', 'create');
$validator
->add('lft', 'valid', ['rule' => 'numeric'])
//
->requirePresence('lft', 'create')
->notEmpty('lft');
$validator
->add('rght', 'valid', ['rule' => 'numeric'])
//
->requirePresence('rght', 'create')
->notEmpty('rght');
}

Esses campos so automaticamente gerenciados pelo TreeBehavior quando uma categoria salvo.
Usando seu navegador, adicione algumas novas categorias usando os /yoursite/categories/add
ao do controlador.
Tutorial - Criando um Blog - Parte 3

85

CakePHP Cookbook Documentation, Verso 3.x

Reordenar categorias com TreeBahavior


Em seu arquivo de modelo de ndices de categorias, voc pode listar as categorias e reorden-los.
Vamos modificar o mtodo de ndice em sua CategoriesController.php e adicionar moveUp() e moveDown()
para ser capaz de reordenar as categorias na rvore:
class CategoriesController extends AppController
{
public function index()
{
$categories = $this->Categories->find()
->order(['lft' => 'ASC']);
$this->set(compact('categories'));
$this->set('_serialize', ['categories']);
}
public function moveUp($id = null)
{
$this->request->allowMethod(['post', 'put']);
$category = $this->Categories->get($id);
if ($this->Categories->moveUp($category)) {
$this->Flash->success('The category has been moved Up.');
} else {
$this->Flash->error('The category could not be moved up. Please, try again.');
}
return $this->redirect($this->referer(['action' => 'index']));
}

public function moveDown($id = null)


{
$this->request->allowMethod(['post', 'put']);
$category = $this->Categories->get($id);
if ($this->Categories->moveDown($category)) {
$this->Flash->success('The category has been moved down.');
} else {
$this->Flash->error('The category could not be moved down. Please, try again.')
}
return $this->redirect($this->referer(['action' => 'index']));
}
}

Em src/Template/Categories/index.ctp substituir o contedo existente com:


<div class="actions large-2 medium-3 columns">
<h3><?= __('Actions') ?></h3>
<ul class="side-nav">
<li><?= $this->Html->link(__('New Category'), ['action' => 'add']) ?></li>
</ul>
</div>
<div class="categories index large-10 medium-9 columns">
<table cellpadding="0" cellspacing="0">
<thead>
<tr>

86

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

<th>Id</th>
<th>Parent Id</th>
<th>Lft</th>
<th>Rght</th>
<th>Name</th>
<th>Description</th>
<th>Created</th>
<th class="actions"><?= __('Actions') ?></th>
</tr>
</thead>
<tbody>
<?php foreach ($categories as $category): ?>
<tr>
<td><?= $category->id ?></td>
<td><?= $category->parent_id ?></td>
<td><?= $category->lft ?></td>
<td><?= $category->rght ?></td>
<td><?= h($category->name) ?></td>
<td><?= h($category->description) ?></td>
<td><?= h($category->created) ?></td>
<td class="actions">
<?= $this->Html->link(__('View'), ['action' => 'view', $category->id]) ?>
<?= $this->Html->link(__('Edit'), ['action' => 'edit', $category->id]) ?>
<?= $this->Form->postLink(__('Delete'), ['action' => 'delete', $category->i
<?= $this->Form->postLink(__('Move down'), ['action' => 'moveDown', $catego
<?= $this->Form->postLink(__('Move up'), ['action' => 'moveUp', $category->
</td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
</div>

Modificando o ArticlesController
Em nossa ArticlesController, vamos obter a lista de todas as categorias. Isto ir permitir-nos para escolher
uma categoria para um artigo ao criar ou editar ele:
// src/Controller/ArticlesController.php
namespace App\Controller;
use Cake\Network\Exception\NotFoundException;
class ArticlesController extends AppController
{
// ...
public function add()
{
$article = $this->Articles->newEntity();
if ($this->request->is('post')) {
$article = $this->Articles->patchEntity($article, $this->request->data);

Tutorial - Criando um Blog - Parte 3

87

CakePHP Cookbook Documentation, Verso 3.x

if ($this->Articles->save($article)) {
$this->Flash->success(__('Your article has been saved.'));
return $this->redirect(['action' => 'index']);
}
$this->Flash->error(__('Unable to add your article.'));
}
$this->set('article', $article);
// Just added the categories list to be able to choose
// one category for an article
$categories = $this->Articles->Categories->find('treeList');
$this->set(compact('categories'));
}
}

Modificando os artigos Templates


O artigo adicionado deveria se parecer como isto:
<!-- File: src/Template/Articles/add.ctp -->
<h1>Add Article</h1>
<?php
echo $this->Form->create($article);
// just added the categories input
echo $this->Form->input('category_id');
echo $this->Form->input('title');
echo $this->Form->input('body', ['rows' => '3']);
echo $this->Form->button(__('Save Article'));
echo $this->Form->end();

Quando voc vai para o endereo /yoursite/articles/add voc deve ver uma lista de categorias
para escolher.

Tutorial - Criando um Blog - Autenticao e Autorizao


Continuando com o exemplo de Tutorial - Criando um Blog - Parte 1, imagine que queramos garantir o
acesso a certas URLs, com base no usurio logado. Temos tambm uma outra exigncia: permitir que o
nosso blog para tenha vrios autores que podem criar, editar e excluir seus prprios artigos, e bloquear para
que outros autores no faam alteraes nos artigos que no lhes pertencem.

Criando todo o cdigo relacionado ao Usurio


Primeiro, vamos criar uma nova tabela no banco de dados do blog para armazenar dados de nossos usurios:
CREATE TABLE users (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50),

88

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

password VARCHAR(255),
role VARCHAR(20),
created DATETIME DEFAULT NULL,
modified DATETIME DEFAULT NULL
);

Respeitado as convenes do CakePHP para nomear tabelas, mas tambm aproveitando de outras conveno: Usando as colunas username e password da tabela de usurios, CakePHP ser capaz de configurar automaticamente a maioria das coisas para ns, na implementao do login do usurio.
O prximo passo criar a nossa classe UsersTable, responsvel por encontrar, salvar e validar os dados do
usurio:
// src/Model/Table/UsersTable.php
namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\Validation\Validator;
class UsersTable extends Table
{
public function validationDefault(Validator $validator)
{
return $validator
->notEmpty('username', 'Usurio necessrio')
->notEmpty('password', 'Senha necessria')
->notEmpty('role', 'Funo necessria')
->add('role', 'inList', [
'rule' => ['inList', ['admin', 'author']],
'message' => 'Por favor informe uma funo vlida'
]);
}
}

Vamos tambm criar o nosso UsersController. O contedo a seguir corresponde a partes de uma classe
UsersController bsica gerado atrves do utilitrio de gerao de cdigo bake fornecido com CakePHP:
// src/Controller/UsersController.php
namespace App\Controller;
use App\Controller\AppController;
use Cake\Event\Event;
class UsersController extends AppController
{
public function beforeFilter(Event $event)
{
parent::beforeFilter($event);
$this->Auth->allow('add');
}

Tutorial - Criando um Blog - Autenticao e Autorizao

89

CakePHP Cookbook Documentation, Verso 3.x

public function index()


{
$this->set('users', $this->Users->find('all'));
}
public function view($id)
{
$user = $this->Users->get($id);
$this->set(compact('user'));
}
public function add()
{
$user = $this->Users->newEntity();
if ($this->request->is('post')) {
$user = $this->Users->patchEntity($user, $this->request->data);
if ($this->Users->save($user)) {
$this->Flash->success(__('O usurio foi salvo.'));
return $this->redirect(['action' => 'add']);
}
$this->Flash->error(__('No possvel adicionar o usurio.'));
}
$this->set('user', $user);
}
}

Da mesma maneira que criamos as views para os nossos artigos usando a ferramenta de gerao de cdigo,
podemos implementar as views do usurio. Para o propsito deste tutorial, vamos mostrar apenas o
add.ctp:
<!-- src/Template/Users/add.ctp -->
<div class="users form">
<?= $this->Form->create($user) ?>
<fieldset>
<legend><?= __('Add User') ?></legend>
<?= $this->Form->input('username') ?>
<?= $this->Form->input('password') ?>
<?= $this->Form->input('role', [
'options' => ['admin' => 'Admin', 'author' => 'Author']
]) ?>
</fieldset>
<?= $this->Form->button(__('Submit')); ?>
<?= $this->Form->end() ?>
</div>

Autenticao (Login e Logout)


Agora estamos prontos para adicionar a nossa camada de autenticao. Em CakePHP isso tratado pelo
Cake\Controller\Component\AuthComponent, uma classe responsvel por exigir o login para

90

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

determinadas aes, a manipulao de login e logout de usurio, e tambm permite as aes para que
esto autorizados.
Para adicionar este componente em sua aplicao abra o arquivos src/Controller/AppController.php e
adicione as seguintes linha:
// src/Controller/AppController.php
namespace App\Controller;
use Cake\Controller\Controller;
use Cake\Event\Event;
class AppController extends Controller
{
//...
public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'loginRedirect' => [
'controller' => 'Articles',
'action' => 'index'
],
'logoutRedirect' => [
'controller' => 'Pages',
'action' => 'display',
'home'
]
]);
}
public function beforeFilter(Event $event)
{
$this->Auth->allow(['index', 'view', 'display']);
}
//...
}

No h muito para ser configurado, como usamos as convenes para a tabela de usurios. Ns apenas
configuramos as URLs que sero carregados aps o login e logout, ests aes so realizadas no nosso
caso para os /articles/ e / respectivamente.
O que fizemos na funo beforeFilter() foi dizer ao AuthComponent para no exigir login em
todos index() e view(), em cada controlador. Queremos que os nossos visitantes sejam capaz de ler e
listar as entradas sem registrar-se no site.
Agora, precisamos ser capaz de registrar novos usurios, salvar seu username e password, e mais
importante, o hash da senha para que ele no seja armazenado como texto simples no nosso banco de dados.
Vamos dizer ao AuthComponet para permitir que usurios deslogados acessem a funo add e execute as
aes de login e logout:

Tutorial - Criando um Blog - Autenticao e Autorizao

91

CakePHP Cookbook Documentation, Verso 3.x

// src/Controller/UsersController.php
public function beforeFilter(Event $event)
{
parent::beforeFilter($event);
// Permitir aos usurios se registrarem e efetuar logout.
// Voc no deve adicionar a ao de "login" a lista de permisses.
// Isto pode causar problemas com o funcionamento normal do AuthComponent.
$this->Auth->allow(['add', 'logout']);
}
public function login()
{
if ($this->request->is('post')) {
$user = $this->Auth->identify();
if ($user) {
$this->Auth->setUser($user);
return $this->redirect($this->Auth->redirectUrl());
}
$this->Flash->error(__('Usurio ou senha nvalido, tente novamente'));
}
}
public function logout()
{
return $this->redirect($this->Auth->logout());
}

O hashing da senha ainda no est feito, precisamos de uma classe a fim de manipular sua gerao. Crie o
arquivo src/Model/Entity/User.php e adicione a seguinte trecho:
// src/Model/Entity/User.php
namespace App\Model\Entity;
use Cake\Auth\DefaultPasswordHasher;
use Cake\ORM\Entity;
class User extends Entity
{
// Gera conjunto de todos os campos exceto o com a chave primria.
protected $_accessible = [
'*' => true,
'id' => false
];
// ...
protected function _setPassword($password)
{
return (new DefaultPasswordHasher)->hash($password);
}

92

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

// ...
}

Agora, a senha criptografada usando a classe DefaultPasswordHasher. Est faltando apenas o arquivo para exibio da tela de login. Abra o arquivo src/Template/Users/login.ctp e adicione as seguintes
linhas:
<!-- File: src/Template/Users/login.ctp -->
<div class="users form">
<?= $this->Flash->render('auth') ?>
<?= $this->Form->create() ?>
<fieldset>
<legend><?= __('Por favor informe seu usurio e senha') ?></legend>
<?= $this->Form->input('username') ?>
<?= $this->Form->input('password') ?>
</fieldset>
<?= $this->Form->button(__('Login')); ?>
<?= $this->Form->end() ?>
</div>

Agora voc pode registrar um novo usurio, acessando a URL /users/add e faa login com o usurio
recm-criado, indo para a URL /users/login. Alm disso, tente acessar qualquer outro URL que no
tenha sido explicitamente permitido, como /articles/add, voc vai ver que o aplicativo redireciona
automaticamente para a pgina de login.
E isso! Parece simples demais para ser verdade. Vamos voltar um pouco para explicar o que aconteceu. A funo beforeFilter() est falando para o AuthComponent no solicitar um login para
a ao add() em adio as aes index() e view() que foram prontamente autorizadas na funo
beforeFilter() do AppController.
A ao login() chama a funo $this->Auth->identify() da AuthComponent, que funciona
sem qualquer outra configurao porque estamos seguindo convenes, como mencionado anteriormente.
Ou seja, ter uma tabela de usurios com um username e uma coluna de password, e usamos um form
para postar os dados do usurio para o controller. Esta funo retorna se o login foi bem sucedido ou
no, e caso ela retorne sucesso, ento ns redirecionamos o usurio para a URL que configuramos quando
adicionamos o AuthComponent em nossa aplicao.
O logout funciona quando acessamos a URL /users/logout que ir redirecionar o usurio para a url
configurada em logoutUrl. Essa url acionada quando a funo AuthComponent::logout().

Autorizao (quem tem permisso para acessar o que)


Como afirmado anteriormente, ns estamos convertendo esse blog em uma ferramenta multi usurio de
autoria, e para fazer isso, precisamos modificar a tabela de artigos um pouco para adicionar a referncia
tabela de Usurios:
ALTER TABLE articles ADD COLUMN user_id INT(11);

Alm disso, uma pequena mudana no ArticlesController necessrio para armazenar o usurio conectado
no momento como uma referncia para o artigo criado:

Tutorial - Criando um Blog - Autenticao e Autorizao

93

CakePHP Cookbook Documentation, Verso 3.x

// src/Controller/ArticlesController.php
public function add()
{
$article = $this->Articles->newEntity();
if ($this->request->is('post')) {
$article = $this->Articles->patchEntity($article, $this->request->data);
// Adicione esta linha
$article->user_id = $this->Auth->user('id');
// Voc tambm pode fazer o seguinte
//$newData = ['user_id' => $this->Auth->user('id')];
//$article = $this->Articles->patchEntity($article, $newData);
if ($this->Articles->save($article)) {
$this->Flash->success(__('Seu artigo foi salvo.'));
return $this->redirect(['action' => 'index']);
}
$this->Flash->error(__('No foi possvel adicionar seu artigo.'));
}
$this->set('article', $article);
}

A funo user() fornecida pelo componente retorna qualquer coluna do usurio logado no momento. Ns
usamos esse metdo para adicionar a informao dentro de request data para que ela seja salva.
Vamos garantir que nossa app evite que alguns autores editem ou apaguem posts de outros. Uma regra
bsica para nossa aplicao que usurios admin possam acessar qualquer url, enquanto usurios normais
(o papel author) podem somente acessar as actions permitidas. Abra novamente a classe AppController e
adicione um pouco mais de opes para as configuraes do Auth:
// src/Controller/AppController.php
public function initialize()
{
$this->loadComponent('Flash');
$this->loadComponent('Auth', [
'authorize' => ['Controller'], // Adicione est linha
'loginRedirect' => [
'controller' => 'Articles',
'action' => 'index'
],
'logoutRedirect' => [
'controller' => 'Pages',
'action' => 'display',
'home'
]
]);
}
public function isAuthorized($user)
{
// Admin pode acessar todas as actions
if (isset($user['role']) && $user['role'] === 'admin') {
return true;

94

Captulo 4. Tutoriais & Exemplos

CakePHP Cookbook Documentation, Verso 3.x

}
// Bloqueia acesso por padro
return false;
}

Acabamos de criar um mecanismo de autorizao muito simples. Nesse caso os usurios com papel admin
podero acessar qualquer url no site quando estiverem logados, mas o restante dos usurios (author) no
podem acessar qualquer coisa diferente dos usurios no logados.
Isso no exatamente o que ns queremos, por isso precisamos corrigir nosso metdo isAuthorized()
para fornecer mais regras. Mas ao invs de fazer isso no AppController, vamos delegar a cada controller
para suprir essas regras extras. As regras que adicionaremos para o add de ArticlesController deve permitir ao autores criarem os posts mas evitar a edio de posts que no sejam deles. Abra o arquivo
src/Controller/ArticlesController.php e adicione o seguinte contedo:
// src/Controller/ArticlesController.php
public function isAuthorized($user)
{
// Todos os usurios registrados podem adicionar artigos
if ($this->request->action === 'add') {
return true;
}
// Apenas o proprietrio do artigo pode editar e exclu
if (in_array($this->request->action, ['edit', 'delete'])) {
$articleId = (int)$this->request->params['pass'][0];
if ($this->Articles->isOwnedBy($articleId, $user['id'])) {
return true;
}
}
return parent::isAuthorized($user);
}

Estamos sobrescrevendo a chamada isAuthorized()do AppController e internamente


verificando na classe pai se o usurio est autorizado. Caso no
esteja, ento apenas permitem acessar a action add, e condicionalmente action edit e delete. Uma ltima coisa no foi implementada. Para dizer ou no se o usurio est
autorizado a editar o artigo, ns estamos chamando uma funo isOwnedBy() na tabela artigos. Vamos,
ento, implementar essa funo:
// src/Model/Table/ArticlesTable.php
public function isOwnedBy($articleId, $userId)
{
return $this->exists(['id' => $articleId, 'user_id' => $userId]);
}

Isso conclui ento nossa autorizao simples e nosso tutorial de autorizao. Para garantir o UsersController
voc pode seguir as mesmas tcnicas que usamos para ArticlesController, voc tambm pode ser mais
criativo e codificar algumas coisas mais gerais no AppController para suas prprias regras baseadas em
Tutorial - Criando um Blog - Autenticao e Autorizao

95

CakePHP Cookbook Documentation, Verso 3.x

papis.
Se precisar de mais controle, ns sugerimos que leia o guia completo do Auth Authentication seo onde
voc encontrar mais sobre a configurao do componente, criao de classes de Autorizao customizadas,
e muito mais.
Sugerimos as seguintes leituras
1. Gerao de cdigo com o Bake Generating basic CRUD code
2. Authentication: User registration and login

96

Captulo 4. Tutoriais & Exemplos

CAPTULO 5

Contribuindo

Existem vrias maneiras de contribuir com o CakePHP. As sees abaixo iro abordar estas formas de
contribuio:

Documentao
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Tickets
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Cdigo
1
2

https://github.com/cakephp/docs
https://github.com/cakephp/docs

97

CakePHP Cookbook Documentation, Verso 3.x

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Padres de cdigo
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Guia de retrocompatibilidade
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github5 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs
https://github.com/cakephp/docs
5
https://github.com/cakephp/docs
4

98

Captulo 5. Contribuindo

CAPTULO 6

Instalao

O CakePHP rpido e fcil de instalar. Os requisitos mnimos so um servidor web e uma cpia do
CakePHP, s isso! Apesar deste manual focar principalmente na configurao do Apache (porqu ele
o mais simples de instalar e configurar), o CakePHP vai ser executado em uma srie de servidores web
como nginx, LightHTTPD, ou Microsoft IIS.

Requisitos
HTTP Server. Por exemplo: Apache. De preferncia com mod_rewrite ativo, mas no obrigatrio.
PHP 5.5.9 ou superior.
extenso mbstring
extenso intl
Nota: Tanto no XAMPP quanto no WAMP, as extenses mcrypt e mbstring so setadas por padro.
Se voc estiver usando o XAMPP, j tem a extenso intl inclusa, mas preciso descomentar a linha
extension=php_intl.dll no arquivo php.ini e ento, reiniciar o servidor atravs do painel de
controle do XAMPP.
Caso voc esteja usando o WAMP, a extenso intl est ativa por padro, mas no est funcional. Para
faz-la funcionar, voc deve ir pasta do php (que por padro ) C:\wamp\bin\php\php{version},
copiar todos os arquivos que se paream com icu***.dll e col-los no diretrio bin do apache
C:\wamp\bin\apache\apache{version}\bin. Reiniciando todos os servios a extenso j deve
ficar ok.
Apesar de um mecanismo de banco de dados no ser exigido, ns imaginamos que a maioria das aplicaes
ir utilizar um. O CakePHP suporta uma variedade de mecanismos de armazenamento de banco de dados:
MySQL (5.1.10 ou superior)
PostgreSQL

99

CakePHP Cookbook Documentation, Verso 3.x

Microsoft SQL Server (2008 ou superior)


SQLite 3
Nota: Todos os drivers inclusos internamente requerem PDO. Voc deve assegurar-se que possui a extenso
PDO correta instalada.

Instalando o CakePHP
O CakePHP utiliza Composer1 , uma ferramenta de gerenciamento de dependncias para PHP 5.3+, como o
mtodo suportado oficial para instalao.
Primeiramente, voc precisar baixar e instalar o Composer se no o fez anteriormente. Se voc tem cURL
instalada, to fcil quanto executar o seguinte:
curl -s https://getcomposer.org/installer | php

Ou, voc pode baixar composer.phar do Site oficial do Composer2 .


Para sistemas Windows, voc pode baixar o instalador aqui3 . Mais instrues para o instalador Windows do
Composer podem ser encontradas dentro do LEIA-ME aqui4 .
Agora que voc baixou e instalou o Composer, voc pode receber uma nova aplicao CakePHP executando:
php composer.phar create-project --prefer-dist cakephp/app [app_name]

Ou se o Composer estiver instalado globalmente:


composer create-project --prefer-dist cakephp/app [app_name]

Uma vez que o Composer terminar de baixar o esqueleto da aplicao e o ncleo da biblioteca CakePHP,
voc deve ter uma aplicao funcional instalada via Composer. Esteja certo de manter os arquivos composer.json e composer.lock com o restante do seu cdigo fonte.
You can now visit the path to where you installed your CakePHP application and see the setup traffic lights.

Mantendo sincronizao com as ltimas alteraes no CakePHP


Se voc quer se manter atualizado com as ltimas mudanas no CakePHP, voc pode adicionar o seguinte
ao composer.json de sua aplicao:
"require": {
"cakephp/cakephp": "dev-master"
}
1

http://getcomposer.org
https://getcomposer.org/download/
3
https://github.com/composer/windows-setup/releases/
4
https://github.com/composer/windows-setup
2

100

Captulo 6. Instalao

CakePHP Cookbook Documentation, Verso 3.x

Onde <branch> o nome do branch que voc segue. Toda vez que voc executar php composer.phar
update voc receber as ltimas atualizaes do branch escolhido.

Permisses
O CakePHP utiliza o diretrio tmp para diversas operaes. Descrio de models, views armazenadas em
cache e informaes de sesso so apenas alguns exemplos. O diretrio logs utilizado para escrever
arquivos de log pelo mecanismo padro FileLog.
Como tal, certifique-se que os diretrios logs, tmp e todos os seus sub-diretrios em sua instalao
CakePHP so gravveis pelo usurio relacionado ao servidor web. O processo de instalao do Composer
faz tmp e seus sub-diretrios globalmente gravveis para obter as coisas funcionando rapidamente, mas
voc pode atualizar as permisses para melhor segurana e mant-los gravveis apenas para o usurio relacionado ao servidor web.
Um problema comum que os diretrios e sub-diretrios de logs e tmp devem ser gravveis tanto pelo
servidor quanto pelo usurio da linha de comando. Em um sistema UNIX, se seu usurio relacionado ao
servidor web diferente do seu usurio da linha de comando, voc pode executar somente uma vez os
seguintes comandos a partir do diretrio da sua aplicao para assegurar que as permisses sero configuradas corretamente:
HTTPDUSER=`ps
setfacl -R -m
setfacl -R -d
setfacl -R -m
setfacl -R -d

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


u:${HTTPDUSER}:rwx tmp
-m u:${HTTPDUSER}:rwx tmp
u:${HTTPDUSER}:rwx logs
-m u:${HTTPDUSER}:rwx logs

Servidor de Desenvolvimento
Uma instalao de desenvolvimento o mtodo mais rpido de configurar o CakePHP. Neste exemplo, ns
vamos utilizar o console CakePHP para executar o servidor integrado do PHP que vai tornar sua aplicao
disponvel em http://host:port. A partir do diretrio da aplicao, execute:
bin/cake server

Por padro, sem nenhum argumento fornecido, isso vai disponibilizar a sua aplicao em
http://localhost:8765/.
Se voc tem algo conflitante com localhost ou porta 8765, voc pode dizer ao console CakePHP para
executar o servidor web em um host e/ou porta especfica utilizando os seguintes argumentos:
bin/cake server -H 192.168.13.37 -p 5673

Isto ir disponibilizar sua aplicao em http://192.168.13.37:5673/.


isso a! Sua aplicao CakePHP est instalada e funcionando sem ter que configurar um servidor web.

Permisses

101

CakePHP Cookbook Documentation, Verso 3.x

Aviso: O servidor de desenvolvimento nunca deve ser usado em um ambiente de produo. Destina-se
apenas como um servidor de desenvolvimento bsico.
Se voc preferir usar um servidor web real, voc deve ser capaz de mover a instalao do CakePHP (incluindo os arquivos ocultos) para dentro do diretrio raiz do seu servidor web. Voc deve, ento, ser capaz
de apontar seu navegador para o diretrio que voc moveu os arquivos para dentro e ver a aplicao em ao.

Produo
Uma instalao de produo uma forma mais flexvel de configurar o CakePHP. Usar este mtodo permite
total domnio para agir como uma aplicao CakePHP singular. Este exemplo o ajudar a instalar o CakePHP
em qualquer lugar em seu sistema de arquivos e torn-lo disponvel em http://www.example.com. Note que
esta instalao pode exigir os direitos de alterar o DocumentRoot em servidores web Apache.
Depois de instalar a aplicao usando um dos mtodos acima no diretrio de sua escolha - vamos supor que
voc escolheu /cake_install - sua configurao de produo ser parecida com esta no sistema de arquivos:
/cake_install/
bin/
config/
logs/
plugins/
src/
tests/
tmp/
vendor/
webroot/ (esse diretrio definido como DocumentRoot)
.gitignore
.htaccess
.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md

Desenvolvedores utilizando Apache devem definir a diretiva DocumentRoot pelo domnio para:
DocumentRoot /cake_install/webroot

Se o seu servidor web est configurado corretamente, agora voc deve encontrar sua aplicao CakePHP
acessvel em http://www.example.com.

Aquecendo
Tudo bem, vamos ver o CakePHP em ao. Dependendo de qual configurao voc usou, voc deve apontar
seu navegador para http://example.com/ ou http://localhost:8765/. Nesse ponto, voc ser apresentado
pgina home padro do CakePHP e uma mensagem que diz a voc o estado da sua conexo atual com o
banco de dados.

102

Captulo 6. Instalao

CakePHP Cookbook Documentation, Verso 3.x

Parabns! Voc est pronto para create your first CakePHP application.

Reescrita de URL
Apache
Apesar do CakePHP ser construdo para trabalhar com mod_rewrite fora da caixa, e normalmente o faz, nos
atentamos que aluns usurios lutam para conseguir fazer tudo funcionar bem em seus sistemas.
Aqui esto algumas coisas que voc poderia tentar para conseguir tudo rodando corretamente. Primeiramente observe seu httpd.conf. (Tenha certeza que voc est editando o httpd.conf do sistema ao invs de um
usurio, ou site especfico.)
Esses arquivos podem variar entre diferentes distribuies e verses do Apache. Voc tambm pode
pesquisar em http://wiki.apache.org/httpd/DistrosDefaultLayout para maiores informaes.
1. Tenha certeza que a sobreescrita do .htaccess est permitida e que AllowOverride est definido para
All no correto DocumentRoot. Voc deve ver algo similar a:
# Cada diretrio ao qual o Apache tenha acesso pode ser configurado com respeito
# a quais servios e recursos esto permitidos e/ou desabilitados neste
# diretrio (e seus sub-diretrios).
#
# Primeiro, ns configuramos o "default" para ser um conjunto bem restrito de
# recursos.
<Directory />
Options FollowSymLinks
AllowOverride All
#
Order deny,allow
#
Deny from all
</Directory>

2. Certifique-se que o mod_rewrite est sendo carregado corretamente. Voc deve ver algo como:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Em muitos sistemas estar comentado por padro, ento voc pode apenas remover os smbolos #.
Depois de fazer as mudanas, reinicie o Apache para certificar-se que as configuraes esto ativas.
Verifique se os seus arquivos .htaccess esto realmente nos diretrios corretos. Alguns sistemas operacionais tratam arquivos iniciados com . como ocultos e portanto, no os copia.
3. Certifique-se de sua cpia do CakePHP vir da seo de downloads do site ou do nosso repositrio Git,
e que foi descompactado corretamente, verificando os arquivos .htaccess.
O diretrio app do CakePHP (ser copiado para o diretrio mais alto de sua aplicao atravs do
bake):
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule
^$
webroot/

Reescrita de URL

[L]

103

CakePHP Cookbook Documentation, Verso 3.x

RewriteRule
</IfModule>

(.*) webroot/$1

[L]

O diretrio webroot do CakePHP (ser copiado para a raz de sua aplicao atravs do bake):
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
</IfModule>

Se o seu site CakePHP ainda possuir problemas com mod_rewrite, voc pode tentar modificar as
configuraes para Virtual Hosts. No Ubuntu, edita o arquivo /etc/apache2/sites-available/default (a
localizao depende da distribuio). Nesse arquivo, certifique-se que AllowOverride None seja
modificado para AllowOverride All, ento voc ter:
<Directory />
Options FollowSymLinks
AllowOverride All
</Directory>
<Directory /var/www>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order Allow,Deny
Allow from all
</Directory>

No Mac OSX, outra soluo usar a ferramenta virtualhostx5 para fazer um Virtual Host apontar para
o seu diretrio.
Para muitos servios de hospedagem (GoDaddy, land1), seu servidor web na verdade oferecido a
partir de um diretrio de usurio que j utiliza mod_rewrite. Se voc est instalando o CakePHP
em um diretrio de usurio (http://example.com/~username/cakephp/), ou qualquer outra estrutura
URL que j utilize mod_rewrite, voc precisar adicionar declaraes RewriteBase para os arquivos
.htaccess que o CakePHP utiliza. (.htaccess, webroot/.htaccess).
Isso pode ser adicionado na mesma seo com a diretiva RewriteEngine, por exemplo, seu arquivo
webroot/.htaccess ficaria como:
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/app
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
</IfModule>

Os detalhes dessas mudanas vo depender da sua configurao, e podem incluir coisas adicionais
que no esto relacionadas ao CakePHP. Por favor, busque pela documentao online do Apache para
mais informaes.
4. (Opcional) Para melhorar a configurao de produo, voc deve prevenir contedos invidos de
serem analisados pelo CakePHP. Modifique seu webroot/.htaccess para algo como:
5

http://clickontyler.com/virtualhostx/

104

Captulo 6. Instalao

CakePHP Cookbook Documentation, Verso 3.x

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/app/
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !^/(webroot/)?(img|css|js)/(.*)$
RewriteRule ^ index.php [L]
</IfModule>

Isto ir simplesmente prevenir contedo incorreto de ser enviado para o index.php e ento exibir sua
pgina de erro 404 do servidor web.
Adicionalmente voc pode criar uma pgina HTML de erro 404 correspondente, ou utilizar a padro
do CakePHP ao adicionar uma diretiva ErrorDocument:
ErrorDocument 404 /404-not-found

nginx
nginx no utiliza arquivos .htaccess como o Apache, ento necessrio criar as reescritas de URL na configurao de sites disponveis. Dependendo da sua configurao, voc precisar modificar isso, mas pelo
menos, voc vai precisar do PHP rodando como uma instncia 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/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$ {
try_files $uri =404;
include /etc/nginx/fastcgi_params;
fastcgi_pass
127.0.0.1:9000;
fastcgi_index
index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}

Reescrita de URL

105

CakePHP Cookbook Documentation, Verso 3.x

IIS7 (Windows hosts)


IIS7 no suporta nativamente arquivos .htaccess. Mesmo existindo add-ons que adicionam esse suporte,
voc tambm pode importar as regras .htaccess no IIS para utilizar as reescritas nativas do CakePHP. Para
isso, siga os seguintes passos:
1. Utilize o Microsofts Web Platform Installer6 para instalar o Rewrite Module 2.07 ou baixe-o diretamente (32-bit8 / 64-bit9 ).
2. Crie um novo arquivo chamado web.config em seu diretrio raiz do CakePHP.
3. Utilize o Notepad ou qualquer editor seguro XML para copiar o seguinte cdigo em seu novo arquivo
web.config:

<?xml version="1.0" encoding="UTF-8"?>


<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Exclude direct access to webroot/*"
stopProcessing="true">
<match url="^webroot/(.*)$" ignoreCase="false" />
<action type="None" />
</rule>
<rule name="Rewrite routed access to assets(img, css, files, js, favic
stopProcessing="true">
<match url="^(img|css|files|js|favicon.ico)(.*)$" />
<action type="Rewrite" url="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>

Uma vez que o arquivo web.config criado com as regras amigveis de reescrita do IIS, os links, CSS,
JavaScript, e roteamento do CakePHP agora devem funcionar corretamente.

No posso utilizar Reescrita de URL


Se voc no quer ou no pode ter mod_rewrite (ou algum outro mdulo compatvel) funcionando no seu
servidor, voc precisar utilizar as URLs amigveis natvas do CakePHP. No config/app.php, descomente
6

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

106

Captulo 6. Instalao

CakePHP Cookbook Documentation, Verso 3.x

a linha que se parece como:


'App' => [
// ...
// 'baseUrl' => env('SCRIPT_NAME'),
]

Tambm remova esses arquivos .htaccess:


/.htaccess
webroot/.htaccess

Isso far suas URLs parecem como www.example.com/index.php/controllername/actionname/param ao invs de www.example.com/controllername/actionname/param.

Reescrita de URL

107

CakePHP Cookbook Documentation, Verso 3.x

108

Captulo 6. Instalao

CAPTULO 7

Configurao

Additional Class Paths


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

109

CakePHP Cookbook Documentation, Verso 3.x

110

Captulo 7. Configurao

CAPTULO 8

Roteamento

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Connecting Routes
Using Named Routes
Filtros do Dispatcher
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

1
2

https://github.com/cakephp/docs
https://github.com/cakephp/docs

111

CakePHP Cookbook Documentation, Verso 3.x

112

Captulo 8. Roteamento

CAPTULO 9

Objetos de requisio e resposta

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Request

https://github.com/cakephp/docs

113

CakePHP Cookbook Documentation, Verso 3.x

114

Captulo 9. Objetos de requisio e resposta

CAPTULO 10

Controllers (Controladores)

class Cake\Controller\Controller
Os controllers (controladores) correspondem ao C no padro MVC. Aps o roteamento ter sido aplicado e o
controller correto encontrado, a ao do controller chamada. Seu controller deve lidar com a interpretao
dos dados de uma requisio, certificando-se que os models corretos so chamados e a resposta ou view
esperada seja exibida. Os controllers podem ser vistos como intermedirios entre a camada Model e View.
Voc vai querer manter seus controllers magros e seus Models gordos. Isso lhe ajudar a reutilizar seu
cdigo e test-los mais facilmente.
Mais comumente, controllers so usados para gerenciar a lgica de um nico model. Por exemplo, se
voc est construindo um site para uma padaria online, voc pode ter um RecipesController e um
IngredientsController gerenciando suas receitas e seus ingredientes. No CakePHP, controllers so
nomeados de acordo com o model que manipulam. tambm absolutamente possvel ter controllers que
usam mais de um model.
Os controllers da sua aplicao so classes que estendem a classe AppController, a qual por
sua vez estende a classe do core Controller. A classe AppController pode ser definida em
src/Controller/AppController.php e deve conter mtodos que so compartilhados entre todos os controllers de sua aplicao.
Os controllers fornecem uma srie de mtodos que lidam com requisies. Estas so chamados de actions.
Por padro, todos os mtodos pblicos em um controller so uma action e acessveis por uma URL. Uma
action responsvel por interpretar a requisio e criar a resposta. Normalmente as respostas so na forma
de uma view renderizada, mas tambm existem outras formas de criar respostas.

O App Controller
Como mencionado anteriormente, a classe AppController a me de todos os outros controllers da
sua aplicao. A prpria AppController estendida da classe Cake\Controller\Controller
includa no CakePHP. Assim sendo, AppController definida em src/Controller/AppController.php
como a seguir:

115

CakePHP Cookbook Documentation, Verso 3.x

namespace App\Controller;
use Cake\Controller\Controller;
class AppController extends Controller
{
}

Os atributos e mtodos criados em seu AppController vo estar disponveis para todos os controllers
que a extendam. Components (sobre os quais voc ir aprender mais tarde) so a melhor alternativa para
cdigos usados por muitos (mas no necessariamente em todos) controllers.
Voc pode usar seu AppController para carregar components que sero usados em cada controller de
sua aplicao. O CakePHP oferece um mtodo initialize() que invocado ao final do construtor do
controller para esse tipo de uso:
namespace App\Controller;
use Cake\Controller\Controller;
class AppController extends Controller
{
public function initialize()
{
// Sempre habilite o CSRF component.
$this->loadComponent('Csrf');
}
}

Em adio ao mtodo initialize(), a antiga propriedade $components tambm vai permitir voc
declarar quais components devem ser carregados. Enquanto heranas objeto-orientadas normais so enquadradas, os components e helpers usados por um controller so especialmente tratados. Nestes casos, os
valores de propriedade do AppController so mesclados com arrays de classes controller filhas. Os
valores na classe filha iro sempre sobre-escrever aqueles na AppController.

Fluxo de requisies
Quando uma requisio feita para uma aplicao CakePHP, a classe Cake\Routing\Router e a classe
Cake\Routing\Dispatcher usam Connecting Routes para encontrar e criar a instncia correta do
controller. Os dados da requisio so encapsulados em um objeto de requisio. O CakePHP coloca todas
as informaes importantes de uma requisio na propriedade $this->request. Veja a seo Request
para mais informaes sobre o objeto de requisio do CakePHP.

116

Captulo 10. Controllers (Controladores)

CakePHP Cookbook Documentation, Verso 3.x

Mtodos (actions) de controllers


Actions de controllers so responsveis por converter os parmetros de requisio em uma resposta para
o navegador/usurio que fez a requisio. O CakePHP usa convenes para automatizar este processo e
remove alguns cdigos clichs que voc teria que escrever de qualquer forma.
Por conveno, o CakePHP renderiza uma view com uma verso flexionada do nome da action. Retornando
ao nosso exemplo da padaria online, nosso RecipesController poderia abrigar as actions view(),
share() e search(). O controller seria encontrado em src/Controller/RecipesController.php contendo:
// src/Controller/RecipesController.php
class RecipesController extends AppController
{
function view($id)
{
// A lgica da action vai aqui.
}
function share($customerId, $recipeId)
{
// A lgica da action vai aqui.
}
function search($query)
{
// A lgica da action vai aqui.
}
}

Os arquivos de template para estas actions seriam src/Template/Recipes/view.ctp,


src/Template/Recipes/share.ctp e src/Template/Recipes/search.ctp. A nomenclatura convencional
para arquivos view a verso lowercased (minscula) e underscored (sem sublinhado) do nome da action.
Actions dos controllers geralmente usam Controller::set() para criar um contexto que a View usa
para renderizar a camada view. Devido s convenes que o CakePHP usa, voc no precisa criar e renderizar as views manualmente. Ao invs, uma vez que uma action de controller completada, o CakePHP
ir manipular a renderizao e devolver a view.
Se por alguma razo voc quiser pular o comportamento padro, voc pode retornar um objeto
Cake\Network\Response a partir da action com a resposta definida.
Quando voc usa mtodos do controller com Routing\RequestActionTrait::requestAction()
voc ir tipicamente retornar uma instncia Response. Se voc tem mtodos de controller que so usados
para requisies web normais + requestAction, voc deve checar o tipo de requisio antes de retornar:
// src/Controller/RecipesController.php
class RecipesController extends AppController
{
public function popular()
{

Mtodos (actions) de controllers

117

CakePHP Cookbook Documentation, Verso 3.x

$popular = $this->Recipes->find('popular');
if ($this->request->is('requested')) {
$this->response->body(json_encode($popular));
return $this->response;
}
$this->set('popular', $popular);
}
}

A action do controller acima um exemplo de como um mtodo pode ser usado com
Routing\RequestActionTrait::requestAction() e requisies normais.
Para que voc possa utilizar um controller de forma eficiente em sua prpria aplicao, ns iremos cobrir
alguns dos atributos e mtodos oferecidos pelo controller do core do CakePHP.

Interagindo com views


Os controllers interagem com as views de diversas maneiras. Primeiro eles so capazes de passar dados para
as views usando Controller::set(). Voc tambm pode decidir no seu controller qual arquivo view
deve ser renderizado atravs do controller.

Definindo variveis para a view


Cake\Controller\Controller::set(string $var, mixed $value)
O mtodo Controller::set() a principal maneira de enviar dados do seu controller para a sua view.
Aps ter usado o mtodo Controller::set(), a varivel pode ser acessada em sua view:
// Primeiro voc passa os dados do controller:
$this->set('color', 'pink');
// Ento, na view, voc pode utilizar os dados:
?>
Voc selecionou a cobertura <?php echo $color; ?> para o bolo.

O mtodo Controller::set() tambm aceita um array associativo como primeiro parmetro. Isto
pode oferecer uma forma rpida para atribuir uma srie de informaes para a view:
$data = [
'color' => 'pink',
'type' => 'sugar',
'base_price' => 23.95
];
// Faa $color, $type, e $base_price
// disponveis na view:
$this->set($data);

118

Captulo 10. Controllers (Controladores)

CakePHP Cookbook Documentation, Verso 3.x

Renderizando uma view


Cake\Controller\Controller::render(string $view, string $layout)
O mtodo Controller::render() chamado automaticamente no fim de cada ao requisitada de um
controller. Este mtodo executa toda a lgica da view (usando os dados que voc passou usando o mtodo
Controller::set()), coloca a view em View::$layout, e serve de volta para o usurio final.
O arquivo view usado pelo mtodo Controller::render() determinado por conveno. Se a
action search() do controller RecipesController requisitada, o arquivo view encontrado em
src/Template/Recipes/search.ctp ser renderizado:
namespace App\Controller;
class RecipesController extends AppController
{
// ...
public function search()
{
// Render the view in src/Template/Recipes/search.ctp
$this->render();
}
// ...
}

Embora o CakePHP ir chamar o mtodo Controller::render() automaticamente (ao menos que


voc altere o atributo $this->autoRender para false) aps cada action, voc pode us-lo para especificar um arquivo view alternativo especificando o nome do arquivo view como primeiro parmetro do
mtodo Controller::render().
Se o parmetro $view comear com /, assumido ser um arquivo view ou elemento relativo ao diretrio
/src/Template. Isto permite a renderizao direta de elementos, muito til em chamadas AJAX:
// Renderiza o elemento em src/Template/Element/ajaxreturn.ctp
$this->render('/Element/ajaxreturn');

O segundo parmetro $layout do Controller::render() permite que voc especifique o layout


pelo qual a view renderizada.
Renderizando uma view especfica
Em seu controller voc pode querer renderizar uma view diferente do que a convencional. Voc pode
fazer isso chamando o mtodo Controller::render() diretamente. Uma vez chamado o mtodo
Controller::render(), o CakePHP no tentar renderizar novamente a view:
namespace App\Controller;
class PostsController extends AppController
{
public function my_action()
{
$this->render('custom_file');

Mtodos (actions) de controllers

119

CakePHP Cookbook Documentation, Verso 3.x

}
}

Isto
renderizaria
o
arquivo
src/Template/Posts/my_action.ctp

src/Template/Posts/custom_file.ctp

ao

invs

de

Voc tambm pode renderizar views de plugins utilizando a seguinte sintaxe:


$this->render(PluginName.PluginController/custom_file). Por exemplo:
namespace App\Controller;
class PostsController extends AppController
{
public function my_action()
{
$this->render('Users.UserDetails/custom_file');
}
}

Isto renderizaria plugins/Users/src/Template/UserDetails/custom_file.ctp

Redirecionando para outras pginas


Cake\Controller\Controller::redirect(string|array $url, integer $status)
O mtodo de controle de fluxo que voc vai usar na majoritariamente Controller::redirect().
Este mtodo recebe seu primeiro parmetro na forma de uma URL relativa do CakePHP. Quando um usurio
executar um pedido com xito, voc pode querer redirecion-lo para uma tela de recepo.
public function place_order()
{
// Logic for finalizing order goes here
if ($success) {
return $this->redirect(
['controller' => 'Orders', 'action' => 'thanks']
);
}
return $this->redirect(
['controller' => 'Orders', 'action' => 'confirm']
);
}

Este mtodo ir retornar a instncia da resposta com cabealhos apropriados definidos. Voc deve retornar
a instncia da resposta da sua action para prevenir renderizao de view e deixar o dispatcher controlar o
redirecionamento corrente.
Voc tambm pode usar uma URL relativa ou absoluta como o parmetro $url:
return $this->redirect('/orders/thanks');
return $this->redirect('http://www.example.com');

Voc tambm pode passar dados para a action:


120

Captulo 10. Controllers (Controladores)

CakePHP Cookbook Documentation, Verso 3.x

return $this->redirect(['action' => 'edit', $id]);

O segundo parmetro passado no Controller::redirect() permite a voc definir um cdigo de


status HTTP para acompanhar o redirecionamento. Voc pode querer usar o cdigo 301 (movido permanentemente) ou 303 (veja outro), dependendo da natureza do redirecionamento.
Se voc precisa redirecionar o usurio de volta para a pgina que fez a requisio, voc pode usar:
$this->redirect($this->referer());

Um exemplo usando seqncias de consulta e hash pareceria com:


return $this->redirect([
'controller' => 'Orders',
'action' => 'confirm',
'?' => [
'product' => 'pizza',
'quantity' => 5
],
'#' => 'top'
]);

A URL gerada seria:


http://www.example.com/orders/confirm?product=pizza&quantity=5#top

Redirecionando para outra action no mesmo Controller


Cake\Controller\Controller::setAction($action, $args...)
Se voc precisar redirecionar a atual action para uma diferente no mesmo controller, voc pode usar
Controller::setAction() para atualizar o objeto da requisio, modificar o template da view que
ser renderizado e redirecionar a execuo para a action especificada:
// De uma action delete, voc pode renderizar uma pgina
// de ndice atualizada.
$this->setAction('index');

Carregando models adicionais


Cake\Controller\Controller::loadModel(string $modelClass, string $type)
O mtodo loadModel vem a calhar quando voc precisa usar um model que no padro do controller ou
o seu model no est associado com este.:
// Em um mtodo do controller.
$this->loadModel('Articles');
$recentArticles = $this->Articles->find('all', [
'limit' => 5,
'order' => 'Articles.created DESC'
]);

Carregando models adicionais

121

CakePHP Cookbook Documentation, Verso 3.x

Se voc est usando um provedor de tabelas que no os da ORM nativa voc pode ligar este sistema de
tabelas aos controllers do CakePHP conectando seus mtodos de factory:
// Em um mtodo do controller.
$this->modelFactory(
'ElasticIndex',
['ElasticIndexes', 'factory']
);

Depois de registrar uma tabela factory, voc pode usar o loadModel para carregar instncias:
// Em um mtodo do controller
$this->loadModel('Locations', 'ElasticIndex');

Nota: O TableRegistry da ORM nativa conectado por padro como o provedor de Tabelas.

Paginando um model
Cake\Controller\Controller::paginate()
Este mtodo usado para fazer a paginao dos resultados retornados por seus models. Voc pode especificar o tamanho da pgina (quantos resultados sero retornados), as condies de busca e outros parmetros.
Veja a seo pagination para mais detalhes sobre como usar o mtodo paginate()
O atributo paginate lhe oferece uma forma fcil de customizar como paginate() se comporta:
class ArticlesController extends AppController
{
public $paginate = [
'Articles' => [
'conditions' => ['published' => 1]
]
];
}

Configurando components para carregar


Cake\Controller\Controller::loadComponent($name, $config =[])
Em seu mtodo initialize() do controller voc pode definir qualquer component que quiser carregado,
e qualquer configurao de dados para eles:
public function intialize()
{
parent::initialize();
$this->loadComponent('Csrf');
$this->loadComponent('Comments', Configure::read('Comments'));
}

122

Captulo 10. Controllers (Controladores)

CakePHP Cookbook Documentation, Verso 3.x

property Cake\Controller\Controller::$components
A propriedade $components em seus controllers permitem a voc configurar components. Components
configurados e suas dependncias sero criados pelo CakePHP para voc. Leia a seo Configuring Components para mais informaes. Como mencionado anteriormente, a propriedade $components ser
mesclada com a propriedade definida em cada classe parente do seu controller.

Configurando helpers para carregar


property Cake\Controller\Controller::$helpers
Vamos observar como dizer ao controller do CakePHP que voc planeja usar classes MVC adicionais:
class RecipesController extends AppController
{
public $helpers = ['Form'];
}

Cada uma dessas variveis so mescladas com seus valores herdados, portanto no necessrio (por exemplo) redeclarar o FormHelper, ou qualquer coisa declarada em seu AppController.

Ciclo de vida de callbacks em uma requisio


Os controllers do CakePHP vm equipados com callbacks que voc pode usar para inserir lgicas em torno
do ciclo de vida de uma requisio:
Cake\Controller\Controller::beforeFilter(Event $event)
Este mtodo executado antes de cada ao dos controllers. um timo lugar para verificar se h
uma sesso ativa ou inspecionar as permisses de um usurio.
Nota: O mtodo beforeFilter() ser chamado para aes perdidas.
Cake\Controller\Controller::beforeRender(Event $event)
Chamada aps a lgica da action de um controller, mas antes da view ser renderizada. Esse
callback no usado frequentemente, mas pode ser necessrio se voc estiver chamando
Controller\Controller::render() manualmente antes do final de uma determinada action.
Cake\Controller\Controller::afterFilter()
Chamada aps cada ao dos controllers, e aps a completa renderizao da view. Este o ltimo
mtodo executado do controller.
Em adio ao ciclo de vida dos callbacks do controller, Components (Componentes) tambm oferece um
conjunto de callbacks similares.
Lembre de chamar os callbacks do AppController em conjunto com os callbacks dos controllers para
melhores resultados:

Configurando helpers para carregar

123

CakePHP Cookbook Documentation, Verso 3.x

public function beforeFilter(Event $event)


{
parent::beforeFilter($event);
}

Mais sobre controllers


O Pages Controller
CakePHP distribudo com o controller PagesController.php. Esse controller simples, seu uso opcional
e normalmente direcionado a prover pginas estticas. A homepage que voc v logo depois de instalar o
CakePHP utiliza esse controller e o arquivo da view fica em src/Template/Pages/home.ctp. Se voc criar o
arquivo src/Template/Pages/about.ctp, voc poder acess-lo em http://example.com/pages/about. Fique
a vontade para alterar esse controller para atender suas necessacidades ou mesmo exclu-lo.
Quando voc cria sua aplicao pelo Composer, o PagesController vai ser criado na pasta
src/Controller/.

Components (Componentes)
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Configuring Components
Authentication

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
1
2

https://github.com/cakephp/docs
https://github.com/cakephp/docs

124

Captulo 10. Controllers (Controladores)

CakePHP Cookbook Documentation, Verso 3.x

CookieComponent

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Cross Site Request Forgery

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Flash

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github5 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Security

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github6 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
3

https://github.com/cakephp/docs
https://github.com/cakephp/docs
5
https://github.com/cakephp/docs
6
https://github.com/cakephp/docs
4

Mais sobre controllers

125

CakePHP Cookbook Documentation, Verso 3.x

Pagination

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github7 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Request Handling

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github8 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

7
8

https://github.com/cakephp/docs
https://github.com/cakephp/docs

126

Captulo 10. Controllers (Controladores)

CAPTULO 11

Views (Visualizao)

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Using View Blocks


Layouts
Elements
More About Views
View Cells (Clulas de Visualizao)
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
1
2

https://github.com/cakephp/docs
https://github.com/cakephp/docs

127

CakePHP Cookbook Documentation, Verso 3.x

Temas
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Views JSON & XML


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Helpers (Facilitadores)
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github5 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Flash
class Cake\View\Helper\FlashHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github6 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
3

https://github.com/cakephp/docs
https://github.com/cakephp/docs
5
https://github.com/cakephp/docs
6
https://github.com/cakephp/docs
4

128

Captulo 11. Views (Visualizao)

CakePHP Cookbook Documentation, Verso 3.x

Form
class Cake\View\Helper\FormHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github7 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Html
class Cake\View\Helper\HtmlHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github8 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Number
class Cake\View\Helper\NumberHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github9 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Paginator
class Cake\View\Helper\PaginatorHelper(View $view, array $config =[])
7

https://github.com/cakephp/docs
https://github.com/cakephp/docs
9
https://github.com/cakephp/docs
8

More About Views

129

CakePHP Cookbook Documentation, Verso 3.x

PaginatorHelper Templates

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github10 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

RSS
class Cake\View\Helper\RssHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github11 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Session
class Cake\View\Helper\SessionHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github12 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Text
class Cake\View\Helper\TextHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github13 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
10

https://github.com/cakephp/docs
https://github.com/cakephp/docs
12
https://github.com/cakephp/docs
13
https://github.com/cakephp/docs
11

130

Captulo 11. Views (Visualizao)

CakePHP Cookbook Documentation, Verso 3.x

Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Time
class Cake\View\Helper\TimeHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github14 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Url
class Cake\View\Helper\UrlHelper(View $view, array $config =[])
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github15 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

14
15

https://github.com/cakephp/docs
https://github.com/cakephp/docs

More About Views

131

CakePHP Cookbook Documentation, Verso 3.x

132

Captulo 11. Views (Visualizao)

CAPTULO 12

Models (Modelos)

Models (Modelos) so as classes que servem como camada de negcio na sua aplicao. Isso significa que
eles devem ser responsveis pela gesto de quase tudo o que acontece em relao a seus dados, sua validade,
interaes e evoluo do fluxo de trabalho de informao no domnio do trabalho.
No CakePHP seu modelo de domnio da aplicao dividido em 2 tipos de objetos principais. Os primeiros
so repositories (repositrios) ou table objects (objetos de tabela). Estes objetos fornecem acesso a
colees de dados. Eles permitem a voc salvar novos registros, modificar/deletar os que j existem, definir
relacionamentos, e executar operaes em massa. O segundo tipo de objetos so as entities (entidades). Entities representam registros individuais e permitem a voc definir comportamento em nvel de linha/registro
e funcionalidades.
O ORM (MOR - Mapeamento Objeto-Relacional) nativo do CakePHP especializa-se em banco de dados
relacionais, mas pode ser extendido para suportar fontes de dados alternativas.
O ORM do Cakephp toma emprestadas ideias e conceitos dos padres ActiveRecord e Datamapper. Isso
permite criar uma implementao hbrida que combina aspectos de ambos padres para criar uma ORM
rpida e simples de utilizar.
Antes de ns comearmos explorando o ORM, tenha certeza que voc configure your database connections.
Nota: Se voc familiarizado com verses anteriores do CakePHP, voc deveria ler o Guia de atualizao
para o novo ORM para esclarecer diferenas importantes entre o CakePHP 3.0 e suas verses antigas.

Exemplo rpido
Para comear voc no precisa escrever cdigo. Se voc seguiu as convenes do CakePHP para suas tabelas
de banco de dados, voc pode simplesmente comear a usar o ORM. Por exemplo, se quisssemos carregar
alguns dados da nossa tabela articles poderamos fazer:
use Cake\ORM\TableRegistry;
$articles = TableRegistry::get('Articles');
$query = $articles->find();

133

CakePHP Cookbook Documentation, Verso 3.x

foreach ($query as $row) {


echo $row->title;
}

Nota-se que ns no temos que criar qualquer cdigo ou definir qualquer configurao. As convenes do
CakePHP nos permitem pular alguns cdigos clich, e permitir que o framework insera classes bsicas enquanto sua aplicao no criou uma classe concreta. Se quisssemos customizar nossa classe ArticlesTable
adicionando algumas associaes ou definir alguns mtodos adicionais, deveriamos acrescentar o seguinte
a src/Model/Table/ArticlesTable.php aps a tag de abertura <?php:
namespace App\Model\Table;
use Cake\ORM\Table;
class ArticlesTable extends Table
{
}

Classes de tabela usam a verso CamelCased do nome da tabela com o sufixo Table como o nome
da classe. Uma vez que sua classe fora criada, voc recebe uma referncia para esta utilizando o
ORM\TableRegistry como antes:
use Cake\ORM\TableRegistry;
// Agora $articles uma instncia de nossa classe ArticlesTable.
$articles = TableRegistry::get('Articles');

Agora que temos uma classe de tabela concreta, ns provavelmente vamos querer usar uma classe de entidade concreta. As classes de entidade permitem definir mtodos de acesso, mtodos mutantes, definir
lgica personalizada para os registros individuais e muito mais. Vamos comear adicionando o seguinte
para src/Model/Entity/Article.php aps a tag de abertura <?php:
namespace App\Model\Entity;
use Cake\ORM\Entity;
class Article extends Entity
{
}

Entidades usam a verso singular CamelCase do nome da tabela como seu nome de classe por padro.
Agora que ns criamos nossa classe de entidade, quando carregarmos entidades do nosso banco de dados,
ns iremos receber instncias da nossa nova classe Article:
use Cake\ORM\TableRegistry;
// Agora uma instncia de ArticlesTable.
$articles = TableRegistry::get('Articles');
$query = $articles->find();
foreach ($query as $row) {
// Cada linha agora uma instncia de nossa classe Article.

134

Captulo 12. Models (Modelos)

CakePHP Cookbook Documentation, Verso 3.x

echo $row->title;
}

CakePHP utiliza convenes de nomenclatura para ligar as classes de tabela e entidade juntas. Se voc
precisar customizar qual entidade uma tabela utiliza, voc pode usar o mtodo entityClass() para
definir nomes de classe especficos.
Veja os captulos em Objetos de tabela e Entities (Entidades) para mais informaes sobre como usar objetos
de tabela e entidades em sua aplicao.

Mais informao
O bsico sobre banco de dados
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Construtor de queries
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Objetos de tabela
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
1

https://github.com/cakephp/docs
https://github.com/cakephp/docs
3
https://github.com/cakephp/docs
2

Mais informao

135

CakePHP Cookbook Documentation, Verso 3.x

Entities (Entidades)
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Requisitando dados e conjuntos de resultados


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github5 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Validando dados
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github6 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Salvando dados
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github7 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
4

https://github.com/cakephp/docs
https://github.com/cakephp/docs
6
https://github.com/cakephp/docs
7
https://github.com/cakephp/docs
5

136

Captulo 12. Models (Modelos)

CakePHP Cookbook Documentation, Verso 3.x

Mais informao

137

CakePHP Cookbook Documentation, Verso 3.x

138

Captulo 12. Models (Modelos)

CakePHP Cookbook Documentation, Verso 3.x

Deletando dados
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github8 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Associaes - Conectando tabelas


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github9 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Behaviors (Comportamentos)
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github10 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

CounterCache
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github11 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
8

https://github.com/cakephp/docs
https://github.com/cakephp/docs
10
https://github.com/cakephp/docs
11
https://github.com/cakephp/docs
9

Mais informao

139

CakePHP Cookbook Documentation, Verso 3.x

Timestamp
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github12 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Translate
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github13 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Tree
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github14 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Schema
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github15 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
12

https://github.com/cakephp/docs
https://github.com/cakephp/docs
14
https://github.com/cakephp/docs
15
https://github.com/cakephp/docs
13

140

Captulo 12. Models (Modelos)

CakePHP Cookbook Documentation, Verso 3.x

ORM Cache Shell


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github16 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

16

https://github.com/cakephp/docs

Mais informao

141

CakePHP Cookbook Documentation, Verso 3.x

142

Captulo 12. Models (Modelos)

CAPTULO 13

Authentication

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

143

CakePHP Cookbook Documentation, Verso 3.x

144

Captulo 13. Authentication

CAPTULO 14

Bake Console

O bake console do CakePHP outro empenho para voc ter o CakePHP configurado e funcionando rpido.
O bake console pode criar qualquer ingrediente bsico do CakePHP: models, behaviors, views, helpers,
components, test cases, fixtures e plugins. E ns no estamos apenas falando de classes esqueleto: O Bake
pode criar uma aplicao totalmente funcional em questo de minutos. De fato, o Bake um passo natural
a se dar uma vez que a aplicao tem seu alicerce construdo.

Instalao
Antes de tentar usar ou extender o bake, tenha certeza que ele est instalado em sua aplicao. O bake
distribudo como um plugin que voc pode instalar com o Composer:
composer require --dev cakephp/bake:~1.0

Isto ir instalar o bake como uma dependncia de desenvolvimento, sendo assim, no instalado quando em
um ambiente de produo. As sees a seguir cobrem o uso do bake com mais detalhes:

Gerao de cdigo com o Bake


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
1

https://github.com/cakephp/docs

145

CakePHP Cookbook Documentation, Verso 3.x

Extendendo o Bake
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

146

Captulo 14. Bake Console

CAPTULO 15

Caching

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

147

CakePHP Cookbook Documentation, Verso 3.x

148

Captulo 15. Caching

CAPTULO 16

Console e Shells

O CakePHP no oferece um framework apenas para desenvolvimento web, mas tambm um framework para
criao de aplicaes de console. Estas aplicaes so ideais para manipular variadas tarefas em segundo
plano como manuteno e complementao de trabalho fora do ciclo requisio-resposta. As aplicaes de
console do CakePHP permitem a voc reutilizar suas classes de aplicao a partir da linha de comando.
O CakePHP traz consigo algumas aplicaes de console nativas. Algumas dessas aplicaes so utilizadas
em conjunto com outros recursos do CakePHP (como i18n), e outros de uso geral para acelerao de trabalho.

O Console do CakePHP
Esta seo prov uma introduo linha de comando do CakePHP. Ferramentas de console so ideais para
uso em cron jobs, ou utilitrios baseados em linha de comando que no precisam ser acessveis por um
navegador web.
O PHP prov um cliente CLI que faz interface com o seu sistema de arquivos e aplicaes de forma muito
mais suave. O console do CakePHP prov um framework para criar scripts shell. O console utiliza uma
configurao tipo dispatcher para carregar uma shell ou tarefa, e prover seus parmetros.
Nota: Uma linha de comando (CLI) constutuda a partir do PHP deve estar disponvel no sistema se voc
planeja utilizr o Console.
Antes de entrar em detalhes, vamos ter certeza de que voc pode executar o console do CakePHP. Primeiro,
voc vai precisar executar um sistema shell. Os exemplos apresentados nesta seo sero em bash, mas
o Console do CakePHP compatvel com o Windows tambm. Este exemplo assume que o usurio est
conectado em um prompt do bash e est atualmente na raiz de uma aplicao CakePHP.
Aplicaes CakePHP possuem um diretrio Console que contm todas as shells e tarefas para uma aplicao. Ele tambm vem com um executvel:
$ cd /path/to/app
$ bin/cake

149

CakePHP Cookbook Documentation, Verso 3.x

Executar o Console sem argumentos produz esta mensagem de ajuda:


Welcome to CakePHP v3.0.0 Console
--------------------------------------------------------------App : App
Path: /Users/markstory/Sites/cakephp-app/src/
--------------------------------------------------------------Current Paths:
-app: src
-root: /Users/markstory/Sites/cakephp-app
-core: /Users/markstory/Sites/cakephp-app/vendor/cakephp/cakephp
Changing Paths:
Your working path should be the same as your application path. To change your path use the
Example: -app relative/path/to/myapp or -app /absolute/path/to/myapp
Available Shells:
[Bake] bake
[Migrations] migrations
[CORE] i18n, orm_cache, plugin, server
[app] behavior_time, console, orm
To run an app or core command, type cake shell_name [args]
To run a plugin command, type cake Plugin.shell_name [args]
To get help on a specific command, type cake shell_name --help

A primeira informao impressa refere-se a caminhos. Isso til se voc estiver executando o console a
partir de diferentes partes do sistema de arquivos.

Criando uma Shell


Vamos criar uma shell para utilizar no Console. Para este exemplo, criaremos uma simples Hello World
(Ol Mundo) shell. No diretrio src/Shell de sua aplicao crie HelloShell.php. Coloque o seguinte cdigo
dentro do arquivo recem criado:
namespace App\Shell;
use Cake\Console\Shell;
class HelloShell extends Shell
{
public function main()
{
$this->out('Hello world.');

150

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

}
}

As convenes para as classes de shell so de que o nome da classe deve corresponder ao nome do arquivo,
com o sufixo de Shell. No nosso shell criamos um mtodo main(). Este mtodo chamado quando um
shell chamado sem comandos adicionais. Vamos adicionar alguns comandos daqui a pouco, mas por agora
vamos executar a nossa shell. A partir do diretrio da aplicao, execute:
bin/cake hello

Voc deve ver a seguinte sada:


Welcome to CakePHP Console
--------------------------------------------------------------App : app
Path: /Users/markstory/Sites/cake_dev/src/
--------------------------------------------------------------Hello world.

Como mencionado antes, o mtodo main() em shells um mtodo especial chamado sempre que no h
outros comandos ou argumentos dados para uma shell. Por nosso mtodo principal no ser muito interessante, vamos adicionar outro comando que faz algo:
namespace App\Shell;
use Cake\Console\Shell;
class HelloShell extends Shell
{
public function main()
{
$this->out('Hello world.');
}
public function heyThere($name = 'Anonymous')
{
$this->out('Hey there ' . $name);
}
}

Depois de salvar o arquivo, voc deve ser capaz de executar o seguinte comando e ver o seu nome impresso:
bin/cake hello hey_there your-name

Qualquer mtodo pblico no prefixado por um _ permitido para ser chamado a partir da linha de comando.
Como voc pode ver, os mtodos invocados a partir da linha de comando so transformados do argumento
prefixado para a forma correta do nome camel-cased (camelizada) na classe.
No nosso mtodo heyThere() podemos ver que os argumentos posicionais so providos para nossa
funo heyThere(). Argumentos posicionais tambm esto disponvels na propriedade args. Voc
pode acessar switches ou opes em aplicaes shell, estando disponveis em $this->params, mas ns
iremos cobrir isso daqui a pouco.
Quando utilizando um mtodo main() voc no estar liberado para utilizar argumentos posicionais. Isso
Criando uma Shell

151

CakePHP Cookbook Documentation, Verso 3.x

se deve ao primeiro argumento posicional ou opo ser interpretado(a) como o nome do comando. Se voc
quer utilizar argumentos, voc deve usar mtodos diferentes de main().

Usando Models em suas shells


Voc frequentemente precisar acessar a camada lgica de negcios em seus utilitrios shell; O CakePHP
faz essa tarefa super fcil. Voc pode carregar models em shells assim como faz em um controller utilizando
loadModel(). Os models carregados so definidos como propriedades anexas sua shell:
namespace App\Shell;
use Cake\Console\Shell;
class UserShell extends Shell
{
public function initialize()
{
parent::initialize();
$this->loadModel('Users');
}
public function show()
{
if (empty($this->args[0])) {
return $this->error('Por favor, indique um nome de usurio.');
}
$user = $this->Users->findByUsername($this->args[0])->first();
$this->out(print_r($user, true));
}
}

A shell acima, ir preencher um user pelo seu username e exibir a informao armazenada no banco de
dados.

Tasks de Shell
Havero momentos construindo aplicaes mais avanadas de console que voc vai querer compor funcionalidades em classes reutilizveis que podem ser compartilhadas atravs de muitas shells. Tasks permitem que voc extraia comandos em classes. Por exemplo, o bake feito quase que completamente de
tasks. Voc define tasks para uma shell usando a propriedade $tasks:
class UserShell extends Shell
{
public $tasks = ['Template'];
}

Voc pode utilizar tasks de plugins utilizando o padro plugin syntax. Tasks so armazenadas sob
Shell/Task/ em arquivos nomeados depois de suas classes. Ento se ns estivssemos criando uma
nova task FileGenerator, voc deveria criar src/Shell/Task/FileGeneratorTask.php.
152

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

Cada task deve ao menos implementar um mtodo main(). O ShellDispatcher, vai chamar esse mtodo
quando a task invocada. Uma classe task se parece com:
namespace App\Shell\Task;
use Cake\Console\Shell;
class FileGeneratorTask extends Shell
{
public function main()
{
}
}

Uma shell tambm pode prover acesso a suas tasks como propriedades, que fazem tasks serem timas para
criar punhados de funcionalidade reutilizveis similares a Components (Componentes):
// Localizado em src/Shell/SeaShell.php
class SeaShell extends Shell
{
// Localizado em src/Shell/Task/SoundTask.php
public $tasks = ['Sound'];
public function main()
{
$this->Sound->main();
}
}

Voc tambm pode acessar tasks diretamente da linha de comando:


$ cake sea sound

Nota: Para acessar tasks diretamente atravs da linha de comando, a task deve ser includa na propriedade
da classe shell $tasks. Portanto, esteja ciente que um mtodo chamado sound na classe SeaShell deve
sobrescrever a habilidade de acessar a funcionalidade na task Sound, especificada no array $tasks.

Carregando Tasks em tempo-real com TaskRegistry


Voc pode carregar arquivos em tempo-real utilizando o Task registry object. Voc pode carregar tasks que
no foram declaradas no $tasks dessa forma:
$project = $this->Tasks->load('Project');

Carregar e retornar uma instncia ProjectTask. Voc pode carregar tasks de plugins usando:
$progressBar = $this->Tasks->load('ProgressBar.ProgressBar');

Tasks de Shell

153

CakePHP Cookbook Documentation, Verso 3.x

Invocando outras Shells a partir da sua Shell


Cake\Console\dispatchShell($args)
Existem ainda muitos casos onde voc vai querer invocar uma shell a partir de outra.
Shell::dispatchShell() lhe d a habilidade de chamar outras shells ao providenciar o argv para
a sub shell. Voc pode providenciar argumentos e opes tanto como variveis ou como strings:
// Como uma string
$this->dispatchShell('schema create Blog --plugin Blog');
// Como um array
$this->dispatchShell('schema', 'create', 'Blog', '--plugin', 'Blog');

O contedo acima mostra como voc pode chamar a shell schema para criar o schema de um plugin de
dentro da shell do prprio.

Recenendo Input de usurios


Cake\Console\in($question, $choices = null, $defaut = null)
Quando construir aplicaes interativas pelo console voc ir precisar receber inputs dos usurios. CakePHP
oferece uma forma fcil de fazer isso:
// Receber qualquer texto dos usurios.
$color = $this->in('What color do you like?');
// Receber uma escolha dos usurios.
$selection = $this->in('Red or Green?', ['R', 'G'], 'R');

A validao de seleo insensitiva a maisculas / minsculas.

Criando Arquivos
Cake\Console\createFile($path, $contents)
Muitas aplicaes Shell auxiliam tarefas de desenvolvimento e implementao. Criar arquivos frequentemente importante nestes casos de uso. O CakePHP oferece uma forma fcil de criar um arquivo em um
determinado diretrio:
$this->createFile('bower.json', $stuff);

Se a Shell for interativa, um alerta vai ser gerado, e o usurio questionado se ele quer sobreescrever o
arquivo caso j exista. Se a propriedade de interao da shell for false, nenhuma questo ser disparada e
o arquivo ser simplesmente sobreescrito.

154

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

Sada de dados do Console


A classe Shell oferece alguns mtodos para direcionar contedo:
// Escreve para stdout
$this->out('Normal message');
// Escreve para stderr
$this->err('Error message');
// Escreve para stderr e para o processo
$this->error('Fatal error');

A Shell tambm inclui mtodos para limpar a sada de dados, criando linhas em branco, ou desenhando uma
linha de traos:
// Exibe 2 linhas novas
$this->out($this->nl(2));
// Limpa a tela do usurio
$this->clear();
// Desenha uma linha horizontal
$this->hr();

Por ltimo, voc pode atualizar a linha atual de texto na tela usando _io->overwrite():
$this->out('Counting down');
$this->out('10', 0);
for ($i = 9; $i > 0; $i--) {
sleep(1);
$this->_io->overwrite($i, 0, 2);
}

importante lembrar, que voc no pode sobreescrever texto uma vez que uma nova linha tenha sido exibida.

Console Output Levels


Shells frequentemente precisam de diferentes nveis de verbosidade. Quando executadas como cron jobs,
muitas sadas so desnecessrias. E h ocasies que voc no estar interessado em tudo que uma shell
tenha a dizer. Voc pode usar os nveis de sada para sinalizar sadas apropriadamente. O usurio
da shell, pode ento decidir qual nvel de detalhe ele est interessado ao sinalizar o chamado da shell.
Cake\Console\Shell::out() suporta 3 tipos de sada por padro.
QUIET - Apenas informao absolutamente importante deve ser sinalizada.
NORMAL - O nvel padro, e uso normal.
VERBOSE - Sinalize mensagens que podem ser irritantes em demasia para uso dirio, mas informativas para depurao como VERBOSE.
Voc pode sinalizar a sade da seguinte forma:

Sada de dados do Console

155

CakePHP Cookbook Documentation, Verso 3.x

// Deve aparecer em todos os nveis.


$this->out('Quiet message', 1, Shell::QUIET);
$this->quiet('Quiet message');
// No deve aparecer quando a sada quiet estiver alternado.
$this->out('normal message', 1, Shell::NORMAL);
$this->out('loud message', 1, Shell::VERBOSE);
$this->verbose('Verbose output');
// Deve aparecer somente quando a sade verbose estiver habilitada.
$this->out('extra message', 1, Shell::VERBOSE);
$this->verbose('Verbose output');

Voc pode controlar o nvel de sada das shells, ao usar as opes --quiet e --verbose. Estas opes
so adicionadas por padro, e permitem a voc controlar consistentemente nveis de sada dentro das suas
shells do CakePHP.

Estilizando a sada de dados


Estilizar a sada de dados feito ao incluir tags - como no HTML - em sua sada. O ConsoleOutput ir
substituir estas tags com a seqncia correta de cdigo ansi. Ho diversos estilos nativos, e voc pode criar
mais. Os nativos so:
error Mensagens de erro. Texto sublinhado vermelho.
warning Mensagens de alerta. Texto amarelo.
info Mensagens informativas. Texto ciano.
comment Texto adicional. Texto azul.
question Texto que uma questo, adicionado automaticamente pela shell.
Voc pode criar estilos adicionais usando $this->stdout->styles(). Para declarar um novo estilo
de sade voc pode fazer:
$this->_io->styles('flashy', ['text' => 'magenta', 'blink' => true]);

Isso deve ento permit-lo usar uma <flashy> tag na sada de sua shell, e se as cores
ansi estiverem habilitadas, o seguinte pode ser renderizado como texto magenta piscante
$this->out(<flashy>Whoooa</flashy> Something went wrong);. Quando definir
estilos voc pode usar as seguintes cores para os atributos text e background:
black
red
green
yellow
blue
magenta

156

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

cyan
white
Voc tambm pode usar as seguintes opes atravs de valores boleanos, defini-los com valor positivo os
habilita.
bold
underline
blink
reverse
Adicionar um estilo o torna disponvel para todas as instncias do ConsoleOutput, ento voc no tem que
redeclarar estilos para os objetos stdout e stderr respectivamente.

Desabilitando a colorizao
Mesmo que a colorizao seja incrvel, havero ocasies que voc querer desabilit-la, ou for-la:
$this->_io->outputAs(ConsoleOutput::RAW);

O citado ir colocar o objeto de sada em modo raw. Em modo raw, nenhum estilo aplicado. Existem trs
modos que voc pode usar.
ConsoleOutput::RAW - Sada raw, nenhum estilo ou formatao sero aplicados. Este um modo
indicado se voc estiver exibindo XML ou, quiser depurar porqu seu estilo no est funcionando.
ConsoleOutput::PLAIN - Sada de texto simples, tags conhecidas de estilo sero removidas da
sada.
ConsoleOutput::COLOR - Sada onde a cor removida.
Por padro em sistemas *nix objetos ConsoleOutput padronizam-se a a sada de cores. Em sistemas Windows, a sada simples padro a no ser que a varivel de ambiente ANSICON esteja presente.

Opes de configurao e Gerao de ajuda


class Cake\Console\ConsoleOptionParser
ConsoleOptionParser oferece uma opo de CLI e analisador de argumentos.
OptionParsers permitem a voc completar dois objetivos ao mesmo tempo. Primeiro, eles permitem definir
opes e argumentos para os seus comandos. Isso permite separar validao bsica de dados e seus comandos do console. Segundo, permite prover documentao, que usada para gerar arquivos de ajuda bem
formatados.
O console framework no CakePHP recebe as opes do seu interpetador shell ao chamar
$this->getOptionParser(). Sobreescrever esse mtodo permite configurar o OptionParser para
definir as entradas aguardadas da sua shell. Voc tambm pode configurar interpetadores de subcomandos,

Opes de configurao e Gerao de ajuda

157

CakePHP Cookbook Documentation, Verso 3.x

que permitem ter diferentes interpretadores para subcomandos e tarefas. O ConsoleOptionParser implementa uma interface fluida e inclui mtodos para facilmente definir mltiplas opes/argumentos de uma
vez:
public function getOptionParser()
{
$parser = parent::getOptionParser();
// Configure parser
return $parser;
}

Configurando um interpretador de opo com a interface fluida


Todos os mtodos que configuram um interpretador de opes podem ser encadeados, permitindo definir
um interpretador de opes completo em uma srie de chamadas de mtodos:
public function getOptionParser()
{
$parser = parent::getOptionParser();
$parser->addArgument('type', [
'help' => 'Either a full path or type of class.'
])->addArgument('className', [
'help' => 'A CakePHP core class name (e.g: Component, HtmlHelper).'
])->addOption('method', [
'short' => 'm',
'help' => __('The specific method you want help on.')
])->description(__('Lookup doc block comments for classes in CakePHP.'));
return $parser;
}

Os mtodos que permitem encadeamento so:


description()
epilog()
command()
addArgument()
addArguments()
addOption()
addOptions()
addSubcommand()
addSubcommands()
Cake\Console\ConsoleOptionParser::description($text = null)
Recebe ou define a descrio para o interpretador de opes. A descrio exibida acima da informao do
argumento e da opo. Ao instanciar tanto em array como em string, voc pode definir o valor da descrio.
Instanciar sem argumentos vai retornar o valor atual:

158

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

// Define mltiplas linhas de uma vez


$parser->description(['line one', 'line two']);
// L o valor atual
$parser->description();

Cake\Console\ConsoleOptionParser::epilog($text = null)
Recebe ou define o eplogo para o interpretador de opes. O eplogo exibido depois da informao do
argumento e da opo. Ao instanciar tanto em array como em string, voc pode definir o valor do eplogo.
Instanciar sem argumentos vai retornar o valor atual:
// Define mltiplas linhas de uma vez
$parser->epilog(['line one', 'line two']);
// L o valor atual
$parser->epilog();

Adicionando argumentos
Cake\Console\ConsoleOptionParser::addArgument($name, $params =[])
Argumentos posicionais so frequentemente usados em ferramentas de linha de comando, e
ConsoleOptionParser permite definir argumentos bem como torn-los requirveis. Voc pode adicionar argumentos um por vez com $parser->addArgument(); ou mltiplos de uma vez com
$parser->addArguments();:
$parser->addArgument('model', ['help' => 'The model to bake']);

Voc pode usar as seguintes opes ao criar um argumento:


help O texto de ajuda a ser exibido para este argumento.
required Se esse parmetro requisito.
index O ndice do argumento, se deixado indefinido, o argumento ser colocado no final dos argumentos. Se voc definir o mesmo ndice duas vezes, a primeira opo ser sobreescrita.
choices Um array de opes vlidas para esse argumento. Se deixado vazio, todos os valores so
vlidos. Uma exceo ser lanada quando parse() encontrar um valor invlido.
Argumentos que forem definidos como requisito lanaro uma exceo quando interpretarem o comando se
eles forem omitidos. Ento voc no tem que lidar com isso em sua shell.
Cake\Console\ConsoleOptionParser::addArguments(array $args)
Se voc tem um array com mltiplos argumentos voc pode usar $parser->addArguments() para
adicion-los de uma vez.:
$parser->addArguments([
'node' => ['help' => 'The node to create', 'required' => true],
'parent' => ['help' => 'The parent node', 'required' => true]
]);

Opes de configurao e Gerao de ajuda

159

CakePHP Cookbook Documentation, Verso 3.x

Assim como todos os mtodos de construo no ConsoleOptionParser, addArguments pode ser usado como
parte de um fluido mtodo encadeado.

Validando argumentos
Ao criar argumentos posicionais, voc pode usar a marcao required para indicar que um argumento
deve estar presente quando uma shell chamada. Adicionalmente voc pode usar o choices para forar
um argumento a ser de uma lista de escolhas vlidas:
$parser->addArgument('type', [
'help' => 'The type of node to interact with.',
'required' => true,
'choices' => ['aro', 'aco']
]);

O cdigo acima ir criar um argumento que requisitado e tem validao no input. Se o argumento est
tanto indefinodo, ou possui um valor incorreto, uma exceo ser lanada e a shell parar.

Adicionando opes
Cake\Console\ConsoleOptionParser::addOption($name, $options =[])
Opes so frequentemente usadas em ferramentas CLI. ConsoleOptionParser suporta a criao de
opes com verbose e aliases curtas, suprindo padres e criando ativadores boleanos. Opes so criadas
tanto com $parser->addOption() ou $parser->addOptions().:
$parser->addOption('connection', [
'short' => 'c',
'help' => 'connection',
'default' => 'default',
]);

O cdigo citado permite a voc usar tanto cake myshell --connection=other, cake myshell
--connection other, ou cake myshell -c other quando invocando a shell. Voc tambm
criar ativadores boleanos. Estes ativadores no consumem valores, e suas presenas apenas os habilitam nos
parmetros interpretados.:
$parser->addOption('no-commit', ['boolean' => true]);

Com essa opo, ao chamar uma shell como cake myshell --no-commit something o parmetro
no-commit deve ter um valor de true, e something deve ser tratado como um argumento posicional. As
opes nativas --help, --verbose, e --quiet usam essa funcionalidade.
Ao criar opes voc pode usar os seguintes argumentos para definir o seu comportamento:
short - A variao de letra nica para essa opo, deixe indefinido para none.
help - Texto de ajuda para essa opo. Usado ao gerar ajuda para a opo.
default - O valor padro para essa opo. Se no estiver definido o valor padro ser true.
boolean - A opo no usa valor, apenas um ativador boleano. Por padro false.
160

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

choices - Um array de escolhas vlidas para essa opo. Se deixado vazio, todos os valores so
considerados vlidos. Uma exceo ser lanada quando parse() encontrar um valor invlido.
Cake\Console\ConsoleOptionParser::addOptions(array $options)
Se voc tem um array com mltiplas opes, voc pode usar $parser->addOptions() para adicionlas de uma vez.:
$parser->addOptions([
'node' => ['short' => 'n', 'help' => 'The node to create'],
'parent' => ['short' => 'p', 'help' => 'The parent node']
]);

Assim como com todos os mtodos construtores, no ConsoleOptionParser, addOptions pode ser usado como
parte de um mtodo fluente encadeado.

Validando opes
Opes podem ser fornecidas com um conjunto de escolhas bem como argumentos posicionais podem ser.
Quando uma opo define escolhas, essas so as nicas opes vlidas para uma opo. Todos os outros
valores iro gerar um InvalidArgumentException:
$parser->addOption('accept', [
'help' => 'What version to accept.',
'choices' => ['working', 'theirs', 'mine']
]);

Usando opes boleanas


As opes podem ser definidas como opes boleanas, que so teis quando voc precisa criar algumas
opes de marcao. Como opes com padres, opes boleanas sempre iro incluir -se nos parmetros
analisados. Quando as marcaes esto presentes elas so definidas para true, quando elas esto ausentes,
so definidas como false:
$parser->addOption('verbose', [
'help' => 'Enable verbose output.',
'boolean' => true
]);

A opo seguinte resultaria em $this->params[verbose] sempre estando disponvel. Isso permite


a voc omitir verificaes empty() ou isset() em marcaes boleanas:
if ($this->params['verbose']) {
// Do something.
}

Desde que as opes boleanas estejam sempre definidas como true ou false, voc pode omitir mtodos
de verificao adicionais.

Opes de configurao e Gerao de ajuda

161

CakePHP Cookbook Documentation, Verso 3.x

Adicionando subcomandos
Cake\Console\ConsoleOptionParser::addSubcommand($name, $options =[])
Aplicativos de console so muitas vezes feitas de subcomandos, e esses subcomandos podem exigir a anlise
de opes especiais e terem a sua prpria ajuda. Um perfeito exemplo disso bake. Bake feita de muitas
tarefas separadas e todas tm a sua prpria ajuda e opes. ConsoleOptionParser permite definir
subcomandos e fornecer comandos analisadores de opo especfica, de modo que a shell sabe como analisar
os comandos para as suas funes:
$parser->addSubcommand('model', [
'help' => 'Bake a model',
'parser' => $this->Model->getOptionParser()
]);

A descrio acima um exemplo de como voc poderia fornecer ajuda e um especializado interpretador de
opo para a tarefa de uma shell. Ao chamar a tarefa de getOptionParser() no temos de duplicar a
gerao do interpretador de opo, ou misturar preocupaes no nosso shell. Adicionar subcomandos desta
forma tem duas vantagens. Primeiro, ele permite que o seu shell documente facilmente seus subcomandos
na ajuda gerada. Ele tambm d fcil acesso ao subcomando help. Com o subcomando acima criado
voc poderia chamar cake myshell --help e ver a lista de subcomandos, e tambm executar o cake
myshell model --help para exibir a ajuda apenas o modelo de tarefa.
Nota: Uma vez que seu Shell define subcomandos, todos os subcomandos deve ser explicitamente
definidos.
Ao definir um subcomando, voc pode usar as seguintes opes:
help - Texto de ajuda para o subcomando.
parser - Um ConsoleOptionParser para o subcomando. Isso permite que voc crie mtodos analisadores de opo especfios. Quando a ajuda gerada por um subcomando, se um analisador est
presente ele vai ser usado. Voc tambm pode fornecer o analisador como uma matriz que seja compatvel com Cake\Console\ConsoleOptionParser::buildFromArray()
Adicionar subcomandos pode ser feito como parte de uma cadeia de mtodos fluente.

Construir uma ConsoleOptionParser de uma matriz


Cake\Console\ConsoleOptionParser::buildFromArray($spec)
Como mencionado anteriormente, ao criar interpretadores de opo de subcomando, voc pode definir a
especificao interpretadora como uma matriz para esse mtodo. Isso pode ajudar fazer analisadores mais
facilmente, j que tudo um array:
$parser->addSubcommand('check', [
'help' => __('Check the permissions between an ACO and ARO.'),
'parser' => [
'description' => [
__("Use this command to grant ACL permissions. Once executed, the "),
__("ARO specified (and its children, if any) will have ALLOW access "),

162

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

__("to the specified ACO action (and the ACO's children, if any).")
],
'arguments' => [
'aro' => ['help' => __('ARO to check.'), 'required' => true],
'aco' => ['help' => __('ACO to check.'), 'required' => true],
'action' => ['help' => __('Action to check')]
]
]
]);

Dentro da especificao do interpretador, voc pode definir as chaves para arguments,


options, description e epilog.
Voc no pode definir subcommands dentro de um construtor estilo array.
Os valores para os argumentos e opes, devem
seguir o formato que Cake\Console\ConsoleOptionParser::addArguments() e
Cake\Console\ConsoleOptionParser::addOptions() usam.
Voc tambm pode usar
buildFromArray por conta prpria, para construir um interpretador de opo:
public function getOptionParser()
{
return ConsoleOptionParser::buildFromArray([
'description' => [
__("Use this command to grant ACL permissions. Once executed, the "),
__("ARO specified (and its children, if any) will have ALLOW access "),
__("to the specified ACO action (and the ACO's children, if any).")
],
'arguments' => [
'aro' => ['help' => __('ARO to check.'), 'required' => true],
'aco' => ['help' => __('ACO to check.'), 'required' => true],
'action' => ['help' => __('Action to check')]
]
]);
}

Recebendo ajuda das Shells


Com a adio de ConsoleOptionParser receber ajuda de shells feito de uma forma consistente e uniforme.
Ao usar a opo --help ou -h voc pode visualizar a ajuda para qualquer ncleo shell, e qualquer shell
que implementa um ConsoleOptionParser:
cake bake --help
cake bake -h

Ambos devem gerar a ajuda para o bake. Se o shell suporta subcomandos voc pode obter ajuda para estes
de uma forma semelhante:
cake bake model --help
cake bake model -h

Isso deve fornecer a voc a ajuda especfica para a tarefa bake dos models.

Opes de configurao e Gerao de ajuda

163

CakePHP Cookbook Documentation, Verso 3.x

Recebendo ajuda como XML


Quando a construo de ferramentas automatizadas ou ferramentas de desenvolvimento que necessitam
interagir com shells do CakePHP, bom ter ajuda disponvel em uma mquina capaz interpretar formatos.
O ConsoleOptionParser pode fornecer ajuda em xml, definindo um argumento adicional:
cake bake --help xml
cake bake -h xml

O trecho acima deve retornar um documento XML com a ajuda gerada, opes, argumentos e subcomando
para o shell selecionado. Um documento XML de amostra seria algo como:
<?xml version="1.0"?>
<shell>
<command>bake fixture</command>
<description>Generate fixtures for use with the test suite. You can use
`bake fixture all` to bake all fixtures.</description>
<epilog>
Omitting all arguments and options will enter into an interactive
mode.
</epilog>
<subcommands/>
<options>
<option name="--help" short="-h" boolean="1">
<default/>
<choices/>
</option>
<option name="--verbose" short="-v" boolean="1">
<default/>
<choices/>
</option>
<option name="--quiet" short="-q" boolean="1">
<default/>
<choices/>
</option>
<option name="--count" short="-n" boolean="">
<default>10</default>
<choices/>
</option>
<option name="--connection" short="-c" boolean="">
<default>default</default>
<choices/>
</option>
<option name="--plugin" short="-p" boolean="">
<default/>
<choices/>
</option>
<option name="--records" short="-r" boolean="1">
<default/>
<choices/>
</option>
</options>
<arguments>
<argument name="name" help="Name of the fixture to bake.

164

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

Can use Plugin.name to bake plugin fixtures." required="">


<choices/>
</argument>
</arguments>
</shell>

Roteamento em Shells / CLI


Na interface de linha de comando (CLI), especificamente suas shells e tarefas, env(HTTP_HOST) e
outras variveis de ambiente webbrowser especfica, no esto definidas.
Se voc gerar relatrios ou enviar e-mails que fazem uso de Router::url(), estes contero a mquina
padro http://localhost/ e resultando assim em URLs invlidas. Neste caso, voc precisa especificar o domnio manualmente. Voc pode fazer isso usando o valor de configurao App.fullBaseURL
no seu bootstrap ou na sua configurao, por exemplo.
Para enviar e-mails, voc deve fornecer a classe CakeEmail com o host que voc deseja enviar o e-mail:
$Email = new CakeEmail();
$Email->domain('www.example.org');

Iste afirma que os IDs de mensagens geradas so vlidos e adequados para o domnio a partir do qual os
e-mails so enviados.

Mtodos enganchados
Cake\Console\ConsoleOptionParser::initialize()
Inicializa a Shell para atua como construtor de subclasses e permite configurao de tarefas antes de
desenvolver a execuo.
Cake\Console\ConsoleOptionParser::startup()
Inicia-se a Shell e exibe a mensagem de boas-vindas. Permite a verificao e configurao antes de
comandar ou da execuo principal.
Substitua este mtodo se voc quiser remover as informaes de boas-vindas, ou outra forma modificar o fluxo de pr-comando.

Mais tpicos
Shell Helpers
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
1

https://github.com/cakephp/docs

Roteamento em Shells / CLI

165

CakePHP Cookbook Documentation, Verso 3.x

Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Console Interativo (REPL)


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Executando Shells como Cron Jobs


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

I18N Shell
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Completion Shell
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github5 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
2

https://github.com/cakephp/docs
https://github.com/cakephp/docs
4
https://github.com/cakephp/docs
5
https://github.com/cakephp/docs
3

166

Captulo 16. Console e Shells

CakePHP Cookbook Documentation, Verso 3.x

Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Plugin Shell
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github6 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Routes Shell
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github7 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Upgrade Shell
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github8 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs
https://github.com/cakephp/docs
8
https://github.com/cakephp/docs
7

Mais tpicos

167

CakePHP Cookbook Documentation, Verso 3.x

168

Captulo 16. Console e Shells

CAPTULO 17

Debugging

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

169

CakePHP Cookbook Documentation, Verso 3.x

170

Captulo 17. Debugging

CAPTULO 18

Implantao

Uma vez que sua aplicao est completa, ou mesmo antes quando voc quiser coloc-la no ar. Existem
algumas poucas coisas que voc deve fazer quando colocar em produo uma aplicao CakePHP.

Atualizar config/app.php
Atualizar o arquivo core.php, especificamente o valor do debug de extrema importncia. Tornar o debug
igual a false desabilita muitos recursos do processo de desenvolvimento que nunca devem ser expostos
ao mundo. Desabilitar o debug, altera as seguintes coisas:
Mensagens de depurao criadas com pr() e debug() sero desabilitadas.
O cache interno do CakePHP ser descartado aps 999 dias ao invs de ser a cada 10 segundos como
em desenvolvimento.
Views de erros sero menos informativas, retornando mensagens de erros genricas.
Erros do PHP no sero mostrados.
O rastreamento de stack traces (conjunto de excees) ser desabilitado.
Alm dos itens citados acima, muitos plugins e extenses usam o valor do debug para modificarem seus
comportamentos.
Por exemplo, voc pode setar uma varivel de ambiente em sua configurao do Apache:
SetEnv CAKEPHP_DEBUG 1

E ento voc pode definir o level de debug dinamicamente no config/app.php:


$debug = (bool)getenv('CAKEPHP_DEBUG');
return [
'debug' => $debug,
.....
];

171

CakePHP Cookbook Documentation, Verso 3.x

Checar a segurana
Se voc est jogando sua aplicao na selva, uma boa idia certificar-se que ela no possui vulnerabilidades
bvias:
Certifique-se de utilizar o Cross Site Request Forgery.
Voc pode querer habilitar o Security. Isso pode prevenir diversos tipos de adulterao de formulrios
e reduzir a possibilidade de overdose de requisies.
Certifique-se que seus models possuem as regras Validao de validao habilitadas.
Verifique se apenas o seu diretrio webroot visvel publicamente, e que seus segredos (como seu
app salt, e qualquer chave de segurana) so privados e nicos tambm.

Definir a raiz do documento


Definir a raiz do documento da sua aplicao corretamente um passo importante para manter seu cdigo
protegido e sua aplicao mais segura. As aplicaes desenvolvidas com o CakePHP devem ter a raiz
apontando para o diretrio webroot. Isto torna a aplicao e os arquivos de configuraes inacessveis
via URL. Configurar a raiz do documento depende de cada servidor web. Veja a Reescrita de URL para
informaes sobre servidores web especficos.
De qualquer forma voc vai querer definir o host/domnio virtual para o webroot/. Isso remove a possibilidade de arquivos fora do diretrio raiz serem executados.

Aprimorar a performance de sua aplicao


O carregamento de classes pode alocar facilmente o tempo de processamento de sua aplicao. A fim de
evitar esse problema, recomendado que voc execute este comando em seu servidor de produo uma vez
que a aplicao esteja implantada:
php composer.phar dumpautoload -o

Sabendo que manipulao de referncias estticas, como imagens, JavaScript e arquivos CSS, plugins,
atravs do Dispatcher incrivelmente ineficiente, fortemente recomendado referenci-los simbolicamente para produo. Por exemplo:
ln -s Plugin/YourPlugin/webroot/css/yourplugin.css webroot/css/yourplugin.css

172

Captulo 18. Implantao

CAPTULO 19

Email

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

173

CakePHP Cookbook Documentation, Verso 3.x

174

Captulo 19. Email

CAPTULO 20

Erros & Excees

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

175

CakePHP Cookbook Documentation, Verso 3.x

176

Captulo 20. Erros & Excees

CAPTULO 21

Sistema de eventos

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

177

CakePHP Cookbook Documentation, Verso 3.x

178

Captulo 21. Sistema de eventos

CAPTULO 22

Internacionalizao e Localizao

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

179

CakePHP Cookbook Documentation, Verso 3.x

180

Captulo 22. Internacionalizao e Localizao

CAPTULO 23

Logging

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

181

CakePHP Cookbook Documentation, Verso 3.x

182

Captulo 23. Logging

CAPTULO 24

Formulrios sem models

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

183

CakePHP Cookbook Documentation, Verso 3.x

184

Captulo 24. Formulrios sem models

CAPTULO 25

Pagination

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

185

CakePHP Cookbook Documentation, Verso 3.x

186

Captulo 25. Pagination

CAPTULO 26

Plugins

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

187

CakePHP Cookbook Documentation, Verso 3.x

188

Captulo 26. Plugins

CAPTULO 27

REST

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

189

CakePHP Cookbook Documentation, Verso 3.x

190

Captulo 27. REST

CAPTULO 28

Segurana

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Segurana
Choosing a Specific Crypto Implementation
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Cross Site Request Forgery


Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github3 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
1

https://github.com/cakephp/docs
https://github.com/cakephp/docs
3
https://github.com/cakephp/docs
2

191

CakePHP Cookbook Documentation, Verso 3.x

Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Security
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github4 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

192

Captulo 28. Segurana

CAPTULO 29

Sessions

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

193

CakePHP Cookbook Documentation, Verso 3.x

194

Captulo 29. Sessions

CAPTULO 30

Testing

O CakePHP vem com suporte interno para testes e integrao para o PHPUnit1 . Em adio aos recursos
oferecidos pelo PHPUnit, o CakePHP oferece alguns recursos adicionais para fazer testes mais facilmente.
Esta seo abordar a instalao do PHPUnit, comeando com testes unitrios e como voc pode usar as
extenses que o CakePHP oferece.

Instalando o PHPUnit
O CakePHP usa o PHPUnit como framework de teste bsico. O PHPUnit um padro para testes unitrios
em PHP. Ele oferece um profundo e poderoso conjunto de recursos para voc ter certeza que o seu cdigo
faz o que voc acha que ele faz. O PHPUnit pode ser instalado usando o PHAR package2 ou Composer3 .

Instalando o PHPUnit com Composer


Para instalar o PHPUnit com Composer:
$ php composer.phar require --dev phpunit/phpunit

Isto adicionar a dependncia para a seo require-dev do seu composer.json, e depois instalar o
PHPUnit com qualquer outra dependncia.
Agora voc executa o PHPUnit usando:
$ vendor/bin/phpunit

Usando o arquivo PHAR


Depois de ter baixado o arquivo phpunit.phar , voc pode usar ele para executar seus testes:
1

http://phpunit.de
http://phpunit.de/#download
3
http://getcomposer.org
2

195

CakePHP Cookbook Documentation, Verso 3.x

php phpunit.phar

Dica: Como convenincia voc pode deixar phpunit.phar disponivel globalmente em sistemas Unix ou
Linux com os comandos:
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version

Por favor, consulte a documentao do PHPUnit para instrues sobre como instalar globalmente o PHPUnit
PHAR em sistemas Windows4 .

Configurao do banco de dados test


Lembre-se de ter o debug abilitado em seu arquivo config/app.php antes de executar qualquer teste. Antes
de executar quaisquer testes voc deve adicionar um datasourse test para o arquivo config/app.php. Esta
configurao usada pelo CakePHP para fixar tabelas e dados:
'Datasources' => [
'test' => [
'datasource' => 'Cake\Database\Driver\Mysql',
'persistent' => false,
'host' => 'dbhost',
'username' => 'dblogin',
'password' => 'dbpassword',
'database' => 'test_database'
],
],

Controller Integration Testing


Nota: uma boa ideia usar bancos de dados diferentes para o banco de testes e para o banco de desenvolvimento. Isto evitara erros mais tarde.

http://phpunit.de/manual/current/en/installation.html#installation.phar.windows

196

Captulo 30. Testing

CAPTULO 31

Validao

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

197

CakePHP Cookbook Documentation, Verso 3.x

198

Captulo 31. Validao

CAPTULO 32

App Class

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

199

CakePHP Cookbook Documentation, Verso 3.x

200

Captulo 32. App Class

CAPTULO 33

Collections (Colees)

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

201

CakePHP Cookbook Documentation, Verso 3.x

202

Captulo 33. Collections (Colees)

CAPTULO 34

Arquivos & Pastas

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

203

CakePHP Cookbook Documentation, Verso 3.x

204

Captulo 34. Arquivos & Pastas

CAPTULO 35

Hash

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

205

CakePHP Cookbook Documentation, Verso 3.x

206

Captulo 35. Hash

CAPTULO 36

Http Client

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

207

CakePHP Cookbook Documentation, Verso 3.x

208

Captulo 36. Http Client

CAPTULO 37

Inflector

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

209

CakePHP Cookbook Documentation, Verso 3.x

210

Captulo 37. Inflector

CAPTULO 38

Nmero

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

211

CakePHP Cookbook Documentation, Verso 3.x

212

Captulo 38. Nmero

CAPTULO 39

Objetos de Registro

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

213

CakePHP Cookbook Documentation, Verso 3.x

214

Captulo 39. Objetos de Registro

CAPTULO 40

Texto

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

215

CakePHP Cookbook Documentation, Verso 3.x

216

Captulo 40. Texto

CAPTULO 41

Tempo

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

217

CakePHP Cookbook Documentation, Verso 3.x

218

Captulo 41. Tempo

CAPTULO 42

Xml

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

219

CakePHP Cookbook Documentation, Verso 3.x

220

Captulo 42. Xml

CAPTULO 43

Constantes e Funes

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

221

CakePHP Cookbook Documentation, Verso 3.x

222

Captulo 43. Constantes e Funes

CAPTULO 44

Debug Kit

DebugKit um plugin suportado pelo time principal que oferece uma barra de ferramentas para ajudar a
fazer a depurao de aplicaes do CakePHP mais facilmente.

Instalao
Por padro o DebugKit instalado com com o esqueleto padro da aplicao. Se voc o removeu e gostaria
de reinstal-lo, voc pode faz-lo ao executar o seguinte comando a partir do diretrio raiz da aplicao
(onde o arquivo composer.json est localizado):
php composer.phar require --dev cakephp/debug_kit "~3.0"

Then, you need to enable the plugin by executing the following line:
bin/cake plugin load DebugKit

Armazenamento do DebugKit
Por padro, o DebugKit usa um pequeno banco de dados SQLite no diretrio /tmp de sua aplicao para
armazenar os dados do painel. Se voc quizesse que o DebugKit armazenasse seus dados em outro lugar,
voc deve definir uma conexo debug_kit.

Configurao doe banco de dados


Por padro, o DebugKit armazenar os dados do painel em um banco de dados SQLite no diretrio /tmp
de sua aplicao. Se voc no puder instalar a extenso do PHP pdo_sqlite, voc pode configurar o DebugKit para usar um banco de dados diferente ao definir uma conexo debug_kit em seu arquivo config/app.php.

223

CakePHP Cookbook Documentation, Verso 3.x

Uso da barra de ferramentas


A Barra de Ferramentas DebugKit composta por vrios painis, que so mostrados ao clicar no cone
do CakePHP no canto inferior direito da janela do seu navegador. Uma vez que a barra de ferramentas
aberta, voc deve ver uma srie de botes. Cada um desses botes expande-se em um painel de informaes
relacionadas.
Cada painel permite que voc olhar para um aspecto diferente da sua aplicao:
Cache Exibe o uso de cache durante uma solicitao e limpa caches.
Environment Exibe variveis de ambiente relacionadas com PHP + CakePHP.
History Exibe uma lista de requisies anteriores, e permite que voc carregue e veja dados da barra
de ferramentas a partir de solicitaes anteriores.
Include Exibe os arquivos inclusos divididos por grupo.
Log Exibe todas as entradas feitas nos arquivos de log este pedido.
Request Exibe informaes sobre a requisio atual, GET, POST, informaes sobre a rota atual do
Cake e Cookies.
Session Exibe a informao atual da sesso.
Sql Logs Exibe logs SQL para cada conexo com o banco de dados.
Timer Exibe qualquer temporizador que fora definido durante a requisio com
DebugKit\DebugTimer, e memria utilizada coletada com DebugKit\DebugMemory.
Variables Exibe variveis de View definidas em um Controller.
Tipicamente, um painel manipula a recolha e apresentao de um nico tipo de informaes como logs
ou informaes de requisies. Voc pode optar por visualizar painis padro da barra de ferramentas ou
adicionar seus prprios painis personalizados.

Usando o painel History


O painel History uma das mais frequentemente confundidas caractersticas do DebugKit. Ele oferece uma
forma de visualizar os dados da barra de ferramentas de requisies anteriores, incluindo erros e redirecionamentos.
Como voc pode ver, o painel contm uma lista de requisies. Na esquerda voc pode ver um ponto
marcando a requisio ativa. Clicar em quaisquer dados de requisio vai carregar os dados do painel para
aquela requisio. Quando os dados so carregados, os ttulos do painel vo sofrer uma transio para
indicar que dados alternativos foram carregados.

Desenvolvendo seus prprios painis


Voc pode criar seus prprios painis customizados para o DebugKit para ajudar na depurao de suas
aplicaes.
224

Captulo 44. Debug Kit

CakePHP Cookbook Documentation, Verso 3.x

Criando uma Panel Class


Panel Classes precisam ser colocadas no diretrio src/Panel. O nome do arquivo deve combinar com o nome
da classe, ento a classe MyCustomPanel deveria ter o nome de arquivo src/Panel/MyCustomPanel.php:
namespace App\Panel;
use DebugKit\DebugPanel;
/**
* My Custom Panel
*/
class MyCustomPanel extends DebugPanel
{
...
}

Perceba que painis customizados so necessrios para extender a classe DebugPanel.

Callbacks
Por padro objetos do painel possuem dois callbacks, permitindo-lhes acoplar-se na requisio atual. Painis
inscrevem-se aos eventos Controller.initialize e Controller.shutdown. Se o seu painel
precisa inscrever-se a eventos adicionais, voc pode usar o mtodo implementedEvents para definir
todos os eventos que o seu painel possa estar interessado.
Voc deveria estudar os painis nativos para absorver alguns exemplos de como construir painis.
Desenvolvendo seus prprios painis

225

CakePHP Cookbook Documentation, Verso 3.x

Elementos do painel
Cada painel deve ter um elemento view que renderiza o contedo do mesmo. O nome do elemento deve
ser sublinhado e flexionado a partir do nome da classe. Por exemplo SessionPanel possui um elemento nomeado session_panel.ctp, e SqllogPanel possui um elemento nomeado sqllog_panel.ctp. Estes
elementos devem estar localizados na raiz do seu diretrio src/Template/Element.

Ttulos personalizados e Elementos


Os painis devem pegar o seu ttulo e nome do elemento por conveno. No entanto, se voc precisa escolher
um nome de elemento personalizado ou ttulo, voc pode definir mtodos para customizar o comportamento
do seu painel:
title() - Configure o ttulo que exibido na barra de ferramentas.
elementName() - Configure qual elemento deve ser utilizada para um determinado painel.

Painis em outros plugins


Painis disponibilizados por Plugins funcionam quase que totalmente como outros plugins, com uma pequena diferena: Voc deve definir public $plugin para ser o nome do diretrio do plugin, com isso
os elementos do painel podero ser encontrados no momento de renderizao:
namespace MyPlugin\Panel;
use DebugKit\DebugPanel;
class MyCustomPanel extends DebugPanel
{
public $plugin = 'MyPlugin';
...
}

Para usar um plugin ou painel da aplicao, atualize a configurao do DebugKit de sua aplicao para
incluir o painel:
Configure::write(
'DebugKit.panels',
array_merge(Configure::read('DebugKit.panels'), ['MyCustomPanel'])
);

O cdigo acima deve carregar todos os painis padro tanto como os outros painis customizados do
MyPlugin.

226

Captulo 44. Debug Kit

CAPTULO 45

Migrations

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

https://github.com/cakephp/docs

227

CakePHP Cookbook Documentation, Verso 3.x

228

Captulo 45. Migrations

CAPTULO 46

Apndices

Os apndices contm informaes sobre os novos recursos introduzidos em cada verso e a forma de executar a migrao entre verses.

Guia de Migrao para a verso 3.x


3.x Migration Guide
Migration guides contain information regarding the new features introduced in each version and the migration path between versions.
3.2 Migration Guide
3.2 Guia de migrao

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github1 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

3.1 Migration Guide


3.1 Guia de migrao

https://github.com/cakephp/docs

229

CakePHP Cookbook Documentation, Verso 3.x

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github2 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

3.0 Migration Guide


3.0 - Guia de migrao

Esta pgina resume as alteraes do CakePHP 2.x e ir auxiliar na migrao do seu projeto para a verso 3.0,
e tambm ser uma referncia para atualiz-lo quanto s principais mudanas do branch 2.x. Certifique-se
de ler tambm as outras pginas nesse guia para conhecer todas as novas funcionalidades e mudanas na
API.
Requerimentos
O CakePHP 3.x suporta o PHP 5.4.16 e acima.
O CakePHP 3.x precisa da extenso mbstring.
O CakePHP 3.x precisa da extenso intl.
Aviso: O CakePHP 3.0 no ir funcionar se voc no atender aos requisitos acima.

Ferramenta de atualizao Enquanto este documento cobre todas as alteraes e melhorias feitas no
CakePHP 3.0, ns tambm criamos uma aplicao de console para ajudar voc a completar mais facilmente
algumas das alteraes mecnicas que consomem tempo. Voc pode pegar a ferramenta de atualizao no
github3 .
Layout do diretrio da aplicao O Layout do diretrio da aplicao mudou e agora segue o PSR-44 .
Voc deve usar o projeto do esqueleto da aplicao5 como um ponto de referncia quando atualizar sua
aplicao.
O CakePHP deve ser instalado via Composer Como o CakePHP no pode mais ser instalado facilmente
via PEAR, ou em um diretrio compartilhado, essas opes no so mais suportadas. Ao invs disso, voc
deve usar o Composer6 para instalar o CakePHP em sua aplicao.
2

https://github.com/cakephp/docs
https://github.com/cakephp/upgrade
4
http://www.php-fig.org/psr/psr-4/
5
https://github.com/cakephp/app
6
http://getcomposer.org
3

230

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

Namespaces Todas as classes do core do CakePHP agora usam namespaces e seguem as especificaes de autoload (auto-carregamento) do PSR-4. Por exemplo src/Cache/Cache.php tem o namespace
Cake\Cache\Cache. Constantes globais e mtodos de helpers como __() e debug() no usam
namespaces por questes de convenincia.
Constantes removidas As seguintes constantes obsoletas foram removidas:
IMAGES
CSS
JS
IMAGES_URL
JS_URL
CSS_URL
DEFAULT_LANGUAGE
Configurao As configuraes no CakePHP 3.0 esto significativamente diferentes que nas verses anteriores. Voc deve ler a documentao Configurao para ver como a configurao feita.
Voc no pode mais usar o App::build() para configurar caminhos adicionais de classes. Ao invs
disso, voc deve mapear caminhos adicionais usando o autoloader da sua aplicao. Veja a seo Caminhos
de Classes Adicionais para mais informaes.
Trs novas variveis de configurao fornecem o caminho de configurao para plugins, views
e arquivos de localizao. Voc pode adicionar vrios caminhos em App.paths.templates,
App.paths.plugins, App.paths.locales para configurar mltiplos caminhos para templates,
plugins e arquivos de localizao respectivamente.
A chave de configurao www_root mudou para wwwRoot devido a consistncia. Por favor, ajuste seu arquivo de configurao app.php assim como qualquer uso de Configure::read(App.wwwRoot).
Novo ORM O CakePHP 3.0 possui um novo ORM que foi refeito do zero. O novo ORM significativamente diferente e incompatvel com o anterior. Migrar para o novo ORM necessita de alteraes extensas
em qualquer aplicao que esteja sendo atualizada. Veja a nova documentao Models (Modelos) para
informaes de como usar o novo ORM.
Bsico
O LogError() foi removido, ele no tinha vantagens e era raramente ou mesmo, nunca usado.
As seguintes funes globais foram removidas: config(), cache(), clearCache(),
convertSlashes(), am(), fileExistsInPath(), sortByKey().

Guia de Migrao para a verso 3.x

231

CakePHP Cookbook Documentation, Verso 3.x

Debug
A funo Configure::write(debug, $bool) no suporta mais 0/1/2. Um boleano simples usado para mudar o modo de debug para ligado ou desligado.
Especificaes/Configuraes de objetos
Os objetos usados no CakePHP agora tem um sistema consistente de armazenamento/recuperao
de configurao-de-instncia.
Os cdigos que anteriormente acessavam, por exemplo
$object->settings, devem ser atualizados para usar $object->config() alternativamente.
Cache
Memcache foi removido, use Cake\Cache\Cache\Engine\Memcached alternativamente.
Cache engines so carregados sob demanda no primeiro uso.
Cake\Cache\Cache::engine() foi adicionado.
Cake\Cache\Cache::enabled() foi adicionado.
Cache.disable.

Substituindo a opo de configurao

Cake\Cache\Cache::enable() foi adicionado.


Cake\Cache\Cache::disable() foi adicionado.
Configurao de cache agora imutvel. Se voc precisa alterar a configurao, ser necessrio
desfazer-se da configurao e recri-la. Isso previne problemas de sincronizao com as opes de
configurao.
Cache::set() foi removido. recomendado criar mltiplas configuraes de cache para substituir
ajustes de configurao em tempo de execuo anteriormente possveis com Cache::set().
Todas as subclasses CacheEngine agora implementam um mtodo config().
Cake\Cache\Cache::readMany(),
Cake\Cache\Cache::deleteMany(),
Cake\Cache\Cache::writeMany() foram adicionados.

Todos os mtodos Cake\Cache\Cache\CacheEngine agora so responsveis por manipular o prefixo


chave configurado. O Cake\Cache\CacheEngine::write() no mais permite definir a durao na
escrita, a durao captada pela configurao de tempo de execuo do mecanismo de cache. Chamar um
mtodo cache com uma chuva vazia ir lanar uma InvalidArgumentException ao invs de retornar
false.
Core
App
App::pluginPath() foi removido. Use CakePlugin::path() alternativamente.
App::build() foi removido.

232

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

App::location() foi removido.


App::paths() foi removido.
App::load() foi removido.
App::objects() foi removido.
App::RESET foi removido.
App::APPEND foi removido.
App::PREPEND foi removido.
App::REGISTER foi removido.
Plugin
O Cake\Core\Plugin::load() no configura a carga automtica a menos que voc defina a
opo autoload como true.
Quanto estiver carregando plugins voc no pode mais fornecer um callable.
Quanto estiver carregando plugins voc no pode mais fornecer um array de arquivos de configurao
para carregar.
Configure
O Cake\Configure\PhpReader foi renomeado para Cake\Core\Configure\EnginePhpConfig
O Cake\Configure\IniReader foi renomeado para Cake\Core\Configure\EngineIniConfig
O
Cake\Configure\ConfigReaderInterface
Cake\Core\Configure\ConfigEngineInterface

foi

renomeado

para

O Cake\Core\Configure::consume() foi adicionado.


O Cake\Core\Configure::load() agora espera o nome de arquivo sem o sufixo de extenso
como isso pode ser derivado do mecanismo. Ex.: para usar o PhpConfig use app para carregar
app.php.
Definir
uma
varivel
$config
no
arquivo
PHP
config
est
obsoleto.
Cake\Core\Configure\EnginePhpConfig agora espera que o arquivo de configurao
retorne um array.
Um novo mecanismo de configurao Cake\Core\Configure\EngineJsonConfig foi adicionado.
Object A classe Object foi removida. Ela anteriormente continha um monte de mtodos que
eram utilizados em vrios locais no framework. O mais til destes mtodos foi extraido como
um trait.
Voc pode usar o Cake\Log\LogTrait para acessar o mtodo log().
O
Cake\Routing\RequestActionTrait fornece o mtodo requestAction().

Guia de Migrao para a verso 3.x

233

CakePHP Cookbook Documentation, Verso 3.x

Console O executvel cake foi movido do diretrio app/Console para o diretrio bin dentro do
esqueleto da aplicao. Voc pode agora invocar o console do CakePHP com bin/cake.
TaskCollection Substitudo Essa classe foi renomeada para Cake\Console\TaskRegistry. Veja
a seo em Objetos de Registro para mais informaes sobre funcionalidades fornecidas pela nova classe.
Voc pode usar o cake upgrade rename_collections para ajuda ao atualizar seu cdigo. Tarefas
no tem mais acesso a callbacks, como nunca houve nenhum callback para se usar.
Shell
O Shell::__construct()
Cake\Console\ConsoleIo.

foi

alterado.

Ele

agora

usa

uma

instncia

de

O Shell::param() foi adicionado como um acesso conveniente aos parmetros.


Adicionalmente todos os mtodos shell sero transformados em camel case quando invocados. Por exemplo,
se voc tem um mtodo hello_world() dentro de um shell e chama ele com bin/cake my_shell
hello_world, voc ter que renomear o mtodo para helloWorld. No h necessidade de mudanas
no modo que voc chama os mtodos/comandos.
ConsoleOptionParser
O ConsoleOptionParser::merge() foi adicionado para mesclar os parsers.
ConsoleInputArgument
O ConsoleInputArgument::isEqualTo() foi adicionado para comparar dois argumentos.
Shell / Tarefa Os Shells e Tarefas foram movidas de Console/Command
Console/Command/Task para Shell e Shell/Task, respectivamente.

ApiShell Removido O ApiShell foi removido pois ele no fornecia nenhum beneficio alm do prprio
arquivo fonte e da documentao/API7 online.
SchemaShell Removido O SchemaShell foi removido como ele nunca foi uma implementao completa
de migrao de banco de dados e surgiram ferramentas melhores como o Phinx8 . Ele foi substitudo pelo
CakePHP Migrations Plugin9 que funciona como um empacotamento entre o CakePHP e o Phinx10 .
7

http://api.cakephp.org/
https://phinx.org/
9
https://github.com/cakephp/migrations
10
https://phinx.org/
8

234

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

ExtractTask
O bin/cake i18n extract no inclui mais mensagens de validao sem traduo. Se voc
quiser mensagens de validao traduzidas voc deve encapsula-las com chamadas __() como qualquer
outro contedo.
BakeShell / TemplateTask
O Bake no faz mais parte do fonte do ncleo e suplantado pelo CakePHP Bake Plugin11
Os templates do Bake foram movidos para src/Template/Bake.
A sintaxe dos templates do Bake agora usam tags estilo erb (<% %>) para denotar lgica de template,
permitindo cdigo php ser tratado como texto plano.
O comando bake view foi renomeado para bake template.
Eventos O mtodo getEventManager(), foi removido de todos os objetos que continham. Um
mtodo eventManager() agora fornecido pelo EventManagerTrait. O EventManagerTrait
contm a lgica de instanciao e manuteno de uma referncia para um gerenciador local de eventos.
O subsistema Event teve um monte de funcionalidades opcionais removidas. Quando despachar eventos
voc no poder mais usar as seguintes opes:
passParams Essa opo est agora ativada sempre implicitamente. Voc no pode desliga-la.
break Essa opo foi removida. Voc deve agora parar os eventos.
breakOn Essa opo foi removida. Voc deve agora parar os eventos.
Log
As configuraes do Log agora no imutveis. Se voc precisa alterar a configurao voc deve
primeiro derrubar a configurao e ento recria-la. Isso previne problemas de sincronizao com
opes de configurao.
Os mecanismos de Log agora so carregados tardiamente aps a primeira escrita nos logs.
O Cake\Log\Log::engine() foi adicionado.
Os seguintes mtodos foram removidos de Cake\Log\Log :: defaultLevels(), enabled(),
enable(), disable().
Voc no pode mais criar nveis personalizados usando Log::levels().
Quando configurar os loggers voc deve usar levels ao invs de types.
Voc no pode mais especificar nveis personalizados de log. Voc deve usar o conjunto padro de
nveis de log. Voc deve usar escopos de log para criar arquivos de log personalizados ou manipulaes especficas para diferentes sees de sua aplicao. Usando um nvel de log no padro ir
lanar uma exceo.
11

https://github.com/cakephp/bake

Guia de Migrao para a verso 3.x

235

CakePHP Cookbook Documentation, Verso 3.x

O Cake\Log\LogTrait foi adicionado. Voc pode usar este trait em suas classes para adicionar
o mtodo log().
O escopo de log passado para Cake\Log\Log::write() agora encaminhado para o mtodo
write() dos mecanismos de log de maneira a fornecer um melhor contexto para os mecanismos.
Os mecanismos de Log agora so necessrios para implementar Psr\Log\LogInterface
invs do prprio LogInterface do Cake.
Em geral, se voc herdou o
Cake\Log\Engine\BaseEngine voc s precisa renomear o mtodo write() para
log().
O Cake\Log\Engine\FileLog agora grava arquivos em ROOT/logs no lugar de
ROOT/tmp/logs.
Roteamento
Parmetros Nomeados Os parmetros nomeados foram removidos no 3.0. Os parmetros nomeados
foram adicionados no 1.2.0 como uma verso bonita de parmetros de requisio. Enquanto o benefcio
visual discutvel, os problemas criados pelos parmetros nomeados no so.
Os parmetros nomeados necessitam manipulao especial no CakePHP assim como em qualquer biblioteca
PHP ou JavaScript que necessite interagir com eles, os parmetros nomeados no so implementados ou
entendidos por qualquer biblioteca exceto o CakePHP. A complexidade adicionada e o cdigo necessrio
para dar suporte aos parmetros nomeados no justificam a sua existncia, e eles foram removidos. No lugar
deles, voc deve agora usar o padro de parmetros de requisio (querystring) ou argumentos passados
configurados nas rotas. Por padro o Router ir tratar qualquer parmetro adicional ao Router::url()
como argumentos de requisio.
Como muitas aplicaes ainda precisaro analisar URLs contendo parmetros nomeados, o
Cake\Routing\Router::parseNamedParams() foi adicionado para permitir compatibilidade
com URLs existentes.
RequestActionTrait
O Cake\Routing\RequestActionTrait::requestAction() teve algumas de suas
opes extras alteradas:
o options[url] agora options[query].
o options[data] agora options[post].
os parmetros nomeados no so mais suportados.
Roteador
Os parmetros nomeados foram removidos, veja acima para mais informaes.
A opo full_base foi substituda com a opo _full.
A opo ext foi substituda com a opo _ext.
As opes _scheme, _port, _host, _base, _full, _ext foram adicionadas.
236

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

As URLs em strings no so mais modificados pela adio de plugin/controller/nomes de prefixo.


A manipulao da rota padro de fallback foi removida. Se nenhuma rota combinar com o conjunto de parmetros, o / ser retornado.
As classes de rota so responsveis por toda gerao de URLs incluindo parmetros de requisio
(query string). Isso faz com que as rotas sejam muito mais poderosas e flexveis.
Parmetros
persistentes
foram
removidos.
Eles
foram
substitudos
pelo
Cake\Routing\Router::urlFilter() que permite um jeito mais flexvel para mudar
URLs sendo roteadas reversamente.
O
Router::parseExtensions()
foi
removido.
Use
o
Cake\Routing\Router::extensions() no lugar.
Esse mtodo deve ser chamado
antes das rotas serem conectadas. Ele no ir modificar rotas existentes.
O
Router::setExtensions()
foi
removido.
Cake\Routing\Router::extensions() no lugar.

Use

O Router::resourceMap() foi removido.


A opo [method] foi renomeada para _method.
A habilidade de combinar cabealhos arbitrrios com parmetros no estilo [] foi removida. Se voc
precisar combinar/analisar em condies arbitrrias considere usar classes personalizadas de roteamento.
O Router::promote() foi removido.
O Router::parse() ir agora lanar uma exceo quando uma URL no puder ser atendida por
nenhuma rota.
O Router::url() agora ir lanar uma exceo quando nenhuma rota combinar com um conjunto
de parmetros.
Os escopos de rotas foram adicionados. Escopos de rotas permitem voc manter seu arquivo de rotas
limpo e dar dicas de rotas em como otimizar anlise e reverso de rotas de URL.
Route
O CakeRoute foi renomeado para Route.
A assinatura de match() mudou para match($url, $context = []).
Cake\Routing\Route::match() para mais informaes sobre a nova assinatura.

Veja

Configurao
de
Filtros
do
Despachante
Mudaram Os
filtros
do
despachante
no so mais adicionados em sua aplicao usando o Configure.
Voc deve
agora anexa-los com Cake\Routing\DispatcherFactory.
Isso significa que
sua aplicao usava Dispatcher.filters,
voc deve usar agora o mtodo
Cake\Routing\DispatcherFactory::add().
Alm das mudanas de configurao, os filtros do despachante tiveram algumas convenes atualizadas e
novas funcionalidades. Veja a documentao em Filtros do Dispatcher para mais informaes.

Guia de Migrao para a verso 3.x

237

CakePHP Cookbook Documentation, Verso 3.x

FilterAssetFilter
Os itens de plugins e temas manipulados pelo AssetFilter no so mais lidos via include, ao invs
disso eles so tratados como arquivos de texto plano. Isso corrige um nmero de problemas com
bibliotecas javascript como TinyMCE e ambientes com short_tags ativadas.
O suporte para a configurao Asset.filter e ganchos foram removidos. Essa funcionalidade
pode ser facilmente substituda com um plugin ou filtro de despachante.
Rede
Requisio
O CakeRequest foi renomeada para Cake\Network\Request.
O Cake\Network\Request::port() foi adicionado.
O Cake\Network\Request::scheme() foi adicionado.
O Cake\Network\Request::cookie() foi adicionado.
O Cake\Network\Request::$trustProxy foi adicionado. Isso torna mais fcil colocar aplicaes CakePHP atrs de balanceadores de carga.
O Cake\Network\Request::$data no mais mesclado com a chave de dados prefixada, pois
esse prefixo foi removido.
O Cake\Network\Request::env() foi adicionado.
O Cake\Network\Request::acceptLanguage() mudou de um mtodo esttico para noesttico.
O detector de requisio para dispositivos mveis foi removido do ncleo. Agora o app template
adiciona detectores para dispositivos mveis usando a biblioteca MobileDetect.
O mtodo onlyAllow() foi renomeado para allowMethod() e no aceita mais argumentos
var. Todos os nomes de mtodos precisam ser passados como primeiro argumento, seja como string
ou como array de strings.
Resposta
O mapeamento do mimetype text/plain para extenso csv foi removido. Como consequncia o
Cake\Controller\Component\RequestHandlerComponent no define a extenso para
csv se o cabealho Accept tiver o mimetype text/plain que era um problema comum quando
recebia uma requisio XHR do jQuery.
Sesses A classe de sesso no mais esttica, agora a sesso (session) pode ser acessada atravs do objeto
de requisio (request). Veja a documentao em Sessions para ver como usar o objeto de sesso.
O Cake\Network\Session e classes de sesso relacionadas foram movidas para o namespace
Cake\Network.
O SessionHandlerInterface foi removido em favor ao fornecido pelo prprio PHP.
238

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

A propriedade Session::$requestCountdown foi removida.


O funcionalidade de sesso checkAgent foi removida. Ela causava um monte de bugs quando
quadros do chrome e o flash player estavam envolvidos.
A conveno de nome para a tabela de sesso no banco de dados agora sessions ao invs de
cake_sessions.
O cookie de tempo limite da sesso atualizado automaticamente em conjunto com o tempo limite
dos dados de sesso.
O caminho padro para o cookie de sesso agora o caminho base da aplicao, ao invs de /. Alm
disso, uma nova varivel de configurao Session.cookiePath foi adicionada para facilitar a
personalizao do caminho para os cookies.
Um novo mtodo conveniente Cake\Network\Session::consume() foi adicionado para permitir a leitura e excluso de dados de sesso em um nico passo.
O valor padro do argumento $renew de Cake\Network\Session::clear() mudou de
true para false.
Network\Http
O HttpSocket agora Cake\Network\Http\Client.
O HttpClient foi reescrito do zero. Ele tem uma API mais simples/fcil de usar, suporta novos sistemas
de autenticao como OAuth, e uploads de arquivos. Ele usa as API de stream do PHP de modo que
no h requerimentp para o cURL. Veja a documentao Http Client para mais informaes.
Network\Email
O Cake\Network\Email\Email::config() agora usado para definir perfis de configurao. Isso substitui as classes EmailConfig nas verses anteriores.
O Cake\Network\Email\Email::profile() substitui o config() como modo de modificar opes de configurao por instncia.
O Cake\Network\Email\Email::drop() foi adicionado para permitir a remoo de configuraes de email.
O Cake\Network\Email\Email::configTransport() foi adicionado para permitir a
definio de configuraes de transporte. Essa mudana retira as opes de transporte dos perfis
de entrega e permite a voc reusar facilmente os transportes atravs de perfis de e-mails.
O Cake\Network\Email\Email::dropTransport() foi adicionado para permitir a remoo de configuraes de transporte.
Controller

Guia de Migrao para a verso 3.x

239

CakePHP Cookbook Documentation, Verso 3.x

Controller
As propriedades $helpers e $components agora esto mescladas com todas classes pai, no
apenas a AppController e o plugin de AppController. As propriedades so mescladas de modo
diferente agora tambm. No lugar de todas as configuraes em todas as classes serem mescladas juntas, as configuraes definidas nas classes filho sero usadas. Isso quer dizer que se voc tem alguma
configuraes definida no seu AppController, e alguma configurao definida em uma a subclasse,
apenas a configurao na subclasse ser usada.
O Controller::httpCodes() foi removido, use o Cake\Network\Response::httpCodes()
no lugar.
O
Controller::disableCache()
foi
Cake\Network\Response::disableCache() no lugar.

removido,

use

O Controller::flash() foi removido. Esse mtodo era raramente usado em aplicaes reais e
no tinha mais propsito algum.
O Controller::validate() e Controller::validationErrors() foram removidos.
Eles eram restos dos dias do 1.x onde as preocupaes com os models + controllers eram muito mais
entrelaados.
O Controller::loadModel() agora carrega uma tabela de objetos.
A propriedade Controller::$scaffold foi removida. O scaffolding dinmico foi removido do
ncleo do CakePHP. Um plugin de scaffolding melhorado, chamado CRUD, pode ser encontrado em:
https://github.com/FriendsOfCake/crud
A propriedade Controller::$ext foi removida. Voc deve agora estender e sobrescrever a propriedade View::$_ext se voc deseja usar uma extenso de arquivo de viso no padro.
A propriedade Controller::$methods foi removida.
Voc deve usar o
Controller::isAction() para determinar quando ou no um nome de mtodo uma
ao. Essa mudana foi feita para permitir personalizaes mais fceis do que vai contar ou no
como uma ao.
A propriedade Controller::$Components foi removida e substituda pelo _components.
Se voc precisar carregar componentes em tempo de execuo voc deve usar o
$this->loadComponent() em seu controller.
A assinatura do Cake\Controller\Controller::redirect() mudou para
Controller::redirect(string|array $url, int $status = null).
O terceiro argumento $exit foi removido. O mtodo no pode mais enviar resposta e sair do script, no
lugar ele retorna uma instncia de Response com os cabealhos apropriados definidos.
As propriedades mgicas base, webroot, here, data, action, e params foram removidas.
Voc deve acessar todas essas propriedades em $this->request no lugar.
Mtodos de controlar prefixados com sublinhado como _someMethod() no so mais tratados
como mtodos privados. Use as palavras chaves de visibilidade apropriadas no lugar. Somente mtodos pblicos podem ser usados como ao de controllers.

240

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

Scaffold Removido O scaffolding dinmico no CakePHP foi removido do ncleo do CakePHP. Ele no
era usado com frequncia, e no era voltado para uso em produo. Um plugin melhorado de scaffolding,
chamado CRUD, pode ser encontrado em: https://github.com/FriendsOfCake/crud
ComponentCollection
Substitudo Essa
classe
foi
renomeada
para
Cake\Controller\ComponentRegistry. Veja a seo em Objetos de Registro para mais informaes sobre as funcionalidades fornecidas pela nova classe. Voc pode usar o cake upgrade
rename_collections para ajudar voc a atualizar o seu cdigo.
Components
A propriedade _Collection agora _registry.
Cake\Controller\ComponentRegistry agora.

Ela contm uma instncia do

Todos components devem agora usar o mtodo config() para obter/definir configuraes.
A configurao padro para components deve ser definido na propriedade $_defaultConfig.
Essa propriedade automaticamente mesclada com qualquer configurao fornecida pelo construtor.
Opes de configurao no so mais definidas como propriedades pblicas.
O mtodo Component::initialize() no mais um event listener (ouvinte de eventos). Ao invs disso, ele um gancho ps-construtor como o Table::initialize() e
Controller::initialize(). O novo mtodo Component::beforeFilter() ligado
ao mesmo evento que o Component::initialize() costumava ser. O mtodo de inicializao
deve ter a seguinte assinatura initialize(array $config).
Controller\Components
CookieComponent
Ele usa o Cake\Network\Request::cookie() para ler os dados de cookies, isso facilita os
testes, e permite o ControllerTestCase definir os cookies.
Os Cookies encriptados pelas verses anteriores do CakePHP usando o mtodo cipher(), agora
no podem ser lidos, pois o Security::cipher() foi removido. Voc precisar reencriptar os
cookies com o mtodo rijndael() ou aes() antes de atualizar.
O CookieComponent::type() foi removido e substitudo com dados de configurao acessados
atravs de config().
O write() no aceita mais os parmetros encryption ou expires. Os dois agora so gerenciados atravs de dados de configurao. Veja CookieComponent para mais informaes.
O caminho padro para os cookies agora o caminho base da aplicao, ao invs de /.
AuthComponent

Guia de Migrao para a verso 3.x

241

CakePHP Cookbook Documentation, Verso 3.x

O Default agora o hasher de senhas padro usado pelas classes de autenticao. Ele usa exclusivamente o algoritmo de hash bcrypt. Se voc desejar continuar usando o hash SHA1 usado no 2.x,
use passwordHasher => Weak nas configuraes de seu autenticador.
O novo FallbackPasswordHasher foi adicionado para ajudar os usurios migrar senhas antigas
de um algoritmo para o outro. Veja a documentao do AuthComponent para mais informaes.
A classe BlowfishAuthenticate foi removida. Apenas use FormAuthenticate.
A classe BlowfishPasswordHasher foi removida. Use o DefaultPasswordHasher no
lugar.
O mtodo loggedIn() foi removido. Use o user() no lugar.
As opes de configurao no so mais definidas como propriedades pblicas.
Os mtodos allow() e deny() no aceitam mais var args. Todos os nomes de mtodos precisam
ser passados como primeiro argumento, seja como string ou array de strings.
O mtodo login() foi removido e substitudo por setUser(). Para logar um usurio agora voc
deve chamar identify() que retorna as informaes do usurio caso identificado com sucesso e
ento usar setUser() para salvar as informaes na sesso de maneira persistente entre as requisies.
O BaseAuthenticate::_password() foi removido. Use a classe PasswordHasher no
lugar.
O BaseAuthenticate::logout() foi removido.
O AuthComponent agora dispara dois eventos Auth.afterIdentify e Auth.logout
aps um usurio ser identificado e antes de um usurio ser deslogado respectivamente. Voc
pode definir funes de callback para esses eventos retornando um array mapeado no mtodo
implementedEvents() de sua classe de autenticao.
Classes relacionadas a ACL foram movidas para um plugin separado. Hashers de senha, fornecedores de
Autenticao e Autorizao foram movidos para o namespace \Cake\Auth. Voc DEVE mover seus
fornecedores e hashers para o namespace App\Auth tambm.
RequestHandlerComponent
Os seguintes mtodos foram removidos do componente RequestHandler:
isAjax(),
isFlash(), isSSL(), isPut(), isPost(), isGet(), isDelete(). Use o mtodo
Cake\Network\Request::is() no lugar com o argumento relevante.
O
RequestHandler::setContent()
Cake\Network\Response::type() no lugar.

foi

removido,

use

O
RequestHandler::getReferer()
Cake\Network\Request::referer() no lugar.

foi

removido,

use

removido,

use

O
RequestHandler::getClientIP()
Cake\Network\Request::clientIp() no lugar.

foi

O RequestHandler::getAjaxVersion() foi removido.

242

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

O RequestHandler::mapType() foi removido, use Cake\Network\Response::mapType()


no lugar.
As opes de configurao no so mais definidas como propriedades pblicas.
SecurityComponent
Os seguintes mtodos e as propriedades relacionadas foram removidas do componente Security: requirePost(), requireGet(), requirePut(), requireDelete(). Use o
Cake\Network\Request::allowMethod() no lugar.
SecurityComponent::$disabledFields()
SecurityComponent::$unlockedFields().

foi

removido,

use

As funes relacionadas ao CSRF no SecurityComponent foram extradas e movidas em separado no


CsrfComponent. Isso permite que voc use a proteo CSRF facilmente sem ter que usar preveno
de adulterao de formulrios.
As opes de configurao no so mais definidas como propriedades pblicas.
Os mtodos requireAuth() e requireSecure() no aceitam mais var args. Todos os
nomes de mtodos precisam ser passados como primeiro argumento, seja como string ou array de
strings.
SessionComponent
O SessionComponent::setFlash() est obsoleto. Voc deve usar o Flash no lugar.
Error ExceptionRenderers personalizados agora espera-se que retornem ou um objeto
Cake\Network\Response ou uma string quando renderizando erros. Isso significa que qualquer
mtodo que manipule excees especficas devem retornar uma resposta ou valor de string.
Model A camada de model do 2.x foi completamente reescrita e substituda. Voc deve revisar o Guia de
atualizao para o novo ORM para saber como usar o novo ORM.
A classe Model foi removida.
A classe BehaviorCollection foi removida.
A classe DboSource foi removida.
A classe Datasource foi removida.
As vrias classes de fonte de dados foram removidas.
ConnectionManager
O ConnectionManager
Cake\Datasource.

(gerenciador

de

conexo)

foi

movido

para

namespace

O ConnectionManager teve os seguintes mtodos removidos:

Guia de Migrao para a verso 3.x

243

CakePHP Cookbook Documentation, Verso 3.x

sourceList
getSourceName
loadDataSource
enumConnectionObjects
O Database\ConnectionManager::config() foi adicionado e agora o nico jeito de configurar conexes.
O Database\ConnectionManager::get()
getDataSource().

foi

adicionado.

Ele

substitui

O Database\ConnectionManager::configured() foi adicionado.


Ele junto com
config() substitui o sourceList() e enumConnectionObjects() com uma API mais
padro e consistente.
O ConnectionManager::create() foi removido.
config($name, $config) e get($name).

Ele pode ser substitudo por

Behaviors
Os mtodos de comportamentos (behaviors) prefixados com sublinhado como _someMethod() no
so mais tratados como mtodos privados. Use as palavras chaves de visibilidade.
TreeBehavior O TreeBehavior foi completamente reescrito para usar o novo ORM. Embora ele funcione
do mesmo modo que no 2.x, alguns mtodos foram renomeados ou removidos:
TreeBehavior::children() agora uma busca personalizada find(children).
TreeBehavior::generateTreeList()
find(treeList).

agora

uma

busca

personalizada

TreeBehavior::getParentNode() foi removido.


TreeBehavior::getPath() agora uma busca personalizada find(path).
TreeBehavior::reorder() foi removido.
TreeBehavior::verify() foi removido.
Sute de Testes
Casos de Teste
O _normalizePath() foi adicionado para permitir testes de comparao de caminhos para executar em todos os sistemas operacionais, independente de sua configurao (\ no Windows vs / no
UNIX, por exemplo).
Os seguintes mtodos de assero foram removidos j que eles estavam h muito obsoletos e foram substitudos pelo seu equivalente no PHPUnit:
assertEqual() substitudo por assertEquals()
244

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

assertNotEqual() substitudo por assertNotEquals()


assertIdentical() substitudo por assertSame()
assertNotIdentical() substitudo por assertNotSame()
assertPattern() substitudo por assertRegExp()
assertNoPattern() substitudo por assertNotRegExp()
assertReference() substitudo por assertSame()
assertIsA() substitudo por assertInstanceOf()
Note que alguns mtodos tiveram a ordem dos argumentos trocada, ex.
$expected) deve ser agora assertEquals($expected, $is).

assertEqual($is,

Os seguintes mtodos de assero esto obsoletos e sero removidos no futuro:


assertWithinMargin() substitudo por assertWithinRange()
assertTags() substitudo por assertHtml()
Em ambas as substituies dos mtodos tambm mudaram a ordem dos argumentos para manter a consistncia na API com $expected como primeiro argumento.
Os seguintes mtodos de assero foram adicionados:
assertNotWithinRange() em contrapartida ao assertWithinRange()
View
Temas so agora Plugins Bsicos Ter os temas e plugins de modo a criar components modulares da
aplicao se provou limitado e confuso. No CakePHP 3.0, temas no residem mais dentro da aplicao. Ao
invs disso, eles so plugins independentes. Isso resolveu alguns problemas com temas:
Voc no podia colocar temas nos plugins.
Temas no podiam fornecer helpers (helpers), ou classes de viso personalizadas.
Esses dois problemas foram resolvidos ao converter os temas em plugins.
Pasta das views renomeada As pastas contendo os arquivos de views agora ficam em src/Template no
lugar de src/View. Isso foi feito para separar os arquivos de viso dos arquivos contendo classes php. (ex.
helpers, Classes de viso).
As seguintes pastas de Viso foram renomeadas para evitar coliso de nomes com nomes de controllers:
Layouts agora Layout
Elements agora Element
Errors agora Error
Emails agora Email (o mesmo para Email dentro de Layout)

Guia de Migrao para a verso 3.x

245

CakePHP Cookbook Documentation, Verso 3.x

Coleo de Helpers Substituda Essa classe foi renomeada para Cake\View\HelperRegistry.


Veja a seo em Objetos de Registro para mais informaes sobre as funcionalidades fornecidas pela nova
classe. Voc pode usar o cake upgrade rename_collections para ajudar voc a atualizar seu
cdigo.
Classe View
A chave plugin foi removida do argumento $options de Cake\View\View::element().
Especifique o nome do elemento como AlgumPlugin.nome_do_elemento no lugar.
O View::getVar() foi removido, use o Cake\View\View::get() no lugar.
O View::$ext foi removido e no lugar uma propriedade protegida View::$_ext foi adicionada.
O View::addScript() foi removido. Use o Using View Blocks no lugar.
As propriedades mgicas base, webroot, here, data, action, e params foram removidas.
Ao invs disso, voc deve acessar todas essas propriedades no $this->request.
O View::start() no se liga mais a um bloco existente. Ao invs disso ele ir sobrescrever o
contedo do bloco quando o end() for chamado. Se voc precisa combinar o contedo de um bloco
voc dever buscar o contedo do bloco quando chamar o start uma segunda vez, ou usar o modo de
captura de append().
O View::prepend() no tem mais um modo de captura.
O View::startIfEmpty() foi removido. Agora que o start() sempre sobrescreve, o startIfEmpty
no tem mais propsito.
A propriedade View::$Helpers foi removida e substituda com _helpers. Se voc precisar
carregar helpers em tempo de execuo voc deve usar o $this->addHelper() em seus arquivos
de viso.
O View agora ir lanar Cake\View\Exception\MissingTemplateException quando
templates estiverem faltando, ao invs de MissingViewException.
ViewBlock
O ViewBlock::append() foi removido, use o Cake\ViewViewBlock::concat() no lugar. Entretanto o View::append() ainda existe.
JsonView
Agora os dados JSON tero as entidades HTML codificadas por padro. Isso previne possveis problemas de XSS quando o contedo de viso JSON est encapsulado em arquivos HTML.
O Cake\View\JsonView agora suporta a varivel de viso _jsonOptions. Isso permite a voc
configurar as opes de mscara de bits usadas ao gerar JSON.

246

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

XmlView
A Cake\View\XmlView agora suporta a varivel de viso _xmlOptions. Isso permite a voc
configurar as opes usadas quando gerar XML.
View\Helper
A propriedade $settings agora chamada $_config e deve ser acessada atravs do mtodo
config().
As opes de configurao no so mais definidas como propriedades pblicas.
O Helper::clean() foi removido. Ele nunca foi robusto o suficiente para prevenir completamente XSS. Ao invs disso voc deve escapar o contedo com h ou ou usar uma biblioteca dedicada
como o htmlPurifier.
O Helper::output() foi removido. Esse mtodo estava obsoleto no 2.x.
Os mtodos Helper::webroot(),
Helper::url(),
Helper::assetUrl(),
Helper::assetTimestamp()
foram
movidos
para
o
novo
ajudante
Cake\View\Helper\UrlHelper.
O Helper::url() est agora disponvel como
Cake\View\Helper\UrlHelper::build().
Os Assessores Mgicos a propriedades obsoletas foram removidos. A seguinte propriedade agora
deve ser acessada a partir do objeto de requisio:
base
here
webroot
data
action
params
Helpers A classe Helper teve os seguintes mtodos removidos:
Helper::setEntity()
Helper::entity()
Helper::model()
Helper::field()
Helper::value()
Helper::_name()
Helper::_initInputField()
Helper::_selectedArray()

Guia de Migrao para a verso 3.x

247

CakePHP Cookbook Documentation, Verso 3.x

Esses mtodos eram partes usadas apenas pelo FormHelper, e parte de uma funcionalidade de persistncia
de campos que se mostrou problemtica com o tempo. O FormHelper no precisa mais destes mtodos e a
complexidades que eles provm no mais necessria.
Os seguintes mtodos foram removidos:
Helper::_parseAttributes()
Helper::_formatAttribute()
Esses mtodos podem agora ser encontrados na classe StringTemplate que os helpers usam com frequncia. Veja o StringTemplateTrait para um jeito fcil de integrar os templates de string em seus
prprios helpers.
FormHelper O FormHelper foi completamente reescrito para o 3.0. Ele teve algumas grandes mudanas:
O FormHelper trabalha junto com o novo ORM. Mas tambm possui um sistema extensvel para
integrar com outros ORMs e fontes de dados.
O FormHelper possui um sistema de widgets extensvel que permite a voc criar novos widgets de
entrada personalizados e expandir facilmente aqueles inclusos no framework.
Os Templates de String so a fundao deste ajudante. Ao invs de encher de arrays por toda parte,
a maioria do HTML que o FormHelper gera pode ser personalizado em um lugar central usando
conjuntos de templates.
Alm dessas grandes mudanas, foram feitas algumas mudanas menores que causaram rompendo algumas
coisas da verso anterior. Essas mudanas devem simplificar o HTML que o FormHelper gera e reduzir os
problemas que as pessoas tinham no passado:
O prefixo data[ foi removido de todas as entradas geradas. O prefixo no tem mais propsito.
Os vrios mtodos de entradas independentes, como text(), select() e outros, no geram mais
atributos id.
A opo inputDefaults foi removida de create().
As opes default e onsubmit do create() foram removidas. No lugar voc deve usar
JavaScript event binding ou definir todos os cdigos js necessrios para o onsubmit.
O end() no gerar mais botes. Voc deve criar botes com button() ou submit().
O FormHelper::tagIsInvalid() foi removido. Use isFieldError() no lugar.
O FormHelper::inputDefaults() foi removido.
definir/expandir os templates que o FormHelper usa.

Voc pode usar templates() para

As opes wrap e class foram removidas do mtodo error().


A opo showParents foi removida do select().
As opes div, before, after, between e errorMessage foram removidas do input().
Voc pode usar templates para atualizar o HTML envoltrio. A opo templates permite voc
sobrescrever os templates carregados para uma entrada.

248

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

As opes separator, between, e legend foram removidas do radio(). Voc pode usar
templates para mudar o HTML envoltrio agora.
O parmetro format24Hours foi removido de hour(). Ele foi substitudo pela opo format.
Os parmetros minYear e maxYear foram removidos do year(). Ambos podem ser fornecidos
como opes.
Os parmetros dateFormat e timeFormat foram removidos do datetime(). Voc pode usar
o template para definir a ordem que as entradas devem ser exibidas.
O submit() teve as opes div, before e after removidas. Voc pode personalizar o template
submitContainer para modificar esse contedo.
O mtodo inputs() no aceita mais legend e fieldset no parmetro $fields, voc
deve usar o parmetro $options. Ele tambm exige que o parmetro $fields seja um array.
O parmetro $blacklist foi removido, a funcionalidade foi substituda pela especificao de
field => false no parmetro $fields.
O parmetro inline foi removido do mtodo postLink(). Voc deve usar a opo block no lugar.
Definindo block => true ir emular o comportamento anterior.
O parmetro timeFormat para hour(), time() e dateTime() agora 24 por padro, em
cumprimento ao ISO 8601.
O argumento $confirmMessage de Cake\View\Helper\FormHelper::postLink() foi
removido. Voc deve usar agora a chave confirm no $options para especificar a mensagem.
As entradas do tipo Checkbox e radio so agora renderizadas dentro de elementos do tipo label por
padro. Isso ajuda a aumentar a compatibilidade com bibliotecas CSS populares como Bootstrap12 e
Foundation13 .
As tags de template agora so todas camelBacked (primeira letra minscula e inicio de novas palavras
em maisculo). As tags pr-3.0 formstart, formend, hiddenblock e inputsubmit so
agora formStart, formEnd, hiddenBlock e inputSubmit. Certifique-se de altera-las se
elas estiverem personalizando sua aplicao.
recomendado que voc revise a documentao Form para mais detalhes sobre como usar o FormHelper
no 3.0.
HtmlHelper
O HtmlHelper::useTag() foi removido, use tag() no lugar.
O HtmlHelper::loadConfig() foi removido. As tags podem ser personalizadas usando
templates() ou as configuraes de templates.
O segundo parmetro $options para HtmlHelper::css() agora sempre ir exigir um array.
O primeiro parmetro $data para HtmlHelper::style() agora sempre ir exigir um array.
12
13

http://getbootstrap.com/
http://foundation.zurb.com/

Guia de Migrao para a verso 3.x

249

CakePHP Cookbook Documentation, Verso 3.x

O parmetro inline foi removido dos mtodos meta(), css(), script() e scriptBlock(). Ao invs
disso, voc deve usar a opo block. Definindo block => true ir emular o comportamento
anterior.
O HtmlHelper::meta() agora exige que o $type seja uma string. Opes adicionais podem
ser passadas como $options.
O HtmlHelper::nestedList() agora exige que o $options seja um array. O quarto argumento para o tipo tag foi removido e incluido no array $options.
O argumento $confirmMessage de Cake\View\Helper\HtmlHelper::link() foi removido. Voc deve usar agora a chave confirm no $options para especificar a menssagem.
PaginatorHelper
O link() foi removido. Ele no era mais usado internamente pelo ajudante. Ele era pouco usado
em cdigos de usurios e no se encaixava mais nos objetivos do ajudante.
O next() no tem mais as opes class ou tag. Ele no tem mais argumentos desabilitados. Ao
invs disso so usados templates.
O prev() no tem mais as opes class ou tag. Ele no tem mais argumentos desabilitados. Ao
invs disso so usados templates.
O first() no tem mais as opes after, ellipsis, separator, class ou tag.
O last() no tem mais as opes after, ellipsis, separator, class ou tag.
O numbers() no tem mais as opes separator, tag, currentTag, currentClass, class, tag e
ellipsis. Essas opes so agora facilitadas pelos templates. Ele tambm exige que agora o parmetro
$options seja um array.

O espao reservado de estilo %page% foi removido de Cake\View\Helper\PaginatorHelper::counter()


Use o espao reservado de estilo {{page}} no lugar.
O url() foi renomeada para generateUrl() para evitar coliso de declarao de mtodo com
Helper::url().
Por padro todos os links e textos inativos so encapsulados em elementos <li>. Isso ajuda a fazer o CSS
mais fcil de escrever, e aumenta a compatibilidade com frameworks de CSS populares.
Ao invs de vrias opes em cada mtodo, voc deve usar a funcionalidade de templates. Veja a documentao PaginatorHelper Templates para informaes de como se usar templates.
TimeHelper
TimeHelper::__set(), TimeHelper::__get(), e TimeHelper::__isset() foram
removidos. Eles eram mtodos mgicos para atributos obsoletos.
O TimeHelper::serverOffset() foi removido. Ele provia prticas incorretas de operaes
com tempo.
O TimeHelper::niceShort() foi removido.

250

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

NumberHelper
O NumberHelper::format() agora exige que $options seja um array.
SessionHelper
O SessionHelper est obsoleto. Voc pode usar $this->request->session() diretamente, e a funcionalidade de mensagens flash foi movida para Flash.
JsHelper
O JsHelper e todos motores associados foram removidos. Ele podia gerar somente um subconjunto
muito pequeno de cdigos JavaScript para biblioteca selecionada e consequentemente tentar gerar
todo cdigo JavaScript usando apenas o ajudante se tornava um impedimento com frequncia.
recomendado usar diretamente sua biblioteca JavaScript preferida.
CacheHelper Removido O CacheHelper foi removido. A funcionalidade de cache que ele fornecia no
era padro, limitada e incompatvel com layouts no-HTML e views de dados. Essas limitaes significavam que uma reconstruo completa era necessria. O ESI (Edge Side Includes) se tornou uma maneira
padronizada para implementar a funcionalidade que o CacheHelper costumava fornecer. Entretanto, implementando Edge Side Includes14 em PHP tem vrias limitaes e casos. Ao invs de construir uma soluo
ruim, recomendado que os desenvolvedores que precisem de cache de resposta completa use o Varnish15
ou Squid16 no lugar.
I18n O subsistema de internacionalizao foi completamente reescrito. Em geral, voc pode esperar o
mesmo comportamento que nas verses anteriores, especialmente se voc est usando a famlia de funes
__().
Internamente, a classe I18n usa Aura\Intl, e mtodos apropriados so expostos para dar acesso a
funes especficas da biblioteca. Por esta razo a maior parte dos mtodos dentro de I18n foram removidos ou renomeados.
Devido ao uso do ext/intl, a classe L10n foi removida completamente. Ela fornecia dados incompletos
e desatualizados em comparao com os dados disponveis na classe Locale do PHP.
O idioma padro da aplicao no ser mais alterado automaticamente pelos idiomas aceitos pelo navegador
nem por ter o valor Config.language definido na sesso do navegador. Voc pode, entretanto, usar um
filtro no despachante para trocar o idioma automaticamente a partir do cabealho Accept-Language
enviado pelo navegador:
// No config/bootstrap.php
DispatcherFactory::addFilter('LocaleSelector');

No h nenhum substituto incluso para selecionar automaticamente o idioma a partir de um valor configurado na sesso do usurio.
14

http://en.wikipedia.org/wiki/Edge_Side_Includes
http://varnish-cache.org
16
http://squid-cache.org
15

Guia de Migrao para a verso 3.x

251

CakePHP Cookbook Documentation, Verso 3.x

A funo padro para formatao de mensagens traduzidas no mais a sprintf, mas a mais avanada
e funcional classe MessageFormatter. Em geral voc pode reescrever os espaos reservados nas mensagens como segue:
// Antes:
__('Hoje um dia %s na %s', 'Ensolarado', 'Espanha');
// Depois:
__('Hoje um dia {0} na {1}', 'Ensolarado', 'Espanha');

Voc pode evitar ter de reescrever suas mensagens usando o antigo formatador sprintf:
I18n::defaultFormatter('sprintf');

Adicionalmente, o valor Config.language foi removido e ele no pode mais ser usado para controlar o
idioma atual da aplicao. Ao invs disso, voc pode usar a classe I18n:
// Antes
Configure::write('Config.language', 'fr_FR');
// Agora
I18n::locale('en_US');

Os mtodos abaixo foram movidos:


De Cake\I18n\Multibyte::utf8() para Cake\Utility\Text::utf8()
De Cake\I18n\Multibyte::ascii() para Cake\Utility\Text::ascii()
De
Cake\I18n\Multibyte::checkMultibyte()
Cake\Utility\Text::isMultibyte()

para

Como agora o CakePHP requer a extenso mbstring, a classe Multibyte foi removida.
As mensagens de erro por todo o CakePHP no passam mais atravs das funes de internacionalizao. Isso foi feito para simplificar o ncleo do CakePHP e reduzir a sobrecarga. As mensagens
apresentadas aos desenvolvedores so raramente, isso quando, so de fato traduzidas - de modo que
essa sobrecarga adicional trs pouco beneficio.
Localizao
Agora o construtor de Cake\I18n\L10n recebe uma instncia de Cake\Network\Request
como argumento.
Testes
O TestShell foi removido. O CakePHP, o esqueleto da aplicao e novos plugins cozinhados,
todos usam o phpunit para rodar os testes.
O webrunner (webroot/test.php) foi removido. A adoo do CLI aumentou grandemente desde o
release inicial do 2.x. Adicionalmente, os CLI de execuo oferecem integrao superior com IDEs
e outras ferramentas automticas.

252

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

Se voc sentir necessidade de um jeito de executar os testes a partir de um navegador, voc deve
verificar o VisualPHPUnit17 . Ele oferece muitas funcionalidades adicionais que o antigo webrunner.
O ControllerTestCase est obsoleto e ser removido no CakePHP 3.0.0. Ao invs disso, voc
deve usar a nova funcionalidade Controller Integration Testing.
As Fixtures devem agora ser referenciadas usando sua forma no plural:
// No lugar de
$fixtures = ['app.artigo'];
// Voc deve usar
$fixtures = ['app.artigos'];

Utilitrios
Classe Set Removida A classe Set foi removida, agora voc deve usar a classe Hash no lugar dela.
Pastas & Arquivos As classes de pastas e arquivos foram renomeadas:
O Cake\Utility\File foi renomeado para Cake\Filesystem\File
O Cake\Utility\Folder foi renomeado para Cake\Filesystem\Folder
Inflexo
O valor padro para o argumento $replacement do Cake\Utility\Inflector::slug()
foi alterado do sublinhado (_) para o trao (-). Usando traos para separar palavras nas URLs a
escolha popular e tambm recomendada pelo Google.
As transliteraes para Cake\Utility\Inflector::slug() foram alteradas. Se voc usa
transliteraes personalizadas voc ter que atualizar seu cdigo. No lugar de expresses regulares,
as transliteraes usam simples substituies de string. Isso rendeu melhorias de performance significativas:
// No lugar de
Inflector::rules('transliteration', [
'/|/' => 'ae',
'//' => 'aa'
]);
// Voc deve usar
Inflector::rules('transliteration', [
'' => 'ae',
'' => 'ae',
'' => 'aa'
]);
17

https://github.com/NSinopoli/VisualPHPUnit

Guia de Migrao para a verso 3.x

253

CakePHP Cookbook Documentation, Verso 3.x

Os conjuntos distintos de regras de no-inflexes e irregulares para pluralizao e singularizao foram removidos. No lugar agora temos uma lista comum para cada. Quando usar
Cake\Utility\Inflector::rules() com o tipo singular e plural voc no poder mais
usar chaves como uninflected e irregular no array de argumentos $rules.
Voc pode adicionar / sobrescrever a lista de regras de no-inflexionados e irregulares usando
Cake\Utility\Inflector::rules() com valores uninflected e irregular para o argumento $type.
Sanitize
A classe Sanitize foi removida.
Segurana
O Security::cipher() foi removido. Ele era inseguro e promovia prticas ruins de criptografia.
Voc deve usar o Security::encrypt() no lugar.
O valor de configurao Security.cipherSeed no mais necessrio. Com a remoo de
Security::cipher() ele no tem utilidade.
A retrocompatibilidade do Cake\Utility\Security::rijndael() para valores encriptados antes do CakePHP 2.3.1 foi removido.
Voc deve reencriptar os valores usando
Security::encrypt() e uma verso recente do CakePHP 2.x antes de migrar.
A habilidade para gerar um hash do tipo blowfish foi removido. Voc no pode mais usar
o tipo blowfish em Security::hash(). Deve ser usado apenas o password_hash() do
PHP e password_verify() para gerar e verificar hashes blowfish. A compabilidade da biblioteca
ircmaxell/password-compat18 que instalado junto com o CakePHP fornece essas funes para verses de PHP menor que 5.5.
O OpenSSL usado agora no lugar do mcrypt ao encriptar/desencriptar dados. Esse alterao fornece
uma melhor performance e deixa o CakePHP a prova de futuros abandonos de suporte das distribuies ao mcrypt.
O Security::rijndael() est obsoleto e apenas disponvel quando se usa o mcrypt.
Aviso: Dados encriptados com Security::encrypt() em verses anteriores no so compatveis com a
implementao openssl. Voc deve definir a implementao como mcrypt quando fizer atualizao.

Data e Hora
O CakeTime foi renomeado para Cake\I18n\Time.
O CakeTime::serverOffset() foi removido. Ele provia prticas incorretas de operaes com
tempo.
O CakeTime::niceShort() foi removido.
O CakeTime::convert() foi removido.
18

https://packagist.org/packages/ircmaxell/password-compat

254

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

O CakeTime::convertSpecifiers() foi removido.


O CakeTime::dayAsSql() foi removido.
O CakeTime::daysAsSql() foi removido.
O CakeTime::fromString() foi removido.
O CakeTime::gmt() foi removido.
O CakeTime::toATOM() foi renomeado para toAtomString.
O CakeTime::toRSS() foi renomeado para toRssString.
O CakeTime::toUnix() foi renomeado para toUnixString.
O CakeTime::wasYesterday() foi renomeado para isYesterday para combinar com o
resto da renomeao de mtodos.
O CakeTime::format() no usa mais o formato do sprintf, ao invs disso voc deve usar o
formato i18nFormat.
O Time::timeAgoInWords() agora exige que o $options seja um array.
A classe Time no mais uma coleo de mtodos estticos, ela estende o DateTime para herdar todos
seus mtodos e adicionar funes de formatao baseado em localizao com ajuda da extenso intl.
Em geral, expresses assim:
CakeTime::aMethod($date);

Podem ser migradas reescrevendo para:


(new Time($date))->aMethod();

Nmeros A biblioteca Number foi reescrita para usar internamente a classe NumberFormatter.
O CakeNumber foi renomeada para Cake\I18n\Number.
O Number::format() agora exige que o $options seja um array.
O Number::addFormat() foi removido.
O Number::fromReadableSize() foi movido para Cake\Utility\Text::parseFileSize().
Validao
A faixa de valores para Validation::range() agora inclusiva se $lower e $upper forem
fornecidos.
O Validation::ssn() foi removido.
Xml
O Xml::build() agora exige que o $options seja um array.

Guia de Migrao para a verso 3.x

255

CakePHP Cookbook Documentation, Verso 3.x

O Xml::build() no aceita mais uma URL. Se voc precisar criar um documento XML a partir
de uma URL, use o
Guia de atualizao para o novo ORM

Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.


Por favor, sinta-se a vontade para nos enviar um pull request no Github19 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Informaes Gerais
Processo de desenvolvimento no CakePHP
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github20 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.

Glossrio
Nota: A documentao no atualmente suportada pela lingua portuguesa nesta pgina.
Por favor, sinta-se a vontade para nos enviar um pull request no Github21 ou use o boto Improve This Doc
para propor suas mudanas diretamente.
Voc pode referenciar-se verso inglesa no menu de seleo superior para obter informaes sobre o tpico
desta pgina.
routing array An array of attributes that are passed to Router::url(). They typically look like:
['controller' => 'Posts', 'action' => 'view', 5]

HTML attributes An array of key => values that are composed into HTML attributes. For example:
19

https://github.com/cakephp/docs
https://github.com/cakephp/docs
21
https://github.com/cakephp/docs
20

256

Captulo 46. Apndices

CakePHP Cookbook Documentation, Verso 3.x

// Given
['class' => 'my-class', 'target' => '_blank']
// Would generate
class="my-class" target="_blank"

If an option can be minimized or accepts its name as the value, then true can be used:
// Given
['checked' => true]
// Would generate
checked="checked"

plugin syntax Plugin syntax refers to the dot separated class name indicating classes are part of a plugin:
// The plugin is "DebugKit", and the class name is "Toolbar".
'DebugKit.Toolbar'
// The plugin is "AcmeCorp/Tools", and the class name is "Toolbar".
'AcmeCorp/Tools.Toolbar'

dot notation Dot notation defines an array path, by separating nested levels with . For example:
Cache.default.engine

Would point to the following value:


[
'Cache' => [
'default' => [
'engine' => 'File'
]
]
]

CSRF Cross Site Request Forgery. Prevents replay attacks, double submissions and forged requests from
other domains.
CDN Content Delivery Network. A 3rd party vendor you can pay to help distribute your content to data
centers around the world. This helps put your static assets closer to geographically distributed users.
routes.php A file in config directory that contains routing configuration. This file is included before
each request is processed. It should connect all the routes your application needs so requests can be
routed to the correct controller + action.
DRY Dont repeat yourself. Is a principle of software development aimed at reducing repetition of information of all kinds. In CakePHP DRY is used to allow you to code things once and re-use them across
your application.
PaaS Platform as a Service. Platform as a Service providers will provide cloud based hosting, database
and caching resources. Some popular providers include Heroku, EngineYard and PagodaBox
DSN Data Source Name. A connection string format that is formed like a URI. CakePHP supports DSNs
for Cache, Database, Log and Email connections.
Informaes Gerais

257

CakePHP Cookbook Documentation, Verso 3.x

258

Captulo 46. Apndices

PHP Namespace Index

c
Cake\Console, 149
Cake\Controller, 115
Cake\View\Helper, 131

259

CakePHP Cookbook Documentation, Verso 3.x

260

PHP Namespace Index

ndice

Symbols
() (Cake\Console\ method), 154
:action, 111
:controller, 111
:plugin, 111
$this->request, 113

CDN, 257
components (Cake\Controller\Controller property),
122
ConsoleOptionParser (classe em Cake\Console), 157
Controller (classe em Cake\Controller), 115
CSRF, 257

addArgument() (Cake\Console\ConsoleOptionParser description() (Cake\Console\ConsoleOptionParser


method), 158
method), 159
dot
notation,
257
addArguments() (Cake\Console\ConsoleOptionParser
DRY,
257
method), 159
addOption() (Cake\Console\ConsoleOptionParser DSN, 257
method), 160
E
addOptions() (Cake\Console\ConsoleOptionParser
epilog()
(Cake\Console\ConsoleOptionParser
method), 161
method),
159
addSubcommand() (Cake\Console\ConsoleOptionParser
method), 162
F
afterFilter() (Cake\Controller\Controller method),
FlashHelper (classe em Cake\View\Helper), 128
123
FormHelper (classe em Cake\View\Helper), 129

beforeFilter() (Cake\Controller\Controller method),


greedy star, 111
123
beforeRender()
(Cake\Controller\Controller
H
method), 123
buildFromArray() (Cake\Console\ConsoleOptionParserhelpers (Cake\Controller\Controller property), 123
HTML attributes, 256
method), 162
HtmlHelper (classe em Cake\View\Helper), 129

C
Cake\Console (namespace), 149
Cake\Controller (namespace), 115
Cake\View\Helper (namespace), 128131

I
initialize()
(Cake\Console\ConsoleOptionParser
method), 165

261

CakePHP Cookbook Documentation, Verso 3.x

L
loadComponent()
(Cake\Controller\Controller
method), 122
loadModel() (Cake\Controller\Controller method),
121

N
NumberHelper (classe em Cake\View\Helper), 129

P
PaaS, 257
paginate() (Cake\Controller\Controller method), 122
PaginatorHelper (classe em Cake\View\Helper), 129
plugin syntax, 257

R
redirect() (Cake\Controller\Controller method), 120
render() (Cake\Controller\Controller method), 119
routes.php, 257
routing array, 256
RssHelper (classe em Cake\View\Helper), 130

S
SessionHelper (classe em Cake\View\Helper), 130
set() (Cake\Controller\Controller method), 118
setAction() (Cake\Controller\Controller method),
121
startup()
(Cake\Console\ConsoleOptionParser
method), 165

T
TextHelper (classe em Cake\View\Helper), 130
TimeHelper (classe em Cake\View\Helper), 131
trailing star, 111

U
UrlHelper (classe em Cake\View\Helper), 131

262

ndice