CakePHP Book
Release 3.10

Cake Software Foundation

Aug 12, 2024

Contents

1

CakePHP at a Glance
Conventions Over Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Model Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The View Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Controller Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CakePHP Request Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Just the Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
1
2
2
3
3
5

2

Quick Start Guide
Content Management Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Creating the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Creating the Articles Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
13
15
18

3

3.x Migration Guide
3.10 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.0 Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27
27
28
31
33
38
45
51
61
64
68
72

4

Tutorials & Examples
Content Management Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Creating the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Creating the Articles Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Tags and Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Tutorial - Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bookmarker Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

107
107
109
112
121
129
135
i

Bookmarker Tutorial Part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Blog Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Blog Tutorial - Part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Blog Tutorial - Part 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Blog Tutorial - Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

142
150
153
164
172

5

Contributing
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Coding Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Backwards Compatibility Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

181
181
189
190
192
204

6

Installation
Installing CakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Development Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fire It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

207
208
210
210
211
212
212

7

Configuration
Configuring your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Class Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inflection Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and writing configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bootstrapping CakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disabling Generic Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

217
217
218
221
222
222
225
227
228

8

Routing
Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connecting Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connecting Scoped Middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RESTful Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passed Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redirect Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entity Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Custom Route Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Persistent URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Named Parameters in URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

229
229
231
245
246
250
251
252
252
253
255
256

9

Request & Response Objects
Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Cross Origin Request Headers (CORS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common Mistakes with Immutable Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cookie Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

261
261
272
279
280
280
281

10 Controllers
283
The App Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Request Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
ii

Controller Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interacting with Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redirecting to Other Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading Additional Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Paginating a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Components to Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Helpers to Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Request Life-cycle Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
More on Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

285
285
288
289
290
290
291
291
292

11 Views
The App View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using View Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Your Own View Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
More About Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

337
337
338
341
343
346
348
349
349

12 Database Access & ORM
461
Quick Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
13 Caching
Configuring Cache Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing to a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading From a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting From a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Clearing Cached Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Cache to Store Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Cache to Store Common Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Globally Enable or Disable Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Cache Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

631
632
635
636
638
638
639
639
639
640
641

14 Bake Console

643

15 Console Tools, Shells & Tasks
The CakePHP Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Console Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Renaming Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CakePHP Provided Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routing in the Console Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

645
645
647
648
648
672
687

16 Debugging
Basic Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Debugger Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outputting Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging With Stack Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating Stack Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting an Excerpt From a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Logging to Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

689
689
690
690
691
691
691
692
692
iii

17 Deployment
Moving files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adjust config/app.php . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Check Your Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Document Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Improve Your Application’s Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying an update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

693
693
693
694
694
694
695

18 Email
Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Templated Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Messages Quickly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Emails from CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Reusable Emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

697
697
698
701
701
703
703
705
705
705
707

19 Error & Exception Handling
Error & Exception Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customize Error Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customize the ErrorController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Change the ExceptionRenderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating your Own Error Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating your own Application Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Built in Exceptions for CakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

709
709
710
710
711
712
713
714
715

20 Events System
Example Event Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Event Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Core Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

719
720
720
721
722
725
728

21 Internationalization & Localization
Setting Up Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Translation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Your Own Translators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Localizing Dates and Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automatically Choosing the Locale Based on Request Data . . . . . . . . . . . . . . . . . . . . . . . . . .

729
729
731
735
738
739

22 Logging
Logging Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error and Exception Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interacting with Log Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the FileLog Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging to Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing to Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Log API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Trait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Monolog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

741
741
743
744
744
744
745
746
747
748

iv

23 Modelless Forms
Creating a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing Request Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Form Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invalidating Individual Form Fields from Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating HTML with FormHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

749
749
750
751
752
753
753
753

24 Plugins
Installing a Plugin With Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manually Installing a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading a Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Hook Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Plugin Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Your Own Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Components, Helpers and Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing your Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Publishing your Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plugin Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manage Your Plugins using Mixer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

755
755
756
757
758
760
760
761
762
763
764
765
766
767
768
768
768
768
769

25 REST
The Simple Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accepting Input in Other Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RESTful Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

771
771
774
774

26 Security
775
Security Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
27 Sessions
Session Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Built-in Session Handlers & Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting ini directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Custom Session Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing the Session Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading & Writing Session Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Destroying the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rotating Session Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flash Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

779
779
780
782
783
784
785
786
786
786

28 Testing
Installing PHPUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Test Database Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the Test Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Test Case Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Your First Test Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

787
787
788
789
789
789
791
v

Test Case Lifecycle Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Table Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controller Integration Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Console Integration Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Test Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Tests for Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating Tests with Bake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration with Jenkins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

793
793
800
802
813
813
813
815
816
818
818
819
820
820

29 Validation
Creating Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Validating Entity Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Core Validation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

823
823
832
833
833

30 App Class
Finding Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding Paths to Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locating Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locating Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading Vendor Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

835
835
836
836
836
836

31 Collections
Quick Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Iterating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Aggregation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Tree Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

839
839
840
840
845
846
850
851
853

32 Folder & File
Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Folder API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

861
861
862
866

33 Hash869
Hash Path Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
34 Http Client
Doing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Multipart Requests with Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Request Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Request Method Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Scoped Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting and Managing Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi

885
885
886
887
887
888
890
890
891

Changing Transport Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
35 Inflector
Summary of Inflector Methods and Their Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Plural & Singular Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating CamelCase and under_scored Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Human Readable Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Table and Class Name Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating URL Safe Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inflection Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

895
895
896
897
897
897
898
898
898

36 Number
Formatting Currency Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting the Default Currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Floating Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Percentages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interacting with Human Readable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

899
900
901
901
901
902
902
904
904

37 Registry Objects
Loading Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Triggering Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disabling Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

907
907
908
908

38 Text
Convert Strings into ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating URL Safe Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating UUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simple String Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wrapping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Highlighting Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Truncating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Truncating the Tail of a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extracting an Excerpt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Converting an Array to Sentence Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

909
910
910
911
911
911
912
913
913
913
914
915
916

39 Date & TimeCreating Time Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparing With the Present . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparing With Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Immutable Dates and Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accepting Localized Request Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Timezones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

917
918
919
919
922
923
923
924
924
925
925

40 Xml927
Loading XML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
vii

Loading HTML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
Transforming a XML String in Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
Transforming an Array into a String of XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
41 Constants & Functions
Global Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Core Definition Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timing Definition Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

931
931
933
934

42 Chronos

935

43 Debug Kit

937

44 Migrations

939

45 ElasticSearch

941

46 Appendices3.x Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Forwards Compatibility Shimming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

943
943
943
943

PHP Namespace Index

947

Index

949

viii

CHAPTER 1

CakePHP at a Glance

CakePHP is designed to make common web-development tasks simple, and easy. By providing an all-in-one toolbox
to get you started the various parts of CakePHP work well together or separately.
The goal of this overview is to introduce the general concepts in CakePHP, and give you a quick overview of how thoseconcepts are implemented in CakePHP. If you are itching to get started on a project, you can start with the tutorial, or
dive into the docs.

Conventions Over Configuration
CakePHP provides a basic organizational structure that covers class names, filenames, database table names, and otherconventions. While the conventions take some time to learn, by following the conventions CakePHP provides you
can avoid needless configuration and make a uniform application structure that makes working with various projects
simple. The conventions chapter covers the various conventions that CakePHP uses.

The Model Layer
The Model layer represents the part of your application that implements the business logic. It is responsible for retrieving data and converting it into the primary meaningful concepts in your application. This includes processing,validating, associating or other tasks related to handling data.
In the case of a social network, the Model layer would take care of tasks such as saving the user data, saving friends’
associations, storing and retrieving user photos, finding suggestions for new friends, etc. The model objects can bethought of as “Friend”, “User”, “Comment”, or “Photo”. If we wanted to load some data from our users table we
could do:use Cake\ORM\TableRegistry;(continues on next page)1

CakePHP Book, Release 3.10

(continued from previous page)// Prior to 3.6 use TableRegistry::get('Users')$users = TableRegistry::getTableLocator()->get('Users');$query = $users->find();foreach ($query as $row) {echo $row->username;}
You may notice that we didn’t have to write any code before we could start working with our data. By using conventions,
CakePHP will use standard classes for table and entity classes that have not yet been defined.
If we wanted to make a new user and save it (with validation) we would do something like:use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Users')$users = TableRegistry::getTableLocator()->get('Users');$user = $users->newEntity(['email' => 'mark@example.com']);$users->save($user);The View Layer
The View layer renders a presentation of modeled data. Being separate from the Model objects, it is responsible forusing the information it has available to produce any presentational interface your application might need.
For example, the view could use model data to render an HTML view template containing it, or a XML formatted resultfor others to consume:// In a view template file, we'll render an 'element' for each user.
<?php foreach ($users as $user): ?><li class="user"><?= $this->element('user_info', ['user' => $user]) ?></li><?php endforeach; ?>The View layer provides a number of extension points like View Templates, Elements and View Cells to let you re-use
your presentation logic.
The View layer is not only limited to HTML or text representation of the data. It can be used to deliver common data
formats like JSON, XML, and through a pluggable architecture any other format you may need, such as CSV.

The Controller Layer
The Controller layer handles requests from users. It is responsible for rendering a response with the aid of both theModel and the View layers.
A controller can be seen as a manager that ensures that all resources needed for completing a task are delegated to thecorrect workers. It waits for petitions from clients, checks their validity according to authentication or authorization
rules, delegates data fetching or processing to the model, selects the type of presentational data that the clients are
accepting, and finally delegates the rendering process to the View layer. An example of a user registration controller
would be:2

Chapter 1. CakePHP at a Glance

CakePHP Book, Release 3.10

public function add(){$user = $this->Users->newEntity();if ($this->request->is('post')) {$user = $this->Users->patchEntity($user, $this->request->getData());
if ($this->Users->save($user, ['validate' => 'registration'])) {$this->Flash->success(__('You are now registered.'));} else {$this->Flash->error(__('There were some problems.'));}}$this->set('user', $user);}
You may notice that we never explicitly rendered a view. CakePHP’s conventions will take care of selecting the rightview and rendering it with the view data we prepared with set().

CakePHP Request Cycle
Now that you are familiar with the different layers in CakePHP, lets review how a request cycle works in CakePHP:
The typical CakePHP request cycle starts with a user requesting a page or resource in your application. At a high level
each request goes through the following steps:
1. The webserver rewrite rules direct the request to webroot/index.php.
2. Your Application is loaded and bound to an HttpServer.
3. Your application’s middleware is initialized.
4. A request and response is dispatched through the PSR-7 Middleware that your application uses. Typically thisincludes error trapping and routing.
5. If no response is returned from the middleware and the request contains routing information, a controller & action
are selected.
6. The controller’s action is called and the controller interacts with the required Models and Components.
7. The controller delegates response creation to the View to generate the output resulting from the model data.
8. The view uses Helpers and Cells to generate the response body and headers.
9. The response is sent back out through the /controllers/middleware.
10. The HttpServer emits the response to the webserver.

Just the Start
Hopefully this quick overview has piqued your interest. Some other great features in CakePHP are:
• A caching framework that integrates with Memcached, Redis and other backends.
• Powerful code generation tools so you can start immediately.
• Integrated testing framework so you can ensure your code works perfectly.
The next obvious steps are to download CakePHP, read the tutorial and build something awesome.

CakePHP Request Cycle

3

CakePHP Book, Release 3.10

4Chapter 1. CakePHP at a Glance

CakePHP Book, Release 3.10

Additional Reading
Where to Get Help
The Official CakePHP website
https://cakephp.org
The Official CakePHP website is always a great place to visit. It features links to oft-used developer tools, screencasts,
donation opportunities, and downloads.
The Cookbook
https://book.cakephp.org
This manual should probably be the first place you go to get answers. As with many other open source projects, we
get new folks regularly. Try your best to answer your questions on your own first. Answers may come slower, but willremain longer – and you’ll also be lightening our support load. Both the manual and the API have an online component.
The Bakery
https://bakery.cakephp.org
The CakePHP Bakery is a clearing house for all things regarding CakePHP. Check it out for tutorials, case studies, andcode examples. Once you’re acquainted with CakePHP, log on and share your knowledge with the community and gain
instant fame and fortune.
The API
https://api.cakephp.org/
Straight to the point and straight from the core developers, the CakePHP API (Application Programming Interface) isthe most comprehensive documentation around for all the nitty gritty details of the internal workings of the framework.
It’s a straight forward code reference, so bring your propeller hat.
The Test Cases
If you ever feel the information provided in the API is not sufficient, check out the code of the test cases provided with
CakePHP. They can serve as practical examples for function and data member usage for a class.
tests/TestCase/

Additional Reading5

CakePHP Book, Release 3.10

The IRC Channel
IRC Channels on irc.freenode.net:• #cakephp – General Discussion• #cakephp-docs – Documentation• #cakephp-bakery – Bakery• #cakephp-fr – French Canal.
If you’re stumped, give us a holler in the CakePHP IRC channel. Someone from the development team4 is usually
there, especially during the daylight hours for North and South America users. We’d love to hear from you, whether
you need some help, want to find users in your area, or would like to donate your brand new sports car.
Official CakePHP Forum
CakePHP Official Forum5
Our official forum where you can ask for help, suggest ideas and have a talk about CakePHP. It’s a perfect place forquickly finding answers and help others. Join the CakePHP family by signing up.
Stackoverflow
https://stackoverflow.com/6
Tag your questions with cakephp and the specific version you are using to enable existing users of stackoverflow tofind your questions.
Where to get Help in your Language
Danish• Danish CakePHP Slack Channel7
French• French CakePHP Community8
4 https://github.com/cakephp?tab=members
5 https://discourse.cakephp.org
6 https://stackoverflow.com/questions/tagged/cakephp/
7 https://cakesf.slack.com/messages/denmark/8 https://cakephp-fr.org

6

Chapter 1. CakePHP at a Glance

CakePHP Book, Release 3.10

German• German CakePHP Slack Channel9• German CakePHP Facebook Group10
Iranian• Iranian CakePHP Community11
Dutch• Dutch CakePHP Slack Channel12
Japanese• Japanese CakePHP Slack Channel13• Japanese CakePHP Facebook Group14
Portuguese• Portuguese CakePHP Google Group15
Spanish• Spanish CakePHP Slack Channel16• Spanish CakePHP IRC Channel• Spanish CakePHP Google Group17

CakePHP Conventions
We are big fans of convention over configuration. While it takes a bit of time to learn CakePHP’s conventions, yousave time in the long run. By following conventions, you get free functionality, and you liberate yourself from themaintenance nightmare of tracking config files. Conventions also make for a very uniform development experience,
allowing other developers to jump in and help.
9 https://cakesf.slack.com/messages/german/
10 https://www.facebook.com/groups/146324018754907/
11 https://cakephp.ir
12 https://cakesf.slack.com/messages/netherlands/
13 https://cakesf.slack.com/messages/japanese/
14 https://www.facebook.com/groups/304490963004377/
15 https://groups.google.com/group/cakephp-pt
16 https://cakesf.slack.com/messages/spanish/
17 https://groups.google.com/group/cakephp-esp

Additional Reading7

CakePHP Book, Release 3.10

Controller Conventions
Controller class names are plural, PascalCased, and end in Controller.
ArticleCategoriesController are both examples of conventional controller names.

UsersController andPublic methods on Controllers are often exposed as ‘actions’ accessible through a web browser. For example the /users/view maps to the view() method of the UsersController out of the box. Protected or private methods
cannot be accessed with routing.
URL Considerations for Controller Names
As you’ve just seen, single word controllers map to a simple lower case URL path. For example, UsersController(which would be defined in the file name UsersController.php) is accessed from http://example.com/users.
While you can route multiple word controllers in any way you like, the convention is that your URLs are lowercase anddashed using the DashedRoute class, therefore /article-categories/view-all is the correct form to access the
ArticleCategoriesController::viewAll() action.
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' // PascalCased'plugin' => 'MyPlugin', // PascalCased'controller' => 'ControllerName', // PascalCased'action' => 'actionName' // camelBacked]
For more information on CakePHP URLs and parameter handling, see Connecting Routes.
File and Class Name Conventions
In general, filenames match the class names, and follow the PSR-4 standard for autoloading. The following are someexamples of class names and their filenames:• The Controller class LatestArticlesController would be found in a file named LatestArticlesController.php• The Component class MyHandyComponent would be found in a file named MyHandyComponent.php• The Table class OptionValuesTable would be found in a file named OptionValuesTable.php.
• The Entity class OptionValue would be found in a file named OptionValue.php.
• The Behavior class EspeciallyFunkableBehavior would be found in a file named EspeciallyFunkableBehavior.php• The View class SuperSimpleView would be found in a file named SuperSimpleView.php• The Helper class BestEverHelper would be found in a file named BestEverHelper.php
Each file would be located in the appropriate folder/namespace in your app folder.

8

Chapter 1. CakePHP at a Glance

CakePHP Book, Release 3.10

Database Conventions
Table names corresponding to CakePHP models are plural and underscored.
article_categories, and user_favorite_pages respectively.

For example users,

Field/Column names with two or more words are underscored: first_name.
Foreign keys in hasMany, belongsTo/hasOne relationships are recognized by default as the (singular) name of the related
table followed by _id. So if Users hasMany Articles, the articles table will refer to the users table via a user_id
foreign key. For a table like article_categories whose name contains multiple words, the foreign key would bearticle_category_id.
Join tables, used in BelongsToMany relationships between models, should be named after the model tables they will
join or the bake command won’t work, arranged in alphabetical order (articles_tags rather than tags_articles).
If you need to add additional columns on the junction table you should create a separate entity/table class for that table.
In addition to using an auto-incrementing integer as primary keys, you can also use UUID columns. CakePHP will
create UUID values automatically using (Cake\Utility\Text::uuid()) whenever you save new records using theTable::save() method.
Model Conventions
Table class names are plural, PascalCased and end in Table. UsersTable, ArticleCategoriesTable, andUserFavoritePagesTable are all examples of table class names matching the users, article_categories anduser_favorite_pages tables respectively.
Entity class names are singular PascalCased and have no suffix. User, ArticleCategory, and UserFavoritePage
are all examples of entity names matching the users, article_categories and user_favorite_pages tables
respectively.
View Conventions
View template files are named after the controller functions they display, in an underscored form. The viewAll()function of the ArticlesController class will look for a view template in src/Template/Articles/view_all.ctp.
The basic pattern is src/Template/Controller/underscored_function_name.ctp.
Note: By default CakePHP uses English inflections. If you have database tables/columns that use another language,
you will need to add inflection rules (from singular to plural and vice-versa). You can use Cake\Utility\Inflector
to define your custom inflection rules. See the documentation about Inflector for more information.

Plugins Conventions
It is useful to prefix a CakePHP plugin with “cakephp-” in the package name. This makes the name semantically relatedon the framework it depends on.
Do not use the CakePHP namespace (cakephp) as vendor name as this is reserved to CakePHP owned plugins. The
convention is to use lowercase letters and dashes as separator:// Badcakephp/foo-bar// Good
your-name/cakephp-foo-bar

Additional Reading9CakePHP Book, Release 3.10

Summarized
By naming the pieces of your application using CakePHP conventions, you gain functionality without the hassle andmaintenance tethers of configuration. Here’s a final example that ties the conventions together:• Database table: “articles”• Table class: ArticlesTable, found at src/Model/Table/ArticlesTable.php• Entity class: Article, found at src/Model/Entity/Article.php• Controller class: ArticlesController, found at src/Controller/ArticlesController.php• View template, found at src/Template/Articles/index.ctp
Using these conventions, CakePHP knows that a request to http://example.com/articles maps to a call on theindex() function of the ArticlesController, where the Articles model is automatically available (and automaticallytied to the ‘articles’ table in the database), and renders to a file. None of these relationships have been configured byany means other than by creating classes and files that you’d need to create anyway.
Now that you’ve been introduced to CakePHP’s fundamentals, you might try a run through the Content Management
Tutorial to see how things fit together.
See awesome list recommendations18 for details.

CakePHP Folder Structure
After you’ve downloaded the CakePHP application skeleton, there are a few top level folders you should see:
• The bin folder holds the Cake console executables.
• The config folder holds the Configuration files CakePHP uses. Database connection details, bootstrapping, coreconfiguration files and more should be stored here.
• The plugins folder is where the Plugins your application uses are stored.
• The logs folder normally contains your log files, depending on your log configuration.
• The src folder will be where your application’s source files will be placed.
• The tests folder will be where you put the test cases for your application.
• The tmp folder is where CakePHP stores temporary data. The actual data it stores depends on how you have
CakePHP configured, but this folder is usually used to store translation messages, model descriptions and sometimes session information.
• The vendor folder is where CakePHP and other application dependencies will be installed by Composer19 . Editing these files is not advised, as Composer will overwrite your changes next time you update.
• The webroot directory is the public document root of your application. It contains all the files you want to be
publicly reachable.
Make sure that the tmp and logs folders exist and are writable, otherwise the performance of your application
will be severely impacted. In debug mode, CakePHP will warn you, if these directories are not writable.
18 https://github.com/FriendsOfCake/awesome-cakephp/blob/master/CONTRIBUTING.md#tips-for-creating-cakephp-plugins
19 https://getcomposer.org

10

Chapter 1. CakePHP at a Glance

CakePHP Book, Release 3.10

The src Folder
CakePHP’s src folder is where you will do most of your application development. Let’s look a little closer at the folders
inside src.
CommandContains your application’s console commands. See Console Commands to learn more.
ConsoleContains the installation script executed by Composer.
Controller
Contains your application’s Controllers and their components.
LocaleStores language files for internationalization.
Middleware
Stores any /controllers/middleware for your application.
Model
Contains your application’s tables, entities and behaviors.
Shell
Contains shell tasks for your application. For more information see Console Tools, Shells & Tasks.
Template
Presentational files are placed here: elements, error pages, layouts, and view template files.
View
Presentational classes are placed here: views, cells, helpers.
Note: The folders Command and Locale are not there by default. You can add them when you need them.

Additional Reading11

CakePHP Book, Release 3.10

12Chapter 1. CakePHP at a GlanceCHAPTER 2

Quick Start Guide

The best way to experience and learn CakePHP is to sit down and build something. To start off we’ll build a simple
Content Management application.

Content Management Tutorial
This tutorial will walk you through the creation of a simple CMS (Content Management System) application. To start
with, we’ll be installing CakePHP, creating our database, and building simple article management.
Here’s what you’ll need:
1. A database server. We’re going to be using MySQL server in this tutorial. You’ll need to know enough about
SQL in order to create a database, and run SQL snippets from the tutorial. CakePHP will handle building all thequeries your application needs. Since we’re using MySQL, also make sure that you have pdo_mysql enabled in
PHP.
2. Basic PHP knowledge.
Before starting you should make sure that you have got an up to date PHP version:php -v
You should at least have got installed PHP 5.6 (CLI) or higher. Your webserver’s PHP version must also be of 5.6 orhigher, and should be the same version your command line interface (CLI) PHP is.

13

CakePHP Book, Release 3.10

Getting CakePHPThe easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from yourterminal or command line prompt. First, you’ll need to download and install Composer if you haven’t done so already.
If you have cURL installed, it’s as easy as running the following:
curl -s https://getcomposer.org/installer | php
Or, you can download composer.phar from the Composer website20 .
Then simply type the following line in your terminal from your installation directory to install the CakePHP application
skeleton in the cms directory of the current working directory:
php composer.phar create-project --prefer-dist cakephp/app:"^3.10" cms
If you downloaded and ran the Composer Windows Installer21 , then type the following line in your terminal from yourinstallation directory (ie. C:\wamp\www\dev\cakephp3):
composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" cms
The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting
the correct file permissions and creating your config/app.php file for you.
There are other ways to install CakePHP. If you cannot or don’t want to use Composer, check out the Installation section.
Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup shouldlook something like the following:
/cms
/bin
/config/logs/plugins/src/tests/tmp/vendor/webroot.editorconfig.gitignore.htaccess.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md
Now might be a good time to learn a bit about how CakePHP’s directory structure works: check out the CakePHP
Folder Structure section.
If you get lost during this tutorial, you can see the finished result on GitHub22 .
20 https://getcomposer.org/download/
21 https://getcomposer.org/Composer-Setup.exe
22 https://github.com/cakephp/cms-tutorial

14

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

Checking our Installation
We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you’ll
need to start the development server:
cd /path/to/our/app
bin/cake server

Note: For Windows, the command needs to be bin\cake server (note the backslash).
This will start PHP’s built-in webserver on port 8765. Open up http://localhost:8765 in your web browser to see
the welcome page. All the bullet points should be green chef hats other than CakePHP being able to connect to yourdatabase. If not, you may need to install additional PHP extensions, or set directory permissions.
Next, we will build our Database and create our first model.

CMS Tutorial - Creating the Database
Now that we have CakePHP installed, let’s set up the database for our CMS application. If you haven’t already doneso, create an empty database for use in this tutorial, with a name of your choice, e.g. cake_cms. You can execute thefollowing SQL to create the necessary tables:
USE cake_cms;
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 articles (id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
title VARCHAR(255) NOT NULL,
slug VARCHAR(191) NOT NULL,
body TEXT,
published BOOLEAN DEFAULT FALSE,
created DATETIME,
modified DATETIME,UNIQUE KEY (slug),
FOREIGN KEY user_key (user_id) REFERENCES users(id)) CHARSET=utf8mb4;
CREATE TABLE tags (id INT AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(191),
created DATETIME,
modified DATETIME,(continues on next page)

CMS Tutorial - Creating the Database15

CakePHP Book, Release 3.10

(continued from previous page)

UNIQUE KEY (title)) CHARSET=utf8mb4;
CREATE TABLE articles_tags (article_id INT NOT NULL,
tag_id INT NOT NULL,PRIMARY KEY (article_id, tag_id),
FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),FOREIGN KEY article_key(article_id) REFERENCES articles(id));
INSERT INTO users (email, password, created, modified)
VALUES('cakephp@example.com', 'secret', NOW(), NOW());
INSERT INTO articles (user_id, title, slug, body, published, created, modified)
VALUES(1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());
You may have noticed that the articles_tags table used a composite primary key. CakePHP supports composite
primary keys almost everywhere allowing you to have simpler schemas that don’t require additional id columns.
The table and column names we used were not arbitrary. By using CakePHP’s naming conventions, we can leverage
CakePHP more effectively and avoid needing to configure the framework. While CakePHP is flexible enough to accommodate almost any database schema, adhering to the conventions will save you time as you can leverage the convention
based defaults CakePHP provides.

Database Configuration
Next, let’s tell CakePHP where our database is and how to connect to it. Replace the values in the Datasources.
default array in your config/app_local.php file with those that apply to your setup. A sample completed configurationarray might look something like the following:<?php
return [// More configuration above.
'Datasources' => ['default' => ['className' => 'Cake\Database\Connection','driver' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'localhost','username' => 'cakephp','password' => 'AngelF00dC4k3~','database' => 'cake_cms','encoding' => 'utf8mb4','timezone' => 'UTC','cacheMetadata' => true,],],// More configuration below.
];

16

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

Once you’ve saved your config/app_local.php file, you should see that ‘CakePHP is able to connect to the database’section have a green chef hat.
Note: A copy of CakePHP’s default configuration file is found in config/app.default.php.

Creating our First Model
Models are the heart of a CakePHP applications. They enable us to read and modify our data. They allow us to build
relations between our data, validate data, and apply application rules. Models build the foundations necessary to build
our controller actions and templates.
CakePHP’s models are composed of Table and Entity objects. Table objects provide access to the collection ofentities stored in a specific table. They are stored in src/Model/Table. The file we’ll be creating will be saved tosrc/Model/Table/ArticlesTable.php. The completed file should look like this:<?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');}}We’ve attached the Timestamp behavior which will automatically populate the created and modified columns of ourtable. By naming our Table object ArticlesTable, CakePHP can use naming conventions to know that our model
uses the articles table. CakePHP also uses conventions to know that the id column is our table’s primary key.
Note:
CakePHP will dynamically create a model object for you if it cannot find a corresponding file insrc/Model/Table. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.
We’ll also create an Entity class for our Articles. Entities represent a single record in the database, and provide row
level behavior for our data. Our entity will be saved to src/Model/Entity/Article.php. The completed file should look
like this:<?php// src/Model/Entity/Article.php
namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{
protected $_accessible = ['*' => true,(continues on next page)

CMS Tutorial - Creating the Database17

CakePHP Book, Release 3.10

(continued from previous page)'id' => false,'slug' => false,];}
Our entity is quite slim right now, and we’ve only setup the _accessible property which controls how properties canbe modified by Mass Assignment.
We can’t do much with our models right now, so next we’ll create our first Controller and Template to allow us tointeract with our model.

CMS Tutorial - Creating the Articles Controller
With our model created, we need a controller for our articles. Controllers in CakePHP handle HTTP requests andexecute business logic contained in model methods, to prepare the response. We’ll place this new controller in a filecalled ArticlesController.php inside the src/Controller directory. Here’s what the basic controller should look like:<?php// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{}
Now, let’s add an action to our controller. Actions are controller methods that have routes connected to them. For example, when a user requests www.example.com/articles/index (which is also the same as www.example.com/articles),
CakePHP will call the index method of your ArticlesController. This method should query the model layer, andprepare a response by rendering a Template in the View. The code for that action would look like this:<?php// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{
public function index(){$this->loadComponent('Paginator');$articles = $this->Paginator->paginate($this->Articles->find());$this->set(compact('articles'));}}By defining function index() in our ArticlesController, users can now access the logic there by requestingwww.example.com/articles/index. Similarly, if we were to define a function called foobar(), users would be able toaccess that at www.example.com/articles/foobar. You may be tempted to name your controllers and actions in a waythat allows you to obtain specific URLs. Resist that temptation. Instead, follow the CakePHP Conventions creating
readable, meaningful action names. You can then use Routing to connect the URLs you want to the actions you’ve
created.
18

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

Our controller action is very simple. It fetches a paginated set of articles from the database, using the Articles Modelthat is automatically loaded via naming conventions. It then uses set() to pass the articles into the Template (which
we’ll create soon). CakePHP will automatically render the template after our controller action completes.

Create the Article List Template
Now that we have our controller pulling data from the model, and preparing our view context, let’s create a view
template for our index action.
CakePHP view templates are presentation-flavored PHP code that is inserted inside the application’s layout. While
we’ll be creating HTML here, Views can also generate JSON, CSV or even binary files like PDFs.
A layout is presentation code that is wrapped around a view. Layout files contain common site elements like headers,footers and navigation elements. Your application can have multiple layouts, and you can switch between them, but for
now, let’s just use the default layout.
CakePHP’s template files are stored in src/Template inside a folder named after the controller they correspond to. So
we’ll have to create a folder named ‘Articles’ in this case. Add the following code to your application:<!-- File: src/Template/Articles/index.ctp --><h1>Articles</h1><table><tr><th>Title</th><th>Created</th></tr><!-- Here is where we iterate through our $articles query object, printing out␣
article info -->˓→<?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
</tr>
<?php endforeach; ?></table>In the last section we assigned the ‘articles’ variable to the view using set(). Variables passed into the view areavailable in the view templates as local variables which we used in the above code.
You might have noticed the use of an object called $this->Html. This is an instance of the CakePHP HtmlHelper.
CakePHP comes with a set of view helpers that make tasks like creating links, forms, and pagination buttons easy.
You can learn more about Helpers in their chapter, but what’s important to note here is that the link() method will
generate an HTML link with the given link text (the first parameter) and URL (the second parameter).
When specifying URLs in CakePHP, it is recommended that you use arrays or named routes. These syntaxes allow you
to leverage the reverse routing features CakePHP offers.

CMS Tutorial - Creating the Articles Controller

19CakePHP Book, Release 3.10

At this point, you should be able to point your browser to http://localhost:8765/articles/index. You should see yourlist view, correctly formatted with the title and table listing of the articles.

Create the View Action
If you were to click one of the ‘view’ links in our Articles list page, you’d see an error page saying that action hasn’t
been implemented. Lets fix that now:// Add to existing src/Controller/ArticlesController.php filepublic function view($slug = null){$article = $this->Articles->findBySlug($slug)->firstOrFail();$this->set(compact('article'));}While this is a simple action, we’ve used some powerful CakePHP features. We start our action off by using
findBySlug() which is a Dynamic Finder. This method allows us to create a basic query that finds articles by agiven slug. We then use firstOrFail() to either fetch the first record, or throw a NotFoundException.
Our action takes a $slug parameter, but where does that parameter come from? If a user requests /articles/view/
first-post, then the value ‘first-post’ is passed as $slug by CakePHP’s routing and dispatching layers. If we reload
our browser with our new action saved, we’d see another CakePHP error page telling us we’re missing a view template;
let’s fix that.

Create the View Template
Let’s create the view for our new ‘view’ action and place it in src/Template/Articles/view.ctp<!-- File: src/Template/Articles/view.ctp --><h1><?= h($article->title) ?></h1><p><?= h($article->body) ?></p><p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p><p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>
You can verify that this is working by trying the links at /articles/index or manually requesting an article byaccessing URLs like /articles/view/first-post.

Adding Articles
With the basic read views created, we need to make it possible for new articles to be created. Start by creating an add()
action in the ArticlesController. Our controller should now look like:// src/Controller/ArticlesController.php
namespace App\Controller;
use App\Controller\AppController;class ArticlesController extends AppController{(continues on next page)

20

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

(continued from previous page)

public function initialize(){
parent::initialize();$this->loadComponent('Paginator');$this->loadComponent('Flash'); // Include the FlashComponent}
public function index(){$articles = $this->Paginator->paginate($this->Articles->find());$this->set(compact('articles'));}public function view($slug){$article = $this->Articles->findBySlug($slug)->firstOrFail();$this->set(compact('article'));}public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {$article = $this->Articles->patchEntity($article, $this->request->getData());// Hardcoding the user_id is temporary, and will be removed later// when we build authentication out.
$article->user_id = 1;
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);}}

Note: You need to include the Flash component in any controller where you will use it. Often it makes sense toinclude it in your AppController.
Here’s what the add() action does:• If the HTTP method of the request was POST, try to save the data using the Articles model.
• If for some reason it doesn’t save, just render the view. This gives us a chance to show the user validation errors
or other warnings.
Every CakePHP request includes a request object which is accessible using $this->request. The request object
contains information regarding the request that was just received. We use the Cake\Http\ServerRequest::is()method to check that the request is a HTTP POST request.
CMS Tutorial - Creating the Articles Controller

21CakePHP Book, Release 3.10

Our POST data is available in $this->request->getData(). You can use the pr() or debug() functions to print
it out if you want to see what it looks like. To save our data, we first ‘marshal’ the POST data into an Article Entity.
The Entity is then persisted using the ArticlesTable we created earlier.
After saving our new article we use FlashComponent’s success() method to set a message into the session. The
success method is provided using PHP’s magic method features23 . Flash messages will be displayed on thenext page after redirecting. In our layout we have <?= $this->Flash->render() ?> which displays flash messages and clears the corresponding session variable. Finally, after saving is complete, we use Cake\Controller\
Controller::redirect to send the user back to the articles list. The param ['action' => 'index'] translates to
URL /articles i.e the index action of the ArticlesController. You can refer to Cake\Routing\Router::url()function on the API24 to see the formats in which you can specify a URL for various CakePHP functions.

Create Add Template
Here’s our add view template:<!-- File: src/Template/Articles/add.ctp --><h1>Add Article</h1><?php
echo $this->Form->create($article);// Hard code the user for now.
echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>
We use the FormHelper to generate the opening tag for an HTML form.
$this->Form->create() generates:

Here’s the HTML that<form method="post" action="/articles/add">
Because we called create() without a URL option, FormHelper assumes we want the form to submit back to thecurrent action.
The $this->Form->control() method is used to create form elements of the same name. The first parameter tells
CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options - inthis case, the number of rows for the textarea. There’s a bit of introspection and conventions used here. The control()will output different form elements based on the model field specified, and use inflection to generate the label text. You
can customize the label, the input or any other aspect of the form controls using options. The $this->Form->end()call closes the form.
Now let’s go back and update our src/Template/Articles/index.ctp view to include a new “Add Article” link. Before
the <table>, add the following line:<?= $this->Html->link('Add Article', ['action' => 'add']) ?>23 https://php.net/manual/en/language.oop5.overloading.php#object.call
24 https://api.cakephp.org

22

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

Adding Simple Slug Generation
If we were to save an Article right now, saving would fail as we are not creating a slug attribute, and the column is NOT
NULL. Slug values are typically a URL-safe version of an article’s title. We can use the beforeSave() callback of the
ORM to populate our slug:// in src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;// the Text classuse Cake\Utility\Text;// Add the following method.
public function beforeSave($event, $entity, $options){if ($entity->isNew() && !$entity->slug) {$sluggedTitle = Text::slug($entity->title);// trim slug to maximum length defined in schema$entity->slug = substr($sluggedTitle, 0, 191);}}
This code is simple, and doesn’t take into account duplicate slugs. But we’ll fix that later on.

Add Edit Action
Our application can now save articles, but we can’t edit them. Lets rectify that now. Add the following action to your
ArticlesController:// in src/Controller/ArticlesController.php// Add the following method.
public function edit($slug){$article = $this->Articles->findBySlug($slug)->firstOrFail();
if ($this->request->is(['post', 'put'])) {$this->Articles->patchEntity($article, $this->request->getData());
if ($this->Articles->save($article)) {$this->Flash->success(__('Your article has been updated.'));
return $this->redirect(['action' => 'index']);}$this->Flash->error(__('Unable to update your article.'));}$this->set('article', $article);}This action first ensures that the user has tried to access an existing record. If they haven’t passed in an $slug parameter,or the article does not exist, a NotFoundException will be thrown, and the CakePHP ErrorHandler will render theappropriate error page.

CMS Tutorial - Creating the Articles Controller

23CakePHP Book, Release 3.10

Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST/PUT data
to update our article entity by using the patchEntity() method. Finally, we call save() set the appropriate flash
message and either redirect or display validation errors.

Create Edit Template
The edit template should look like this:<!-- File: src/Template/Articles/edit.ctp --><h1>Edit Article</h1><?php
echo $this->Form->create($article);echo $this->Form->control('user_id', ['type' => 'hidden']);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>This template outputs the edit form (with the values populated), along with any necessary validation error messages.
You can now update your index view with links to edit specific articles:<!-- File: src/Template/Articles/index.ctp(edit links added) --><h1>Articles</h1><p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p><table><tr><th>Title</th><th>Created</th><th>Action</th></tr><!-- Here's where we iterate through our $articles query object, printing out article␣
˓→info --><?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
</td>
</tr>
<?php endforeach; ?></table>24

Chapter 2. Quick Start Guide

CakePHP Book, Release 3.10

Update Validation Rules for Articles
Up until this point our Articles had no input validation done. Lets fix that by using a validator:// src/Model/Table/ArticlesTable.php// add this use statement right below the namespace declaration to import// the Validator classuse Cake\Validation\Validator;// Add the following method.
public function validationDefault(Validator $validator){$validator->allowEmptyString('title', 'Title cannot be empty', false)->minLength('title', 10)->maxLength('title', 255);$validator->allowEmptyString('body', 'Body cannot be empty', false)->minLength('body', 10);return $validator;}
The validationDefault() method tells CakePHP how to validate your data when the save() method is called.
Here, we’ve specified that both the title, and body fields must not be empty, and have certain length constraints.
CakePHP’s validation engine is powerful and flexible. It provides a suite of frequently used rules for tasks like email
addresses, IP addresses etc. and the flexibility for adding your own validation rules. For more information on that
setup, check the Validation documentation.
Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how
it works. Since we’ve used the Cake\View\Helper\FormHelper::control() method of the FormHelper to create
our form elements, our validation error messages will be shown automatically.

Add Delete Action
Next, let’s make a way for users to delete articles. Start with a delete() action in the ArticlesController:// src/Controller/ArticlesController.php
public function delete($slug){$this->request->allowMethod(['post', 'delete']);$article = $this->Articles->findBySlug($slug)->firstOrFail();
if ($this->Articles->delete($article)) {$this->Flash->success(__('The {0} article has been deleted.', $article->title));return $this->redirect(['action' => 'index']);}}This logic deletes the article specified by $slug, and uses $this->Flash->success() to show the user a confirmation message after redirecting them to /articles. If the user attempts to delete an article using a GET request,
CMS Tutorial - Creating the Articles Controller

25CakePHP Book, Release 3.10

allowMethod() will throw an exception. Uncaught exceptions are captured by CakePHP’s exception handler, and anice error page is displayed. There are many built-in Exceptions that can be used to indicate the various HTTP errors
your application might need to generate.
Warning: Allowing content to be deleted using GET requests is very dangerous, as web crawlers could accidentally
delete all your content. That is why we used allowMethod() in our controller.
Because we’re only executing logic and redirecting to another action, this action has no template. You might want to
update your index template with links that allow users to delete articles:<!-- File: src/Template/Articles/index.ctp(delete links added) --><h1>Articles</h1><p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p><table><tr><th>Title</th><th>Created</th><th>Action</th></tr><!-- Here's where we iterate through our $articles query object, printing out article␣
˓→info --><?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?><?= $this->Form->postLink('Delete',['action' => 'delete', $article->slug],['confirm' => 'Are you sure?'])
?>
</td>
</tr>
<?php endforeach; ?></table>Using postLink() will create a link that uses JavaScript to do a POST request deleting our article.
Note: This view code also uses the FormHelper to prompt the user with a JavaScript confirmation dialog before theyattempt to delete an article.
With a basic articles management setup, we’ll create the basic actions for our Tags and Users tables.
26

Chapter 2. Quick Start Guide

CHAPTER 3

3.x Migration Guide

Migration guides contain information regarding the new features introduced in each version and the migration path
between 2.x and 3.x. If you are currently using 1.x you should first upgrade to 2.x. See the 2.x documentation for the
relevant upgrade guides.

3.10 Migration Guide
3.10 Migration Guide
CakePHP 3.10 is an API compatible upgrade from 3.8. This page outlines the changes and improvements made.
To upgrade to 3.10.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.10.*"Deprecations
No features were deprecated in 3.10

27

CakePHP Book, Release 3.10

Behavior Changes
While the following changes do not change the signature of any methods they do change the semantics or behavior of
methods.
Validation• Validation::time() will now reject a string if minutes are missing. Previously, this would accept hours-only
digits although the api documentation showed minutes were required.
New Features• Improved API documentation.
• Backported improvements to Validation::time() from 4.x.
• EmailTrait::assertMailSentFrom() now accepts an array with an address & alias.

3.9 Migration Guide
3.9 Migration Guide
CakePHP 3.9 is an API compatible upgrade from 3.8. This page outlines the changes and improvements made.
To upgrade to 3.9.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.9.*"

Deprecations• ConsoleIo::info(), success(), warning() and error() will no longer accept null values in the message
parameter in 4.0.
• Using a comma separated string for $fixtures in test cases is deprecated. Instead use an array, or implement
the new getFixtures() method on your test case classes.
• Validator::errors() was renamed to Validator::validate().
• FormHelper::create() now emits deprecation warnings when the $context parameter is a boolean or string.
These values trigger fatal errors in 4.0 and will need to be updated before upgrading.
• The magic method signature for FunctionBuilder::cast([...])
FunctionBuilder::cast('field', 'type') instead.

isdeprecated.

Use• Abandoned zendframework package has been replaced with laminas25 which provides backwards-compatibleclasses.
25 https://github.com/laminas/laminas-diactoros

28

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

New Features
Cache• MemcachedEngine::write() and add() no longer cap duration to 30 days. Instead all expiration values areforwarded to memcache.
Console• ConsoleIo::abort() was added.
• Command classes can implement the defaultName() method to overwrite the conventions based CLI name.
Database• Driver::newTableSchema() was added. This hook method lets you customize which the class used for schema
metadata.
• FunctionBuilder::cast() was added.
• Query::orderAsc() and Query::orderDesc() now accept Closure’s as their field enabling you to use build
complex order expressions with the provided QueryExpression object.
Datasource• Cake\Datasource\SimplePaginator was added. This class makes paginating very large results more efficient. It skips running the potentially expensive count() query. If you only use ‘next’ and ‘previous’ navigation
in your pagination controls this class can be a good solution.
Http• Cake\Http\Client\Response::isSuccess() was backported from 4.0• Cake\Http\Middleware\CspMiddleware was backported from 4.0• BaseApplication::addOptionalPlugin() was added. This method handles loading plugins, and handlingerrors for plugins that may not exist because they are dev dependencies.
I18n• Number::FORMAT_CURRENCY_ACCOUNTING was added.
• Number::CURRENCY_ACCOUNTING was added.
• Number::getDefaultCurrencyFormat() and Number::setDefaultCurrencyFormat() were added.
These methods let you define the formatting style for currency values.
• The setJsonEncodeFormat method on Time, FrozenTime, Date and FrozenDate now accepts a callable thatcan be used to return a custom string.
• The i18n global functions now only return strings. The changes made to 4.0 to remove the null return value whenno translation string is provide have been backported to 3.9.

3.9 Migration Guide

29

CakePHP Book, Release 3.10

• Lenient parsing can be disabled for parseDateTime() and parseDate() using disableLenientParsing().
The default is enabled - the same as IntlDateFormatter.
ORM• Table::saveManyOrFail() method has been added that will throw PersistenceFailedException withthe specific entity that failed in case of an error. The entities are saved within a transaction.
• Table::deleteMany() and Table::deleteManyOrFail() methods have been added for removing many
entities at once including callbacks. The entities are removed within a transaction.
• TableLocator::clear() now resets the internal options array.
• BelongsToMany associations now respect the bindingKey set in the junction table’s BelongsTo association. Previously, the target table’s primary key was always used instead.
• Query::clearResult() was added. This method lets you remove the result from a query so you can re-executeit.
TestSuite• TestCase::getFixtures() was added. This method lets you generate your fixture list using application specific logic if necessary.
• TestSuite\EmailTrait::assertMailContainsAttachment() was added.
Utility• Hash::combine() now accepts null for the $keyPath parameter. Providing null will result in a numericallyindexed output array.
• Hash::sort() now accepts the SORT_ASC and SORT_DESC constants in the direction parameter.
• Text::uuid() now uses random_int() with PHP 5.6 insted of mt_rand(). This adds a dependency onparagonie/random_compat which implements it for PHP 5.6.
Validation• The ‘empty’ field detection in Validator now considers UploadedFileInterface objects that have
UPLOAD_ERR_NO_FILE as their error code to be empty.
• Validation::notAlphaNumeric() and Validator::notAlphaNumeric() were backported from 4.x.
• Validation::asciiAlphaNumeric() and Validator::asciiAlphaNumeric() were backported from 4.x.
• Validation::notAsciiAlphaNumeric() and Validator::notAsciiAlphaNumeric() were backported
from 4.x.

30

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

View
• FormHelper had the selectedClass template variable added. This template key controls the class name used
when a radio or checkbox is selected.
• TextHelper::slug() was backported from 4.0.

3.8 Migration Guide
3.8 Migration Guide
CakePHP 3.8 is an API compatible upgrade from 3.7. This page outlines the changes and improvements made in 3.8.
To upgrade to 3.8.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.8.*"

Deprecations• Validator::allowEmptyString(), allowEmptyArray(), allowEmptyFile(), allowEmptyDate(),allowEmptyTime(), and allowEmptyDateTime() now emit a deprecation warning when using the $field,$when, $message signature. Instead you should use $field, $message, $when.
• EntityTrait::visibleProperties() is now deprecated. Use getVisible() instead.
Behavior Changes• Cake\ORM\Table::findOrCreate() now throws a PersistenceFailedException if the find fails and theentity created from $search contains invalid data. Previously an invalid entity would be saved.
• Command classes that have their $modelClass property set will now autoload that model. The manual
loadModel() call with empty argument is not necessary anymore. This makes it consistent to how Shell classes
worked.
• The default format for Cake\I18n\Time, FrozenTime, Date, and FrozenDate is now
yyyy-MM-dd'T'HH':'mm':'ssxxx which solves localization issues in danish and other european locales.
New Features
Collection• CollectionTrait now uses the newCollection method to create clones. This allows sub-classes to havecollection methods create instances of themselves instead of using Collection.

3.8 Migration Guide

31

CakePHP Book, Release 3.10

Console• Command::executeCommand() was added. This method makes it simple to call another command from thecurrent one.
Datasource• Cake\Datasource\ModelAwareTrait::get() can now locate model classes by fully-qualified class names,
enabling you to use ArticlesTable::class as a parameter to get().
Email• Email::setHeaders() and Email::addHeaders() now allow setting multiple headers of the same name.
For that the value for the particular header key in the array argument passed to above functions must be an array.
e.g. $email->addHeaders(['og:tag' => ['foo', 'bar']]);
Http• Response::withCookieCollection() was added.
ORM• Cake\ORM\Locator\TableLocator can now locate table classes in alternative locations. You can either provide a list of namespaces to the constructor, or use the addLocation() method.
Validation• Validator::notEmptyString(),
notEmptyArray(),
notEmptyFile(),notEmptyDate(),notEmptyTime(), and notEmptyDateTime() were added. They act as compliments to the allowEmpty*
methods added in 3.7.
• Validation::mimeType() now compares checks mime-types in a case insensitive manner.
• Validation::dateTime() now supports the iso8601 format.
View• Radio buttons can now customize the generated label by using the label key inside a complex option definition.
This key will be used instead of the label key defined at the top level options.

32

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

3.7 Migration Guide
3.7 Migration Guide
CakePHP 3.7 is an API compatible upgrade from 3.6. This page outlines the changes and improvements made in 3.7.
To upgrade to 3.7.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.7.*"

Deprecations
The following is a list of deprecated methods, properties and behaviors. These features will continue to function until
4.0.0 after which they will be removed.
• Cake\Form\Form::errors() is deprecated. Use getErrors() instead.
• Cake\Http\Client\Response::$headers is deprecated. Use getHeaders() or getHeaderLine() instead.
• Cake\Http\Client\Response::$body is deprecated. Use getStringBody() instead.
• Cake\Http\Client\Response::$json is deprecated. Use getJson() instead.
• Cake\Http\Client\Response::$xml is deprecated. Use getXml() instead.
• Cake\Http\Client\Response::$cookies is deprecated. Use getCookies() instead.
• Cake\Http\Client\Response::$code is deprecated. Use getStatusCode() instead.
• Cake\Http\Client\Response::body() is deprecated. Use getStringBody() instead.
• Cake\ORM\Association::className() has been deprecated. Use getClassName() and setClassName()instead.
• Using Cake\Database\Query::join()
Query::clause('join').

to

read

informationisdeprecated.

Insteaduse• Using Cake\Database\Query::from()
Query::clause('from').

to

read

informationisdeprecated.

Insteaduse• Cake\Database\Connection::logQueries() is deprecated.
isQueryLoggingEnabled() instead.

Use enableQueryLogging() and• The string/array parameter set for Cake\Http\Response::withCookie() is deprecated. Instead you need topass in Cake\Http\Cookie\Cookie instances.
• Cake\Validation\Validation::cc() has been renamed to creditCard().
• Cake\View\ViewVarsTrait::viewOptions() is deprecated. Use viewBuilder()->setOptions() instead.
• Cake\View\View::$request is protected now. Use View::getRequest()/setRequest() to access a
View’s request instance in other contexts.
• Cake\View\View::$response is protected now. Use View::getResponse()/setResponse() to access a
View’s response instance in other contexts.
• Cake\View\View::$templatePath is protected now. Use getTemplatePath()/setTemplatePath() instead.
• Cake\View\View::$template is protected now. Use getTemplate()/setTemplate() instead.
3.7 Migration Guide33

CakePHP Book, Release 3.10

• Cake\View\View::$layout is protected now. Use getLayout()/setLayout() instead.
• Cake\View\View::$layoutPath is protected now. Use getLayoutPath()/setLayoutPath() instead.
• Cake\View\View::$autoLayout is protected now. Use enableAutoLayout()/isAutoLayoutEnabled()
instead.
• Cake\View\View::$theme is protected now. Use getTheme()/setTheme() instead.
• Cake\View\View::$subDir is protected now. Use getSubDir()/setSubDir() instead.
• Cake\View\View::$plugin is protected now. Use getPlugin()/setPlugin() instead.
• Cake\View\View::$name is protected now. Use getName()/setName() instead.
• Cake\View\View::$elementCache is protected now. Use getElementCache()/setElementCache() instead.
• Cake\View\View::$Blocks is protected now. Use public methods on View to interact with blocks.
• Cake\View\View:$helpers is protected now. Use helpers() to interact with the HelperRegistry instead.
• Cake\View\View::$uuids is deprecated and will be removed in 4.0• Cake\View\View::uuid() is deprecated and will be removed in 4.0• Cake\View\Cell::$template is protected now. Use viewBuilder()->getTemplate()/setTemplate()instead.
• Cake\View\Cell::$plugin is protected now. Use viewBuilder()->getPlugin()/setPlugin() instead.
• Cake\View\Cell::$helpers is protected now. Use viewBuilder()->getHelpers()/setHelpers() instead.
• Cake\View\Cell::$action is protected now.
• Cake\View\Cell::$args is protected now.
• Cake\View\Cell::$View is protected now.
• Cake\View\Cell::$request is protected now.
• Cake\View\Cell::$response is protected now.
• Cake\View\ViewVarsTrait::$viewVars is deprecated. This public property will be removed in 4.0.0. Useset() instead.
• Cake\Filesystem\Folder::normalizePath() is deprecated. You should use correctSlashFor() instead.
• Cake\Mailer\Email::setConfigTransport()
TransportFactory::setConfig() instead.

isdeprecated.

UseCake\Mailer\• Cake\Mailer\Email::getConfigTransport()
TransportFactory::getConfig() instead.

isdeprecated.

UseCake\Mailer\• Cake\Mailer\Email::configTransport()isdeprecated.
TransportFactory::getConfig()/setConfig() instead.

Use

Cake\Mailer\• Cake\Mailer\Email::configuredTransport()
TransportFactory::configured() instead.

Use

Cake\Mailer\isdeprecated.

• Cake\Mailer\Email::dropTransport() is deprecated. Use Cake\Mailer\TransportFactory::drop()
instead.

34

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Following view related methods of Cake\Mailer\Email have been deprecated: setTemplate(),getTemplate(),setLayout(),
getLayout(),
setTheme(),getTheme(),setHelpers(),
getHelpers().
Use the same methods through Email’s view builder instead.
For e.g.
$email->viewBuilder()->getTemplate().
• Cake\Mailer\Mailer::layout() is deprecated. Use $mailer->viewBuilder()->setLayout() instead.
• Helper::$theme is removed. Use View::getTheme() instead.
• Helper::$plugin is removed. Use View::getPlugin() instead.
• Helper::$fieldset and Helper::$tags are deprecated as they are unused.
• Helper::$helpers is now protected and should not be accessed from outside a helper class.
• Helper::$request is removed. Use View::getRequest(), View::setRequest() instead.
• Cake\Core\Plugin::load() andApplication::addPlugin().

loadAll()aredeprecated.

Insteadyoushoulduse• Cake\Core\Plugin::unload() is deprecated. Use Plugin::getCollection()->remove() or clear()instead.
• The following properties of Cake\Error\ExceptionRender are now protected: $error, $controller,$template and $method.
• Using underscored fixtures names in TestCase::$fixtures is deprecated. Use CamelCased names instead.
For e.g. app.FooBar, plugin.MyPlugin.FooBar.
Soft Deprecations
The following methods, properties and features have been deprecated but will not be removed until 5.0.0:• Cake\TestSuite\ConsoleIntegrationTestCase is deprecated. You should include Cake\TestSuite\
ConsoleIntegrationTestTrait into your test case class instead.
Behavior Changes• Cake\Database\Type\IntegerType will now raise an exception when values are not numeric when preparing
SQL statements and converting database results to PHP types.
• Cake\Database\Statement\StatementDecorator::fetchAll() now returns an empty array instead offalse when no result is found.
• Cake\Database\Statement\BufferedStatement no longer inherits from StatementDecorator and nolonger implements the IteratorAggregate interface. Instead it directly implements the Iterator interface
to better support using statements with collections.
• When marshalling data from the request into entities, the ORM will now convert non-scalar data into null forboolean, integer, float, and decimal types.
• ExceptionRenderer will now always call handler methods for custom application exception classes. Previously, custom exception class handler methods would only be invoked in debug mode.
• Router::url() will now default the _method key to GET when generating URLs with Router::url().

3.7 Migration Guide

35

CakePHP Book, Release 3.10

New Features
Cache• The ArrayEngine was added. This engine provides an ephemeral in memory cache implementation. It is ideal
for test suites or long running processes where you don’t want persistent cache storage.
Database• Cake\Database\FunctionsBuilder::rand() was added.
Datasource• Paginator will now match unprefixed sort values in the query string to the primary model if there also exists amatching model prefixed default sort field. As an example, if your controller defines a default sort of ['Users.
name' => 'desc'] you can now use either Users.name or name as your sort key.
Error
• ExceptionRenderer will now look for prefixed error controllers when handling exceptions. This allows you todefine custom error controller logic for each routing prefix in your application.
• ErrorHandlerMiddleware will now include previous exceptions in logging.
Filesystem• Cake\Filesystem\Folder::normalizeFullPath() was added.
Form• Cake\Form\Form::setData() was added. This method makes defining default values for forms simpler.
• Cake\Form\Form::getData() was added.
Http• Cake\Http\ServerRequest::setTrustedProxies() was added.
• Cake\Http\Client will now default to use a Curl based adapter if the curl extension is installed.
• New constants have been added to the SecurityHeadersMiddleware. The new constants are used to build thecomponents of HTTP headers.

36

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Mailer• Cake\Mailer\TransportFactory and Cake\Mailer\TransportRegistry were added. This class extracts
transport creation out of Email, allowing Email to become simpler in the future.
ORM• Cake\ORM\EntityTrait::hasErrors() was added. This method can be used to check whether or not anentity has errors more efficiently than getErrors() does.
• Updating has many association data now respects _ids. This makes patching has many associations work thesame as creating new entities, and creates consistency with belongs to many associations.
Shell• cake i18n extract has a new --relative-paths option that makes path comments in POT files relative tothe application root directory instead of absolute paths.
• cake i18n extract has a new --marker-error option that enables reporting of translation functions thatuse non-static values as comments in POT files.
TestSuite• New assertion methods were added to IntegrationTestCase:– assertResponseNotEquals()– assertHeaderNotContains()– assertRedirectNotContains()– assertFlashElement()– assertFlashElementAt()• The custom assertions provided by IntegrationTestCase and ConsoleIntegrationTestCase are now implemented through constraint classes.
• TestCase::loadPlugins(), removePlugins() and clearPlugins() were added to make working withdynamically loaded plugins easier now that Plugin::load() and Plugin::unload() are deprecated.
• getMockForModel() now supports null for the $methods parameter. This allows you to create mocks thatstill execute the original code. This aligns the behavior with how PHPUnit mock objects work.
• Added EmailTrait to help facilitate testing emails.
• The default messages for integration assertions have been improved to provide more context from the exceptionthat was raised if possible.

3.7 Migration Guide37

CakePHP Book, Release 3.10

Utility• Cake\Utility\Text::getTransliterator() was added.
• Cake\Utility\Text::setTransliterator() was added.
• Cake\Utility\Xml::loadHtml() was added.
Validation• Cake\Validation\Validation::iban() was added for validating international bank account numbers.
• Cake\Validation\Validator::allowEmptyString(), allowEmptyArray(), allowEmptyDate(),allowEmptyTime(), allowEmptyDateTime(), and allowEmptyFile() were added. These new methods
replace allowEmpty() and give you more control over what a field should consider empty.
View• FormHelper now supports a confirmJs template variable which allows the javascript snippet generated for
confirmation boxes to be customized.
• FormHelper now has a autoSetCustomValidity option for setting HTML5 validity messages from custom
validation messages. See: Displaying validation messages in HTML5 validity messages• ViewBuilder had setVar(), setVars(), getVar(), getVars() and hasVar() added. These methods will
replace the public viewVars property defined in ViewVarsTrait.
• PaginatorHelper will now match unprefixed sort keys to model prefixed ones on the default model. This allowsmooth operation with the changes made in Cake\Datasource\Paginator• FormHelper will now read maxLength validator rules and use them to automatically define the maxlength
attribute on HTML inputs if a max length is not provided in the input options.

3.6 Migration Guide
3.6 Migration Guide
CakePHP 3.6 is an API compatible upgrade from 3.5. This page outlines the changes and improvements made in 3.6.
To upgrade to 3.6.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.6.*"

Deprecations
The following is a list of deprecated methods, properties and behaviors. These features will continue to function until
4.0.0 after which they will be removed.
• bin/cake orm_cache is now bin/cake schema_cache.
• Cake\Cache\Engine\ApcEngine has been renamed to Cake\Cache\Engine\ApcuEngine to better reflect
the extension name.
• Cake\ORM\Table::association() is deprecated. Use getAssociation() instead.

38

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• The Xcache cache engine has been deprecated. The Xcache extension is no longer actively maintained. If you
are using xcache, consider adopting APCu, Memcached, or Redis instead.
• Passing a list of arrays to Router::setRequestInfo() is now deprecated. Pass an instance of ServerRequest
instead.
• Cake\Controller\Controller:$name is protected now. Use Controller::getName()/setName() to access a controller’s name in other contexts.
• Cake\Controller\Controller:$plugin is protected now.
setPlugin() to access a controller’s plugin in other contexts.
• Cake\Controller\Controller:$autoRender is protecteddisableAutoRender()/isAutoRenderEnabled() instead.

Use Controller::getPlugin()/now.

enableAutoRender()/

Use• The setter mode of ValidationSet::isPresenceRequired() and ValidationSet::isEmptyAllowed()
are deprecated. Use requirePresence() and allowEmpty() instead.
• Cake\Form\Form::validator() is deprecated. Use getValidator() and setValidator() instead.
• Cake\ORM\TableRegistry static API has been deprecated.
Use a table locator directly instead.
A global Cake\ORM\Locator\TableLocator instance can be accessed via Cake\ORM\
TableRegistry::getTableLocator() or using a Cake\ORM\Locator\LocatorAwareTrait.
• Cake\View\Helper\FormHelper::widgetRegistry() is deprecated.
setWidgetLocator() instead.
• Cake\ORM\Behavior\TranslateBehavior::locale()setLocale() instead.

isUse getWidgetLocator() anddeprecated.

• The getter part of Cake\Datasource\QueryTrait::formatResults()
getResultFormatters() instead.

Use

getLocale()

and

is

deprecated.

Use• The getter part of Cake\Datasource\QueryTrait::mapReduce() is deprecated. Use getMapReducers()
instead.
• The getter part of Cake\ORM\Query::contain() is deprecated. Use getContain() instead.
• The getter part of Cake\Datasource\QueryInterface::repository() is deprecated.
getRepository() instead.

Use• The getter part of Cake\Database\Type::map() is deprecated. Use getMap() instead.
• Cake\Database\Type::map() to set complete types map is deprecated. Use setMap() instead.
• Passing $className as object to Cake\Database\Type::map() is deprecated. Use set() instead.
• Cake\Routing\Dispatcher is deprecated. You should upgrade to new HTTP stack.
Several classes were renamed. Their old names will continue to work until 4.0, but will emit deprecation warnings:• Cake\Network\Exception\BadRequestException has been renamed to Cake\Http\Exception\
BadRequestException.
• Cake\Network\Exception\ConflictException
ConflictException.

has

been

renamed

toCake\Http\Exception\• Cake\Network\Exception\ForbiddenException
ForbiddenException.

has

been

renamed

toCake\Http\Exception\• Cake\Network\Exception\GoneException
GoneException.

has

been

renamed

toCake\Http\Exception\• Cake\Network\Exception\HttpException
HttpException.

has

been

renamed

toCake\Http\Exception\

3.6 Migration Guide

39

CakePHP Book, Release 3.10

• Cake\Network\Exception\InternalErrorException has been renamed to Cake\Http\Exception\
InternalErrorException.
• Cake\Network\Exception\InvalidCsrfTokenException has been renamed to Cake\Http\Exception\
InvalidCsrfTokenException.
• Cake\Network\Exception\MethodNotAllowedException has been renamed to Cake\Http\Exception\
MethodNotAllowedException.
• Cake\Network\Exception\NotAcceptableException has been renamed to Cake\Http\Exception\
NotAcceptableException.
• Cake\Network\Exception\NotFoundException
NotFoundException.

has

been

renamed

toCake\Http\Exception\• Cake\Network\Exception\NotImplementedException has been renamed to Cake\Http\Exception\
NotImplementedException.
• Cake\Network\Exception\ServiceUnavailableException
Exception\ServiceUnavailableException.

has

been

renamed

toCake\Http\• Cake\Network\Exception\UnauthorizedException has been renamed to Cake\Http\Exception\
UnauthorizedException.
• Cake\Network\Exception\UnavailableForLegalReasonsException has been renamed to Cake\Http\
Exception\UnavailableForLegalReasonsException.
• Cake\Network\Session has been renamed to Cake\Http\Session.
• Cake\Network\Session\DatabaseSession
DatabaseSession.

has

been

renamed

toCake\Http\Session\• Cake\Network\Session\CacheSession has been renamed to Cake\Http\Session\CacheSession.
• Cake\Network\CorsBuilder has been renamed to Cake\Http\CorsBuilder.
• Cake\View\Widget\WidgetRegistry has been renamed to Cake\View\Widget\WidgetLocator.
Disabling Deprecation Warnings
Deprecation warnings are intended to help you prepare for future versions of CakePHP, but updating your code will
likely be an incremental process. You can disable deprecation warnings while you work towards adopting the new
methods. In your config/app.php you can set Error.errorLevel:// in config/app.php'Error' => ['errorLevel' => E_ALL ^ E_USER_DEPRECATED]
Once you have no remaining deprecation warnings you can set your error level to E_ALL to help prevent future use ofdeprecated methods.

40

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Behavior Changes
The following changes are API compatible, but they represent minor variances in behavior that may affect your application:• Cake\Utility\Security::randomBytes() will now throw exceptions when a secure source of entropy cannot be found in PHP5.
• Tokens generated by SecurityComponent now include the user’s session id, to prevent token reuse between
users/sessions. This changes the value of security tokens and will cause forms created in earlier versions of
CakePHP to fail validation in 3.6.
• Cake\Database\Query::page() now raises exceptions when page values are < 1.
• Pagination now allows sorting on multiple fields across all pages. Previously only the first page could be sorted
by more than one column. Furthermore, sort conditions defined in the query string are prepended to the default
order parameters now instead of fully replacing the default ordering.
• Shell classes will now throw exceptions when task classes cannot be found. Previously invalid tasks would besilently ignored.
• CakePHP internals now chain exceptions where possible, allowing root causes of errors to be exposed.
• MySQL connections now default to utf8mb4 (4 byte unicode) as their encoding. If you want to continue using
the old default of utf8, set your application’s datasource’ encoding in config/app.php to ‘utf8’.
• APCu and Wincache engines no longer set separate _expires keys for data with a TTL. Instead they rely on thenative TTL features of the cache engine. By default all entries created with APCu for a single request/CLI script
will have the same expiration time. You can use apc.use_request_time to change this behavior.
• Router::parseNamedParams() no longer mutates the request object in-place. Instead you will need to use thereturn value of this method to access the modified request.
• Hash::extract() no longer matches integer 0 when using attribute matchers for string values.
• The console environment no longer automatically loads plugins specified by the --plugin option. Instead you
must ensure that your application bootstrapping loads all the required plugins.
• Cake\Http\CorsBuilder::build() no longer mutates the response in place. You must now use the updated
response that build() returns.
Cache• Fallback engines can be disabled by setting fallback = false for any cache configuration.
Collection• The appendItem(), prepend(), prependItems() methods were added to CollectionTrait.

3.6 Migration Guide

41

CakePHP Book, Release 3.10

Configure• consumeOrFail() has been added to complete the API for reading with the expectation of data being present.
ConsoleA new way to build CLI tools has been added. Shells & Tasks have several shortcomings that are hard to correct
without breaking compatibility. Cake\Console\Command will replace Shell long term as the recommended way tobuild console applications. See the Console Commands section for more information.
• ConsoleOptionParse::enableSubcommandSort() was added. This method allows you to disable the automatic sorting of subcommands in generated help text.
Core• Plugins can now define Plugin Objects. These classes are optional and allow a plugin to add middleware andconsole commands to the host application. They are a class based way to configure and define a plugin.
• getTypeName() was added to assist in getting correct class/type name when building more descriptive error
messages.
Database• Query::identifier() was added. This method makes it easier to create identifier expressions for use incomplex queries.
• Database connections will automatically be re-established when connections timeout during long running scripts.
• Cake\Database\Type\BatchCastingInterface was added. This interface allows type classes to optimize
casting operations by operating on all columns in bulk. This interface can be used in custom types now, and will
be used in core types in 4.x.
• Cake\Database\Type\DateTimeType::setTimezone() was added. This method lets you set the timezonethat datetime objects should be converted to before inserting into the database. It does not change datetime data
being read from the database.
• Cake\Database\Statement\StatementDecorator::fetchAssoc() was added.
• Cake\Database\Statement\BufferedStatement::fetchAssoc() was added.
• Cake\Database\Statement\StatementDecorator::FETCH_TYPE_NUM was added.
• Cake\Database\Statement\StatementDecorator::FETCH_TYPE_ASSOC was added.
• Cake\Database\Statement\StatementDecorator::FETCH_TYPE_OBJ was added.
Datasource• A new abstract type was added for binaryuuid. In MySQL and SQLite, BINARY(16) will be used as the column
type. While in SQLServer, and Postgres will use their native UUID types.

42

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Event
• Cake\Event\EventInterface was added to give allow better typehinting in the future.
Form• Form classes now support the _validatorClass property which works the same as it does on ORM\Table.
Http• Response::withAddedLink() was added to make creating Link headers simpler.
• BodyParserMiddleware was added.
I18n• The two leftover FormHelper i18n translation strings 'Edit %s' and 'New %s' are now 'Edit {0}' and 'New{0}'. If you are using translating messages from CakePHP, please make sure you adjust those translations inyour PO file.
Mailer• The various email address setter methods on Email now accept [] allowing individual properties to be reset.
ORM• EntityTrait::isEmpty() and EntityTrait::hasValue() were added.
• Table::getAssociation() can now read deeply nested associations using . separated paths. e.g Users.
Comments. This method will raise exceptions when getting an unknown association now.
• Table::addBehaviors() was added making it simpler to add multiple behaviors at once.
• Table::getBehavior() was added.
• CounterCacheBehavior callback functions can now return false to skip updating the counter value.
• TimestampBehavior now uses the correct mutable/immutable class type when creating time objects instead ofalways using a mutable time instance.
• Query::selectAllExcept() was added.
• Query::whereInList()/Query::whereNotInList() have been added as standalone wrappers around
IN/NOT IN conditions.

3.6 Migration Guide

43

CakePHP Book, Release 3.10

Routing• Cake\Routing\Route\EntityRoute was added. This route class makes building routes that need data fromentities easier. See the Entity Routing section for more information.
• Routing variables can now use {var} style placeholders. This style allows mid-word variables to be defined.
You cannot combine {var} placeholders with :var style placeholders.
• Router::routeExists() was added. This method lets you check if a route array can be resolved into a valid
route.
• Route connection can now use compact ‘string targets’ e.g Bookmarks::index. See Connecting Routes formore information.
• RoutingMiddleware can now cache the route collection created by your routes. Caching routes greatly improves application startup times. It now also requires to be instantiated and the current object ($this) passed
for plugin routing.
Shell• The cake assets copy command now features an --overwrite option for overwriting plugin assets if they
already exist in the application webroot.
Utility• Security::randomString() was added.
Validation• Validation::compareFields() was added as a more flexible version of Validation::compareWith().
• Validator::notSameAs() was added to make it easier to check if a field is not the same as another field.
• New field comparison methods were added. equalToField(), notEqualToField(), greaterThanField(),
greaterThanOrEqualToField(), lessThanField(), lessThanOrEqualToField() were added.
• Validator rules will now use the rule alias as the rule method when the rule key is not defined.
• Validator::addNested() and addNestedMany() now support the when and message parameters like othervalidator methods.
View• UrlHelper::script(), css(), and image() methods now support a timestamp option which allows you to
set the Asset.timestamp setting for a single method call.
• Cell classes now have an initialize() hook method.
• PaginatorHelper will now reset the page to 1 each time sort directions are changed.

44

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

3.5 Migration Guide
3.5 Migration Guide
CakePHP 3.5 is an API compatible upgrade from 3.4. This page outlines the changes and improvements made in 3.5.
To upgrade to 3.5.x run the following composer command:
php composer.phar require --update-with-dependencies "cakephp/cakephp:3.5.*"

Deprecations
The following is a list of deprecated methods, properties and behaviors. These features will continue to function until
4.0.0 after which they will be removed.
• Cake\Http\Client\CookieCollection is deprecated. Use Cake\Http\Cookie\CookieCollection instead.
• Cake\View\Helper\RssHelper is deprecated. Due to infrequent use the RssHelper is deprecated.
• Cake\Controller\Component\CsrfComponent is deprecated. Use csrf-middleware instead.
• Cake\Datasource\TableSchemaInterface
TableSchemaAwareInterface instead.

is• Cake\Console\ShellDispatcher is deprecated.
CommandRunner instead.

deprecated.

UseCake\Database\Applications should update to use Cake\Console\• Cake\Database\Schema\TableSchema::column() is deprecated.
TableSchema::getColumn() instead.

Use Cake\Database\Schema\• Cake\Database\Schema\TableSchema::constraint() is deprecated.
TableSchema::getConstraint() instead.

Use Cake\Database\Schema\• Cake\Database\Schema\TableSchema::index() is deprecated.
TableSchema::getIndex() instead.

Use Cake\Database\Schema\

Deprecated Combined Get/Set Methods
In the past CakePHP has leveraged ‘modal’ methods that provide both a get and set mode. These methods complicate
IDE autocompletion and our ability to add stricter return types in the future. For these reasons, combined get/set
methods are being split into separate get and set methods.
The following is a list of methods that are deprecated and replaced with getX() and setX() methods:
Cake\Cache\Cache• config()• registry()
Cake\Console\Shell• io()
Cake\Console\ConsoleIo• outputAs()
Cake\Console\ConsoleOutput

3.5 Migration Guide

45

CakePHP Book, Release 3.10

• outputAs()
Cake\Database\Connection• logger()Cake\Database\TypedResultInterface• returnType()Cake\Database\TypedResultTrait• returnType()Cake\Database\Log\LoggingStatement• logger()Cake\Datasource\ModelAwareTrait• modelType()Cake\Database\Query• getter part of valueBinder() (now getValueBinder())
Cake\Database\Schema\TableSchema• columnType()Cake\Datasource\QueryTrait• getter part of eagerLoaded() (now isEagerLoaded())
Cake\Event\EventDispatcherInterface• eventManager()Cake\Event\EventDispatcherTrait• eventManager()Cake\Error\Debugger• outputAs() (now getOutputFormat() / setOutputFormat())
Cake\Http\ServerRequest• env() (now getEnv() / withEnv())• charset() (now getCharset() / withCharset())
Cake\I18n\I18n• locale()• translator()• defaultLocale()• defaultFormatter()
Cake\ORM\Association\BelongsToMany• sort()Cake\ORM\LocatorAwareTrait• tableLocator()
Cake\ORM\EntityTrait

46

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• invalid() (now getInvalid(), setInvalid(), setInvalidField(), and getInvalidField())
Cake\ORM\Table• validator()
Cake\Routing\RouteBuilder• extensions()• routeClass()
Cake\Routing\RouteCollection• extensions()
Cake\TestSuite\TestFixture• schema()
Cake\Utility\Security• salt()Cake\View\View• template()• layout()• theme()• templatePath()• layoutPath()• autoLayout() (now isAutoLayoutEnabled() / enableAutoLayout())
Behavior Changes
While these changes are API compatible, they represent minor variances in behavior that may affect your application:• BehaviorRegistry, HelperRegistry and ComponentRegistry will now raise exceptions when unload()
is called with an unknown object name. This change should help find errors easier by making possible typos
more visible.
• HasMany associations now gracefully handle empty values set for the association property, similar to
BelongsToMany associations - that is they treat false, null, and empty strings the same way as empty arrays.
For HasMany associations this now results in all associated records to be deleted/unlinked when the replacesave strategy is being used. As a result this allows you to use forms to delete/unlink all associated records bypassing an empty string. Previously this would have required custom marshalling logic.
• ORM\Table::newEntity() now only marks association properties dirty if the marshalled association record isdirty. In scenarios where an association entity is created that contains no properties the empty record will not be
flagged for persistence.
• Http\Client no longer uses the cookie() method results when building requests. Instead the Cookie header
and internal CookieCollection are used. This should only effect applications that have a custom HTTP adapter
in their clients.
• Multi-word subcommand names previouly required camelBacked names to be used when invoking shells. Now
subcommands can be invoked with underscored_names. For example: cake tool initMyDb can now be calledwith cake tool init_my_db. If your shells previously bound two subcommands with different inflections,only the last bound command will function.

3.5 Migration Guide

47

CakePHP Book, Release 3.10

• SecurityComponent will blackhole post requests that have no request data now. This change helps protect
actions that create records using database defaults alone.
• Cake\ORM\Table::addBehavior() and removeBehavior() now return $this to assist in defining tableobjects in a fluent fashion.
• Cache engines no longer throw an exception when they fail or are misconfigured, but instead fall back to the noop
NullEngine. Fallbacks can also be configured on a per-engine basis.
• Cake\Database\Type\DateTimeType will now marshal ISO-8859-1 formatted datetime strings (e.g. 201707-09T12:33:00+00:02) in addition to the previously accepted format. If you have a subclass of DateTimeType
you may need to update your code.
New Features
Scoped Middleware
Middleware can now be conditionally applied to routes in specific URL scopes. This allows you to build specific stacks
of middleware for different parts of your application without having to write URL checking code in your middleware.
See the Connecting Scoped Middleware section for more information.
New Console Runner
3.5.0 adds Cake\Console\CommandRunner. This class alongside Cake\Console\CommandCollection integrate
the CLI environment with the new Application class. Application classes can now implement a console() hookthat allows them to have full control over which CLI commands are exposed, how they are named and how the shells
get their dependencies. Adopting this new class requires replacing the contents of your bin/cake.php file with thefollowing file26 .
Cache Engine Fallbacks
Cache engines can now be configured with a fallback key that defines a cache configuration to fall back to if the engine
is misconfigured (or unavailable). See Configuring Cache Fallbacks for more information on configuring fallbacks.
dotenv Support added to Application Skeleton
The application skeleton now features a ‘dotenv’ integration making it easier to use environment variables to configure
your application. See the Environment Variables section for more information.
Console Integration Testing
The Cake\TestSuite\ConsoleIntegrationTestCase class was added to make integration testing console applications easier. For more information, visit the Testing Commands section. This test class is fully compatible with thecurrent Cake\Console\ShellDispatcher as well as the new Cake\Console\CommandRunner.
26 https://github.com/cakephp/app/tree/3.next/bin/cake.php

48

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Collection• Cake\Collection\Collection::avg() was added.
• Cake\Collection\Collection::median() was added.
Core• Cake\Core\Configure::read() now supports default values if the desired key does not exist.
• Cake\Core\ObjectRegistry now implements the Countable and IteratorAggregate interfaces.
Console• Cake\Console\ConsoleOptionParser::setHelpAlias() was added. This method allows you to set thecommand name used when generating help output. Defaults to cake.
• Cake\Console\CommandRunnner was added replacing Cake\Console\ShellDispatcher.
• Cake\Console\CommandCollection was added to provide an interface for applications to define the commandline tools they offer.
Database• SQLite driver had the mask option added. This option lets you set the file permissions on the SQLite databasefile when it is created.
Datasource• Cake\Datasource\SchemaInterface was added.
• New abstract types were added for smallinteger and tinyinteger. Existing SMALLINT and TINYINT
columns will now be reflected as these new abstract types. TINYINT(1) columns will continue to be treatedas boolean columns in MySQL.
• Cake\Datasource\PaginatorInterface was added. The PaginatorComponent now uses this interface tointeract with paginators. This allows other ORM-like implementations to be paginated by the component.
• Cake\Datasource\Paginator was added to paginate ORM/Database Query instances.
Event• Cake\Event\EventManager::on() and off() methods are now chainable making it simpler to set multiple
events at once.

3.5 Migration Guide49

CakePHP Book, Release 3.10

Http
• New Cookie & CookieCollection classes have been added. These classes allow you to work with cookies
in an object-orientated way, and are available on Cake\Http\ServerRequest, Cake\Http\Response, andCake\Http\Client\Response. See the Cookies and Setting Cookies for more information.
• New middleware has been added to make applying security headers easier. See security-header-middleware formore information.
• New middleware has been added to transparently encrypt cookie data. See encrypted-cookie-middleware formore information.
• New middleware has been added to make protecting against CSRF easier. See csrf-middleware for more information.
• Cake\Http\Client::addCookie() was added to make it easy to add cookies to a client instance.
InstanceConfigTrait• InstanceConfigTrait::getConfig() now takes a 2nd parameter $default. If no value is available for the
specified $key, the $default value will be returned.
ORM• Cake\ORM\Query::contain() now allows you to call it without the wrapping array when containing a single association. contain('Comments', function () { ... }); will now work. This makes contain()consistent with other eagerloading related methods like leftJoinWith() and matching().
Routing• Cake\Routing\Router::reverseToArray() was added. This method allow you to convert a request object
into an array that can be used to generate URL strings.
• Cake\Routing\RouteBuilder::resources() had the path option added. This option lets you make theresource path and controller name not match.
• Cake\Routing\RouteBuilder now has methods to create routes for specific HTTP methods. e.g get() andpost().
• Cake\Routing\RouteBuilder::loadPlugin() was added.
• Cake\Routing\Route now has fluent methods for defining options.
TestSuite• TestCase::loadFixtures() will now load all fixtures when no arguments are provided.
• IntegrationTestCase::head() was added.
• IntegrationTestCase::options() was added.
• IntegrationTestCase::disableErrorHandlerMiddleware() was added to make debugging errors easierin integration tests.

50

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Validation• Cake\Validation\Validator::scalar() was added to ensure that fields do not get non-scalar data.
• Cake\Validation\Validator::regex() was added for a more convenient way to validate data against aregex pattern.
• Cake\Validation\Validator::addDefaultProvider() was added. This method lets you inject validation
providers into all the validators created in your application.
• Cake\Validation\ValidatorAwareInterface was added to define the methods implemented by Cake\
Validation\ValidatorAwareTrait.
View• Cake\View\Helper\PaginatorHelper::limitControl() was added. This method lets you create a form
with a select box for updating the limit value on a paginated result set.

3.4 Migration Guide
3.4 Migration Guide
CakePHP 3.4 is an API compatible upgrade from 3.3. This page outlines the changes and improvements made in 3.4.
Minimum PHP 5.6 Required
CakePHP 3.4 requires at least PHP 5.6.0 as PHP 5.5 is no longer supported and won’t receive any security fixes anymore.
Deprecations
The following is a list of deprecated methods, properties and behaviors. These features will continue to function until
4.0.0 after which they will be removed.
Request & Response Deprecations
The bulk of deprecations for 3.4 are in the Request and Response objects. The existing methods that modify objects
in-place are now deprecated, and superseded by methods that follow the immutable object patterns described in the
PSR-7 standard.
Several properties on Cake\Network\Request have been deprecated:• Request::$params is deprecated. Use Request::getAttribute('params') instead.
• Request::$data is deprecated. Use Request::getData() instead.
• Request::$query is deprecated. Use Request::getQueryParams() instead.
• Request::$cookies is deprecated. Use Request::getCookie() instead.
• Request::$base is deprecated. Use Request::getAttribute('base') instead.
• Request::$webroot is deprecated. Use Request::getAttribute('webroot') instead.
• Request::$here is deprecated. Use Request::getAttribute('here') instead.
3.4 Migration Guide

51

CakePHP Book, Release 3.10

• Request::$_session was renamed to Request::$session.
A number of methods on Cake\Network\Request have been deprecated:• __get() & __isset() methods are deprecated. Use getParam() instead.
• method() is deprecated. Use getMethod() instead.
• setInput() is deprecated. Use withBody() instead.
• The ArrayAccess methods have all been deprecated.
• Request::param() is deprecated. Use Request::getParam() instead.
• Request::data() is deprecated. Use Request::getData() instead.
• Request::query() is deprecated. Use Request::getQuery() instead.
• Request::cookie() is deprecated. Use Request::getCookie() instead.
Several methods on Cake\Network\Response have been deprecated because they either overlap the PSR-7 methods,
or are made obsolete by the PSR-7 stack:• Response::header() is deprecated. Use getHeaderLine(), hasHeader() or Response::getHeader()instead.
• Response::body() is deprecated. Use Response::withStringBody() instead.
• Response::statusCode() is deprecated. Use Response::getStatusCode() instead.
• Response::httpCodes() This method should no longer be used. CakePHP now supports all standards recommended status codes.
• Response::protocol() is deprecated. Use Response::getProtocolVersion() instead.
• send(), sendHeaders(), _sendHeader(), _sendContent(), _setCookies(), _setContentType(), andstop() are deprecated and made obsolete by the PSR-7 HTTP stack.
With responses heading towards immutable object patterns as recommended by the PSR-7 standards, a number of‘helper’ methods in Response have been deprecated and immutable variants are now recommended:• Response::location() would become Response::withLocation()• Response::disableCache() would become Response::withDisabledCache()• Response::type() would become Response::withType()• Response::charset() would become Response::withCharset()• Response::cache() would become Response::withCache()• Response::modified() would become Response::withModified()• Response::expires() would become Response::withExpires()• Response::sharable() would become Response::withSharable()• Response::maxAge() would become Response::withMaxAge()• Response::vary() would become Response::withVary()• Response::etag() would become Response::withEtag()• Response::compress() would become Response::withCompression()• Response::length() would become Response::withLength()• Response::mustRevalidate() would become Response::withMustRevalidate()• Response::notModified() would become Response::withNotModified()52

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Response::cookie() would become Response::withCookie()• Response::file() would become Response::withFile()• Response::download() would become Response::withDownload()
Please see the Adopting Immutable Responses section for more information before updating your code as using responses through the immutable methods will require additional changes.
Other Deprecations• The public properties on Cake\Event\Event are deprecated, new methods have been added to read/write therelevant properties.
• Event::name() is deprecated. Use Event::getName() instead.
• Event::subject() is deprecated. Use Event::getSubject() instead.
• Event::result() is deprecated. Use Event::getResult() instead.
• Event::data() is deprecated. Use Event::getData() instead.
• The Auth.redirect session variable is no longer used. Instead a query string parameter is used to store theredirect URL. This has the additional effect of removing the ability to store a redirect URL in the session outsideof login scenarios.
• AuthComponent no longer stores redirect URLs when the unauthorized URL is not a GET action.
• The ajaxLogin option for AuthComponent is deprecated. You should use the 403 status code to trigger thecorrect behavior in clientside code now.
• The beforeRedirect method of RequestHandlerComponent is now deprecated.
• The 306 status code in Cake\Network\Response is now deprecated and has its status phrase changed to ‘Unused’ as this status code is non-standard.
• Cake\Database\Schema\Table has been renamed to Cake\Database\Schema\TableSchema. The previous
name was confusing to a number of users.
• The fieldList option for Cake\ORM\Table::newEntity() and patchEntity() has been renamed tofields to be more consistent with other parts of the ORM.
• Router::parse() is deprecated. Router::parseRequest() should be used instead as it accepts a request
and gives more control/flexibility in handling incoming requests.
• Route::parse() is deprecated. Route::parseRequest() should be used instead as it accepts a request andgives more control/flexibility in handling incoming requests.
• FormHelper::input() is deprecated. Use FormHelper::control() instead.
• FormHelper::inputs() is deprecated. Use FormHelper::controls() instead.
• FormHelper::allInputs() is deprecated. Use FormHelper::allControls() instead.
• Mailer::layout() is deprecated. Use Mailer::setLayout() provided by Mailer::__call() instead.

3.4 Migration Guide

53

CakePHP Book, Release 3.10

Deprecated Combined Get/Set Methods
In the past CakePHP has leveraged ‘modal’ methods that provide both a get/set mode. These methods complicate IDE
autocompletion and our ability to add stricter return types in the future. For these reasons, combined get/set methods
are being split into separate get and set methods.
The following is a list of methods that are deprecated and replaced with getX() and setX() methods:
Cake\Core\InstanceConfigTrait• config()
Cake\Core\StaticConfigTrait• config()• dsnClassMap()
Cake\Console\ConsoleOptionParser• command()• description()• epilog()
Cake\Database\Connection• driver()• schemaCollection()• useSavePoints() (now enableSavePoints()/isSavePointsEnabled())
Cake\Database\Driver• autoQuoting (now enableAutoQuoting()/isAutoQuotingEnabled())
Cake\Database\Expression\FunctionExpression• name()Cake\Database\Expression\QueryExpression• tieWith() (now setConjunction()/getConjunction())
Cake\Database\Expression\ValuesExpression• columns()• values()• query()
Cake\Database\Query• connection()• selectTypeMap()• bufferResults() (now enableBufferedResults()/isBufferedResultsEnabled())
Cake\Database\Schema\CachedCollection• cacheMetadata()
Cake\Database\Schema\TableSchema• options()

54

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• temporary() (now setTemporary()/isTemporary())
Cake\Database\TypeMap• defaults()• types()
Cake\Database\TypeMapTrait• typeMap()• defaultTypes()Cake\ORM\Association• name()• cascadeCallbacks()• source()• target()• conditions()• bindingKey()• foreignKey()• dependent()• joinType()• property()• strategy()• finder()Cake\ORM\Association\BelongsToMany• targetForeignKey()• saveStrategy()• conditions()
Cake\ORM\Association\HasMany• saveStrategy()• foreignKey()• sort()Cake\ORM\Association\HasOne• foreignKey()
Cake\ORM\EagerLoadable• config()• setter part of canBeJoined() (now setCanBeJoined())
Cake\ORM\EagerLoader• matching() (getMatching() will have to be called after setMatching() to keep the old behavior)• autoFields() (now enableAutoFields()/isAutoFieldsEnabled())

3.4 Migration Guide55

CakePHP Book, Release 3.10

Cake\ORM\Locator\TableLocator• config()
Cake\ORM\Query• eagerLoader()• hydrate() (now enableHydration()/isHydrationEnabled())• autoFields() (now enableAutoFields()/isAutoFieldsEnabled())
Cake\ORM\Table• table()• alias()• registryAlias()• connection()• schema()• primaryKey()• displayField()• entityClass()
Cake\Mailer\Email• from()• sender()• replyTo()• readReceipt()• returnPath()• to()• cc()• bcc()• charset()• headerCharset()• emailPattern()• subject()• template() (now setTemplate()/getTemplate() and setLayout()/getLayout())• viewRender() (now setViewRenderer()/getViewRenderer())• viewVars()• theme()• helpers()• emailFormat()• transport()• messageId()

56

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• domain()• attachments()• configTransport()• profile()
Cake\Validation\Validator• provider()Cake\View\StringTemplateTrait• templates()
Cake\View\ViewBuilder• templatePath()• layoutPath()• plugin()• helpers()• theme()• template()• layout()• options()• name()• className()• autoLayout() (now enableAutoLayout()/isAutoLayoutEnabled())
Adopting Immutable Responses
Before you migrate your code to use the new response methods you should be aware of the conceptual differences the new methods have. The immutable methods are generally indicated using a with prefix. For example,
withLocation(). Because these methods operate in an immutable context, they return new instances which you needto assign to variables or properties. If you had controller code that looked like:$response = $this->response;$response->location('/login')$response->header('X-something', 'a value');
If you were to simply find & replace method names your code would break. Instead you must now use code that looks
like:$this->response = $this->response->withLocation('/login')->withHeader('X-something', 'a value');
There are a few key differences:
1. The result of your changes is re-assigned to $this->response. This is critical to preserving the intent of theabove code.
2. The setter methods can all be chained together. This allows you to skip storing all the intermediate objects.

3.4 Migration Guide57

CakePHP Book, Release 3.10

Component Migration Tips
In previous versions of CakePHP, Components often held onto references to both the request and response, in order tomake changes later. Before you adopt the immutable methods you should use the response attached to the Controller:// In a component method (not a callback)$this->response->header('X-Rate-Limit', $this->remaining);// Should become$controller = $this->getController();$controller->response = $controller->response->withHeader('X-Rate-Limit', $this->
˓→remaining);
In component callbacks you can use the event object to access the response/controller:
public function beforeRender($event){$controller = $event->getSubject();$controller->response = $controller->response->withHeader('X-Teapot', 1);}

Tip: Instead of holding onto references of Responses, always get the current response from the controller, and re-assign
the response property when you are done.

Behavior Changes
While these changes are API compatible, they represent minor variances in behavior that may affect your application:• ORM\Query results will not typecast aliased columns based on the original column’s type. For example if you
alias created to created_time you will now get a Time object back instead of a string.
• Internal ORM traits used to build Association classes have been removed and replaced with new internal APIs.
This shouldn’t impact your applications, but may if you have created custom association types.
• AuthComponent now uses a query string to store the redirect URL when an unauthenticated user is redirectedto the login page. Previously, this redirect was stored in the session. Using the query string allows for better
multi-browser experience.
• Database Schema reflection now treats unknown column types as string and not text. A visible impact of thisis that FormHelper will generate text inputs instead of textarea elements for unknown column types.
• AuthComponent no longer stores the flash messages it creates under the ‘auth’ key. They are now rendered withthe ‘error’ template under the ‘default’ flash message key. This simplifies using AuthComponent.
• Mailer\Email will now autodetect attachment content types using mime_content_type if a content-type is
not provided. Previously attachments would have defaulted to ‘application/octet-stream’.
• CakePHP now uses the ... operator in place of call_user_func_array(). If you are passing associativearrays, you should update your code to pass a numerically indexed array using array_values() for the following
methods:– Cake\Mailer\Mailer::send()– Cake\Controller\Controller::setAction()– Cake\Http\ServerRequest::is()58

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Visibility Changes• MailerAwareTrait::getMailer() will now become protected.
• CellTrait::cell() will now become protected.
If the above traits are used in controllers, their public methods could be accessed by default routing as actions. Thesechanges help protect your controllers. If you need the methods to remain public you will need to update your use
statement to look like:use CellTrait {cell as public;}use MailerAwareTrait {getMailer as public;}

Collection• CollectionInterface::chunkWithKeys() was added.
CollectionInterface will need to implement this method now.

User

land

implementations

of

the

• Collection::chunkWithKeys() was added.
Error• Debugger::setOutputMask() and Debugger::outputMask() were added. These methods allow you to
configure properties/array keys that should be masked from output generated by Debugger (for instance, whencalling debug()).
Event• Event::getName() was added.
• Event::getSubject() was added.
• Event::getData() was added.
• Event::setData() was added.
• Event::getResult() was added.
• Event::setResult() was added.
I18n• You can now customize the behavior of the fallback message loader. See Creating Generic Translators for more
information.

3.4 Migration Guide

59

CakePHP Book, Release 3.10

Routing• RouteBuilder::prefix() now accepts an array of defaults to add to each connected route.
• Routes can now match only specific hosts through the _host option.
Email• Email::setPriority()/Email::getPriority() have been added.
HtmlHelper• HtmlHelper::scriptBlock() no longer wraps the JavaScript code in <![CDATA[ ]] tag by default. The
safe option which controls this behavior now defaults to false. Using <![CDATA[ ]] tag was only required
for XHTML which is no longer the dominant doctype used for HTML pages.
BreadcrumbsHelper• BreadcrumbsHelper::reset() was added. This method lets you clear out existing crumbs.
PaginatorHelper• PaginatorHelper::numbers() now uses an HTML elipsis instead of ‘. . . ’ in the default templates.
• PaginatorHelper::total() was added to enable reading the total number of pages for the currently paginatedresults.
• PaginatorHelper::generateUrlParams() was added as a lower level URL building method.
• PaginatorHelper::meta() can now create links for ‘first’, ‘last’.
FormHelper• You can now configure the sources which FormHelper reads from. This makes creating GET forms simpler. See
Getting form values from the query string for more information.
• FormHelper::control() was added.
• FormHelper::controls() was added.
• FormHelper::allControls() was added.
Validation• Validation::falsey() and Validation::truthy() were added.

60

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

TranslateBehavior• TranslateBehavior::translationField() was added.
PluginShell• cake plugin load and cake plugin unload now support a --cli option, which updates thebootstrap_cli.php instead.
TestSuite• Support to PHPUnit 6 was added. With this framework version requiring PHP 5.6.0 as a minimum version, thesupported version of PHPUnit are now ^5.7|^6.0

3.3 Migration Guide
3.3 Migration Guide
CakePHP 3.3 is an API compatible upgrade from 3.2. This page outlines the changes and improvements made in 3.3.
Deprecations• Router::mapResources() is deprecated. Use routing scopes and $routes->resources() instead.
• Router::redirect() is deprecated. Use routing scopes and $routes->redirect() instead.
• Router::parseNamedParams() is deprecated. Named parameter backwards compatibility will be removed in
4.0.0• Cake\Http\Client\Response has had the following methods deprecated because they overlap with PSR-7
interface methods:– statusCode() use getStatusCode() instead.
– encoding() use getEncoding() instead.
– header() use getHeaderLine() instead.
– cookie() use getCookie() instead.
– version() use getProtocolVersion() instead.
• Dispatcher Filters are now deprecated. Use /controllers/middleware instead.
• RequestActionTrait has been deprecated. Refactor your code to use View Cells instead.
• Cake\\Utility\\Crypto\\Mcrypt engine has been deprecated as the mcrypt extension is deprecated in PHP
7.1. Use the openssl and Cake\Utility\Crypto\Openssl instead.

3.3 Migration Guide

61

CakePHP Book, Release 3.10

Behavior Changes
While these changes are API compatible, they represent minor variances in behavior that may effect your application:• The default JSON encode format for Date and DateTime instances is now ISO-8601. This means that the timezone value contains a :. For example 2015-11-06T00:00:00+03:00• Controller::referer() now consistently omits the application base path when generating application local
URLs. Previously string URLs would have the base path prepended to them, while array URLs would not.
• The default ErrorController no longer disables Auth and Security components, as it does not extend
AppController. If you are enabling these components through events, you will need to update your code.
• Entity::clean now cleans original values, clearing them on save. This behavior was a bug as the entity’s
original state should not be retained after a save, but instead reflect the new state of the entity.
PSR-7 Middleware Support Added
In tandem with the deprecation of Dispatcher Filters, support for PSR-7 middleware has been added. Middleware ispart of the new HTTP stack that is an opt-in component of CakePHP 3.3.0. By using the new HTTP stack, you cantake advantage of features like:• Using middleware from plugins, and libraries outside of CakePHP.
• Leverage the same response object methods in both the responses you get from Http\Client and the responses
your application generates.
• Be able to augment the response objects emitted by error handling and asset delivery.
See the /controllers/middleware chapter and adding-http-stack sections for more information and how to add the new
HTTP stack to an existing application.
Http Client is now PSR-7 Compatible
Cake\Network\Http\Client has been moved to Cake\Http\Client. Its request and response objects now implement the PSR-7 interfaces27 . Several methods on Cake\Http\Client\Response are now deprecated, see above formore information.
ORM Improvements• Additional support has been added for mapping complex data types. This makes it easier to work with geo-spatial
types, and data that cannot be represented by strings in SQL queries. See the Mapping Custom Datatypes to SQL
Expressions for more information.
• A new JsonType was added. This new type lets you use the native JSON types available in MySQL and Postgres.
In other database providers the json type will map to TEXT columns.
• Association::unique() was added. This method proxies the target table’s unique() method, but ensuresthat association conditions are applied.
• isUnique rules now apply association conditions.
• When entities are converted into JSON, the associated objects are no longer converted to an array first using
toArray(). Instead, the jsonSerialize() method will be invoked on all associated entities. This gives you
more flexibility and control on which properties are exposed in JSON representations of your entities.
27 https://www.php-fig.org/psr/psr-7/

62

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Table::newEntity() and Table::patchEntity() will now raise an exception when an unknown association
is in the ‘associated’ key.
• RulesChecker::validCount() was added. This new method allows to apply rules to the number of associatedrecords an entity has.
• The allowNullableNulls option was added to the existsIn rule. This option allows rules to pass when somecolumns are null.
• Saving translated records is now simpler. See the Saving Multiple Translations for more information.
Multiple Pagination Support Added
You can now paginate multiple queries in a single controller action/view template. See the Paginating Multiple Queries
section for more details.
Cache Shell Added
To help you better manage cached data from the CLI environment, a shell command has been added that exposes
methods for clearing cached data:// Clear one cache config
bin/cake cache clear <configname>// Clear all cache configs
bin/cake cache clear_all

FormHelper• FormHelper will now automatically set the default value of fields to the default value defined in your databasecolumns. You can disable this behavior by setting schemaDefault option to false.
Validation• Validator::requirePresence(), Validator::allowEmpty() and Validator::notEmpty() now accept a list of fields. This allows you to more concisely define the fields that are required.
StringTemplate
StringTemplate::format() now throws an exception instead of returning null when requested template is notfound.

3.3 Migration Guide

63

CakePHP Book, Release 3.10

Other Enhancements• Collection::transpose() was added. This method allows you to tranpose the rows and columns of a matrix
with equal length rows.
• The default ErrorController now loads RequestHandlerComponent to enable Accept header based
content-type negotiation for error pages.
Routing• Router::parse(), RouteCollection::parse() and Route::parse() had a $method argument added.
It defaults to ‘GET’. This new parameter reduces reliance on global state, and necessary for the PSR-7 work
integration to be done.
• When building resource routes, you can now define a prefix. This is useful when defining nested resources as
you can create specialized controllers for nested resources.
• Dispatcher Filters are now deprecated. Use /controllers/middleware instead.
Console• Shell tasks that are invoked directly from the CLI no longer have their _welcome method invoked. They will
also have the requested parameter set now.
• Shell::err() will now apply the ‘error’ style to text. The default styling is red text.
Request• Request::is() and Request::addDetector() now supports additional arguments in detectors. This allows
detector callables to operate on additional parameters.
Debugging Functions• The pr(), debug(), and pj() functions now return the value being dumped. This makes them easier to use
when values are being returned.
• dd() has been added to completely halt execution.

3.2 Migration Guide
3.2 Migration Guide
CakePHP 3.2 is an API compatible upgrade from 3.1. This page outlines the changes and improvements made in 3.2.

64

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Minimum PHP 5.5 Required
CakePHP 3.2 requires at least PHP 5.5.9. By adopting PHP 5.5 we can provide better Date and Time libraries andremove dependencies on password compatibility libraries.
Deprecations
As we continue to improve CakePHP, certain features are deprecated as they are replaced with better solutions. Deprecated features will not be removed until 4.0:
• Shell::error() is deprecated because its name does not clearly indicate that it both outputs a message andstops execution. Use Shell::abort() instead.
• Cake\Database\Expression\QueryExpression::type() is deprecated. Use tieWith() instead.
• Cake\Database\Type\DateTimeType::$dateTimeClass is deprecated. Use DateTimeType::useMutable()or DateTimeType::useImmutable() instead.
• Cake\Database\Type\DateType::$dateTimeClass is deprecated. Use DateTimeType::useMutable()or DateType::useImmutable() instead.
• Cake\ORM\ResultSet::_calculateTypeMap() is now unused and deprecated.
• Cake\ORM\ResultSet::_castValues() is now unused and deprecated.
• The action key for FormHelper::create() has been deprecated. You should use the url key directly.
Disabling Deprecation Warnings
Upon upgrading you may encounter several deprecation warnings. These warnings are emitted by methods, options
and functionality that will be removed in CakePHP 4.x, but will continue to exist throughout the lifetime of 3.x. While
we recommend addressing deprecation issues as they are encountered, that is not always possible. If you’d like to defer
fixing deprecation notices, you can disable them in your config/app.php:'Error' => ['errorLevel' => E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED,]The above error level will suppress deprecation warnings from CakePHP.
New Enhancements
Carbon Replaced with Chronos
The Carbon library has been replaced with cakephp/chronos. This new library is a fork of Carbon with no additional
dependencies. It also offer a calendar date object, and immutable versions of both date and datetime objects.

3.2 Migration Guide

65

CakePHP Book, Release 3.10

New Date Object
The Date class allows you to cleanly map DATE columns into PHP objects. Date instances will always fix their time to
00:00:00 UTC. By default the ORM creates instances of Date when mapping DATE columns now.
New Immutable Date and Time Objects
The FrozenTime, and FrozenDate classes were added. These classes offer the same API as the Time object has. The
frozen classes provide immutable variants of Time and Date. By using immutable objects, you can prevent accidental
mutations. Instead of in-place modifications, modifier methods return new instances:use Cake\I18n\FrozenTime;$time = new FrozenTime('2016-01-01 12:23:32');$newTime = $time->modify('+1 day');In the above code $time and $newTime are different objects. The $time object retains its original value, while$newTime has the modified value. See the Immutable Dates and Times section for more information. As of 3.2,
the ORM can map date/datetime columns into immutable objects. See the Enabling Immutable DateTime Objects
section for more information.
CorsBuilder Added
In order to make setting headers related to Cross Origin Requests (CORS) easier, a new CorsBuilder has been added.
This class lets you define CORS related headers with a fluent interface. See Setting Cross Origin Request Headers(CORS) for more information.
RedirectRoute raises an exception on redirect
Router::redirect() now raises Cake\Network\Routing\RedirectException when a redirect condition isreached. This exception is caught by the routing filter and converted into a response. This replaces calls to
response->send() and allows dispatcher filters to interact with redirect responses.
ORM Improvements• Containing the same association multiple times now works as expected, and the query builder functions are now
stacked.
• Function expressions now correctly cast their results.
This$query->func()->current_date() will return datetime instances.

means

that

expressions

like• Field data that fails validation can now be accessed in entities via the invalid() method.
• Entity accessor method lookups are now cached and perform better.

66

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Improved Validator API
The Validator object has a number of new methods that make building validators less verbose. For example adding
validation rules to a username field can now look like:$validator->email('username')->ascii('username')->lengthBetween('username', [4, 8]);

Console Improvements• Shell::info(), Shell::warn() and Shell::success() were added. These helper methods make using
commonly used styling simpler.
• Cake\Console\Exception\StopException was added.
• Shell::abort() was added to replace error().
StopException Added
Shell::_stop() and Shell::error() no longer call exit(). Instead they raise Cake\Console\Exception\
StopException. If your shells/tasks are catching \Exception where these methods would have been called, thosecatch blocks will need to be updated so they don’t catch the StopException. By not calling exit() testing shells
should be easier and require fewer mocks.
Helper initialize() added
Helpers can now implement an initialize(array $config) hook method like other class types.
Fatal Error Memory Limit Handling
A new configuration option Error.extraFatalErrorMemory can be set to the number of megabytes to increase thememory limit by when a fatal error is encountered. This allows breathing room to complete logging or error handling.
Migration Steps
Updating setToStringFormat()
Before CakePHP 3.2 using Time::setToStringFormat() was working on Date Objects as well. After upgrading you willneed to add Date::setToStringFormat() in addition to see the formatted Date again.

3.2 Migration Guide

67

CakePHP Book, Release 3.10

3.1 Migration Guide
3.1 Migration Guide
CakePHP 3.1 is a fully API compatible upgrade from 3.0. This page outlines the changes and improvements made in
3.1.
Routing• The default route class has been changed to DashedRoute in the cakephp/app repo. Your current code base is
not affected by this, but it is recommended to use this route class from now on.
• Name prefix options were added to the various route builder methods. See the Using Named Routes section for
more information.
Console• Shell::dispatchShell() no longer outputs the welcome message from the dispatched shell.
• The breakpoint() helper function has been added. This function provides a snippet of code that can be put
into eval() to trigger an interactive console. This is very helpful when debugging in test cases, or other CLI
scripts.
• The --verbose and --quiet console options now control stdout/stderr logging output levels.
Shell Helpers Added• Console applications can now create helper classes that encapsulate re-usable blocks of output logic. See theShell Helpers section for more information.
RoutesShell• RoutesShell has been added and now provides you a simple to use CLI interface for testing and debugging routes.
See the Routes Shell section for more information.
Controller• The following Controller properties are now deprecated:– layout– view - replaced with template– theme– autoLayout– viewPath - replaced with templatePath– viewClass - replaced with className– layoutPath68

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Instead of setting these properties on your controllers, you should set them on the view using methods withmatching names:// In a controller, instead of$this->layout = 'advanced';// You should use$this->viewBuilder()->layout('advanced');
These methods should be called after you’ve determined which view class will be used by a controller/action.
AuthComponent• New config option storage has been added. It contains the storage class name that AuthComponent uses tostore user record. By default SessionStorage is used. If using a stateless authenticator you should configure
AuthComponent to use MemoryStorage instead.
• New config option checkAuthIn has been added. It contains the name of the event for which auth checks should
be done. By default Controller.startup is used, but you can set it to Controller.initialize if you want
authentication to be checked before you controller’s beforeFilter() method is run.
• The options scope and contain for authenticator classes have been deprecated. Instead, use the new finder
option to configure a custom finder method and modify the query used to find a user there.
• The logic for setting Auth.redirect session variable, which is used to get the URL to be redirected to after
login, has been changed. It is now set only when trying to access a protected URL without authentication.
So Auth::redirectUrl() returns the protected URL after login. Under normal circumstances, when a user
directly accesses the login page, Auth::redirectUrl() returns the value set for loginRedirect config.
FlashComponent• FlashComponent now stacks Flash messages when set with the set() or __call() method. This means thatthe structure in the Session for stored Flash messages has changed.
CsrfComponent• CSRF cookie expiry time can now be set as a strtotime() compatible value.
• Invalid CSRF tokens will now throw a Cake\Network\Exception\InvalidCsrfTokenException instead of
the Cake\Network\Exception\ForbiddenException.
RequestHandlerComponent• RequestHandlerComponent now switches the layout and template based on the parsed extension or Accept
header in the beforeRender() callback instead of startup().
• addInputType() and viewClassMap() are deprecated. You should use config() to modify this configuration
data at runtime.
• When inputTypeMap or viewClassMap are defined in the component settings, they will overwrite the default
values. This change makes it possible to remove the default configuration.

3.1 Migration Guide69

CakePHP Book, Release 3.10

Network
HttpClient• The default mime type used when sending requests has changed. Previously multipart/form-data would
always be used. In 3.1, multipart/form-data is only used when file uploads are present. When there are no
file uploads, application/x-www-form-urlencoded is used instead.
ORM
You can now Lazily Eager Load Associations. This feature allows you to conditionally load additional associations
into a result set, entity or collection of entities.
The patchEntity() and newEntity() method now support the onlyIds option. This option allows you to restrict
hasMany/belongsToMany association marshalling to only use the _ids list. This option defaults to false.
Query• Query::notMatching() was added.
• Query::leftJoinWith() was added.
• Query::innerJoinWith() was added.
• Query::select() now supports Table and Association objects as parameters. These parameter types will
select all the columns on the provided table or association instance’s target table.
• Query::distinct() now accepts a string to distinct on a single column.
• Table::loadInto() was added.
• EXTRACT, DATE_ADD and DAYOFWEEK raw SQL functions have been abstracted to extract(), dateAdd() anddayOfWeek().
View• You can now set _serialized to true for JsonView and XmlView to serialize all view variables instead of
explicitly specifying them.
• View::$viewPath is deprecated. You should use View::templatePath() instead.
• View::$view is deprecated. You should use View::template() instead.
• View::TYPE_VIEW is deprecated. You should use View::TYPE_TEMPLATE instead.
HelperSessionHelper• The SessionHelper has been deprecated. You can use $this->request->session() directly.

70

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

FlashHelper• FlashHelper can render multiple messages if multiple messages where set with the FlashComponent. Eachmessage will be rendered in its own element. Messages will be rendered in the order they were set.
FormHelper• New option templateVars has been added. templateVars allows you to pass additional variables to yourcustom form control templates.
Email• Email and Transport classes have been moved under the Cake\Mailer namespace. Their former namespaces
are still usable as class aliases have been set for them.
• The default email profile is now automatically set when an Email instance is created. This behavior is similar
to what is done in 2.x.
Mailer• The Mailer class was added. This class helps create reusable emails in an application.
I18n
Time
• Time::fromNow() has been added. This method makes it easier to calculate differences from ‘now’.
• Time::i18nFormat() now supports non-gregorian calendars when formatting dates.
Validation• Validation::geoCoordinate() was added.
• Validation::latitude() was added.
• Validation::longitude() was added.
• Validation::isInteger() was added.
• Validation::ascii() was added.
• Validation::utf8() was added.

3.1 Migration Guide

71

CakePHP Book, Release 3.10

Testing
TestFixture
model key is now supported to retrieve the table name for importing.

3.0 Migration Guide
3.0 Migration Guide
This page summarizes the changes from CakePHP 2.x that will assist in migrating a project to 3.0, as well as a reference
to get up to date with the changes made to the core since the CakePHP 2.x branch. Be sure to read the other pages inthis guide for all the new features and API changes.
Requirements• CakePHP 3.x supports PHP Version 5.4.16 and above.
• CakePHP 3.x requires the mbstring extension.
• CakePHP 3.x requires the intl extension.
Warning: CakePHP 3.0 will not work if you do not meet the above requirements.

Upgrade Tool
While this document covers all the breaking changes and improvements made in CakePHP 3.0, we’ve also created aconsole application to help you complete some of the time consuming mechanical changes. You can get the upgrade
tool from github28 .
Application Directory Layout
The application directory layout has changed and now follows PSR-429 . You should use the app skeleton30 project as areference point when updating your application.
CakePHP should be installed with Composer
Since CakePHP can no longer be installed via PEAR, or in a shared directory, those options are no longer supported.
Instead you should use Composer31 to install CakePHP into your application.
28 https://github.com/cakephp/upgrade/tree/3.x
29 https://www.php-fig.org/psr/psr-4/
30 https://github.com/cakephp/app
31 https://getcomposer.org

72

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Namespaces
All of CakePHP’s core classes are now namespaced and follow PSR-4 autoloading specifications. For example
src/Cache/Cache.php is namespaced as Cake\Cache\Cache. Global constants and helper methods like __() anddebug() are not namespaced for convenience sake.
Removed Constants
The following deprecated constants have been removed:• IMAGES• CSS• JS• IMAGES_URL• JS_URL• CSS_URL• DEFAULT_LANGUAGE
Configuration
Configuration in CakePHP 3.0 is significantly different than in previous versions. You should read the Configuration
documentation for how configuration is done in 3.0.
You can no longer use App::build() to configure additional class paths. Instead you should map additional paths
using your application’s autoloader. See the section on Additional Class Paths for more information.
Three new configure variables provide the path configuration for plugins, views and locale files. You can add multiple paths to App.paths.templates, App.paths.plugins, App.paths.locales to configure multiple paths fortemplates, plugins and locale files respectively.
The config key www_root has been changed to wwwRoot for consistency. Please adjust your app.php config file aswell as any usage of Configure::read('App.wwwRoot').
New ORM
CakePHP 3.0 features a new ORM that has been re-built from the ground up. The new ORM is significantly different
and incompatible with the previous one. Upgrading to the new ORM will require extensive changes in any applicationthat is being upgraded. See the new Database Access & ORM documentation for information on how to use the new
ORM.
Basics• LogError() was removed, it provided no benefit and is rarely/never used.
• The following global functions have been removed: config(), cache(), clearCache(), convertSlashes(),am(), fileExistsInPath(), sortByKey().

3.0 Migration Guide73

CakePHP Book, Release 3.10

Debugging• Configure::write('debug', $bool) does not support 0/1/2 anymore. A simple boolean is used instead toswitch debug mode on or off.
Object settings/configuration• Objects used in CakePHP now have a consistent instance-configuration storage/retrieval system. Code which
previously accessed for example: $object->settings should instead be updated to use $object->config().
Cache• Memcache engine has been removed, use Cake\Cache\Cache\Engine\Memcached instead.
• Cache engines are now lazy loaded upon first use.
• Cake\Cache\Cache::engine() has been added.
• Cake\Cache\Cache::enabled() has been added. This replaced the Cache.disable configure option.
• Cake\Cache\Cache::enable() has been added.
• Cake\Cache\Cache::disable() has been added.
• Cache configurations are now immutable. If you need to change configuration you must first drop the configuration and then re-create it. This prevents synchronization issues with configuration options.
• Cache::set() has been removed. It is recommended that you create multiple cache configurations to replaceruntime configuration tweaks previously possible with Cache::set().
• All CacheEngine subclasses now implement a config() method.
• Cake\Cache\Cache::readMany(),
Cache::writeMany() were added.

Cake\Cache\Cache::deleteMany(),andCake\Cache\

All Cake\Cache\Cache\CacheEngine methods now honor/are responsible for handling the configured key prefix. The Cake\Cache\CacheEngine::write() no longer permits setting the duration on write - the duration
is taken from the cache engine’s runtime config. Calling a cache method with an empty key will now throw an
InvalidArgumentException, instead of returning false.
Core
App• App::pluginPath() has been removed. Use CakePlugin::path() instead.
• App::build() has been removed.
• App::location() has been removed.
• App::paths() has been removed.
• App::load() has been removed.
• App::objects() has been removed.
• App::RESET has been removed.
• App::APPEND has been removed.

74

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• App::PREPEND has been removed.
• App::REGISTER has been removed.
Plugin• Cake\Core\Plugin::load() does not setup an autoloader unless you set the autoload option to true.
• When loading plugins you can no longer provide a callable.
• When loading plugins you can no longer provide an array of config files to load.
Configure• Cake\Configure\PhpReader renamed to Cake\Core\Configure\EnginePhpConfig• Cake\Configure\IniReader renamed to Cake\Core\Configure\EngineIniConfig• Cake\Configure\ConfigReaderInterface
ConfigEngineInterface

renamed

toCake\Core\Configure\• Cake\Core\Configure::consume() was added.
• Cake\Core\Configure::load() now expects the file name without extension suffix as this can be derived
from the engine. E.g. using PhpConfig use app to load app.php.
• Setting a $config variable in PHP config file is deprecated. Cake\Core\Configure\EnginePhpConfig now
expects the config file to return an array.
• A new config engine Cake\Core\Configure\EngineJsonConfig has been added.
ObjectThe Object class has been removed. It formerly contained a grab bag of methods that were used in various placesacross the framework. The most useful of these methods have been extracted into traits. You can use the Cake\Log\
LogTrait to access the log() method. The Cake\Routing\RequestActionTrait provides requestAction().
ConsoleThe cake executable has been moved from the app/Console directory to the bin directory within the application
skeleton. You can now invoke CakePHP’s console with bin/cake.
TaskCollection Replaced
This class has been renamed to Cake\Console\TaskRegistry. See the section on Registry Objects for more information on the features provided by the new class. You can use the cake upgrade rename_collections to assist in
upgrading your code. Tasks no longer have access to callbacks, as there were never any callbacks to use.

3.0 Migration Guide

75

CakePHP Book, Release 3.10

Shell
• Shell::__construct() has changed. It now takes an instance of Cake\Console\ConsoleIo.
• Shell::param() has been added as convenience access to the parameters.
Additionally all shell methods will be transformed to camel case when invoked. For example, if you had ahello_world() method inside a shell and invoked it with bin/cake my_shell hello_world, you will need torename the method to helloWorld. There are no changes required in the way you invoke commands.
ConsoleOptionParser• ConsoleOptionParser::merge() has been added to merge parsers.
ConsoleInputArgument• ConsoleInputArgument::isEqualTo() has been added to compare two arguments.
Shell / Task
Shells and Tasks have been moved from Console/Command and Console/Command/Task to Shell and Shell/Task.
ApiShell Removed
The ApiShell was removed as it didn’t provide any benefit over the file source itself and the online documentation/API32 .
SchemaShell Removed
The SchemaShell was removed as it was never a complete database migration implementation and better tools suchas Phinx33 have emerged. It has been replaced by the CakePHP Migrations Plugin34 which acts as a wrapper between
CakePHP and Phinx35 .
ExtractTask• bin/cake i18n extract no longer includes untranslated validation messages. If you want translated validation messages you should wrap those messages in __() calls like any other content.
32 https://api.cakephp.org/
33 https://phinx.org/
34 https://github.com/cakephp/migrations
35 https://phinx.org/

76

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

BakeShell / TemplateTask• Bake is no longer part of the core source and is superseded by CakePHP Bake Plugin36• Bake templates have been moved under src/Template/Bake.
• The syntax of Bake templates now uses erb-style tags (<% %>) to denote templating logic, allowing php code to
be treated as plain text.
• The bake view command has been renamed bake template.
Event
The getEventManager() method, was removed on all objects that had it. An eventManager() method is now
provided by the EventManagerTrait. The EventManagerTrait contains the logic of instantiating and keeping areference to a local event manager.
The Event subsystem has had a number of optional features removed. When dispatching events you can no longer use
the following options:• passParams This option is now enabled always implicitly. You cannot turn it off.
• break This option has been removed. You must now stop events.
• breakOn This option has been removed. You must now stop events.
Log• Log configurations are now immutable. If you need to change configuration you must first drop the configurationand then re-create it. This prevents synchronization issues with configuration options.
• Log engines are now lazily loaded upon the first write to the logs.
• Cake\Log\Log::engine() has been added.
• The following methods have been removed from Cake\Log\Log :: defaultLevels(), enabled(), enable(),disable().
• You can no longer create custom levels using Log::levels().
• When configuring loggers you should use 'levels' instead of 'types'.
• You can no longer specify custom log levels. You must use the default set of log levels. You should use logging
scopes to create custom log files or specific handling for different sections of your application. Using a nonstandard log level will now throw an exception.
• Cake\Log\LogTrait was added. You can use this trait in your classes to add the log() method.
• The logging scope passed to Cake\Log\Log::write() is now forwarded to the log engines’ write() method
in order to provide better context to the engines.
• Log engines are now required to implement Psr\Log\LogInterface instead of CakePHP’s own
LogInterface. In general, if you extended Cake\Log\Engine\BaseEngine you just need to rename thewrite() method to log().
• Cake\Log\Engine\FileLog now writes files in ROOT/logs instead of ROOT/tmp/logs.
36 https://github.com/cakephp/bake

3.0 Migration Guide

77

CakePHP Book, Release 3.10

Routing
Named Parameters
Named parameters were removed in 3.0. Named parameters were added in 1.2.0 as a ‘pretty’ version of query string
parameters. While the visual benefit is arguable, the problems named parameters created are not.
Named parameters required special handling in CakePHP as well as any PHP or JavaScript library that needed to interact
with them, as named parameters are not implemented or understood by any library except CakePHP. The additional
complexity and code required to support named parameters did not justify their existence, and they have been removed.
In their place you should use standard query string parameters or passed arguments. By default Router will treat any
additional parameters to Router::url() as query string arguments.
Since many applications will still need to parse incoming URLs containing named parameters. Cake\Routing\Router::parseNamedParams() has been added to allow backwards compatibility with existing URLs.
RequestActionTrait• Cake\Routing\RequestActionTrait::requestAction() has had some of the extra options changed:– options[url] is now options[query].
– options[data] is now options[post].
– Named parameters are no longer supported.
Router• Named parameters have been removed, see above for more information.
• The full_base option has been replaced with the _full option.
• The ext option has been replaced with the _ext option.
• _scheme, _port, _host, _base, _full, _ext options added.
• String URLs are no longer modified by adding the plugin/controller/prefix names.
• The default fallback route handling was removed. If no routes match a parameter set / will be returned.
• Route classes are responsible for all URL generation including query string parameters. This makes routes far
more powerful and flexible.
• Persistent parameters were removed. They were replaced with Cake\Routing\Router::urlFilter() whichallows a more flexible way to mutate URLs being reverse routed.
• Router::parseExtensions() has been removed. Use Cake\Routing\Router::extensions() instead.
This method must be called before routes are connected. It won’t modify existing routes.
• Router::setExtensions() has been removed. Use Cake\Routing\Router::extensions() instead.
• Router::resourceMap() has been removed.
• The [method] option has been renamed to _method.
• The ability to match arbitrary headers with [] style parameters has been removed. If you need to parse/matchon arbitrary conditions consider using custom route classes.
• Router::promote() has been removed.
• Router::parse() will now raise an exception when a URL cannot be handled by any route.

78

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Router::url() will now raise an exception when no route matches a set of parameters.
• Routing scopes have been introduced. Routing scopes allow you to keep your routes file DRY and give Routerhints on how to optimize parsing & reverse routing URLs.
Route• CakeRoute was re-named to Route.
• The signature of match() has changed to match($url, $context = []) See Cake\Routing\Route::match() for information on the new signature.
Dispatcher Filters Configuration Changed
Dispatcher filters are no longer added to your application using Configure. You now append them with Cake\
Routing\DispatcherFactory. This means if your application used Dispatcher.filters, you should now use
Cake\Routing\DispatcherFactory::add().
In addition to configuration changes, dispatcher filters have had some conventions updated, and features added. See
the Dispatcher Filters documentation for more information.
FilterAssetFilter• Plugin & theme assets handled by the AssetFilter are no longer read via include instead they are treated as plain
text files. This fixes a number of issues with JavaScript libraries like TinyMCE and environments with short_tags
enabled.
• Support for the Asset.filter configuration and hooks were removed. This feature should be replaced with aplugin or dispatcher filter.
Network
Request• CakeRequest has been renamed to Cake\Network\Request.
• Cake\Network\Request::port() was added.
• Cake\Network\Request::scheme() was added.
• Cake\Network\Request::cookie() was added.
• Cake\Network\Request::$trustProxy was added. This makes it easier to put CakePHP applications behindload balancers.
• Cake\Network\Request::$data is no longer merged with the prefixed data key, as that prefix has been removed.
• Cake\Network\Request::env() was added.
• Cake\Network\Request::acceptLanguage() was changed from static method to non-static.
• Request detector for “mobile” has been removed from the core. Instead the app template adds detectors for“mobile” and “tablet” using MobileDetect lib.

3.0 Migration Guide

79

CakePHP Book, Release 3.10

• The method onlyAllow() has been renamed to allowMethod() and no longer accepts “var args”. All method
names need to be passed as first argument, either as string or array of strings.
Response• The mapping of mimetype text/plain to extension csv has been removed. As a consequence Cake\
Controller\Component\RequestHandlerComponent doesn’t set extension to csv if Accept header contains mimetype text/plain which was a common annoyance when receiving a jQuery XHR request.
Sessions
The session class is no longer static, instead the session can be accessed through the request object. See the Sessions
documentation for using the session object.
• Cake\Network\Session and related session classes have been moved under the Cake\Network namespace.
• SessionHandlerInterface has been removed in favor of the one provided by PHP itself.
• The property Session::$requestCountdown has been removed.
• The session checkAgent feature has been removed. It caused a number of bugs when chrome frame, and flash
player are involved.
• The conventional sessions database table name is now sessions instead of cake_sessions.
• The session cookie timeout is automatically updated in tandem with the timeout in the session data.
• The path for session cookie now defaults to app’s base path instead of “/”. A new configuration variable
Session.cookiePath has been added to customize the cookie path.
• A new convenience method Cake\Network\Session::consume() has been added to allow reading and deleting session data in a single step.
• The default value of Cake\Network\Session::clear()’s argument $renew has been changed from true tofalse.
Network\Http• HttpSocket is now Cake\Network\Http\Client.
• HttpClient has been re-written from the ground up. It has a simpler/easier to use API, support for new authentication systems like OAuth, and file uploads. It uses PHP’s stream APIs so there is no requirement for cURL.
See the Http Client documentation for more information.
Network\Email• Cake\Network\Email\Email::config() is now used to define configuration profiles. This replaces the
EmailConfig classes in previous versions.
• Cake\Network\Email\Email::profile() replaces config() as the way to modify per instance configuration options.
• Cake\Network\Email\Email::drop() has been added to allow the removal of email configuration.
• Cake\Network\Email\Email::configTransport() has been added to allow the definition of transport configurations. This change removes transport options from delivery profiles and allows you to re-use transports
across email profiles.

80

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Cake\Network\Email\Email::dropTransport() has been added to allow the removal of transport configuration.
Controller
Controller• The $helpers, $components properties are now merged with all parent classes not just AppController andthe plugin AppController. The properties are merged differently now as well. Instead of all settings in all classes
being merged together, the configuration defined in the child class will be used. This means that if you have someconfiguration defined in your AppController, and some configuration defined in a subclass, only the configurationin the subclass will be used.
• Controller::httpCodes() has been removed, use Cake\Network\Response::httpCodes() instead.
• Controller::disableCache() has been removed, use Cake\Network\Response::disableCache() instead.
• Controller::flash() has been removed. This method was rarely used in real applications and served no
purpose anymore.
• Controller::validate() and Controller::validationErrors() have been removed. They were left
over methods from the 1.x days where the concerns of models + controllers were far more intertwined.
• Controller::loadModel() now loads table objects.
• The Controller::$scaffold property has been removed. Dynamic scaffolding has been removed from
CakePHP core. An improved scaffolding plugin, named CRUD, can be found here: https://github.com/
FriendsOfCake/crud• The Controller::$ext property has been removed. You now have to extend and override the View::$_ext
property if you want to use a non-default view file extension.
• The Controller::$methods property has been removed. You should now use Controller::isAction() todetermine whether or not a method name is an action. This change was made to allow easier customization ofwhat is and is not counted as an action.
• The Controller::$Components property has been removed and replaced with _components. If you need toload components at runtime you should use $this->loadComponent() on your controller.
• The
signatureofCake\Controller\Controller::redirect()has
beenchangedtoController::redirect(string|array $url, int $status = null).
The 3rd argument $exit
has been dropped. The method can no longer send response and exit script, instead it returns a Response
instance with appropriate headers set.
• The base, webroot, here, data, action, and params magic properties have been removed. You should accessall of these properties on $this->request instead.
• Underscore prefixed controller methods like _someMethod() are no longer treated as private methods. Use
proper visibility keywords instead. Only public methods can be used as controller actions.

3.0 Migration Guide81

CakePHP Book, Release 3.10

Scaffold Removed
The dynamic scaffolding in CakePHP has been removed from CakePHP core. It was infrequently used, and neverintended for production use. An improved scaffolding plugin, named CRUD, can be found here: https://github.com/
FriendsOfCake/crudComponentCollection Replaced
This class has been renamed to Cake\Controller\ComponentRegistry. See the section on Registry Objects formore information on the features provided by the new class. You can use the cake upgrade rename_collections
to assist in upgrading your code.
Component• The _Collection property is now _registry.
ComponentRegistry now.

It contains an instance of Cake\Controller\• All components should now use the config() method to get/set configuration.
• Default configuration for components should be defined in the $_defaultConfig property. This property is
automatically merged with any configuration provided to the constructor.
• Configuration options are no longer set as public properties.
• The Component::initialize() method is no longer an event listener. Instead, it is a post-constructor hook
like Table::initialize() and Controller::initialize(). The new Component::beforeFilter()method is bound to the same event that Component::initialize() used to be. The initialize method shouldhave the following signature initialize(array $config).
Controller\Components
CookieComponent• Uses Cake\Network\Request::cookie() to read cookie data, this eases testing, and allows for ControllerTestCase to set cookies.
• Cookies encrypted in previous versions of CakePHP using the cipher() method are now un-readable because
Security::cipher() has been removed. You will need to re-encrypt cookies with the rijndael() or aes()
method before upgrading.
• CookieComponent::type() has been removed and replaced with configuration data accessed throughconfig().
• write() no longer takes encryption or expires parameters. Both of these are now managed through config
data. See Cookie for more information.
• The path for cookies now defaults to app’s base path instead of “/”.

82

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

AuthComponent• Default is now the default password hasher used by authentication classes. It uses exclusively the bcrypt hashingalgorithm. If you want to continue using SHA1 hashing used in 2.x use 'passwordHasher' => 'Weak' in yourauthenticator configuration.
• A new FallbackPasswordHasher was added to help users migrate old passwords from one algorithm to another. Check AuthComponent’s documentation for more info.
• BlowfishAuthenticate class has been removed. Just use FormAuthenticate• BlowfishPasswordHasher class has been removed. Use DefaultPasswordHasher instead.
• The loggedIn() method has been removed. Use user() instead.
• Configuration options are no longer set as public properties.
• The methods allow() and deny() no longer accept “var args”. All method names need to be passed as firstargument, either as string or array of strings.
• The method login() has been removed and replaced by setUser() instead. To login a user you now have tocall identify() which returns user info upon successful identification and then use setUser() to save the info
to session for persistence across requests.
• BaseAuthenticate::_password() has been removed. Use a PasswordHasher class instead.
• BaseAuthenticate::logout() has been removed.
• AuthComponent now triggers two events Auth.afterIdentify and Auth.logout after a user has been identified and before a user is logged out respectively. You can set callback functions for these events by returning amapping array from implementedEvents() method of your authenticate class.
ACL related classes were moved to a separate plugin. Password hashers, Authentication and Authorization providers
where moved to the \Cake\Auth namespace. You are required to move your providers and hashers to the App\Authnamespace as well.
RequestHandlerComponent• The following methods have been removed from RequestHandler component:: isAjax(), isFlash(),isSSL(), isPut(), isPost(), isGet(), isDelete(). Use the Cake\Network\Request::is() method
instead with relevant argument.
• RequestHandler::setContent() was removed, use Cake\Network\Response::type() instead.
• RequestHandler::getReferer() was removed, use Cake\Network\Request::referer() instead.
• RequestHandler::getClientIP() was removed, use Cake\Network\Request::clientIp() instead.
• RequestHandler::getAjaxVersion() was removed.
• RequestHandler::mapType() was removed, use Cake\Network\Response::mapType() instead.
• Configuration options are no longer set as public properties.

3.0 Migration Guide83

CakePHP Book, Release 3.10

SecurityComponent• The following methods and their related properties have been removed from Security component:
requirePost(), requireGet(), requirePut(), requireDelete().
Use the Cake\Network\
Request::allowMethod() instead.
• SecurityComponent::$disabledFields() has been removed, use SecurityComponent::$unlockedFields().
• The CSRF related features in SecurityComponent have been extracted and moved into a separate CsrfComponent.
This allows you to use CSRF protection without having to use form tampering prevention.
• Configuration options are no longer set as public properties.
• The methods requireAuth() and requireSecure() no longer accept “var args”. All method names need tobe passed as first argument, either as string or array of strings.
SessionComponent• SessionComponent::setFlash() is deprecated. You should use Flash instead.
Error
Custom ExceptionRenderers are now expected to either return a Cake\Network\Response object or string whenrendering errors. This means that any methods handling specific exceptions must return a response or string value.
Model
The Model layer in 2.x has been entirely re-written and replaced. You should review the New ORM Upgrade Guide for
information on how to use the new ORM.
• The Model class has been removed.
• The BehaviorCollection class has been removed.
• The DboSource class has been removed.
• The Datasource class has been removed.
• The various datasource classes have been removed.
ConnectionManager• ConnectionManager has been moved to the Cake\Datasource namespace.
• ConnectionManager has had the following methods removed:– sourceList– getSourceName– loadDataSource– enumConnectionObjects• config() has been added and is now the only way to configure connections.
• get() has been added. It replaces getDataSource().

84

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• configured() has been added. It and config() replace sourceList() & enumConnectionObjects() witha more standard and consistent API.
• ConnectionManager::create() has been removed. It can be replaced by config($name, $config) andget($name).
Behaviors• Underscore prefixed behavior methods like _someMethod() are no longer treated as private methods. Use proper
visibility keywords instead.
TreeBehavior
The TreeBehavior was completely re-written to use the new ORM. Although it works the same as in 2.x, a few methods
were renamed or removed:• TreeBehavior::children() is now a custom finder find('children').
• TreeBehavior::generateTreeList() is now a custom finder find('treeList').
• TreeBehavior::getParentNode() was removed.
• TreeBehavior::getPath() is now a custom finder find('path').
• TreeBehavior::reorder() was removed.
• TreeBehavior::verify() was removed.
TestSuite
TestCase• _normalizePath() has been added to allow path comparison tests to run across all operation systems regarding
their DS settings (\ in Windows vs / in UNIX, for example).
The following assertion methods have been removed as they have long been deprecated and replaced by their new
PHPUnit counterpart:• assertEqual() in favor of assertEquals()• assertNotEqual() in favor of assertNotEquals()• assertIdentical() in favor of assertSame()• assertNotIdentical() in favor of assertNotSame()• assertPattern() in favor of assertRegExp()• assertNoPattern() in favor of assertNotRegExp()• assertReference() if favor of assertSame()• assertIsA() in favor of assertInstanceOf()
Note that some methods have switched the argument order, e.g. assertEqual($is, $expected) should now beassertEquals($expected, $is).
The following assertion methods have been deprecated and will be removed in the future:• assertWithinMargin() in favor of assertWithinRange()

3.0 Migration Guide85

CakePHP Book, Release 3.10

• assertTags() in favor of assertHtml()
Both method replacements also switched the argument order for a consistent assert method API with $expected as
first argument.
The following assertion methods have been added:• assertNotWithinRange() as counter part to assertWithinRange()
View
Themes are now Basic Plugins
Having themes and plugins as ways to create modular application components has proven to be limited, and confusing.
In CakePHP 3.0, themes no longer reside inside the application. Instead they are standalone plugins. This solves a few
problems with themes:• You could not put themes in plugins.
• Themes could not provide helpers, or custom view classes.
Both these issues are solved by converting themes into plugins.
View Folders Renamed
The folders containing view files now go under src/Template instead of src/View. This was done to separate the view
files from files containing php classes (eg. Helpers, View classes).
The following View folders have been renamed to avoid naming collisions with controller names:• Layouts is now Layout• Elements is now Element• Errors is now Error• Emails is now Email (same for Email inside Layout)
HelperCollection Replaced
This class has been renamed to Cake\View\HelperRegistry. See the section on Registry Objects for more information on the features provided by the new class. You can use the cake upgrade rename_collections to assist in
upgrading your code.
View Class• The plugin key has been removed from $options argument of Cake\View\View::element(). Specify theelement name as SomePlugin.element_name instead.
• View::getVar() has been removed, use Cake\View\View::get() instead.
• View::$ext has been removed and instead a protected property View::$_ext has been added.
• View::addScript() has been removed. Use Using View Blocks instead.
• The base, webroot, here, data, action, and params magic properties have been removed. You should accessall of these properties on $this->request instead.

86

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• View::start() no longer appends to an existing block. Instead it will overwrite the block content when end
is called. If you need to combine block contents you should fetch the block content when calling start a second
time, or use the capturing mode of append().
• View::prepend() no longer has a capturing mode.
• View::startIfEmpty() has been removed. Now that start() always overwrites startIfEmpty serves no purpose.
• The View::$Helpers property has been removed and replaced with _helpers. If you need to load helpers at
runtime you should use $this->addHelper() in your view files.
• View will now raise Cake\View\Exception\MissingTemplateException when templates are missing instead of MissingViewException.
ViewBlock• ViewBlock::append() has been removed, use Cake\ViewViewBlock::concat() instead.
View::append() still exists.

However,

JsonView• By default JSON data will have HTML entities encoded now. This prevents possible XSS issues when JSON
view content is embedded in HTML files.
• Cake\View\JsonView now supports the _jsonOptions view variable. This allows you to configure the bitmask options used when generating JSON.
XmlView• Cake\View\XmlView now supports the _xmlOptions view variable. This allows you to configure the options
used when generating XML.
View\Helper• The $settings property is now called $_config and should be accessed through the config() method.
• Configuration options are no longer set as public properties.
• Helper::clean() was removed. It was never robust enough to fully prevent XSS. instead you should escapecontent with h or use a dedicated library like htmlPurifier.
• Helper::output() was removed. This method was deprecated in 2.x.
• Methods Helper::webroot(), Helper::url(), Helper::assetUrl(), Helper::assetTimestamp()
have been moved to new Cake\View\Helper\UrlHelper helper. Helper::url() is now available as Cake\
View\Helper\UrlHelper::build().
• Magic accessors to deprecated properties have been removed. The following properties now need to be accessedfrom the request object:– base– here– webroot– data3.0 Migration Guide

87

CakePHP Book, Release 3.10

– action– params
HelperHelper has had the following methods removed:• Helper::setEntity()• Helper::entity()• Helper::model()• Helper::field()• Helper::value()• Helper::_name()• Helper::_initInputField()• Helper::_selectedArray()
These methods were part used only by FormHelper, and part of the persistent field features that have proven to be
problematic over time. FormHelper no longer relies on these methods and the complexity they provide is not necessary
anymore.
The following methods have been removed:• Helper::_parseAttributes()• Helper::_formatAttribute()
These methods can now be found on the StringTemplate class that helpers frequently use.
StringTemplateTrait for an easy way to integrate string templates into your own helpers.

See theFormHelper
FormHelper has been entirely rewritten for 3.0. It features a few large changes:• FormHelper works with the new ORM. But has an extensible system for integrating with other ORMs or datasources.
• FormHelper features an extensible widget system that allows you to create new custom input widgets and augment
the built-in ones.
• String templates are the foundation of the helper. Instead of munging arrays together everywhere, most of theHTML FormHelper generates can be customized in one central place using template sets.
In addition to these larger changes, some smaller breaking changes have been made as well. These changes should help
streamline the HTML FormHelper generates and reduce the problems people had in the past:• The data[ prefix was removed from all generated inputs. The prefix serves no real purpose anymore.
• The various standalone input methods like text(), select() and others no longer generate id attributes.
• The inputDefaults option has been removed from create().
• Options default and onsubmit of create() have been removed. Instead one should use JavaScript event
binding or set all required js code for onsubmit.
• end() can no longer make buttons. You should create buttons with button() or submit().

88

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• FormHelper::tagIsInvalid() has been removed. Use isFieldError() instead.
• FormHelper::inputDefaults() has been removed. You can use templates() to define/augment the templates FormHelper uses.
• The wrap and class options have been removed from the error() method.
• The showParents option has been removed from select().
• The div, before, after, between and errorMessage options have been removed from input(). You can
use templates to update the wrapping HTML. The templates option allows you to override the loaded templates
for one input.
• The separator, between, and legend options have been removed from radio(). You can use templates tochange the wrapping HTML now.
• The format24Hours parameter has been removed from hour(). It has been replaced with the format option.
• The minYear, and maxYear parameters have been removed from year(). Both of these parameters can now be
provided as options.
• The dateFormat and timeFormat parameters have been removed from datetime(). You can use the template
to define the order the inputs should be displayed in.
• The submit() has had the div, before and after options removed. You can customize the submitContainer
template to modify this content.
• The inputs() method no longer accepts legend and fieldset in the $fields parameter, you must use the$options parameter. It now also requires $fields parameter to be an array. The $blacklist parameter has
been removed, the functionality has been replaced by specifying 'field' => false in the $fields parameter.
• The inline parameter has been removed from postLink() method. You should use the block option instead.
Setting block => true will emulate the previous behavior.
• The timeFormat parameter for hour(), time() and dateTime() now defaults to 24, complying with ISO
8601.
• The $confirmMessage argument of Cake\View\Helper\FormHelper::postLink() has been removed.
You should now use key confirm in $options to specify the message.
• Checkbox and radio input types are now rendered inside of label elements by default. This helps increase compatibility with popular CSS libraries like Bootstrap37 and Foundation38 .
• Templates tags are now all camelBacked. Pre-3.0 tags formstart, formend, hiddenblock and inputsubmit
are now formStart, formEnd, hiddenBlock and inputSubmit. Make sure you change them if they are customized in your app.
It is recommended that you review the Form documentation for more details on how to use the FormHelper in 3.0.
HtmlHelper• HtmlHelper::useTag() has been removed, use tag() instead.
• HtmlHelper::loadConfig() has been removed. Customizing the tags can now be done using templates()or the templates setting.
• The second parameter $options for HtmlHelper::css() now always requires an array as documented.
• The first parameter $data for HtmlHelper::style() now always requires an array as documented.
37 https://getbootstrap.com/
38 https://foundation.zurb.com/

3.0 Migration Guide89

CakePHP Book, Release 3.10

• The inline parameter has been removed from meta(), css(), script(), scriptBlock() methods. You should use
the block option instead. Setting block => true will emulate the previous behavior.
• HtmlHelper::meta() now requires $type to be a string. Additional options can further on be passed as$options.
• HtmlHelper::nestedList() now requires $options to be an array. The forth argument for the tag type has
been removed and included in the $options array.
• The $confirmMessage argument of Cake\View\Helper\HtmlHelper::link() has been removed. You
should now use key confirm in $options to specify the message.
PaginatorHelper• link() has been removed. It was no longer used by the helper internally. It had low usage in user land code,and no longer fit the goals of the helper.
• next() no longer has ‘class’, or ‘tag’ options. It no longer has disabled arguments. Instead templates are used.
• prev() no longer has ‘class’, or ‘tag’ options. It no longer has disabled arguments. Instead templates are used.
• first() no longer has ‘after’, ‘ellipsis’, ‘separator’, ‘class’, or ‘tag’ options.
• last() no longer has ‘after’, ‘ellipsis’, ‘separator’, ‘class’, or ‘tag’ options.
• numbers() no longer has ‘separator’, ‘tag’, ‘currentTag’, ‘currentClass’, ‘class’, ‘tag’, ‘ellipsis’ options. These
options are now facilitated through templates. It also requires the $options parameter to be an array now.
• The
%page%
style
placeholders
have
been
removedfrom
PaginatorHelper::counter(). Use {{page}} style placeholders instead.

Cake\View\Helper\• url() has been renamed to generateUrl() to avoid method declaration clashes with Helper::url().
By default all links and inactive texts are wrapped in <li> elements. This helps make CSS easier to write, and improvescompatibility with popular CSS frameworks.
Instead of the various options in each method, you should use the templates feature. See the PaginatorHelper Templates
documentation for information on how to use templates.
TimeHelper• TimeHelper::__set(), TimeHelper::__get(), and TimeHelper::__isset() were removed. These were
magic methods for deprecated attributes.
• TimeHelper::serverOffset() has been removed. It promoted incorrect time math practices.
• TimeHelper::niceShort() has been removed.
NumberHelper• NumberHelper::format() now requires $options to be an array.

90

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

SessionHelper• The SessionHelper has been deprecated. You can use $this->request->session() directly, and the flash
message functionality has been moved into Flash instead.
JsHelper• JsHelper and all associated engines have been removed. It could only generate a very small subset of JavaScript
code for selected library and hence trying to generate all JavaScript code using just the helper often became an
impediment. It’s now recommended to directly use JavaScript library of your choice.
CacheHelper Removed
CacheHelper has been removed. The caching functionality it provided was non-standard, limited and incompatible with
non-HTML layouts and data views. These limitations meant a full rebuild would be necessary. Edge Side Includes
have become a standardized way to implement the functionality CacheHelper used to provide. However, implementing
Edge Side Includes39 in PHP has a number of limitations and edge cases. Instead of building a sub-par solution, we
recommend that developers needing full response caching use Varnish40 or Squid41 instead.
I18n
The I18n subsystem was completely rewritten. In general, you can expect the same behavior as in previous versions,specifically if you are using the __() family of functions.
Internally, the I18n class uses Aura\Intl, and appropriate methods are exposed to access the specific features of thislibrary. For this reason most methods inside I18n were removed or renamed.
Due to the use of ext/intl, the L10n class was completely removed. It provided outdated and incomplete data incomparison to the data available from the Locale class in PHP.
The default application language will no longer be changed automatically by the browser accepted language nor by having the Config.language value set in the browser session. You can, however, use a dispatcher filter to get automatic
language switching from the Accept-Language header sent by the browser:// In config/bootstrap.php
DispatcherFactory::addFilter('LocaleSelector');There is no built-in replacement for automatically selecting the language by setting a value in the user session.
The default formatting function for translated messages is no longer sprintf, but the more advanced and feature rich
MessageFormatter class. In general you can rewrite placeholders in messages as follows:// Before:__('Today is a %s day in %s', 'Sunny', 'Spain');// After:__('Today is a {0} day in {1}', 'Sunny', 'Spain');
You can avoid rewriting your messages by using the old sprintf formatter:
39 https://en.wikipedia.org/wiki/Edge_Side_Includes
40 https://varnish-cache.org
41 https://squid-cache.org

3.0 Migration Guide91

CakePHP Book, Release 3.10

I18n::defaultFormatter('sprintf');
Additionally, the Config.language value was removed and it can no longer be used to control the current languageof the application. Instead, you can use the I18n class:// Before
Configure::write('Config.language', 'fr_FR');// Now
I18n::setLocale('en_US');• The methods below have been moved:– From Cake\I18n\Multibyte::utf8() to Cake\Utility\Text::utf8()– From Cake\I18n\Multibyte::ascii() to Cake\Utility\Text::ascii()– From Cake\I18n\Multibyte::checkMultibyte() to Cake\Utility\Text::isMultibyte()• Since CakePHP now requires the mbstring extension, the Multibyte class has been removed.
• Error messages throughout CakePHP are no longer passed through I18n functions. This was done to simplify theinternals of CakePHP and reduce overhead. The developer facing messages are rarely, if ever, actually translated- so the additional overhead reaps very little benefit.
L10n• Cake\I18n\L10n ‘s constructor now takes a Cake\Network\Request instance as argument.
Testing• The TestShell has been removed. CakePHP, the application skeleton and newly baked plugins all use phpunit
to run tests.
• The webrunner (webroot/test.php) has been removed. CLI adoption has greatly increased since the initial releaseof 2.x. Additionaly, CLI runners offer superior integration with IDE’s and other automated tooling.
If you find yourself in need of a way to run tests from a browser you should checkout VisualPHPUnit42 . It offers
many additional features over the old webrunner.
• ControllerTestCase is deprecated and will be removed for CakePHP 3.0.0. You should use the new Controller
Integration Testing features instead.
• Fixtures should now be referenced using their plural form:// Instead of$fixtures = ['app.article'];// You should use$fixtures = ['app.articles'];
42 https://github.com/NSinopoli/VisualPHPUnit

92

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

Utility
Set Class Removed
The Set class has been removed, you should use the Hash class instead now.
Folder & File
The folder and file classes have been renamed:• Cake\Utility\File renamed to Cake\Filesystem\File• Cake\Utility\Folder renamed to Cake\Filesystem\Folder
Inflector• The default value for $replacement argument of Cake\Utility\Inflector::slug() has been changed
from underscore (_) to dash (-). Using dashes to separate words in URLs is the popular choice and also recommended by Google.
• Transliterations for Cake\Utility\Inflector::slug() have changed. If you use custom transliterations you
will need to update your code. Instead of regular expressions, transliterations use simple string replacement.
This yielded significant performance improvements:// Instead ofInflector::rules('transliteration', ['/ä|æ/' => 'ae','/å/' => 'aa']);// You should use
Inflector::rules('transliteration', ['ä' => 'ae','æ' => 'ae','å' => 'aa']);
• Separate set of uninflected and irregular rules for pluralization and singularization have been removed. Instead
we now have a common list for each. When using Cake\Utility\Inflector::rules() with type ‘singular’and ‘plural’ you can no longer use keys like ‘uninflected’, ‘irregular’ in $rules argument array.
You can add / overwrite the list of uninflected and irregular rules using Cake\Utility\Inflector::rules()by using values ‘uninflected’ and ‘irregular’ for $type argument.

3.0 Migration Guide

93

CakePHP Book, Release 3.10

Sanitize• Sanitize class has been removed.
Security• Security::cipher() has been removed. It is insecure and promoted bad cryptographic practices. You should
use Security::encrypt() instead.
• The Configure value Security.cipherSeed is no longer required. With the removal of Security::cipher()it serves no use.
• Backwards compatibility in Cake\Utility\Security::rijndael() for values encrypted prior to CakePHP
2.3.1 has been removed. You should re-encrypt values using Security::encrypt() and a recent version of
CakePHP 2.x before migrating.
• The ability to generate a blowfish hash has been removed. You can no longer use type “blowfish” forSecurity::hash(). One should just use PHP’s password_hash() and password_verify() to generate and verify
blowfish hashes. The compability library ircmaxell/password-compat43 which is installed along with CakePHP
provides these functions for PHP < 5.5.
• OpenSSL is now used over mcrypt when encrypting/decrypting data. This change provides better performanceand future proofs CakePHP against distros dropping support for mcrypt.
• Security::rijndael() is deprecated and only available when using mcrypt.
Warning: Data encrypted with Security::encrypt() in previous versions is not compatible with the openssl implementation. You should set the implementation to mcrypt when upgrading.

Time• CakeTime has been renamed to Cake\I18n\Time.
• CakeTime::serverOffset() has been removed. It promoted incorrect time math practises.
• CakeTime::niceShort() has been removed.
• CakeTime::convert() has been removed.
• CakeTime::convertSpecifiers() has been removed.
• CakeTime::dayAsSql() has been removed.
• CakeTime::daysAsSql() has been removed.
• CakeTime::fromString() has been removed.
• CakeTime::gmt() has been removed.
• CakeTime::toATOM() has been renamed to toAtomString.
• CakeTime::toRSS() has been renamed to toRssString.
• CakeTime::toUnix() has been renamed to toUnixString.
• CakeTime::wasYesterday() has been renamed to isYesterday to match the rest of the method naming.
• CakeTime::format() Does not use sprintf format strings anymore, you can use i18nFormat instead.
43 https://packagist.org/packages/ircmaxell/password-compat

94

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

• Time::timeAgoInWords() now requires $options to be an array.
Time is not a collection of static methods anymore, it extends DateTime to inherit all its methods and adds location
aware formatting functions with the help of the intl extension.
In general, expressions looking like this:CakeTime::aMethod($date);
Can be migrated by rewriting it to:(new Time($date))->aMethod();

Number
The Number library was rewritten to internally use the NumberFormatter class.
• CakeNumber has been renamed to Cake\I18n\Number.
• Number::format() now requires $options to be an array.
• Number::addFormat() was removed.
• Number::fromReadableSize() has been moved to Cake\Utility\Text::parseFileSize().
Validation• The range for Validation::range() now is inclusive if $lower and $upper are provided.
• Validation::ssn() has been removed.
Xml• Xml::build() now requires $options to be an array.
• Xml::build() no longer accepts a URL. If you need to create an XML document from a URL, use Http\Client.

New ORM Upgrade Guide
CakePHP 3.0 features a new ORM that has been re-written from the ground up. While the ORM used in 1.x and 2.x
has served us well for a long time it had a few issues that we wanted to fix.
• Frankenstein - Is it a record, or a table? In CakePHP 2.x it’s both.
• Inconsistent API - Model::read() for example.
• No query object - Queries are always defined as arrays, this has some limitations and restrictions. For example
it makes doing unions and sub-queries much harder.
• Returns arrays - This is a common complaint about CakePHP, and has probably reduced adoption at some levels.
• No record object - This makes attaching formatting methods difficult/impossible.
• Containable - Should be part of the ORM, not a crazy hacky behavior.
• Recursive - This should be better controlled as defining which associations are included, not a level of recursiveness.

3.0 Migration Guide95

CakePHP Book, Release 3.10

• DboSource - It is a beast, and Model relies on it more than datasource. That separation could be cleaner andsimpler.
• Validation - Should be separate, it’s a giant crazy function right now. Making it a reusable bit would make theframework more extensible.
The ORM in CakePHP 3.0 solves these and many more problems. The new ORM focuses on relational data storesright now. In the future and through plugins we will add non relational stores like ElasticSearch and others.
Design of the New ORM
The new ORM solves several problems by having more specialized and focused classes. In the past you would use
Model and a Datasource for all operations. Now the ORM is split into more layers:• Cake\Database\Connection - Provides a platform independent way to create and use connections. This classprovides a way to use transactions, execute queries and access schema data.
• Cake\Database\Dialect - The classes in this namespace provide platform specific SQL and transform queries
to work around platform specific limitations.
• Cake\Database\Type - Is the gateway class to CakePHP database type conversion system. It is a pluggable
framework for adding abstract column types and providing mappings between database, PHP representations and
PDO bindings for each data type. For example datetime columns are represented as DateTime instances in yourcode now.
• Cake\ORM\Table - The main entry point into the new ORM. Provides access to a single table. Handles thedefinition of association, use of behaviors and creation of entities and query objects.
• Cake\ORM\Behavior - The base class for behaviors, which act very similar to behaviors in previous versions of
CakePHP.
• Cake\ORM\Query - A fluent object based query builder that replaces the deeply nested arrays used in previous
versions of CakePHP.
• Cake\ORM\ResultSet - A collection of results that gives powerful tools for manipulating data in aggregate.
• Cake\ORM\Entity - Represents a single row result. Makes accessing data and serializing to various formats a
snap.
Now that you are more familiar with some of the classes you’ll interact with most frequently in the new ORM it is goodto look at the three most important classes. The Table, Query and Entity classes do much of the heavy lifting in the
new ORM, and each serves a different purpose.
Table Objects
Table objects are the gateway into your data. They handle many of the tasks that Model did in previous releases. Table
classes handle tasks like:• Creating queries.
• Providing finders.
• Validating and saving entities.
• Deleting entities.
• Defining and accessing associations.
• Triggering callback events.
• Interacting with behaviors.

96

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

The documentation chapter on Table Objects provides far more detail on how to use table objects than this guide can.
Generally when moving existing model code over it will end up in a table object. Table objects don’t contain any
platform dependent SQL. Instead they collaborate with entities and the query builder to do their work. Table objects
also interact with behaviors and other interested parties through published events.
Query Objects
While these are not classes you will build yourself, your application code will make extensive use of the Query Builder
which is central to the new ORM. The query builder makes it easy to build simple or complex queries including thosethat were previously very difficult in CakePHP like HAVING, UNION and sub-queries.
The various find() calls your application has currently will need to be updated to use the new query builder. The Queryobject is responsible for containing the data to make a query without executing the query itself. It collaborates with theconnection/dialect to generate platform specific SQL which is executed creating a ResultSet as the output.
Entity Objects
In previous versions of CakePHP the Model class returned dumb arrays that could not contain any logic or behavior.
While the community made this short-coming less painful with projects like CakeEntity, the array results were often ashort coming that caused many developers trouble. For CakePHP 3.0, the ORM always returns object result sets unless
you explicitly disable that feature. The chapter on Entities covers the various tasks you can accomplish with entities.
Entities are created in one of two ways. Either by loading data from the database, or converting request data into entities.
Once created, entities allow you to manipulate the data they contain and persist their data by collaborating with tableobjects.
Key Differences
The new ORM is a large departure from the existing Model layer. There are many important differences that areimportant in understanding how the new ORM operates and how to update your code.
Inflection Rules Updated
You may have noticed that table classes have a pluralized name. In addition to tables having pluralized names, associations are also referred in the plural form. This is in contrast to Model where class names and association aliases were
singular. There are a few reasons for this change:• Table classes represent collections of data, not single rows.
• Associations link tables together, describing the relations between many things.
While the conventions for table objects are to always use plural forms, your entity association properties will be populated based on the association type.
Note: BelongsTo and HasOne associations will use the singular form in entity properties, while HasMany and BelongsToMany (HABTM) will use plural forms.
The convention change for table objects is most apparent when building queries. Instead of expressing queries like:// Wrong$query->where(['User.active' => 1]);

3.0 Migration Guide

97

CakePHP Book, Release 3.10

You need to use the plural form:// Correct$query->where(['Users.active' => 1]);

Find returns a Query Object
One important difference in the new ORM is that calling find on a table will not return the results immediately, butwill return a Query object; this serves several purposes.
It is possible to alter queries further, after calling find:// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$query = $articles->find();$query->where(['author_id' => 1])->order(['title' => 'DESC']);
It is possible to stack custom finders to append conditions, sorting, limit and any other clause to the same query before
it is executed:$query = $articles->find('approved')->find('popular');$query->find('latest');You can compose queries one into the other to create subqueries easier than ever:$query = $articles->find('approved');$favoritesQuery = $article->find('favorites', ['for' => $user]);$query->where(['id' => $favoritesQuery->select(['id'])]);
You can decorate queries with iterators and call methods without even touching the database. This is great when you
have parts of your view cached and having the results taken from the database is not actually required:// No queries made in this example!
$results = $articles->find()->order(['title' => 'DESC'])->formatResults(function (\Cake\Collection\CollectionInterface $results) {return $results->extract('title');});Queries can be seen as the result object, trying to iterate the query, calling toArray() or any method inherited fromcollection, will result in the query being executed and results returned to you.
The biggest difference you will find when coming from CakePHP 2.x is that find('first') does not exist anymore.
There is a trivial replacement for it, and it is the first() method:// Before$article = $this->Article->find('first');// Now$article = $this->Articles->find()->first();// Before$article = $this->Article->find('first', ['conditions' => ['author_id' => 1](continues on next page)98

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

(continued from previous page)]);// Now$article = $this->Articles->find('all', ['conditions' => ['author_id' => 1]])->first();// Can also be written$article = $this->Articles->find()->where(['author_id' => 1])->first();If you are loading a single record by its primary key, it will be better to just call get():$article = $this->Articles->get(10);Finder Method Changes
Returning a query object from a find method has several advantages, but comes at a cost for people migrating from
2.x. If you had some custom find methods in your models, they will need some modifications. This is how you createcustom finder methods in 3.0:
class ArticlesTable{
public function findPopular(Query $query, array $options){
return $query->where(['times_viewed' > 1000]);}
public function findFavorites(Query $query, array $options){$for = $options['for'];return $query->matching('Users.Favorites', function ($q) use ($for) {return $q->where(['Favorites.user_id' => $for]);});}}
As you can see, they are pretty straightforward, they get a Query object instead of an array and must return a Queryobject back. For 2.x users that implemented afterFind logic in custom finders, you should check out the Modifying
Results with Map/Reduce section, or use the features found on the collection objects. If in your models you used to relyon having an afterFind for all find operations you can migrate this code in one of a few ways:
1. Override your entity constructor method and do additional formatting there.
2. Create accessor methods in your entity to create the virtual fields.
3. Redefine findAll() and use formatResults.
In the 3rd case above your code would look like:public function findAll(Query $query, array $options){(continues on next page)

3.0 Migration Guide99

CakePHP Book, Release 3.10

(continued from previous page)

return $query->formatResults(function (\Cake\Collection\CollectionInterface
˓→$results) {return $results->map(function ($row) {// Your afterfind logic});})}
You may have noticed that custom finders receive an options array. You can pass any extra information to your finderusing this parameter. This is great news for people migrating from 2.x. Any of the query keys that were used in previous
versions will be converted automatically for you in 3.x to the correct functions:// This works in both CakePHP 2.x and 3.0$articles = $this->Articles->find('all', ['fields' => ['id', 'title'],'conditions' => ['OR' => ['title' => 'Cake', 'author_id' => 1],'published' => true],'contain' => ['Authors'], // The only change! (notice plural)'order' => ['title' => 'DESC'],'limit' => 10,]);
If your application uses ‘magic’ or Dynamic Finders, you will have to adapt those calls. In 3.x the findAllBy* methods
have been removed, instead findBy* always returns a query object. To get the first result, you need to use the first()
method:$article = $this->Articles->findByTitle('A great post!')->first();Hopefully, migrating from older versions is not as daunting as it first seems. Many of the features we have added
will help you remove code as you can better express your requirements using the new ORM and at the same time thecompatibility wrappers will help you rewrite those tiny differences in a fast and painless way.
One of the other nice improvements in 3.x around finder methods is that behaviors can implement finder methods withno fuss. By simply defining a method with a matching name and signature on a Behavior the finder will automaticallybe available on any tables the behavior is attached to.
Recursive and ContainableBehavior Removed
In previous versions of CakePHP you needed to use recursive, bindModel(), unbindModel() andContainableBehavior to reduce the loaded data to the set of associations you were interested in. A common tactic
to manage associations was to set recursive to -1 and use Containable to manage all associations. In CakePHP 3.0
ContainableBehavior, recursive, bindModel, and unbindModel have all been removed. Instead the contain() method
has been promoted to be a core feature of the query builder. Associations are only loaded if they are explicitly turned
on. For example:$query = $this->Articles->find('all');Will only load data from the articles table as no associations have been included. To load articles and their related
authors you would do:

100

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

$query = $this->Articles->find('all')->contain(['Authors']);
By only loading associated data that has been specifically requested you spend less time fighting the ORM trying to get
only the data you want.
No afterFind Event or Virtual Fields
In previous versions of CakePHP you needed to make extensive use of the afterFind callback and virtual fields
in order to create generated data properties. These features have been removed in 3.0. Because of how ResultSets
iteratively generate entities, the afterFind callback was not possible. Both afterFind and virtual fields can largely be
replaced with virtual properties on entities. For example if your User entity has both first and last name columns you
can add an accessor for full_name and generate the property on the fly:
namespace App\Model\Entity;
use Cake\ORM\Entity;class User extends Entity{
protected function _getFullName(){
return $this->first_name . ' ' . $this->last_name;}}Once defined you can access your new property using $user->full_name. Using the Modifying Results with
Map/Reduce features of the ORM allow you to build aggregated data from your results, which is another use casethat the afterFind callback was often used for.
While virtual fields are no longer an explicit feature of the ORM, adding calculated fields is easy to do in your finder
methods. By using the query builder and expression objects you can achieve the same results that virtual fields gave:namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\ORM\Query;class ReviewsTable extends Table{
public function findAverage(Query $query, array $options = []){$avg = $query->func()->avg('rating');$query->select(['average' => $avg]);
return $query;}}

3.0 Migration Guide

101

CakePHP Book, Release 3.10

Associations No Longer Defined as Properties
In previous versions of CakePHP the various associations your models had were defined in properties like $belongsTo
and $hasMany. In CakePHP 3.0, associations are created with methods. Using methods allows us to sidestep the many
limitations class definitions have, and provide only one way to define associations. Your initialize() method andall other parts of your application code, interact with the same API when manipulating associations:namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\ORM\Query;class ReviewsTable extends Table{
public function initialize(array $config){$this->belongsTo('Movies');$this->hasOne('Ratings');$this->hasMany('Comments')$this->belongsToMany('Tags')}}
As you can see from the example above each of the association types uses a method to create the association. One other
difference is that hasAndBelongsToMany has been renamed to belongsToMany. To find out more about creating
associations in 3.0 see the section on Associations - Linking Tables Together.
Another welcome improvement to CakePHP is the ability to create your own association classes. If you have association
types that are not covered by the built-in relation types you can create a custom Association sub-class and define theassociation logic you need.
Validation No Longer Defined as a Property
Like associations, validation rules were defined as a class property in previous versions of CakePHP. This array would
then be lazily transformed into a ModelValidator object. This transformation step added a layer of indirection,complicating rule changes at runtime. Furthermore, validation rules being defined as a property made it difficult for amodel to have multiple sets of validation rules. In CakePHP 3.0, both these problems have been remedied. Validation
rules are always built with a Validator object, and it is trivial to have multiple sets of rules:
namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\ORM\Query;
use Cake\Validation\Validator;
class ReviewsTable extends Table{
public function validationDefault(Validator $validator){$validator->requirePresence('body')->add('body', 'length', ['rule' => ['minLength', 20],'message' => 'Reviews must be 20 characters or more',(continues on next page)

102

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

(continued from previous page)])->add('user_id', 'numeric', ['rule' => 'numeric']);return $validator;}}
You can define as many validation methods as you need. Each method should be prefixed with validation and accept
a $validator argument.
In previous versions of CakePHP ‘validation’ and the related callbacks covered a few related but different uses. In
CakePHP 3.0, what was formerly called validation is now split into two concepts:
1. Data type and format validation.
2. Enforcing application, or business rules.
Validation is now applied before ORM entities are created from request data. This step lets you ensure data matches
the data type, format, and basic shape your application expects. You can use your validators when converting request
data into entities by using the validate option. See the documentation on Converting Request Data into Entities formore information.
Application rules allow you to define rules that ensure your application’s rules, state and workflows are enforced. Rules
are defined in your Table’s buildRules() method. Behaviors can add rules using the buildRules() hook method.
An example buildRules() method for our articles table could be:// In src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\ORM\RulesChecker;
class ArticlesTable extends Table{
public function buildRules(RulesChecker $rules){$rules->add($rules->existsIn('user_id', 'Users'));$rules->add(function ($article, $options) {return ($article->published && empty($article->reviewer));},'isReviewed',['errorField' => 'published','message' => 'Articles must be reviewed before publishing.']);
return $rules;}}

3.0 Migration Guide103

CakePHP Book, Release 3.10

Identifier Quoting Disabled by Default
In the past CakePHP has always quoted identifiers. Parsing SQL snippets and attempting to quote identifiers was both
error prone and expensive. If you are following the conventions CakePHP sets out, the cost of identifier quoting far
outweighs any benefit it provides. Because of this identifier quoting has been disabled by default in 3.0. You should
only need to enable identifier quoting if you are using column names or table names that contain special characters or
are reserved words. If required, you can enable identifier quoting when configuring a connection:// In config/app.php'Datasources' => ['default' => ['className' => 'Cake\Database\Driver\Mysql','username' => 'root','password' => 'super_secret','host' => 'localhost','database' => 'cakephp','quoteIdentifiers' => true,]],

Note: Identifiers in QueryExpression objects will not be quoted, and you will need to quote them manually or use
IdentifierExpression objects.

Updating Behaviors
Like most ORM related features, behaviors have changed in 3.0 as well. They now attach to Table instances which are
the conceptual descendant of the Model class in previous versions of CakePHP. There are a few key differences frombehaviors in CakePHP 2.x:
• Behaviors are no longer shared across multiple tables. This means you no longer have to ‘namespace’ settings
stored in a behavior. Each table using a behavior will get its own instance.
• The method signatures for mixin methods have changed.
• The method signatures for callback methods have changed.
• The base class for behaviors have changed.
• Behaviors can add finder methods.
New Base Class
The base class for behaviors has changed. Behaviors should now extend Cake\ORM\Behavior; if a behavior does notextend this class an exception will be raised. In addition to the base class changing, the constructor for behaviors has
been modified, and the startup() method has been removed. Behaviors that need access to the table they are attached
to should define a constructor:
namespace App\Model\Behavior;
use Cake\ORM\Behavior;class SluggableBehavior extends Behavior(continues on next page)

104

Chapter 3. 3.x Migration Guide

CakePHP Book, Release 3.10

(continued from previous page){
protected $_table;
public function __construct(Table $table, array $config){
parent::__construct($table, $config);$this->_table = $table;}}

Mixin Methods Signature Changes
Behaviors continue to offer the ability to add ‘mixin’ methods to Table objects, however the method signature for thesemethods has changed. In CakePHP 3.0, behavior mixin methods can expect the same arguments provided to the table‘method’. For example:// Assume table has a slug() method provided by a behavior.
$table->slug($someValue);
The behavior providing the slug() method will receive only 1 argument, and its method signature should look like:public function slug($value){// Code here.
}

Callback Method Signature Changes
Behavior callbacks have been unified with all other listener methods. Instead of their previous arguments, they need to
expect an event object as their first argument:
public function beforeFind(Event $event, Query $query, array $options){// Code.
}See Lifecycle Callbacks for the signatures of all the callbacks a behavior can subscribe to.

3.0 Migration Guide

105

CakePHP Book, Release 3.10

106

Chapter 3. 3.x Migration Guide

CHAPTER 4

Tutorials & Examples

In this section, you can walk through typical CakePHP applications to see how all of the pieces come together.
Alternatively, you can refer to the non-official CakePHP plugin repository CakePackages44 and the Bakery45 for existing
applications and components.

Content Management Tutorial
This tutorial will walk you through the creation of a simple CMS application. To start with, we’ll be installing CakePHP,
creating our database, and building simple article management.
Here’s what you’ll need:
1. A database server. We’re going to be using MySQL server in this tutorial. You’ll need to know enough about
SQL in order to create a database, and run SQL snippets from the tutorial. CakePHP will handle building all thequeries your application needs. Since we’re using MySQL, also make sure that you have pdo_mysql enabled in
PHP.
2. Basic PHP knowledge.
Before starting you should make sure that you have got an up to date PHP version:php -v
You should at least have got installed PHP 5.6 (CLI) or higher. Your webserver’s PHP version must also be of 5.6 orhigher, and should be the same version your command line interface (CLI) PHP is.
44 https://plugins.cakephp.org/
45 https://bakery.cakephp.org/

107

CakePHP Book, Release 3.10

Getting CakePHPThe easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from yourterminal or command line prompt. First, you’ll need to download and install Composer if you haven’t done so already.
If you have cURL installed, it’s as easy as running the following:
curl -s https://getcomposer.org/installer | php
Or, you can download composer.phar from the Composer website46 .
Then simply type the following line in your terminal from your installation directory to install the CakePHP application
skeleton in the cms directory of the current working directory:
php composer.phar create-project --prefer-dist cakephp/app:"^3.10" cms
If you downloaded and ran the Composer Windows Installer47 , then type the following line in your terminal from yourinstallation directory (ie. C:\wamp\www\dev\cakephp3):
composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" cms
The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting
the correct file permissions and creating your config/app.php file for you.
There are other ways to install CakePHP. If you cannot or don’t want to use Composer, check out the Installation section.
Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup shouldlook something like the following:
/cms
/bin
/config/logs/plugins/src/tests/tmp/vendor/webroot.editorconfig.gitignore.htaccess.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md
Now might be a good time to learn a bit about how CakePHP’s directory structure works: check out the CakePHP
Folder Structure section.
If you get lost during this tutorial, you can see the finished result on GitHub48 .
46 https://getcomposer.org/download/
47 https://getcomposer.org/Composer-Setup.exe
48 https://github.com/cakephp/cms-tutorial

108

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Checking our Installation
We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you’ll
need to start the development server:
cd /path/to/our/app
bin/cake server

Note: For Windows, the command needs to be bin\cake server (note the backslash).
This will start PHP’s built-in webserver on port 8765. Open up http://localhost:8765 in your web browser to see
the welcome page. All the bullet points should be green chef hats other than CakePHP being able to connect to yourdatabase. If not, you may need to install additional PHP extensions, or set directory permissions.
Next, we will build our Database and create our first model.

CMS Tutorial - Creating the Database
Now that we have CakePHP installed, let’s set up the database for our CMS application. If you haven’t already doneso, create an empty database for use in this tutorial, with a name of your choice, e.g. cake_cms. You can execute thefollowing SQL to create the necessary tables:
USE cake_cms;
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 articles (id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
title VARCHAR(255) NOT NULL,
slug VARCHAR(191) NOT NULL,
body TEXT,
published BOOLEAN DEFAULT FALSE,
created DATETIME,
modified DATETIME,UNIQUE KEY (slug),
FOREIGN KEY user_key (user_id) REFERENCES users(id)) CHARSET=utf8mb4;
CREATE TABLE tags (id INT AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(191),
created DATETIME,
modified DATETIME,(continues on next page)

CMS Tutorial - Creating the Database109

CakePHP Book, Release 3.10

(continued from previous page)

UNIQUE KEY (title)) CHARSET=utf8mb4;
CREATE TABLE articles_tags (article_id INT NOT NULL,
tag_id INT NOT NULL,PRIMARY KEY (article_id, tag_id),
FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),FOREIGN KEY article_key(article_id) REFERENCES articles(id));
INSERT INTO users (email, password, created, modified)
VALUES('cakephp@example.com', 'secret', NOW(), NOW());
INSERT INTO articles (user_id, title, slug, body, published, created, modified)
VALUES(1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());
You may have noticed that the articles_tags table used a composite primary key. CakePHP supports composite
primary keys almost everywhere allowing you to have simpler schemas that don’t require additional id columns.
The table and column names we used were not arbitrary. By using CakePHP’s naming conventions, we can leverage
CakePHP more effectively and avoid needing to configure the framework. While CakePHP is flexible enough to accommodate almost any database schema, adhering to the conventions will save you time as you can leverage the convention
based defaults CakePHP provides.

Database Configuration
Next, let’s tell CakePHP where our database is and how to connect to it. Replace the values in the Datasources.
default array in your config/app_local.php file with those that apply to your setup. A sample completed configurationarray might look something like the following:<?php
return [// More configuration above.
'Datasources' => ['default' => ['className' => 'Cake\Database\Connection','driver' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'localhost','username' => 'cakephp','password' => 'AngelF00dC4k3~','database' => 'cake_cms','encoding' => 'utf8mb4','timezone' => 'UTC','cacheMetadata' => true,],],// More configuration below.
];

110

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Once you’ve saved your config/app_local.php file, you should see that ‘CakePHP is able to connect to the database’section have a green chef hat.
Note: A copy of CakePHP’s default configuration file is found in config/app.default.php.

Creating our First Model
Models are the heart of a CakePHP applications. They enable us to read and modify our data. They allow us to build
relations between our data, validate data, and apply application rules. Models build the foundations necessary to build
our controller actions and templates.
CakePHP’s models are composed of Table and Entity objects. Table objects provide access to the collection ofentities stored in a specific table. They are stored in src/Model/Table. The file we’ll be creating will be saved tosrc/Model/Table/ArticlesTable.php. The completed file should look like this:<?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');}}We’ve attached the Timestamp behavior which will automatically populate the created and modified columns of ourtable. By naming our Table object ArticlesTable, CakePHP can use naming conventions to know that our model
uses the articles table. CakePHP also uses conventions to know that the id column is our table’s primary key.
Note:
CakePHP will dynamically create a model object for you if it cannot find a corresponding file insrc/Model/Table. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.
We’ll also create an Entity class for our Articles. Entities represent a single record in the database, and provide row
level behavior for our data. Our entity will be saved to src/Model/Entity/Article.php. The completed file should look
like this:<?php// src/Model/Entity/Article.php
namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{
protected $_accessible = ['*' => true,(continues on next page)

CMS Tutorial - Creating the Database111

CakePHP Book, Release 3.10

(continued from previous page)'id' => false,'slug' => false,];}
Our entity is quite slim right now, and we’ve only setup the _accessible property which controls how properties canbe modified by Mass Assignment.
We can’t do much with our models right now, so next we’ll create our first Controller and Template to allow us tointeract with our model.

CMS Tutorial - Creating the Articles Controller
With our model created, we need a controller for our articles. Controllers in CakePHP handle HTTP requests andexecute business logic contained in model methods, to prepare the response. We’ll place this new controller in a filecalled ArticlesController.php inside the src/Controller directory. Here’s what the basic controller should look like:<?php// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{}
Now, let’s add an action to our controller. Actions are controller methods that have routes connected to them. For example, when a user requests www.example.com/articles/index (which is also the same as www.example.com/articles),
CakePHP will call the index method of your ArticlesController. This method should query the model layer, andprepare a response by rendering a Template in the View. The code for that action would look like this:<?php// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{
public function index(){$this->loadComponent('Paginator');$articles = $this->Paginator->paginate($this->Articles->find());$this->set(compact('articles'));}}By defining function index() in our ArticlesController, users can now access the logic there by requestingwww.example.com/articles/index. Similarly, if we were to define a function called foobar(), users would be able toaccess that at www.example.com/articles/foobar. You may be tempted to name your controllers and actions in a waythat allows you to obtain specific URLs. Resist that temptation. Instead, follow the CakePHP Conventions creating
readable, meaningful action names. You can then use Routing to connect the URLs you want to the actions you’ve
created.
112

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Our controller action is very simple. It fetches a paginated set of articles from the database, using the Articles Modelthat is automatically loaded via naming conventions. It then uses set() to pass the articles into the Template (which
we’ll create soon). CakePHP will automatically render the template after our controller action completes.

Create the Article List Template
Now that we have our controller pulling data from the model, and preparing our view context, let’s create a view
template for our index action.
CakePHP view templates are presentation-flavored PHP code that is inserted inside the application’s layout. While
we’ll be creating HTML here, Views can also generate JSON, CSV or even binary files like PDFs.
A layout is presentation code that is wrapped around a view. Layout files contain common site elements like headers,footers and navigation elements. Your application can have multiple layouts, and you can switch between them, but for
now, let’s just use the default layout.
CakePHP’s template files are stored in src/Template inside a folder named after the controller they correspond to. So
we’ll have to create a folder named ‘Articles’ in this case. Add the following code to your application:<!-- File: src/Template/Articles/index.ctp --><h1>Articles</h1><table><tr><th>Title</th><th>Created</th></tr><!-- Here is where we iterate through our $articles query object, printing out␣
article info -->˓→<?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
</tr>
<?php endforeach; ?></table>In the last section we assigned the ‘articles’ variable to the view using set(). Variables passed into the view areavailable in the view templates as local variables which we used in the above code.
You might have noticed the use of an object called $this->Html. This is an instance of the CakePHP HtmlHelper.
CakePHP comes with a set of view helpers that make tasks like creating links, forms, and pagination buttons easy.
You can learn more about Helpers in their chapter, but what’s important to note here is that the link() method will
generate an HTML link with the given link text (the first parameter) and URL (the second parameter).
When specifying URLs in CakePHP, it is recommended that you use arrays or named routes. These syntaxes allow you
to leverage the reverse routing features CakePHP offers.

CMS Tutorial - Creating the Articles Controller

113

CakePHP Book, Release 3.10

At this point, you should be able to point your browser to http://localhost:8765/articles/index. You should see yourlist view, correctly formatted with the title and table listing of the articles.

Create the View Action
If you were to click one of the ‘view’ links in our Articles list page, you’d see an error page saying that action hasn’t
been implemented. Lets fix that now:// Add to existing src/Controller/ArticlesController.php filepublic function view($slug = null){$article = $this->Articles->findBySlug($slug)->firstOrFail();$this->set(compact('article'));}While this is a simple action, we’ve used some powerful CakePHP features. We start our action off by using
findBySlug() which is a Dynamic Finder. This method allows us to create a basic query that finds articles by agiven slug. We then use firstOrFail() to either fetch the first record, or throw a NotFoundException.
Our action takes a $slug parameter, but where does that parameter come from? If a user requests /articles/view/
first-post, then the value ‘first-post’ is passed as $slug by CakePHP’s routing and dispatching layers. If we reload
our browser with our new action saved, we’d see another CakePHP error page telling us we’re missing a view template;
let’s fix that.

Create the View Template
Let’s create the view for our new ‘view’ action and place it in src/Template/Articles/view.ctp<!-- File: src/Template/Articles/view.ctp --><h1><?= h($article->title) ?></h1><p><?= h($article->body) ?></p><p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p><p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>
You can verify that this is working by trying the links at /articles/index or manually requesting an article byaccessing URLs like /articles/view/first-post.

Adding Articles
With the basic read views created, we need to make it possible for new articles to be created. Start by creating an add()
action in the ArticlesController. Our controller should now look like:// src/Controller/ArticlesController.php
namespace App\Controller;
use App\Controller\AppController;class ArticlesController extends AppController{(continues on next page)

114

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)

public function initialize(){
parent::initialize();$this->loadComponent('Paginator');$this->loadComponent('Flash'); // Include the FlashComponent}
public function index(){$articles = $this->Paginator->paginate($this->Articles->find());$this->set(compact('articles'));}public function view($slug){$article = $this->Articles->findBySlug($slug)->firstOrFail();$this->set(compact('article'));}public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {$article = $this->Articles->patchEntity($article, $this->request->getData());// Hardcoding the user_id is temporary, and will be removed later// when we build authentication out.
$article->user_id = 1;
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);}}

Note: You need to include the Flash component in any controller where you will use it. Often it makes sense toinclude it in your AppController.
Here’s what the add() action does:• If the HTTP method of the request was POST, try to save the data using the Articles model.
• If for some reason it doesn’t save, just render the view. This gives us a chance to show the user validation errors
or other warnings.
Every CakePHP request includes a request object which is accessible using $this->request. The request object
contains information regarding the request that was just received. We use the Cake\Http\ServerRequest::is()method to check that the request is a HTTP POST request.
CMS Tutorial - Creating the Articles Controller

115

CakePHP Book, Release 3.10

Our POST data is available in $this->request->getData(). You can use the pr() or debug() functions to print
it out if you want to see what it looks like. To save our data, we first ‘marshal’ the POST data into an Article Entity.
The Entity is then persisted using the ArticlesTable we created earlier.
After saving our new article we use FlashComponent’s success() method to set a message into the session. The
success method is provided using PHP’s magic method features49 . Flash messages will be displayed on thenext page after redirecting. In our layout we have <?= $this->Flash->render() ?> which displays flash messages and clears the corresponding session variable. Finally, after saving is complete, we use Cake\Controller\
Controller::redirect to send the user back to the articles list. The param ['action' => 'index'] translates to
URL /articles i.e the index action of the ArticlesController. You can refer to Cake\Routing\Router::url()function on the API50 to see the formats in which you can specify a URL for various CakePHP functions.

Create Add Template
Here’s our add view template:<!-- File: src/Template/Articles/add.ctp --><h1>Add Article</h1><?php
echo $this->Form->create($article);// Hard code the user for now.
echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>
We use the FormHelper to generate the opening tag for an HTML form.
$this->Form->create() generates:

Here’s the HTML that<form method="post" action="/articles/add">
Because we called create() without a URL option, FormHelper assumes we want the form to submit back to thecurrent action.
The $this->Form->control() method is used to create form elements of the same name. The first parameter tells
CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options - inthis case, the number of rows for the textarea. There’s a bit of introspection and conventions used here. The control()will output different form elements based on the model field specified, and use inflection to generate the label text. You
can customize the label, the input or any other aspect of the form controls using options. The $this->Form->end()call closes the form.
Now let’s go back and update our src/Template/Articles/index.ctp view to include a new “Add Article” link. Before
the <table>, add the following line:<?= $this->Html->link('Add Article', ['action' => 'add']) ?>49 https://php.net/manual/en/language.oop5.overloading.php#object.call
50 https://api.cakephp.org

116

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Adding Simple Slug Generation
If we were to save an Article right now, saving would fail as we are not creating a slug attribute, and the column is NOT
NULL. Slug values are typically a URL-safe version of an article’s title. We can use the beforeSave() callback of the
ORM to populate our slug:// in src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;// the Text classuse Cake\Utility\Text;// Add the following method.
public function beforeSave($event, $entity, $options){if ($entity->isNew() && !$entity->slug) {$sluggedTitle = Text::slug($entity->title);// trim slug to maximum length defined in schema$entity->slug = substr($sluggedTitle, 0, 191);}}
This code is simple, and doesn’t take into account duplicate slugs. But we’ll fix that later on.

Add Edit Action
Our application can now save articles, but we can’t edit them. Lets rectify that now. Add the following action to your
ArticlesController:// in src/Controller/ArticlesController.php// Add the following method.
public function edit($slug){$article = $this->Articles->findBySlug($slug)->firstOrFail();
if ($this->request->is(['post', 'put'])) {$this->Articles->patchEntity($article, $this->request->getData());
if ($this->Articles->save($article)) {$this->Flash->success(__('Your article has been updated.'));
return $this->redirect(['action' => 'index']);}$this->Flash->error(__('Unable to update your article.'));}$this->set('article', $article);}This action first ensures that the user has tried to access an existing record. If they haven’t passed in an $slug parameter,or the article does not exist, a NotFoundException will be thrown, and the CakePHP ErrorHandler will render theappropriate error page.

CMS Tutorial - Creating the Articles Controller

117CakePHP Book, Release 3.10

Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST/PUT data
to update our article entity by using the patchEntity() method. Finally, we call save() set the appropriate flash
message and either redirect or display validation errors.

Create Edit Template
The edit template should look like this:<!-- File: src/Template/Articles/edit.ctp --><h1>Edit Article</h1><?php
echo $this->Form->create($article);echo $this->Form->control('user_id', ['type' => 'hidden']);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>This template outputs the edit form (with the values populated), along with any necessary validation error messages.
You can now update your index view with links to edit specific articles:<!-- File: src/Template/Articles/index.ctp(edit links added) --><h1>Articles</h1><p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p><table><tr><th>Title</th><th>Created</th><th>Action</th></tr><!-- Here's where we iterate through our $articles query object, printing out article␣
˓→info --><?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
</td>
</tr>
<?php endforeach; ?></table>118

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Update Validation Rules for Articles
Up until this point our Articles had no input validation done. Lets fix that by using a validator:// src/Model/Table/ArticlesTable.php// add this use statement right below the namespace declaration to import// the Validator classuse Cake\Validation\Validator;// Add the following method.
public function validationDefault(Validator $validator){$validator->allowEmptyString('title', 'Title cannot be empty', false)->minLength('title', 10)->maxLength('title', 255);$validator->allowEmptyString('body', 'Body cannot be empty', false)->minLength('body', 10);return $validator;}
The validationDefault() method tells CakePHP how to validate your data when the save() method is called.
Here, we’ve specified that both the title, and body fields must not be empty, and have certain length constraints.
CakePHP’s validation engine is powerful and flexible. It provides a suite of frequently used rules for tasks like email
addresses, IP addresses etc. and the flexibility for adding your own validation rules. For more information on that
setup, check the Validation documentation.
Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how
it works. Since we’ve used the Cake\View\Helper\FormHelper::control() method of the FormHelper to create
our form elements, our validation error messages will be shown automatically.

Add Delete Action
Next, let’s make a way for users to delete articles. Start with a delete() action in the ArticlesController:// src/Controller/ArticlesController.php
public function delete($slug){$this->request->allowMethod(['post', 'delete']);$article = $this->Articles->findBySlug($slug)->firstOrFail();
if ($this->Articles->delete($article)) {$this->Flash->success(__('The {0} article has been deleted.', $article->title));return $this->redirect(['action' => 'index']);}}This logic deletes the article specified by $slug, and uses $this->Flash->success() to show the user a confirmation message after redirecting them to /articles. If the user attempts to delete an article using a GET request,
CMS Tutorial - Creating the Articles Controller

119CakePHP Book, Release 3.10

allowMethod() will throw an exception. Uncaught exceptions are captured by CakePHP’s exception handler, and anice error page is displayed. There are many built-in Exceptions that can be used to indicate the various HTTP errors
your application might need to generate.
Warning: Allowing content to be deleted using GET requests is very dangerous, as web crawlers could accidentally
delete all your content. That is why we used allowMethod() in our controller.
Because we’re only executing logic and redirecting to another action, this action has no template. You might want to
update your index template with links that allow users to delete articles:<!-- File: src/Template/Articles/index.ctp(delete links added) --><h1>Articles</h1><p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p><table><tr><th>Title</th><th>Created</th><th>Action</th></tr><!-- Here's where we iterate through our $articles query object, printing out article␣
˓→info --><?php foreach ($articles as $article): ?>
<tr>
<td>
<?= $this->Html->link($article->title, ['action' => 'view', $article->slug])␣
˓→?>
</td>
<td>
<?= $article->created->format(DATE_RFC850) ?>
</td>
<td>
<?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?><?= $this->Form->postLink('Delete',['action' => 'delete', $article->slug],['confirm' => 'Are you sure?'])
?>
</td>
</tr>
<?php endforeach; ?></table>Using postLink() will create a link that uses JavaScript to do a POST request deleting our article.
Note: This view code also uses the FormHelper to prompt the user with a JavaScript confirmation dialog before theyattempt to delete an article.
With a basic articles management setup, we’ll create the basic actions for our Tags and Users tables.
120

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

CMS Tutorial - Tags and Users
With the basic article creation functionality built, we need to enable multiple authors to work in our CMS. Previously,
we built all the models, views and controllers by hand. This time around we’re going to use Bake Console to create ourskeleton code. Bake is a powerful code generation CLI (Command Line Interface) tool that leverages the conventions
CakePHP uses to create skeleton CRUD (Create, Read, Update, Delete) applications very efficiently. We’re going touse bake to build our users code:
cd /path/to/our/app
bin/cake bake model users
bin/cake bake controller users
bin/cake bake template users
These 3 commands will generate:• The Table, Entity, Fixture files.
• The Controller• The CRUD templates.
• Test cases for each generated class.
Bake will also use the CakePHP conventions to infer the associations, and validation your models have.

Adding Tagging to Articles
With multiple users able to access our small CMS it would be nice to have a way to categorize our content. We’ll use
tags and tagging to allow users to create free-form categories and labels for their content. Again, we’ll use bake toquickly generate some skeleton code for our application:# Generate all the code at once.
bin/cake bake all tags
Once you have the scaffold code created, create a few sample tags by going to http://localhost:8765/tags/add.
Now that we have a Tags table, we can create an association between Articles and Tags. We can do so by adding thefollowing to the initialize method on the ArticlesTable:
public function initialize(array $config){$this->addBehavior('Timestamp');$this->belongsToMany('Tags'); // Add this line}
This association will work with this simple definition because we followed CakePHP conventions when creating ourtables. For more information, read Associations - Linking Tables Together.

CMS Tutorial - Tags and Users

121

CakePHP Book, Release 3.10

Updating Articles to Enable Tagging
Now that our application has tags, we need to enable users to tag their articles. First, update the add action to look like:// in src/Controller/ArticlesController.php
namespace App\Controller;
use App\Controller\AppController;class ArticlesController extends AppController{
public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {$article = $this->Articles->patchEntity($article, $this->request->getData());// Hardcoding the user_id is temporary, and will be removed later// when we build authentication out.
$article->user_id = 1;
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.'));}// Get a list of tags.
$tags = $this->Articles->Tags->find('list');// Set tags to the view context$this->set('tags', $tags);$this->set('article', $article);}// Other actions}
The added lines load a list of tags as an associative array of id => title. This format will let us create a new tag
input in our template. Add the following to the PHP block of controls in src/Template/Articles/add.ctp:
echo $this->Form->control('tags._ids', ['options' => $tags]);
This will render a multiple select element that uses the $tags variable to generate the select box options. You should
now create a couple new articles that have tags, as in the following section we’ll be adding the ability to find articles
by tags.
You should also update the edit method to allow adding or editing tags. The edit method should now look like:public function edit($slug){$article = $this->Articles(continues on next page)

122

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)->findBySlug($slug)->contain('Tags') // load associated Tags->firstOrFail();
if ($this->request->is(['post', 'put'])) {$this->Articles->patchEntity($article, $this->request->getData());
if ($this->Articles->save($article)) {$this->Flash->success(__('Your article has been updated.'));
return $this->redirect(['action' => 'index']);}$this->Flash->error(__('Unable to update your article.'));}// Get a list of tags.
$tags = $this->Articles->Tags->find('list');// Set tags to the view context$this->set('tags', $tags);$this->set('article', $article);}
Remember to add the new tags multiple select control we added to the add.ctp template to thesrc/Template/Articles/edit.ctp template as well.

Finding Articles By Tags
Once users have categorized their content, they will want to find that content by the tags they used. For this feature
we’ll implement a route, controller action, and finder method to search through articles by tag.
Ideally, we’d have a URL that looks like http://localhost:8765/articles/tagged/funny/cat/gifs. This would let us find
all the articles that have the ‘funny’, ‘cat’ or ‘gifs’ tags. Before we can implement this, we’ll add a new route. Your
config/routes.php should look like:<?php
use Cake\Http\Middleware\CsrfProtectionMiddleware;
use Cake\Routing\RouteBuilder;use Cake\Routing\Router;use Cake\Routing\Route\DashedRoute;
Router::defaultRouteClass(DashedRoute::class);
Router::scope('/', function (RouteBuilder $routes) {// Register scoped middleware for in scopes.
$routes->registerMiddleware('csrf', new CsrfProtectionMiddleware(['httpOnly' => true]));
$routes->applyMiddleware('csrf');$routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);$routes->connect('/pages/*', ['controller' => 'Pages', 'action' => 'display']);$routes->fallbacks(DashedRoute::class);});// Add this(continues on next page)

CMS Tutorial - Tags and Users

123

CakePHP Book, Release 3.10

(continued from previous page)// New route we're adding for our tagged action.
// The trailing `*` tells CakePHP that this action has// passed parameters.
Router::scope('/articles', function (RouteBuilder $routes) {$routes->connect('/tagged/*', ['controller' => 'Articles', 'action' => 'tags']);});
The above defines a new ‘route’ which connects the /articles/tagged/ path, to ArticlesController::tags().
By defining routes, you can isolate how your URLs look, from how they are implemented. If we were to visit
http://localhost:8765/articles/tagged, we would see a helpful error page from CakePHP informing you that the controller action does not exist. Let’s implement that missing method now. In src/Controller/ArticlesController.php add
the following:
public function tags(){// The 'pass' key is provided by CakePHP and contains all// the passed URL path segments in the request.
$tags = $this->request->getParam('pass');// Use the ArticlesTable to find tagged articles.
$articles = $this->Articles->find('tagged', ['tags' => $tags]);// Pass variables into the view template context.
$this->set(['articles' => $articles,'tags' => $tags]);}
To access other parts of the request data, consult the Request section.
Since passed arguments are passed as method parameters, you could also write the action using PHP’s variadic argument:
public function tags(...$tags){// Use the ArticlesTable to find tagged articles.
$articles = $this->Articles->find('tagged', ['tags' => $tags]);// Pass variables into the view template context.
$this->set(['articles' => $articles,'tags' => $tags
]);
}

124

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Creating the Finder Method
In CakePHP we like to keep our controller actions slim, and put most of our application’s logic in the model layer. If
you were to visit the /articles/tagged URL now you would see an error that the findTagged() method has not been
implemented yet, so let’s do that. In src/Model/Table/ArticlesTable.php add the following:// add this use statement right below the namespace declaration to import// the Query classuse Cake\ORM\Query;// The $query argument is a query builder instance.
// The $options array will contain the 'tags' option we passed// to find('tagged') in our controller action.
public function findTagged(Query $query, array $options){$columns = ['Articles.id', 'Articles.user_id', 'Articles.title','Articles.body', 'Articles.published', 'Articles.created','Articles.slug',];$query = $query->select($columns)->distinct($columns);
if (empty($options['tags'])) {// If there are no tags provided, find articles that have no tags.
$query->leftJoinWith('Tags')->where(['Tags.title IS' => null]);} else {// Find articles that have one or more of the provided tags.
$query->innerJoinWith('Tags')->where(['Tags.title IN' => $options['tags']]);}
return $query->group(['Articles.id']);}We just implemented a custom finder method. This is a very powerful concept in CakePHP that allows you to package
up re-usable queries. Finder methods always get a Query Builder object and an array of options as parameters. Finders
can manipulate the query and add any required conditions or criteria. When complete, finder methods must return amodified query object. In our finder we’ve leveraged the distinct() and leftJoin() methods which allow us tofind distinct articles that have a ‘matching’ tag.

CMS Tutorial - Tags and Users

125

CakePHP Book, Release 3.10

Creating the View
Now if you visit the /articles/tagged URL again, CakePHP will show a new error letting you know that you have notmade a view file. Next, let’s build the view file for our tags() action. In src/Template/Articles/tags.ctp put thefollowing content:<h1>
Articles tagged with<?= $this->Text->toList(h($tags), 'or') ?></h1><section><?php foreach ($articles as $article): ?><article><!-- Use the HtmlHelper to create a link --><h4><?= $this->Html->link($article->title,['controller' => 'Articles', 'action' => 'view', $article->slug]) ?></h4><span><?= h($article->created) ?></span></article><?php endforeach; ?></section>
In the above code we use the Html and Text helpers to assist in generating our view output. We also use the h shortcut
function to HTML encode output. You should remember to always use h() when outputting data to prevent HTMLinjection issues.
The tags.ctp file we just created follows the CakePHP conventions for view template files. The convention is to havethe template use the lower case and underscored version of the controller action name.
You may notice that we were able to use the $tags and $articles variables in our view template. When we use
the set() method in our controller, we set specific variables to be sent to the view. The View will make all passed
variables available in the template scope as local variables.
You should now be able to visit the /articles/tagged/funny URL and see all the articles tagged with ‘funny’.

Improving the Tagging Experience
Right now, adding new tags is a cumbersome process, as authors need to pre-create all the tags they want to use. We
can improve the tag selection UI by using a comma separated text field. This will let us give a better experience to ourusers, and use some more great features in the ORM.
Adding a Computed Field
Because we’ll want a simple way to access the formatted tags for an entity, we can add a virtual/computed field to theentity. In src/Model/Entity/Article.php add the following:// add this use statement right below the namespace declaration to import// the Collection classuse Cake\Collection\Collection;// Update the accessible property to contain `tag_string`(continues on next page)

126

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)

protected $_accessible = [//other fields...
'tag_string' => true];
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, ', ');}This will let us access the $article->tag_string computed property. We’ll use this property in controls later on.
Updating the Views
With the entity updated we can add a new control for our tags. In src/Template/Articles/add.ctp andsrc/Template/Articles/edit.ctp, replace the existing tags._ids control with the following:echo $this->Form->control('tag_string', ['type' => 'text']);We’ll also need to update the article view template. In src/Template/Articles/view.ctp add the line as shown:<!-- File: src/Template/Articles/view.ctp --><h1><?= h($article->title) ?></h1><p><?= h($article->body) ?></p>// Add the following line
<p><b>Tags:</b> <?= h($article->tag_string) ?></p>

Persisting the Tag String
Now that we can view existing tags as a string, we’ll want to save that data as well. Because we marked the tag_stringas accessible, the ORM will copy that data from the request into our entity. We can use a beforeSave() hook method
to parse the tag string and find/build the related entities. Add the following to src/Model/Table/ArticlesTable.php:
public function beforeSave($event, $entity, $options){if ($entity->tag_string) {$entity->tags = $this->_buildTags($entity->tag_string);}// Other code
(continues on next page)

CMS Tutorial - Tags and Users

127

CakePHP Book, Release 3.10

(continued from previous page)}
protected function _buildTags($tagString){// Trim tags
$newTags = array_map('trim', explode(',', $tagString));// Remove all empty tags
$newTags = array_filter($newTags);// Reduce duplicated tags
$newTags = array_unique($newTags);$out = [];$query = $this->Tags->find()->where(['Tags.title IN' => $newTags]);// Remove existing tags from the list of new tags.
foreach ($query->extract('title') as $existing) {$index = array_search($existing, $newTags);
if ($index !== false) {unset($newTags[$index]);}}// Add existing tags.
foreach ($query as $tag) {$out[] = $tag;}// Add new tags.
foreach ($newTags as $tag) {$out[] = $this->Tags->newEntity(['title' => $tag]);}
return $out;}
If you now create or edit articles, you should be able to save tags as a comma separated list of tags, and have the tags
and linking records automatically created.
While this code is a bit more complicated than what we’ve done so far, it helps to showcase how powerful the ORM
in CakePHP is. You can manipulate query results using the Collections methods, and handle scenarios where you arecreating entities on the fly with ease.

Auto-populating the Tag String
Before we finish up, we’ll need a mechanism that will load the associated tags (if any) whenever we load an article.
In your src/Model/Table/ArticlesTable.php, change:
public function initialize(array $config){$this->addBehavior('Timestamp');// Change this line
$this->belongsToMany('Tags', ['joinTable' => 'articles_tags',(continues on next page)

128

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)'dependent' => true]);}
This will tell the Articles table model that there is a join table associated with tags. The ‘dependent’ option tells thetable to delete any associated records from the join table if an article is deleted.
Lastly, update the findBySlug() method calls in src/Controller/ArticlesController.php:
public function edit($slug){// Update this line
$article = $this->Articles->findBySlug($slug)->contain(['Tags'])->firstOrFail();...
}public function view($slug = null){// Update this line
$article = $this->Articles->findBySlug($slug)->contain(['Tags'])->firstOrFail();$this->set(compact('article'));}
The contain() method tells the ArticlesTable object to also populate the Tags association when the article is loaded.
Now when tag_string is called for an Article entity, there will be data present to create the string!
Next we’ll be adding authentication.

CMS Tutorial - Authentication
Now that our CMS has users, we should enable them to login, and apply some basic access control to the article creation& editing experiences.

Adding Password Hashing
If you were to create/update a user at this point in time, you might notice that the passwords are stored in plain text.
This is really bad from a security point of view, so lets fix that.
This is also a good time to talk about the model layer in CakePHP. In CakePHP, we separate the methods that operate
on a collection of objects, and a single object into different classes. Methods that operate on the collection of entities
are put in the Table class, while features belonging to a single record are put on the Entity class.
For example, password hashing is done on the individual record, so we’ll implement this behavior on the entity object.
Because we want to hash the password each time it is set, we’ll use a mutator/setter method. CakePHP will callconvention based setter methods any time a property is set in one of your entities. Let’s add a setter for the password.
In src/Model/Entity/User.php add the following:<?php
namespace App\Model\Entity;(continues on next page)

CMS Tutorial - Authentication

129

CakePHP Book, Release 3.10

(continued from previous page)use Cake\Auth\DefaultPasswordHasher; // Add this line
use Cake\ORM\Entity;class User extends Entity{// Code from bake.
// Add this method
protected function _setPassword($value){
if (strlen($value)) {$hasher = new DefaultPasswordHasher();
return $hasher->hash($value);}}}Now, point your browser to http://localhost:8765/users to see a list of users. You can edit the default user that was
created during Installation. If you change that user’s password, you should see a hashed password instead of the originalvalue on the list or view pages. CakePHP hashes passwords with bcrypt51 by default. You can also use SHA-1 or MD5
if you’re working with an existing database, but we recommend bcrypt for all new applications.
Note: Create a hashed password for at least one of the user accounts now! It will be needed in the next steps.

Adding Login
In CakePHP, authentication is handled by Components. Components can be thought of as ways to create reusable chunksof controller code related to a specific feature or concept. Components can hook into the controller’s event life-cycle
and interact with your application that way. To get started, we’ll add the AuthComponent to our application. We’ll want
the create, update and delete methods to require authentication, so we’ll add AuthComponent in our AppController:// In src/Controller/AppController.php
namespace App\Controller;
use Cake\Controller\Controller;class AppController extends Controller{
public function initialize(){// Existing code
$this->loadComponent('Auth', ['authenticate' => ['Form' => ['fields' => ['username' => 'email',(continues on next page)51 https://codahale.com/how-to-safely-store-a-password/

130

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)'password' => 'password']]],'loginAction' => ['controller' => 'Users','action' => 'login'],// If unauthorized, return them to page they were just on'unauthorizedRedirect' => $this->referer()]);// Allow the display action so our PagesController// continues to work. Also enable the read only actions.
$this->Auth->allow(['display', 'view', 'index']);}}We’ve just told CakePHP that we want to load the Auth component. We’ve customized the configuration of AuthComponent, as our users table uses email as the username. Now, if you go any protected URL, such as /articles/add,
you’ll be redirected to /users/login, which will show an error page as we have not written that code yet. So let’s create
the login action:// In 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.');}}Create a new template src/Template/Users/login.ctp and add the following:<h1>Login</h1><?= $this->Form->create() ?><?= $this->Form->control('email') ?><?= $this->Form->control('password') ?><?= $this->Form->button('Login') ?><?= $this->Form->end() ?>Now that we have a simple login form, we should be able to log in with one of the users that has a hashed password.
Note:
If none of your users have hashed passwords, comment the loadComponent('Auth') block and$this->Auth->allow() calls. Then go and edit the user, saving a new password for them. After saving a new
password for the user, make sure to uncomment the lines we just temporarily commented!

CMS Tutorial - Authentication

131

CakePHP Book, Release 3.10

Try it out! Before logging in, visit /articles/add. Since this action is not allowed, you will be redirected to the login
page. After logging in successfully, CakePHP will automatically redirect you back to /articles/add.
Adding Logout
Now that people can log in, you’ll probably want to provide a way to log out as well. Again, in the UsersController,
add the following code:
public function initialize(){
parent::initialize();$this->Auth->allow(['logout']);}public function logout(){$this->Flash->success('You are now logged out.');return $this->redirect($this->Auth->logout());}
This code adds the logout action to the list of actions that do not require authentication and implements the logout
method. Now you can visit /users/logout to log out. You should then be sent to the login page.
Enabling Registrations
If you aren’t logged in and you try to visit /users/add you will be redirected to the login page. We should fix that as wewant to allow people to sign up for our application. In the UsersController add the following:
public function initialize(){
parent::initialize();// Add the 'add' action to the allowed actions list.
$this->Auth->allow(['logout', 'add']);}The above tells AuthComponent that the add() action of the UsersController does not require authentication or
authorization. You may want to take the time to clean up the Users/add.ctp and remove the misleading links, or
continue on to the next section. We won’t be building out user editing, viewing or listing in this tutorial, but that is an
exercise you can complete on your own.
Restricting Article Access
Now that users can log in, we’ll want to limit users to only edit articles that they created. We’ll do this using an ‘authorization’ adapter. Since our requirements are basic, we can use a controller hook method in our ArticlesController.
But before we do that, we’ll want to tell the AuthComponent how our application is going to authorize actions. Update
your AppController adding the following:
public function isAuthorized($user){// By default deny access.
return false;}

132

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Next we’ll tell AuthComponent that we want to use controller hook methods for authorization.
AppController::initialize() method should now look like:Yourpublic function initialize(){// Existing code
$this->loadComponent('Flash');$this->loadComponent('Auth', [// Added this line
'authorize'=> 'Controller','authenticate' => ['Form' => ['fields' => ['username' => 'email','password' => 'password']]],'loginAction' => ['controller' => 'Users','action' => 'login'],// If unauthorized, return them to page they were just on'unauthorizedRedirect' => $this->referer()]);// Allow the display action so our pages controller// continues to work. Also enable the read only actions.
$this->Auth->allow(['display', 'view', 'index']);}We’ll default to denying access, and incrementally grant access where it makes sense. First, we’ll add the authorization
logic for articles. In your ArticlesController add the following:
public function isAuthorized($user){$action = $this->request->getParam('action');// The add and tags actions are always allowed to logged in users.
if (in_array($action, ['add', 'tags'])) {return true;}// All other actions require a slug.
$slug = $this->request->getParam('pass.0');
if (!$slug) {return false;}// Check that the article belongs to the current user.
$article = $this->Articles->findBySlug($slug)->first();return $article->user_id === $user['id'];}

CMS Tutorial - Authentication

133

CakePHP Book, Release 3.10

Now if you try to edit or delete an article that does not belong to you, you should be redirected back to the page youcame from. If no error message is displayed, add the following to your layout:// In src/Template/Layout/default.ctp<?= $this->Flash->render() ?>Next you should add the tags action to the actions allowed for unauthenticated users, by adding the following toinitialize() in src/Controller/ArticlesController.php:$this->Auth->allow(['tags']);
While the above is fairly simplistic it illustrates how you could build more complex logic that combines the current
user and request data to build flexible authorization logic.
Fixing the Add & Edit Actions
While we’ve blocked access to the edit action, we’re still open to users changing the user_id attribute of articles duringedit. We will solve these problems next. First up is the add action.
When creating articles, we want to fix the user_id to be the currently logged in user. Replace your add action withthe following:// in src/Controller/ArticlesController.php
public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {$article = $this->Articles->patchEntity($article, $this->request->getData());// Changed: Set the user_id from the session.
$article->user_id = $this->Auth->user('id');
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);}
Next we’ll update the edit action. Replace the edit method with the following:// in src/Controller/ArticlesController.php
public function edit($slug){$article = $this->Articles->findBySlug($slug)->contain('Tags') // load associated Tags->firstOrFail();
if ($this->request->is(['post', 'put'])) {(continues on next page)

134

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)$this->Articles->patchEntity($article, $this->request->getData(), [// Added: Disable modification of user_id.
'accessibleFields' => ['user_id' => false]]);
if ($this->Articles->save($article)) {$this->Flash->success(__('Your article has been updated.'));
return $this->redirect(['action' => 'index']);}$this->Flash->error(__('Unable to update your article.'));}$this->set('article', $article);}
Here we’re modifying which properties can be mass-assigned, via the options for patchEntity(). See theChanging Accessible Fields section for more information. Remember to remove the user_id control fromsrc/Template/Articles/edit.ctp as we no longer need it.
Wrapping Up
We’ve built a simple CMS application that allows users to login, post articles, tag them, explore posted articles bytag, and applied basic access control to articles. We’ve also added some nice UX improvements by leveraging theFormHelper and ORM capabilities.
Thank you for taking the time to explore CakePHP. Next, you should learn more about the Database Access & ORM,
or you peruse the /topics.

Bookmarker Tutorial
This tutorial will walk you through the creation of a simple bookmarking application (bookmarker). To start with, we’ll
be installing CakePHP, creating our database, and using the tools CakePHP provides to get our application up fast.
Here’s what you’ll need:
1. A database server. We’re going to be using MySQL server in this tutorial. You’ll need to know enough about
SQL in order to create a database: CakePHP will be taking the reins from there. Since we’re using MySQL, also
make sure that you have pdo_mysql enabled in PHP.
2. Basic PHP knowledge.
Before starting you should make sure that you have got an up to date PHP version:php -v
You should at least have got installed PHP 5.6 (CLI) or higher. Your webserver’s PHP version must also be of 5.6 orhigher, and should best be the same version your command line interface (CLI) PHP version is of. If you’d like to see
the completed application, checkout cakephp/bookmarker52 . Let’s get started!
52 https://github.com/cakephp/bookmarker-tutorial

Bookmarker Tutorial

135

CakePHP Book, Release 3.10

Getting CakePHPThe easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from yourterminal or command line prompt. First, you’ll need to download and install Composer if you haven’t done so already.
If you have cURL installed, it’s as easy as running the following:
curl -s https://getcomposer.org/installer | php
Or, you can download composer.phar from the Composer website53 .
Then simply type the following line in your terminal from your installation directory to install the CakePHP application
skeleton in the bookmarker directory:
php composer.phar create-project --prefer-dist cakephp/app:"^3.10" bookmarker
If you downloaded and ran the Composer Windows Installer54 , then type the following line in your terminal from yourinstallation directory (ie. C:\wamp\www\dev\cakephp3):
composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10"␣
˓→bookmarker
The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting
the correct file permissions and creating your config/app.php file for you.
There are other ways to install CakePHP. If you cannot or don’t want to use Composer, check out the Installation section.
Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup shouldlook something like the following:/bookmarker/bin/config/logs/plugins/src/tests/tmp/vendor/webroot.editorconfig.gitignore.htaccess.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md
Now might be a good time to learn a bit about how CakePHP’s directory structure works: check out the CakePHP
Folder Structure section.
53 https://getcomposer.org/download/
54 https://getcomposer.org/Composer-Setup.exe

136

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Checking our Installation
We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you’ll
need to start the development server:
bin/cake server

Note: For Windows, the command needs to be bin\cake server (note the backslash).
This will start PHP’s built-in webserver on port 8765. Open up http://localhost:8765 in your web browser to see thewelcome page. All the bullet points should be checkmarks other than CakePHP being able to connect to your database.
If not, you may need to install additional PHP extensions, or set directory permissions.

Creating the Database
Next, let’s set up the database for our bookmarking application. If you haven’t already done so, create an empty databasefor use in this tutorial, with a name of your choice, e.g. cake_bookmarks. You can execute the following SQL to create
the necessary tables:
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),
FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),(continues on next page)

Bookmarker Tutorial

137

CakePHP Book, Release 3.10

(continued from previous page)

FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id));
You may have noticed that the bookmarks_tags table used a composite primary key. CakePHP supports composite
primary keys almost everywhere, making it easier to build multi-tenanted applications.
The table and column names we used were not arbitrary. By using CakePHP’s naming conventions, we can leverage
CakePHP better and avoid having to configure the framework. CakePHP is flexible enough to accommodate eveninconsistent legacy database schemas, but adhering to the conventions will save you time.

Database Configuration
Next, let’s tell CakePHP where our database is and how to connect to it. For many, this will be the first and last time
you will need to configure anything.
The configuration should be pretty straightforward: just replace the values in the Datasources.default array in theconfig/app.php file with those that apply to your setup. A sample completed configuration array might look something
like the following:
return [// More configuration above.
'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,],],// More configuration below.
];
Once you’ve saved your config/app.php file, you should see that ‘CakePHP is able to connect to the database’ section
have a checkmark.
Note: A copy of CakePHP’s default configuration file is found in config/app.default.php.

138

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Generating Scaffold Code
Because our database is following the CakePHP conventions, we can use the bake console application to quickly generate a basic application. In your command line run the following commands:// On Windows you'll need to use bin\cake instead.
bin/cake bake all users
bin/cake bake all bookmarks
bin/cake bake all tags
This will generate the controllers, models, views, their corresponding test cases, and fixtures for our users, bookmarks
and tags resources. If you’ve stopped your server, restart it and go to http://localhost:8765/bookmarks.
You should see a basic but functional application providing data access to your application’s database tables. Onceyou’re at the list of bookmarks, add a few users, bookmarks, and tags.

Adding Password Hashing
When you created your users (by visiting http://localhost:8765/users), you probably noticed that the passwords werestored in plain text. This is pretty bad from a security point of view, so let’s get that fixed.
This is also a good time to talk about the model layer in CakePHP. In CakePHP, we separate the methods that operate
on a collection of objects, and a single object into different classes. Methods that operate on the collection of entities
are put in the Table class, while features belonging to a single record are put on the Entity class.
For example, password hashing is done on the individual record, so we’ll implement this behavior on the entity object.
Because, we want to hash the password each time it is set, we’ll use a mutator/setter method. CakePHP will callconvention based setter methods any time a property is set in one of your entities. Let’s add a setter for the password.
In src/Model/Entity/User.php add the following:namespace App\Model\Entity;
use Cake\Auth\DefaultPasswordHasher; //include this line
use Cake\ORM\Entity;class User extends Entity{// Code from bake.
protected function _setPassword($value){$hasher = new DefaultPasswordHasher();
return $hasher->hash($value);}}Now update one of the users you created earlier, if you change their password, you should see a hashed password insteadof the original value on the list or view pages. CakePHP hashes passwords with bcrypt55 by default. You can also use
sha1 or md5 if you’re working with an existing database.
Note: If the password doesn’t get hashed, make sure you followed the same case for the password member of the classwhile naming the setter function
55 https://codahale.com/how-to-safely-store-a-password/

Bookmarker Tutorial

139

CakePHP Book, Release 3.10

Getting Bookmarks with a Specific Tag
Now that we’re storing passwords safely, we can build out some more interesting features in our application. Onceyou’ve amassed a collection of bookmarks, it is helpful to be able to search through them by tag. Next we’ll implementa route, controller action, and finder method to search through bookmarks by tag.
Ideally, we’d have a URL that looks like http://localhost:8765/bookmarks/tagged/funny/cat/gifs. This would let us
find all the bookmarks that have the ‘funny’, ‘cat’ or ‘gifs’ tags. Before we can implement this, we’ll add a new route.
Your config/routes.php should look like:<?php
use Cake\Routing\Route\DashedRoute;
use Cake\Routing\Router;
Router::defaultRouteClass(DashedRoute::class);// New route we're adding for our tagged action.
// The trailing `*` tells CakePHP that this action has// passed parameters.
Router::scope('/bookmarks',['controller' => 'Bookmarks'],function ($routes) {$routes->connect('/tagged/*', ['action' => 'tags']);});Router::scope('/', function ($routes) {// Connect the default home and /pages/* routes.
$routes->connect('/', ['controller' => 'Pages','action' => 'display', 'home']);$routes->connect('/pages/*', ['controller' => 'Pages','action' => 'display']);// Connect the conventions based default routes.
$routes->fallbacks();});
The above defines a new ‘route’ which connects the /bookmarks/tagged/ path, to BookmarksController::tags().
By defining routes, you can isolate how your URLs look, from how they are implemented. If we wereto visit http://localhost:8765/bookmarks/tagged, we would see a helpful error page from CakePHP informing you that the controller action does not exist.
Let’s implement that missing method now.
In
src/Controller/BookmarksController.php add the following:
public function tags(){// The 'pass' key is provided by CakePHP and contains all// the passed URL path segments in the request.
$tags = $this->request->getParam('pass');(continues on next page)

140

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)// Use the BookmarksTable to find tagged bookmarks.
$bookmarks = $this->Bookmarks->find('tagged', ['tags' => $tags]);// Pass variables into the view template context.
$this->set(['bookmarks' => $bookmarks,'tags' => $tags]);}
To access other parts of the request data, consult the Request section.
Creating the Finder Method
In CakePHP we like to keep our controller actions slim, and put most of our application’s logic in the models. If you
were to visit the /bookmarks/tagged URL now you would see an error that the findTagged() method has not been
implemented yet, so let’s do that. In src/Model/Table/BookmarksTable.php add the following:// The $query argument is a query builder instance.
// The $options array will contain the 'tags' option we passed// to find('tagged') in our controller action.
public function findTagged(Query $query, array $options){$bookmarks = $this->find()->select(['id', 'url', 'title', 'description']);if (empty($options['tags'])) {$bookmarks->leftJoinWith('Tags')->where(['Tags.title IS' => null]);} else {$bookmarks->innerJoinWith('Tags')->where(['Tags.title IN ' => $options['tags']]);}
return $bookmarks->group(['Bookmarks.id']);}We just implemented a custom finder method. This is a very powerful concept in CakePHP that allows you to package
up re-usable queries. Finder methods always get a Query Builder object and an array of options as parameters. Finders
can manipulate the query and add any required conditions or criteria. When complete, finder methods must return amodified query object. In our finder we’ve leveraged the innerJoinWith(), where() and group() methods whichallow us to find distinct bookmarks that have a matching tag. When no tags are provided we use a leftJoinWith()and modify the ‘where’ condition, finding bookmarks without tags.

Bookmarker Tutorial

141

CakePHP Book, Release 3.10

Creating the View
Now if you visit the /bookmarks/tagged URL, CakePHP will show an error letting you know that you have not made aview file. Next, let’s build the view file for our tags() action. In src/Template/Bookmarks/tags.ctp put the following
content:<h1>
Bookmarks tagged with<?= $this->Text->toList(h($tags)) ?></h1><section><?php foreach ($bookmarks as $bookmark): ?><article><!-- Use the HtmlHelper to create a link --><h4><?= $this->Html->link($bookmark->title, $bookmark->url) ?></h4><small><?= h($bookmark->url) ?></small><!-- Use the TextHelper to format text --><?= $this->Text->autoParagraph(h($bookmark->description)) ?></article><?php endforeach; ?></section>
In the above code we use the Html and Text helpers to assist in generating our view output. We also use the h shortcut
function to HTML encode output. You should remember to always use h() when outputting user data to prevent HTMLinjection issues.
The tags.ctp file we just created follows the CakePHP conventions for view template files. The convention is to havethe template use the lower case and underscored version of the controller action name.
You may notice that we were able to use the $tags and $bookmarks variables in our view. When we use the set()method in our controller, we set specific variables to be sent to the view. The view will make all passed variables
available in the templates as local variables.
You should now be able to visit the /bookmarks/tagged/funny URL and see all the bookmarks tagged with ‘funny’.
So far, we’ve created a basic application to manage bookmarks, tags and users. However, everyone can see everyone
else’s tags. In the next chapter, we’ll implement authentication and restrict the visible bookmarks to only those thatbelong to the current user.
Now continue to Bookmarker Tutorial Part 2 to continue building your application or dive into the documentation tolearn more about what CakePHP can do for you.

Bookmarker Tutorial Part 2
After finishing the first part of this tutorial you should have a very basic bookmarking application. In this chapter we’ll
be adding authentication and restricting the bookmarks each user can see/modify to only the ones they own.

142

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Adding Login
In CakePHP, authentication is handled by Components. Components can be thought of as ways to create reusable
chunks of controller code related to a specific feature or concept. Components can also hook into the controller’s event
life-cycle and interact with your application that way. To get started, we’ll add the AuthComponent to our application.
We’ll pretty much want every method to require authentication, so we’ll add AuthComponent in our AppController:// In 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'],'unauthorizedRedirect' => $this->referer() // If unauthorized, return them␣˓→to page they were just on]);// Allow the display action so our pages controller// continues to work.
$this->Auth->allow(['display']);}}We’ve just told CakePHP that we want to load the Flash and Auth components. In addition, we’ve customized theconfiguration of AuthComponent, as our users table uses email as the username. Now, if you go to any URL you’ll
be kicked to /users/login, which will show an error page as we have not written that code yet. So let’s create the login
action:// In 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());}(continues on next page)

Bookmarker Tutorial Part 2

143

CakePHP Book, Release 3.10

(continued from previous page)$this->Flash->error('Your username or password is incorrect.');}}And in src/Template/Users/login.ctp add the following:<h1>Login</h1><?= $this->Form->create() ?><?= $this->Form->control('email') ?><?= $this->Form->control('password') ?><?= $this->Form->button('Login') ?><?= $this->Form->end() ?>Note: The control() method is available since 3.4. For prior versions you can use the input() method instead.
Now that we have a simple login form, we should be able to log in with one of the users that has a hashed password.
Note: If none of your users have hashed passwords, comment the loadComponent('Auth') line. Then go and edit
the user, saving a new password for them.

Adding Logout
Now that people can log in, you’ll probably want to provide a way to log out as well. Again, in the UsersController,
add the following code:
public function initialize(){
parent::initialize();$this->Auth->allow(['logout']);}public function logout(){$this->Flash->success('You are now logged out.');return $this->redirect($this->Auth->logout());}
This code whitelists the logout action as a public action, and implements the logout method. Now you can visit/users/logout to log out. You should then be sent to the login page.

144

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Enabling Registrations
If you aren’t logged in and you try to visit /users/add you will be kicked to the login page. We should fix that as wewant to allow people to sign up for our application. In the UsersController add the following:
public function initialize(){
parent::initialize();// Add the 'add' action to the allowed actions list.
$this->Auth->allow(['logout', 'add']);}The above tells AuthComponent that the add() action does not require authentication or authorization. You may wantto take the time to clean up the Users/add.ctp and remove the misleading links, or continue on to the next section. We
won’t be building out user editing, viewing or listing in this tutorial so they will not work as AuthComponent will deny
you access to those controller actions.

Restricting Bookmark Access
Now that users can log in, we’ll want to limit the bookmarks they can see to the ones they made. We’ll do thisusing an ‘authorization’ adapter. Since our requirements are pretty simple, we can write some simple code in ourBookmarksController. But before we do that, we’ll want to tell the AuthComponent how our application is going
to authorize actions. In your AppController add the following:
public function isAuthorized($user){
return false;}
Also, add the following to the configuration for Auth in your AppController:'authorize' => 'Controller',Your initialize() method should now look like: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()(continues on next page)

Bookmarker Tutorial Part 2145

CakePHP Book, Release 3.10

(continued from previous page)]);// Allow the display action so our pages controller// continues to work.
$this->Auth->allow(['display']);}We’ll default to denying access, and incrementally grant access where it makes sense. First, we’ll add the authorization
logic for bookmarks. In your BookmarksController add the following:
public function isAuthorized($user){$action = $this->request->getParam('action');// The add and index actions are always allowed.
if (in_array($action, ['index', 'add', 'tags'])) {return true;}// All other actions require an id.
if (!$this->request->getParam('pass.0')) {return false;}// Check that the bookmark belongs to the current user.
$id = $this->request->getParam('pass.0');$bookmark = $this->Bookmarks->get($id);
if ($bookmark->user_id == $user['id']) {return true;}
return parent::isAuthorized($user);}
Now if you try to view, edit or delete a bookmark that does not belong to you, you should be redirected back to the page
you came from. If no error message is displayed, add the following to your layout:// In src/Template/Layout/default.ctp<?= $this->Flash->render() ?>You should now see the authorization error messages.

Fixing List view and Forms
While view and delete are working, edit, add and index have a few problems:
1. When adding a bookmark you can choose the user.
2. When editing a bookmark you can choose the user.
3. The list page shows bookmarks from other users.
Let’s tackle the add form first.
To begin with remove the control('user_id') fromsrc/Template/Bookmarks/add.ctp.
With that removed, we’ll also update the add() action fromsrc/Controller/BookmarksController.php to look like:

146

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

public function add(){$bookmark = $this->Bookmarks->newEntity();if ($this->request->is('post')) {$bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData());$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'));$this->set('_serialize', ['bookmark']);}By setting the entity property with the session data, we remove any possibility of the user modifying whichuser a bookmark is for. We’ll do the same for the edit form and action. Your edit() action fromsrc/Controller/BookmarksController.php should look like: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->getData());$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'));$this->set('_serialize', ['bookmark']);}List View
Now, we only need to show bookmarks for the currently logged in user. We can do that by updating the call topaginate(). Make your index() action from src/Controller/BookmarksController.php look like:public function index(){$this->paginate = ['conditions' => ['Bookmarks.user_id' => $this->Auth->user('id'),]];(continues on next page)

Bookmarker Tutorial Part 2

147

CakePHP Book, Release 3.10

(continued from previous page)$this->set('bookmarks', $this->paginate($this->Bookmarks));$this->set('_serialize', ['bookmarks']);}
We should also update the tags() action and the related finder method, but we’ll leave that as an exercise you cancomplete on your own.

Improving the Tagging Experience
Right now, adding new tags is a difficult process, as the TagsController disallows all access. Instead of allowing
access, we can improve the tag selection UI by using a comma separated text field. This will let us give a better
experience to our users, and use some more great features in the ORM.
Adding a Computed Field
Because we’ll want a simple way to access the formatted tags for an entity, we can add a virtual/computed field to theentity. In src/Model/Entity/Bookmark.php add the following:
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, ', ');}This will let us access the $bookmark->tag_string computed property. We’ll use this property in controls later on.
Remember to add the tag_string property to the _accessible list in your entity, as we’ll want to ‘save’ it later on.
In src/Model/Entity/Bookmark.php add the tag_string to $_accessible this way:protected $_accessible = ['user_id' => true,'title' => true,'description' => true,'url' => true,'user' => true,'tags' => true,'tag_string' => true,];

148

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Updating the Views
With the entity updated we can add a new control for our tags. In src/Template/Bookmarks/add.ctp andsrc/Template/Bookmarks/edit.ctp, replace the existing tags._ids control with the following:echo $this->Form->control('tag_string', ['type' => 'text']);Persisting the Tag String
Now that we can view existing tags as a string, we’ll want to save that data as well. Because we marked the tag_stringas accessible, the ORM will copy that data from the request into our entity. We can use a beforeSave() hook method
to parse the tag string and find/build the related entities. Add the following to 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){// Trim tags
$newTags = array_map('trim', explode(',', $tagString));// Remove all empty tags
$newTags = array_filter($newTags);// Reduce duplicated tags
$newTags = array_unique($newTags);$out = [];$query = $this->Tags->find()->where(['Tags.title IN' => $newTags]);// Remove existing tags from the list of new tags.
foreach ($query->extract('title') as $existing) {$index = array_search($existing, $newTags);
if ($index !== false) {unset($newTags[$index]);}}// Add existing tags.
foreach ($query as $tag) {$out[] = $tag;}// Add new tags.
foreach ($newTags as $tag) {$out[] = $this->Tags->newEntity(['title' => $tag]);}
return $out;}
While this code is a bit more complicated than what we’ve done so far, it helps to showcase how powerful the ORM
in CakePHP is. You can manipulate query results using the Collections methods, and handle scenarios where you are

Bookmarker Tutorial Part 2

149

CakePHP Book, Release 3.10

creating entities on the fly with ease.

Wrapping Up
We’ve expanded our bookmarking application to handle authentication and basic authorization/access control scenarios.
We’ve also added some nice UX improvements by leveraging the FormHelper and ORM capabilities.
Thanks for taking the time to explore CakePHP. Next, you can complete the Blog Tutorial, learn more about the
Database Access & ORM, or you can peruse the /topics.

Blog Tutorial
This tutorial will walk you through the creation of a simple blog application. We’ll be installing CakePHP, creating a
database, and creating enough application logic to list, add, edit, and delete blog articles.
Here’s what you’ll need:
1. A running web server. We’re going to assume you’re using Apache, though the instructions for using otherservers should be very similar. We might have to play a little with the server configuration, but most folks can
get CakePHP up and running without any configuration at all. Make sure you have PHP 5.6 or greater, and thatthe mbstring and intl extensions are enabled in PHP.
2. A database server. We’re going to be using MySQL server in this tutorial. You’ll need to know enough about
SQL in order to create a database: CakePHP will be taking the reins from there. Since we’re using MySQL, also
make sure that you have pdo_mysql enabled in PHP.
3. Basic PHP knowledge.
Let’s get started!

Getting CakePHPThe easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from yourterminal or command line prompt. First, you’ll need to download and install Composer if you haven’t done so already.
If you have cURL installed, it’s as easy as running the following:
curl -s https://getcomposer.org/installer | php
Or, you can download composer.phar from the Composer website56 .
Then simply type the following line in your terminal from your installation directory to install the CakePHP application
skeleton in the directory that you wish to use it with. For this example we will be using “blog” but feel free to change
it to something else.:
php composer.phar create-project --prefer-dist cakephp/app:"^3.10" blog
In case you’ve already got composer installed globally, you may instead type:composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" blog
The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting
the correct file permissions and creating your config/app.php file for you.
There are other ways to install CakePHP. If you cannot or don’t want to use Composer, check out the Installation section.
56 https://getcomposer.org/download/

150

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup shouldlook something like the following:/cake_install/bin/config/logs/plugins/src/tests/tmp/vendor/webroot.editorconfig.gitignore.htaccess.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md
Now might be a good time to learn a bit about how CakePHP’s directory structure works: check out the CakePHP
Folder Structure section.

Directory Permissions on tmp and logs
The tmp and logs directories need to have proper permissions to be writable by your webserver. If you used Composer
for the install, this should have been done for you and confirmed with a “Permissions set on <folder>” message. If you
instead got an error message or want to do it manually, the best way would be to find out what user your webserver runsas (<?= `whoami`; ?>) and change the ownership of these two directories to that user. The final command you run(in *nix) might look something like this:chown -R www-data tmp
chown -R www-data logs
If for some reason CakePHP can’t write to these directories, you’ll be informed by a warning while not in production
mode.
While not recommended, if you are unable to set the permissions to the same as your webserver, you can simply set
write permissions on the folder by running a command such as:
chmod -R 777 tmp
chmod -R 777 logs

Blog Tutorial

151

CakePHP Book, Release 3.10

Creating the Blog Database
Next, let’s set up the underlying MySQL database for our blog. If you haven’t already done so, create an empty databasefor use in this tutorial, with a name of your choice, e.g. cake_blog. Right now, we’ll just create a single table to store
our articles. We’ll also throw in a few articles to use for testing purposes. Execute the following SQL statements into
your database:# First, create our articles table
CREATE TABLE articles (id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(50),body TEXT,
created DATETIME DEFAULT NULL,
modified DATETIME DEFAULT NULL);
# Then insert some articles for testing:
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());
The choices on table and column names are not arbitrary. If you follow CakePHP’s database naming conventions, and
CakePHP’s class naming conventions (both outlined in CakePHP Conventions), you’ll be able to take advantage of alot of free functionality and avoid configuration. CakePHP is flexible enough to accommodate even inconsistent legacy
database schemas, but adhering to the conventions will save you time.
Check out CakePHP Conventions for more information, but it’s suffice to say that naming our table ‘articles’ automatically hooks it to our Articles model, and having fields called ‘modified’ and ‘created’ will be automatically managed
by CakePHP.

Database Configuration
Next, let’s tell CakePHP where our database is and how to connect to it. For many, this will be the first and last time
you will need to configure anything.
The configuration should be pretty straightforward: just replace the values in the Datasources.default array in theconfig/app.php file with those that apply to your setup. A sample completed configuration array might look something
like the following:
return [// More configuration above.
'Datasources' => ['default' => ['className' => 'Cake\Database\Connection','driver' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'localhost','username' => 'cake_blog','password' => 'AngelF00dC4k3~','database' => 'cake_blog','encoding' => 'utf8',(continues on next page)

152

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)'timezone' => 'UTC'],],// More configuration below.
];
Once you’ve saved your config/app.php file, you should be able to open your browser and see the CakePHP welcome
page. It should also tell you that your database connection file was found, and that CakePHP can successfully connect
to the database.
Note: A copy of CakePHP’s default configuration file is found in config/app.default.php.

Optional Configuration
There are a few other items that can be configured. Most developers complete these laundry-list items, but they’re notrequired for this tutorial. One is defining a custom string (or “salt”) for use in security hashes.
The security salt is used for generating hashes. If you used Composer this too is taken care of for you during the install.
Else you’d need to change the default salt value by editing config/app.php. It doesn’t matter much what the new value
is, as long as it’s not guessable:'Security' => ['salt' => 'something long and containing lots of different values.',],

A Note on mod_rewrite
Occasionally new users will run into mod_rewrite issues. For example if the CakePHP welcome page looks a little
funny (no images or CSS styles). This probably means mod_rewrite is not functioning on your system. Please refer tothe URL Rewriting section to help resolve any issues you are having.
Now continue to Blog Tutorial - Part 2 to start building your first CakePHP application.

Blog Tutorial - Part 2
Create an Article Model
Models are the bread and butter of CakePHP applications. By creating a CakePHP model that will interact with our
database, we’ll have the foundation in place needed to do our view, add, edit, and delete operations later.
CakePHP’s model class files are split between Table and Entity objects. Table objects provide access to the collection of entities stored in a specific table and go in src/Model/Table. The file we’ll be creating will be saved tosrc/Model/Table/ArticlesTable.php. The completed file should look like this:// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;(continues on next page)

Blog Tutorial - Part 2

153

CakePHP Book, Release 3.10

(continued from previous page)use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp');}}
Naming conventions are very important in CakePHP. By naming our Table object ArticlesTable, CakePHP canautomatically infer that this Table object will be used in the ArticlesController, and will be tied to a database tablecalled articles.
Note:
CakePHP will dynamically create a model object for you if it cannot find a corresponding file insrc/Model/Table. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.
For more on models, such as callbacks, and validation, check out the Database Access & ORM chapter of the Manual.
Note: If you completed Part 1 of the Blog Tutorial and created the articles table in our Blog database you canleverage CakePHP’s bake console and its code generation capabilities to create the ArticlesTable model:
bin/cake bake model Articles

For more on bake and its code generation features please visit /bake/usage.

Create the Articles Controller
Next, we’ll create a controller for our articles. The controller is where all interaction with articles will happen. In anutshell, it’s the place where you play with the business logic contained in the models and get work related to articles
done. We’ll place this new controller in a file called ArticlesController.php inside the src/Controller directory. Here’s
what the basic controller should look like:// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{}
Now, let’s add an action to our controller. Actions often represent a single function or interface in an application. For
example, when users request www.example.com/articles/index (which is also the same as www.example.com/articles/),
they might expect to see a listing of articles. The code for that action would look like this:// src/Controller/ArticlesController.php
namespace App\Controller;(continues on next page)

154

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)class ArticlesController extends AppController{
public function index(){$articles = $this->Articles->find('all');$this->set(compact('articles'));}}By defining function index() in our ArticlesController, users can now access the logic there by requestingwww.example.com/articles/index. Similarly, if we were to define a function called foobar(), users would be able toaccess that at www.example.com/articles/foobar.
Warning: You may be tempted to name your controllers and actions a certain way to obtain a certain URL.
Resist that temptation. Follow CakePHP Conventions (capitalization, plural names, etc.) and create readable,
understandable action names. You can map URLs to your code using Routing covered later on.
The single instruction in the action uses set() to pass data from the controller to the view (which we’ll create next). Theline sets the view variable called ‘articles’ equal to the return value of the find('all') method of the ArticlesTable
object.
Note: If you completed Part 1 of the Blog Tutorial and created the articles table in your Blog database you canleverage CakePHP’s bake console and its code generation capabilities to create the ArticlesController class:bin/cake bake controller Articles

For more on bake and its code generation features please visit /bake/usage.
To learn more about CakePHP’s controllers, check out the Controllers chapter.

Creating Article Views
Now that we have our data flowing from our model, and our application logic is defined by our controller, let’s create
a view for the index action we created above.
CakePHP views are just presentation-flavored fragments that fit inside an application’s layout. For most applications,they’re HTML mixed with PHP, but they may end up as XML, CSV, or even binary data.
A layout is presentation code that is wrapped around a view. Multiple layouts can be defined, and you can switch
between them, but for now, let’s just use the default.
Remember in the last section how we assigned the ‘articles’ variable to the view using the set() method? That would
hand down the query object collection to the view to be invoked with a foreach iteration.
CakePHP’s template files are stored in src/Template inside a folder named after the controller they correspond to (we’ll
have to create a folder named ‘Articles’ in this case). To format this article data in a nice table, our view code mightlook something like this:<!-- File: src/Template/Articles/index.ctp -->(continues on next page)

Blog Tutorial - Part 2

155

CakePHP Book, Release 3.10

(continued from previous page)<h1>Blog articles</h1><table><tr><th>Id</th><th>Title</th><th>Created</th></tr><!-- Here is where we iterate through our $articles query object, printing out␣
article info -->˓→<?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>Hopefully this should look somewhat simple.
You might have noticed the use of an object called $this->Html. This is an instance of the CakePHP Cake\View\
Helper\HtmlHelper class. CakePHP comes with a set of view helpers that make things like linking, form output
a snap. You can learn more about how to use them in Helpers, but what’s important to note here is that the link()
method will generate an HTML link with the given title (the first parameter) and URL (the second parameter).
When specifying URLs in CakePHP, it is recommended that you use the array format. This is explained in more detailin the section on Routes. Using the array format for URLs allows you to take advantage of CakePHP’s reverse routing
capabilities. You can also specify URLs relative to the base of the application in the form of /controller/action/
param1/param2 or use named routes.
At this point, you should be able to point your browser to http://www.example.com/articles/index. You should see yourview, correctly formatted with the title and table listing of the articles.
If you happened to have clicked on one of the links we created in this view (that link a article’s title to a URL /articles/view/some\_id), you were probably informed by CakePHP that the action hasn’t yet been defined. If you
were not so informed, either something has gone wrong, or you actually did define it already, in which case you arevery sneaky. Otherwise, we’ll create it in the ArticlesController now:// src/Controller/ArticlesController.php
namespace App\Controller;class ArticlesController extends AppController{
public function index(){$this->set('articles', $this->Articles->find('all'));}(continues on next page)

156

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)

public function view($id = null){$article = $this->Articles->get($id);$this->set(compact('article'));}}The set() call should look familiar. Notice we’re using get() rather than find('all') because we only really wanta single article’s information.
Notice that our view action takes a parameter: the ID of the article we’d like to see. This parameter is handed to theaction through the requested URL. If a user requests /articles/view/3, then the value ‘3’ is passed as $id.
We also do a bit of error checking to ensure a user is actually accessing a record. By using the get() function in the
Articles table, we make sure the user has accessed a record that exists. In case the requested article is not present in the
database, or the id is false the get() function will throw a NotFoundException.
Now let’s create the view for our new ‘view’ action and place it in src/Template/Articles/view.ctp<!-- File: src/Template/Articles/view.ctp --><h1><?= h($article->title) ?></h1><p><?= h($article->body) ?></p><p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p>
Verify that this is working by trying the links at /articles/index or manually requesting an article by accessing/articles/view/{id}, replacing {id} by an article ‘id’.

Adding Articles
Reading from the database and showing us the articles is a great start, but let’s allow for the adding of new articles.
First, start by creating an add() action in the ArticlesController:// src/Controller/ArticlesController.php
namespace App\Controller;
use App\Controller\AppController;class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Flash'); // Include the FlashComponent}
public function index(){$this->set('articles', $this->Articles->find('all'));(continues on next page)

Blog Tutorial - Part 2

157

CakePHP Book, Release 3.10

(continued from previous page)}
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')) {// Prior to 3.4.0 $this->request->data() was used.
$article = $this->Articles->patchEntity($article, $this->request->getData());
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);}}

Note: You need to include the Flash component in any controller where you will use it. If necessary, include it inyour AppController.
Here’s what the add() action does: if the HTTP method of the request was POST, try to save the data using the Articles
model. If for some reason it doesn’t save, just render the view. This gives us a chance to show the user validation errors
or other warnings.
Every CakePHP request includes a ServerRequest object which is accessible using $this->request. The request
object contains useful information regarding the request that was just received, and can be used to control the flow ofyour application. In this case, we use the Cake\Http\ServerRequest::is() method to check that the request is a
HTTP POST request.
When a user uses a form to POST data to your application, that information is available in$this->request->getData() ( Or $this->request->data() for CakePHP v3.3 and under ). You can use
the pr() or debug() functions to print it out if you want to see what it looks like.
We use FlashComponent’s success() and error() methods to set a message to a session variable. These methods
are provided using PHP’s magic method features57 . Flash messages will be displayed on the page after redirection.
In the layout we have <?= $this->Flash->render() ?> which displays the message and clears the corresponding
session variable. The controller’s Cake\Controller\Controller::redirect function redirects to another URL.
The param ['action' => 'index'] translates to URL /articles i.e the index action of the ArticlesController.
You can refer to Cake\Routing\Router::url() function on the API58 to see the formats in which you can specify
a URL for various CakePHP functions.
Calling the save() method will check for validation errors and abort the save if any occur. We’ll discuss how thoseerrors are handled in the following sections.
57 https://php.net/manual/en/language.oop5.overloading.php#object.call
58 https://api.cakephp.org

158

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Data Validation
CakePHP goes a long way toward taking the monotony out of form input validation. Everyone hates coding up endlessforms and their validation routines. CakePHP makes it easier and faster.
To take advantage of the validation features, you’ll need to use CakePHP’s Form helper in your views. The Cake\
View\Helper\FormHelper is available by default to all views at $this->Form.
Here’s our add view:<!-- File: src/Template/Articles/add.ctp --><h1>Add Article</h1><?php
echo $this->Form->create($article);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>
We use the FormHelper to generate the opening tag for an HTML form.
$this->Form->create() generates:

Here’s the HTML that<form method="post" action="/articles/add">
If create() is called with no parameters supplied, it assumes you are building a form that submits via POST to thecurrent controller’s add() action (or edit() action when id is included in the form data).
The $this->Form->control() method is used to create form elements of the same name. The first parameter tells
CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options in this case, the number of rows for the textarea. There’s a bit of introspection and automagic here: control() will
output different form elements based on the model field specified.
The $this->Form->end() call ends the form. Outputting hidden inputs if CSRF/Form Tampering prevention isenabled.
Now let’s go back and update our src/Template/Articles/index.ctp view to include a new “Add Article” link. Before
the <table>, add the following line:<?= $this->Html->link('Add Article', ['action' => 'add']) ?>You may be wondering: how do I tell CakePHP about my validation requirements? Validation rules are defined in themodel. Let’s look back at our Articles model and make a few adjustments:// 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){(continues on next page)

Blog Tutorial - Part 2

159

CakePHP Book, Release 3.10

(continued from previous page)$this->addBehavior('Timestamp');}public function validationDefault(Validator $validator){$validator->notEmpty('title')->requirePresence('title')->notEmpty('body')->requirePresence('body');
return $validator;}}
The validationDefault() method tells CakePHP how to validate your data when the save() method is called.
Here, we’ve specified that both the body and title fields must not be empty, and are required for both create and update operations. CakePHP’s validation engine is strong, with a number of pre-built rules (credit card numbers, email
addresses, etc.) and flexibility for adding your own validation rules. For more information on that setup, check the
Validation documentation.
Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how
it works. Since we’ve used the Cake\View\Helper\FormHelper::control() method of the FormHelper to create
our form elements, our validation error messages will be shown automatically.

Editing Articles
Post editing: here we go. You’re a CakePHP pro by now, so you should have picked up a pattern. Make the action, thenthe view. Here’s what the edit() action of the ArticlesController would look like:// src/Controller/ArticlesController.php
public function edit($id = null){$article = $this->Articles->get($id);
if ($this->request->is(['post', 'put'])) {// Prior to 3.4.0 $this->request->data() was used.
$this->Articles->patchEntity($article, $this->request->getData());
if ($this->Articles->save($article)) {$this->Flash->success(__('Your article has been updated.'));
return $this->redirect(['action' => 'index']);}$this->Flash->error(__('Unable to update your article.'));}$this->set('article', $article);}This action first ensures that the user has tried to access an existing record. If they haven’t passed in an $id parameter,or the article does not exist, we throw a NotFoundException for the CakePHP ErrorHandler to take care of.
Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST data to
update our article entity by using the patchEntity() method. Finally we use the table object to save the entity back160

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

or kick back and show the user validation errors.
The edit view might look something like this:<!-- File: src/Template/Articles/edit.ctp --><h1>Edit Article</h1><?php
echo $this->Form->create($article);echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();?>This view outputs the edit form (with the values populated), along with any necessary validation error messages.
CakePHP will determine whether a save() generates an insert or an update statement based on the state of the entity.
You can now update your index view with links to edit specific articles:<!-- File: src/Template/Articles/index.ctp(edit links added) --><h1>Blog articles</h1><p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p><table><tr><th>Id</th><th>Title</th><th>Created</th><th>Action</th></tr><!-- Here's where we iterate through our $articles query object, printing out article␣
˓→info --><?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('Edit', ['action' => 'edit', $article->id]) ?>
</td>
</tr>
<?php endforeach; ?></table>Blog Tutorial - Part 2

161

CakePHP Book, Release 3.10

Deleting Articles
Next, let’s make a way for users to delete articles. Start with a delete() action in the ArticlesController:// 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(__('The article with id: {0} has been deleted.', h($id)));return $this->redirect(['action' => 'index']);}}This logic deletes the article specified by $id, and uses $this->Flash->success() to show the user a confirmation message after redirecting them on to /articles. If the user attempts to do a delete using a GET request, theallowMethod() will throw an Exception. Uncaught exceptions are captured by CakePHP’s exception handler, and anice error page is displayed. There are many built-in Exceptions that can be used to indicate the various HTTP errors
your application might need to generate.
Because we’re just executing some logic and redirecting, this action has no view. You might want to update your index
view with links that allow users to delete articles, however:<!-- File: src/Template/Articles/index.ctp (delete links added) --><h1>Blog articles</h1><p><?= $this->Html->link('Add Article', ['action' => 'add']) ?></p><table><tr><th>Id</th><th>Title</th><th>Created</th><th>Actions</th></tr><!-- Here's where we loop through our $articles query object, printing out article info ˓→-><?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('Delete',['action' => 'delete', $article->id],(continues on next page)

162

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)['confirm' => 'Are you sure?'])?><?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
</td>
</tr>
<?php endforeach; ?></table>Using postLink() will create a link that uses JavaScript to do a POST request deleting our article.
Warning: Allowing content to be deleted using GET requests is dangerous, as web crawlers could accidentally
delete all your content.

Note: This view code also uses the FormHelper to prompt the user with a JavaScript confirmation dialog before theyattempt to delete an article.

RoutesFor some, CakePHP’s default routing works well enough. Developers who are sensitive to user-friendliness and generalsearch engine compatibility will appreciate the way that CakePHP’s URLs map to specific actions. So we’ll just makea quick change to routes in this tutorial.
For more information on advanced routing techniques, see Connecting Routes.
By default, CakePHP responds to a request for the root of your site (e.g., http://www.example.com) using its
PagesController, rendering a view called “home”. Instead, we’ll replace this with our ArticlesController by creating
a routing rule.
CakePHP’s routing is found in config/routes.php. You’ll want to comment out or remove the line that defines thedefault root route. It looks like this:$routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);This line connects the URL ‘/’ with the default CakePHP home page. We want it to connect with our own controller,
so replace that line with this one:$routes->connect('/', ['controller' => 'Articles', 'action' => 'index']);This should connect users requesting ‘/’ to the index() action of our ArticlesController.
Note: CakePHP also makes use of ‘reverse routing’. If, with the above route defined, you pass ['controller'=> 'Articles', 'action' => 'index'] to a function expecting an array, the resulting URL used will be ‘/’. It’s
therefore a good idea to always use arrays for URLs as this means your routes define where a URL goes, and also
ensures that links point to the same place.

Blog Tutorial - Part 2163

CakePHP Book, Release 3.10

Conclusion
Keep in mind that this tutorial was very basic. CakePHP has many more features to offer, and is flexible in ways wedidn’t wish to cover here for simplicity’s sake. Use the rest of this manual as a guide for building more feature-richapplications.
Now that you’ve created a basic CakePHP application, you can either continue to Blog Tutorial - Part 3, or start yourown project. You can also peruse the /topics or API59 to learn more about CakePHP.
If you need help, there are many ways to get the help you need - please see the Where to Get Help page. Welcome to
CakePHP!
Suggested Follow-up Reading
These are common tasks people learning CakePHP usually want to study next:
1. Layouts: Customizing your website layout
2. Elements: Including and reusing view snippets
3. /bake/usage: Generating basic CRUD code
4. Blog Tutorial - Authentication and Authorization: User authentication and authorization tutorial

Blog Tutorial - Part 3
Create a Tree Category
Let’s continue our blog application and imagine we want to categorize our articles. We want the categories to beordered, and for this, we will use the Tree behavior to help us organize the categories.
But first, we need to modify our tables.

Migrations Plugin
We will use the migrations plugin60 to create a table in our database. If you already have an articles table in yourdatabase, erase it.
Now open your application’s composer.json file. Normally you would see that the migrations plugin is already underrequire. If not, add it by executing:composer require cakephp/migrations:~1.0
The migrations plugin will now be in your application’s plugins$this->addPlugin('Migrations'); to your application’s bootstrap method.

folder.

Also,

add

Once the plugin is loaded, run the following command to create a migration file:bin/cake bake migration CreateArticles title:string body:text category_id:integer␣˓→created modified
A migration file will be generated in the /config/Migrations folder with the following:
59 https://api.cakephp.org
60 https://github.com/cakephp/migrations

164

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10<?php
use Migrations\AbstractMigration;
class CreateArticles 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();}}Run another command to create a categories table. If you need to specify a field length, you can do it within brackets
in the field type, ie:bin/cake bake migration CreateCategories parent_id:integer lft:integer[10]␣
˓→rght:integer[10] name:string[100] description:string created modified
This will generate the following file in config/Migrations:<?php
use Migrations\AbstractMigration;
class CreateCategories extends AbstractMigration{
public function change(){$table = $this->table('categories');$table->addColumn('parent_id', 'integer', [(continues on next page)

Blog Tutorial - Part 3165

CakePHP Book, Release 3.10

(continued from previous page)'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();}}Now that the migration files are created, you can edit them before creating your tables. We need to change the 'null'=> false for the parent_id field with 'null' => true because a top-level category has a null parent_id.
Run the following command to create your tables:
bin/cake migrations migrate

166

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Modifying the Tables
With our tables set up, we can now focus on categorizing our articles.
We suppose you already have the files (Tables, Controllers and Templates of Articles) from part 2. So we’ll just add
the references to categories.
We need to associate the Articles and Categories tables together. Open the src/Model/Table/ArticlesTable.php fileand add the following:// 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',]);}}

Generate Skeleton Code for Categories
Create all files by launching bake commands:
bin/cake bake model Categories
bin/cake bake controller Categories
bin/cake bake template Categories
Alternatively, you can bake all with just one line:
bin/cake bake all Categories
The bake tool has created all your files in a snap. You can give them a quick read if you want re-familiarize yourself
with how CakePHP works.
Note: If you are on Windows remember to use \ instead of /.
You’ll need to edit the following in src/Template/Categories/add.ctp and src/Template/Categories/edit.ctp:
echo $this->Form->control('parent_id', ['options' => $parentCategories,'empty' => 'No parent category']);

Blog Tutorial - Part 3167

CakePHP Book, Release 3.10

Attach TreeBehavior to CategoriesTable
The TreeBehavior helps you manage hierarchical Tree structures in database table. It uses the MPTT logic61 to manage
the data. MPTT tree structures are optimized for reads, which often makes them a good fit for read heavy applications
like blogs.
If you open the src/Model/Table/CategoriesTable.php file, you’ll see that the TreeBehavior has been attached to yourCategoriesTable in the initialize() method. Bake adds this behavior to any Tables that contain lft and rght
columns:$this->addBehavior('Tree');With the TreeBehavior attached you’ll be able to access some features like reordering the categories. We’ll see that ina moment.
But for now, you have to remove the following controls in your Categories add and edit template files:
echo $this->Form->control('lft');echo $this->Form->control('rght');
In addition you should disable or remove the requirePresence from the validator for both the lft and rght columns inyour CategoriesTable model:
public function validationDefault(Validator $validator){$validator->add('id', 'valid', ['rule' => 'numeric'])->allowEmptyString('id', 'create');$validator->add('lft', 'valid', ['rule' => 'numeric'])//->requirePresence('lft', 'create')->notEmpty('lft');$validator->add('rght', 'valid', ['rule' => 'numeric'])//->requirePresence('rght', 'create')->notEmpty('rght');}
These fields are automatically managed by the TreeBehavior when a category is saved.
Using your web browser, add some new categories using the /yoursite/categories/add controller action.
61 https://www.sitepoint.com/hierarchical-data-database-2/

168

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Reordering Categories with TreeBehavior
In your categories index template file, you can list the categories and re-order them.
Let’s modify the index method in your CategoriesController.php and add moveUp() and moveDown() methods to beable to reorder the categories in the tree: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']));}}
In src/Template/Categories/index.ctp replace the existing content with:<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">(continues on next page)

Blog Tutorial - Part 3

169

CakePHP Book, Release 3.10

(continued from previous page)<thead><tr><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˓→>id], ['confirm' => __('Are you sure you want to delete # {0}?', $category->id)]) ?><?= $this->Form->postLink(__('Move down'), ['action' => 'moveDown',
˓→$category->id], ['confirm' => __('Are you sure you want to move down # {0}?',˓→$category->id)]) ?><?= $this->Form->postLink(__('Move up'), ['action' => 'moveUp',
˓→$category->id], ['confirm' => __('Are you sure you want to move up # {0}?', $category->
˓→id)]) ?>
</td>
</tr>
<?php endforeach; ?></tbody></table></div>

Modifying the ArticlesController
In our ArticlesController, we’ll get the list of all the categories. This will allow us to choose a category for an
Article when creating or editing it:// src/Controller/ArticlesController.php
namespace App\Controller;// Prior to 3.6 use Cake\Network\Exception\NotFoundException
use Cake\Http\Exception\NotFoundException;(continues on next page)

170

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)class ArticlesController extends AppController{// ...
public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {// Prior to 3.4.0 $this->request->data() was used.
$article = $this->Articles->patchEntity($article, $this->request->getData());
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'));}}Modifying the Articles Templates
The article add file should look something like this:<!-- File: src/Template/Articles/add.ctp --><h1>Add Article</h1><?php
echo $this->Form->create($article);// just added the categories control
echo $this->Form->control('category_id');echo $this->Form->control('title');echo $this->Form->control('body', ['rows' => '3']);echo $this->Form->button(__('Save Article'));echo $this->Form->end();
When you go to the address /yoursite/categories/add you should see a list of categories to choose.

Blog Tutorial - Part 3

171

CakePHP Book, Release 3.10

Blog Tutorial - Authentication and Authorization
Following our Blog Tutorial example, imagine we wanted to secure access to certain URLs, based on the logged-in
user. We also have another requirement: to allow our blog to have multiple authors who can create, edit, and delete
their own articles while disallowing other authors from making changes to articles they do not own.

Creating All User-Related CodeFirst, let’s create a new table in our blog database to hold our users’ data:
CREATE TABLE users (id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50),
password VARCHAR(255),
role VARCHAR(20),created DATETIME DEFAULT NULL,
modified DATETIME DEFAULT NULL);
We have adhered to the CakePHP conventions in naming tables, but we’re also taking advantage of another convention:
By using the username and password columns in a users table, CakePHP will be able to auto-configure most things for
us when implementing the user login.
Next step is to create our UsersTable class, responsible for finding, saving and validating any user data:// 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', 'A username is required')->notEmpty('password', 'A password is required')->notEmpty('role', 'A role is required')->add('role', 'inList', ['rule' => ['inList', ['admin', 'author']],'message' => 'Please enter a valid role']);}}Let’s also create our UsersController. The following content corresponds to parts of a basic baked UsersController
class using the code generation utilities bundled with CakePHP:// src/Controller/UsersController.php
namespace App\Controller;(continues on next page)

172

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

(continued from previous page)use App\Controller\AppController;
use Cake\Event\Event;class UsersController extends AppController{
public function beforeFilter(Event $event){parent::beforeFilter($event);$this->Auth->allow('add');}
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')) {// Prior to 3.4.0 $this->request->data() was used.
$user = $this->Users->patchEntity($user, $this->request->getData());
if ($this->Users->save($user)) {$this->Flash->success(__('The user has been saved.'));
return $this->redirect(['action' => 'add']);}$this->Flash->error(__('Unable to add the user.'));}$this->set('user', $user);}}In the same way we created the views for our articles by using the code generation tool, we can implement the user
views. For the purpose of this tutorial, we will show just the add.ctp:<!-- src/Template/Users/add.ctp --><div class="users form"><?= $this->Form->create($user) ?><fieldset><legend><?= __('Add User') ?></legend><?= $this->Form->control('username') ?><?= $this->Form->control('password') ?><?= $this->Form->control('role', ['options' => ['admin' => 'Admin', 'author' => 'Author'](continues on next page)

Blog Tutorial - Authentication and Authorization

173

CakePHP Book, Release 3.10

(continued from previous page)]) ?></fieldset><?= $this->Form->button(__('Submit')); ?><?= $this->Form->end() ?></div>

Authentication (Login and Logout)
We’re now ready to add our authentication layer. In CakePHP this is handled by the Cake\Controller\Component\
AuthComponent, a class responsible for requiring login for certain actions, handling user login and logout, and also
authorizing logged-in users to the actions they are allowed to reach.
To add this component to your application open your src/Controller/AppController.php file and add the following
lines:// 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']);
}
//...
}
There is not much to configure, as we used the conventions for the users table. We just set up the URLs that will be
loaded after the login and logout actions is performed, in our case to /articles/ and / respectively.
What we did in the beforeFilter() function was to tell the AuthComponent to not require a login for all index()
174

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

and view() actions, in every controller. We want our visitors to be able to read and list the entries without registeringin the site.
Now, we need to be able to register new users, save their username and password, and more importantly, hash theirpassword so it is not stored as plain text in our database. Let’s tell the AuthComponent to let un-authenticated users
access the users add function and implement the login and logout action:// src/Controller/UsersController.php
namespace App\Controller;
use App\Controller\AppController;
use Cake\Event\Event;class UsersController extends AppController{// Other methods..
public function beforeFilter(Event $event){parent::beforeFilter($event);// Allow users to register and logout.
// You should not add the "login" action to allow list. Doing so would// cause problems with normal functioning of 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(__('Invalid username or password, try again'));}}public function logout(){
return $this->redirect($this->Auth->logout());}}
Password hashing is not done yet, we need an Entity class for our User in order to handle its own specific logic. Create
the src/Model/Entity/User.php entity file and add the following:// src/Model/Entity/User.php
namespace App\Model\Entity;
use Cake\Auth\DefaultPasswordHasher;use Cake\ORM\Entity;class User extends Entity(continues on next page)

Blog Tutorial - Authentication and Authorization

175

CakePHP Book, Release 3.10

(continued from previous page){// Make all fields mass assignable except for primary key field "id".
protected $_accessible = ['*' => true,'id' => false];// ...
protected function _setPassword($password){
if (strlen($password) > 0) {return (new DefaultPasswordHasher)->hash($password);}}// ...
}
Now every time the password property is assigned to the user it will be hashed using the DefaultPasswordHasherclass. We’re just missing a template view file for the login function. Open up your src/Template/Users/login.ctp fileand add the following lines:<!-- File: src/Template/Users/login.ctp --><div class="users form"><?= $this->Flash->render() ?><?= $this->Form->create() ?><fieldset><legend><?= __('Please enter your username and password') ?></legend><?= $this->Form->control('username') ?><?= $this->Form->control('password') ?></fieldset><?= $this->Form->button(__('Login')); ?><?= $this->Form->end() ?></div>
You can now register a new user by accessing the /users/add URL and log in with the newly created credentials bygoing to /users/login URL. Also, try to access any other URL that was not explicitly allowed such as /articles/
add, you will see that the application automatically redirects you to the login page.
And that’s it! It looks too simple to be true. Let’s go back a bit to explain what happened. The beforeFilter()function is telling the AuthComponent to not require a login for the add() action in addition to the index() andview() actions that were already allowed in the AppController’s beforeFilter() function.
The login() action calls the $this->Auth->identify() function in the AuthComponent, and it works without any
further config because we are following conventions as mentioned earlier. That is, having a Users table with a username
and a password column, and use a form posted to a controller with the user data. This function returns whether thelogin was successful or not, and in the case it succeeds, then we redirect the user to the configured redirection URL
that we used when adding the AuthComponent to our application.
The logout works by just accessing the /users/logout URL and will redirect the user to the configured logoutUrlformerly described. This URL is the result of the AuthComponent::logout() function on success.

176

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

Authorization (who’s allowed to access what)
As stated before, we are converting this blog into a multi-user authoring tool, and in order to do this, we need to modify
the articles table a bit to add the reference to the Users table:
ALTER TABLE articles ADD COLUMN user_id INT(11);Also, a small change in the ArticlesController is required to store the currently logged in user as a reference for thecreated article:// src/Controller/ArticlesController.php
public function add(){$article = $this->Articles->newEntity();if ($this->request->is('post')) {// Prior to 3.4.0 $this->request->data() was used.
$article = $this->Articles->patchEntity($article, $this->request->getData());// Added this line
$article->user_id = $this->Auth->user('id');// You could also do the following//$newData = ['user_id' => $this->Auth->user('id')];//$article = $this->Articles->patchEntity($article, $newData);
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'));}The user() function provided by the component returns any column from the currently logged in user. We used thismethod to add the data into the request info that is saved.
Let’s secure our app to prevent some authors from editing or deleting the others’ articles. Basic rules for our app arethat admin users can access every URL, while normal users (the author role) can only access the permitted actions.
Again, open the AppController class and add a few more options to the Auth config:// src/Controller/AppController.php
public function initialize(){$this->loadComponent('Flash');$this->loadComponent('Auth', ['authorize' => ['Controller'], // Added this line
'loginRedirect' => ['controller' => 'Articles','action' => 'index'(continues on next page)

Blog Tutorial - Authentication and Authorization

177

CakePHP Book, Release 3.10

(continued from previous page)],'logoutRedirect' => ['controller' => 'Pages','action' => 'display','home']]);}
public function isAuthorized($user){// Admin can access every action
if (isset($user['role']) && $user['role'] === 'admin') {return true;}// Default denyreturn false;}
We just created a simple authorization mechanism. Users with the admin role will be able to access any URL in thesite when logged-in. All other users – those with the author role – will have the same access as users who aren’tlogged-in.
This is not exactly what we want. We need to supply more rules to our isAuthorized() method. However insteadof doing it in AppController, we’ll delegate supplying those extra rules to each individual controller. The rules we’regoing to add to ArticlesController should permit authors to create articles but prevent authors from editing articles they
do not own. Add the following content to your ArticlesController.php:// src/Controller/ArticlesController.php
public function isAuthorized($user){// All registered users can add articles// Prior to 3.4.0 $this->request->param('action') was used.
if ($this->request->getParam('action') === 'add') {return true;}// The owner of an article can edit and delete it// Prior to 3.4.0 $this->request->param('action') was used.
if (in_array($this->request->getParam('action'), ['edit', 'delete'])) {// Prior to 3.4.0 $this->request->params('pass.0')$articleId = (int)$this->request->getParam('pass.0');
if ($this->Articles->isOwnedBy($articleId, $user['id'])) {return true;}}
return parent::isAuthorized($user);}
We’re now overriding the AppController’s isAuthorized() call and internally checking if the parent class is already178

Chapter 4. Tutorials & Examples

CakePHP Book, Release 3.10

authorizing the user. If he isn’t, then just allow him to access the add action, and conditionally access edit and delete.
One final thing has not been implemented. To tell whether or not the user is authorized to edit the article, we’re callinga isOwnedBy() function in the Articles table. Let’s then implement that function:// src/Model/Table/ArticlesTable.php
public function isOwnedBy($articleId, $userId){
return $this->exists(['id' => $articleId, 'user_id' => $userId]);}
This concludes our simple authentication and authorization tutorial. For securing the UsersController you can follow
the same technique we did for ArticlesController. You could also be more creative and code something more generalin AppController based on your own rules.
Should you need more control, we suggest you read the complete Auth guide in the AuthComponent section where you
will find more about configuring the component, creating custom Authorization classes, and much more.
Suggested Follow-up Reading
1. /bake/usage Generating basic CRUD code
2. AuthComponent: User registration and login

Blog Tutorial - Authentication and Authorization

179

CakePHP Book, Release 3.10

180Chapter 4. Tutorials & Examples

CHAPTER 5

Contributing

There are a number of ways you can contribute to CakePHP. The following sections cover the various ways you cancontribute to CakePHP:

Documentation
Contributing to the documentation is simple. The files are hosted on https://github.com/cakephp/docs. Feel free tofork the repo, add your changes/improvements/translations and give back by issuing a pull request. You can even edit
the docs online with GitHub, without ever downloading the files – the “Improve this Doc” button on any given page
will direct you to GitHub’s online editor for that page.
CakePHP documentation is continuously integrated62 , and deployed after each pull request is merged.

Translations
Email the docs team (docs at cakephp dot org) or hop on IRC (#cakephp on freenode) to discuss any translation efforts
you would like to participate in.
62 https://en.wikipedia.org/wiki/Continuous_integration

181

CakePHP Book, Release 3.10

New Translation Language
We want to provide translations that are as complete as possible. However, there may be times where a translation fileis not up-to-date. You should always consider the English version as the authoritative version.
If your language is not in the current languages, please contact us through Github and we will consider creating askeleton folder for it. The following sections are the first one you should consider translating as these files don’t change
often:• index.rst• intro.rst• quickstart.rst• installation.rst• /intro folder• /tutorials-and-examples folder
Reminder for Docs Administrators
The structure of all language folders should mirror the English folder structure. If the structure changes for the English
version, we should apply those changes in the other languages.
For example, if a new English file is created in en/file.rst, we should:• Add the file in all other languages : fr/file.rst, zh/file.rst, . . .
• Delete the content, but keeping the title, meta information and eventual toc-tree elements. The following
note will be added while nobody has translated the file:
File Title##########.. note::The documentation is not currently supported in XX language for thispage.
Please feel free to send us a pull request on`Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**button to directly propose your changes.
You can refer to the English version in the select top menu to haveinformation about this page's topic.
// If toc-tree elements are in the English version.. toctree:::maxdepth: 1
one-toc-fileother-toc-file.. meta:::title lang=xx: File Title:keywords lang=xx: title, description,...

182

Chapter 5. Contributing

CakePHP Book, Release 3.10

Translator tips
• Browse and edit in the language you want the content to be translated to - otherwise you won’t see what has
already been translated.
• Feel free to dive right in if your chosen language already exists on the book.
• Use Informal Form63 .
• Translate both the content and the title at the same time.
• Do compare to the English content before submitting a correction (if you correct something, but don’t integratean ‘upstream’ change your submission won’t be accepted).
• If you need to write an English term, wrap it in <em> tags. E.g. “asdf asdf Controller asdf” or “asdf asdf
Kontroller (Controller) asfd” as appropriate.
• Do not submit partial translations.
• Do not edit a section with a pending change.
• Do not use HTML entities64 for accented characters, the book uses UTF-8.
• Do not significantly change the markup (HTML) or add new content.
• If the original content is missing some info, submit an edit for that first.

Documentation Formatting Guide
The new CakePHP documentation is written with ReST formatted text65 . ReST (Re Structured Text) is a plain text
markup syntax similar to markdown, or textile. To maintain consistency it is recommended that when adding to the
CakePHP documentation you follow the guidelines here on how to format and structure your text.
Line Length
Lines of text should be wrapped at 80 columns. The only exception should be long URLs, and code snippets.
Headings and Sections
Section headers are created by underlining the title with punctuation characters at least the length of the text.
• # Is used to denote page titles.
• = Is used for sections in a page.
• - Is used for subsections.
• ~ Is used for sub-subsections.
• ^ Is used for sub-sub-subsections.
Headings should not be nested more than 5 levels deep. Headings should be preceded and followed by a blank line.
63 https://en.wikipedia.org/wiki/Register_(linguistics)
64 https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
65 https://en.wikipedia.org/wiki/ReStructuredText

Documentation

183

CakePHP Book, Release 3.10

Paragraphs
Paragraphs are simply blocks of text, with all the lines at the same level of indentation. Paragraphs should be separated
by one blank line.
Inline Markup• One asterisk: text for emphasis (italics) We’ll use it for general highlighting/emphasis.
– *text*.
• Two asterisks: text for strong emphasis (boldface) We’ll use it for working directories, bullet list subject, tablenames and excluding the following word “table”.
– **/config/Migrations**, **articles**, etc.
• Two backquotes: text for code samples We’ll use it for names of method options, names of table columns,
object names, excluding the following word “object” and for method/function names – include “()”.
– ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, etc.
If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to beescaped with a backslash.
Inline markup has a few restrictions:• It may not be nested.
• Content may not start or end with whitespace: * text* is wrong.
• Content must be separated from surrounding text by non-word characters. Use a backslash escaped space towork around that: onelong\ *bolded*\ word.
Lists
List markup is very similar to markdown. Unordered lists are indicated by starting a line with a single asterisk and aspace. Numbered lists can be created with either numerals, or # for auto numbering:* This is a bullet* So is this. But this line
has two lines.
1. First line
2. Second line#. Automatic numbering#. Will save you some time.
Indented lists can also be created, by indenting sections and separating them with an empty line:* First line
* Second line
* Going deeper* Whoah* Back to the first level.

184

Chapter 5. Contributing

CakePHP Book, Release 3.10

Definition lists can be created by doing the following:
term
definition
CakePHP
An MVC framework for PHP
Terms cannot be more than one line, but definitions can be multi-line and all lines should be indented consistently.
Links
There are several kinds of links, each with their own uses.
External Links
Links to external documents can be done with the following:`External Link to php.net <https://php.net>`_The resulting link would look like this: External Link to php.net66
Links to Other Pages:doc:
Other pages in the documentation can be linked to using the :doc: role. You can link to the specified document
using either an absolute or relative path reference. You should omit the .rst extension. For example, if the reference :doc:`form` appears in the document core-helpers/html, then the link references core-helpers/
form. If the reference was :doc:`/core-helpers`, it would always reference /core-helpers regardless of
where it was used.
Cross Referencing Links:ref:
You can cross reference any arbitrary title in any document using the :ref: role. Link label targets must be
unique across the entire documentation. When creating labels for class methods, it’s best to use class-method
as the format for your link label.
The most common use of labels is above a title. Example:.. _label-name:
Section heading--------------More content here.
Elsewhere you could reference the above section using :ref:`label-name`. The link’s text would be the title
that the link preceded. You can also provide custom link text using :ref:`Link text <label-name>`.
66 https://php.net

Documentation

185

CakePHP Book, Release 3.10

Prevent Sphinx to Output Warnings
Sphinx will output warnings if a file is not referenced in a toc-tree. It’s a great way to ensure that all files have a link
directed to them, but sometimes, you don’t need to insert a link for a file, eg. for our epub-contents and pdf-contents
files. In those cases, you can add :orphan: at the top of the file, to suppress warnings that the file is not in the toc-tree.
Describing Classes and their Contents
The CakePHP documentation uses the phpdomain67 to provide custom directives for describing PHP objects and constructs. Using these directives and roles is required to give proper indexing and cross referencing features.
Describing Classes and Constructs
Each directive populates the index, and or the namespace index.
.. php:global:: name
This directive declares a new PHP global variable.
.. php:function:: name(signature)
Defines a new global function outside of a class.
.. php:const:: name
This directive declares a new PHP constant, you can also use it nested inside a class directive to create classconstants.
.. php:exception:: name
This directive declares a new Exception in the current namespace. The signature can include constructor arguments.
.. php:class:: name
Describes a class. Methods, attributes, and constants belonging to the class should be inside this directive’s body:.. php:class:: MyClassClass description.. php:method:: method($argument)
Method description
Attributes, methods and constants don’t need to be nested. They can also just follow the class declaration:.. php:class:: MyClass
Text about the class.. php:method:: methodName()
Text about the method
See also:
php:method, php:attr, php:const
67 https://pypi.python.org/pypi/sphinxcontrib-phpdomain

186

Chapter 5. Contributing

CakePHP Book, Release 3.10.. php:method:: name(signature)
Describe a class method, its arguments, return value, and exceptions:.. php:method:: instanceMethod($one, $two):param string $one: The first parameter.
:param string $two: The second parameter.
:returns: An array of stuff.
:throws: InvalidArgumentException
This is an instance method.
.. php:staticmethod:: ClassName::methodName(signature)
Describe a static method, its arguments, return value and exceptions, see php:method for options.
.. php:attr:: name
Describe an property/attribute on a class.
Prevent Sphinx to Output Warnings
Sphinx will output warnings if a function is referenced in multiple files. It’s a great way to ensure that you did not add
a function two times, but sometimes, you actually want to write a function in two or more files, eg. debug object isreferenced in /development/debugging and in /core-libraries/global-constants-and-functions. In this case, you can add:noindex: under the function debug to suppress warnings. Keep only one reference without :no-index: to still
have the function referenced:.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true):noindex:

Cross Referencing
The following roles refer to PHP objects and links are generated if a matching directive is found::php:func:
Reference a PHP function.
:php:global:
Reference a global variable whose name has $ prefix.
:php:const:
Reference either a global constant, or a class constant. Class constants should be preceded by the owning class:
DateTime has an :php:const:`DateTime::ATOM` constant.
:php:class:
Reference a class by name::php:class:`ClassName`:php:meth:
Reference a method of a class. This role supports both kinds of methods:

Documentation

187

CakePHP Book, Release 3.10

:php:meth:`DateTime::setDate`:php:meth:`Classname::staticMethod`:php:attr:
Reference a property on an object::php:attr:`ClassName::$propertyName`:php:exc:
Reference an exception.
Source CodeLiteral code blocks are created by ending a paragraph with ::. The literal block must be indented, and like all paragraphs
be separated by single lines:
This is a paragraph::while ($i--) {doStuff()}
This is regular text again.
Literal text is not modified or formatted, save that one level of indentation is removed.
Notes and Warnings
There are often times when you want to inform the reader of an important tip, special note or a potential hazard.
Admonitions in sphinx are used for just that. There are fives kinds of admonitions.
• .. tip:: Tips are used to document or re-iterate interesting or important information. The content of thedirective should be written in complete sentences and include all appropriate punctuation.
• .. note:: Notes are used to document an especially important piece of information. The content of the directive should be written in complete sentences and include all appropriate punctuation.
• .. warning:: Warnings are used to document potential stumbling blocks, or information pertaining to security.
The content of the directive should be written in complete sentences and include all appropriate punctuation.
• .. versionadded:: X.Y.Z “Version added” admonitions are used to display notes specific to new features
added at a specific version, X.Y.Z being the version on which the said feature was added.
• .. deprecated:: X.Y.Z As opposed to “version added” admonitions, “deprecated” admonition are used to
notify of a deprecated feature, X.Y.Z being the version on which the said feature was deprecated.
All admonitions are made the same:.. note::Indented and preceded and followed by a blank line. Just like aparagraph.
This text is not part of the note.

188

Chapter 5. Contributing

CakePHP Book, Release 3.10

Samples

Tip: This is a helpful tid-bit you probably forgot.

Note: You should pay attention here.

Warning: It could be dangerous.
New in version 2.6.3: This awesome feature was added on version 2.6.3
Deprecated since version 2.6.3: This old feature was deprecated on version 2.6.3

Tickets
Getting feedback and help from the community in the form of tickets is an extremely important part of the CakePHP
development process. All of CakePHP’s tickets are hosted on GitHub68 .

Reporting Bugs
Well written bug reports are very helpful. There are a few steps to help create the best bug report possible:• Do: Please search69 for a similar existing ticket, and ensure someone hasn’t already reported your issue, or thatit hasn’t already been fixed in the repository.
• Do: Please include detailed instructions on how to reproduce the bug. This could be in the form of a test-caseor a snippet of code that demonstrates the issue. Not having a way to reproduce an issue means it’s less likely to
get fixed.
• Do: Please give as many details as possible about your environment: (OS, PHP version, CakePHP version).
• Don’t: Please don’t use the ticket system to ask support questions. The #cakephp IRC channel on Freenode70
has many developers available to help answer your questions. Also have a look at Stack Overflow71 .

Reporting Security Issues
If you’ve found a security issue in CakePHP, please use the following procedure instead of the normal bug reporting
system. Instead of using the bug tracker, mailing list or IRC please send an email to security [at] cakephp.org. Emails
sent to this address go to the CakePHP core team on a private mailing list.
For each report, we try to first confirm the vulnerability. Once confirmed, the CakePHP team will take the following
actions:• Acknowledge to the reporter that we’ve received the issue, and are working on a fix. We ask that the reporter
keep the issue confidential until we announce it.
68 https://github.com/cakephp/cakephp/issues
69 https://github.com/cakephp/cakephp/search?q=it+is+broken&ref=cmdform&type=Issues
70 https://webchat.freenode.net
71 https://stackoverflow.com/questions/tagged/cakephp

Tickets

189

CakePHP Book, Release 3.10

• Get a fix/patch prepared.
• Prepare a post describing the vulnerability, and the possible exploits.
• Release new versions of all affected versions.
• Prominently feature the problem in the release announcement.

Code
Patches and pull requests are a great way to contribute code back to CakePHP. Pull requests can be created in GitHub,
and are preferred over patch files in ticket comments.

Initial Setup
Before working on patches for CakePHP, it’s a good idea to get your environment setup. You’ll need the following
software:• Git• PHP 5.6 or greater• PHPUnit 5.7.0 or greaterSet up your user information with your name/handle and working email address:
git config --global user.name 'Bob Barker'
git config --global user.email 'bob.barker@example.com'

Note: If you are new to Git, we highly recommend you to read the excellent and free ProGit72 book.
Get a clone of the CakePHP source code from GitHub:• If you don’t have a GitHub73 account, create one.
• Fork the CakePHP repository74 by clicking the Fork button.
After your fork is made, clone your fork to your local machine:
git clone git@github.com:YOURNAME/cakephp.git
Add the original CakePHP repository as a remote repository. You’ll use this later to fetch changes from the CakePHP
repository. This will let you stay up to date with CakePHP:
cd cakephp
git remote add upstream git://github.com/cakephp/cakephp.git
Now that you have CakePHP setup you should be able to define a $test database connection, and run all the tests.
72 https://git-scm.com/book/73 https://github.com
74 https://github.com/cakephp/cakephp

190

Chapter 5. Contributing

CakePHP Book, Release 3.10

Working on a Patch
Each time you want to work on a bug, feature or enhancement create a topic branch.
The branch you create should be based on the version that your fix/enhancement is for. For example if you are fixing a
bug in 3.x you would want to use the master branch as the base for your branch. If your change is a bug fix for the
2.x release series, you should use the 2.x branch:# fixing a bug on 3.x
git fetch upstream
git checkout -b ticket-1234 upstream/master# fixing a bug on 2.x
git fetch upstream
git checkout -b ticket-1234 upstream/2.x

Tip: Use a descriptive name for your branch, referencing the ticket or feature name is a good convention. e.g. ticket1234, feature-awesome
The above will create a local branch based on the upstream (CakePHP) 2.x branch. Work on your fix, and make as
many commits as you need; but keep in mind the following:• Follow the Coding Standards.
• Add a test case to show the bug is fixed, or that the new feature works.
• Keep your commits logical, and write clear commit messages that provide context on what you changed and why.

Submitting a Pull Request
Once your changes are done and you’re ready for them to be merged into CakePHP, you’ll want to update your branch:# Rebase fix on top of mastergit checkout mastergit fetch upstream
git merge upstream/mastergit checkout <branch_name>git rebase master
This will fetch + merge in any changes that have happened in CakePHP since you started. It will then rebase - or replay
your changes on top of the current code. You might encounter a conflict during the rebase. If the rebase quits early you
can see which files are conflicted/un-merged with git status. Resolve each conflict, and then continue the rebase:
git add <filename> # do this for each conflicted file.
git rebase --continue
Check that all your tests continue to pass. Then push your branch to your fork:
git push origin <branch-name>
If you’ve rebased after pushing your branch, you’ll need to use force push:
git push --force origin <branch-name>Once your branch is on GitHub, you can submit a pull request on GitHub.
Code

191

CakePHP Book, Release 3.10

Choosing Where Your Changes will be Merged Into
When making pull requests you should make sure you select the correct base branch, as you cannot edit it once the pull
request is created.
• If your change is a bugfix and doesn’t introduce new functionality and only corrects existing behavior that ispresent in the current release. Then choose master as your merge target.
• If your change is a new feature or an addition to the framework, then you should choose the branch with the next
version number. For example if the current stable release is 3.6.0, the branch accepting new features will be
3.next.
• If your change is a breaks existing functionality, or APIs then you’ll have to choose then next major release. For
example, if the current release is 3.6.0 then the next time existing behavior can be broken will be in 4.x so you
should target that branch.
Note: Remember that all code you contribute to CakePHP will be licensed under the MIT License, and the Cake
Software Foundation75 will become the owner of any contributed code. Contributors should follow the CakePHPCommunity Guidelines76 .
All bug fixes merged into a maintenance branch will also be merged into upcoming releases periodically by the coreteam.

Coding Standards
CakePHP developers will use the PSR-2 coding style guide77 in addition to the following rules as coding standards.
It is recommended that others developing CakeIngredients follow the same standards.
You can use the CakePHP Code Sniffer78 to check that your code follows required standards.

Adding New Features
No new features should be added, without having their own tests – which should be passed before committing them tothe repository.

IDE Setup
Please make sure your IDE is set up to “trim right” on whitespaces. There should be no trailing spaces per line.
Most modern IDEs also support an .editorconfig file. The CakePHP app skeleton ships with it by default. It alreadycontains best practise defaults.
We recommend to use the IdeHelper79 plugin if you want to maximize IDE compatibility. It will assist to keep the
annotations up-to-date which will make the IDE fully understand how all classes work together and provides bettertype-hinting and auto-completion.
75 https://cakefoundation.org/pages/about
76 https://community.cakephp.org/guidelines
77 https://www.php-fig.org/psr/psr-2/
78 https://github.com/cakephp/cakephp-codesniffer
79 https://github.com/dereuromark/cakephp-ide-helper

192

Chapter 5. Contributing

CakePHP Book, Release 3.10

Indentation
Four spaces will be used for indentation.
So, indentation should look like this:// base level// level 1// level 2// level 1// base levelOr:$booleanVariable = true;$stringVariable = 'moose';if ($booleanVariable) {echo 'Boolean value is true';
if ($stringVariable === 'moose') {echo 'We have encountered a moose';}}
In cases where you’re using a multi-line function call use the following guidelines:• Opening parenthesis of a multi-line function call must be the last content on the line.
• Only one argument is allowed per line in a multi-line function call.
• Closing parenthesis of a multi-line function call must be on a line by itself.
As an example, instead of using the following formatting:$matches = array_intersect_key($this->_listeners,
array_flip(preg_grep($matchPattern,array_keys($this->_listeners), 0)));Use this instead:$matches = array_intersect_key($this->_listeners,
array_flip(
preg_grep($matchPattern, array_keys($this->_listeners), 0)));

Line Length
It is recommended to keep lines at approximately 100 characters long for better code readability. A limit of 80 or 120
characters makes it necessary to distribute complex logic or expressions by function, as well as give functions andobjects shorter, more expressive names. Lines must not be longer than 120 characters.
In short:• 100 characters is the soft limit.
• 120 characters is the hard limit.

Coding Standards

193

CakePHP Book, Release 3.10

Control Structures
Control structures are for example “if”, “for”, “foreach”, “while”, “switch” etc. Below, an example with “if”:
if ((expr_1) || (expr_2)) {// action_1;} elseif (!(expr_3) && (expr_4)) {// action_2;} else {// default_action;}• In the control structures there should be 1 (one) space before the first parenthesis and 1 (one) space between thelast parenthesis and the opening bracket.
• Always use curly brackets in control structures, even if they are not needed. They increase the readability of thecode, and they give you fewer logical errors.
• Opening curly brackets should be placed on the same line as the control structure. Closing curly brackets shouldbe placed on new lines, and they should have same indentation level as the control structure. The statement
included in curly brackets should begin on a new line, and code contained within it should gain a new level ofindentation.
• Inline assignments should not be used inside of the control structures.
// wrong = no brackets, badly placed statement
if (expr) statement;// wrong = no brackets
if (expr)
statement;// goodif (expr) {statement;}// wrong = inline assignment
if ($variable = Class::function()) {statement;}// good$variable = Class::function();if ($variable) {statement;}

194

Chapter 5. Contributing

CakePHP Book, Release 3.10

Ternary Operator
Ternary operators are permissible when the entire ternary operation fits on one line. Longer ternaries should be split
into if else statements. Ternary operators should not ever be nested. Optionally parentheses can be used around thecondition check of the ternary for clarity:// Good, simple and readable$variable = isset($options['variable']) ? $options['variable'] : true;// Nested ternaries are bad$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false :␣
˓→false;Template FilesIn template files (.ctp files) developers should use keyword control structures. Keyword control structures are easier toread in complex template files. Control structures can either be contained in a larger PHP block, or in separate PHP
tags:
<?php
if ($isAdmin):echo '<p>You are the admin user.</p>';endif;?><p>The following is also acceptable:</p><?php if ($isAdmin): ?><p>You are the admin user.</p><?php endif; ?>Comparison
Always try to be as strict as possible. If a non-strict test is deliberate it might be wise to comment it as such to avoid
confusing it for a mistake.
For testing if a variable is null, it is recommended to use a strict check:if ($value === null) {// ...
}The value to check against should be placed on the right side:// not recommended
if (null === $this->foo()) {// ...
}// recommended
if ($this->foo() === null) {// ...
}

Coding Standards

195

CakePHP Book, Release 3.10

Function Calls
Functions should be called without space between function’s name and starting parenthesis. There should be one space
between every parameter of a function call:$var = foo($bar, $bar2, $bar3);
As you can see above there should be one space on both sides of equals sign (=).

Method Definition
Example of a method definition:
public function someFunction($arg1, $arg2 = ''){if (expr) {statement;}
return $var;}
Parameters with a default value, should be placed last in function definition. Try to make your functions return something, at least true or false, so it can be determined whether the function call was successful:
public function connection($dns, $persistent = false){
if (is_array($dns)) {$dnsInfo = $dns;} else {$dnsInfo = BD::parseDNS($dns);}
if (!($dnsInfo) || !($dnsInfo['phpType'])) {return $this->addError();}return true;}
There are spaces on both side of the equals sign.

Bail Early
Try to avoid unnecessary nesting by bailing early:
public function run(array $data){...
if (!$success) {return false;}(continues on next page)

196

Chapter 5. Contributing

CakePHP Book, Release 3.10

(continued from previous page)...
}
public function check(array $data){...
if (!$success) {throw new RuntimeException(...);}...
}
This helps to keep the code flow simple and easy to follow.
Typehinting
Arguments that expect objects, arrays or callbacks (callable) can be typehinted. We only typehint public methods,
though, as typehinting is not cost-free:/*** Some method description.
** @param \Cake\ORM\Table $table The table class to use.
* @param array $array Some array value.
* @param callable $callback Some callback.
* @param bool $boolean Some boolean value.
*/
public function foo(Table $table, array $array, callable $callback, $boolean){}Here $table must be an instance of \Cake\ORM\Table, $array must be an array and $callback must be of typecallable (a valid callback).
Note that if you want to allow $array to be also an instance of \ArrayObject you should not typehint as array
accepts only the primitive type:/*** Some method description.
** @param array|\ArrayObject $array Some array value.
*/
public function foo($array){}

Coding Standards

197

CakePHP Book, Release 3.10

Anonymous Functions (Closures)
Defining anonymous functions follows the PSR-280 coding style guide, where they are declared with a space after thefunction keyword, and a space before and after the use keyword:$closure = function ($arg1, $arg2) use ($var1, $var2) {// code};Method Chaining
Method chaining should have multiple methods spread across separate lines, and indented with four spaces:$email->from('foo@example.com')->to('bar@example.com')->subject('A great message')->send();Commenting CodeAll comments should be written in English, and should in a clear way describe the commented block of code.
Comments can include the following phpDocumentor81 tags:• @author82• @copyright83• @deprecated84 Using the @version <vector> <description> format, where version and description
are mandatory. Version refers to the one it got deprecated in.
• @example85• @ignore86• @internal87• @link88• @see89• @since90• @version91
PhpDoc tags are very much like JavaDoc tags in Java. Tags are only processed if they are the first thing in a DocBlockline, for example:
80 https://www.php-fig.org/psr/psr-2/
81 https://phpdoc.org
82 https://phpdoc.org/docs/latest/references/phpdoc/tags/author.html
83 https://phpdoc.org/docs/latest/references/phpdoc/tags/copyright.html
84 https://phpdoc.org/docs/latest/references/phpdoc/tags/deprecated.html
85 https://phpdoc.org/docs/latest/references/phpdoc/tags/example.html
86 https://phpdoc.org/docs/latest/references/phpdoc/tags/ignore.html
87 https://phpdoc.org/docs/latest/references/phpdoc/tags/internal.html
88 https://phpdoc.org/docs/latest/references/phpdoc/tags/link.html
89 https://phpdoc.org/docs/latest/references/phpdoc/tags/see.html
90 https://phpdoc.org/docs/latest/references/phpdoc/tags/since.html
91 https://phpdoc.org/docs/latest/references/phpdoc/tags/version.html

198

Chapter 5. Contributing

CakePHP Book, Release 3.10/**
* Tag example.
** @author this tag is parsed, but this @version is ignored* @version 1.0 this tag is also parsed*//*** Example of inline phpDoc tags.
** This function works hard with foo() to rule the world.
** @return void*/
function bar(){}/*** Foo function.
** @return void*/
function foo(){}
Comment blocks, with the exception of the first block in a file, should always be preceded by a newline.
Variable Types
Variable types for use in DocBlocks:
Type
Description
mixed
A variable with undefined (or multiple) type.
int
Integer type variable (whole number).
float
Float type (point number).
bool
Logical type (true or false).
stringString type (any value in “ “ or ‘ ‘).
null
Null type. Usually used in conjunction with another type.
array
Array type.

Coding Standards

199

CakePHP Book, Release 3.10

objectObject type. A specific class name should be used if possible.
resource
Resource type (returned by for example mysql_connect()). Remember that when you specify the type as mixed,
you should indicate whether it is unknown, or what the possible types are.
callable
Callable function.
You can also combine types using the pipe char:
int|bool
For more than two types it is usually best to just use mixed.
When returning the object itself, e.g. for chaining, one should use $this instead:/*** Foo function.
** @return $this*/public function foo(){
return $this;}Including Files
include, require, include_once and require_once do not have parentheses:// wrong = parentheses
require_once('ClassFileName.php');
require_once ($class);// good = no parentheses
require_once 'ClassFileName.php';
require_once $class;
When including files with classes or libraries, use only and always the require_once92 function.

PHP Tags
Always use long tags (<?php ?>) instead of short tags (<? ?>). The short echo should be used in template files (.ctp)
where appropriate.
92 https://php.net/require_once

200

Chapter 5. Contributing

CakePHP Book, Release 3.10

Short Echo
The short echo should be used in template files in place of <?php echo. It should be immediately followed by a single
space, the variable or function value to echo, a single space, and the php closing tag:// wrong = semicolon, no spaces<td><?=$name;?></td>// good = spaces, no semicolon<td><?= $name ?></td>
As of PHP 5.4 the short echo tag (<?=) is no longer to be consider a ‘short tag’ is always available regardless of theshort_open_tag ini directive.

Naming Convention
FunctionsWrite all functions in camelBack:function longFunctionName(){}

ClassesClass names should be written in CamelCase, for example:
class ExampleClass{}

Variables
Variable names should be as descriptive as possible, but also as short as possible. All variables should start with alowercase letter, and should be written in camelBack in case of multiple words. Variables referencing objects shouldin some way associate to the class the variable is an object of. Example:$user = 'John';$users = ['John', 'Hans', 'Arne'];$dispatcher = new Dispatcher();

Coding Standards

201

CakePHP Book, Release 3.10

Member Visibility
Use PHP’s public, protected and private keywords for methods and variables.
Example Addresses
For all example URL and mail addresses use “example.com”, “example.org” and “example.net”, for example:• Email: someone@example.com• WWW: http://www.example.com• FTP: ftp://ftp.example.com
The “example.com” domain name has been reserved for this (see RFC 260693 ) and is recommended for use in documentation or as examples.
Files
File names which do not contain classes should be lowercased and underscored, for example:
long_file_name.php

Casting
For casting we use:
Type
Description(bool)
Cast to boolean.
(int)Cast to integer.
(float)Cast to float.
(string)
Cast to string.
(array)Cast to array.
(object)
Cast to object.
Please use (int)$var instead of intval($var) and (float)$var instead of floatval($var) when applicable.
93 https://datatracker.ietf.org/doc/html/rfc2606.html

202

Chapter 5. Contributing

CakePHP Book, Release 3.10

Constants
Constants should be defined in capital letters:
define('CONSTANT', 1);
If a constant name consists of multiple words, they should be separated by an underscore character, for example:
define('LONG_NAMED_CONSTANT', 2);

Careful when using empty()/isset()
While empty() is an easy to use function, it can mask errors and cause unintended effects when '0' and 0 are given.
When variables or properties are already defined, the usage of empty() is not recommended. When working withvariables, it is better to rely on type-coercion to boolean instead of empty():function manipulate($var){// Not recommended, $var is already defined in the scopeif (empty($var)) {// ...
}// Use boolean type coercion
if (!$var) {// ...
}
if ($var) {// ...
}}
When dealing with defined properties you should favour null checks over empty()/isset() checks:
class Thing{
private $property; // Defined
public function readProperty(){// Not recommended as the property is defined in the classif (!isset($this->property)) {// ...
}// Recommended
if ($this->property === null) {}}}When working with arrays, it is better to merge in defaults over using empty() checks. By merging in defaults, you
can ensure that required keys are defined:

Coding Standards

203

CakePHP Book, Release 3.10

function doWork(array $array){// Merge defaults to remove need for empty checks.
$array += ['key' => null,];// Not recommended, the key is already set
if (isset($array['key'])) {// ...
}// Recommended
if ($array['key'] !== null) {// ...
}}

Backwards Compatibility Guide
Ensuring that you can upgrade your applications easily and smoothly is important to us. That’s why we only breakcompatibility at major release milestones. You might be familiar with semantic versioning94 , which is the general
guideline we use on all CakePHP projects. In short, semantic versioning means that only major releases (such as 2.0,
3.0, 4.0) can break backwards compatibility. Minor releases (such as 2.1, 3.1, 3.2) may introduce new features, but
are not allowed to break compatibility. Bug fix releases (such as 2.1.2, 3.0.1) do not add new features, but fix bugs orenhance performance only.
Note: Deprecations are removed with the next major version of the framework. It is advised to early on adapt yourcode already each minor as outlined in the deprecation comments and the migration guides.
To clarify what changes you can expect in each release tier we have more detailed information for developers using
CakePHP, and for developers working on CakePHP that helps set expectations of what can be done in minor releases.
Major releases can have as many breaking changes as required.
94 https://semver.org/

204

Chapter 5. Contributing

CakePHP Book, Release 3.10

Migration Guides
For each major and minor release, the CakePHP team will provide a migration guide. These guides explain the newfeatures and any breaking changes that are in each release. They can be found in the Appendices section of the cookbook.

Using CakePHP
If you are building your application with CakePHP, the following guidelines explain the stability you can expect.
Interfaces
Outside of major releases, interfaces provided by CakePHP will not have any existing methods changed. New methods
may be added, but no existing methods will be changed.
ClassesClasses provided by CakePHP can be constructed and have their public methods and properties used by application
code and outside of major releases backwards compatibility is ensured.
Note: Some classes in CakePHP are marked with the @internal API doc tag. These classes are not stable and do
not have any backwards compatibility promises.
In minor releases, new methods may be added to classes, and existing methods may have new arguments added. Any
new arguments will have default values, but if you’ve overridden methods with a differing signature you may see fatal
errors. Methods that have new arguments added will be documented in the migration guide for that release.
The following table outlines several use cases and what compatibility you can expect from CakePHP:
If you. . .

Backwards compatibility?

Typehint against the classCreate a new instance
Extend the class
Access a public property
Call a public method
Extend a class and. . .
Override a public property
Access a protected property
Override a protected property
Override a protected method
Call a protected method
Add a public property
Add a public method
Add an argument to an overridden method
Add a default argument value to an existing method argument

Yes
Yes
Yes
Yes
Yes
Yes
No1
No1
No1
No1
No
No
No1
Yes

1 Your code may be broken by minor releases. Check the migration guide for details.

Backwards Compatibility Guide

205

CakePHP Book, Release 3.10

Working on CakePHP
If you are helping make CakePHP even better please keep the following guidelines in mind when adding/changing
functionality:
In a minor release you can:In a minor release can you. . .
Classes
Remove a class
Remove an interface
Remove a trait
Make final
Make abstract
Change name
Properties
Add a public property
Remove a public property
Add a protected property
Remove a protected property
Methods
Add a public method
Remove a public method
Add a protected method
Move to parent class
Remove a protected method
Reduce visibility
Change method name
Add a new argument with default value
Add a new required argument to an existing method.
Remove a default value from an existing argument
Change method type void

No
No
No
No
No
Yes2
Yes
No
Yes
Yes3
Yes
No
Yes
Yes
Yes3
No
Yes2
Yes
No
No
Yes

Deprecations
In each minor release, features may be deprecated. If features are deprecated, API documentation and runtime warnings
will be added. Runtime errors help you locate code that needs to be updated before it breaks. If you wish to disable
runtime warnings you can do so using the Error.errorLevel configuration value:// in config/app.php// ...
'Error' => ['errorLevel' => E_ALL ^ E_USER_DEPRECATED,]// ...
Will disable runtime deprecation warnings.

2 You can change a class/method name as long as the old name remains available. This is generally avoided unless renaming has significant
benefit.
3 Avoid whenever possible. Any removals need to be documented in the migration guide.

206

Chapter 5. Contributing

CHAPTER 6

Installation

CakePHP has a few system requirements:• HTTP Server. For example: Apache. Having mod_rewrite is preferred, but by no means required. You can also
use nginx, or Microsoft IIS if you prefer.
• Minimum PHP 5.6 (7.4 supported).
• mbstring PHP extension• intl PHP extension• simplexml PHP extension• PDO PHP extension
Note: In XAMPP, intl extension is included but you have to uncomment extension=php_intl.dll in php.ini andrestart the server through the XAMPP Control Panel.
In WAMP, the intl extension is “activated” by default but not working. To make it work you have to go to php folder(by default) C:\wamp\bin\php\php{version}, copy all the files that looks like icu*.dll and paste them into the apachebin directory C:\wamp\bin\apache\apache{version}\bin. Then restart all services and it should be OK.
While a database engine isn’t required, we imagine that most applications will utilize one. CakePHP supports a variety
of database storage engines:• MySQL (5.5.3 or greater)• MariaDB (5.5 or greater)• PostgreSQL• Microsoft SQL Server (2008 or higher)• SQLite 3

207

CakePHP Book, Release 3.10

Note: All built-in drivers require PDO. You should make sure you have the correct PDO extensions installed.

Installing CakePHP
Before starting you should make sure that your PHP version is up to date:php -v
You should have PHP 5.6 (CLI) or higher. Your webserver’s PHP version must also be of 5.6 or higher, and should be
the same version your command line interface (CLI) uses.

Installing Composer
CakePHP uses Composer95 , a dependency management tool, as the officially supported method for installation.
• Installing Composer on Linux and macOS
1. Run the installer script as described in the official Composer documentation96 and follow the instructions
to install Composer.
2. Execute the following command to move the composer.phar to a directory that is in your path:
mv composer.phar /usr/local/bin/composer• Installing Composer on Windows
For Windows systems, you can download Composer’s Windows installer here97 . Further instructions for Composer’s Windows installer can be found within the README here98 .

Create a CakePHP Project
You can create a new CakePHP application using composer’s create-project command :composer create-project --prefer-dist cakephp/app:"^3.10" my_app_name
Once Composer finishes downloading the application skeleton and the core CakePHP library, you should have a functioning CakePHP application installed via Composer. Be sure to keep the composer.json and composer.lock files withthe rest of your source code.
You can now visit the path to where you installed your CakePHP application and see the default home page. To change
the content of this page, edit src/Template/Pages/home.ctp.
Although composer is the recommended installation method, there are pre-installed downloads available on Github99 .
Those downloads contain the app skeleton with all vendor packages installed. Also it includes the composer.phar soyou have everything you need for further use.
95 https://getcomposer.org
96 https://getcomposer.org/download/
97 https://github.com/composer/windows-setup/releases/
98 https://github.com/composer/windows-setup
99 https://github.com/cakephp/cakephp/tags

208

Chapter 6. Installation

CakePHP Book, Release 3.10

Keeping Up To Date with the Latest CakePHP Changes
By default this is what your application composer.json looks like:"require": {"cakephp/cakephp": "3.10.*"}Each time you run php composer.phar update you will receive patch releases for this minor version. You caninstead change this to ^3.10 to also receive the latest stable minor releases of the 3.x branch.
If you want to stay up to date with the latest unreleased changes in CakePHP, designate dev-master as the package
version in your application’s composer.json:"require": {"cakephp/cakephp": "dev-master"}Be aware that this is not recommended, as your application can break when the next major version is released. Additionally, composer does not cache development branches, so it slows down consecutive composer installs/updates.

Installation using DDEV
Another quick way to install CakePHP is via DDEV100 . It is an open source tool for launching local web development
environments.
If you want to configure a new project, you just need:mkdir my-cakephp-app
cd my-cakephp-app
ddev config --project-type=cakephp --docroot=webroot --php-version 7.4
ddev composer create --prefer-dist cakephp/app:"^3.10"
ddev launch
If you have an existing project:
git clone <your-cakephp-repo>
cd <your-cakephp-project>ddev config --project-type=cakephp --docroot=webroot --php-version 7.4
ddev composer install
ddev launch
Please check DDEV Docs101 for details on how to install / update DDEV.
Note: IMPORTANT: This is not a deployment script. It is aimed to help developers to set up a development environment quickly. It is not intended for production environments.
100 https://ddev.com/
101 https://ddev.readthedocs.io/

Installing CakePHP

209

CakePHP Book, Release 3.10

Permissions
CakePHP uses the tmp directory for a number of different operations. Model descriptions, cached views, and session
information are a few examples. The logs directory is used to write log files by the default FileLog engine.
As such, make sure the directories logs, tmp and all its subdirectories in your CakePHP installation are writable by the
web server user. Composer’s installation process makes tmp and its subfolders globally writeable to get things up andrunning quickly but you can update the permissions for better security and keep them writable only for the web serveruser.
One common issue is that logs and tmp directories and subdirectories must be writable both by the web server and thecommand line user. On a UNIX system, if your web server user is different from your command line user, you can run
the following commands from your application directory just once in your project to ensure that permissions will be
setup properly:
HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root␣˓→| head -1 | cut -d\-f1`
setfacl -R -m u:${HTTPDUSER}:rwx tmp
setfacl -R -d -m u:${HTTPDUSER}:rwx tmp
setfacl -R -m u:${HTTPDUSER}:rwx logs
setfacl -R -d -m u:${HTTPDUSER}:rwx logs
In order to use the CakePHP console tools, you need to ensure that bin/cake file is executable. On *nix or macOS,
you can execute:chmod +x bin/cakeOn Windows, the .bat file should be executable already. If you are using a Vagrant, or any other virtualized environment, any shared directories need to be shared with execute permissions (Please refer to your virtualized environment’s
documentation on how to do this).
If, for whatever reason, you cannot change the permissions of the bin/cake file, you can run the CakePHP console
with:
php bin/cake.php

Development Server
A development installation is the fastest way to setup CakePHP. In this example, we use CakePHP’s console to run
PHP’s built-in web server which will make your application available at http://host:port. From the app directory,
execute:bin/cake server
By default, without any arguments provided, this will serve your application at http://localhost:8765/.
If there is conflict with localhost or port 8765, you can tell the CakePHP console to run the web server on a specifichost and/or port utilizing the following arguments:
bin/cake server -H 192.168.13.37 -p 5673
This will serve your application at http://192.168.13.37:5673/.
That’s it! Your CakePHP application is up and running without having to configure a web server.

210

Chapter 6. Installation

CakePHP Book, Release 3.10

Note: Try bin/cake server -H 0.0.0.0 if the server is unreachable from other hosts.

Warning: The development server should never be used in a production environment. It is only intended as abasic development server.
If you’d prefer to use a real web server, you should be able to move your CakePHP install (including the hidden files)
inside your web server’s document root. You should then be able to point your web-browser at the directory you moved
the files into and see your application in action.

Production
A production installation is a more flexible way to setup CakePHP. Using this method allows an entire domain to act asa single CakePHP application. This example will help you install CakePHP anywhere on your filesystem and make itavailable at http://www.example.com. Note that this installation may require the rights to change the DocumentRooton Apache webservers.
After installing your application using one of the methods above into the directory of your choosing - we’ll assume you
chose /cake_install - your production setup will look like this on the file system:/cake_install/bin/config/logs/
plugins/src/
tests/
tmp/
vendor/webroot/ (this directory is set as DocumentRoot).gitignore.htaccess.travis.yml
composer.json
index.php
phpunit.xml.dist
README.md
Developers using Apache should set the DocumentRoot directive for the domain to:DocumentRoot /cake_install/webrootIf your web server is configured correctly, you should now find your CakePHP application accessible at http://www.
example.com.

Production

211

CakePHP Book, Release 3.10

Fire It Up
Alright, let’s see CakePHP in action. Depending on which setup you used, you should point your browser to http://
example.com/ or http://localhost:8765/. At this point, you’ll be presented with CakePHP’s default home, and a message
that tells you the status of your current database connection.
Congratulations! You are ready to create your first CakePHP application.

URL Rewriting
ApacheWhile CakePHP is built to work with mod_rewrite out of the box–and usually does–we’ve noticed that a few users
struggle with getting everything to play nicely on their systems.
Here are a few things you might try to get it running correctly. First look at your httpd.conf. (Make sure you are editing
the system httpd.conf rather than a user- or site-specific httpd.conf.)
These files can vary between different distributions and Apache versions. You may also take a look at https://wiki.
apache.org/httpd/DistrosDefaultLayout for further information.
1. Make sure that an .htaccess override is allowed and that AllowOverride is set to All for the correct DocumentRoot.
You should see something similar to:# Each directory to which Apache has access can be configured with respect# to which services and features are allowed and/or disabled in that# directory (and its subdirectories).
## First, we configure the "default" to be a very restrictive set of# features.
<Directory />Options FollowSymLinks
AllowOverride All#
Order deny,allow#
Deny from all</Directory>
2. Make sure you are loading mod_rewrite correctly. You should see something like:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
In many systems these will be commented out by default, so you may just need to remove the leading # symbols.
After you make changes, restart Apache to make sure the settings are active.
Verify that your .htaccess files are actually in the right directories. Some operating systems treat files that startwith ‘.’ as hidden and therefore won’t copy them.
3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository, and has
been unpacked correctly, by checking for .htaccess files.
CakePHP app directory (will be copied to the top directory of your application by bake):<IfModule mod_rewrite.c>
RewriteEngine on(continues on next page)212

Chapter 6. Installation

CakePHP Book, Release 3.10

(continued from previous page)

RewriteRule
RewriteRule</IfModule>^$
webroot/(.*) webroot/$1

[L]
[L]

CakePHP webroot directory (will be copied to your application’s web root by bake):<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]</IfModule>
If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings for Virtual
Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution-dependent). In thisfile, ensure that AllowOverride None is changed to AllowOverride All, so you have:<Directory />Options FollowSymLinks
AllowOverride All</Directory><Directory /var/www>
Options FollowSymLinks
AllowOverride All
Order Allow,Deny
Allow from all</Directory>
On macOS, another solution is to use the tool virtualhostx102 to make a Virtual Host to point to your folder.
For many hosting services (GoDaddy, 1and1), your web server is being served from a user directory that already uses mod_rewrite. If you are installing CakePHP into a user directory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (.htaccess, webroot/.htaccess).
This can be added to the same section with the RewriteEngine directive, so for example, your webroot .htaccessfile would look like:<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/app
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]</IfModule>
The details of those changes will depend on your setup, and can include additional things that are not related to
CakePHP. Please refer to Apache’s online documentation for more information.
4. (Optional) To improve production setup, you should prevent invalid assets from being parsed by CakePHP. Modify your webroot .htaccess to something like:<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /path/to/app/(continues on next page)
102 https://clickontyler.com/virtualhostx/

URL Rewriting213

CakePHP Book, Release 3.10

(continued from previous page)

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !^/(webroot/)?(img|css|js)/(.*)$
RewriteRule ^ index.php [L]</IfModule>
The above will prevent incorrect assets from being sent to index.php and instead display your web server’s 404
page.
Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by adding an
ErrorDocument directive:
ErrorDocument 404 /404-not-found

nginx
nginx does not make use of .htaccess files like Apache, so it is necessary to create those rewritten URLs in the site-available configuration.
This is usually found in /etc/nginx/sites-available/
your_virtual_host_conf_file. Depending on your setup, you will have to modify this, but at the very least,
you will need PHP running as a FastCGI instance. The following configuration redirects the request to webroot/index.php:
location / {try_files $uri $uri/ /index.php?$args;}
A sample of the server directive is as follows:
server {listen80;
listen[::]:80;server_name www.example.com;
return 301 http://example.com$request_uri;}server {listen80;
listen[::]:80;server_name example.com;
root
index

/var/www/example.com/public/webroot;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 fastcgi_params;(continues on next page)

214

Chapter 6. Installation

CakePHP Book, Release 3.10

(continued from previous page)fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_intercept_errors on;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;}}Note: Recent configurations of PHP-FPM are set to listen to the unix php-fpm socket instead of TCP port 9000 on
address 127.0.0.1. If you get 502 bad gateway errors from the above configuration, try update fastcgi_pass to use
the unix socket path (eg: fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;) instead of the TCP port.

IIS7 (Windows hosts)
IIS7 does not natively support .htaccess files. While there are add-ons that can add this support, you can also importhtaccess rules into IIS to use CakePHP’s native rewrites. To do this, follow these steps:
1. Use Microsoft’s Web Platform Installer103 to install the URL Rewrite Module 2.0104 or download it directly(32-bit105 / 64-bit106 ).
2. Create a new file called web.config in your CakePHP root folder.
3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file:<?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, favicon)˓→"stopProcessing="true"><match url="^(font|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>(continues on next page)103 https://www.microsoft.com/web/downloads/platform.aspx
104 https://www.iis.net/downloads/microsoft/url-rewrite
105 https://www.microsoft.com/en-us/download/details.aspx?id=5747
106 https://www.microsoft.com/en-us/download/details.aspx?id=7435

URL Rewriting215

CakePHP Book, Release 3.10

(continued from previous page)</rewrite></system.webServer></configuration>
Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaScript, andrerouting should work correctly.

I Can’t Use URL Rewriting
If you don’t want or can’t get mod_rewrite (or some other compatible module) running on your server, you will need
to use CakePHP’s built in pretty URLs. In config/app.php, uncomment the line that looks like:'App' => [// ...
// 'baseUrl' => env('SCRIPT_NAME'),]
Also remove these .htaccess files:/.htaccesswebroot/.htaccessThis will make your URLs look like www.example.com/index.php/controllername/actionname/param rather thanwww.example.com/controllername/actionname/param.

216

Chapter 6. Installation

CHAPTER 7

Configuration

While conventions remove the need to configure all of CakePHP, you’ll still need to configure a few things like yourdatabase credentials.
Additionally, there are optional configuration options that allow you to swap out default values & implementations withones tailored to your application.

Configuring your Application
Your application will come with a few configuration files located in the config directory. By default CakePHP uses
PHP files for its configuration, but you can switch to INI or JSON files if you’d prefer.
Configuration files are loaded at the beginning of each request during your application’s ‘bootstrap’ process. Configuration is loaded into Cake\Core\Configure and is used to configure the various services provided by CakePHP andyour application.
The application skeleton features a config/app.php file which should contain configuration that doesn’t vary across thevarious environments your application is deployed in. The config/app_local.php file should contain the configuration
data that varies between environments and shouldn’t be checked into version control. Both of these files reference environment variables through the env() function that enables configuration values to set though the server environment.

217

CakePHP Book, Release 3.10

Loading Additional Configuration Files
If your application has many configuration options it can be helpful to split configuration into multiple files. After
creating each of the files in your config/ directory you can load them in bootstrap.php:
use Cake\Core\Configure;use Cake\Core\Configure\Engine\PhpConfig;
Configure::config('default', new PhpConfig());
Configure::load('app', 'default', false);
Configure::load('other_config', 'default');

Environment Variables
Many modern cloud providers, like Heroku, let you define environment variables for configuration data. You canconfigure your CakePHP through environment variables in the 12factor app style107 . Environment variables allow
your application to require less state making your application easier to manage when it is deployed across a number ofenvironments.
As you can see in your app.php, the env() function is used to read configuration from the environment, and build theapplication configuration. CakePHP uses DSN strings for databases, logs, email transports and cache configurations
allowing you to easily vary these libraries in each environment.
For local development, CakePHP leverages dotenv108 to allow easy local development using environment variables.
You will see a config/.env.example in your application. By copying this file into config/.env and customizing
the values you can configure your application.
You should avoid committing the config/.env file to your repository and instead use the config/.env.example asa template with placeholder values so everyone on your team knows what environment variables are in use and whatshould go in each one.
Once your environment variables have been set, you can use env() to read data from the environment:$debug = env('APP_DEBUG', false);
The second value passed to the env function is the default value. This value will be used if no environment variable
exists for the given key.
Changed in version 3.5.0: dotenv library support was added to the application skeleton.
Changed in version 3.5.1: dotenv library support is now opt in. You must uncomment the appropriate block of code inconfig/bootstrap.php
107 https://12factor.net/
108 https://github.com/josegonzalez/php-dotenv

218

Chapter 7. Configuration

CakePHP Book, Release 3.10

General Configuration
Below is a description of the variables and how they affect your CakePHP application.
debug
Changes CakePHP debugging output. false = Production mode. No error messages, errors, or warnings shown.
true = Errors and warnings shown.
App.namespace
The namespace to find app classes under.
Note: When changing the namespace in your configuration, you will also need to update your composer.json
file to use this namespace as well. Additionally, create a new autoloader by running php composer.phar
dump-autoload.
App.baseUrl
Un-comment this definition if you don’t plan to use Apache’s mod_rewrite with CakePHP. Don’t forget to remove
your .htaccess files too.
App.base
The base directory the app resides in. If false this will be auto detected. If not false, ensure your string starts
with a / and does NOT end with a /. E.g., /basedir is a valid App.base. Otherwise, the AuthComponent will notwork properly.
App.encoding
Define what encoding your application uses. This encoding is used to generate the charset in the layout, andencode entities. It should match the encoding values specified for your database.
App.webroot
The webroot directory.
App.wwwRoot
The file path to webroot.
App.fullBaseUrl
The fully qualified domain name (including protocol), e.g. https://app.example.org, to your application’sroot. This is used when generating absolute URLs. By default this value is generated using the $_SERVER environment. However, you should define it manually to optimize performance or if you are concerned about people
manipulating the Host header. In a CLI context (from shells) the fullBaseUrl cannot be read from $_SERVER,
as there is no webserver involved. You do need to specify it yourself if you do need to generate URLs from ashell (e.g. when sending emails).
App.imageBaseUrl
Web path to the public images directory under webroot. If you are using a CDN you should set this value to the
CDN’s location.
App.cssBaseUrl
Web path to the public css directory under webroot. If you are using a CDN you should set this value to the
CDN’s location.
App.jsBaseUrl
Web path to the public js directory under webroot. If you are using a CDN you should set this value to the CDN’s
location.
App.paths
Configure paths for non class based resources. Supports the plugins, templates, locales subkeys, whichallow the definition of paths for plugins, view templates and locale files respectively.

Environment Variables219

CakePHP Book, Release 3.10

App.uploadedFilesAsObjects
Defines whether uploaded files are being represented as objects (true), or arrays (false). This option is being
treated as disabled by default. See the File Uploads section in the Request & Response Objects chapter for more
information.
New in version 3.9.0: Support for uploaded files as objects in the request data was added in version 3.9.0
Security.salt
A random string used in hashing. This value is also used as the HMAC salt when doing symetric encryption.
Asset.timestamp
Appends a timestamp which is last modified time of the particular file at the end of asset files URLs (CSS,JavaScript, Image) when using proper helpers. Valid values:• (bool) false - Doesn’t do anything (default)• (bool) true - Appends the timestamp when debug is true
• (string) ‘force’ - Always appends the timestamp.
Changed in version 3.6.0: As of 3.6.0, you can override this global setting when linking assets using thetimestamp option.
Asset.cacheTime
Sets the asset cache time. This determines the http header Cache-Control’s max-age, and the http header’s
Expire’s time for assets. This can take anything that you version of PHP’s strtotime function109 can take. The
default is +1 day.

Using a CDN
To use a CDN for loading your static assets, change App.imageBaseUrl, App.cssBaseUrl, App.jsBaseUrl to point
the CDN URI, for example: https://mycdn.example.com/ (note the trailing /).
All images, scripts and styles loaded via HtmlHelper will prepend the absolute CDN path, matching the same relative
path used in the application. Please note there is a specific use case when using plugin based assets: plugins will not
use the plugin’s prefix when absolute ...BaseUrl URI is used, for example By default:• $this->Helper->assetUrl('TestPlugin.logo.png') resolves to test_plugin/logo.png
If you set App.imageBaseUrl to https://mycdn.example.com/:• $this->Helper->assetUrl('TestPlugin.logo.png') resolves to https://mycdn.example.com/
logo.png.

Database Configuration
See the Database Configuration for information on configuring your database connections.
109 https://php.net/manual/en/function.strtotime.php

220

Chapter 7. Configuration

CakePHP Book, Release 3.10

Caching Configuration
See the Caching Configuration for information on configuring caching in CakePHP.

Error and Exception Handling Configuration
See the Error and Exception Configuration for information on configuring error and exception handlers.

Logging Configuration
See the Logging Configuration for information on configuring logging in CakePHP.

Email Configuration
See the Email Configuration for information on configuring email presets in CakePHP.

Session Configuration
See the Session Configuration for information on configuring session handling in CakePHP.

Routing configuration
See the Routes Configuration for more information on configuring routing and creating routes for your application.

Additional Class Paths
Additional class paths are setup through the autoloaders your application uses. When using composer to generate yourautoloader, you could do the following, to provide fallback paths for controllers in your application:"autoload": {"psr-4": {"App\\Controller\\": "/path/to/directory/with/controller/folders/","App\\": "src/"}}
The above would setup paths for both the App and App\Controller namespace. The first key will be searched, andif that path does not contain the class/file the second key will be searched. You can also map a single namespace tomultiple directories with the following:"autoload": {"psr-4": {"App\\": ["src/", "/path/to/directory/"]}}

Additional Class Paths

221

CakePHP Book, Release 3.10

Plugin, View Template and Locale Paths
Since plugins, view templates and locales are not classes, they cannot have an autoloader configured. CakePHP provides
three Configure variables to setup additional paths for these resources. In your config/app.php you can set thesevariables:
return [// More configuration'App' => ['paths' => ['plugins' => [ROOT . DS . 'plugins' . DS,'/path/to/other/plugins/'],'templates' => [APP . 'Template' . DS,
APP . 'Template2' . DS],
'locales' => [APP . 'Locale' . DS]]]];
Paths should end with a directory separator, or they will not work properly.

Inflection Configuration
See the Inflection Configuration docs for more information.

Configure Class
class Cake\Core\Configure
CakePHP’s Configure class can be used to store and retrieve application or runtime specific values. Be careful, thisclass allows you to store anything in it, then use it in any other part of your code: a sure temptation to break the MVC
pattern CakePHP was designed for. The main goal of Configure class is to keep centralized variables that can be shared
between many objects. Remember to try to live by “convention over configuration” and you won’t end up breaking the
MVC structure CakePHP provides.

222

Chapter 7. Configuration

CakePHP Book, Release 3.10

Writing Configuration data
static Cake\Core\Configure::write($key, $value)
Use write() to store data in the application’s configuration:
Configure::write('Company.name','Pizza, Inc.');Configure::write('Company.slogan','Pizza for your body and soul');Note: The dot notation used in the $key parameter can be used to organize your configuration settings into logicalgroups.
The above example could also be written in a single call:Configure::write('Company', ['name' => 'Pizza, Inc.','slogan' => 'Pizza for your body and soul']);
You can use Configure::write('debug', $bool) to switch between debug and production modes on the fly. Thisis especially handy for JSON interactions where debugging information can cause parsing problems.

Reading Configuration Datastatic Cake\Core\Configure::read($key = null, $default = null)
Used to read configuration data from the application. If a key is supplied, the data is returned. Using our examples
from write() above, we can read that data back:// Returns 'Pizza Inc.'
Configure::read('Company.name');// Returns 'Pizza for your body and soul'Configure::read('Company.slogan');Configure::read('Company');// Returns:['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];// Returns 'fallback' as Company.nope is undefined.
Configure::read('Company.nope', 'fallback');
If $key is left null, all values in Configure will be returned.
Changed in version 3.5.0: The $default parameter was added in 3.5.0
static Cake\Core\Configure::readOrFail($key)
Reads configuration data just like Cake\Core\Configure::read but expects to find a key/value pair. In case therequested pair does not exist, a RuntimeException will be thrown:
Configure::readOrFail('Company.name');// Yields: 'Pizza, Inc.'
Configure::readOrFail('Company.geolocation'); // Will throw an exception(continues on next page)

Configure Class223

CakePHP Book, Release 3.10

(continued from previous page)

Configure::readOrFail('Company');// Yields:['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];
New in version 3.1.7: Configure::readOrFail() was added in 3.1.7

Checking to see if Configuration Data is Defined
static Cake\Core\Configure::check($key)
Used to check if a key/path exists and has non-null value:$exists = Configure::check('Company.name');Deleting Configuration Datastatic Cake\Core\Configure::delete($key)
Used to delete information from the application’s configuration:
Configure::delete('Company.name');Reading & Deleting Configuration Datastatic Cake\Core\Configure::consume($key)
Read and delete a key from Configure. This is useful when you want to combine reading and deleting values in a single
operation.
static Cake\Core\Configure::consumeOrFail($key)
Consumes configuration data just like Cake\Core\Configure::consume but expects to find a key/value pair. In casethe requested pair does not exist, a RuntimeException will be thrown:
Configure::consumeOrFail('Company.name');// Yields: 'Pizza, Inc.'
Configure::consumeOrFail('Company.geolocation'); // Will throw an exception
Configure::consumeOrFail('Company');// Yields:['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];
New in version 3.6.0: Configure::readOrFail() was added in 3.6.0

224

Chapter 7. Configuration

CakePHP Book, Release 3.10

Reading and writing configuration files
static Cake\Core\Configure::config($name, $engine)
CakePHP comes with two built-in configuration file engines. Cake\Core\Configure\Engine\PhpConfig is able
to read PHP config files, in the same format that Configure has historically read. Cake\Core\Configure\Engine\
IniConfig is able to read ini config files. See the PHP documentation110 for more information on the specifics of ini
files. To use a core config engine, you’ll need to attach it to Configure using Configure::config():
use Cake\Core\Configure\Engine\PhpConfig;// Read config files from config
Configure::config('default', new PhpConfig());// Read config files from another path.
Configure::config('default', new PhpConfig('/path/to/your/config/files/'));
You can have multiple engines attached to Configure, each reading different kinds or sources of configuration files.
You can interact with attached engines using a few other methods on Configure. To check which engine aliases areattached you can use Configure::configured():// Get the array of aliases for attached engines.
Configure::configured();// Check if a specific engine is attached
Configure::configured('default');
static Cake\Core\Configure::drop($name)
You can also remove attached engines. Configure::drop('default') would remove the default engine alias. Any
future attempts to load configuration files with that engine would fail:Configure::drop('default');

Loading Configuration Filesstatic Cake\Core\Configure::load($key, $config = 'default', $merge = true)
Once you’ve attached a config engine to Configure you can load configuration files:// Load my_file.php using the 'default' engine object.
Configure::load('my_file', 'default');
Loaded configuration files merge their data with the existing runtime configuration in Configure. This allows you to
overwrite and add new values into the existing runtime configuration. By setting $merge to true, values will not everoverwrite the existing configuration.
110 https://php.net/parse_ini_file

Reading and writing configuration files

225

CakePHP Book, Release 3.10

Creating or Modifying Configuration Filesstatic Cake\Core\Configure::dump($key, $config = 'default', $keys = [])Dumps all or some of the data in Configure into a file or storage system supported by a config engine. The serialization
format is decided by the config engine attached as $config. For example, if the ‘default’ engine is a Cake\Core\
Configure\Engine\PhpConfig, the generated file will be a PHP configuration file loadable by the Cake\Core\
Configure\Engine\PhpConfig
Given that the ‘default’ engine is an instance of PhpConfig. Save all data in Configure to the file my_config.php:
Configure::dump('my_config', 'default');
Save only the error handling configuration:
Configure::dump('error', 'default', ['Error', 'Exception']);Configure::dump() can be used to either modify or overwrite configuration files that are readable with
Configure::load()

Storing Runtime Configuration
static Cake\Core\Configure::store($name, $cacheConfig = 'default', $data = null)
You can also store runtime configuration values for use in a future request. Since configure only remembers values forthe current request, you will need to store any modified configuration information if you want to use it in subsequent
requests:// Store the current configuration in the 'user_1234' key in the 'default' cache.
Configure::store('user_1234', 'default');
Stored configuration data is persisted in the named cache configuration. See the Caching documentation for more
information on caching.

Restoring Runtime Configuration
static Cake\Core\Configure::restore($name, $cacheConfig = 'default')
Once you’ve stored runtime configuration, you’ll probably need to restore it so you can access it again.
Configure::restore() does exactly that:// Restore runtime configuration from the cache.
Configure::restore('user_1234', 'default');
When restoring configuration information it’s important to restore it with the same key, and cache configuration as wasused to store it. Restored information is merged on top of the existing runtime configuration.

226

Chapter 7. Configuration

CakePHP Book, Release 3.10

Configuration Engines
CakePHP provides the ability to load configuration files from a number of different sources, and features a pluggablesystem for creating your own configuration engines111 . The built in configuration engines are:
• JsonConfig112• IniConfig113• PhpConfig114
By default your application will use PhpConfig.

Bootstrapping CakePHP
If you have any additional configuration needs, you should add them to your application’s config/bootstrap.php file.
This file is included before each request, and CLI command.
This file is ideal for a number of common bootstrapping tasks:• Defining convenience functions.
• Declaring constants.
• Defining cache configuration.
• Defining logging configuration.
• Loading custom inflections.
• Loading configuration files.
It might be tempting to place formatting functions there in order to use them in your controllers. As you’ll see in theControllers and Views sections there are better ways you add custom logic to your application.

Application::bootstrap()
In addition to the config/bootstrap.php file which should be used to configure low-level concerns of your application,
you can also use the Application::bootstrap() hook method to load/initialize plugins, and attach global event
listeners:// in src/Application.php
namespace App;use Cake\Core\Plugin;
use Cake\Http\BaseApplication;
class Application extends BaseApplication{
public function bootstrap(){// Call the parent to `require_once` config/bootstrap.php
parent::bootstrap();(continues on next page)
111 https://api.cakephp.org/3.x/class-Cake.Core.Configure.ConfigEngineInterface.html
112 https://api.cakephp.org/3.x/class-Cake.Core.Configure.Engine.JsonConfig.html
113 https://api.cakephp.org/3.x/class-Cake.Core.Configure.Engine.IniConfig.html
114 https://api.cakephp.org/3.x/class-Cake.Core.Configure.Engine.PhpConfig.html

Bootstrapping CakePHP

227

CakePHP Book, Release 3.10

(continued from previous page)$this->addPlugin('MyPlugin', ['bootstrap' => true, 'routes' => true]);}}
Loading plugins/events in Application::bootstrap() makes Controller Integration Testing easier as events androutes will be re-processed on each test method.

Disabling Generic Tables
While utilizing generic table classes - also called auto-tables - when quickly creating new applications and baking
models is useful, generic table class can make debugging more difficult in some scenarios.
You can check if any query was emitted from a generic table class via DebugKit via the SQL panel in DebugKit. If
you’re still having trouble diagnosing an issue that could be caused by auto-tables, you can throw an exception when
CakePHP implicitly uses a generic Cake\ORM\Table instead of your concrete class like so:// In your bootstrap.php
use Cake\Event\EventManager;// Prior to 3.6 use Cake\Network\Exception\InteralErrorException
use Cake\Http\Exception\InternalErrorException;$isCakeBakeShellRunning = (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'bake');if (!$isCakeBakeShellRunning) {EventManager::instance()->on('Model.initialize', function($event) {$subject = $event->getSubject();
if (get_class($subject) === 'Cake\ORM\Table') {$msg = sprintf('Missing table class or incorrect alias when registering table class for␣
˓→database table %s.',$subject->getTable());
throw new InternalErrorException($msg);
}
});
}

228

Chapter 7. Configuration

CHAPTER 8

Routingclass Cake\Routing\Router
Routing provides you tools that map URLs to controller actions. By defining routes, you can separate how your application is implemented from how its URLs are structured.
Routing in CakePHP also encompasses the idea of reverse routing, where an array of parameters can be transformed
into a URL string. By using reverse routing, you can re-factor your application’s URL structure without having to
update all your code.

Quick TourThis section will teach you by example the most common uses of the CakePHP Router. Typically you want to display
something as a landing page, so you add this to your routes.php file:
use Cake\Routing\RouteBuilder;use Cake\Routing\Router;// Using a scoped route builder.
Router::scope('/', function (RouteBuilder $routes) {$routes->connect('/', ['controller' => 'Articles', 'action' => 'index']);});// Using the static method.
Router::connect('/', ['controller' => 'Articles', 'action' => 'index']);Router provides two interfaces for connecting routes. The static method is a backwards compatible interface, while
the scoped builders offer more terse syntax when building multiple routes, and better performance.
This will execute the index method in the ArticlesController when the homepage of your site is visited. Sometimes
you need dynamic routes that will accept multiple parameters, this would be the case, for example of a route for viewing229

CakePHP Book, Release 3.10

an article’s content:$routes->connect('/articles/*', ['controller' => 'Articles', 'action' => 'view']);
The above route will accept any URL looking like /articles/15 and invoke the method view(15) in the
ArticlesController. This will not, though, prevent people from trying to access URLs looking like /articles/
foobar. If you wish, you can restrict some parameters to conform to a regular expression:$routes->connect('/articles/:id',['controller' => 'Articles', 'action' => 'view'])->setPatterns(['id' => '\d+'])->setPass(['id']);// Prior to 3.5 use the options array$routes->connect('/articles/:id',['controller' => 'Articles', 'action' => 'view'],['id' => '\d+', 'pass' => ['id']]);
The previous example changed the star matcher by a new placeholder :id. Using placeholders allows us to validate
parts of the URL, in this case we used the \d+ regular expression so that only digits are matched. Finally, we told theRouter to treat the id placeholder as a function argument to the view() function by specifying the pass option. Moreon using this option later.
The CakePHP Router can also reverse match routes. That means that from an array containing matching parameters,
it is capable of generating a URL string:use Cake\Routing\Router;echo Router::url(['controller' => 'Articles', 'action' => 'view', 'id' => 15]);// Will output/articles/15
Routes can also be labelled with a unique name, this allows you to quickly reference them when building links insteadof specifying each of the routing parameters:// In routes.php$routes->connect('/login',['controller' => 'Users', 'action' => 'login'],['_name' => 'login']);use Cake\Routing\Router;echo Router::url(['_name' => 'login']);// Will output/loginTo help keep your routing code DRY, the Router has the concept of ‘scopes’. A scope defines a common path segment,
and optionally route defaults. Any routes connected inside a scope will inherit the path/defaults from their wrapping
scopes:230

Chapter 8. Routing

CakePHP Book, Release 3.10

Router::scope('/blog', ['plugin' => 'Blog'], function (RouteBuilder $routes) {$routes->connect('/', ['controller' => 'Articles']);});
The above route would match /blog/ and send it to Blog\Controller\ArticlesController::index().
The application skeleton comes with a few routes to get you started. Once you’ve added your own routes, you canremove the default routes if you don’t need them.

Connecting Routes
To keep your code DRY you should use ‘routing scopes’. Routing scopes not only let you keep your code DRY, theyalso help Router optimize its operation. This method defaults to the / scope. To create a scope and connect some routes
we’ll use the scope() method:// In config/routes.php
use Cake\Routing\Route\DashedRoute;
Router::scope('/', function (RouteBuilder $routes) {// Connect the generic fallback routes.
$routes->fallbacks(DashedRoute::class);});
The connect() method takes up to three parameters: the URL template you wish to match, the default values for yourroute elements, and the options for the route. Options frequently include regular expression rules to help the routermatch elements in the URL.
The basic format for a route definition is:$routes->connect('/url/template',['targetKey' => 'targetValue'],['option' => 'matchingRegex']);
The first parameter is used to tell the router what sort of URL you’re trying to control. The URL is a normal slash
delimited string, but can also contain a wildcard (*) or Route Elements. Using a wildcard tells the router that you arewilling to accept any additional arguments supplied. Routes without a * only match the exact template pattern supplied.
Once you’ve specified a URL, you use the last two parameters of connect() to tell CakePHP what to do with a request
once it has been matched. The second parameter defines the route ‘target’. This can be defined either as an array, or asa destination string. A few examples of route targets are:// Array target to an application controller$routes->connect('/users/view/*',['controller' => 'Users', 'action' => 'view']);// String target to an application controller. requires >=3.6.0$routes->connect('/users/view/*', 'Users::view');// Array target to a prefixed plugin controller$routes->connect((continues on next page)

Connecting Routes

231CakePHP Book, Release 3.10

(continued from previous page)'/admin/cms/articles',['prefix' => 'admin', 'plugin' => 'Cms', 'controller' => 'Articles', 'action' =>˓→'index']);// String target to a prefixed plugin controller. requires >=3.6.0$routes->connect('/admin/cms/articles', 'Cms.Admin/Articles::index');
The first route we connect matches URLs starting with /users/view and maps those requests to theUsersController->view(). The trailing /* tells the router to pass any additional segments as method arguments.
For example, /users/view/123 would map to UsersController->view(123).
The above example also illustrates string targets. String targets provide a compact way to define a route’s destination.
String targets have the following syntax:[Plugin].[Prefix]/[Controller]::[action]
Some example string targets are:// Application controller'Bookmarks::view'// Application controller with prefix
Admin/Bookmarks::view// Plugin controller
Cms.Articles::edit// Prefixed plugin controller
Vendor/Cms.Management/Admin/Articles::view
New in version 3.6.0: String based route targets were added.
Earlier we used the greedy star (/*) to capture additional path segments, there is also the trailing star (/**). Using a
trailing double star, will capture the remainder of a URL as a single passed argument. This is useful when you want touse an argument that included a / in it:$routes->connect('/pages/**',['controller' => 'Pages', 'action' => 'show']);
The incoming URL of /pages/the-example-/-and-proof would result in a single passed argument ofthe-example-/-and-proof.
The second parameter of connect() can define any parameters that compose the default route parameters:$routes->connect('/government',['controller' => 'Pages', 'action' => 'display', 5]);This example uses the second parameter of connect() to define default parameters. If you built an application thatfeatures products for different categories of customers, you might consider creating a route. This allows you to link to/government rather than /pages/display/5.

232

Chapter 8. Routing

CakePHP Book, Release 3.10

A common use for routing is to rename controllers and their actions. Instead of accessing our users controller at /users/some_action/5, we’d like to be able to access it through /cooks/some_action/5. The following routetakes care of that:$routes->connect('/cooks/:action/*', ['controller' => 'Users']);
This is telling the Router that any URL beginning with /cooks/ should be sent to the UsersController. The action
called will depend on the value of the :action parameter. By using Route Elements, you can create variable routes, that
accept user input or variables. The above route also uses the greedy star. The greedy star indicates that this route should
accept any additional positional arguments given. These arguments will be made available in the Passed Arguments
array.
When generating URLs, routes are used too.
Using ['controller' => 'Users', 'action' =>'some_action', 5] as a URL will output /cooks/some_action/5 if the above route is the first match
found.
The routes we’ve connected so far will match any HTTP verb. If you are building a REST API you’ll often want to map
HTTP actions to different controller methods. The RouteBuilder provides helper methods that make defining routes
for specific HTTP verbs simpler:// Create a route that only responds to GET requests.
$routes->get('/cooks/:id',['controller' => 'Users', 'action' => 'view'],'users:view');// Create a route that only responds to PUT requests$routes->put('/cooks/:id',['controller' => 'Users', 'action' => 'update'],'users:update');
The above routes map the same URL to different controller actions based on the HTTP verb used. GET requests will
go to the ‘view’ action, while PUT requests will go to the ‘update’ action. There are HTTP helper methods for:
• GET
• POST• PUT• PATCH• DELETE• OPTIONS• HEAD
All of these methods return the route instance allowing you to leverage the fluent setters to further configure your route.
New in version 3.5.0: The HTTP verb helper methods were added.

Connecting Routes

233

CakePHP Book, Release 3.10

Route Elements
You can specify your own route elements and doing so gives you the power to define places in the URL where parameters for controller actions should lie. When a request is made, the values for these route elements are found in$this->request->getParam() in the controller. When you define a custom route element, you can optionally specify a regular expression - this tells CakePHP how to know if the URL is correctly formed or not. If you choose to notprovide a regular expression, any non / character will be treated as part of the parameter:$routes->connect('/:controller/:id',['action' => 'view'])->setPatterns(['id' => '[0-9]+']);// Prior to 3.5 use the options array$routes->connect('/:controller/:id',['action' => 'view'],['id' => '[0-9]+']);The above example illustrates how to create a quick way to view models from any controller by crafting a URL thatlooks like /controllername/:id. The URL provided to connect() specifies two route elements: :controller
and :id. The :controller element is a CakePHP default route element, so the router knows how to match and identify
controller names in URLs. The :id element is a custom route element, and must be further clarified by specifying amatching regular expression in the third parameter of connect().
CakePHP does not automatically produce lowercased and dashed URLs when using the :controller parameter. If
you need this, the above example could be rewritten like so:use Cake\Routing\Route\DashedRoute;// Create a builder with a different route class.
$routes->scope('/', function (RouteBuilder $routes) {$routes->setRouteClass(DashedRoute::class);$routes->connect('/:controller/:id', ['action' => 'view'])->setPatterns(['id' => '[0-9]+']);// Prior to 3.5 use options array$routes->connect('/:controller/:id',['action' => 'view'],['id' => '[0-9]+']);});The DashedRoute class will make sure that the :controller and :plugin parameters are correctly lowercased anddashed.
If you need lowercased and underscored URLs while migrating from a CakePHP 2.x application, you can instead use
the InflectedRoute class.
Note: Patterns used for route elements must not contain any capturing groups. If they do, Router will not function
correctly.

234

Chapter 8. Routing

CakePHP Book, Release 3.10

Once this route has been defined, requesting /apples/5 would call the view() method of the ApplesController. Inside
the view() method, you would need to access the passed ID at $this->request->getParam('id').
If you have a single controller in your application and you do not want the controller name to appear in the URL, you
can map all URLs to actions in your controller. For example, to map all URLs to actions of the home controller, e.g
have URLs like /demo instead of /home/demo, you can do the following:$routes->connect('/:action', ['controller' => 'Home']);If you would like to provide a case insensitive URL, you can use regular expression inline modifiers:// Prior to 3.5 use the options array instead of setPatterns()$routes->connect('/:userShortcut',['controller' => 'Teachers', 'action' => 'profile', 1],)->setPatterns(['userShortcut' => '(?i:principal)']);
One more example, and you’ll be a routing pro:// Prior to 3.5 use the options array instead of setPatterns()$routes->connect('/:controller/:year/:month/:day',['action' => 'index'])->setPatterns(['year' => '[12][0-9]{3}','month' => '0[1-9]|1[012]','day' => '0[1-9]|[12][0-9]|3[01]']);This is rather involved, but shows how powerful routes can be. The URL supplied has four route elements. The first is
familiar to us: it’s a default route element that tells CakePHP to expect a controller name.
Next, we specify some default values. Regardless of the controller, we want the index() action to be called.
Finally, we specify some regular expressions that will match years, months and days in numerical form. Note thatparenthesis (capturing groups) are not supported in the regular expressions. You can still specify alternates, as above,
but not grouped with parenthesis.
Once defined, this route will match /articles/2007/02/01, /articles/2004/11/16, handing the requests to theindex() actions of their respective controllers, with the date parameters in $this->request->getParam().
As of 3.6.0 you can use {var} for route elements instead of :var. This new parameter style enables route elements tobe embedded in non-capturing blocks. For example:$routes->connect('/images/resize/{id}/{width}x{height}',['controller' => 'Images', 'action' => 'view']);
Would be impossible to define using :var style placeholders.

Connecting Routes

235

CakePHP Book, Release 3.10

Reserved Route Elements
There are several route elements that have special meaning in CakePHP, and should not be used unless you want the
special meaning• controller Used to name the controller for a route.
• action Used to name the controller action for a route.
• plugin Used to name the plugin a controller is located in.
• prefix Used for Prefix Routing• _ext Used for File extentions routing.
• _base Set to false to remove the base path from the generated URL. If your application is not in the root
directory, this can be used to generate URLs that are ‘cake relative’.
• _scheme Set to create links on different schemes like webcal or ftp. Defaults to the current scheme.
• _host Set the host to use for the link. Defaults to the current host.
• _port Set the port if you need to create links on non-standard ports.
• _full If true the FULL_BASE_URL constant will be prepended to generated URLs.
• # Allows you to set URL hash fragments.
• _ssl Set to true to convert the generated URL to https or false to force http.
• _method Define the HTTP verb/method to use. Useful when working with RESTful Routing.
• _name Name of route. If you have setup named routes, you can use this key to specify it.

Configuring Route Options
There are a number of route options that can be set on each route. After connecting a route you can use its fluent
builder methods to further configure the route. These methods replace many of the keys in the $options parameter ofconnect():$routes->connect('/:lang/articles/:slug',['controller' => 'Articles', 'action' => 'view'])// Allow GET and POST requests.
->setMethods(['GET', 'POST'])// Only match on the blog subdomain.
->setHost('blog.example.com')// Set the route elements that should be converted to passed arguments->setPass(['slug'])// Set the matching patterns for route elements->setPatterns(['slug' => '[a-z0-9-_]+','lang' => 'en|fr|es',])(continues on next page)

236

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page)// Also allow JSON file extensions->setExtensions(['json'])// Set lang to be a persistent parameter->setPersist(['lang']);
New in version 3.5.0: Fluent builder methods were added in 3.5.0

Passing Parameters to Action
When connecting routes using Route Elements you may want to have routed elements be passed arguments instead.
The pass option whitelists which route elements should also be made available as arguments passed into the controller
functions:// src/Controller/BlogsController.php
public function view($articleId = null, $slug = null){// Some code here...
}// routes.php
Router::scope('/', function (RouteBuilder $routes) {$routes->connect('/blog/:id-:slug', // E.g. /blog/3-CakePHP_Rocks['controller' => 'Blogs', 'action' => 'view'])// Define the route elements in the route template// to pass as function arguments. Order matters since this// will simply map ":id" to $articleId in your action->setPass(['id', 'slug'])// Define a pattern that `id` must match.
->setPatterns(['id' => '[0-9]+',]);});Now thanks to the reverse routing capabilities, you can pass in the URL array like below and CakePHP will know how
to form the URL as defined in the routes:// view.ctp// This will return a link to /blog/3-CakePHP_Rocksecho $this->Html->link('CakePHP Rocks', ['controller' => 'Blog','action' => 'view','id' => 3,'slug' => 'CakePHP_Rocks']);// You can also used numerically indexed parameters.
echo $this->Html->link('CakePHP Rocks', ['controller' => 'Blog','action' => 'view',(continues on next page)

Connecting Routes

237CakePHP Book, Release 3.10

(continued from previous page)3,'CakePHP_Rocks']);

Using Named Routes
Sometimes you’ll find typing out all the URL parameters for a route too verbose, or you’d like to take advantage ofthe performance improvements that named routes have. When connecting routes you can specifiy a _name option, thisoption can be used in reverse routing to identify the route you want to use:// Connect a route with a name.
$routes->connect('/login',['controller' => 'Users', 'action' => 'login'],['_name' => 'login']);// Name a verb specific route (3.5.0+)$routes->post('/logout',['controller' => 'Users', 'action' => 'logout'],'logout');// Generate a URL using a named route.
$url = Router::url(['_name' => 'logout']);// Generate a URL using a named route,// with some query string args.
$url = Router::url(['_name' => 'login', 'username' => 'jimmy']);If your route template contains any route elements like :controller you’ll need to supply those as part of the options
to Router::url().
Note: Route names must be unique across your entire application. The same _name cannot be used twice, even if thenames occur inside a different routing scope.
When building named routes, you will probably want to stick to some conventions for the route names. CakePHP
makes building up route names easier by allowing you to define name prefixes in each scope:
Router::scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) {// This route's name will be `api:ping`$routes->get('/ping', ['controller' => 'Pings'], 'ping');});// Generate a URL for the ping route
Router::url(['_name' => 'api:ping']);// Use namePrefix with plugin()
Router::plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder
˓→$routes) {(continues on next page)

238

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page)// Connect routes.
});// Or with prefix()
Router::prefix('Admin', ['_namePrefix' => 'admin:'], function (RouteBuilder $routes) {// Connect routes.
});
You can also use the _namePrefix option inside nested scopes and it works as you’d expect:
Router::plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder
˓→$routes) {$routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) {// This route's name will be `contacts:api:ping`$routes->get('/ping', ['controller' => 'Pings'], 'ping');});});// Generate a URL for the ping route
Router::url(['_name' => 'contacts:api:ping']);Routes connected in named scopes will only have names added if the route is also named. Nameless routes will nothave the _namePrefix applied to them.
New in version 3.1: The _namePrefix option was added in 3.1

Prefix Routing
static Cake\Routing\Router::prefix($name, $callback)
Many applications require an administration section where privileged users can make changes. This is often done
through a special URL such as /admin/users/edit/5. In CakePHP, prefix routing can be enabled by using theprefix scope method:use Cake\Routing\Route\DashedRoute;
Router::prefix('admin', function (RouteBuilder $routes) {// All routes here will be prefixed with `/admin`// And have the prefix => admin route element added.
$routes->fallbacks(DashedRoute::class);});
Prefixes are mapped to sub-namespaces in your application’s Controller namespace. By having prefixes as separate
controllers you can create smaller and simpler controllers. Behavior that is common to the prefixed and non-prefixed
controllers can be encapsulated using inheritance, Components, or traits. Using our users example, accessing the URL/admin/users/edit/5 would call the edit() method of our src/Controller/Admin/UsersController.php passing
5 as the first parameter. The view file used would be src/Template/Admin/Users/edit.ctp
You can map the URL /admin to your index() action of pages controller using following route:
Router::prefix('admin', function (RouteBuilder $routes) {// Because you are in the admin scope,// you do not need to include the /admin prefix(continues on next page)

Connecting Routes

239

CakePHP Book, Release 3.10

(continued from previous page)// or the admin route element.
$routes->connect('/', ['controller' => 'Pages', 'action' => 'index']);});When creating prefix routes, you can set additional route parameters using the $options argument:
Router::prefix('admin', ['param' => 'value'], function (RouteBuilder $routes) {// Routes connected here are prefixed with '/admin' and// have the 'param' routing key set.
$routes->connect('/:controller');});
Make sure to set a path for multi word prefixes to keep the desired inflection:
Router::prefix('my_prefix', ['path' => '/my-prefix'], function (RouteBuilder $routes) {// Routes connected here are prefixed with '/my-prefix'$routes->connect('/:controller');});
You can define prefixes inside plugin scopes as well:
Router::plugin('DebugKit', ['path' => '/debug-kit'], function (RouteBuilder $routes) {$routes->prefix('admin', function (RouteBuilder $routes) {$routes->connect('/:controller');});});
The above would create a route template like /debug-kit/admin/:controller. The connected route would havethe plugin and prefix route elements set.
When defining prefixes, you can nest multiple prefixes if necessary:
Router::prefix('manager', function (RouteBuilder $routes) {$routes->prefix('admin', function (RouteBuilder $routes) {$routes->connect('/:controller');});});
The above would create a route template like /manager/admin/:controller. The connected route would have theprefix route element set to manager/admin.
The current prefix will be available from the controller methods through $this->request->getParam('prefix')
When using prefix routes it’s important to set the prefix option. Here’s how to build this link using the HTML helper:// Go into a prefixed route.
echo $this->Html->link('Manage articles',['prefix' => 'manager', 'controller' => 'Articles', 'action' => 'add']);// Leave a prefix
echo $this->Html->link('View Post',(continues on next page)

240

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page)['prefix' => false, 'controller' => 'Articles', 'action' => 'view', 5]);Note: You should connect prefix routes before you connect fallback routes.

Creating Links to Prefix Routes
You can create links that point to a prefix, by adding the prefix key to your URL array:echo $this->Html->link('New admin todo',['prefix' => 'admin', 'controller' => 'TodoItems', 'action' => 'create']);
When using nesting, you need to chain them together:echo $this->Html->link('New todo',['prefix' => 'admin/my_prefix', 'controller' => 'TodoItems', 'action' => 'create']);
This would link to a controller with the namespace App\\Controller\\Admin\\MyPrefix and the file path src/
Controller/Admin/MyPrefix/TodoItemsController.php.
Note: The prefix is always under_scored here, even if the routing result is dashed. The route itself will do the inflection
if necessary.

Plugin Routing
static Cake\Routing\Router::plugin($name, $options = [], $callback)
Routes for Plugins should be created using the plugin() method. This method creates a new routing scope for theplugin’s routes:
Router::plugin('DebugKit', function (RouteBuilder $routes) {// Routes connected here are prefixed with '/debug_kit' and// have the plugin route element set to 'DebugKit'.
$routes->connect('/:controller');});
When creating plugin scopes, you can customize the path element used with the path option:
Router::plugin('DebugKit', ['path' => '/debugger'], function (RouteBuilder $routes) {// Routes connected here are prefixed with '/debugger' and// have the plugin route element set to 'DebugKit'.
$routes->connect('/:controller');});
When using scopes you can nest plugin scopes within prefix scopes:
Connecting Routes

241CakePHP Book, Release 3.10

Router::prefix('admin', function (RouteBuilder $routes) {$routes->plugin('DebugKit', ['path' => '/debug-kit'], function (RouteBuilder
˓→$routes) {$routes->connect('/:controller');});});
The above would create a route that looks like /admin/debug-kit/:controller. It would have the prefix, andplugin route elements set. The Plugin Routes section has more information on building plugin routes.

Creating Links to Plugin Routes
You can create links that point to a plugin, by adding the plugin key to your URL array:echo $this->Html->link('New todo',['plugin' => 'Todo', 'controller' => 'TodoItems', 'action' => 'create']);
Conversely if the active request is a plugin request and you want to create a link that has no plugin you can do thefollowing:echo $this->Html->link('New todo',['plugin' => null, 'controller' => 'Users', 'action' => 'profile']);
By setting 'plugin' => null you tell the Router that you want to create a link that is not part of a plugin.

SEO-Friendly Routing
Some developers prefer to use dashes in URLs, as it’s perceived to give better search engine rankings. The
DashedRoute class can be used in your application with the ability to route plugin, controller, and camelized action
names to a dashed URL.
For example, if we had a ToDo plugin, with a TodoItems controller, and a showItems() action, it could be accessed
at /to-do/todo-items/show-items with the following router connection:
use Cake\Routing\Route\DashedRoute;
Router::plugin('ToDo', ['path' => 'to-do'], function (RouteBuilder $routes) {$routes->fallbacks(DashedRoute::class);
});

242

Chapter 8. Routing

CakePHP Book, Release 3.10

Matching Specific HTTP Methods
Routes can match specific HTTP methods using the HTTP verb helper methods:
Router::scope('/', function (RouteBuilder $routes) {// This route only matches on POST requests.
$routes->post('/reviews/start',['controller' => 'Reviews', 'action' => 'start']);// Match multiple verbs// Prior to 3.5 use $options['_method'] to set method$routes->connect('/reviews/start',['controller' => 'Reviews','action' => 'start',])->setMethods(['POST', 'PUT']);});
You can match multiple HTTP methods by using an array. Because the _method parameter is a routing key, it participates in both URL parsing and URL generation. To generate URLs for method specific routes you’ll need to include
the _method key when generating the URL:
$url = Router::url(['controller' => 'Reviews','action' => 'start','_method' => 'POST',]);

Matching Specific Hostnames
Routes can use the _host option to only match specific hosts. You can use the *. wildcard to match any subdomain:
Router::scope('/', function (RouteBuilder $routes) {// This route only matches on http://images.example.com// Prior to 3.5 use the _host option$routes->connect('/images/default-logo.png',['controller' => 'Images', 'action' => 'default'])->setHost('images.example.com');// This route only matches on http://*.example.com$routes->connect('/images/old-log.png',['controller' => 'Images', 'action' => 'oldLogo'])->setHost('*.example.com');});
The _host option is also used in URL generation. If your _host option specifies an exact domain, that domain will
be included in the generated URL. However, if you use a wildcard, then you will need to provide the _host parameter

Connecting Routes

243CakePHP Book, Release 3.10

when generating URLs:// If you have this route$routes->connect('/images/old-log.png',['controller' => 'Images', 'action' => 'oldLogo'])->setHost('images.example.com');// You need this to generate a urlecho Router::url(['controller' => 'Images','action' => 'oldLogo','_host' => 'images.example.com',]);
New in version 3.4.0: The _host option was added in 3.4.0

Routing File Extensions
static Cake\Routing\Router::extensions(string|array|null $extensions, $merge = true)
To handle different file extensions with your routes, you can define extensions on a global, as well as on a scoped level.
Defining global extensions can be achieved via the routers static Router::extensions() method:
Router::extensions(['json', 'xml']);// ...
This will affect all routes that are being connected afterwards, no matter their scope.
In order to restrict extensions to specific scopes, you can define them using the Cake\Routing\RouteBuilder::setExtensions() method:
Router::scope('/', function (RouteBuilder $routes) {// Prior to 3.5.0 use `extensions()`$routes->setExtensions(['json', 'xml']);});This will enable the named extensions for all routes that are being connected in that scope after the setExtensions()
call, including those that are being connected in nested scopes. Similar to the global Router::extensions() method,
any routes connected prior to the call will not inherit the extensions.
Note: Setting the extensions should be the first thing you do in a scope, as the extensions will only be applied to routes
connected after the extensions are set.
Also be aware that re-opened scopes will not inherit extensions defined in previously opened scopes.
By using extensions, you tell the router to remove any matching file extensions, and then parse what remains. If you
want to create a URL such as /page/title-of-page.html you would create your route using:Router::scope('/page', function (RouteBuilder $routes) {// Prior to 3.5.0 use `extensions()`$routes->setExtensions(['json', 'xml', 'html']);$routes->connect((continues on next page)244

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page)'/:title',['controller' => 'Pages', 'action' => 'view'])->setPass(['title']);});Then to create links which map back to the routes simply use:
$this->Html->link('Link title',['controller' => 'Pages', 'action' => 'view', 'title' => 'super-article', '_ext' =>˓→'html']);
File extensions are used by Request Handling to do automatic view switching based on content types.

Connecting Scoped Middleware
While Middleware can be applied to your entire application, applying middleware to specific routing scopes offers more
flexibility, as you can apply middleware only where it is needed allowing your middleware to not concern itself withhow/where it is being applied.
Note: Applied scoped middleware will be run by RoutingMiddleware, normally at the end of your application’s
middleware queue.
Before middleware can be applied to a scope, it needs to be registered into the route collection:// in config/routes.php
use Cake\Http\Middleware\CsrfProtectionMiddleware;
use Cake\Http\Middleware\EncryptedCookieMiddleware;
Router::scope('/', function (RouteBuilder $routes) {$routes->registerMiddleware('csrf', new CsrfProtectionMiddleware());$routes->registerMiddleware('cookies', new EncryptedCookieMiddleware());});
Once registered, scoped middleware can be applied to specific scopes:$routes->scope('/cms', function (RouteBuilder $routes) {// Enable CSRF & cookies middleware$routes->applyMiddleware('csrf', 'cookies');$routes->get('/articles/:action/*', ['controller' => 'Articles'])});In situations where you have nested scopes, inner scopes will inherit the middleware applied in the containing scope:$routes->scope('/api', function (RouteBuilder $routes) {$routes->applyMiddleware('ratelimit', 'auth.api');$routes->scope('/v1', function (RouteBuilder $routes) {$routes->applyMiddleware('v1compat');// Define routes here.
(continues on next page)

Connecting Scoped Middleware245

CakePHP Book, Release 3.10

(continued from previous page)});});In the above example, the routes defined in /v1 will have ‘ratelimit’, ‘auth.api’, and ‘v1compat’ middleware applied.
If you re-open a scope, the middleware applied to routes in each scope will be isolated:$routes->scope('/blog', function (RouteBuilder $routes) {$routes->applyMiddleware('auth');// Connect the authenticated actions for the blog here.
});$routes->scope('/blog', function (RouteBuilder $routes) {// Connect the public actions for the blog here.
});
In the above example, the two uses of the /blog scope do not share middleware. However, both of these scopes will
inherit middleware defined in their enclosing scopes.

Grouping Middleware
To help keep your route code DRY (Do not Repeat Yourself) middleware can be combined into groups. Once combinedgroups can be applied like middleware can:$routes->registerMiddleware('cookie', new EncryptedCookieMiddleware());$routes->registerMiddleware('auth', new AuthenticationMiddleware());$routes->registerMiddleware('csrf', new CsrfProtectionMiddleware());$routes->middlewareGroup('web', ['cookie', 'auth', 'csrf']);// Apply the group$routes->applyMiddleware('web');
New in version 3.5.0: Scoped middleware & middleware groups were added in 3.5.0

RESTful Routing
Router makes it easy to generate RESTful routes for your controllers. RESTful routes are helpful when you are creating
API endpoints for your application. If we wanted to allow REST access to a recipe controller, we’d do something likethis:// In config/routes.php...
Router::scope('/', function (RouteBuilder $routes) {// Prior to 3.5.0 use `extensions()`$routes->setExtensions(['json']);$routes->resources('Recipes');});
The first line sets up a number of default routes for easy REST access where method specifies the desired result format(e.g. xml, json, rss). These routes are HTTP Request Method sensitive.

246

Chapter 8. Routing

CakePHP Book, Release 3.10

HTTP format

URL.format

Controller action invoked

GET
GET
POST
PUT
PATCH
DELETE/recipes.format/recipes/123.format/recipes.format/recipes/123.format/recipes/123.format/recipes/123.format

RecipesController::index()
RecipesController::view(123)RecipesController::add()
RecipesController::edit(123)RecipesController::edit(123)RecipesController::delete(123)

The HTTP method being used is detected from a few different sources. The sources in order of preference are:
1. The _method POST variable
2. The X_HTTP_METHOD_OVERRIDE header.
3. The REQUEST_METHOD header
The _method POST variable is helpful in using a browser as a REST client (or anything else that can do POST). Just
set the value of _method to the name of the HTTP request method you wish to emulate.

Creating Nested Resource Routes
Once you have connected resources in a scope, you can connect routes for sub-resources as well. Sub-resource routes
will be prepended by the original resource name and a id parameter. For example:
Router::scope('/api', function (RouteBuilder $routes) {$routes->resources('Articles', function (RouteBuilder $routes) {$routes->resources('Comments');});});
Will generate resource routes for both articles and comments. The comments routes will look like:/api/articles/:article_id/comments/api/articles/:article_id/comments/:id
You can get the article_id in CommentsController by:$this->request->getParam('article_id');
By default resource routes map to the same prefix as the containing scope. If you have both nested and non-nested
resource controllers you can use a different controller in each context by using prefixes:
Router::scope('/api', function (RouteBuilder $routes) {$routes->resources('Articles', function (RouteBuilder $routes) {$routes->resources('Comments', ['prefix' => 'articles']);});});
The above would map the ‘Comments’ resource to the App\Controller\Articles\CommentsController. Having
separate controllers lets you keep your controller logic simpler. The prefixes created this way are compatible with Prefix
Routing.

RESTful Routing

247

CakePHP Book, Release 3.10

Note: While you can nest resources as deeply as you require, it is not recommended to nest more than 2 resources
together.
New in version 3.3: The prefix option was added to resources() in 3.3.

Limiting the Routes Created
By default CakePHP will connect 6 routes for each resource. If you’d like to only connect specific resource routes you
can use the only option:$routes->resources('Articles', ['only' => ['index', 'view']]);
Would create read only resource routes. The route names are create, update, view, index, and delete.

Changing the Controller Actions Used
You may need to change the controller action names that are used when connecting routes. For example, if your edit()action is called put() you can use the actions key to rename the actions used:$routes->resources('Articles', ['actions' => ['update' => 'put', 'create' => 'add']]);
The above would use put() for the edit() action, and add() instead of create().

Mapping Additional Resource Routes
You can map additional resource methods using the map option:$routes->resources('Articles', ['map' => ['deleteAll' => ['action' => 'deleteAll','method' => 'DELETE']]]);// This would connect /articles/deleteAll
In addition to the default routes, this would also connect a route for /articles/delete_all. By default the path segment
will match the key name. You can use the ‘path’ key inside the resource definition to customize the path name:$routes->resources('Articles', ['map' => ['updateAll' => ['action' => 'updateAll','method' => 'DELETE','path' => '/update-many'(continues on next page)

248

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page)

],
]
]);
// This would connect /articles/update-many
If you define ‘only’ and ‘map’, make sure that your mapped methods are also in the ‘only’ list.

Prefixed Resource Routing
Resource routes can be connected to controllers in routing prefixes by connecting routes within a prefixed scope or byusing the prefix option:$routes->resources('Articles', ['prefix' => 'Api',]);

Custom Route Classes for Resource Routes
You can provide connectOptions key in the $options array for resources() to provide custom setting used byconnect():
Router::scope('/', function (RouteBuilder $routes) {$routes->resources('Books', ['connectOptions' => ['routeClass' => 'ApiRoute',
]
];
});

URL Inflection for Resource Routes
By default, multi-worded controllers’ URL fragments are the underscored form of the controller’s name. E.g.,
BlogPostsController’s URL fragment would be /blog_posts.
You can specify an alternative inflection type using the inflect option:
Router::scope('/', function (RouteBuilder $routes) {$routes->resources('BlogPosts', ['inflect' => 'dasherize' // Will use ``Inflector::dasherize()``]);});
The above will generate URLs styled like: /blog-posts.
Note: As of CakePHP 3.1 the official app skeleton uses DashedRoute as its default route class. Using the 'inflect'=> 'dasherize' option when connecting resource routes is recommended for URL consistency.

RESTful Routing249

CakePHP Book, Release 3.10

Changing the Path Element
By default resource routes use an inflected form of the resource name for the URL segment. You can set a custom URL
segment with the path option:
Router::scope('/', function (RouteBuilder $routes) {$routes->resources('BlogPosts', ['path' => 'posts']);});
New in version 3.5.0: The path option was added in 3.5.0

Passed Arguments
Passed arguments are additional arguments or path segments that are used when making a request. They are often used
to pass parameters to your controller methods.
http://localhost/calendars/view/recent/markIn the above example, both recent and mark are passed arguments to CalendarsController::view(). Passed
arguments are given to your controllers in three ways. First as arguments to the action method called, and secondly
they are available in $this->request->getParam('pass') as a numerically indexed array. When using custom
routes you can force particular parameters to go into the passed arguments as well.
If you were to visit the previously mentioned URL, and you had a controller action that looked like:class CalendarsController extends AppController{
public function view($arg1, $arg2){
debug(func_get_args());}}
You would get the following output:
Array([0] => recent[1] => mark)This same data is also available at $this->request->getParam('pass') in your controllers, views, and helpers.
The values in the pass array are numerically indexed based on the order they appear in the called URL:
debug($this->request->getParam('pass'));Either of the above would output:
Array([0] => recent[1] => mark)250

Chapter 8. Routing

CakePHP Book, Release 3.10

When generating URLs, using a routing array you add passed arguments as values without string keys in the array:['controller' => 'Articles', 'action' => 'view', 5]Since 5 has a numeric key, it is treated as a passed argument.

Generating URLs
static Cake\Routing\Router::url($url = null, $full = false)
Generating URLs or Reverse routing is a feature in CakePHP that is used to allow you to change your URL structure
without having to modify all your code. By using routing arrays to define your URLs, you can later configure routes
and the generated URLs will automatically update.
If you create URLs using strings like:$this->Html->link('View', '/articles/view/' . $id);
And then later decide that /articles should really be called ‘posts’ instead, you would have to go through your entire
application renaming URLs. However, if you defined your link like:$this->Html->link('View',['controller' => 'Articles', 'action' => 'view', $id]);
Then when you decided to change your URLs, you could do so by defining a route. This would change both theincoming URL mapping, as well as the generated URLs.
When using array URLs, you can define both query string parameters and document fragments using special keys:
Router::url(['controller' => 'Articles','action' => 'index','?' => ['page' => 1],'#' => 'top']);// Will generate a URL like.
/articles/index?page=1#top
Router will also convert any unknown parameters in a routing array to querystring parameters. The ? is offered forbackwards compatibility with older versions of CakePHP.
You can also use any of the special route elements when generating URLs:• _ext Used for Routing File Extensions routing.
• _base Set to false to remove the base path from the generated URL. If your application is not in the root
directory, this can be used to generate URLs that are ‘cake relative’.
• _scheme Set to create links on different schemes like webcal or ftp. Defaults to the current scheme.
• _host Set the host to use for the link. Defaults to the current host.
• _port Set the port if you need to create links on non-standard ports.
• _method Define the HTTP verb the URL is for.
Generating URLs

251

CakePHP Book, Release 3.10

• _full If true the FULL_BASE_URL constant will be prepended to generated URLs.
• _ssl Set to true to convert the generated URL to https or false to force http.
• _name Name of route. If you have setup named routes, you can use this key to specify it.

Redirect Routing
Redirect routing allows you to issue HTTP status 30x redirects for incoming routes, and point them at different URLs.
This is useful when you want to inform client applications that a resource has moved and you don’t want to expose two
URLs for the same content.
Redirection routes are different from normal routes as they perform an actual header redirection if a match is found.
The redirection can occur to a destination within your application or an outside location:
Router::scope('/', function (RouteBuilder $routes) {$routes->redirect('/home/*',['controller' => 'Articles', 'action' => 'view'],['persist' => true]// Or ['persist'=>['id']] for default routing where the// view action expects $id as an argument.
);})
Redirects /home/* to /articles/view and passes the parameters to /articles/view. Using an array as the redirect
destination allows you to use other routes to define where a URL string should be redirected to. You can redirect toexternal locations using string URLs as the destination:
Router::scope('/', function (RouteBuilder $routes) {$routes->redirect('/articles/*', 'https://google.com', ['status' => 302]);});
This would redirect /articles/* to https://google.com with a HTTP status of 302.

Entity Routing
Entity routing allows you to use an entity, an array or object implement ArrayAccess as the source of routing parameters. This allows you to refactor routes more easily, and generate URLs with less code. For example, if you start off
with a route that looks like:$routes->get('/view/:id',['controller' => 'Articles', 'action' => 'view'],'articles:view');
You can generate URLs to this route using:// $article is an entity in the local scope.
Router::url(['_name' => 'articles:view', 'id' => $article->id]);252

Chapter 8. Routing

CakePHP Book, Release 3.10

Later on, you may want to expose the article slug in the URL for SEO purposes. In order to do this you would need
to update everywhere you generate a URL to the articles:view route, which could take some time. If we use entity
routes we pass the entire article entity into URL generation allowing us to skip any rework when URLs require moreparameters:
use Cake\Routing\Route\EntityRoute;// Create entity routes for the rest of this scope.
$routes->setRouteClass(EntityRoute::class);// Create the route just like before.
$routes->get('/view/:id',['controller' => 'Articles', 'action' => 'view'],'articles:view');Now we can generate URLs using the _entity key:
Router::url(['_name' => 'articles:view', '_entity' => $article]);This will extract both the id property and the slug property out of the provided entity.
New in version 3.6.0: Entity routing was added in 3.6.0

Custom Route Classes
Custom route classes allow you to extend and change how individual routes parse requests and handle reverse routing.
Route classes have a few conventions:• Route classes are expected to be found in the Routing\\Route namespace of your application or plugin.
• Route classes should extend Cake\Routing\Route.
• Route classes should implement one or both of match() and/or parse().
The parse() method is used to parse an incoming URL. It should generate an array of request parameters that can be
resolved into a controller & action. Return false from this method to indicate a match failure.
The match() method is used to match an array of URL parameters and create a string URL. If the URL parameters do
not match the route false should be returned.
You can use a custom route class when making a route by using the routeClass option:$routes->connect('/:slug',['controller' => 'Articles', 'action' => 'view'],['routeClass' => 'SlugRoute']);// Or by setting the routeClass in your scope.
$routes->scope('/', function (RouteBuilder $routes) {//Prior to 3.5.0 use `routeClass()`$routes->setRouteClass('SlugRoute');$routes->connect('/:slug',(continues on next page)

Custom Route Classes

253

CakePHP Book, Release 3.10

(continued from previous page)['controller' => 'Articles', 'action' => 'view']);});
This route would create an instance of SlugRoute and allow you to implement custom parameter handling. You can
use plugin route classes using standard plugin syntax.

Default Route Classstatic Cake\Routing\Router::defaultRouteClass($routeClass = null)If you want to use an alternate route class for all your routes besides the default Route, you can do so by calling
Router::defaultRouteClass() before setting up any routes and avoid having to specify the routeClass option
for each route. For example using:use Cake\Routing\Route\InflectedRoute;
Router::defaultRouteClass(InflectedRoute::class);
will cause all routes connected after this to use the InflectedRoute route class. Calling the method without anargument will return current default route class.

Fallbacks Method
Cake\Routing\Router::fallbacks($routeClass = null)
The fallbacks method is a simple shortcut for defining default routes. The method uses the passed routing class for thedefined rules or if no class is provided the class returned by Router::defaultRouteClass() is used.
Calling fallbacks like so:use Cake\Routing\Route\DashedRoute;$routes->fallbacks(DashedRoute::class);
Is equivalent to the following explicit calls:
use Cake\Routing\Route\DashedRoute;$routes->connect('/:controller', ['action' => 'index'], ['routeClass' =>␣
˓→DashedRoute::class]);$routes->connect('/:controller/:action/*', [], ['routeClass' => DashedRoute::class]);

Note: Using the default route class (Route) with fallbacks, or any route with :plugin and/or :controller routeelements will result in inconsistent URL case.

254

Chapter 8. Routing

CakePHP Book, Release 3.10

Creating Persistent URL Parameters
You can hook into the URL generation process using URL filter functions. Filter functions are called before the URLs
are matched against the routes, this allows you to prepare URLs before routing.
Callback filter functions should expect the following parameters:• $params The URL parameter array being processed.
• $request The current request (Cake\Http\ServerRequest instance).
The URL filter function should always return the parameters even if unmodified.
URL filters allow you to implement features like persistent parameters:
Router::addUrlFilter(function (array $params, ServerRequest $request) {if ($request->getParam('lang') && !isset($params['lang'])) {$params['lang'] = $request->getParam('lang');}
return $params;});
Filter functions are applied in the order they are connected.
Another use case is changing a certain route on runtime (plugin routes for example):
Router::addUrlFilter(function (array $params, ServerRequest $request) {if (empty($params['plugin']) || $params['plugin'] !== 'MyPlugin' || empty($params[
˓→'controller'])) {return $params;}
if ($params['controller'] === 'Languages' && $params['action'] === 'view') {$params['controller'] = 'Locations';$params['action'] = 'index';$params['language'] = $params[0];unset($params[0]);}return $params;});
This will alter the following route:
Router::url(['plugin' => 'MyPlugin', 'controller' => 'Languages', 'action' => 'view', 'es
˓→']);
into this:Router::url(['plugin' => 'MyPlugin', 'controller' => 'Locations', 'action' => 'index',
˓→'language' => 'es']);Warning: If you are using the caching features of routing-middleware you must define the URL filters in yourapplication bootstrap() as filters are not part of the cached data.

Creating Persistent URL Parameters

255

CakePHP Book, Release 3.10

Handling Named Parameters in URLs
Although named parameters were removed in CakePHP 3.0, applications may have published URLs containing them.
You can continue to accept URLs containing named parameters.
In your controller’s beforeFilter() method you can call parseNamedParams() to extract any named parametersfrom the passed arguments:
public function beforeFilter(Event $event){parent::beforeFilter($event);$this->request = Router::parseNamedParams($this->request);}
This will populate $this->request->getParam('named') with any named parameters found in the passed arguments. Any passed argument that was interpreted as a named parameter, will be removed from the list of passed
arguments.

Dispatcher Filters
Deprecated since version 3.3.0: As of 3.3.0 Dispatcher Filters are deprecated. You should use /controllers/middleware
instead now.
There are several reasons to want a piece of code to be run before any controller code is executed or right before theresponse is sent to the client, such as response caching, header tuning, special authentication or just to provide accessto a mission-critical API response in lesser time than a complete request dispatching cycle would take.
CakePHP provides a clean interface for attaching filters to the dispatch cycle. It is similar to a middleware layer, but
re-uses the existing event subsystem used in other parts of CakePHP. Since they do not work exactly like traditional
middleware, we refer to them as Dispatcher Filters.
Built-in Filters
CakePHP comes with several dispatcher filters built-in. They handle common features that all applications are likely
to need. The built-in filters are:
• AssetFilter checks whether the request is referring to a theme or plugin asset file, such as a CSS, JavaScript
or image file stored in either a plugin’s webroot folder or the corresponding one for a Theme. It will serve thefile accordingly if found, stopping the rest of the dispatching cycle:// Use options to set cacheTime for your static assets// If not set, this defaults to +1 hour
DispatcherFactory::add('Asset', ['cacheTime' => '+24 hours']);• RoutingFilter applies application routing rules to the request URL. Populates $request->getParam() withthe results of routing.
• ControllerFactory uses $request->getParam() to locate the controller that will handle the current request.
• LocaleSelector enables automatic language switching from the Accept-Language header sent by thebrowser.

256

Chapter 8. Routing

CakePHP Book, Release 3.10

Using Filters
Filters are usually enabled in your application’s bootstrap.php file, but you could load them any time before the request
is dispatched. Adding and removing filters is done through Cake\Routing\DispatcherFactory. By default, the
CakePHP application template comes with a couple filter classes already enabled for all requests; let’s take a look at
how they are added:
DispatcherFactory::add('Routing');
DispatcherFactory::add('ControllerFactory');// Plugin syntax is also possible
DispatcherFactory::add('PluginName.DispatcherName');// Use options to set priority
DispatcherFactory::add('Asset', ['priority' => 1]);
Dispatcher filters with higher priority (lower numbers) - will be executed first. Priority defaults to 10.
While using the string name is convenient, you can also pass instances into add():
use Cake\Routing\Filter\RoutingFilter;
DispatcherFactory::add(new RoutingFilter());

Configuring Filter Order
When adding filters, you can control the order they are invoked in using event handler priorities. While filters candefine a default priority using the $_priority property, you can set a specific priority when attaching the filter:
DispatcherFactory::add('Asset', ['priority' => 1]);
DispatcherFactory::add(new AssetFilter(['priority' => 1]));
The higher the priority the later this filter will be invoked.
Conditionally Applying Filters
If you don’t want to run a filter on every request, you can use conditions to only apply it some of the time. You canapply conditions using the for and when options. The for option lets you match on URL substrings, while the when
option allows you to run a callable:// Only runs on requests starting with `/blog`
DispatcherFactory::add('BlogHeader', ['for' => '/blog']);// Only run on GET requests.
DispatcherFactory::add('Cache', ['when' => function ($request, $response) {return $request->is('get');}]);The callable provided to when should return true when the filter should run. The callable can expect to get the current
request and response as arguments.

Handling Named Parameters in URLs

257

CakePHP Book, Release 3.10

Building a Filter
To create a filter, define a class in src/Routing/Filter. In this example, we’ll be making a filter that adds a tracking
cookie for the first landing page. First, create the file. Its contents should look like:namespace App\Routing\Filter;
use Cake\Event\Event;use Cake\Routing\DispatcherFilter;class TrackingCookieFilter extends DispatcherFilter{
public function beforeDispatch(Event $event){$request = $event->getData('request');$response = $event->getData('response');if (!$request->getCookie('landing_page')) {$response->cookie(['name' => 'landing_page','value' => $request->here(),'expire' => '+ 1 year',
]);
}
}
}
Save this file into src/Routing/Filter/TrackingCookieFilter.php. As you can see, like other classes in CakePHP,
dispatcher filters have a few conventions:• Class names end in Filter.
• Classes are in the Routing\Filter namespace. For example, App\Routing\Filter.
• Generally filters extend Cake\Routing\DispatcherFilter.
DispatcherFilter exposes two methods that can be overridden in subclasses, they are beforeDispatch() andafterDispatch(). These methods are executed before or after any controller is executed respectively. Bothmethods receive a Cake\Event\Event object containing the ServerRequest and Response objects (Cake\Http\
ServerRequest and Cake\Http\Response instances) inside the $data property.
While our filter was pretty simple, there are a few other interesting things we can do in filter methods. By returning
an Response object, you can short-circuit the dispatch process and prevent the controller from being called. When
returning a response, you should also remember to call $event->stopPropagation() so other filters are not called.
Note: When a beforeDispatch method returns a response, the controller, and afterDispatch event will not be invoked.
Let’s now create another filter for altering response headers in any public page, in our case it would be anything served
from the PagesController:
namespace App\Routing\Filter;
use Cake\Event\Event;use Cake\Routing\DispatcherFilter;class HttpCacheFilter extends DispatcherFilter(continues on next page)

258

Chapter 8. Routing

CakePHP Book, Release 3.10

(continued from previous page){
public function afterDispatch(Event $event){$request = $event->getData('request');$response = $event->getData('response');if ($response->statusCode() === 200) {$response->sharable(true);$response->expires(strtotime('+1 day'));}}}// In our bootstrap.php
DispatcherFactory::add('HttpCache', ['for' => '/pages'])This filter will send a expiration header to 1 day in the future for all responses produced by the pages controller.
You could of course do the same in the controller, this is just an example of what could be done with filters. For
instance, instead of altering the response, you could cache it using Cake\Cache\Cache and serve the response fromthe beforeDispatch() callback.
While powerful, dispatcher filters have the potential to make your application more difficult to maintain. Filters are an
extremely powerful tool when used wisely and adding response handlers for each URL in your app is not a good use forthem. Keep in mind that not everything needs to be a filter; Controllers and Components are usually a more accurate
choice for adding any request handling code to your app.

Handling Named Parameters in URLs

259

CakePHP Book, Release 3.10

260

Chapter 8. Routing

CHAPTER 9

Request & Response Objects

The request and response objects provide an abstraction around HTTP requests and responses. The request object in
CakePHP allows you to introspect an incoming request, while the response object allows you to effortlessly create
HTTP responses from your controllers.

Requestclass Cake\Http\ServerRequest
ServerRequest is the default request object used in CakePHP. It centralizes a number of features for interrogating
and interacting with request data. On each request one Request is created and then passed by reference to the various
layers of an application that use request data. By default the request is assigned to $this->request, and is available
in Controllers, Cells, Views and Helpers. You can also access it in Components using the controller reference. Someof the duties ServerRequest performs include:• Processing the GET, POST, and FILES arrays into the data structures you are familiar with.
• Providing environment introspection pertaining to the request. Information like the headers sent, the client’s IP
address, and the subdomain/domain names the server your application is running on.
• Providing access to request parameters both as array indexes and object properties.
As of 3.4.0, CakePHP’s request object implements the PSR-7 ServerRequestInterface115 making it easier to use libraries
from outside of CakePHP.
115 https://www.php-fig.org/psr/psr-7/

261

CakePHP Book, Release 3.10

Request Parameters
The request exposes routing parameters through the getParam() method:$controllerName = $this->request->getParam('controller');// Prior to 3.4.0$controllerName = $this->request->param('controller');
To get all routing parameters as an array use getAttribute():$parameters = $this->request->getAttribute('params');
All Route Elements are accessed through this interface.
In addition to Route Elements, you also often need access to Passed Arguments. These are both available on the request
object as well:// Passed arguments$passedArgs = $this->request->getParam('pass');
Will all provide you access to the passed arguments. There are several important/useful parameters that CakePHP uses
internally, these are also all found in the routing parameters:• plugin The plugin handling the request. Will be null when there is no plugin.
• controller The controller handling the current request.
• action The action handling the current request.
• prefix The prefix for the current action. See Prefix Routing for more information.

Query String Parameters
Cake\Http\ServerRequest::getQuery($name)Query string parameters can be read using the getQuery() method:// URL is /posts/index?page=1&sort=title$page = $this->request->getQuery('page');// Prior to 3.4.0$page = $this->request->query('page');
You can either directly access the query property, or you can use getQuery() method to read the URL query array inan error-free manner. Any keys that do not exist will return null:$foo = $this->request->getQuery('value_that_does_not_exist');// $foo === null// You can also provide default values$foo = $this->request->getQuery('does_not_exist', 'default val');If you want to access all the query parameters you can use getQueryParams():$query = $this->request->getQueryParams();

262

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

New in version 3.4.0: getQueryParams() and getQuery() were added in 3.4.0

Request Body Data
Cake\Http\ServerRequest::getData($name, $default = null)
All POST data can be accessed using Cake\Http\ServerRequest::getData(). Any form data that contains a data
prefix will have that data prefix removed. For example:// An input with a name attribute equal to 'MyModel[title]' is accessible at$title = $this->request->getData('MyModel.title');Any keys that do not exist will return null:$foo = $this->request->getData('Value.that.does.not.exist');// $foo == nullFile Uploads
Uploaded files can be accessed through the request body data, using the Cake\Http\ServerRequest::getData()
method described above. For example, a file from an input element with a name attribute of MyModel[attachment],
can be accessed like this:$attachment = $this->request->getData('MyModel.attachment');
By default file uploads are represented in the request data as arrays, with a normalized structure that remains the sameeven for nested inputs/names, which is different from how PHP represents them in the $_FILES superglobal (refer tothe PHP manual116 for more information), ie the $attachment value would look something like this:['name' => 'attachment.txt','type' => 'text/plain','size' => 123,
'tmp_name' => '/tmp/hfz6dbn.tmp''error' => 0]
Alternatively it’s possible to have CakePHP provide the uploads in the request data as objects that implement\Psr\Http\Message\UploadedFileInterface117 . In order to enable this behavior, set the configuration value App.
uploadedFilesAsObjects to true, for example in your config/app.php file:
return [// ...
'App' => [// ...
'uploadedFilesAsObjects' => true,],// ...
];
116 https://www.php.net/manual/en/features.file-upload.php
117 https://www.php-fig.org/psr/psr-7/#16-uploaded-files

Request263

CakePHP Book, Release 3.10

In the above example, $attachment would then hold an object, in the current implementation it would by default be
an instance of \Zend\Diactoros\UploadedFile.
New in version 3.9.0: Support for uploaded files as objects in the request data was added in version 3.9.0
Furthermore uploaded files can be accessed as objects separately from the request data via the Cake\
Http\ServerRequest::getUploadedFile() and Cake\Http\ServerRequest::getUploadedFiles() methods. These methods will always return objects, irrespectively of the App.uploadedFilesAsObjects configuration.
Cake\Http\ServerRequest::getUploadedFile($path)
Returns the uploaded file at a specific path.
ServerRequest::getData() method:

The path uses the same dot syntax as the Cake\Http\$attachment = $this->request->getUploadedFile('MyModel.attachment');
Unlike Cake\Http\ServerRequest::getData(), Cake\Http\ServerRequest::getUploadedFile() would
only return data when an actual file upload exists for the given path, if there is regular, non-file request body data
present at the given path, then this method will return null, just like it would for any non-existent path.
Cake\Http\ServerRequest::getUploadedFiles()Returns all uploaded files in a normalized array structure. For the above example with the file input name of
MyModel[attachment], the structure would look like:['MyModel' => ['attachment' => object(Zend\Diactoros\UploadedFile) {// ...
}]]
Cake\Http\ServerRequest::withUploadedFiles(array $files)
This method sets the uploaded files of the request object, it accepts an array of objects that implement\Psr\Http\Message\UploadedFileInterface118 . It will replace all possibly existing uploaded files:$files = ['MyModel' => ['attachment' => new \Zend\Diactoros\UploadedFile($streamOrFile,$size,$errorStatus,$clientFilename,$clientMediaType),'anotherAttachment' => new \Zend\Diactoros\UploadedFile('/tmp/hfz6dbn.tmp',
123,\UPLOAD_ERR_OK,'attachment.txt','text/plain'),(continues on next page)
118 https://www.php-fig.org/psr/psr-7/#16-uploaded-files

264

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

(continued from previous page)],];$this->request = $this->request->withUploadedFiles($files);Note: Uploaded files that have been added to the request via this method, will not be available in the request
body data, ie you cannot retrieve them via Cake\Http\ServerRequest::getData()! If you need them in therequest data (too), then you have to set them via Cake\Http\ServerRequest::withData() or Cake\Http\
ServerRequest::withParsedBody().

PUT, PATCH or DELETE Data
Cake\Http\ServerRequest::input($callback [, $options ])When building REST services, you often accept request data on PUT and DELETE requests. Any application/x-www-form-urlencoded request body data will automatically be parsed and set to $this->data for PUT and
DELETE requests. If you are accepting JSON or XML data, see below for how you can access those request bodies.
When accessing the input data, you can decode it with an optional function. This is useful when interacting withXML or JSON request body content. Additional parameters for the decoding function can be passed as arguments to
input():$jsonData = $this->request->input('json_decode');Environment Variables (from $_SERVER and $_ENV)
Cake\Http\ServerRequest::env($key, $value = null)ServerRequest::env() is a wrapper for env() global function and acts as a getter/setter for environment variables
without having to modify globals $_SERVER and $_ENV:// Get the host
$host = $this->request->env('HTTP_HOST');// Set a value, generally helpful in testing.
$this->request->env('REQUEST_METHOD', 'POST');To access all the environment variables in a request use getServerParams():$env = $this->request->getServerParams();
New in version 3.4.0: getServerParams() was added in 3.4.0

Request265

CakePHP Book, Release 3.10

XML or JSON Data
Applications employing REST often exchange data in non-URL-encoded post bodies. You can read input data in any
format using input(). By providing a decoding function, you can receive the content in a deserialized format:// Get JSON encoded data submitted to a PUT/POST action$jsonData = $this->request->input('json_decode');Some deserializing methods require additional parameters when called, such as the ‘as array’ parameter on
json_decode. If you want XML converted into a DOMDocument object, input() supports passing in additionalparameters as well:// Get XML encoded data submitted to a PUT/POST action$data = $this->request->input('Cake\Utility\Xml::build', ['return' => 'domdocument']);Path Information
The request object also provides useful information about the paths in your application. The base and webrootattributes are useful for generating URLs, and determining whether or not your application is in a subdirectory. The
attributes you can use are:// Assume the current request URL is /subdir/articles/edit/1?page=1// Holds /subdir/articles/edit/1?page=1$here = $request->getRequestTarget();// Holds /subdir$base = $request->getAttribute('base');// Holds /subdir/$base = $request->getAttribute('webroot');// Prior to 3.4.0$webroot = $request->webroot;$base = $request->base;$here = $request->here();Checking Request Conditions
Cake\Http\ServerRequest::is($type, $args...)
The request object provides an easy way to inspect certain conditions in a given request. By using the is() method
you can check a number of common conditions, as well as inspect other application specific request criteria:$isPost = $this->request->is('post');You can also extend the request detectors that are available, by using Cake\Http\ServerRequest::addDetector()
to create new kinds of detectors. There are different types of detectors that you can create:• Environment value comparison - Compares a value fetched from env() for equality with the provided value.
• Header value comparison - If the specified header exists with the specified value, or if the callable returns true.

266

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

• Pattern value comparison - Pattern value comparison allows you to compare a value fetched from env() to aregular expression.
• Option based comparison - Option based comparisons use a list of options to create a regular expression. Subsequent calls to add an already defined options detector will merge the options.
• Callback detectors - Callback detectors allow you to provide a ‘callback’ type to handle the check. The callback
will receive the request object as its only parameter.
Cake\Http\ServerRequest::addDetector($name, $options)
Some examples would be:// Add an environment detector.
$this->request->addDetector('post',['env' => 'REQUEST_METHOD', 'value' => 'POST']);// Add a pattern value detector.
$this->request->addDetector('iphone',['env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i']);// Add an option detector$this->request->addDetector('internalIp', ['env' => 'CLIENT_IP','options' => ['192.168.0.101', '192.168.0.100']]);// Add a header detector with value comparison$this->request->addDetector('fancy', ['env' => 'CLIENT_IP','header' => ['X-Fancy' => 1]]);// Add a header detector with callable comparison$this->request->addDetector('fancy', ['env' => 'CLIENT_IP','header' => ['X-Fancy' => function ($value, $header) {return in_array($value, ['1', '0', 'yes', 'no'], true);}]]);// Add a callback detector. Must be a valid callable.
$this->request->addDetector('awesome',function ($request) {return $request->getParam('awesome');});// Add a detector that uses multiple condition types(continues on next page)

Request267

CakePHP Book, Release 3.10

(continued from previous page)// If any type matches the check passes.
$this->request->addDetector('csv',['accept' => ['text/csv'],'param' => '_ext','value' => 'csv',]);
There are several built-in detectors that you can use:
• is('get') Check to see whether the current request is a GET.
• is('put') Check to see whether the current request is a PUT.
• is('patch') Check to see whether the current request is a PATCH.
• is('post') Check to see whether the current request is a POST.
• is('delete') Check to see whether the current request is a DELETE.
• is('head') Check to see whether the current request is HEAD.
• is('options') Check to see whether the current request is OPTIONS.
• is('ajax') Check to see whether the current request came with X-Requested-With = XMLHttpRequest.
• is('ssl') Check to see whether the request is via SSL.
• is('flash') Check to see whether the request has a User-Agent of Flash.
• is('requested') Check to see whether the request has a query param ‘requested’ with value 1.
• is('json') Check to see whether the request has ‘json’ extension and accept ‘application/json’ mimetype.
• is('xml') Check to see whether the request has ‘xml’ extension and accept ‘application/xml’ or ‘text/xml’
mimetype.
New in version 3.3.0: Detectors can take additional parameters as of 3.3.0.
ServerRequest also includes methods like Cake\Http\ServerRequest::domain(), Cake\Http\
ServerRequest::subdomains() and Cake\Http\ServerRequest::host() to make applications that use
subdomains simpler.

Session Data
To access the session for a given request use the session() method:$userName = $this->request->session()->read('Auth.User.name');For more information, see the Sessions documentation for how to use the session object.

268

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

Host and Domain Name
Cake\Http\ServerRequest::domain($tldLength = 1)
Returns the domain name your application is running on:// Prints 'example.org'
echo $request->domain();Cake\Http\ServerRequest::subdomains($tldLength = 1)
Returns the subdomains your application is running on as an array:// Returns ['my', 'dev'] for 'my.dev.example.org'$subdomains = $request->subdomains();Cake\Http\ServerRequest::host()
Returns the host your application is on:// Prints 'my.dev.example.org'
echo $request->host();Reading the HTTP Method
Cake\Http\ServerRequest::getMethod()
Returns the HTTP method the request was made with:// Output POST
echo $request->getMethod();// Prior to 3.4.0
echo $request->method();

Restricting Which HTTP method an Action Accepts
Cake\Http\ServerRequest::allowMethod($methods)
Set allowed HTTP methods. If not matched, will throw MethodNotAllowedException. The 405 response will
include the required Allow header with the passed methods:
public function delete(){// Only accept POST and DELETE requests$this->request->allowMethod(['post', 'delete']);...
}Request269

CakePHP Book, Release 3.10

Reading HTTP Headers
Allows you to access any of the HTTP_* headers that were used for the request. For example:// Get the header as a string$userAgent = $this->request->getHeaderLine('User-Agent');// Get an array of all values.
$acceptHeader = $this->request->getHeader('Accept');// Check if a header exists$hasAcceptHeader = $this->request->hasHeader('Accept');// Prior to 3.4.0$userAgent = $this->request->header('User-Agent');
While some apache installs don’t make the Authorization header accessible, CakePHP will make it available throughapache specific methods as required.
Cake\Http\ServerRequest::referer($local = false)
Returns the referring address for the request.
Cake\Http\ServerRequest::clientIp()
Returns the current visitor’s IP address.

Trusting Proxy Headers
If your application is behind a load balancer or running on a cloud service, you will often get the load balancer host,port and scheme in your requests. Often load balancers will also send HTTP-X-Forwarded-* headers with the originalvalues. The forwarded headers will not be used by CakePHP out of the box. To have the request object use these headers
set the trustProxy property to true:$this->request->trustProxy = true;// These methods will now use the proxied headers.
$port = $this->request->port();$host = $this->request->host();$scheme = $this->request->scheme();$clientIp = $this->request->clientIp();
Once proxies are trusted the clientIp() method will use the last IP address in the X-Forwarded-For header. If
your application is behind multiple proxies, you can use setTrustedProxies() to define the IP addresses of proxies
in your control:$request->setTrustedProxies(['127.1.1.1', '127.8.1.3']);After proxies are trusted clientIp() will use the first IP address in the X-Forwarded-For header providing it is the
only value that isn’t from a trusted proxy.
New in version 3.7.0: setTrustedProxies() was added.

270

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

Checking Accept HeadersCake\Http\ServerRequest::accepts($type = null)
Find out which content types the client accepts, or check whether it accepts a particular type of content.
Get all types:$accepts = $this->request->accepts();
Check for a single type:$acceptsJson = $this->request->accepts('application/json');Cake\Http\ServerRequest::acceptLanguage($language = null)Get all the languages accepted by the client, or check whether a specific language is accepted.
Get the list of accepted languages:$acceptsLanguages = $this->request->acceptLanguage();
Check whether a specific language is accepted:$acceptsSpanish = $this->request->acceptLanguage('es-es');

CookiesRequest cookies can be read through a number of methods:// Get the cookie value, or null if the cookie is missing.
$rememberMe = $this->request->getCookie('remember_me');// Read the value, or get the default of 0
$rememberMe = $this->request->getCookie('remember_me', 0);// Get all cookies as an hash$cookies = $this->request->getCookieParams();// Get a CookieCollection instance (starting with 3.5.0)$cookies = $this->request->getCookieCollection()
See the Cake\Http\Cookie\CookieCollection documentation for how to work with cookie collection.
New in version 3.5.0: ServerRequest::getCookieCollection() was added in 3.5.0

Request271

CakePHP Book, Release 3.10

Response
class Cake\Http\Response
Cake\Http\Response is the default response class in CakePHP. It encapsulates a number of features and functionality
for generating HTTP responses in your application. It also assists in testing, as it can be mocked/stubbed allowing you
to inspect headers that will be sent. Like Cake\Http\ServerRequest, Cake\Http\Response consolidates a numberof methods previously found on Controller, RequestHandlerComponent and Dispatcher. The old methods are
deprecated in favour of using Cake\Http\Response.
Response provides an interface to wrap the common response-related tasks such as:• Sending headers for redirects.
• Sending content type headers.
• Sending any header.
• Sending the response body.

Dealing with Content Types
Cake\Http\Response::withType($contentType = null)
You can control the Content-Type of your application’s responses with Cake\Http\Response::withType(). If yourapplication needs to deal with content types that are not built into Response, you can map them with type() as well:// Add a vCard type$this->response->type(['vcf' => 'text/v-card']);// Set the response Content-Type to vcard.
$this->response = $this->response->withType('vcf');// Prior to 3.4.0$this->response->type('vcf');
Usually, you’ll want to map additional content types in your controller’s beforeFilter() callback, so you can leverage
the automatic view switching features of RequestHandlerComponent if you are using it.

Sending Files
Cake\Http\Response::withFile($path, $options = [])There are times when you want to send files as responses for your requests. You can accomplish that by using Cake\
Http\Response::withFile():public function sendFile($id){$file = $this->Attachments->getFile($id);$response = $this->response->withFile($file['path']);// Return the response to prevent controller from trying to render// a view.
return $response;}(continues on next page)272

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

(continued from previous page)// Prior to 3.4.0$file = $this->Attachments->getFile($id);$this->response->file($file['path']);// Return the response to prevent controller from trying to render// a view.
return $this->response;
As shown in the above example, you must pass the file path to the method. CakePHP will send a proper content typeheader if it’s a known file type listed in Cake\Http\Response::$_mimeTypes. You can add new types prior to callingCake\Http\Response::withFile() by using the Cake\Http\Response::withType() method.
If you want, you can also force a file to be downloaded instead of displayed in the browser by specifying the options:$response = $this->response->withFile($file['path'],['download' => true, 'name' => 'foo']);// Prior to 3.4.0$this->response->file($file['path'],['download' => true, 'name' => 'foo']);
The supported options are:name
The name allows you to specify an alternate file name to be sent to the user.
download
A boolean value indicating whether headers should be set to force download.

Sending a String as File
You can respond with a file that does not exist on the disk, such as a pdf or an ics generated on the fly from a string:
public function sendIcs(){$icsString = $this->Calendars->generateIcs();$response = $this->response;// Inject string content into response body (3.4.0+)$response = $response->withStringBody($icsString);// Inject string content into response body (before 3.4.0)$response->body($icsString);$response = $response->withType('ics');// Optionally force file download$response = $response->withDownload('filename_for_download.ics');(continues on next page)

Response273

CakePHP Book, Release 3.10

(continued from previous page)// Return response object to prevent controller from trying to render// a view.
return $response;}
Callbacks can also return the body as a string:$path = '/some/file.png';$this->response->body(function () use ($path) {return file_get_contents($path);});

Setting HeadersCake\Http\Response::withHeader($header, $value)
Setting headers is done with the Cake\Http\Response::withHeader() method. Like all of the PSR-7 interface
methods, this method returns a new instance with the new header:// Add/replace a header$response = $response->withHeader('X-Extra', 'My header');// Set multiple headers$response = $response->withHeader('X-Extra', 'My header')->withHeader('Location', 'http://example.com');// Append a value to an existing header$response = $response->withAddedHeader('Set-Cookie', 'remember_me=1');// Prior to 3.4.0 - Set a header$this->response->header('Location', 'http://example.com');
Headers are not sent when set. Instead, they are held until the response is emitted by Cake\Http\Server.
You can now use the convenience method Cake\Http\Response::withLocation() to directly set or get the redirect
location header.

Setting the Body
Cake\Http\Response::withStringBody($string)
To set a string as the response body, do the following:// Set a string into the body$response = $response->withStringBody('My Body');// If you want a json response$response = $response->withType('application/json')->withStringBody(json_encode(['Foo' => 'bar']));New in version 3.4.3: withStringBody() was added in 3.4.3

274

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

Cake\Http\Response::withBody($body)
To set the response body, use the withBody() method, which is provided by the Zend\Diactoros\MessageTrait:$response = $response->withBody($stream);// Prior to 3.4.0 - Set the body$this->response->body('My Body');
Be sure that $stream is a Psr\Http\Message\StreamInterface object. See below on how to create a new stream.
You can also stream responses from files using Zend\Diactoros\Stream streams:// To stream from a fileuse Zend\Diactoros\Stream;$stream = new Stream('/path/to/file', 'rb');$response = $response->withBody($stream);
You can also stream responses from a callback using the CallbackStream. This is useful when you have resources
like images, CSV files or PDFs you need to stream to the client:// Streaming from a callback
use Cake\Http\CallbackStream;// Create an image.
$img = imagecreate(100, 100);// ...
$stream = new CallbackStream(function () use ($img) {imagepng($img);});$response = $response->withBody($stream);// Prior to 3.4.0 you can use the following to create streaming responses.
$file = fopen('/some/file.png', 'r');$this->response->body(function () use ($file) {rewind($file);
fpassthru($file);
fclose($file);});

Setting the Character Set
Cake\Http\Response::withCharset($charset)
Sets the charset that will be used in the response:$this->response = $this->response->withCharset('UTF-8');// Prior to 3.4.0$this->response->charset('UTF-8');

Response275

CakePHP Book, Release 3.10

Interacting with Browser Caching
Cake\Http\Response::withDisabledCache()
You sometimes need to force browsers not to cache the results of a controller action.
Response::withDisabledCache() is intended for just that:

Cake\Http\

public function index(){// Disable caching$this->response = $this->response->withDisabledCache();// Prior to 3.4.0$this->response->disableCache();}Warning: Disabling caching from SSL domains while trying to send files to Internet Explorer can result in errors.
Cake\Http\Response::withCache($since, $time = '+1 day')You can also tell clients that you want them to cache responses. By using Cake\Http\Response::withCache():public function index(){// Enable caching$this->response = $this->response->withCache('-1 minute', '+5 days');}
The above would tell clients to cache the resulting response for 5 days, hopefully speeding up your visitors’ experience.
The withCache() method sets the Last-Modified value to the first argument. Expires header and the max-age
directive are set based on the second parameter. Cache-Control’s public directive is set as well.

Fine Tuning HTTP Cache
One of the best and easiest ways of speeding up your application is to use HTTP cache. Under this caching model, you
are only required to help clients decide if they should use a cached copy of the response by setting a few headers suchas modified time and response entity tag.
Rather than forcing you to code the logic for caching and for invalidating (refreshing) it once the data has changed,
HTTP uses two models, expiration and validation, which usually are much simpler to use.
Apart from using Cake\Http\Response::withCache(), you can also use many other methods to fine-tune HTTP
cache headers to take advantage of browser or reverse proxy caching.

276

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

The Cache Control Header
Cake\Http\Response::withSharable($public, $time = null)
Used under the expiration model, this header contains multiple indicators that can change the way browsers or proxies
use the cached content. A Cache-Control header can look like this:Cache-Control: private, max-age=3600, must-revalidate
Response class helps you set this header with some utility methods that will produce a final valid Cache-Control
header. The first is the withSharable() method, which indicates whether a response is to be considered sharable
across different users or clients. This method actually controls the public or private part of this header. Setting a
response as private indicates that all or part of it is intended for a single user. To take advantage of shared caches, thecontrol directive must be set as public.
The second parameter of this method is used to specify a max-age for the cache, which is the number of seconds after
which the response is no longer considered fresh:
public function view(){// ...
// Set the Cache-Control as public for 3600 seconds$this->response = $this->response->withSharable(true, 3600);}
public function my_data(){// ...
// Set the Cache-Control as private for 3600 seconds$this->response = $this->response->withSharable(false, 3600);}
Response exposes separate methods for setting each of the directives in the Cache-Control header.
The Expiration Header
Cake\Http\Response::withExpires($time)
You can set the Expires header to a date and time after which the response is no longer considered fresh. This header
can be set using the withExpires() method:
public function view(){$this->response = $this->response->withExpires('+5 days');}This method also accepts a DateTime instance or any string that can be parsed by the DateTime class.

Response277

CakePHP Book, Release 3.10

The Etag Header
Cake\Http\Response::withEtag($tag, $weak = false)
Cache validation in HTTP is often used when content is constantly changing, and asks the application to only generate
the response contents if the cache is no longer fresh. Under this model, the client continues to store pages in the cache,but it asks the application every time whether the resource has changed, instead of using it directly. This is commonlyused with static resources such as images and other assets.
The withEtag() method (called entity tag) is a string that uniquely identifies the requested resource, as a checksum
does for a file, in order to determine whether it matches a cached resource.
To take advantage of this header, you must either call the checkNotModified() method manually or include theRequest Handling in your controller:
public function index(){$articles = $this->Articles->find('all');// Simple checksum of the article contents.
// You should use a more efficient implementation// in a real world application.
$checksum = md5(json_encode($articles));$response = $this->response->withEtag($checksum);if ($response->checkNotModified($this->request)) {return $response;}$this->response = $response;// ...
}

Note: Most proxy users should probably consider using the Last Modified Header instead of Etags for performanceand compatibility reasons.

The Last Modified Header
Cake\Http\Response::withModified($time)Also, under the HTTP cache validation model, you can set the Last-Modified header to indicate the date and time atwhich the resource was modified for the last time. Setting this header helps CakePHP tell caching clients whether the
response was modified or not based on their cache.
To take advantage of this header, you must either call the checkNotModified() method manually or include theRequest Handling in your controller:
public function view(){$article = $this->Articles->find()->first();$response = $this->response->withModified($article->modified);
if ($response->checkNotModified($this->request)) {return $response;(continues on next page)

278

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

(continued from previous page)}$this->response;// ...
}The Vary Header
Cake\Http\Response::withVary($header)
In some cases, you might want to serve different content using the same URL. This is often the case if you have amultilingual page or respond with different HTML depending on the browser. Under such circumstances you can use
the Vary header:$response = $this->response->withVary('User-Agent');$response = $this->response->withVary('Accept-Encoding', 'User-Agent');$response = $this->response->withVary('Accept-Language');

Sending Not-Modified Responses
Cake\Http\Response::checkNotModified(Request $request)
Compares the cache headers for the request object with the cache header from the response and determines whether it
can still be considered fresh. If so, deletes the response content, and sends the 304 Not Modified header:// In a controller action.
if ($this->response->checkNotModified($this->request)) {return $this->response;}

Setting Cookies
Cookies can be added to response using either an array or a Cake\Http\Cookie\Cookie object:
use Cake\Http\Cookie\Cookie;
use DateTime;// Add a cookie as an array using the immutable API (3.4.0+)$this->response = $this->response->withCookie(new Cookie('remember_me','yes',
new DateTime('+1 year'), // expiration time'/', // path'', // domain
false, // securetrue // httponly));// Before 3.4.0$this->response->cookie('remember', [(continues on next page)

Setting Cookies

279

CakePHP Book, Release 3.10

(continued from previous page)'value' => 'yes','path' => '/',
'httpOnly' => true,'secure' => false,'expire' => strtotime('+1 year')]);
See the Creating Cookies section for how to use the cookie object. You can use withExpiredCookie() to send an
expired cookie in the response. This will make the browser remove its local cookie:// As of 3.5.0$this->response = $this->response->withExpiredCookie('remember_me');Setting Cross Origin Request Headers (CORS)
As of 3.2 you can use the cors() method to define HTTP Access Control119 related headers with a fluent interface:$this->response = $this->response->cors($this->request)->allowOrigin(['*.cakephp.org'])->allowMethods(['GET', 'POST'])->allowHeaders(['X-CSRF-Token'])->allowCredentials()->exposeHeaders(['Link'])->maxAge(300)->build();
CORS related headers will only be applied to the response if the following criteria are met:
1. The request has an Origin header.
2. The request’s Origin value matches one of the allowed Origin values.
New in version 3.2: The CorsBuilder was added in 3.2

Common Mistakes with Immutable Responses
As of CakePHP 3.4.0, response objects offer a number of methods that treat responses as immutable objects. Immutableobjects help prevent difficult to track accidental side-effects, and reduce mistakes caused by method calls caused byrefactoring that change ordering. While they offer a number of benefits, immutable objects can take some getting used
to. Any method that starts with with operates on the response in an immutable fashion, and will always return a
new instance. Forgetting to retain the modified instance is the most frequent mistake people make when working withimmutable objects:$this->response->withHeader('X-CakePHP', 'yes!');In the above code, the response will be lacking the X-CakePHP header, as the return value of the withHeader() method
was not retained. To correct the above code you would write:
119 https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS

280

Chapter 9. Request & Response Objects

CakePHP Book, Release 3.10

$this->response = $this->response->withHeader('X-CakePHP', 'yes!');Cookie Collectionsclass Cake\Http\Cookie\CookieCollection
CookieCollection objects are accessible from the request and response objects. They let you interact with groupsof cookies using immutable patterns, which allow the immutability of the request and response to be preserved.

Creating Cookies
class Cake\Http\Cookie\Cookie
Cookie objects can be defined through constructor objects, or by using the fluent interface that follows immutable
patterns:
use Cake\Http\Cookie\Cookie;// All arguments in the constructor$cookie = new Cookie('remember_me', // name1, // value
new DateTime('+1 year'), // expiration time, if applicable'/', // path, if applicable'example.com', // domain, if applicablefalse, // secure only?
true // http only ?
);// Using the builder methods$cookie = (new Cookie('remember_me'))->withValue('1')->withExpiry(new DateTime('+1 year'))->withPath('/')->withDomain('example.com')->withSecure(false)->withHttpOnly(true);
Once you have created a cookie, you can add it to a new or existing CookieCollection:
use Cake\Http\Cookie\CookieCollection;// Create a new collection$cookies = new CookieCollection([$cookie]);// Add to an existing collection$cookies = $cookies->add($cookie);// Remove a cookie by name$cookies = $cookies->remove('remember_me');Cookie Collections

281

CakePHP Book, Release 3.10

Note: Remember that collections are immutable and adding cookies into, or removing cookies from a collection,
creates a new collection object.
Cookie objects can be added to responses:// Add one cookie$response = $this->response->withCookie($cookie);// Replace the entire cookie collection$response = $this->response->withCookieCollection($cookies);
Cookies set to responses can be encrypted using the encrypted-cookie-middleware.
New in version 3.8.0: Response::withCookieCollection() was added.

Reading Cookies
Once you have a CookieCollection instance, you can access the cookies it contains:// Check if a cookie exists$cookies->has('remember_me');// Get the number of cookies in the collection
count($cookies);// Get a cookie instance$cookie = $cookies->get('remember_me');Once you have a Cookie object you can interact with it’s state and modify it. Keep in mind that cookies are immutable,
so you’ll need to update the collection if you modify a cookie:// Get the value$value = $cookie->getValue()// Access data inside a JSON value$id = $cookie->read('User.id');// Check state$cookie->isHttpOnly();$cookie->isSecure();New in version 3.5.0: CookieCollection and Cookie were added in 3.5.0.

282

Chapter 9. Request & Response Objects

CHAPTER 10

Controllers

class Cake\Controller\Controller
Controllers are the ‘C’ in MVC. After routing has been applied and the correct controller has been found, your controller’s action is called. Your controller should handle interpreting the request data, making sure the correct models
are called, and the right response or view is rendered. Controllers can be thought of as middle layer between the Model
and View. You want to keep your controllers thin, and your models fat. This will help you reuse your code and makes
your code easier to test.
Commonly, a controller is used to manage the logic around a single model. For example, if you were building a site foran online bakery, you might have a RecipesController managing your recipes and an IngredientsController managing
your ingredients. However, it’s also possible to have controllers work with more than one model. In CakePHP, acontroller is named after the primary model it handles.
Your application’s controllers extend the AppController class, which in turn extends the core Controller class.
The AppController class can be defined in src/Controller/AppController.php and it should contain methods thatare shared between all of your application’s controllers.
Controllers provide a number of methods that handle requests. These are called actions. By default, each public
method in a controller is an action, and is accessible from a URL. An action is responsible for interpreting the request
and creating the response. Usually responses are in the form of a rendered view, but there are other ways to create
responses as well.

283

CakePHP Book, Release 3.10

The App Controller
As stated in the introduction, the AppController class is the parent class to all of your application’s controllers.
AppController itself extends the Cake\Controller\Controller class included in CakePHP. AppController isdefined in src/Controller/AppController.php as follows:namespace App\Controller;
use Cake\Controller\Controller;class AppController extends Controller{}
Controller attributes and methods created in your AppController will be available in all controllers that extend it.
Components (which you’ll learn about later) are best used for code that is used in many (but not necessarily all) controllers.
You can use your AppController to load components that will be used in every controller in your application.
CakePHP provides a initialize() method that is invoked at the end of a Controller’s constructor for this kind ofuse:
namespace App\Controller;
use Cake\Controller\Controller;class AppController extends Controller{
public function initialize(){// Always enable the CSRF component.
$this->loadComponent('Csrf');}}
In addition to the initialize() method, the older $components property will also allow you to declare which
components should be loaded. While normal object-oriented inheritance rules apply, the components and helpers usedby a controller are treated specially. In these cases, AppController property values are merged with child controller
class arrays. The values in the child class will always override those in AppController.

Request Flow
When a request is made to a CakePHP application, CakePHP’s Cake\Routing\Router and Cake\Routing\
Dispatcher classes use Connecting Routes to find and create the correct controller instance. The request data is
encapsulated in a request object. CakePHP puts all of the important request information into the $this->request
property. See the section on Request for more information on the CakePHP request object.

284

Chapter 10. Controllers

CakePHP Book, Release 3.10

Controller Actions
Controller actions are responsible for converting the request parameters into a response for the browser/user making therequest. CakePHP uses conventions to automate this process and remove some boilerplate code you would otherwise
need to write.
By convention, CakePHP renders a view with an inflected version of the action name. Returning to our online bakery
example, our RecipesController might contain the view(), share(), and search() actions. The controller would befound in src/Controller/RecipesController.php and contain:// src/Controller/RecipesController.php
class RecipesController extends AppController{
public function view($id){// Action logic goes here.
}
public function share($customerId, $recipeId){// Action logic goes here.
}
public function search($query){// Action logic goes here.
}}
The template files for these actions would be src/Template/Recipes/view.ctp, src/Template/Recipes/share.ctp, andsrc/Template/Recipes/search.ctp. The conventional view file name is the lowercased and underscored version of theaction name.
Controller actions generally use Controller::set() to create a context that View uses to render the view layer.
Because of the conventions that CakePHP uses, you don’t need to create and render the view manually. Instead, once
a controller action has completed, CakePHP will handle rendering and delivering the View.
If for some reason you’d like to skip the default behavior, you can return a Cake\Http\Response object from theaction with the fully created response.
In order for you to use a controller effectively in your own application, we’ll cover some of the core attributes andmethods provided by CakePHP’s controllers.

Interacting with Views
Controllers interact with views in a number of ways. First, they are able to pass data to the views, using
Controller::set(). You can also decide which view class to use, and which view file should be rendered fromthe controller.

Controller Actions285

CakePHP Book, Release 3.10

Setting View Variables
Cake\Controller\Controller::set(string $var, mixed $value)
The Controller::set() method is the main way to send data from your controller to your view. Once you’ve used
Controller::set(), the variable can be accessed in your view:// First you pass data from the controller:$this->set('color', 'pink');// Then, in the view, you can utilize the data:?>
You have selected <?= h($color) ?> icing for the cake.
The Controller::set() method also takes an associative array as its first parameter. This can often be a quick way
to assign a set of information to the view:$data = ['color' => 'pink','type' => 'sugar','base_price' => 23.95];// Make $color, $type, and $base_price// available to the view:$this->set($data);
Keep in mind that view vars are shared among all parts rendered by your view. They will be available in all parts ofthe view: the template, the layout and all elements inside the former two.

Setting View Options
If you want to customize the view class, layout/template paths, helpers or the theme that will be used when rendering
the view, you can use the viewBuilder() method to get a builder. This builder can be used to define properties of theview before it is created:$this->viewBuilder()->helpers(['MyCustom'])->theme('Modern')->className('Modern.Admin');
The above shows how you can load custom helpers, set the theme and use a custom view class.
New in version 3.1: ViewBuilder was added in 3.1

286

Chapter 10. Controllers

CakePHP Book, Release 3.10

Rendering a View
Cake\Controller\Controller::render(string $view, string $layout)
The Controller::render() method is automatically called at the end of each requested controller action. Thismethod performs all the view logic (using the data you’ve submitted using the Controller::set() method), places
the view inside its View::$layout, and serves it back to the end user.
The default view file used by render is determined by convention. If the search() action of the RecipesController isrequested, the view file in src/Template/Recipes/search.ctp will be rendered:namespace App\Controller;class RecipesController extends AppController{// ...
public function search(){// Render the view in src/Template/Recipes/search.ctp$this->render();}// ...
}
Although CakePHP will automatically call it after every action’s logic (unless you’ve called$this->disableAutoRender()), you can use it to specify an alternate view file by specifying a view filename as first argument of Controller::render() method.
If $view starts with ‘/’, it is assumed to be a view or element file relative to the src/Template folder. This allows direct
rendering of elements, very useful in AJAX calls:// Render the element in src/Template/Element/ajaxreturn.ctp$this->render('/Element/ajaxreturn');
The second parameter $layout of Controller::render() allows you to specify the layout with which the view isrendered.
Rendering a Specific Template
In your controller, you may want to render a different view than the conventional one. You can do this by calling
Controller::render() directly. Once you have called Controller::render(), CakePHP will not try to re-renderthe view:
namespace App\Controller;class PostsController extends AppController{
public function my_action(){$this->render('custom_file');}}This would render src/Template/Posts/custom_file.ctp instead of src/Template/Posts/my_action.ctp.

Interacting with Views

287CakePHP Book, Release 3.10

You can also render views inside plugins using the following syntax:
PluginController/custom_file'). For example:$this->render('PluginName.

namespace App\Controller;class PostsController extends AppController{
public function my_action(){$this->render('Users.UserDetails/custom_file');}}This would render plugins/Users/src/Template/UserDetails/custom_file.ctp

Redirecting to Other Pages
Cake\Controller\Controller::redirect(string|array $url, integer $status)
The flow control method you’ll use most often is Controller::redirect(). This method takes its first parameterin the form of a CakePHP-relative URL. When a user has successfully placed an order, you might wish to redirect him
to a receipt screen.
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']);}
The method will return the response instance with appropriate headers set. You should return the response instancefrom your action to prevent view rendering and let the dispatcher handle actual redirection.
You can also use a relative or absolute URL as the $url argument:
return $this->redirect('/orders/thanks');
return $this->redirect('http://www.example.com');
You can also pass data to the action:
return $this->redirect(['action' => 'edit', $id]);
The second parameter of Controller::redirect() allows you to define an HTTP status code to accompany theredirect. You may want to use 301 (moved permanently) or 303 (see other), depending on the nature of the redirect.
If you need to redirect to the referer page you can use:

288

Chapter 10. Controllers

CakePHP Book, Release 3.10

return $this->redirect($this->referer());
An example using query strings and hash would look like:return $this->redirect(['controller' => 'Orders','action' => 'confirm','?' => ['product' => 'pizza','quantity' => 5],'#' => 'top']);
The generated URL would be:
http://www.example.com/orders/confirm?product=pizza&quantity=5#top

Redirecting to Another Action on the Same Controller
Cake\Controller\Controller::setAction($action, $args...)If you need to forward the current action to a different action on the same controller, you can use
Controller::setAction() to update the request object, modify the view template that will be rendered and forward execution to the named action:// From a delete action, you can render the updated// list page.
$this->setAction('index');

Loading Additional Models
Cake\Controller\Controller::loadModel(string $modelClass, string $type)The loadModel() function comes handy when you need to use a model table/collection that is not the controller’s
default one:// In a controller method.
$this->loadModel('Articles');$recentArticles = $this->Articles->find('all', ['limit' => 5,'order' => 'Articles.created DESC']);
If you are using a table provider other than the built-in ORM you can link that table system into CakePHP’s controllers
by connecting its factory method:// In a controller method.
$this->modelFactory('ElasticIndex',(continues on next page)

Loading Additional Models289CakePHP Book, Release 3.10

(continued from previous page)['ElasticIndexes', 'factory']);
After registering a table factory, you can use loadModel to load instances:// In a controller method.
$this->loadModel('Locations', 'ElasticIndex');Note: The built-in ORM’s TableRegistry is connected by default as the ‘Table’ provider.

Paginating a Model
Cake\Controller\Controller::paginate()
This method is used for paginating results fetched by your models. You can specify page sizes, model find conditions
and more. See the pagination section for more details on how to use paginate().
The $paginate attribute gives you an easy way to customize how paginate() behaves:class ArticlesController extends AppController{
public $paginate = ['Articles' => ['conditions' => ['published' => 1]]];}

Configuring Components to Load
Cake\Controller\Controller::loadComponent($name, $config = [])In your Controller’s initialize() method you can define any components you want loaded, and any configuration
data for them:public function initialize(){
parent::initialize();$this->loadComponent('Csrf');$this->loadComponent('Comments', Configure::read('Comments'));}property Cake\Controller\Controller::$components
The $components property on your controllers allows you to configure components. Configured components and theirdependencies will be created by CakePHP for you. Read the Configuring Components section for more information.
As mentioned earlier the $components property will be merged with the property defined in each of your controller’sparent classes.

290

Chapter 10. Controllers

CakePHP Book, Release 3.10

Configuring Helpers to Load
property Cake\Controller\Controller::$helpers
Let’s look at how to tell a CakePHP Controller that you plan to use additional MVC classes:
class RecipesController extends AppController{
public $helpers = ['Form'];}
Each of these variables are merged with their inherited values, therefore it is not necessary (for example) to redeclare
the FormHelper, or anything that is declared in your AppController.
Deprecated since version 3.0: Loading Helpers from the controller is provided for backwards compatibility reasons.
You should see Configuring Helpers for how to load helpers.

Request Life-cycle Callbacks
CakePHP controllers trigger several events/callbacks that you can use to insert logic around the request life-cycle:

Event List
• Controller.initialize• Controller.startup• Controller.beforeRedirect• Controller.beforeRender• Controller.shutdown

Controller Callback Methods
By default the following callback methods are connected to related events if the methods are implemented by yourcontrollers
Cake\Controller\Controller::beforeFilter(Event $event)Called during the Controller.initialize event which occurs before every action in the controller. It’s ahandy place to check for an active session or inspect user permissions.
Note: The beforeFilter() method will be called for missing actions.
Returning a response from a beforeFilter method will not prevent other listeners of the same event from being
called. You must explicitly stop the event.
Cake\Controller\Controller::beforeRender(Event $event)Called during the Controller.beforeRender event which occurs after controller action logic, but before theview is rendered. This callback is not used often, but may be needed if you are calling render() manually before
the end of a given action.

Configuring Helpers to Load

291

CakePHP Book, Release 3.10

Cake\Controller\Controller::afterFilter(Event $event)Called during the Controller.shutdown event which is triggered after every controller action, and after rendering is complete. This is the last controller method to run.
In addition to controller life-cycle callbacks, Components also provide a similar set of callbacks.
Remember to call AppController’s callbacks within child controller callbacks for best results://use Cake\Event\Event;public function beforeFilter(Event $event){parent::beforeFilter($event);}

More on Controllers
The Pages Controller
CakePHP’s official skeleton app ships with a default controller PagesController.php. This is a simple and optional
controller for serving up static content. The home page you see after installation is generated using this controller
and the view file src/Template/Pages/home.ctp. If you make the view file src/Template/Pages/about_us.ctp you canaccess it using the URL http://example.com/pages/about_us. You are free to modify the Pages Controller to meetyour needs.
When you “bake” an app using Composer the Pages Controller is created in your src/Controller/ folder.

Components
Components are packages of logic that are shared between controllers. CakePHP comes with a fantastic set of corecomponents you can use to aid in various common tasks. You can also create your own components. If you find yourself
wanting to copy and paste things between controllers, you should consider creating your own component to containthe functionality. Creating components keeps controller code clean and allows you to reuse code between different
controllers.
For more information on the components included in CakePHP, check out the chapter for each component:
AuthComponent
class AuthComponent(ComponentCollection $collection, array $config = [])Identifying, authenticating, and authorizing users is a common part of almost every web application. In CakePHP
AuthComponent provides a pluggable way to do these tasks. AuthComponent allows you to combine authentication
objects and authorization objects to create flexible ways of identifying and checking user authorization.
Deprecated since version 4.0.0: The AuthComponent is deprecated as of 4.0.0 and will be replaced by the authorization120 and authentication121 plugins.
120 https://book.cakephp.org/authorization/
121 https://book.cakephp.org/authentication/

292

Chapter 10. Controllers

CakePHP Book, Release 3.10

Suggested Reading Before Continuing
Configuring authentication requires several steps including defining a users table, creating a model, controller & views,
etc.
This is all covered step by step in the CMS Tutorial.
If you are looking for existing authentication and/or authorization solutions for CakePHP, have a look at the Authentication and Authorization122 section of the Awesome CakePHP list.
Authentication
Authentication is the process of identifying users by provided credentials and ensuring that users are who they say
they are. Generally, this is done through a username and password, that are checked against a known list of users. In
CakePHP, there are several built-in ways of authenticating users stored in your application.
• FormAuthenticate allows you to authenticate users based on form POST data. Usually, this is a login form
that users enter information into.
• BasicAuthenticate allows you to authenticate users using Basic HTTP authentication.
• DigestAuthenticate allows you to authenticate users using Digest HTTP authentication.
By default AuthComponent uses FormAuthenticate.
Choosing an Authentication Type
Generally, you’ll want to offer form based authentication. It is the easiest for users using a web-browser to use. If
you are building an API or webservice, you may want to consider basic authentication or digest authentication. The
key differences between digest and basic authentication are mostly related to how passwords are handled. In basic
authentication, the username and password are transmitted as plain-text to the server. This makes basic authentication
un-suitable for applications without SSL, as you would end up exposing sensitive passwords. Digest authentication uses
a digest hash of the username, password, and a few other details. This makes digest authentication more appropriate
for applications without SSL encryption.
You can also use authentication systems like OpenID as well; however, OpenID is not part of CakePHP core.
Configuring Authentication Handlers
You configure authentication handlers using the authenticate config. You can configure one or many handlers forauthentication. Using multiple handlers allows you to support different ways of logging users in. When logging users
in, authentication handlers are checked in the order they are declared. Once one handler is able to identify the user, noother handlers will be checked. Conversely, you can halt all authentication by throwing an exception. You will need tocatch any thrown exceptions and handle them as needed.
You can configure authentication handlers in your controller’s beforeFilter() or initialize() methods. You canpass configuration information into each authentication object using an array:// Simple setup$this->Auth->config('authenticate', ['Form']);// Pass settings in(continues on next page)
122 https://github.com/FriendsOfCake/awesome-cakephp/blob/master/README.md#authentication-and-authorization

More on Controllers

293CakePHP Book, Release 3.10

(continued from previous page)$this->Auth->config('authenticate', ['Basic' => ['userModel' => 'Members'],'Form' => ['userModel' => 'Members']]);
In the second example, you’ll notice that we had to declare the userModel key twice. To help you keep your code
DRY, you can use the all key. This special key allows you to set settings that are passed to every attached object. The
all key is also exposed as AuthComponent::ALL:// Pass settings in using 'all'$this->Auth->config('authenticate', [AuthComponent::ALL => ['userModel' => 'Members'],'Basic','Form']);In the above example, both Form and Basic will get the settings defined for the ‘all’ key. Any settings passed to a
specific authentication object will override the matching key in the ‘all’ key. The core authentication objects support
the following configuration keys.
• fields The fields to use to identify a user by. You can use keys username and password to specify yourusername and password fields respectively.
• userModel The model name of the users table; defaults to Users.
• finder The finder method to use to fetch a user record. Defaults to ‘all’.
• passwordHasher Password hasher class; Defaults to Default.
• The scope and contain options have been deprecated as of 3.1. Use a custom finder instead to modify thequery to fetch a user record.
• The userFields option has been deprecated as of 3.1. Use select() in your custom finder.
To configure different fields for user in your initialize() method:
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authenticate' => ['Form' => ['fields' => ['username' => 'email', 'password' => 'passwd']
]
]
]);
}
Do not put other Auth configuration keys, such as authError, loginAction, etc., within the authenticate or Formelement. They should be at the same level as the authenticate key. The setup above with other Auth configuration shouldlook like:public function initialize(){
parent::initialize();$this->loadComponent('Auth', [(continues on next page)294

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)'loginAction' => ['controller' => 'Users','action' => 'login','plugin' => 'Users'],'authError' => 'Did you really think you are allowed to see that?','authenticate' => ['Form' => ['fields' => ['username' => 'email']]],'storage' => 'Session']);}
In addition to the common configuration, Basic authentication supports the following keys:• realm The realm being authenticated. Defaults to env('SERVER_NAME').
In addition to the common configuration Digest authentication supports the following keys:• realm The realm authentication is for. Defaults to the servername.
• nonce A nonce used for authentication. Defaults to uniqid().
• qop Defaults to auth; no other values are supported at this time.
• opaque A string that must be returned unchanged by clients. Defaults to md5($config['realm']).
Note: To find the user record, the database is queried only using the username. The password check is done in PHP.
This is necessary because hashing algorithms like bcrypt (which is used by default) generate a new hash each time,even for the same string and you can’t just do simple string comparison in SQL to check if the password matches.

Customizing Find Query
You can customize the query used to fetch the user record using the finder option in authenticate class config:
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authenticate' => ['Form' => ['finder' => 'auth'
]
],
]);
}
This will require your UsersTable to have finder method findAuth(). In the example shown below the query is
modified to fetch only required fields and add a condition. You must ensure that you select the fields you need toauthenticate a user, such as username and password:

More on Controllers

295CakePHP Book, Release 3.10

public function findAuth(\Cake\ORM\Query $query, array $options){$query->select(['id', 'username', 'password'])->where(['Users.active' => 1]);
return $query;}

Note: finder option is available since 3.1. Prior to that you can use scope and contain options to modify a query.

Identifying Users and Logging Them In
AuthComponent::identify()
You need to manually call $this->Auth->identify() to identify the user using credentials provided in request.
Then use $this->Auth->setUser() to log the user in, i.e., save user info to session.
When authenticating users, attached authentication objects are checked in the order they are attached. Once one ofthe objects can identify the user, no other objects are checked. A sample login function for working with a login form
could look like:public function login(){if ($this->request->is('post')) {$user = $this->Auth->identify();
if ($user) {$this->Auth->setUser($user);return $this->redirect($this->Auth->redirectUrl());} else {$this->Flash->error(__('Username or password is incorrect'));}}}
The above code will attempt to first identify a user by using the POST data. If successful we set the user info to thesession so that it persists across requests and then redirect to either the last page they were visiting or a URL specified
in the loginRedirect config. If the login is unsuccessful, a flash message is set.
Warning: $this->Auth->setUser($data) will log the user in with whatever data is passed to the method. It
won’t actually check the credentials against an authentication class.

296

Chapter 10. Controllers

CakePHP Book, Release 3.10

Redirecting Users After Login
AuthComponent::redirectUrl()
After logging a user in, you’ll generally want to redirect them back to where they came from. Pass a URL in to set thedestination a user should be redirected to after logging in.
If no parameter is passed, the returned URL will use the following rules:• Returns the normalized URL from the redirect query string value if it is present and for the same domain thecurrent app is running on. Before 3.4.0, the Auth.redirect session value was used.
• If there is no query string/session value and there is a config with loginRedirect, the loginRedirect value
is returned.
• If there is no redirect value and no loginRedirect, / is returned.
Creating Stateless Authentication Systems
Basic and digest are stateless authentication schemes and don’t require an initial POST or a form. If using only basic/digest authenticators you don’t require a login action in your controller. Stateless authentication will re-verify theuser’s credentials on each request, this creates a small amount of additional overhead, but allows clients to login without
using cookies and makes AuthComponent more suitable for building APIs.
For stateless authenticators, the storage config should be set to Memory so that AuthComponent does not use a session
to store user record. You may also want to set config unauthorizedRedirect to false so that AuthComponent
throws a ForbiddenException instead of the default behavior of redirecting to referrer.
The unauthorizedRedirect option only applies to authenticated users. When a user is not yet authenticated and you
do not want the user to be redirected, you will need to load one or more stateless authenticators, like Basic or Digest.
Authentication objects can implement a getUser() method that can be used to support user login systems that
don’t rely on cookies. A typical getUser method looks at the request/environment and uses the information there
to confirm the identity of the user. HTTP Basic authentication for example uses $_SERVER['PHP_AUTH_USER'] and$_SERVER['PHP_AUTH_PW'] for the username and password fields.
Note:
In case authentication does not work like expected, check if queries are executed atall (see BaseAuthenticate::_query($username)).
In case no queries are executed check if$_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] do get populated by the webserver. If you
are using Apache with FastCGI-PHP you might need to add this line to your .htaccess file in webroot:
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]On each request, these values, PHP_AUTH_USER and PHP_AUTH_PW, are used to re-identify the user and ensure they
are the valid user. As with authentication object’s authenticate() method, the getUser() method should return anarray of user information on the success or false on failure.
public function getUser(ServerRequest $request){$username = env('PHP_AUTH_USER');$pass = env('PHP_AUTH_PW');
if (empty($username) || empty($pass)) {return false;(continues on next page)

More on Controllers

297

CakePHP Book, Release 3.10

(continued from previous page)}
return $this->_findUser($username, $pass);}
The above is how you could implement the getUser method for HTTP basic authentication. The _findUser() method
is part of BaseAuthenticate and identifies a user based on a username and password.
Using Basic Authentication
Basic authentication allows you to create a stateless authentication that can be used in intranet applications or for simple
API scenarios. Basic authentication credentials will be rechecked on each request.
Warning: Basic authentication transmits credentials in plain-text. You should use HTTPS when using Basicauthentication.
To use basic authentication, you’ll need to configure AuthComponent:$this->loadComponent('Auth', ['authenticate' => ['Basic' => ['fields' => ['username' => 'username', 'password' => 'api_key'],'userModel' => 'Users'],],'storage' => 'Memory','unauthorizedRedirect' => false]);
Here we’re using username + API key as our fields and use the Users model.
Creating API Keys for Basic Authentication
Because basic HTTP sends credentials in plain-text, it is unwise to have users send their login password. Instead, an
opaque API key is generally used. You can generate these API tokens randomly using libraries from CakePHP:
namespace App\Model\Table;
use Cake\Auth\DefaultPasswordHasher;use Cake\Utility\Text;
use Cake\Event\Event;use Cake\ORM\Table;
use Cake\Utility\Security;
class UsersTable extends Table{
public function beforeSave(Event $event){$entity = $event->getData('entity');(continues on next page)

298

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)if ($entity->isNew()) {$hasher = new DefaultPasswordHasher();// Generate an API 'token'$entity->api_key_plain = Security::hash(Security::randomBytes(32), 'sha256',␣
false);

˓→// Bcrypt the token so BasicAuthenticate can check// it during login.
$entity->api_key = $hasher->hash($entity->api_key_plain);}return true;}}
The above generates a random hash for each user as they are saved. The above code assumes you have two columns
api_key - to store the hashed API key, and api_key_plain - to the plaintext version of the API key, so we can display
it to the user later on. Using a key instead of a password means that even over plain HTTP, your users can use an opaquetoken instead of their original password. It is also wise to include logic allowing API keys to be regenerated at a user’s
request.
Using Digest Authentication
Digest authentication offers an improved security model over basic authentication, as the user’s credentials are neversent in the request header. Instead, a hash is sent.
To use digest authentication, you’ll need to configure AuthComponent:$this->loadComponent('Auth', ['authenticate' => ['Digest' => ['fields' => ['username' => 'username', 'password' => 'digest_hash'],'userModel' => 'Users'],],'storage' => 'Memory','unauthorizedRedirect' => false]);
Here we’re using username + digest_hash as our fields and use the Users model.
Hashing Passwords For Digest Authentication
Because Digest authentication requires a password hashed in the format defined by the RFC, in order to correctly hash a password for use with Digest authentication you should use the special password hashing function on
DigestAuthenticate. If you are going to be combining digest authentication with any other authentication strategies, it’s also recommended that you store the digest password in a separate column, from the normal password hash:namespace App\Model\Table;
use Cake\Auth\DigestAuthenticate;(continues on next page)

More on Controllers

299

CakePHP Book, Release 3.10

(continued from previous page)use Cake\Event\Event;use Cake\ORM\Table;class UsersTable extends Table{
public function beforeSave(Event $event){$entity = $event->getData('entity');// Make a password for digest auth.
$entity->digest_hash = DigestAuthenticate::password($entity->username,$entity->plain_password,env('SERVER_NAME'));
return true;}}
Passwords for digest authentication need a bit more information than other password hashes, based on the RFC fordigest authentication.
Note:
The third parameter of DigestAuthenticate::password() must match the ‘realm’ config value
defined when DigestAuthentication was configured in AuthComponent::$authenticate. This defaults toenv('SCRIPT_NAME'). You may wish to use a static string if you want consistent hashes in multiple environments.

Creating Custom Authentication Objects
Because authentication objects are pluggable, you can create custom authentication objects in your application or plugins. If for example, you wanted to create an OpenID authentication object. In src/Auth/OpenidAuthenticate.php
you could put the following:namespace App\Auth;
use Cake\Auth\BaseAuthenticate;use Cake\Http\ServerRequest;
use Cake\Http\Response;class OpenidAuthenticate extends BaseAuthenticate{
public function authenticate(ServerRequest $request, Response $response){// Do things for OpenID here.
// Return an array of user if they could authenticate the user,// return false if not.
}}Authentication objects should return false if they cannot identify the user and an array of user information if theycan. It’s not required that you extend BaseAuthenticate, only that your authentication object implements Cake\

300

Chapter 10. Controllers

CakePHP Book, Release 3.10

Event\EventListenerInterface. The BaseAuthenticate class provides a number of helpful methods that arecommonly used. You can also implement a getUser() method if your authentication object needs to support statelessor cookie-less authentication. See the sections on basic and digest authentication below for more information.
AuthComponent triggers two events, Auth.afterIdentify and Auth.logout, after a user has been identified andbefore a user is logged out respectively. You can set callback functions for these events by returning a mapping arrayfrom implementedEvents() method of your authenticate class:public function implementedEvents(){
return ['Auth.afterIdentify' => 'afterIdentify','Auth.logout' => 'logout'];}

Using Custom Authentication Objects
Once you’ve created your custom authentication objects, you can use them by including them in AuthComponent’s
authenticate array:$this->Auth->config('authenticate', ['Openid', // app authentication object.
'AuthBag.Openid', // plugin authentication object.
]);

Note: Note that when using simple notation there’s no ‘Authenticate’ word when initiating the authentication object.
Instead, if using namespaces, you’ll need to set the full namespace of the class, including the ‘Authenticate’ word.

Handling Unauthenticated Requests
When an unauthenticated user tries to access a protected page first the unauthenticated() method of the last authenticator in the chain is called. The authenticate object can handle sending response or redirection by returning a
response object to indicate no further action is necessary. Due to this, the order in which you specify the authentication
provider in authenticate config matters.
If authenticator returns null, AuthComponent redirects user to the login action. If it’s an AJAX request and config
ajaxLogin is specified that element is rendered else a 403 HTTP status code is returned.
Displaying Auth Related Flash Messages
In order to display the session error messages that Auth generates, you need to add the following code to your layout.
Add the following two lines to the src/Template/Layout/default.ctp file in the body section:// Only this is necessary after 3.4.0
echo $this->Flash->render();// Prior to 3.4.0 this will be required as well.
echo $this->Flash->render('auth');More on Controllers

301

CakePHP Book, Release 3.10

You can customize the error messages and flash settings AuthComponent uses. Using flash config you can configure
the parameters AuthComponent uses for setting flash messages. The available keys are• key - The key to use, defaults to ‘default’. Prior to 3.4.0, the key defaulted to ‘auth’.
• element - The element name to use for rendering, defaults to null.
• params - The array of additional parameters to use, defaults to [].
In addition to the flash message settings you can customize other error messages AuthComponent uses. In your controller’s beforeFilter(), or component settings you can use authError to customize the error used for when authorization fails:$this->Auth->config('authError', "Woopsie, you are not authorized to access this area.");Sometimes, you want to display the authorization error only after the user has already logged-in. You can suppress thismessage by setting its value to boolean false.
In your controller’s beforeFilter() or component settings:
if (!$this->Auth->user()) {$this->Auth->config('authError', false);}

Hashing Passwords
You are responsible for hashing the passwords before they are persisted to the database, the easiest way is to use a setter
function in your User entity:
namespace App\Model\Entity;
use Cake\Auth\DefaultPasswordHasher;use Cake\ORM\Entity;class User extends Entity{// ...
protected function _setPassword($password){
if (strlen($password) > 0) {return (new DefaultPasswordHasher)->hash($password);}}// ...
}
AuthComponent is configured by default to use the DefaultPasswordHasher when validating user credentials so no
additional configuration is required in order to authenticate users.
DefaultPasswordHasher uses the bcrypt hashing algorithm internally, which is one of the stronger password hashingsolutions used in the industry. While it is recommended that you use this password hasher class, the case may be thatyou are managing a database of users whose password was hashed differently.

302

Chapter 10. Controllers

CakePHP Book, Release 3.10

Creating Custom Password Hasher Classes
In order to use a different password hasher, you need to create the class in src/Auth/LegacyPasswordHasher.php andimplement the hash() and check() methods. This class needs to extend the AbstractPasswordHasher class:namespace App\Auth;
use Cake\Auth\AbstractPasswordHasher;class LegacyPasswordHasher extends AbstractPasswordHasher{
public function hash($password){
return sha1($password);}
public function check($password, $hashedPassword){
return sha1($password) === $hashedPassword;}}
Then you are required to configure the AuthComponent to use your own password hasher:
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authenticate' => ['Form' => ['passwordHasher' => ['className' => 'Legacy',
]
]
]
]);
}
Supporting legacy systems is a good idea, but it is even better to keep your database with the latest security advancements. The following section will explain how to migrate from one hashing algorithm to CakePHP’s default.
Changing Hashing Algorithms
CakePHP provides a clean way to migrate your users’ passwords from one algorithm to another, this is achieved throughthe FallbackPasswordHasher class. Assuming you are migrating your app from CakePHP 2.x which uses sha1
password hashes, you can configure the AuthComponent as follows:
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authenticate' => [(continues on next page)

More on Controllers

303

CakePHP Book, Release 3.10

(continued from previous page)'Form' => ['passwordHasher' => ['className' => 'Fallback','hashers' => ['Default','Weak' => ['hashType' => 'sha1']
]
]
]
]
]);
}
The first name appearing in the hashers key indicates which of the classes is the preferred one, but it will fallback to
the others in the list if the check was unsuccessful.
When using the WeakPasswordHasher you will need to set the Security.salt configure the value to ensure passwords are salted.
In order to update old users’ passwords on the fly, you can change the login function accordingly:
public function login(){if ($this->request->is('post')) {$user = $this->Auth->identify();
if ($user) {$this->Auth->setUser($user);if ($this->Auth->authenticationProvider()->needsPasswordRehash()) {$user = $this->Users->get($this->Auth->user('id'));$user->password = $this->request->getData('password');$this->Users->save($user);}return $this->redirect($this->Auth->redirectUrl());
}
...
}
}
As you can see we are just setting the plain password again so the setter function in the entity will hash the password
as shown in the previous example and then save the entity.
Manually Logging Users In
AuthComponent::setUser(array $user)
Sometimes the need arises where you need to manually log a user in, such as just after they registered for your application. You can do this by calling $this->Auth->setUser() with the user data you want to ‘login’:
public function register(){$user = $this->Users->newEntity($this->request->getData());
if ($this->Users->save($user)) {$this->Auth->setUser($user->toArray());(continues on next page)

304

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)

return $this->redirect(['controller' => 'Users','action' => 'home']);}}

Warning: Be sure to manually add the new User id to the array passed to the setUser() method. Otherwise, you
won’t have the user id available.

Accessing the Logged In User
AuthComponent::user($key = null)Once a user is logged in, you will often need some particular information about the current user. You can access thecurrently logged in user using the following// From inside a controller or other component.
$this->Auth->user('id');If the current user is not logged in or the key doesn’t exist, null will be returned.
Logging Users Out
AuthComponent::logout()
Eventually, you’ll want a quick way to de-authenticate someone and redirect them to where they need to go. Thismethod is also useful if you want to provide a ‘Log me out’ link inside a members’ area of your application:
public function logout(){
return $this->redirect($this->Auth->logout());}
Logging out users that logged in with Digest or Basic auth is difficult to accomplish for all clients. Most browsers willretain credentials for the duration they are still open. Some clients can be forced to logout by sending a 401 status code.
Changing the authentication realm is another solution that works for some clients.
Deciding When to run Authentication
In some cases you may want to use $this->Auth->user() in the beforeFilter(Event $event) method. This isachievable by using the checkAuthIn config key. The following changes which event for which initial authentication
checks should be done://Set up AuthComponent to authenticate in initialize()$this->Auth->config('checkAuthIn', 'Controller.initialize');
Default value for checkAuthIn is 'Controller.startup' - but by using 'Controller.initialize' initial authentication is done before beforeFilter() method.
More on Controllers

305

CakePHP Book, Release 3.10

Authorization
Authorization is the process of ensuring that an identified/authenticated user is allowed to access the resources they
are requesting. If enabled AuthComponent can automatically check authorization handlers and ensure that logged inusers are allowed to access the resources they are requesting. There are several built-in authorization handlers and you
can create custom ones for your application or as part of a plugin.
• ControllerAuthorize Calls isAuthorized() on the active controller, and uses the return of that to authorize
a user. This is often the most simple way to authorize users.
Note: The ActionsAuthorize & CrudAuthorize adapter available in CakePHP 2.x have now been moved to a
separate plugin cakephp/acl123 .

Configuring Authorization Handlers
You configure authorization handlers using the authorize config key. You can configure one or many handlers for
authorization. Using multiple handlers allows you to support different ways of checking authorization. When authorization handlers are checked, they will be called in the order they are declared. Handlers should return false, if they
are unable to check authorization, or the check has failed. Handlers should return true if they were able to checkauthorization successfully. Handlers will be called in sequence until one passes. If all checks fail, the user will be
redirected to the page they came from. Additionally, you can halt all authorization by throwing an exception. You willneed to catch any thrown exceptions and handle them.
You can configure authorization handlers in your controller’s beforeFilter() or initialize() methods. You canpass configuration information into each authorization object, using an array:// Basic setup$this->Auth->config('authorize', ['Controller']);// Pass settings in$this->Auth->config('authorize', ['Actions' => ['actionPath' => 'controllers/'],'Controller']);
Much like authenticate, authorize, helps you keep your code DRY, by using the all key. This special key allows
you to set settings that are passed to every attached object. The all key is also exposed as AuthComponent::ALL:// Pass settings in using 'all'$this->Auth->config('authorize', [AuthComponent::ALL => ['actionPath' => 'controllers/'],'Actions','Controller']);
In the above example, both the Actions and Controller will get the settings defined for the ‘all’ key. Any settingspassed to a specific authorization object will override the matching key in the ‘all’ key.
If an authenticated user tries to go to a URL they are not authorized to access, they will be redirected back to thereferrer. If you do not want such redirection (mostly needed when using stateless authentication adapter) you can set
config option unauthorizedRedirect to false. This causes AuthComponent to throw a ForbiddenException
instead of redirecting.
123 https://github.com/cakephp/acl

306

Chapter 10. Controllers

CakePHP Book, Release 3.10

Creating Custom Authorize Objects
Because authorize objects are pluggable, you can create custom authorize objects in your application or plugins. If
for example, you wanted to create an LDAP authorize object. In src/Auth/LdapAuthorize.php you could put thefollowing:namespace App\Auth;
use Cake\Auth\BaseAuthorize;
use Cake\Http\ServerRequest;class LdapAuthorize extends BaseAuthorize{
public function authorize($user, ServerRequest $request){// Do things for ldap here.
}}
Authorize objects should return false if the user is denied access, or if the object is unable to perform a check. If theobject is able to verify the user’s access, true should be returned. It’s not required that you extend BaseAuthorize,
only that your authorize object implements an authorize() method. The BaseAuthorize class provides a numberof helpful methods that are commonly used.
Using Custom Authorize Objects
Once you’ve created your custom authorize object, you can use them by including them in your AuthComponent’s
authorize array:$this->Auth->config('authorize', ['Ldap', // app authorize object.
'AuthBag.Combo', // plugin authorize object.
]);

Using No Authorization
If you’d like to not use any of the built-in authorization objects and want to handle things entirely outside of
AuthComponent, you can set $this->Auth->config('authorize', false);. By default AuthComponent starts
off with authorize set to false. If you don’t use an authorization scheme, make sure to check authorization yourself
in your controller’s beforeFilter() or with another component.
Making Actions Public
AuthComponent::allow($actions = null)
There are often times controller actions that you wish to remain entirely public or that don’t require users to be logged
in. AuthComponent is pessimistic and defaults to denying access. You can mark actions as public actions by using
AuthComponent::allow(). By marking actions as public, AuthComponent will not check for a logged in user nor
will authorize objects to be checked:

More on Controllers

307CakePHP Book, Release 3.10// Allow all actions$this->Auth->allow();// Allow only the index action.
$this->Auth->allow('index');// Allow only the view and index actions.
$this->Auth->allow(['view', 'index']);By calling it empty you allow all actions to be public. For a single action, you can provide the action name as a string.
Otherwise, use an array.
Note: You should not add the “login” action of your UsersController to allow list. Doing so would cause problems
with the normal functioning of AuthComponent.

Making Actions Require Authorization
AuthComponent::deny($actions = null)
By default all actions require authorization. However, after making actions public you want to revoke the public access.
You can do so using AuthComponent::deny():// Deny all actions.
$this->Auth->deny();// Deny one action$this->Auth->deny('add');// Deny a group of actions.
$this->Auth->deny(['add', 'edit']);By calling it empty you deny all actions. For a single action, you can provide the action name as a string. Otherwise,
use an array.
Using ControllerAuthorize
ControllerAuthorize allows you to handle authorization checks in a controller callback. This is ideal when you havevery simple authorization or you need to use a combination of models and components to do your authorization anddon’t want to create a custom authorize object.
The callback is always called isAuthorized() and it should return a boolean as to whether or not the user is allowed
to access resources in the request. The callback is passed the active user so it can be checked:
class AppController extends Controller{
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authorize' => 'Controller',(continues on next page)

308

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)]);}
public function isAuthorized($user = null){// Any registered user can access public functions
if (!$this->request->getParam('prefix')) {return true;}// Only admins can access admin functions
if ($this->request->getParam('prefix') === 'admin') {return (bool)($user['role'] === 'admin');}// Default denyreturn false;}}
The above callback would provide a very simple authorization system where only users with role = admin could accessactions that were in the admin prefix.
Configuration options
The following settings can all be defined either in your controller’s initialize() method or using$this->Auth->config() in your beforeFilter():ajaxLogin
The name of an optional view element to render when an AJAX request is made with an invalid or expired
session.
allowedActions
Controller actions for which user validation is not required.
authenticate
Set to an array of Authentication objects you want to use when logging users in. There are several core authentication objects; see the section on Suggested Reading Before Continuing.
authError
Error to display when user attempts to access an object or action to which they do not have access.
You can suppress authError message from being displayed by setting this value to boolean false.
authorize
Set to an array of Authorization objects you want to use when authorizing users on each request; see the section
on Authorization.
flash
Settings to use when Auth needs to do a flash message with FlashComponent::set(). Available keys are:• element - The element to use; defaults to ‘default’.
• key - The key to use; defaults to ‘auth’.
• params - The array of additional parameters to use; defaults to ‘[]’.

More on Controllers

309

CakePHP Book, Release 3.10

loginAction
A URL (defined as a string or array) to the controller action that handles logins. Defaults to /users/login.
loginRedirect
The URL (defined as a string or array) to the controller action users should be redirected to after logging in. Thisvalue will be ignored if the user has an Auth.redirect value in their session.
logoutRedirect
The default action to redirect to after the user is logged out. While AuthComponent does not handle post-logout
redirection, a redirect URL will be returned from AuthComponent::logout(). Defaults to loginAction.
unauthorizedRedirect
Controls handling of unauthorized access. By default unauthorized user is redirected to the referrer URL or
loginAction or ‘/’. If set to false, a ForbiddenException exception is thrown instead of redirecting.
storage
Storage class to use for persisting user record. When using stateless authenticator you should set this to Memory.
Defaults to Session. You can pass config options to storage class using array format. For e.g. to use a custom
session key you can set storage to ['className' => 'Session', 'key' => 'Auth.Admin'].
checkAuthIn
Name of the event in which initial auth checks should be done. Defaults to Controller.startup. You can set
it to Controller.initialize if you want the check to be done before controller’s beforeFilter() method
is run.
You can get current configuration values by calling $this->Auth->config():: only the configuration option:$this->Auth->config('loginAction');$this->redirect($this->Auth->config('loginAction'));This is useful if you want to redirect a user to the login route for example. Without a parameter, the full configuration
will be returned.
Testing Actions Protected By AuthComponent
See the Testing Actions That Require Authentication section for tips on how to test controller actions that are protectedby AuthComponent.
Cookieclass Cake\Controller\Component\CookieComponent(ComponentRegistry $collection, array $config = [])The CookieComponent is a wrapper around the native PHP setcookie() method. It makes it easier to manipulate
cookies, and automatically encrypt cookie data. Cookies added through CookieComponent will only be sent if thecontroller action completes.
Deprecated since version 3.5.0: Cookies are available in the ServerRequest see Cookies. For encrypted cookies see
the encrypted-cookie-middleware.

310

Chapter 10. Controllers

CakePHP Book, Release 3.10

Configuring Cookies
Cookies can be configured either globally or per top-level name. The global configuration data will be merged with the
top-level configuration. So only need to override the parts that are different. To configure the global settings use theconfig() method:$this->Cookie->config('path', '/');$this->Cookie->config(['expires' => '+10 days','httpOnly' => true]);
To configure a specific key use the configKey() method:$this->Cookie->configKey('User', 'path', '/');$this->Cookie->configKey('User', ['expires' => '+10 days','httpOnly' => true]);
There are a number of configurable values for cookies:
expires
How long the cookies should last for. Defaults to 1 month.
path
The path on the server in which the cookie will be available on. If path is set to ‘/foo/’, the cookie will only beavailable within the /foo/ directory and all sub-directories such as /foo/bar/ of domain. The default value is app’s
base path.
domainThe domain that the cookie is available. To make the cookie available on all subdomains of example.com set
domain to ‘.example.com’.
secureIndicates that the cookie should only be transmitted over a secure HTTPS connection. When set to true, thecookie will only be set if a secure connection exists.
key
Encryption key used when encrypted cookies are enabled. Defaults to Security.salt.
httpOnly
Set to true to make HTTP only cookies. Cookies that are HTTP only are not accessible in JavaScript. Defaults
to false.
encryption
Type of encryption to use. Defaults to ‘aes’. Can also be ‘rijndael’ for backwards compatibility.

More on Controllers

311

CakePHP Book, Release 3.10

Using the Component
The CookieComponent offers a number of methods for working with Cookies.
Cake\Controller\Component\CookieComponent::write(mixed $key, mixed $value = null)
The write() method is the heart of the cookie component. $key is the cookie variable name you want, and the$value is the information to be stored:$this->Cookie->write('name', 'Larry');
You can also group your variables by using dot notation in the key parameter:$this->Cookie->write('User.name', 'Larry');$this->Cookie->write('User.role', 'Lead');If you want to write more than one value to the cookie at a time, you can pass an array:$this->Cookie->write('User',['name' => 'Larry', 'role' => 'Lead']);All values in the cookie are encrypted with AES by default. If you want to store the values as plain text, be sure
to configure the key space:$this->Cookie->configKey('User', 'encryption', false);
Cake\Controller\Component\CookieComponent::read(mixed $key = null)This method is used to read the value of a cookie variable with the name specified by $key.
// Outputs "Larry"echo $this->Cookie->read('name');// You can also use the dot notation for readecho $this->Cookie->read('User.name');// To get the variables which you had grouped// using the dot notation as an array use the following$this->Cookie->read('User');// This outputs something like ['name' => 'Larry', 'role' => 'Lead']

Warning:
CookieComponent cannot interact with bare strings values that contain ,. The component will attempt to interpret these values as arrays, leading to incorrect results. Instead you should use$request->getCookie().
Cake\Controller\Component\CookieComponent::check($key)
Parameters• $key (string) – The key to check.
Used to check whether a key/path exists and has a non-null value.

312

Chapter 10. Controllers

CakePHP Book, Release 3.10

Cake\Controller\Component\CookieComponent::delete(mixed $key)
Deletes a cookie variable of the name in $key. Works with dot notation:// Delete a variable$this->Cookie->delete('bar');// Delete the cookie variable bar, but not everything under foo$this->Cookie->delete('foo.bar');

Cross Site Request Forgery
By enabling the CSRF Component you get protection against attacks. CSRF124 or Cross Site Request Forgery is acommon vulnerability in web applications. It allows an attacker to capture and replay a previous request, and sometimes
submit data requests using image tags or resources on other domains.
The CsrfComponent works by setting a cookie to the user’s browser. When forms are created with the Cake\View\
Helper\FormHelper, a hidden field is added containing the CSRF token. During the Controller.startup event,if the request is a POST, PUT, DELETE, PATCH request the component will compare the request data & cookie
value. If either is missing or the two values mismatch the component will throw a Cake\Network\Exception\
InvalidCsrfTokenException.
Note: You should always verify the HTTP method being used before executing to avoid side-effects. You should
check the HTTP method or use Cake\Http\ServerRequest::allowMethod() to ensure the correct HTTP method
is used.
New in version 3.1: The exception type changed from Cake\Network\Exception\ForbiddenException to Cake\
Network\Exception\InvalidCsrfTokenException.
Deprecated since version 3.5.0: You should use csrf-middleware instead of CsrfComponent.
Using the CsrfComponent
Simply by adding the CsrfComponent to your components array, you can benefit from the CSRF protection it provides:
public function initialize(){
parent::initialize();$this->loadComponent('Csrf');}
Settings can be passed into the component through your component’s settings. The available configuration options are:• cookieName The name of the cookie to send. Defaults to csrfToken.
• expiry How long the CSRF token should last. Defaults to browser session. Accepts strtotime values as of
3.1• secure Whether or not the cookie will be set with the Secure flag. That is, the cookie will only be set on a
HTTPS connection and any attempt over normal HTTP will fail. Defaults to false.
• field The form field to check.
FormHelper.

Defaults to _csrfToken.

Changing this will also require configuring

124 https://en.wikipedia.org/wiki/Cross-site_request_forgery

More on Controllers

313

CakePHP Book, Release 3.10

When enabled, you can access the current CSRF token on the request object:$token = $this->request->getParam('_csrfToken');Integration with FormHelper
The CsrfComponent integrates seamlessly with FormHelper. Each time you create a form with FormHelper, it willinsert a hidden field containing the CSRF token.
Note: When using the CsrfComponent you should always start your forms with the FormHelper. If you do not, youwill need to manually create hidden inputs in each of your forms.

CSRF Protection and AJAX Requests
In addition to request data parameters, CSRF tokens can be submitted through a special X-CSRF-Token header. Usinga header often makes it easier to integrate a CSRF token with JavaScript heavy applications, or XML/JSON based API
endpoints.
Disabling the CSRF Component for Specific Actions
While not recommended, you may want to disable the CsrfComponent on certain requests. You can do this using thecontroller’s event dispatcher, during the beforeFilter() method:
public function beforeFilter(Event $event){$this->getEventManager()->off($this->Csrf);}

Flashclass Cake\Controller\Component\FlashComponent(ComponentCollection $collection, array $config = [])FlashComponent provides a way to set one-time notification messages to be displayed after processing a form or acknowledging data. CakePHP refers to these messages as “flash messages”. FlashComponent writes flash messages to$_SESSION, to be rendered in a View using FlashHelper.
Setting Flash Messages
FlashComponent provides two ways to set flash messages: its __call() magic method and its set() method. To
furnish your application with verbosity, FlashComponent’s __call() magic method allows you use a method namethat maps to an element located under the src/Template/Element/Flash directory. By convention, camelcased methods
will map to the lowercased and underscored element name:// Uses src/Template/Element/Flash/success.ctp$this->Flash->success('This was successful');// Uses src/Template/Element/Flash/great_success.ctp$this->Flash->greatSuccess('This was greatly successful');314

Chapter 10. Controllers

CakePHP Book, Release 3.10

Alternatively, to set a plain-text message without rendering an element, you can use the set() method:$this->Flash->set('This is a message');
New in version 3.1: Flash messages now stack. Successive calls to set() or __call() with the same key will append
the messages in the $_SESSION. If you want to keep the old behavior (one message even after consecutive calls), set
the clear parameter to true when configuring the Component.
FlashComponent’s __call() and set() methods optionally take a second parameter, an array of options:• key Defaults to ‘flash’. The array key found under the Flash key in the session.
• element Defaults to null, but will automatically be set when using the __call() magic method. The element
name to use for rendering.
• params An optional array of keys/values to make available as variables within an element.
New in version 3.1: A new key clear was added. This key expects a bool and allows you to delete all messages in
the current stack and start a new one.
An example of using these options:// In your Controller$this->Flash->success('The user has been saved', ['key' => 'positive','params' => ['name' => $user->name,'email' => $user->email]]);// In your View<?= $this->Flash->render('positive') ?><!-- In src/Template/Element/Flash/success.ctp --><div id="flash-<?= h($key) ?>" class="message-info success"><?= h($message) ?>: <?= h($params['name']) ?>, <?= h($params['email']) ?>.
</div>
Note that the parameter element will be always overridden while using __call(). In order to retrieve a specificelement from a plugin, you should set the plugin parameter. For example:// In your Controller$this->Flash->warning('My message', ['plugin' => 'PluginName']);
The code above will use the warning.ctp element under plugins/PluginName/src/Template/Element/Flash for rendering the flash message.
Note: By default, CakePHP escapes the content in flash messages to prevent cross site scripting. User data in yourflash messages will be HTML encoded and safe to be printed. If you want to include HTML in your flash messages, youneed to pass the escape option and adjust your flash message templates to allow disabling escaping when the escapeoption is passed.

More on Controllers

315CakePHP Book, Release 3.10

HTML in Flash Messages
New in version 3.3.3.
It is possible to output HTML in flash messages by using the 'escape' option key:
$this->Flash->info(sprintf('<b>%s</b> %s', h($highlight), h($message)), ['escape' =>␣
˓→false]);Make sure that you escape the input manually, then. In the above example $highlight and $message are non-HTML
input and therefore escaped.
For more information about rendering your flash messages, please refer to the FlashHelper section.
Securityclass SecurityComponent(ComponentCollection $collection, array $config = [])The Security Component creates an easy way to integrate tighter security in your application. It provides methods forvarious tasks like:• Restricting which HTTP methods your application accepts.
• Form tampering protection• Requiring that SSL be used.
• Limiting cross controller communication.
Like all components it is configured through several configurable parameters. All of these properties can be set directlyor through setter methods of the same name in your controller’s beforeFilter().
By using the Security Component you automatically get form tampering protection. Hidden token fields will automatically be inserted into forms and checked by the Security component.
If you are using Security component’s form protection features and other components that process form data in theirstartup() callbacks, be sure to place Security Component before those components in your initialize() method.
Note: When using the Security Component you must use the FormHelper to create your forms. In addition, you must
not override any of the fields’ “name” attributes. The Security Component looks for certain indicators that are createdand managed by the FormHelper (especially those created in create() and end()). Dynamically altering the fields
that are submitted in a POST request (e.g. disabling, deleting or creating new fields via JavaScript) is likely to cause
the request to be send to the blackhole callback.
You should always verify the HTTP method being used before executing to avoid side-effects. You should check the
HTTP method or use Cake\Http\ServerRequest::allowMethod() to ensure the correct HTTP method is used.

316

Chapter 10. Controllers

CakePHP Book, Release 3.10

Handling Blackhole Callbacks
SecurityComponent::blackHole(object $controller, string $error = '', SecurityException $exception = null)
If an action is restricted by the Security Component it is ‘black-holed’ as an invalid request which will result in a 400
error by default. You can configure this behavior by setting the blackHoleCallback configuration option to a callback
function in the controller.
By configuring a callback method you can customize how the blackhole process works:
public function beforeFilter(Event $event){parent::beforeFilter($event);$this->Security->setConfig('blackHoleCallback', 'blackhole');}public function blackhole($type, SecurityException $exception){if ($exception->getMessage() === 'Request is not SSL and the action is required to␣˓→be secure') {// Reword the exception message with a translatable string.
$exception->setMessage(__('Please access the requested page through HTTPS'));}// Re-throw the conditionally reworded exception.
throw $exception;// Alternatively, handle the error, e.g. set a flash message &// redirect to HTTPS version of the requested page.
}

Note: use $this->Security->config() for CakePHP versions prior to 3.4
The $type parameter can have the following values:• ‘auth’ Indicates a form validation error, or a controller/action mismatch error.
• ‘secure’ Indicates an SSL method restriction failure.
New in version cakephp/cakephp: 3.2.6
As of v3.2.6 an additional parameter is included in the blackHole callback, an instance of the Cake\Controller\
Exception\SecurityException is included as a second parameter.

More on Controllers

317

CakePHP Book, Release 3.10

Restrict Actions to SSL
SecurityComponent::requireSecure()
Sets the actions that require a SSL-secured request. Takes any number of arguments. Can be called with noarguments to force all actions to require a SSL-secured.
SecurityComponent::requireAuth()
Sets the actions that require a valid Security Component generated token. Takes any number of arguments. Can
be called with no arguments to force all actions to require a valid authentication.
Restricting Cross Controller Communication
allowedControllers
A list of controllers which can send requests to this controller. This can be used to control cross controller
requests.
allowedActions
A list of actions which are allowed to send requests to this controller’s actions. This can be used to control crosscontroller requests.
These configuration options allow you to restrict cross controller communication. Set them with the setConfig()
method, or config() if you are using a CakePHP version below 3.4.
Form Tampering Prevention
By default the SecurityComponent prevents users from tampering with forms in specific ways.
SecurityComponent will prevent the following things:

The• Unknown fields cannot be added to the form.
• Fields cannot be removed from the form.
• Values in hidden inputs cannot be modified.
Preventing these types of tampering is accomplished by working with the FormHelper and tracking which fields arein a form. The values for hidden fields are tracked as well. All of this data is combined and turned into a hash. When aform is submitted, the SecurityComponent will use the POST data to build the same structure and compare the hash.
Note: The SecurityComponent will not prevent select options from being added/changed. Nor will it prevent radio
options from being added/changed.
unlockedFields
Set to a list of form fields to exclude from POST validation. Fields can be unlocked either in the Component, orwith FormHelper::unlockField(). Fields that have been unlocked are not required to be part of the POST
and hidden unlocked fields do not have their values checked.
validatePost
Set to false to completely skip the validation of POST requests, essentially turning off form validation.
The above configuration options can be set with setConfig() or config() for CakePHP versions below 3.4.

318

Chapter 10. Controllers

CakePHP Book, Release 3.10

Usage
Using the security component is generally done in the controller’s beforeFilter(). You would specify the security
restrictions you want and the Security Component will enforce them on its startup:
namespace App\Controller;
use App\Controller\AppController;
use Cake\Event\Event;class WidgetsController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Security');}public function beforeFilter(Event $event){parent::beforeFilter($event);
if ($this->request->getParam('admin')) {$this->Security->requireSecure();}}}The above example would force all actions that had admin routing to require secure SSL requests:
namespace App\Controller;
use App\Controller\AppController;
use Cake\Event\Event;class WidgetsController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Security', ['blackHoleCallback' => 'forceSSL']);}
public function beforeFilter(Event $event){parent::beforeFilter($event);
if ($this->request->getParam('admin')) {$this->Security->requireSecure();}}public function forceSSL($error = '', SecurityException $exception = null)(continues on next page)

More on Controllers

319

CakePHP Book, Release 3.10

(continued from previous page){') {if ($exception instanceof SecurityException && $exception->getType() === 'secure˓→

return $this->redirect('https://' . env('SERVER_NAME') . Router::url($this->request->getRequestTarget()));}

˓→

throw $exception;}}

Note: Use $this->request->here() for CakePHP versions prior to 3.4.0
This example would force all actions that had admin routing to require secure SSL requests. When the request isblack holed, it will call the nominated forceSSL() callback which will redirect non-secure requests to secure requests
automatically.
CSRF Protection
CSRF or Cross Site Request Forgery is a common vulnerability in web applications. It allows an attacker to capture
and replay a previous request, and sometimes submit data requests using image tags or resources on other domains. To
enable CSRF protection features use the Cross Site Request Forgery.
Disabling Security Component for Specific Actions
There may be cases where you want to disable all security checks for an action (ex. AJAX requests). You may“unlock” these actions by listing them in $this->Security->unlockedActions in your beforeFilter(). The
unlockedActions property will not affect other features of SecurityComponent:
namespace App\Controller;
use App\Controller\AppController;
use Cake\Event\Event;class WidgetController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Security');}public function beforeFilter(Event $event){parent::beforeFilter($event);$this->Security->setConfig('unlockedActions', ['edit']);
}
}

320

Chapter 10. Controllers

CakePHP Book, Release 3.10

Note: Use $this->Security->config() for CakePHP versions prior to 3.4.0
This example would disable all security checks for the edit action.
Pagination
class Cake\Controller\Component\PaginatorComponent
One of the main obstacles of creating flexible and user-friendly web applications is designing an intuitive user interface.
Many applications tend to grow in size and complexity quickly, and designers and programmers alike find they areunable to cope with displaying hundreds or thousands of records. Refactoring takes time, and performance and user
satisfaction can suffer.
Displaying a reasonable number of records per page has always been a critical part of every application and used tocause many headaches for developers. CakePHP eases the burden on the developer by providing a quick, easy way topaginate data.
Pagination in CakePHP is offered by a component in the controller. You then use PaginatorHelper in your view
templates to generate pagination controls.
Basic Usage
To paginate a query we first need to load the PaginatorComponent:
class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Paginator');}}Once loaded we can paginate an ORM table class or Query object:public function index(){// Paginate the ORM table.
$this->set('articles', $this->paginate($this->Articles));// Paginate a partially completed query$query = $this->Articles->find('published');$this->set('articles', $this->paginate($query));}More on Controllers

321CakePHP Book, Release 3.10

Advanced Usage
PaginatorComponent supports more complex use cases by configuring the $paginate controller property or as the$settings argument to paginate(). These conditions service as the basis for you pagination queries. They areaugmented by the sort, direction, limit, and page parameters passed in from the URL:
class ArticlesController extends AppController{
public $paginate = ['limit' => 25,'order' => ['Articles.title' => 'asc']];}

Tip: Default order options must be defined as an array.
While you can include any of the options supported by find() such as fields in your pagination settings. It is cleaner
and simpler to bundle your pagination options into a Custom Find Method. You can use your finder in pagination byusing the finder option:
class ArticlesController extends AppController{
public $paginate = ['finder' => 'published',];}
If your finder method requires additional options you can pass those as values for the finder:class ArticlesController extends AppController{// find articles by tag
public function tags(){$tags = $this->request->getParam('pass');$customFinderOptions = ['tags' => $tags];// We're using the $settings argument to paginate() here.
// But the same structure could be used in $this->paginate//// Our custom finder is called findTagged inside ArticlesTable.php// which is why we're using `tagged` as the key.
// Our finder should look like:// public function findTagged(Query $query, array $options) {$settings = ['finder' => ['tagged' => $customFinderOptions](continues on next page)

322

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)];$articles = $this->paginate($this->Articles, $settings);$this->set(compact('articles', 'tags'));}}In addition to defining general pagination values, you can define more than one set of pagination defaults in the controller. The name of each model can be used as a key in the $paginate property:
class ArticlesController extends AppController{
public $paginate = ['Articles' => [],'Authors' => [],];}The values of the Articles and Authors keys could contain all the properties that a basic $paginate array would.
Once you have used paginate() to create results. The controller’s request will be updated with paging parameters.
You can access the pagination metadata at $this->request->getParam('paging').
Simple Pagination
By default pagination uses a count() query to calculate the size of the result set so that page number links can berendered. On very large datasets this count query can be very expensive. In situations where you only want to show
‘Next’ and ‘Previous’ links you can use the ‘simple’ paginator which does not do a count query:public function initialize(){
parent::initialize();// Load the paginator component with the simple paginator strategy.
$this->loadComponent('Paginator', ['paginator' => new \Cake\Datasource\SimplePaginator(),]);}
When using the SimplePaginator you will not be able to generate page numbers, counter data, links to the last page,or total record count controls.
New in version 3.9.0: SimplePaginator was added.

More on Controllers

323

CakePHP Book, Release 3.10

Using the PaginatorComponent Directly
If you need to paginate data from another component you may want to use the PaginatorComponent directly. Itfeatures a similar API to the controller method:$articles = $this->Paginator->paginate($articleTable->find(), $config);// Or$articles = $this->Paginator->paginate($articleTable, $config);
The first parameter should be the query object from a find on table object you wish to paginate results from. Optionally,
you can pass the table object and let the query be constructed for you. The second parameter should be the array ofsettings to use for pagination. This array should have the same structure as the $paginate property on a controller.
When paginating a Query object, the finder option will be ignored. It is assumed that you are passing in the query
you want paginated.
Paginating Multiple Queries
You can paginate multiple models in a single controller action, using the scope option both in the controller’s$paginate property and in the call to the paginate() method:// Paginate property
public $paginate = ['Articles' => ['scope' => 'article'],'Tags' => ['scope' => 'tag']];// In a controller action$articles = $this->paginate($this->Articles, ['scope' => 'article']);$tags = $this->paginate($this->Tags, ['scope' => 'tag']);$this->set(compact('articles', 'tags'));
The scope option will result in PaginatorComponent looking in scoped query string parameters. For example, thefollowing URL could be used to paginate both tags and articles at the same time:/dashboard?article[page]=1&tag[page]=3See the Paginating Multiple Results section for how to generate scoped HTML elements and URLs for pagination.
New in version 3.3.0: Multiple Pagination was added in 3.3.0
Paginating the Same Model multiple Times
To paginate the same model multiple times within a single controller action you need to define an alias for the model.
See Using the TableLocator for additional details on how to use the table registry:// In a controller action$this->paginate = ['ArticlesTable' => ['scope' => 'published_articles','limit' => 10,'order' => [(continues on next page)

324

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)'id' => 'desc',],],'UnpublishedArticlesTable' => ['scope' => 'unpublished_articles','limit' => 10,'order' => ['id' => 'desc',],],];// Register an additional table object to allow differentiating in pagination component
TableRegistry::config('UnpublishedArticles', ['className' => 'App\Model\Table\ArticlesTable','table' => 'articles','entityClass' => 'App\Model\Entity\Article',]);$publishedArticles = $this->paginate($this->Articles->find('all', ['scope' => 'published_articles'])->where(['published' => true]));$unpublishedArticles = $this->paginate(
TableRegistry::getTableLocator()->get('UnpublishedArticles')->find('all', ['scope' => 'unpublished_articles'])->where(['published' => false]));

Control which Fields Used for Ordering
By default sorting can be done on any non-virtual column a table has. This is sometimes undesirable as it allows users
to sort on un-indexed columns that can be expensive to order by. You can set the whitelist of fields that can be sorted
using the sortWhitelist option. This option is required when you want to sort on any associated data, or computed
fields that may be part of your pagination query:public $paginate = ['sortWhitelist' => ['id', 'title', 'Users.username', 'created']];
Any requests that attempt to sort on fields not in the whitelist will be ignored.

More on Controllers

325

CakePHP Book, Release 3.10

Limit the Maximum Number of Rows per Page
The number of results that are fetched per page is exposed to the user as the limit parameter. It is generally undesirable
to allow users to fetch all rows in a paginated set. The maxLimit option asserts that no one can set this limit too highfrom the outside. By default CakePHP limits the maximum number of rows that can be fetched to 100. If this default is
not appropriate for your application, you can adjust it as part of the pagination options, for example reducing it to 10:
public $paginate = [// Other keys here.
'maxLimit' => 10];
If the request’s limit param is greater than this value, it will be reduced to the maxLimit value.
Joining Additional Associations
Additional associations can be loaded to the paginated table by using the contain parameter:
public function index(){$this->paginate = ['contain' => ['Authors', 'Comments']];$this->set('articles', $this->paginate($this->Articles));}

Out of Range Page Requests
The PaginatorComponent will throw a NotFoundException when trying to access a non-existent page, i.e. page
number requested is greater than total page count.
So you could either let the normal error page be rendered or use a try catch block and take appropriate action when a
NotFoundException is caught:// Prior to 3.6 use Cake\Network\Exception\NotFoundException
use Cake\Http\Exception\NotFoundException;
public function index(){
try {$this->paginate();} catch (NotFoundException $e) {// Do something here like redirecting to first or last page.
// $this->request->getParam('paging') will give you required info.
}
}

326

Chapter 10. Controllers

CakePHP Book, Release 3.10

Pagination in the View
Check the PaginatorHelper documentation for how to create links for pagination navigation.
Request Handlingclass RequestHandlerComponent(ComponentCollection $collection, array $config = [])The Request Handler component is used in CakePHP to obtain additional information about the HTTP requests thatare made to your application. You can use it to see what content types clients prefer, automatically parse request input,
define how content types map to view classes or template paths.
By default RequestHandler will automatically detect AJAX requests based on the X-Requested-With HTTP header
that many JavaScript libraries use. When used in conjunction with Cake\Routing\Router::extensions(), RequestHandler will automatically switch the layout and template files to those that match non-HTML media types. Furthermore, if a helper with the same name as the requested extension exists, it will be added to the Controllers Helper
array. Lastly, if XML/JSON data is POST’ed to your Controllers, it will be parsed into an array which is assigned to$this->request->getData(), and can then be accessed as you would standard POST data. In order to make use ofRequestHandler it must be included in your initialize() method:class WidgetsController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}// Rest of controller}

Obtaining Request Information
Request Handler has several methods that provide information about the client and its request.
RequestHandlerComponent::accepts($type = null)$type can be a string, or an array, or null. If a string, accepts() will return true if the client accepts the content
type. If an array is specified, accepts() return true if any one of the content types is accepted by the client. Ifnull returns an array of the content-types that the client accepts. For example:
class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
public function beforeFilter(Event $event){if ($this->RequestHandler->accepts('html')) {// Execute code only if client accepts an HTML (text/html)(continues on next page)

More on Controllers

327

CakePHP Book, Release 3.10

(continued from previous page)// response.
} elseif ($this->RequestHandler->accepts('xml')) {// Execute XML-only code}
if ($this->RequestHandler->accepts(['xml', 'rss', 'atom'])) {// Executes if the client accepts any of the above: XML, RSS// or Atom.
}}}
Other request ‘type’ detection methods include:
RequestHandlerComponent::isXml()
Returns true if the current request accepts XML as a response.
RequestHandlerComponent::isRss()
Returns true if the current request accepts RSS as a response.
RequestHandlerComponent::isAtom()Returns true if the current call accepts an Atom response, false otherwise.
RequestHandlerComponent::isMobile()
Returns true if user agent string matches a mobile web browser, or if the client accepts WAP content. The
supported Mobile User Agent strings are:
• Android• AvantGo• BlackBerry• DoCoMo• Fennec• iPad• iPhone• iPod• J2ME• MIDP• NetFront• Nokia• Opera Mini
• Opera Mobi
• PalmOS• PalmSource• portalmmm• Plucker• ReqwirelessWeb

328

Chapter 10. Controllers

CakePHP Book, Release 3.10

• SonyEricsson• Symbian• UP.Browser• webOS• Windows CE• Windows Phone OS• XiinoRequestHandlerComponent::isWap()
Returns true if the client accepts WAP content.
All of the above request detection methods can be used in a similar fashion to filter functionality intended for specificcontent types. For example when responding to AJAX requests, you often will want to disable browser caching, andchange the debug level. However, you want to allow caching for non-AJAX requests. The following would accomplishthat:
if ($this->request->is('ajax')) {$this->response = $this->response->withDisabledCache();// Prior to 3.4.0$this->response->disableCache();}// Continue Controller action

Automatically Decoding Request Data
Add a request data decoder. The handler should contain a callback, and any additional arguments for the callback. The
callback should return an array of data contained in the request input. For example adding a CSV handler could looklike:class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$parser = function ($data) {$rows = str_getcsv($data, "\n");foreach ($rows as &$row) {$row = str_getcsv($row, ',');}
return $rows;};$this->loadComponent('RequestHandler', ['inputTypeMap' => ['csv' => [$parser]
]
]);
}
}

More on Controllers

329

CakePHP Book, Release 3.10

You can use any callable125 for the handling function. You can also pass additional arguments to the callback, this isuseful for callbacks like json_decode:$this->RequestHandler->addInputType('json', ['json_decode', true]);// After 3.1.0 you should use$this->RequestHandler->config('inputTypeMap.json', ['json_decode', true]);
The above will make $this->request->getData() an array of the JSON input data, without the additional true
you’d get a set of stdClass objects.
Deprecated since version 3.1.0: As of 3.1.0 the addInputType() method is deprecated. You should use config() to
add input types at runtime.
Changed in version 3.6.0: You should prefer using body-parser-middleware instead of RequestHandlerComponent.
Checking Content-Type Preferences
RequestHandlerComponent::prefers($type = null)
Determines which content-types the client prefers. If no parameter is given the most likely content type is returned.
If $type is an array the first type the client accepts will be returned. Preference is determined primarily by the fileextension parsed by Router if one has been provided, and secondly by the list of content-types in HTTP_ACCEPT:$this->RequestHandler->prefers('json');Responding To Requests
RequestHandlerComponent::renderAs($controller, $type)
Change the render mode of a controller to the specified type. Will also append the appropriate helper to the controller’shelper array if available and not already in the array:// Force the controller to render an xml response.
$this->RequestHandler->renderAs($this, 'xml');
This method will also attempt to add a helper that matches your current content type. For example if you render as rss,
the RssHelper will be added.
RequestHandlerComponent::respondAs($type, $options)
Sets the response header based on content-type map names. This method lets you set a number of response properties
at once:$this->RequestHandler->respondAs('xml', [// Force download'attachment' => true,'charset' => 'UTF-8']);
RequestHandlerComponent::responseType()
Returns the current response type Content-type header or null if one has yet to be set.
125 https://php.net/callback

330

Chapter 10. Controllers

CakePHP Book, Release 3.10

Taking Advantage of HTTP Cache Validation
The HTTP cache validation model is one of the processes used for cache gateways, also known as reverse proxies, todetermine if they can serve a stored copy of a response to the client. Under this model, you mostly save bandwidth, butwhen used correctly you can also save some CPU processing, reducing this way response times.
Enabling the RequestHandlerComponent in your controller automatically activates a check done before rendering theview. This check compares the response object against the original request to determine whether the response was not
modified since the last time the client asked for it.
If response is evaluated as not modified, then the view rendering process is stopped, saving processing time, saving
bandwidth and no content is returned to the client. The response status code is then set to 304 Not Modified.
You can opt-out this automatic checking by setting the checkHttpCache setting to false:
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler', ['checkHttpCache' => false]);}

Using Custom ViewClasses
When using JsonView/XmlView you might want to override the default serialization with a custom View class, or add
View classes for other types.
You can map existing and new types to your custom classes. You can also set this automatically by using the
viewClassMap setting:public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler', ['viewClassMap' => ['json' => 'ApiKit.MyJson','xml' => 'ApiKit.MyXml','csv' => 'ApiKit.Csv']]);}
Deprecated since version 3.1.0: As of 3.1.0 the viewClassMap() method is deprecated. You should use config() tochange the viewClassMap at runtime.

More on Controllers

331CakePHP Book, Release 3.10

Configuring Components
Many of the core components require configuration. Some examples of components requiring configuration are AuthComponent and Cookie. Configuration for these components, and for components in general, is usually done via
loadComponent() in your Controller’s initialize() method or via the $components array:class PostsController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Auth', ['authorize' => 'Controller','loginAction' => ['controller' => 'Users', 'action' => 'login']]);$this->loadComponent('Cookie', ['expires' => '1 day']);}}You can configure components at runtime using the config() method. Often, this is done in your controller’s
beforeFilter() method. The above could also be expressed as:
public function beforeFilter(Event $event){$this->Auth->config('authorize', ['controller']);$this->Auth->config('loginAction', ['controller' => 'Users', 'action' => 'login']);$this->Cookie->config('name', 'CookieMonster');}
Like helpers, components implement a config() method that is used to get and set any configuration data for acomponent:// Read config data.
$this->Auth->config('loginAction');// Set config$this->Csrf->config('cookieName', 'token');As with helpers, components will automatically merge their $_defaultConfig property with constructor configuration to create the $_config property which is accessible with config().
Aliasing Components
One common setting to use is the className option, which allows you to alias components. This feature is usefulwhen you want to replace $this->Auth or another common Component reference with a custom implementation:// src/Controller/PostsController.php
class PostsController extends AppController{
public function initialize(){(continues on next page)

332

Chapter 10. Controllers

CakePHP Book, Release 3.10

(continued from previous page)$this->loadComponent('Auth', ['className' => 'MyAuth']);}}// src/Controller/Component/MyAuthComponent.php
use Cake\Controller\Component\AuthComponent;
class MyAuthComponent extends AuthComponent{// Add your code to override the core AuthComponent}
The above would alias MyAuthComponent to $this->Auth in your controllers.
Note: Aliasing a component replaces that instance anywhere that component is used, including inside other Components.

Loading Components on the Fly
You might not need all of your components available on every controller action. In situations like this you can load acomponent at runtime using the loadComponent() method in your controller:// In a controller action$this->loadComponent('OneTimer');$time = $this->OneTimer->getTime();Note: Keep in mind that components loaded on the fly will not have missed callbacks called. If you rely on the
beforeFilter or startup callbacks being called, you may need to call them manually depending on when you load
your component.

Using Components
Once you’ve included some components in your controller, using them is pretty simple. Each component you use is
exposed as a property on your controller. If you had loaded up the Cake\Controller\Component\FlashComponent
in your controller, you could access it like so:class PostsController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Flash');}public function delete()(continues on next page)

More on Controllers

333CakePHP Book, Release 3.10

(continued from previous page){if ($this->Post->delete($this->request->getData('Post.id')) {$this->Flash->success('Post deleted.');return $this->redirect(['action' => 'index']);}}Note: Since both Models and Components are added to Controllers as properties they share the same ‘namespace’.
Be sure to not give a component and a model the same name.

Creating a Component
Suppose our application needs to perform a complex mathematical operation in many different parts of the application.
We could create a component to house this shared logic for use in many different controllers.
The first step is to create a new component file and class.
Create the file insrc/Controller/Component/MathComponent.php. The basic structure for the component would look something like this:namespace App\Controller\Component;
use Cake\Controller\Component;
class MathComponent extends Component{
public function doComplexOperation($amount1, $amount2){
return $amount1 + $amount2;}}

Note: All components must extend Cake\Controller\Component. Failing to do this will trigger an exception.

Including your Component in your Controllers
Once our component is finished, we can use it in the application’s controllers by loading it during the controller’s
initialize() method. Once loaded, the controller will be given a new attribute named after the component, throughwhich we can access an instance of it:// In a controller// Make the new component available at $this->Math,// as well as the standard $this->Csrf
public function initialize(){
parent::initialize();$this->loadComponent('Math');$this->loadComponent('Csrf');}

334

Chapter 10. Controllers

CakePHP Book, Release 3.10

When including Components in a Controller you can also declare a set of parameters that will be passed on to theComponent’s constructor. These parameters can then be handled by the Component:// In your controller.
public function initialize(){
parent::initialize();$this->loadComponent('Math', ['precision' => 2,'randomGenerator' => 'srand']);$this->loadComponent('Csrf');}
The above would pass the array containing precision and randomGenerator to MathComponent::initialize() inthe $config parameter.
Using Other Components in your Component
Sometimes one of your components may need to use another component. In this case you can include other components
in your component the exact same way you include them in controllers - using the $components var:// src/Controller/Component/CustomComponent.php
namespace App\Controller\Component;
use Cake\Controller\Component;
class CustomComponent extends Component{// The other component your component uses
public $components = ['Existing'];// Execute any other additional setup for your component.
public function initialize(array $config){$this->Existing->foo();}public function bar(){// ...
}}// src/Controller/Component/ExistingComponent.php
namespace App\Controller\Component;
use Cake\Controller\Component;
class ExistingComponent extends Component{
public function foo(){(continues on next page)

More on Controllers

335

CakePHP Book, Release 3.10

(continued from previous page)// ...
}}

Note: In contrast to a component included in a controller no callbacks will be triggered on a component’s component.

Accessing a Component’s Controller
From within a Component you can access the current controller through the registry:$controller = $this->_registry->getController();
You can access the controller in any callback method from the event object:$controller = $event->getSubject();

Component Callbacks
Components also offer a few request life-cycle callbacks that allow them to augment the request cycle.
beforeFilter(Event $event)Is called before the controller’s beforeFilter method, but after the controller’s initialize() method.
startup(Event $event)Is called after the controller’s beforeFilter method but before the controller executes the current action handler.
beforeRender(Event $event)Is called after the controller executes the requested action’s logic, but before the controller renders views andlayout.
shutdown(Event $event)Is called before output is sent to the browser.
beforeRedirect(Event $event, $url, Response $response)
Is invoked when the controller’s redirect method is called but before any further action. If this method returns
false the controller will not continue on to redirect the request. The $url, and $response parameters allow you
to inspect and modify the location or any other headers in the response.

336

Chapter 10. Controllers

CHAPTER 11

Views

class Cake\View\View
Views are the V in MVC. Views are responsible for generating the specific output required for the request. Often
this is in the form of HTML, XML, or JSON, but streaming files and creating PDFs that users can download are also
responsibilities of the View Layer.
CakePHP comes with a few built-in View classes for handling the most common rendering scenarios:• To create XML or JSON webservices you can use the JSON and XML views.
• To serve protected files, or dynamically generated files, you can use Sending Files.
• To create multiple themed views, you can use Themes.

The App View
AppView is your application’s default View class. AppView itself extends the Cake\View\View class included in
CakePHP and is defined in src/View/AppView.php as follows:<?php
namespace App\View;
use Cake\View\View;
class AppView extends View{}
You can use your AppView to load helpers that will be used for every view rendered in your application. CakePHP
provides an initialize() method that is invoked at the end of a View’s constructor for this kind of use:

337

CakePHP Book, Release 3.10<?php
namespace App\View;
use Cake\View\View;
class AppView extends View{
public function initialize(){// Always enable the MyUtils Helper$this->loadHelper('MyUtils');}}

View Templates
The view layer of CakePHP is how you speak to your users. Most of the time your views will be rendering
HTML/XHTML documents to browsers, but you might also need to reply to a remote application via JSON, or output
a CSV file for a user.
CakePHP template files have a default extension of .ctp (CakePHP Template) and utilize the alternative PHP syntax126
for control structures and output. These files contain the logic necessary to prepare the data received from the controller
into a presentation format that is ready for your audience.

Alternative Echos
Echo, or print a variable in your template:<?php echo $variable; ?>Using Short Tag support:<?= $variable ?>Alternative Control Structures
Control structures, like if, for, foreach, switch, and while can be written in a simplified format. Notice that there
are no braces. Instead, the end brace for the foreach is replaced with endforeach. Each of the control structureslisted above has a similar closing syntax: endif, endfor, endforeach, and endwhile. Also notice that instead ofusing a semicolon after each structure (except the last one), there is a colon.
The following is an example using foreach:<ul><?php foreach ($todo as $item): ?><li><?= $item ?></li><?php endforeach; ?></ul>
126 https://php.net/manual/en/control-structures.alternative-syntax.php

338

Chapter 11. Views

CakePHP Book, Release 3.10

Another example, using if/elseif/else. Notice the colons:<?php if ($username === 'sally'): ?><h3>Hi Sally</h3><?php elseif ($username === 'joe'): ?><h3>Hi Joe</h3><?php else: ?><h3>Hi unknown user</h3><?php endif; ?>If you’d prefer using a templating language like Twig127 , a subclass of View will bridge your templating language and
CakePHP.
Template files are stored in src/Template/, in a folder named after the controller that uses the files, and named after theaction it corresponds to. For example, the view file for the Products controller’s view() action, would normally befound in src/Template/Products/view.ctp.
The view layer in CakePHP can be made up of a number of different parts. Each part has different uses, and will becovered in this chapter:• templates: Templates are the part of the page that is unique to the action being run. They form the meat of yourapplication’s response.
• elements: small, reusable bits of view code. Elements are usually rendered inside views.
• layouts: template files that contain presentational code that wraps many interfaces in your application. Most
views are rendered inside a layout.
• helpers: these classes encapsulate view logic that is needed in many places in the view layer. Among otherthings, helpers in CakePHP can help you build forms, build AJAX functionality, paginate model data, or serve
RSS feeds.
• cells: these classes provide miniature controller-like features for creating self contained UI components. See theView Cells documentation for more information.

View Variables
Any variables you set in your controller with set() will be available in both the view and the layout your action renders.
In addition, any set variables will also be available in any element. If you need to pass additional variables from theview to the layout you can either call set() in the view template, or use a Using View Blocks.
You should remember to always escape any user data before outputting it as CakePHP does not automatically escape
output. You can escape user content with the h() function:<?= h($user->bio); ?>127 https://twig.sensiolabs.org

View Templates339

CakePHP Book, Release 3.10

Setting View Variables
Cake\View\View::set(string $var, mixed $value)
Views have a set() method that is analogous to the set() found in Controller objects. Using set() from your view
file will add the variables to the layout and elements that will be rendered later. See Setting View Variables for more
information on using set().
In your view file you can do:$this->set('activeMenuButton', 'posts');
Then, in your layout, the $activeMenuButton variable will be available and contain the value ‘posts’.

Extending Views
View extending allows you to wrap one view in another. Combining this with view blocks gives you a powerful way tokeep your views DRY . For example, your application has a sidebar that needs to change depending on the specific view
being rendered. By extending a common view file, you can avoid repeating the common markup for your sidebar, andonly define the parts that change:<!-- src/Template/Common/view.ctp --><h1><?= h($this->fetch('title')) ?></h1><?= $this->fetch('content') ?><div class="actions"><h3>Related actions</h3><ul><?= $this->fetch('sidebar') ?></ul></div>
The above view file could be used as a parent view. It expects that the view extending it will define the sidebar andtitle blocks. The content block is a special block that CakePHP creates. It will contain all the uncaptured content
from the extending view. Assuming our view file has a $post variable with the data about our post, the view could
look like:<!-- src/Template/Posts/view.ctp --><?php$this->extend('/Common/view');$this->assign('title', $post->title);$this->start('sidebar');
?>
<li>
<?php
echo $this->Html->link('edit', ['action' => 'edit',$post->id
]);
?>
</li>
<?php $this->end(); ?>(continues on next page)

340

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)// The remaining content will be available as the 'content' block// In the parent view.
<?= h($post->body) ?>The post view above shows how you can extend a view, and populate a set of blocks. Any content not already in adefined block will be captured and put into a special block named content. When a view contains a call to extend(),execution continues to the bottom of the current view file. Once it is complete, the extended view will be rendered.
Calling extend() more than once in a view file will override the parent view that will be processed next:$this->extend('/Common/view');$this->extend('/Common/index');
The above will result in /Common/index.ctp being rendered as the parent view to the current view.
You can nest extended views as many times as necessary. Each view can extend another view if desired. Each parent
view will get the previous view’s content as the content block.
Note: You should avoid using content as a block name in your application. CakePHP uses this for uncaptured content
in extended views.
You can get the list of all populated blocks using the blocks() method:$list = $this->blocks();

Using View Blocks
View blocks provide a flexible API that allows you to define slots or blocks in your views/layouts that will be definedelsewhere. For example, blocks are ideal for implementing things such as sidebars, or regions to load assets at thebottom/top of the layout. Blocks can be defined in two ways: either as a capturing block, or by direct assignment. The
start(), append(), prepend(), assign(), fetch(), and end() methods allow you to work with capturing blocks:// Create the sidebar block.
$this->start('sidebar');echo $this->element('sidebar/recent_topics');
echo $this->element('sidebar/recent_comments');$this->end();// Append into the sidebar later on.
$this->start('sidebar');echo $this->fetch('sidebar');echo $this->element('sidebar/popular_topics');$this->end();
You can also append into a block using append():$this->append('sidebar');echo $this->element('sidebar/popular_topics');$this->end();(continues on next page)

Using View Blocks

341

CakePHP Book, Release 3.10

(continued from previous page)// The same as the above.
$this->append('sidebar', $this->element('sidebar/popular_topics'));If you need to clear or overwrite a block there are a couple of alternatives. The reset() method will clear or overwrite
a block at any time. The assign() method with an empty content string can also be used to clear the specified block.:// Clear the previous content from the sidebar block.
$this->reset('sidebar');// Assigning an empty string will also clear the sidebar block.
$this->assign('sidebar', '');New in version 3.2: View::reset() was added in 3.2
Assigning a block’s content is often useful when you want to convert a view variable into a block. For example, you
may want to use a block for the page title, and sometimes assign the title as a view variable in the controller:// In view file or layout above $this->fetch('title')$this->assign('title', $title);
The prepend() method allows you to prepend content to an existing block:// Prepend to sidebar$this->prepend('sidebar', 'this content goes on top of sidebar');

Displaying Blocks
You can display blocks using the fetch() method. fetch() will output a block, returning ‘’ if a block does not exist:<?= $this->fetch('sidebar') ?>You can also use fetch to conditionally show content that should surround a block should it exist. This is helpful inlayouts, or extended views where you want to conditionally show headings or other markup:// In src/Template/Layout/default.ctp<?php if ($this->fetch('menu')): ?><div class="menu"><h3>Menu options</h3><?= $this->fetch('menu') ?></div><?php endif; ?>You can also provide a default value for a block if it does not exist. This allows you to add placeholder content when ablock does not exist. You can provide a default value using the second argument:<div class="shopping-cart"><h3>Your Cart</h3><?= $this->fetch('cart', 'Your cart is empty') ?></div>

342

Chapter 11. Views

CakePHP Book, Release 3.10

Using Blocks for Script and CSS FilesThe HtmlHelper ties into view blocks, and its script(), css(), and meta() methods each update a block with thesame name when used with the block = true option:<?php// In your view file
$this->Html->script('carousel', ['block' => true]);$this->Html->css('carousel', ['block' => true]);?>// In your layout file.
<!DOCTYPE html><html lang="en"><head><title><?= h($this->fetch('title')) ?></title><?= $this->fetch('script') ?><?= $this->fetch('css') ?></head>// Rest of the layout follows
The Cake\View\Helper\HtmlHelper also allows you to control which block the scripts and CSS go to:// In your view
$this->Html->script('carousel', ['block' => 'scriptBottom']);// In your layout<?= $this->fetch('scriptBottom') ?>Layouts
A layout contains presentation code that wraps around a view. Anything you want to see in all of your views should beplaced in a layout.
CakePHP’s default layout is located at src/Template/Layout/default.ctp. If you want to change the overall look of yourapplication, then this is the right place to start, because controller-rendered view code is placed inside of the default
layout when the page is rendered.
Other layout files should be placed in src/Template/Layout. When you create a layout, you need to tell CakePHP whereto place the output of your views. To do so, make sure your layout includes a place for $this->fetch('content')
Here’s an example of what a default layout might look like:<!DOCTYPE html><html lang="en"><head><title><?= h($this->fetch('title')) ?></title><link rel="shortcut icon" href="favicon.ico" type="image/x-icon"><!-- Include external files and scripts here (See HTML helper for more info.) --><?php
echo $this->fetch('meta');echo $this->fetch('css');
echo $this->fetch('script');?>(continues on next page)

Layouts343

CakePHP Book, Release 3.10

(continued from previous page)</head><body><!-- If you'd like some sort of menu toshow up on all of your views, include it here --><div id="header"><div id="menu">...</div></div><!-- Here's where I want my views to be displayed --><?= $this->fetch('content') ?><!-- Add a footer to each displayed page --><div id="footer">...</div></body></html>The script, css and meta blocks contain any content defined in the views using the built-in HTML helper. Usefulfor including JavaScript and CSS files from views.
Note: When using HtmlHelper::css() or HtmlHelper::script() in template files, specify 'block' => true
to place the HTML source in a block with the same name. (See API for more details on usage).
The content block contains the contents of the rendered view.
You can set the title block content from inside your view file:$this->assign('title', 'View Active Users');
Empty values for the title block will be automatically replaced with a representation of the current template path,such as 'Admin/Articles'.
You can create as many layouts as you wish: just place them in the src/Template/Layout directory, and switch between
them inside of your controller actions using the controller or view’s $layout property:// From a controller
public function view(){// Set the layout.
$this->viewBuilder()->setLayout('admin');// Before 3.4$this->viewBuilder()->layout('admin');// Before 3.1$this->layout = 'admin';}// From a view file
$this->layout = 'loggedin';For example, if a section of my site included a smaller ad banner space, I might create a new layout with the smaller

344

Chapter 11. Views

CakePHP Book, Release 3.10

advertising space and specify it as the layout for all controllers’ actions using something like:namespace App\Controller;class UsersController extends AppController{
public function viewActive(){$this->set('title', 'View Active Users');$this->viewBuilder()->setLayout('default_small_ad');// or the following before 3.4$this->viewBuilder()->layout('default_small_ad');// or the following before 3.1$this->layout = 'default_small_ad';}public function viewImage(){$this->viewBuilder()->setLayout('image');// Output user image}}
Besides a default layout CakePHP’s official skeleton app also has an ‘ajax’ layout. The Ajax layout is handy for crafting
AJAX responses - it’s an empty layout. (Most AJAX calls only require a bit of markup in return, rather than a fullyrendered interface.)
The skeleton app also has a default layout to help generate RSS.

Using Layouts from Plugins
If you want to use a layout that exists in a plugin, you can use plugin syntax. For example, to use the contact layout
from the Contacts plugin:
namespace App\Controller;class UsersController extends AppController{
public function viewActive(){$this->viewBuilder()->setLayout('Contacts.contact');// or the following before 3.4$this->viewBuilder()->layout('Contacts.contact');// or the following before 3.1$this->layout = 'Contacts.contact';}}

Layouts345

CakePHP Book, Release 3.10

Elements
Cake\View\View::element(string $elementPath, array $data, array $options = [])Many applications have small blocks of presentation code that need to be repeated from page to page, sometimes
in different places in the layout. CakePHP can help you repeat parts of your website that need to be reused. These
reusable parts are called Elements. Ads, help boxes, navigational controls, extra menus, login forms, and callouts areoften implemented in CakePHP as elements. An element is basically a mini-view that can be included in other views,
in layouts, and even within other elements. Elements can be used to make a view more readable, placing the renderingof repeating elements in its own file. They can also help you re-use content fragments in your application.
Elements live in the src/Template/Element/ folder, and have the .ctp filename extension. They are output using theelement method of the view:
echo $this->element('helpbox');

Passing Variables into an Element
You can pass data to an element through the element’s second argument:echo $this->element('helpbox', ["helptext" => "Oh, this text is very helpful."]);Inside the element file, all the passed variables are available as members of the parameter array. In the above example,
the src/Template/Element/helpbox.ctp file can use the $helptext variable:// Inside src/Template/Element/helpbox.ctp
echo $helptext; // Outputs "Oh, this text is very helpful."
Keep in mind that in those view vars are merged with the view vars from the view itself. So all view vars set using
Controller::set() in the controller and View::set() in the view itself are also available inside the element.
The View::element() method also supports options for the element. The options supported are ‘cache’ and ‘callbacks’. An example:
echo $this->element('helpbox', ["helptext" => "This is passed to the element as $helptext","foobar" => "This is passed to the element as $foobar",],[// uses the "long_view" cache configuration"cache" => "long_view",// set to true to have before/afterRender called for the element"callbacks" => true]);
Element caching is facilitated through the Cache class. You can configure elements to be stored in any Cache configuration you’ve set up. This gives you a great amount of flexibility to decide where and for how long elements are stored.
To cache different versions of the same element in an application, provide a unique cache key value using the following
format:346

Chapter 11. Views

CakePHP Book, Release 3.10

$this->element('helpbox', [], ["cache" => ['config' => 'short', 'key' => 'unique value']]);If you need more logic in your element, such as dynamic data from a datasource, consider using a View Cell instead ofan element. Find out more about View Cells.

Caching Elements
You can take advantage of CakePHP view caching if you supply a cache parameter. If set to true, it will cache theelement in the ‘default’ Cache configuration. Otherwise, you can set which cache configuration should be used. See
Caching for more information on configuring Cache. A simple example of caching an element would be:echo $this->element('helpbox', [], ['cache' => true]);
If you render the same element more than once in a view and have caching enabled, be sure to set the ‘key’ parameterto a different name each time. This will prevent each successive call from overwriting the previous element() call’s
cached result. For example:
echo $this->element('helpbox',['var' => $var],['cache' => ['key' => 'first_use', 'config' => 'view_long']]);echo $this->element('helpbox',['var' => $differenVar],['cache' => ['key' => 'second_use', 'config' => 'view_long']]);
The above will ensure that both element results are cached separately. If you want all element caching to use the same
cache configuration, you can avoid some repetition by setting View::$elementCache to the cache configuration you
want to use. CakePHP will use this configuration when none is given.

Requesting Elements from a Plugin
If you are using a plugin and wish to use elements from within the plugin, just use the familiar plugin syntax. If theview is being rendered for a plugin controller/action, the plugin name will automatically be prefixed onto all elements
used, unless another plugin name is present. If the element doesn’t exist in the plugin, it will look in the main APP
folder:echo $this->element('Contacts.helpbox');
If your view is a part of a plugin, you can omit the plugin name. For example, if you are in the ContactsControllerof the Contacts plugin, the following:echo $this->element('helpbox');// andecho $this->element('Contacts.helpbox');Elements347

CakePHP Book, Release 3.10

are equivalent and will result in the same element being rendered.
For elements inside subfolder of a plugin (e.g., plugins/Contacts/Template/Element/sidebar/helpbox.ctp), use thefollowing:echo $this->element('Contacts.sidebar/helpbox');

Routing prefix and Elements
New in version 3.0.1.
If you have a Routing prefix configured, the Element path resolution can switch to a prefix location, as Layouts andaction View do. Assuming you have a prefix “Admin” configured and you call:echo $this->element('my_element');
The element first be looked for in src/Template/Admin/Element/. If such a file does not exist, it will be looked for in
the default location.

Caching Sections of Your View
Cake\View\View::cache(callable $block, array $options = [])Sometimes generating a section of your view output can be expensive because of rendered View Cells or expensive
helper operations. To help make your application run faster CakePHP provides a way to cache view sections:// Assuming some local variables
echo $this->cache(function () use ($user, $article) {echo $this->cell('UserProfile', [$user]);echo $this->cell('ArticleFull', [$article]);}, ['key' => 'my_view_key']);By default cached view content will go into the View::$elementCache cache config, but you can use the config
option to change this.

View Events
Like Controller, view trigger several events/callbacks that you can use to insert logic around the rendering life-cycle:

Event List
• View.beforeRender• View.beforeRenderFile• View.afterRenderFile• View.afterRender• View.beforeLayout• View.afterLayout
You can attach application event listeners to these events or use Helper Callbacks.
348

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Your Own View Classes
You may need to create custom view classes to enable new types of data views, or add additional custom view-rendering
logic to your application. Like most components of CakePHP, view classes have a few conventions:• View class files should be put in src/View. For example: src/View/PdfView.php• View classes should be suffixed with View. For example: PdfView.
• When referencing view class names you should$this->viewBuilder()->setClassName('Pdf');.

omit

the

View

suffix.

For

example:You’ll also want to extend View to ensure things work correctly:// In src/View/PdfView.php
namespace App\View;
use Cake\View\View;
class PdfView extends View{
public function render($view = null, $layout = null){// Custom logic here.
}}
Replacing the render method lets you take full control over how your content is rendered.

More About Views
View Cells
View cells are small mini-controllers that can invoke view logic and render out templates. The idea of cells is borrowed
from cells in Ruby128 , where they fulfill a similar role and purpose.
When to use Cells
Cells are ideal for building reusable page components that require interaction with models, view logic, and rendering
logic. A simple example would be the cart in an online store, or a data-driven navigation menu in a CMS.
128 https://github.com/trailblazer/cells

Creating Your Own View Classes

349

CakePHP Book, Release 3.10

Creating a Cell
To create a cell, define a class in src/View/Cell and a template in src/Template/Cell/. In this example, we’ll be making
a cell to display the number of messages in a user’s notification inbox. First, create the class file. Its contents shouldlook like:namespace App\View\Cell;
use Cake\View\Cell;class InboxCell extends Cell{
public function display(){}}
Save this file into src/View/Cell/InboxCell.php. As you can see, like other classes in CakePHP, Cells have a few
conventions:• Cells live in the App\View\Cell namespace. If you are making a cell in a plugin, the namespace would be
PluginName\View\Cell.
• Class names should end in Cell.
• Classes should inherit from Cake\View\Cell.
We added an empty display() method to our cell; this is the conventional default method when rendering a cell. We’ll
cover how to use other methods later in the docs. Now, create the file src/Template/Cell/Inbox/display.ctp. This will
be our template for our new cell.
You can generate this stub code quickly using bake:bin/cake bake cell Inbox
Would generate the code we created above.
Implementing the Cell
Assume that we are working on an application that allows users to send messages to each other. We have a Messages
model, and we want to show the count of unread messages without having to pollute AppController. This is a perfectuse case for a cell. In the class we just made, add the following:namespace App\View\Cell;
use Cake\View\Cell;class InboxCell extends Cell{
public function display(){$this->loadModel('Messages');$unread = $this->Messages->find('unread');$this->set('unread_count', $unread->count());
}
}

350

Chapter 11. Views

CakePHP Book, Release 3.10

Because Cells use the ModelAwareTrait and ViewVarsTrait, they behave very much like a controller would. We
can use the loadModel() and set() methods just like we would in a controller. In our template file, add the following:<!-- src/Template/Cell/Inbox/display.ctp --><div class="notification-icon">
You have <?= $unread_count ?> unread messages.
</div>

Note: Cell templates have an isolated scope that does not share the same View instance as the one used to render
template and layout for the current controller action or other cells. Hence they are unaware of any helper calls made or
blocks set in the action’s template / layout and vice versa.

Loading Cells
Cells can be loaded from views using the cell() method and works the same in both contexts:// Load an application cell
$cell = $this->cell('Inbox');// Load a plugin cell
$cell = $this->cell('Messaging.Inbox');
The above will load the named cell class and execute the display() method. You can execute other methods using
the following:// Run the expanded() method on the Inbox cell
$cell = $this->cell('Inbox::expanded');If you need controller logic to decide which cells to load in a request, you can use the CellTrait in your controller toenable the cell() method there:
namespace App\Controller;
use App\Controller\AppController;
use Cake\View\CellTrait;class DashboardsController extends AppController{
use CellTrait;// More code.
}

More About Views

351

CakePHP Book, Release 3.10

Passing Arguments to a Cell
You will often want to parameterize cell methods to make cells more flexible. By using the second and third argumentsof cell(), you can pass action parameters and additional options to your cell classes, as an indexed array:$cell = $this->cell('Inbox::recent', ['-3 days']);
The above would match the following function signature:public function recent($since){}

Rendering a Cell
Once a cell has been loaded and executed, you’ll probably want to render it. The easiest way to render a cell is to echoit:<?= $cell ?>This will render the template matching the lowercased and underscored version of our action name, e.g. display.ctp.
Because cells use View to render templates, you can load additional cells within a cell template if required.
Note: Echoing a cell uses the PHP __toString() magic method which prevents PHP from showing the filename and line number for any fatal errors raised. To obtain a meanful error message, it is recommended to use the
Cell::render() method, for example <?= $cell->render() ?>.

Rendering Alternate Templates
By convention cells render templates that match the action they are executing. If you need to render a different view
template, you can specify the template to use when rendering the cell:// Calling render() explicitly
echo $this->cell('Inbox::recent', ['-3 days'])->render('messages');// Set template before echoing the cell.
$cell = $this->cell('Inbox');$cell->viewBuilder()->setTemplate('messages');// Before 3.4$cell->viewBuilder()->template('messages');// Before 3.1$cell->template = 'messages';echo $cell;

352

Chapter 11. Views

CakePHP Book, Release 3.10

Caching Cell Output
When rendering a cell you may want to cache the rendered output if the contents don’t change often or to help improve
performance of your application. You can define the cache option when creating a cell to enable & configure caching:// Cache using the default config and a generated key$cell = $this->cell('Inbox', [], ['cache' => true]);// Cache to a specific cache config and a generated key$cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache']]);// Specify the key and config to use.
$cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache', 'key' => 'inbox_' . $user->id]]);If a key is generated the underscored version of the cell class and template name will be used.
Note: A new View instance is used to render each cell and these new objects do not share context with the main template/ layout. Each cell is self-contained and only has access to variables passed as arguments to the View::cell() call.

Paginating Data inside a Cell
Creating a cell that renders a paginated result set can be done by leveraging the Paginator class of the ORM. An
example of paginating a user’s favorite messages could look like:namespace App\View\Cell;
use Cake\View\Cell;
use Cake\Datasource\Paginator;
class FavoritesCell extends Cell{
public function display($user){$this->loadModel('Messages');// Create a paginator$paginator = new Paginator();// Paginate the model$results = $paginator->paginate($this->Messages,$this->request->getQueryParams(),[// Use a parameterized custom finder.
'finder' => ['favorites' => [$user]],// Use scoped query string parameters.
'scope' => 'favorites',](continues on next page)

More About Views

353

CakePHP Book, Release 3.10

(continued from previous page));$paging = $paginator->getPagingParams() + (array)$this->request->getParam('paging');

˓→$this->request = $this->request->withParam('paging', $paging);$this->set('favorites', $results);}}
The above cell would paginate the Messages model using scoped pagination parameters.
New in version 3.5.0: Cake\Datasource\Paginator was added in 3.5.0.
Cell Options
Cells can declare constructor options that are converted into properties when creating a cell object:namespace App\View\Cell;
use Cake\View\Cell;
use Cake\Datasource\Paginator;
class FavoritesCell extends Cell{
protected $_validCellOptions = ['limit'];protected $limit = 3;
public function display($userId){$this->loadModel('Users');$result = $this->Users->find('friends', ['for' => $userId]);$this->set('favorites', $result);}}
Here we have defined a $limit property and add limit as a cell option. This will allow us to define the option whencreating the cell:$cell = $this->cell('Favorites', [$user->id], ['limit' => 10])
Cell options are handy when you want data available as properties allowing you to override default values.

354

Chapter 11. Views

CakePHP Book, Release 3.10

Themes
Themes in CakePHP are simply plugins that focus on providing template files. See the section on Creating Your Own
Plugins. You can take advantage of themes, making it easy to switch the look and feel of your page quickly. In addition
to template files, they can also provide helpers and cells if your theming requires that. When using cells and helpers
from your theme, you will need to continue using the plugin syntax.
To use themes, set the theme name in your controller’s action or beforeRender() callback:class ExamplesController extends AppController{// For CakePHP before 3.1
public $theme = 'Modern';public function beforeRender(\Cake\Event\Event $event){$this->viewBuilder()->setTheme('Modern');// For CakePHP before 3.5$this->viewBuilder()->theme('Modern');}}
Theme template files need to be within a plugin with the same name. For example, the above theme would be found inplugins/Modern/src/Template. It’s important to remember that CakePHP expects PascalCase plugin/theme names.
Beyond that, the folder structure within the plugins/Modern/src/Template folder is exactly the same as src/Template/.
For example, the view file for an edit action of a Posts controller would reside at plugins/Modern/src/Template/Posts/edit.ctp. Layout files would reside in plugins/Modern/src/Template/Layout/.
You can provide customized templates for plugins with a theme as well. If you had a plugin named ‘Cms’, that contained a TagsController, the Modern theme could provide plugins/Modern/src/Template/Plugin/Cms/Tags/edit.ctp
to replace the edit template in the plugin.
If a view file can’t be found in the theme, CakePHP will try to locate the view file in the src/Template/ folder. Thisway, you can create master template files and simply override them on a case-by-case basis within your theme folder.
If your theme also acts as a plugin, don’t forget to ensure it is loaded in your application’s bootstrap method. For
example:// Load our plugin theme residing in the folder /plugins/Modern$this->addPlugin('Modern');

Theme Assets
Because themes are standard CakePHP plugins, they can include any necessary assets in their webroot directory. This
allows for easy packaging and distribution of themes. Whilst in development, requests for theme assets will be handled
by Cake\Routing\Dispatcher. To improve performance for production environments, it’s recommended that you
Improve Your Application’s Performance.
All of CakePHP’s built-in helpers are aware of themes and will create the correct paths automatically. Like templatefiles, if a file isn’t in the theme folder, it will default to the main webroot folder:// When in a theme with the name of 'purple_cupcake'$this->Html->css('main.css');(continues on next page)

More About Views

355

CakePHP Book, Release 3.10

(continued from previous page)// creates a path like/purple_cupcake/css/main.css// and links toplugins/PurpleCupcake/webroot/css/main.css

JSON and XML views
The JsonView and XmlView let you create JSON and XML responses, and integrate with the Cake\Controller\
Component\RequestHandlerComponent.
By enabling RequestHandlerComponent in your application, and enabling support for the json and/or xml extensions, you can automatically leverage the new view classes. JsonView and XmlView will be referred to as data views
for the rest of this page.
There are two ways you can generate data views. The first is by using the _serialize key, and the second is by creating
normal template files.
Enabling Data Views in Your Application
Before you can use the data view classes, you’ll first need to load the Cake\Controller\Component\
RequestHandlerComponent in your controller:
public function initialize(){...
$this->loadComponent('RequestHandler');}This can be done in your AppController and will enable automatic view class switching on content types. You canalso set the component up with the viewClassMap setting, to map types to your custom classes and/or map other datatypes.
You can optionally enable the json and/or xml extensions with Routing File Extensions. This will allow you to accessthe JSON, XML or any other special format views by using a custom URL ending with the name of the response type asa file extension such as http://example.com/articles.json.
By default, when not enabling Routing File Extensions, the request, the Accept header is used for, selecting which
type of format should be rendered to the user. An example Accept format that is used to render JSON responses isapplication/json.
Using Data Views with the Serialize Key
The _serialize key is a special view variable that indicates which other view variable(s) should be serialized whenusing a data view. This lets you skip defining template files for your controller actions if you don’t need to do any
custom formatting before your data is converted into json/xml.
If you need to do any formatting or manipulation of your view variables before generating the response, you should use
template files. The value of _serialize can be either a string or an array of view variables to serialize:

356

Chapter 11. Views

CakePHP Book, Release 3.10

namespace App\Controller;class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
public function index(){// Set the view vars that have to be serialized.
$this->set('articles', $this->paginate());// Specify which view vars JsonView should serialize.
$this->set('_serialize', 'articles');}}
You can also define _serialize as an array of view variables to combine:namespace App\Controller;class ArticlesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
public function index(){// Some code that created $articles and $comments// Set the view vars that have to be serialized.
$this->set(compact('articles', 'comments'));// Specify which view vars JsonView should serialize.
$this->set('_serialize', ['articles', 'comments']);}}Defining _serialize as an array has added the benefit of automatically appending a top-level <response> element
when using XmlView. If you use a string value for _serialize and XmlView, make sure that your view variable hasa single top-level element. Without a single top-level element the Xml will fail to generate.

More About Views

357

CakePHP Book, Release 3.10

Using a Data View with Template Files
You should use template files if you need to do some manipulation of your view content before creating the final output.
For example if we had articles, that had a field containing generated HTML, we would probably want to omit that froma JSON response. This is a situation where a view file would be useful:// Controller codeclass ArticlesController extends AppController{
public function index(){$articles = $this->paginate('Articles');$this->set(compact('articles'));}}// View code - src/Template/Articles/json/index.ctp
foreach ($articles as &$article) {unset($article->generated_html);}
echo json_encode(compact('articles'));
You can do more complex manipulations, or use helpers to do formatting as well. The data view classes don’t support
layouts. They assume that the view file will output the serialized content.
Note: As of 3.1.0 until 3.5.0, AppController in the application skeleton automatically added '_serialize' => true
to all XML/JSON requests. You will need to remove this code from the beforeRender callback or set '_serialize'=> false in your controller’s action if you want to use view files.

Creating XML Views
class XmlView
By default when using _serialize the XmlView will wrap your serialized view variables with a <response> node.
You can set a custom name for this node using the _rootNode view variable.
The XmlView class supports the _xmlOptions variable that allows you to customize the options used to generateXML, e.g. tags vs attributes.
An example of using XmlView would be to generate a sitemap.xml129 . This document type requires that you change_rootNode and set attributes. Attributes are defined using the @ prefix:
public function sitemap(){$pages = $this->Pages->find();$urls = [];foreach ($pages as $page) {$urls[] = ['loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->
˓→slug, '_full' => true]),'lastmod' => $page->modified->format('Y-m-d'),(continues on next page)
129 https://www.sitemaps.org/protocol.html

358

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)'changefreq' => 'daily','priority' => '0.5'];}// Define a custom root node in the generated document.
$this->set('_rootNode', 'urlset');$this->set([// Define an attribute on the root node.
'@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9','url' => $urls]);$this->set('_serialize', ['@xmlns', 'url']);}Creating JSON Views
class JsonView
The JsonView class supports the _jsonOptions variable that allows you to customize the bit-mask used to generate
JSON. See the json_encode130 documentation for the valid values of this option.
For example, to serialize validation error output of CakePHP entities in a consistent form of JSON do:// In your controller's action when saving failed$this->set('errors', $articles->errors());$this->set('_jsonOptions', JSON_FORCE_OBJECT);$this->set('_serialize', ['errors']);

JSONP Responses
When using JsonView you can use the special view variable _jsonp to enable returning a JSONP response. Setting it
to true makes the view class check if query string parameter named “callback” is set and if so wrap the json responsein the function name provided. If you want to use a custom query string parameter name instead of “callback” set_jsonp to required name instead of true.
Example Usage
While the RequestHandlerComponent can automatically set the view based on the request content-type or extension,
you could also handle view mappings in your controller:// src/Controller/VideosController.php
namespace App\Controller;
use App\Controller\AppController;// Prior to 3.6 use Cake\Network\Exception\NotFoundException
use Cake\Http\Exception\NotFoundException;(continues on next page)
130 https://php.net/json_encode

More About Views

359

CakePHP Book, Release 3.10

(continued from previous page)class VideosController extends AppController{
public function export($format = ''){$format = strtolower($format);// Format to view mapping$formats = ['xml' => 'Xml','json' => 'Json',];// Error on unknown typeif (!isset($formats[$format])) {throw new NotFoundException(__('Unknown format.'));}// Set Out Format View
$this->viewBuilder()->className($formats[$format]);// Get data$videos = $this->Videos->find('latest');// Set Data View
$this->set(compact('videos'));$this->set('_serialize', ['videos']);// Set Force Download// Prior to 3.4.0// $this->response->download('report-' . date('YmdHis') . '.' . $format);return $this->response->withDownload('report-' . date('YmdHis') . '.' . $format);}}

Helpers
Helpers are the component-like classes for the presentation layer of your application. They contain presentational logic
that is shared between many views, elements, or layouts. This chapter will show you how to configure helpers. How toload helpers and use those helpers, and outline the simple steps for creating your own custom helpers.
CakePHP includes a number of helpers that aid in view creation. They assist in creating well-formed markup (including
forms), aid in formatting text, times and numbers, and can even speed up AJAX functionality. For more informationon the helpers included in CakePHP, check out the chapter for each helper:

360

Chapter 11. Views

CakePHP Book, Release 3.10

Breadcrumbs
class Cake\View\Helper\BreadcrumbsHelper(View $view, array $config = [])New in version 3.3.6.
BreadcrumbsHelper provides a way to easily deal with the creation and rendering of a breadcrumbs trail for your app.
Creating a Breadcrumbs Trail
You can add a crumb to the list using the add() method. It takes three arguments:• title The string to be displayed as a the title of the crumb• url A string or an array of parameters that will be given to the Url• options An array of attributes for the item and itemWithoutLink templates. See the section about defining
attributes for the item for more information.
In addition to adding to the end of the trail, you can do a variety of operations:// Add at the end of the trail$this->Breadcrumbs->add('Products',['controller' => 'products', 'action' => 'index']);// Add multiple crumbs at the end of the trail$this->Breadcrumbs->add([['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view',
˓→ 1234]]]);// Prepended crumbs will be put at the top of the list
$this->Breadcrumbs->prepend('Products',['controller' => 'products', 'action' => 'index']);// Prepend multiple crumbs at the top of the trail, in the order given$this->Breadcrumbs->prepend([['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view',
˓→ 1234]]]);// Insert in a specific slot. If the slot is out of// bounds, an exception will be raised.
$this->Breadcrumbs->insertAt(
2,'Products',['controller' => 'products', 'action' => 'index']);(continues on next page)

More About Views

361

CakePHP Book, Release 3.10

(continued from previous page)// Insert before another crumb, based on the title.
// If the named crumb title cannot be found,// an exception will be raised.
$this->Breadcrumbs->insertBefore('A product name', // the title of the crumb to insert before'Products',['controller' => 'products', 'action' => 'index']);// Insert after another crumb, based on the title.
// If the named crumb title cannot be found,// an exception will be raised.
$this->Breadcrumbs->insertAfter('A product name', // the title of the crumb to insert after'Products',['controller' => 'products', 'action' => 'index']);
Using these methods gives you the ability to work with CakePHP’s 2-step rendering process. Since templates andlayouts are rendered from the inside out (meaning, included elements are rendered first), this allows you to define
precisely where you want to add a breadcrumb.
Rendering the Breadcrumbs Trail
After adding crumbs to the trail, you can easily render it using the render() method. This method accepts two arrayarguments:• $attributes : An array of attributes that will applied to the wrapper template. This gives you the ability
to add attributes to the HTML tag. It accepts the special templateVars key to allow the insertion of custom
template variables in the template.
• $separator : An array of attributes for the separator template. Possible properties are:– separator The string to be displayed as a separator– innerAttrs To provide attributes in case your separator is divided in two elements– templateVars Allows the insertion of custom template variable in the template
All other properties will be converted as HTML attributes and will replace the attrs key in the template. If you
use the default for this option (empty), it will not render a separator.
Here is an example of how to render a trail:
echo $this->Breadcrumbs->render(['class' => 'breadcrumbs-trail'],['separator' => '<i class="fa fa-angle-right"></i>']);

362

Chapter 11. Views

CakePHP Book, Release 3.10

Customizing the Output
The BreadcrumbsHelper internally uses the StringTemplateTrait, which gives the ability to easily customize output
of various HTML strings. It includes four templates, with the following default declaration:['wrapper' => '<ul{{attrs}}>{{content}}</ul>','item' => '<li{{attrs}}><a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{˓→{separator}}','itemWithoutLink' => '<li{{attrs}}><span{{innerAttrs}}>{{title}}</span></li>{˓→{separator}}','separator' => '<li{{attrs}}><span{{innerAttrs}}>{{separator}}</span></li>']
You can easily customize them using the templates() method from the StringTemplateTrait:$this->Breadcrumbs->templates(['wrapper' => '<nav class="breadcrumbs"><ul{{attrs}}>{{content}}</ul></nav>',]);
Since your templates will be rendered, the templateVars option allows you to add your own template variables in thevarious templates:$this->Breadcrumbs->templates(['item' => '<li{{attrs}}>{{icon}}<a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{˓→{separator}}']);And to define the {{icon}} parameter, just specify it when adding the crumb to the trail:$this->Breadcrumbs->add('Products',['controller' => 'products', 'action' => 'index'],['templateVars' => ['icon' => '<i class="fa fa-money"></i>']]);Defining Attributes for the Item
If you want to apply specific HTML attributes to both the item and its sub-item , you can leverage the innerAttrs
key, which the $options argument provides. Everything except innerAttrs and templateVars will be rendered asHTML attributes:$this->Breadcrumbs->add('Products',['controller' => 'products', 'action' => 'index'],['class' => 'products-crumb','data-foo' => 'bar',(continues on next page)

More About Views

363

CakePHP Book, Release 3.10

(continued from previous page)'innerAttrs' => ['class' => 'inner-products-crumb','id' => 'the-products-crumb']]);// Based on the default template, this will render the following HTML :<li class="products-crumb" data-foo="bar"><a href="/products/index" class="inner-products-crumb" id="the-products-crumb">
˓→Products</a></li>

Clearing the Breadcrumbs
You can clear the bread crumbs using the reset() method. This can be useful when you want to transform the crumbs
and overwrite the list:$crumbs = $this->Breadcrumbs->getCrumbs();$crumbs = collection($crumbs)->map(function ($crumb) {$crumb['options']['class'] = 'breadcrumb-item';return $crumb;})->toArray();$this->Breadcrumbs->reset()->add($crumbs);
New in version 3.4.0: The reset() method was added in 3.4.0
Flashclass Cake\View\Helper\FlashHelper(View $view, array $config = [])FlashHelper provides a way to render flash messages that were set in $_SESSION by FlashComponent. FlashComponent and FlashHelper primarily use elements to render flash messages. Flash elements are found under thesrc/Template/Element/Flash directory. You’ll notice that CakePHP’s App template comes with three flash elements:
success.ctp, default.ctp, and error.ctp.
Rendering Flash Messages
To render a flash message, you can simply use FlashHelper’s render() method in your template file:<?= $this->Flash->render() ?>By default, CakePHP uses a “flash” key for flash messages in a session. But, if you’ve specified a key when setting the
flash message in FlashComponent, you can specify which flash key to render:<?= $this->Flash->render('other') ?>You can also override any of the options that were set in FlashComponent:

364

Chapter 11. Views

CakePHP Book, Release 3.10// In your Controller$this->Flash->set('The user has been saved.', ['element' => 'success']);// In your template file: Will use great_success.ctp instead of succcess.ctp<?= $this->Flash->render('flash', ['element' => 'great_success']);Note: When building custom flash message templates, be sure to properly HTML encode any user data. CakePHP
won’t escape flash message parameters for you.
New in version 3.1: The FlashComponent now stacks messages. If you set multiple flash messages, when you callrender(), each message will be rendered in its own elements, in the order they were set.
For more information about the available array options, please refer to the FlashComponent section.
Routing Prefix and Flash Messages
New in version 3.0.1.
If you have a Routing prefix configured, you can now have your Flash elements stored in
src/Template/{Prefix}/Element/Flash. This way, you can have specific messages layouts for each part of yourapplication. For instance, using different layouts for your front-end and admin section.
Flash Messages and Themes
The FlashHelper uses normal elements to render the messages and will therefore obey any theme you might havespecified. So when your theme has a src/Template/Element/Flash/error.ctp file it will be used, just as with any
Elements and Views.
Formclass Cake\View\Helper\FormHelper(View $view, array $config = [])The FormHelper does most of the heavy lifting in form creation. The FormHelper focuses on creating forms quickly,
in a way that will streamline validation, re-population and layout. The FormHelper is also flexible - it will do almost
everything for you using conventions, or you can use specific methods to get only what you need.
Starting a Form
Cake\View\Helper\FormHelper::create(mixed $context = null, array $options = [])• $context - The context for which the form is being defined. Can be an ORM entity, ORM resultset, array of
metadata or false/null (to make a model-less form).
• $options - An array of options and/or HTML attributes.

More About Views

365

CakePHP Book, Release 3.10

The first method you’ll need to use in order to take advantage of the FormHelper is create(). This method outputs
an opening form tag.
All parameters are optional. If create() is called with no parameters supplied, it assumes you are building a form
that submits to the current controller, via the current URL. The default method for form submission is POST. If you
were to call create() inside the view for UsersController::add(), you would see something like the following
output in the rendered view:<form method="post" action="/users/add">
The $context argument is used as the form’s ‘context’. There are several built-in form contexts and you can add yourown, which we’ll cover below, in a following section. The built-in providers map to the following values of $context:• An Entity instance or an iterator will map to EntityContext131 ; this context class allows FormHelper to workwith results from the built-in ORM.
• An array containing the 'schema' key, will map to ArrayContext132 which allows you to create simple data
structures to build forms against.
• null and false will map to NullContext133 ; this context class simply satisfies the interface FormHelper requires.
This context is useful if you want to build a short form that doesn’t require ORM persistence.
All context classes also have access to the request data, making it simpler to build forms.
Once a form has been created with a context, all controls you create will use the active context. In the case of an ORM
backed form, FormHelper can access associated data, validation errors and schema metadata. You can close the active
context using the end() method, or by calling create() again.
To create a form for an entity, do the following:// If you are on /articles/add// $article should be an empty Article entity.
echo $this->Form->create($article);
Output:<form method="post" action="/articles/add">This will POST the form data to the add() action of ArticlesController. However, you can also use the same logic tocreate an edit form. The FormHelper uses the Entity object to automatically detect whether to create an add or edit
form. If the provided entity is not ‘new’, the form will be created as an edit form.
For example, if we browse to http://example.org/articles/edit/5, we could do the following:// src/Controller/ArticlesController.php:
public function edit($id = null){
if (empty($id)) {throw new NotFoundException;}$article = $this->Articles->get($id);// Save logic goes here
$this->set('article', $article);}(continues on next page)
131 https://api.cakephp.org/3.x/class-Cake.View.Form.EntityContext.html
132 https://api.cakephp.org/3.x/class-Cake.View.Form.ArrayContext.html
133 https://api.cakephp.org/3.x/class-Cake.View.Form.NullContext.html

366

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)// View/Articles/edit.ctp:// Since $article->isNew() is false, we will get an edit form<?= $this->Form->create($article) ?>Output:<form method="post" action="/articles/edit/5"><input type="hidden" name="_method" value="PUT" />Note: Since this is an edit form, a hidden input field is generated to override the default HTTP method.
In some cases, the entity’s ID is automatically appended to the end of the form’s action URL. If you would liketo avoid an ID being added to the URL, you can pass a string to $options['url'], such as '/my-account' or\Cake\Routing\Router::url(['controller' => 'Users', 'action' => 'myAccount']).
Options for Form Creation
The $options array is where most of the form configuration happens. This special array can contain a number ofdifferent key-value pairs that affect the way the form tag is generated. Valid values:• 'type' - Allows you to choose the type of form to create. If no type is provided then it will be autodetectedbased on the form context. Valid values:– 'get' - Will set the form method to HTTP GET.
– 'file' - Will set the form method to POST and the 'enctype' to “multipart/form-data”.
– 'post' - Will set the method to POST.
– 'put', 'delete', 'patch' - Will override the HTTP method with PUT, DELETE or PATCH respectively, when the form is submitted.
• 'method' - Valid values are the same as above. Allows you to explicitly override the form’s method.
• 'url' - Specify the URL the form will submit to. Can be a string or a URL array.
• 'encoding' - Sets the accept-charset encoding for the form. Defaults to Configure::read('App.
encoding').
• 'enctype' - Allows you to set the form encoding explicitly.
• 'templates' - The templates you want to use for this form. Any templates provided will be merged on top of thealready loaded templates. Can be either a filename (without extension) from /config or an array of templates
to use.
• 'context' - Additional options for the form context class. (For example the EntityContext accepts a 'table'
option that allows you to set the specific Table class the form should be based on.)• 'idPrefix' - Prefix for generated ID attributes.
• 'templateVars' - Allows you to provide template variables for the formStart template.
• autoSetCustomValidity - Set to true to use custom required and notBlank validation messages in the control’s HTML5 validity message. Default is false.

More About Views

367

CakePHP Book, Release 3.10

Tip: Besides the above options you can provide, in the $options argument, any valid HTML attributes that you wantto pass to the created form element.

Getting form values from the query string
New in version 3.4.0.
A FormHelper’s values sources define where its rendered elements, such as input-tags, receive their values from.
By default FormHelper draws its values from the ‘context’. The default contexts, such as EntityContext, will fetch
data from the current entity, or from $request->getData().
If however, you are building a form that needs to read from the query string, you can use valueSource() to change
where FormHelper reads data input data from:// Prioritize query string over context:
echo $this->Form->create($article, ['valueSources' => ['query', 'context']]);// Same effect:
echo $this->Form->setValueSources(['query', 'context'])->create($articles);// Only read data from the query stringecho $this->Form->create($article);$this->Form->setValueSources('query');// Same effect:
echo $this->Form->create($article, ['valueSources' => 'query']);The supported sources are context, data and query. You can use one or more sources. Any widgets generated by
FormHelper will gather their values from the sources, in the order you setup.
The value sources will be reset to the default (['context']) when end() is called.
Changing the HTTP Method for a Form
By using the type option you can change the HTTP method a form will use:echo $this->Form->create($article, ['type' => 'get']);Output:<form method="get" action="/articles/edit/5">
Specifying a 'file' value for type, changes the form submission method to ‘post’, and includes an enctype of“multipart/form-data” on the form tag. This is to be used if there are any file elements inside the form. The absence ofthe proper enctype attribute will cause the file uploads not to function.
E.g.

368

Chapter 11. Views

CakePHP Book, Release 3.10

echo $this->Form->create($article, ['type' => 'file']);Output:<form enctype="multipart/form-data" method="post" action="/articles/add">
When using 'put', 'patch' or 'delete' as 'type' values, your form will be functionally equivalent to a ‘post’ form,
but when submitted, the HTTP request method will be overridden with ‘PUT’, ‘PATCH’ or ‘DELETE’, respectively.
This allows CakePHP to emulate proper REST support in web browsers.
Setting a URL for the Form
Using the 'url' option allows you to point the form to a specific action in your current controller or another controller
in your application.
For example, if you’d like to point the form to the publish() action of the current controller, you would supply an$options array, like the following:echo $this->Form->create($article, ['url' => ['action' => 'publish']]);
Output:<form method="post" action="/articles/publish">
If the desired form action isn’t in the current controller, you can specify a complete URL for the form action. The
supplied URL can be relative to your CakePHP application:echo $this->Form->create(null, ['url' => ['controller' => 'Articles','action' => 'publish']]);
Output:<form method="post" action="/articles/publish">Or you can point to an external domain:echo $this->Form->create(null, ['url' => 'https://www.google.com/search','type' => 'get']);
Output:<form method="get" action="https://www.google.com/search">
Use 'url' => false if you don’t want to output a URL as the form action.

More About Views

369CakePHP Book, Release 3.10

Using Custom Validators
Often models will have multiple validation sets, and you will want FormHelper to mark fields required based on a thespecific validation rules your controller action is going to apply. For example, your Users table has specific validation
rules that only apply when an account is being registered:echo $this->Form->create($user, ['context' => ['validator' => 'register']]);
The above will use the rules defined in the register validator, which are defined byUsersTable::validationRegister(), for $user and all related associations. If you are creating a form for
associated entities, you can define validation rules for each association by using an array:echo $this->Form->create($user, ['context' => ['validator' => ['Users' => 'register','Comments' => 'default']]]);
The above would use register for the user, and default for the user’s comments.
Creating context classes
While the built-in context classes are intended to cover the basic cases you’ll encounter you may need tobuild a new context class if you are using a different ORM. In these situations you need to implement the
Cake\View\Form\ContextInterface134 . Once you have implemented this interface you can wire your new context into
the FormHelper. It is often best to do this in a View.beforeRender event listener, or in an application view class:$this->Form->addContextProvider('myprovider', function ($request, $data) {if ($data['entity'] instanceof MyOrmClass) {return new MyProvider($request, $data);}});
Context factory functions are where you can add logic for checking the form options for the correct type of entity. Ifmatching input data is found you can return an object. If there is no match return null.
Creating Form Controls
Cake\View\Helper\FormHelper::control(string $fieldName, array $options = [])• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array that can include both Options for Control, and options of the other methods (which
control() employs internally to generate various HTML elements) as well as any valid HTML attributes.
134 https://api.cakephp.org/3.x/class-Cake.View.Form.ContextInterface.html

370

Chapter 11. Views

CakePHP Book, Release 3.10

The control() method lets you to generate complete form controls. These controls will include a wrapping div,
label, control widget, and validation error if necessary. By using the metadata in the form context, this method will
choose an appropriate control type for each field. Internally control() uses the other methods of FormHelper.
Tip: Please note that while the fields generated by the control() method are called generically “inputs” on this page,technically speaking, the control() method can generate not only all of the HTML input type elements, but also
other HTML form elements (e.g. select, button, textarea).
By default the control() method will employ the following widget templates:'inputContainer' => '<div class="input {{type}}{{required}}">{{content}}</div>''input' => '<input type="{{type}}" name="{{name}}"{{attrs}}/>'
In case of validation errors it will also use:
'inputContainerError' => '<div class="input {{type}}{{required}} error">{{content}}{
˓→{error}}</div>'
The type of control created (when we provide no additional options to specify the generated element type) is inferred
via model introspection and depends on the column datatype:
Column Type
Resulting Form Field
string, uuid (char, varchar, etc.)
text
boolean, tinyint(1)checkbox
decimalnumberfloat
numberintegernumbertext
textarea
text, with name of password, passwd
password
text, with name of email
email
text, with name of tel, telephone, or phonetel
dateday, month, and year selects
datetime, timestampday, month, year, hour, minute, and meridian selects
timehour, minute, and meridian selectsMore About Views

371

CakePHP Book, Release 3.10

binaryfile
The $options parameter allows you to choose a specific control type if you need to:echo $this->Form->control('published', ['type' => 'checkbox']);Tip: As a small subtlety, generating specific elements via the control() form method will always also generate the wrapping div, by default. Generating the same type of element via one of the specific form methods (e.g.
$this->Form->checkbox('published');) in most cases won’t generate the wrapping div. Depending on yourneeds you can use one or another.
The wrapping div will have a required class name appended if the validation rules for the model’s field indicatethat it is required and not allowed to be empty. You can disable automatic required flagging using the 'required'option:echo $this->Form->control('title', ['required' => false]);To skip browser validation triggering for the whole form you can set option 'formnovalidate' => true for the
input button you generate using submit() or set 'novalidate' => true in options for create().
For example, let’s assume that your Users model includes fields for a username (varchar), password (varchar), approved(datetime) and quote (text). You can use the control() method of the FormHelper to create appropriate controls forall of these form fields:
echo $this->Form->create($user);// The following generates a Text input
echo $this->Form->control('username');// The following generates a Password input
echo $this->Form->control('password');// Assuming 'approved' is a datetime or timestamp field the following//generates: Day, Month, Year, Hour, Minuteecho $this->Form->control('approved');// The following generates a Textarea element
echo $this->Form->control('quote');echo $this->Form->button('Add');
echo $this->Form->end();
A more extensive example showing some options for a date field:
echo $this->Form->control('birth_dt', ['label' => 'Date of birth','minYear' => date('Y') - 70,'maxYear' => date('Y') - 18,]);
Besides the specific Options for Control, you also can specify any option accepted by corresponding specific method
for the chosen (or inferred by CakePHP) control type and any HTML attribute (for instance onfocus).
If you want to create a select form field while using a belongsTo (or hasOne) relation, you can add the following to
your UsersController (assuming your User belongsTo Group):$this->set('groups', $this->Users->Groups->find('list'));372

Chapter 11. Views

CakePHP Book, Release 3.10

Afterwards, add the following to your view template:echo $this->Form->control('group_id', ['options' => $groups]);
To make a select box for a belongsToMany Groups association you can add the following to your UsersController:$this->set('groups', $this->Users->Groups->find('list'));Afterwards, add the following to your view template:echo $this->Form->control('groups._ids', ['options' => $groups]);If your model name consists of two or more words (e.g. “UserGroups”), when passing the data using set() you should
name your data in a pluralised and lower camelCased135 format as follows:$this->set('userGroups', $this->UserGroups->find('list'));Note: You should not use FormHelper::control() to generate submit buttons. Use submit() instead.

Field Naming Conventions
When creating control widgets you should name your fields after the matching attributes in the form’s entity. For
example, if you created a form for an $article entity, you would create fields named after the properties. E.g. title,
body and published.
You can create controls for associated models, or arbitrary models by passing in association.fieldname as the firstparameter:
echo $this->Form->control('association.fieldname');Any dots in your field names will be converted into nested request data. For example, if you created a field with a name0.comments.body you would get a name attribute that looks like 0[comments][body]. This convention makes it
easy to save data with the ORM. Details for the various association types can be found in the Creating Inputs for
Associated Data section.
When creating datetime related controls, FormHelper will append a field-suffix. You may notice additional fields
named year, month, day, hour, minute, or meridian being added. These fields will be automatically converted into
DateTime objects when entities are marshalled.
Options for Control
FormHelper::control() supports a large number of options via its $options argument. In addition to its own
options, control() accepts options for the inferred/chosen generated control types (e.g. for checkbox or textarea),
as well as HTML attributes. This subsection will cover the options specific to FormHelper::control().
• $options['type'] - A string that specifies the widget type to be generated. In addition to the field types foundin the Creating Form Controls, you can also create 'file', 'password', and any other type supported by
HTML5. By specifying a 'type' you will force the type of the generated control, overriding model introspection.
Defaults to null.
E.g.
135 https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms

More About Views

373

CakePHP Book, Release 3.10

echo $this->Form->control('field', ['type' => 'file']);echo $this->Form->control('email', ['type' => 'email']);Output:<div class="input file"><label for="field">Field</label><input type="file" name="field" value="" id="field" /></div><div class="input email"><label for="email">Email</label><input type="email" name="email" value="" id="email" /></div>• $options['label'] - Either a string caption or an array of options for the label. You can set this key tothe string you would like to be displayed within the label that usually accompanies the input HTML element.
Defaults to null.
E.g.
echo $this->Form->control('name', ['label' => 'The User Alias']);
Output:<div class="input"><label for="name">The User Alias</label><input name="name" type="text" value="" id="name" /></div>
Alternatively, set this key to false to disable the generation of the label element.
E.g.
echo $this->Form->control('name', ['label' => false]);
Output:<div class="input"><input name="name" type="text" value="" id="name" /></div>
Set this to an array to provide additional options for the label element. If you do this, you can use a 'text'
key in the array to customize the label text.
E.g.
echo $this->Form->control('name', ['label' => ['class' => 'thingy','text' => 'The User Alias']]);
Output:374

Chapter 11. Views

CakePHP Book, Release 3.10

<div class="input"><label for="name" class="thingy">The User Alias</label><input name="name" type="text" value="" id="name" /></div>• $options['options'] - You can provide in here an array containing the elements to be generated for widgets
such as radio or select, which require an array of items as an argument (see Creating Radio Buttons andCreating Select Pickers for more details). Defaults to null.
• $options['error'] - Using this key allows you to override the default model error messages and can be used,
for example, to set i18n messages. To disable the error message output & field classes set the 'error' key tofalse. Defaults to null.
E.g.
echo $this->Form->control('name', ['error' => false]);To override the model error messages use an array with the keys matching the original validation error messages.
E.g.
$this->Form->control('name', ['error' => ['Not long enough' => __('This is not long enough')]]);
As seen above you can set the error message for each validation rule you have in your models. In addition you
can provide i18n messages for your forms.
To disable the HTML entity encoding for error messages only, the 'escape' sub key can be used:$this->Form->control('name', ['error' => ['escape' => false],]);• $options['nestedInput'] - Used with checkboxes and radio buttons. Controls whether the input element isgenerated inside or outside the label element. When control() generates a checkbox or a radio button, you
can set this to false to force the generation of the HTML input element outside of the label element.
On the other hand you can set this to true for any control type to force the generated input element inside thelabel. If you change this for radio buttons then you need to also modify the default radioWrapper template.
Depending on the generated control type it defaults to true or false.
• $options['templates'] - The templates you want to use for this input. Any specified templates will be merged
on top of the already loaded templates. This option can be either a filename (without extension) in /config that
contains the templates you want to load, or an array of templates to use.
• $options['labelOptions'] - Set this to false to disable labels around nestedWidgets or set it to an arrayof attributes to be provided to the label tag.

More About Views

375CakePHP Book, Release 3.10

Generating Specific Types of Controls
In addition to the generic control() method, FormHelper has specific methods for generating a number of different
types of controls. These can be used to generate just the control widget itself, and combined with other methods likelabel() and error() to generate fully custom form layouts.
Common Options For Specific Controls
Many of the various control element methods support a common set of options which, depending on the form method
used, must be provided inside the $options or in the $attributes array argument. All of these options are also
supported by the control() method. To reduce repetition, the common options shared by all control methods are as
follows:• 'id' - Set this key to force the value of the DOM id for the control. This will override the 'idPrefix' that may
be set.
• 'default' - Used to set a default value for the control field. The value is used if the data passed to the form
does not contain a value for the field (or if no data is passed at all). An explicit default value will override any
default values defined in the schema.
Example usage:
echo $this->Form->text('ingredient', ['default' => 'Sugar']);Example with select field (size “Medium” will be selected as default):$sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];echo $this->Form->select('size', $sizes, ['default' => 'm']);Note:
You cannot use default to check a checkbox - instead you might set the value in$this->request->getData() in your controller, or set the control option 'checked' to true.
Beware of using false to assign a default value. A false value is used to disable/exclude options of a control
field, so 'default' => false would not set any value at all. Instead use 'default' => 0.
• 'value' - Used to set a specific value for the control field. This will override any value that may else be injectedfrom the context, such as Form, Entity or request->getData() etc.
Note: If you want to set a field to not render its value fetched from context or valuesSource you will need to set'value' to '' (instead of setting it to null).
In addition to the above options, you can mixin any HTML attribute you wish to use. Any non-special option namewill be treated as an HTML attribute, and applied to the generated HTML control element.
Changed in version 3.3.0: As of 3.3.0, FormHelper will automatically use any default values defined in your database
schema. You can disable this behavior by setting the schemaDefault option to false.

376

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Input Elements
The rest of the methods available in the FormHelper are for creating specific form elements. Many of these methods also
make use of a special $options or $attributes parameter. In this case, however, this parameter is used primarily
to specify HTML tag attributes (such as the value or DOM id of an element in the form).
Creating Text Inputs
Cake\View\Helper\FormHelper::text(string $name, array $options)• $name - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls as well as any valid
HTML attributes.
Creates a simple input HTML element of text type.
E.g.
echo $this->Form->text('username', ['class' => 'users']);Will output:<input name="username" type="text" class="users">

Creating Password Inputs
Cake\View\Helper\FormHelper::password(string $fieldName, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls as well as any valid
HTML attributes.
Creates a simple input element of password type.
E.g.
echo $this->Form->password('password');Will output:<input name="password" value="" type="password">

Creating Hidden Inputs
Cake\View\Helper\FormHelper::hidden(string $fieldName, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls as well as any valid
HTML attributes.
Creates a hidden form input.
E.g.
More About Views

377

CakePHP Book, Release 3.10

echo $this->Form->hidden('id');
Will output:<input name="id" type="hidden" />Creating Textareas
Cake\View\Helper\FormHelper::textarea(string $fieldName, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls, of the specific textarea
options (see below) as well as any valid HTML attributes.
Creates a textarea control field. The default widget template used is:'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'
For example:
echo $this->Form->textarea('notes');Will output:<textarea name="notes"></textarea>
If the form is being edited (i.e. the array $this->request->getData() contains the information previously saved
for the User entity), the value corresponding to notes field will automatically be added to the HTML generated.
Example:<textarea name="notes" id="notes">
This text is to be edited.
</textarea>
Options for Textarea
In addition to the Common Options For Specific Controls, textarea() supports a couple of specific options:• 'escape' - Determines whether or not the contents of the textarea should be escaped. Defaults to true.
E.g.
echo $this->Form->textarea('notes', ['escape' => false]);// OR....
echo $this->Form->control('notes', ['type' => 'textarea', 'escape' => false]);• 'rows', 'cols' - You can use these two keys to set the HTML attributes which specify the number of rows
and columns for the textarea field.
E.g.
echo $this->Form->textarea('comment', ['rows' => '5', 'cols' => '5']);
Output:378

Chapter 11. Views

CakePHP Book, Release 3.10

<textarea name="comment" cols="5" rows="5"></textarea>

Creating Select, Checkbox and Radio Controls
These controls share some commonalities and a few options and thus, they are all grouped in this subsection for easierreference.
Options for Select, Checkbox and Radio Controls
You can find below the options which are shared by select(), checkbox() and radio() (the options particular only
to one of the methods are described in each method’s own section.)• 'value' - Sets or selects the value of the affected element(s):– For checkboxes, it sets the HTML 'value' attribute assigned to the input element to whatever you provide
as value.
– For radio buttons or select pickers it defines which element will be selected when the form is rendered (inthis case 'value' must be assigned a valid, existent element value). May also be used in combination withany select-type control, such as date(), time(), dateTime():echo $this->Form->time('close_time', ['value' => '13:30:00']);

Note: The 'value' key for date() and dateTime() controls may also have as value a UNIX timestamp, ora DateTime object.
For a select control where you set the 'multiple' attribute to true, you can provide an array with the values
you want to select by default:// HTML <option> elements with values 1 and 3 will be rendered preselectedecho $this->Form->select('rooms',[1, 2, 3, 4, 5],['multiple' => true,'value' => [1, 3]]);• 'empty' - Applies to radio() and select(). Defaults to false.
– When passed to radio() and set to true it will create an extra input element as the first radio button, witha value of '' and a label caption equal to the string 'empty'. If you want to control the label caption set
this option to a string instead.
– When passed to a select method, this creates a blank HTML option element with an empty value inyour drop down list. If you want to have an empty value with text displayed instead of just a blank option,pass a string to 'empty':More About Views

379

CakePHP Book, Release 3.10

echo $this->Form->select('field',[1, 2, 3, 4, 5],['empty' => '(choose one)']);Output:<select name="field"><option value="">(choose one)</option><option value="0">1</option><option value="1">2</option><option value="2">3</option><option value="3">4</option><option value="4">5</option></select>• 'hiddenField' - For checkboxes and radio buttons, by default, a hidden input element is also created, alongwith the main element, so that the key in $this->request->getData() will exist even without a value specified. For checkboxes its value defaults to 0 and for radio buttons to ''.
Example of default output:<input type="hidden" name="published" value="0" /><input type="checkbox" name="published" value="1" />This can be disabled by setting 'hiddenField' to false:
echo $this->Form->checkbox('published', ['hiddenField' => false]);Which outputs:<input type="checkbox" name="published" value="1">
If you want to create multiple blocks of controls on a form, that are all grouped together, you should set thisparameter to false on all controls except the first. If the hidden input is on the page in multiple places, only thelast group of inputs’ values will be saved.
In this example, only the tertiary colors would be passed, and the primary colors would be overridden:<h2>Primary Colors</h2><input type="hidden" name="color" value="0" /><label for="color-red"><input type="checkbox" name="color[]" value="5" id="color-red" />Red</label><label for="color-blue"><input type="checkbox" name="color[]" value="5" id="color-blue" />Blue</label><label for="color-yellow"><input type="checkbox" name="color[]" value="5" id="color-yellow" />Yellow(continues on next page)

380

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)</label><h2>Tertiary Colors</h2><input type="hidden" name="color" value="0" /><label for="color-green"><input type="checkbox" name="color[]" value="5" id="color-green" />Green</label><label for="color-purple"><input type="checkbox" name="color[]" value="5" id="color-purple" />Purple</label><label for="color-orange"><input type="checkbox" name="color[]" value="5" id="color-orange" />Orange</label>Disabling 'hiddenField' on the second control group would prevent this behavior.
You can set a hidden field to a value other than 0, such as ‘N’:echo $this->Form->checkbox('published', ['value' => 'Y',
'hiddenField' => 'N',]);

Using Collections to build options
It’s possible to use the Collection class to build your options array. This approach is ideal if you already have a collectionof entities and would like to build a select element from them.
You can use the combine method to build a basic options array.:$options = $examples->combine('id', 'name');It’s also possible to add extra attributes by expanding the array. The following will create a data attribute on the option
element, using the map collection method.:$options = $examples->map(function ($value, $key) {return ['value' => $value->id,'text' => $value->name,'data-created' => $value->created];});More About Views

381

CakePHP Book, Release 3.10

Creating Checkboxes
Cake\View\Helper\FormHelper::checkbox(string $fieldName, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls, or of the Options for
Select, Checkbox and Radio Controls above, of the checkbox-specific options (see below), as well as any valid
HTML attributes.
Creates a checkbox form element. The widget template used is:'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'
Options for Checkboxes• 'checked' - Boolean to indicate whether this checkbox will be checked. Defaults to false.
• 'disabled' - Create a disabled checkbox input.
This method also generates an associated hidden form input element to force the submission of data for the specified
field.
E.g.
echo $this->Form->checkbox('done');Will output:<input type="hidden" name="done" value="0"><input type="checkbox" name="done" value="1">
It is possible to specify the value of the checkbox by using the $options array.
E.g.
echo $this->Form->checkbox('done', ['value' => 555]);
Will output:<input type="hidden" name="done" value="0"><input type="checkbox" name="done" value="555">
If you don’t want the FormHelper to create a hidden input use 'hiddenField'.
E.g.
echo $this->Form->checkbox('done', ['hiddenField' => false]);Will output:<input type="checkbox" name="done" value="1">382

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Radio Buttons
Cake\View\Helper\FormHelper::radio(string $fieldName, array $options, array $attributes)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array containing at minimum the labels for the radio buttons. Can also contain valuesand HTML attributes. When this array is missing, the method will either generate only the hidden input (if'hiddenField' is true) or no element at all (if 'hiddenField' is false).
• $attributes - An optional array including any of the Common Options For Specific Controls, or of the Optionsfor Select, Checkbox and Radio Controls, of the radio button specific attributes (see below), as well as any valid
HTML attributes.
Creates a set of radio button inputs. The default widget templates used are:'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>''radioWrapper' => '{{label}}'Attributes for Radio Buttons• 'label' - Boolean to indicate whether or not labels for widgets should be displayed, or an array of attributes
to apply to all labels. In case a class attribute is defined, selected will be added to the class attribute ofchecked buttons. Defaults to true.
• 'hiddenField' - If set to true a hidden input with a value of '' will be included. This is useful for creating
radio sets that are non-continuous. Defaults to true.
• 'disabled' - Set to true or 'disabled' to disable all the radio buttons. Defaults to false.
You must provide the label captions for the radio buttons via the $options argument.
For example:$this->Form->radio('gender', ['Masculine', 'Feminine', 'Neuter']);Will output:<input name="gender" value="" type="hidden"><label for="gender-0"><input name="gender" value="0" id="gender-0" type="radio">
Masculine</label><label for="gender-1"><input name="gender" value="1" id="gender-1" type="radio">Feminine</label><label for="gender-2"><input name="gender" value="2" id="gender-2" type="radio">
Neuter</label>Generally $options contains simple key => value pairs. However, if you need to put custom attributes on yourradio buttons you can use an expanded format.
E.g.

More About Views

383

CakePHP Book, Release 3.10

echo $this->Form->radio('favorite_color',[['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],]);Will output:<input type="hidden" name="favorite_color" value=""><label for="favorite-color-r"><input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite˓→color-r">
Red</label><label for="favorite-color-u"><input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite˓→color-u">Blue</label><label for="favorite-color-g"><input type="radio" name="favorite_color" value="g" style="color:green;" id=˓→"favorite-color-g">Green</label>You can define additional attributes for an individual option’s label as well:echo $this->Form->radio('favorite_color',[['value' => 'r', 'text' => 'Red', 'label' => ['class' => 'red']],['value' => 'u', 'text' => 'Blue', 'label' => ['class' => 'blue']],]);Will output:<input type="hidden" name="favorite_color" value=""><label for="favorite-color-r" class="red"><input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite˓→color-r">
Red</label><label for="favorite-color-u" class="blue"><input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite˓→color-u">Blue</label>If the label key is used on an option, the attributes in $attributes['label'] will be ignored.
Changed in version 3.8.0: The label key in complex options was added.
384

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Select Pickers
Cake\View\Helper\FormHelper::select(string $fieldName, array $options, array $attributes)• $fieldName - A field name in the form 'Modelname.fieldname'. This will provide the name attribute of theselect element.
• $options - An optional array containing the list of items for the select picker. When this array is missing, themethod will generate only the empty select HTML element without any option elements inside it.
• $attributes - An optional array including any of the Common Options For Specific Controls, or of the Optionsfor Select, Checkbox and Radio Controls, or of the select-specific attributes (see below), as well as any valid
HTML attributes.
Creates a select element, populated with the items from the $options array. If $attributes['value'] is provided, then the HTML option element(s) which have the specified value(s) will be shown as selected when rendering
the select picker.
By default select uses the following widget templates:'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>''option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'
May also use:
'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>''selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</˓→select>'
Attributes for Select Pickers• 'multiple' - If set to true allows multiple selections in the select picker. If set to 'checkbox', multiple
checkboxes will be created instead. Defaults to null.
• 'escape' - Boolean. If true the contents of the option elements inside the select picker will be HTML entity
encoded. Defaults to true.
• 'val' - Allows preselecting a value in the select picker.
• 'disabled' - Controls the disabled attribute. If set to true disables the whole select picker. If set to an arrayit will disable only those specific option elements whose values are provided in the array.
The $options argument allows you to manually specify the contents of the option elements of a select control.
E.g.
echo $this->Form->select('field', [1, 2, 3, 4, 5]);
Output:<select name="field"><option value="0">1</option><option value="1">2</option><option value="2">3</option><option value="3">4</option><option value="4">5</option></select>
The array for $options can also be supplied as key-value pairs.

More About Views

385CakePHP Book, Release 3.10

E.g.
echo $this->Form->select('field', ['Value 1' => 'Label 1','Value 2' => 'Label 2','Value 3' => 'Label 3']);
Output:<select name="field"><option value="Value 1">Label 1</option><option value="Value 2">Label 2</option><option value="Value 3">Label 3</option></select>
If you would like to generate a select with optgroups, just pass data in hierarchical format (nested array). This works
on multiple checkboxes and radio buttons too, but instead of optgroup it wraps the elements in fieldset elements.
For example:$options = ['Group 1' => ['Value 1' => 'Label 1','Value 2' => 'Label 2'],'Group 2' => ['Value 3' => 'Label 3']];
echo $this->Form->select('field', $options);
Output:<select name="field"><optgroup label="Group 1"><option value="Value 1">Label 1</option><option value="Value 2">Label 2</option></optgroup><optgroup label="Group 2"><option value="Value 3">Label 3</option></optgroup></select>To generate HTML attributes within an option tag:
$options = [['text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1'],['text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2'],['text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_
˓→value'],];echo $this->Form->select('field', $options);
Output:386

Chapter 11. Views

CakePHP Book, Release 3.10

<select name="field"><option value="value 1" attr_name="attr_value 1">Description 1</option><option value="value 2" attr_name="attr_value 2">Description 2</option><option value="value 3" other_attr_name="other_attr_value">Description 3</option></select>
Controlling Select Pickers via Attributes
By using specific options in the $attributes parameter you can control certain behaviors of the select() method.
• 'empty' - Set the 'empty' key in the $attributes argument to true (the default value is false) to add a
blank option with an empty value at the top of your dropdown list.
For example:$options = ['M' => 'Male', 'F' => 'Female'];echo $this->Form->select('gender', $options, ['empty' => true]);Will output:<select name="gender"><option value=""></option><option value="M">Male</option><option value="F">Female</option></select>• 'escape' - The select() method allows for an attribute called 'escape' which accepts a boolean value anddetermines whether to HTML entity encode the contents of the select’s option elements.
E.g.
// This will prevent HTML-encoding the contents of each option element$options = ['M' => 'Male', 'F' => 'Female'];echo $this->Form->select('gender', $options, ['escape' => false]);• 'multiple' - If set to true, the select picker will allow multiple selections.
E.g.
echo $this->Form->select('field', $options, ['multiple' => true]);
Alternatively, set 'multiple' to 'checkbox' in order to output a list of related checkboxes:$options = ['Value 1' => 'Label 1','Value 2' => 'Label 2'];
echo $this->Form->select('field', $options, ['multiple' => 'checkbox']);
Output:<input name="field" value="" type="hidden"><div class="checkbox"><label for="field-1">(continues on next page)

More About Views

387

CakePHP Book, Release 3.10

(continued from previous page)<input name="field[]" value="Value 1" id="field-1" type="checkbox">
Label 1</label></div><div class="checkbox"><label for="field-2"><input name="field[]" value="Value 2" id="field-2" type="checkbox">
Label 2</label></div>• 'disabled' - This option can be set in order to disable all or some of the select’s option items. To disable
all items set 'disabled' to true. To disable only certain items, assign to 'disabled' an array containing thekeys of the items to be disabled.
E.g.
$options = ['M' => 'Masculine','F' => 'Feminine','N' => 'Neuter'];echo $this->Form->select('gender', $options, ['disabled' => ['M', 'N']]);
Will output:<select name="gender"><option value="M" disabled="disabled">Masculine</option><option value="F">Feminine</option><option value="N" disabled="disabled">Neuter</option></select>
This option also works when 'multiple' is set to 'checkbox':$options = ['Value 1' => 'Label 1','Value 2' => 'Label 2'];
echo $this->Form->select('field', $options, ['multiple' => 'checkbox','disabled' => ['Value 1']]);
Output:<input name="field" value="" type="hidden"><div class="checkbox"><label for="field-1"><input name="field[]" disabled="disabled" value="Value 1" type="checkbox">
Label 1</label>(continues on next page)

388

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)</div><div class="checkbox"><label for="field-2"><input name="field[]" value="Value 2" id="field-2" type="checkbox">
Label 2</label></div>Creating File Inputs
Cake\View\Helper\FormHelper::file(string $fieldName, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $options - An optional array including any of the Common Options For Specific Controls as well as any valid
HTML attributes.
Creates a file upload field in the form. The widget template used by default is:'file' => '<input type="file" name="{{name}}"{{attrs}}>'To add a file upload field to a form, you must first make sure that the form enctype is set to 'multipart/form-data'.
So start off with a create() method such as the following:echo $this->Form->create($document, ['enctype' => 'multipart/form-data']);// ORecho $this->Form->create($document, ['type' => 'file']);Next add a line that looks like either of the following two lines to your form’s view template file:echo $this->Form->control('submittedfile', ['type' => 'file'
]);
// OR
echo $this->Form->file('submittedfile');Note: Due to the limitations of HTML itself, it is not possible to put default values into input fields of type ‘file’. Eachtime the form is displayed, the value inside will be empty.
Upon submission, file fields provide an expanded data array to the script receiving the form data.
For the example above, the values in the submitted data array would be organized as follows, if CakePHP was installed
on a Windows server (the key 'tmp_name' will contain a different path in a Unix environment):$this->request->data['submittedfile']// would contain the following array:['name' => 'conference_schedule.pdf','type' => 'application/pdf',(continues on next page)

More About Views

389

CakePHP Book, Release 3.10

(continued from previous page)'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp','error' => 0, // On Windows this can be a string.
'size' => 41737,];
This array is generated by PHP itself, so for more detail on the way PHP handles data passed via file fields read the
PHP manual section on file uploads136 .
Note: When using $this->Form->file(), remember to set the form encoding-type, by setting the 'type' option
to 'file' in $this->Form->create().

Creating Date & Time Related Controls
The date and time related methods share a number of common traits and options and hence are grouped together into
this subsection.
Common Options for Date & Time Controls
These options are common for the date and time related controls:• 'empty' - If true an extra, empty, option HTML element is added inside select at the top of the list. If a
string, that string is displayed as the empty element. Defaults to true.
• 'default' | value - Use either of the two to set the default value to be shown by the field. A value in$this->request->getData() matching the field name will override this value. If no default is providedtime() will be used.
• 'year', 'month', 'day', 'hour', 'minute', 'second', 'meridian' - These options allow you tocontrol which control elements are generated or not. By setting any of these options to false you can disable thegeneration of that specific that select picker (if by default it would be rendered in the used method). In addition
each option allows you to pass HTML attributes to that specific select element.
Options for Date-Related Controls
These options are concerning the date-related methods - i.e. year(), month(), day(), dateTime() and date():• 'monthNames' - If false, 2 digit numbers will be used instead of text for displaying months in the select picker.
If set to an array (e.g. ['01' => 'Jan', '02' => 'Feb', ...]), the given array will be used.
• 'minYear' - The lowest value to use in the year select picker.
• 'maxYear' - The maximum value to use in the year select picker.
• 'orderYear' - The order of year values in the year select picker. Possible values are 'asc' and 'desc'.
Defaults to 'desc'.
• 'year', 'month', 'day' - These options allow you to control which control elements are generated or not.
By setting any of these options to false you can disable the generation of that specific that select picker (if bydefault it would be rendered in the used method). In addition each option allows you to pass HTML attributes tothat specific select element.
136 https://php.net/features.file-upload390

Chapter 11. Views

CakePHP Book, Release 3.10

Options for Time-Related Controls
These options are concerning the time-related methods - hour(), minute(), second(), dateTime() and time():• 'interval' - The interval in minutes between the values which are displayed in the option elements of theminutes select picker. Defaults to 1.
• 'round' - Set to up or down if you want to force rounding minutes in either direction when the value doesn’t fit
neatly into an interval. Defaults to null.
• timeFormat - Applies to dateTime() and time(). The time format to use in the select picker; either 12 or
24. When this option is set to anything else than 24 the format will be automatically set to 12 and the meridian
select picker will be displayed automatically to the right of the seconds select picker. Defaults to 24.
• format - Applies to hour(). The time format to use; either 12 or 24. In case it’s set to 12 the meridian selectpicker won’t be automatically displayed. It’s up to you to either add it or provide means to infer from the form
context the right period of the day. Defaults to 24.
• second - Applies to dateTime() and time(). Set to true to enable the seconds drop down. Defaults to false.
• 'hour', 'minute', 'second', 'meridian' - These options allow you to control which control elements
are generated or not. By setting any of these options to false you can disable the generation of that specific that
select picker (if by default it would be rendered in the used method). In addition each option allows you to passHTML attributes to that specific select element.
Creating DateTime Controls
Cake\View\Helper\FormHelper::dateTime($fieldName, $options = [])• $fieldName - A string that will be used as a prefix for the HTML name attribute of the select elements.
• $options - An optional array including any of the Common Options For Specific Controls, or specific datetime
options (see above), as well as any valid HTML attributes.
Creates a set of select elements for date and time.
To control the order of controls, and any elements/content between the controls you can override the dateWidget
template. By default the dateWidget template is:{{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}Calling the method without additional options will generate, by default, 5 select pickers, for: year (4 digits), month(full English name), day (num), hour (num), minutes (num).
For example<?= $this->form->dateTime('registered') ?>Output:<select name="registered[year]"><option value="" selected="selected"></option><option value="2022">2022</option>...
<option value="2012">2012</option></select><select name="registered[month]"><option value="" selected="selected"></option>(continues on next page)

More About Views

391

CakePHP Book, Release 3.10

(continued from previous page)<option value="01">January</option>...
<option value="12">December</option></select><select name="registered[day]"><option value="" selected="selected"></option><option value="01">1</option>...
<option value="31">31</option></select><select name="registered[hour]"><option value="" selected="selected"></option><option value="00">0</option>...
<option value="23">23</option></select><select name="registered[minute]"><option value="" selected="selected"></option><option value="00">00</option>...
<option value="59">59</option></select>
To create datetime controls with custom classes/attributes on a specific select box, you can provide them as arrays of
options for each component, within the $options argument.
For example:
echo $this->Form->dateTime('released', ['year' => ['class' => 'year-classname',],'month' => ['class' => 'month-class','data-type' => 'month',],]);
Which would create the following two select pickers:<select name="released[year]" class="year-class"><option value="" selected="selected"></option><option value="00">0</option><option value="01">1</option><!-- .. snipped for brevity .. --></select><select name="released[month]" class="month-class" data-type="month"><option value="" selected="selected"></option><option value="01">January</option><!-- .. snipped for brevity .. --></select>392

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Date Controls
Cake\View\Helper\FormHelper::date($fieldName, $options = [])• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select elements.
• $options - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Time-Related Controls, as well as any valid HTMLattributes.
Creates, by default, three select pickers populated with values for: year (4 digits), month (full English name) and day(numeric), respectively.
You can further control the generated select elements by providing additional options.
For example:// Assuming current year is 2017; this disables day picker, removes empty// option on year picker, limits lowest year, adds HTML attributes on year,// adds a string 'empty' option on month, changes month to numeric<?phpecho $this->Form->date('registered', ['minYear' => 2018,'monthNames' => false, // Months are displayed as numbers'empty' => ['year' => false, // The year select control has no option for empty value'month' => 'Choose month...', // The month select control does, though],'day' => false, // Do not show day select control'year' => ['class' => 'cool-years','title' => 'Registration Year']]);?>
Output:<select class= "cool-years" name="registered[year]" title="Registration Year"><option value="2022">2022</option><option value="2021">2021</option>...
<option value="2018">2018</option></select><select name="registered[month]"><option value="" selected="selected">Choose month...</option><option value="01">1</option>...
<option value="12">12</option></select>More About Views

393

CakePHP Book, Release 3.10

Creating Time Controls
Cake\View\Helper\FormHelper::time($fieldName, $options = [])• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select elements.
• $options - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Time-Related Controls, as well as any valid HTMLattributes.
Creates, by default, two select elements (hour and minute) populated with values for 24 hours and 60 minutes, respectively. Additionally, HTML attributes may be supplied in $options for each specific component. If$options['empty'] is false, the select picker will not include an empty default option.
For example, to create a time range with minutes selectable in 15 minute increments, and to apply classes to the selectboxes, you could do the following:echo $this->Form->time('released', ['interval' => 15,'hour' => ['class' => 'foo-class',],'minute' => ['class' => 'bar-class',],]);
Which would create the following two select pickers:<select name="released[hour]" class="foo-class"><option value="" selected="selected"></option><option value="00">0</option><option value="01">1</option><!-- .. snipped for brevity .. --><option value="22">22</option><option value="23">23</option></select><select name="released[minute]" class="bar-class"><option value="" selected="selected"></option><option value="00">00</option><option value="15">15</option><option value="30">30</option><option value="45">45</option></select>394

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Year Controls
Cake\View\Helper\FormHelper::year(string $fieldName, array $options = [])• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $options - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Date-Related Controls, as well as any valid HTMLattributes.
Creates a select element populated with the years from minYear to maxYear (when these options are provided) orelse with values starting from -5 years to +5 years counted from today. Additionally, HTML attributes may be suppliedin $options. If $options['empty'] is false, the select picker will not include an empty item in the list.
For example, to create a year range from 2000 to the current year you would do the following:echo $this->Form->year('purchased', ['minYear' => 2000,'maxYear' => date('Y')]);
If it was 2009, you would get the following:<select name="purchased[year]"><option value=""></option><option value="2009">2009</option><option value="2008">2008</option><option value="2007">2007</option><option value="2006">2006</option><option value="2005">2005</option><option value="2004">2004</option><option value="2003">2003</option><option value="2002">2002</option><option value="2001">2001</option><option value="2000">2000</option></select>Creating Month Controls
Cake\View\Helper\FormHelper::month(string $fieldName, array $attributes)• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $attributes - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Date-Related Controls, as well as any valid HTMLattributes.
Creates a select element populated with month names.
For example:
echo $this->Form->month('mob');
Will output:

More About Views

395CakePHP Book, Release 3.10

<select name="mob[month]"><option value=""></option><option value="01">January</option><option value="02">February</option><option value="03">March</option><option value="04">April</option><option value="05">May</option><option value="06">June</option><option value="07">July</option><option value="08">August</option><option value="09">September</option><option value="10">October</option><option value="11">November</option><option value="12">December</option></select>
You can pass in, your own array of months to be used by setting the 'monthNames' attribute, or have months displayed
as numbers by passing false.
E.g.
echo $this->Form->month('mob', ['monthNames' => false]);Note: The default months can be localized with CakePHP Internationalization & Localization features.

Creating Day Controls
Cake\View\Helper\FormHelper::day(string $fieldName, array $attributes)• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $attributes - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Date-Related Controls, as well as any valid HTMLattributes.
Creates a select element populated with the (numerical) days of the month.
To create an empty option element with a prompt text of your choosing (e.g. the first option is ‘Day’), you can supply
the text in the 'empty' parameter.
For example:
echo $this->Form->day('created', ['empty' => 'Day']);Will output:<select name="created[day]"><option value="" selected="selected">Day</option><option value="01">1</option><option value="02">2</option><option value="03">3</option>...
(continues on next page)

396

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)<option value="31">31</option></select>Creating Hour Controls
Cake\View\Helper\FormHelper::hour(string $fieldName, array $attributes)• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $attributes - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Time-Related Controls, as well as any valid HTMLattributes.
Creates a select element populated with the hours of the day.
You can create either 12 or 24 hour pickers using the 'format' option:echo $this->Form->hour('created', ['format' => 12]);
echo $this->Form->hour('created', ['format' => 24]);

Creating Minute Controls
Cake\View\Helper\FormHelper::minute(string $fieldName, array $attributes)• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $attributes - An optional array including any of the Common Options For Specific Controls, of the Common
Options for Date & Time Controls, any applicable Options for Time-Related Controls, as well as any valid HTMLattributes.
Creates a select element populated with values for the minutes of the hour. You can create a select picker that only
contains specific values by using the 'interval' option.
For example, if you wanted 10 minutes increments you would do the following:// In your view template fileecho $this->Form->minute('arrival', ['interval' => 10]);
This would output:<select name="arrival[minute]"><option value="" selected="selected"></option><option value="00">00</option><option value="10">10</option><option value="20">20</option><option value="30">30</option><option value="40">40</option>(continues on next page)

More About Views

397

CakePHP Book, Release 3.10

(continued from previous page)<option value="50">50</option></select>Creating Meridian Controls
Cake\View\Helper\FormHelper::meridian(string $fieldName, array $attributes)• $fieldName - A field name that will be used as a prefix for the HTML name attribute of the select element.
• $attributes - An optional array including any of the Common Options For Specific Controls as well as any
valid HTML attributes.
Creates a select element populated with ‘am’ and ‘pm’. This is useful when the hour format is set to 12 instead of24, as it allows to specify the period of the day to which the hour belongs.
Creating Labels
Cake\View\Helper\FormHelper::label(string $fieldName, string $text, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $text - An optional string providing the label caption text.
• $options - Optional. Array containing any of the Common Options For Specific Controls as well as any valid
HTML attributes.
Creates a label element. The argument $fieldName is used for generating the HTML for attribute of the element;
if $text is undefined, $fieldName will also be used to inflect the label’s text attribute.
E.g.
echo $this->Form->label('name');echo $this->Form->label('name', 'Your username');
Output:<label for="name">Name</label><label for="name">Your username</label>With the third parameter $options you can set the id or class:echo $this->Form->label('name', null, ['id' => 'user-label']);echo $this->Form->label('name', 'Your username', ['class' => 'highlight']);Output:<label for="name" id="user-label">Name</label><label for="name" class="highlight">Your username</label>

398

Chapter 11. Views

CakePHP Book, Release 3.10

Displaying and Checking Errors
FormHelper exposes a couple of methods that allow us to easily check for field errors and when necessary display
customized error messages.
Displaying Errors
Cake\View\Helper\FormHelper::error(string $fieldName, mixed $text, array $options)• $fieldName - A field name in the form 'Modelname.fieldname'.
• $text - Optional. A string or array providing the error message(s). If an array, then it should be a hash of key
names => messages. Defaults to null.
• $options - An optional array that can only contain a boolean with the key 'escape', which will define whether
to HTML escape the contents of the error message. Defaults to true.
Shows a validation error message, specified by $text, for the given field, in the event that a validation error has
occurred. If $text is not provided then the default validation error message for that field will be used.
Uses the following template widgets:'error' => '<div class="error-message">{{content}}</div>''errorList' => '<ul>{{content}}</ul>''errorItem' => '<li>{{text}}</li>'
The 'errorList' and 'errorItem' templates are used to format mutiple error messages per field.
Example:// If in TicketsTable you have a 'notEmpty' validation rule:
public function validationDefault(Validator $validator){$validator->requirePresence('ticket', 'create')->notEmpty('ticket');}// And inside Templates/Tickets/add.ctp you have:echo $this->Form->text('ticket');if ($this->Form->isFieldError('ticket')) {echo $this->Form->error('ticket', 'Completely custom error message!');}If you would click the Submit button of your form without providing a value for the Ticket field, your form would output:<input name="ticket" class="form-error" required="required" value="" type="text"><div class="error-message">Completely custom error message!</div>

Note: When using control(), errors are rendered by default, so you don’t need to use isFieldError() or callerror() manually.

More About Views

399CakePHP Book, Release 3.10

Tip: If you use a certain model field to generate multiple form fields via control(), and you want the same validation error message displayed for each one, you will probably be better off defining a custom error message inside therespective validator rules.

Checking for Errors
Cake\View\Helper\FormHelper::isFieldError(string $fieldName)• $fieldName - A field name in the form 'Modelname.fieldname'.
Returns true if the supplied $fieldName has an active validation error, otherwise returns false.
Example:if ($this->Form->isFieldError('gender')) {echo $this->Form->error('gender');}

Displaying validation messages in HTML5 validity messages
New in version 3.7.0.
If the autoSetCustomValidity FormHelper option is set to true, error messages for the field’s required and notBlank
validation rules will be used in lieu of the default browser HTML5 required messages. Enabling the option will add
the onvalid and oninvalid event attributes to your fields, for example:<input type="text" name="field" required onvalid="this.setCustomValidity('')" oninvalid=
˓→"this.setCustomValidity('Custom notBlank message')" />If you want to manually set those events with custom JavaScript, you can set the autoSetCustomValidity option tofalse and use the special customValidityMessage template variable instead. This template variable is added whena field is required:// example template['input' => '<input type="{{type}}" name="{{name}}" data-error-message="{˓→{customValidityMessage}}" {{attrs}}/>',]// would create an input like this
<input type="text" name="field" required data-error-message="Custom notBlank message" />You could then use JavaScript to set the onvalid and oninvalid events as you like.

400

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Buttons and Submit Elements
Creating Submit Elements
Cake\View\Helper\FormHelper::submit(string $caption, array $options)• $caption - An optional string providing the button’s text caption or a path to an image. Defaults to 'Submit'.
• $options - An optional array including any of the Common Options For Specific Controls, or of the specificsubmit options (see below) as well as any valid HTML attributes.
Creates an input element of submit type, with $caption as value. If the supplied $caption is a URL pointing
to an image (i.e. if the string contains ‘://’ or contains any of the extensions ‘.jpg, .jpe, .jpeg, .gif’), an image submit
button will be generated, using the specified image if it exists. If the first character is ‘/’ then the image path is relative
to webroot, else if the first character is not ‘/’ then the image path is relative to webroot/img.
By default it will use the following widget templates:'inputSubmit' => '<input type="{{type}}"{{attrs}}/>''submitContainer' => '<div class="submit">{{content}}</div>'
Options for Submit• 'type' - Set this option to 'reset' in order to generate reset buttons. It defaults to 'submit'.
• 'templateVars' - Set this array to provide additional template variables for the input element and its container.
• Any other provided attributes will be assigned to the input element.
The following:echo $this->Form->submit('Click me');Will output:<div class="submit"><input value="Click me" type="submit"></div>
You can pass a relative or absolute URL of an image to the caption parameter instead of the caption text:
echo $this->Form->submit('ok.png');
Will output:<div class="submit"><input type="image" src="/img/ok.png"></div>
Submit inputs are useful when you only need basic text or images. If you need more complex button content you should
use button().

More About Views

401CakePHP Book, Release 3.10

Creating Button Elements
Cake\View\Helper\FormHelper::button(string $title, array $options = [])• $title - Mandatory string providing the button’s text caption.
• $options - An optional array including any of the Common Options For Specific Controls, or of the specificbutton options (see below) as well as any valid HTML attributes.
Creates an HTML button with the specified title and a default type of 'button'.
Options for Button• $options['type'] - You can set this to one of the following three possible values:
1. 'submit' - Similarly to the $this->Form->submit() method it will create a submit button. However
this won’t generate a wrapping div as submit() does. This is the default type.
2. 'reset' - Creates a form reset button.
3. 'button' - Creates a standard push button.
• $options['escape'] - Boolean. If set to true it will HTML encode the value provided inside $title. Defaults to false.
For example:
echo $this->Form->button('A Button');echo $this->Form->button('Another Button', ['type' => 'button']);echo $this->Form->button('Reset the Form', ['type' => 'reset']);echo $this->Form->button('Submit Form', ['type' => 'submit']);Will output:<button type="submit">A Button</button><button type="button">Another Button</button><button type="reset">Reset the Form</button><button type="submit">Submit Form</button>
Example of use of the 'escape' option:// Will render escaped HTML.
echo $this->Form->button('<em>Submit Form</em>', ['type' => 'submit','escape' => true]);

Closing the Form
Cake\View\Helper\FormHelper::end($secureAttributes = [])• $secureAttributes - Optional. Allows you to provide secure attributes which will be passed as HTML attributes into the hidden input elements generated for the SecurityComponent.
The end() method closes and completes a form. Often, end() will only output a closing form tag, but using end()
is a good practice as it enables FormHelper to insert the hidden form elements that Cake\Controller\Component\
SecurityComponent requires:

402

Chapter 11. Views

CakePHP Book, Release 3.10<?= $this->Form->create(); ?><!-- Form elements go here --><?= $this->Form->end(); ?>If you need to add additional attributes to the generated hidden inputs you can use the $secureAttributes argument.
E.g.
echo $this->Form->end(['data-type' => 'hidden']);Will output:<div style="display:none;"><input type="hidden" name="_Token[fields]" data-type="hidden"
value="2981c38990f3f6ba935e6561dc77277966fabd6d%3AAddresses.id"><input type="hidden" name="_Token[unlocked]" data-type="hidden"
value="address%7Cfirst_name"></div>

Note: If you are using Cake\Controller\Component\SecurityComponent in your application you should always
end your forms with end().

Creating Standalone Buttons and POST Links
Creating POST Buttons
Cake\View\Helper\FormHelper::postButton(string $title, mixed $url, array $options = [])• $title - Mandatory string providing the button’s text caption. By default not HTML encoded.
• $url - The URL of the form provided as a string or as array.
• $options - An optional array including any of the Common Options For Specific Controls, or of the specificoptions (see below) as well as any valid HTML attributes.
Creates a <button> tag with a surrounding <form> element that submits via POST, by default. Also, by default, it
generates hidden input fields for the SecurityComponent.
Options for POST Button• 'data' - Array with key/value to pass in hidden input.
• 'method' - Request method to use. E.g. set to 'delete' to simulate a HTTP/1.1 DELETE request. Defaults
to 'post'.
• 'form' - Array with any option that FormHelper::create() can take.
• Also, the postButton() method will accept the options which are valid for the button() method.
For example:// In Templates/Tickets/index.ctp<?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' =>˓→'delete', 5]) ?>More About Views

403

CakePHP Book, Release 3.10

Will output HTML similar to:<form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5"><div style="display:none;"><input name="_method" value="POST" type="hidden"></div><button type="submit">Delete Record</button><div style="display:none;"><input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A"␣˓→type="hidden"><input name="_Token[unlocked]" value="" type="hidden"><input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C
˓→%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden"></div></form>Since this method generates a form element, do not use this method in an already opened form. Instead use Cake\
View\Helper\FormHelper::submit() or Cake\View\Helper\FormHelper::button() to create buttons inside
opened forms.
Creating POST Links
Cake\View\Helper\FormHelper::postLink(string $title, mixed $url = null, array $options = [])• $title - Mandatory string providing the text to be wrapped in <a> tags.
• $url - Optional. String or array which contains the URL of the form (Cake-relative or external URL startingwith http://).
• $options - An optional array including any of the Common Options For Specific Controls, or of the specificoptions (see below) as well as any valid HTML attributes.
Creates an HTML link, but accesses the URL using the method you specify (defaults to POST). Requires JavaScript to
be enabled in browser:// In your template, e.g. to delete an article<?= $this->Form->postLink('Delete',['action' => 'delete', $article->id],['confirm' => 'Are you sure?'])?>Options for POST Link
• 'data' - Array with key/value to pass in hidden input.
• 'method' - Request method to use. E.g. set to 'delete' to simulate a HTTP/1.1 DELETE request. Defaults
to 'post'.
• 'confirm' - The confirmation message to display on click. Defaults to null.
• 'block' - Set this option to true to append the form to view block 'postLink' or provide a custom blockname. Defaults to null.
• Also, the postLink method will accept the options which are valid for the link() method.
This method creates a <form> element. If you want to use this method inside of an existing form, you must use theblock option so that the new form is being set to a view block that can be rendered outside of the main form.

404

Chapter 11. Views

CakePHP Book, Release 3.10

If all you are looking for is a button to submit your form, then you should use Cake\View\Helper\
FormHelper::button() or Cake\View\Helper\FormHelper::submit() instead.
Note: Be careful to not put a postLink inside an open form. Instead use the block option to buffer the form into aview block

Customizing the Templates FormHelper Uses
Like many helpers in CakePHP, FormHelper uses string templates to format the HTML it creates. While the default
templates are intended to be a reasonable set of defaults, you may need to customize the templates to suit your application.
To change the templates when the helper is loaded you can set the 'templates' option when including the helper inyour controller:// In a View class$this->loadHelper('Form', ['templates' => 'app_form',]);
This would load the tags found in config/app_form.php. This file should contain an array of templates indexed byname:// in config/app_form.php
return ['inputContainer' => '<div class="form-control">{{content}}</div>',];
Any templates you define will replace the default ones included in the helper. Templates that are not replaced, willcontinue to use the default values.
You can also change the templates at runtime using the setTemplates() method:$myTemplates = ['inputContainer' => '<div class="form-control">{{content}}</div>',];$this->Form->setTemplates($myTemplates);// Prior to 3.4$this->Form->templates($myTemplates);

Warning: Template strings containing a percentage sign (%) need special attention; you should prefix this characterwith another percentage so it looks like %%. The reason is that internally templates are compiled to be used withsprintf(). Example: '<div style="width:{{size}}%%">{{content}}</div>'

More About Views

405

CakePHP Book, Release 3.10

List of Templates
The list of default templates, their default format and the variables they expect can be found in the FormHelper API
documentation137 .
Using Distinct Custom Control Containers
In addition to these templates, the control() method will attempt to use distinct templates for each control container.
For example, when creating a datetime control the datetimeContainer will be used if it is present. If that container
is missing the inputContainer template will be used.
For example:// Add custom radio wrapping HTML
$this->Form->setTemplates(['radioContainer' => '<div class="form-radio">{{content}}</div>']);// Create a radio set with our custom wrapping div.
echo $this->Form->control('email_notifications', ['options' => ['y', 'n'],'type' => 'radio']);

Using Distinct Custom Form Groups
Similar to controlling containers, the control() method will also attempt to use distinct templates for each form group.
A form group is a combo of label and control. For example, when creating a radio control the radioFormGroup will
be used if it is present. If that template is missing by default each set of label & input is rendered using the default
formGroup template.
For example:// Add custom radio form group$this->Form->setTemplates(['radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>']);

Adding Additional Template Variables to Templates
You can add additional template placeholders in custom templates, and populate those placeholders when generating
controls.
E.g.
// Add a template with the help placeholder.
$this->Form->setTemplates(['inputContainer' => '<div class="input {{type}}{{required}}">{{content}} <span class="help">{{help}}</span></div>'(continues on next page)
137 https://api.cakephp.org/3.x/class-Cake.View.Helper.FormHelper.html#%24_defaultConfig

406

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)]);// Generate an input and populate the help variableecho $this->Form->control('password', ['templateVars' => ['help' => 'At least 8 characters long.']]);
Output:<div class="input password"><label for="password">
Password</label><input name="password" id="password" type="password"><span class="help">At least 8 characters long.</span></div>New in version 3.1: The templateVars option was added in 3.1.0
Moving Checkboxes & Radios Outside of a Label
By default CakePHP nests checkboxes created via control() and radio buttons created by both control() andradio() within label elements. This helps make it easier to integrate popular CSS frameworks. If you need to placecheckbox/radio inputs outside of the label you can do so by modifying the templates:$this->Form->setTemplates(['nestingLabel' => '{{hidden}}{{input}}<label{{attrs}}>{{text}}</label>','formGroup' => '{{input}}{{label}}',]);This will make radio buttons and checkboxes render outside of their labels.
Generating Entire Forms
Creating Multiple Controls
Cake\View\Helper\FormHelper::controls(array $fields = [], $options = [])• $fields - An array of fields to generate. Allows setting custom types, labels and other options for each specified
field.
• $options - Optional. An array of options. Valid keys are:
1. 'fieldset' - Set this to false to disable the fieldset. If empty, the fieldset will be enabled. Can also be
an array of parameters to be applied as HTML attributes to the fieldset tag.
2. legend - String used to customize the legend text. Set this to false to disable the legend for the generated
input set.
Generates a set of controls for the given context wrapped in a fieldset. You can specify the generated fields by
including them:More About Views

407

CakePHP Book, Release 3.10

echo $this->Form->controls(['name','email']);You can customize the legend text using an option:echo $this->Form->controls($fields, ['legend' => 'Update news post']);You can customize the generated controls by defining additional options in the $fields parameter:
echo $this->Form->controls(['name' => ['label' => 'custom label']]);
When customizing, $fields, you can use the $options parameter to control the generated legend/fieldset.
For example:
echo $this->Form->controls(['name' => ['label' => 'custom label']],['legend' => 'Update your post']);
If you disable the fieldset, the legend will not print.
Creating Controls for a Whole Entity
Cake\View\Helper\FormHelper::allControls(array $fields, $options = [])• $fields - Optional. An array of customizations for the fields that will be generated. Allows setting custom
types, labels and other options.
• $options - Optional. An array of options. Valid keys are:
1. 'fieldset' - Set this to false to disable the fieldset. If empty, the fieldset will be enabled. Can also be
an array of parameters to be applied as HTMl attributes to the fieldset tag.
2. legend - String used to customize the legend text. Set this to false to disable the legend for the generated
control set.
This method is closely related to controls(), however the $fields argument is defaulted to all fields in the current
top-level entity. To exclude specific fields from the generated controls, set them to false in the $fields parameter:
echo $this->Form->allControls(['password' => false]);// Or prior to 3.4.0:
echo $this->Form->allInputs(['password' => false]);408

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Inputs for Associated Data
Creating forms for associated data is straightforward and is closely related to the paths in your entity’s data. Assuming
the following table relations:• Authors HasOne Profiles• Authors HasMany Articles• Articles HasMany Comments• Articles BelongsTo Authors• Articles BelongsToMany Tags
If we were editing an article with its associations loaded we could create the following controls:$this->Form->create($article);// Article controls.
echo $this->Form->control('title');// Author controls (belongsTo)
echo $this->Form->control('author.id');echo $this->Form->control('author.first_name');echo $this->Form->control('author.last_name');// Author profile (belongsTo + hasOne)
echo $this->Form->control('author.profile.id');echo $this->Form->control('author.profile.username');// Tags controls (belongsToMany)// as separate inputs
echo $this->Form->control('tags.0.id');echo $this->Form->control('tags.0.name');echo $this->Form->control('tags.1.id');echo $this->Form->control('tags.1.name');// Inputs for the joint table (articles_tags)
echo $this->Form->control('tags.0._joinData.starred');echo $this->Form->control('tags.1._joinData.starred');// Comments controls (hasMany)echo $this->Form->control('comments.0.id');echo $this->Form->control('comments.0.comment');
echo $this->Form->control('comments.1.id');echo $this->Form->control('comments.1.comment');// Multiple file control (hasMany) (requires $this->Form->create($article, ['type' => 'file˓→']))
echo $this->Form->control('files[].filename', ['type' => 'file', 'multiple' => 'true']);
The above controls could then be marshalled into a completed entity graph using the following code in your controller:$article = $this->Articles->patchEntity($article, $this->request->getData(), ['associated' => [(continues on next page)

More About Views

409

CakePHP Book, Release 3.10

(continued from previous page)'Authors','Authors.Profiles','Tags','Comments']]);
The above example shows an expanded example for belongs to many associations, with separate inputs for each entityand join data record. You can also create a multiple select input for belongs to many associations:// Multiple select element for belongsToMany// Does not support _joinData
echo $this->Form->control('tags._ids', ['type' => 'select','multiple' => true,'options' => $tagList,]);

Adding Custom Widgets
CakePHP makes it easy to add custom control widgets in your application, and use them like any other control type.
All of the core control types are implemented as widgets, which means you can override any core widget with yourown implementation as well.
Building a Widget Class
Widget classes have a very simple required interface.
They must implement the Cake\View\Widget\
WidgetInterface. This interface requires the render(array $data) and secureFields(array $data) methods to be implemented. The render() method expects an array of data to build the widget and is expected to returna string of HTML for the widget. The secureFields() method expects an array of data as well and is expected toreturn an array containing the list of fields to secure for this widget. If CakePHP is constructing your widget you can
expect to get a Cake\View\StringTemplate instance as the first argument, followed by any dependencies you define.
If we wanted to build an Autocomplete widget you could do the following:namespace App\View\Widget;
use Cake\View\Form\ContextInterface;
use Cake\View\Widget\WidgetInterface;class AutocompleteWidget implements WidgetInterface{
protected $_templates;
public function __construct($templates){$this->_templates = $templates;}
public function render(array $data, ContextInterface $context){(continues on next page)

410

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)$data += ['name' => '',];return $this->_templates->format('autocomplete', ['name' => $data['name'],'attrs' => $this->_templates->formatAttributes($data, ['name'])]);}public function secureFields(array $data){
return [$data['name']];}}Obviously, this is a very simple example, but it demonstrates how a custom widget could be built. This widget would
render the “autocomplete” string template, such as:$this->Form->setTemplates(['autocomplete' => '<input type="autocomplete" name="{{name}}" {{attrs}} />']);For more information on string templates, see Customizing the Templates FormHelper Uses.
Using Widgets
You can load custom widgets when loading FormHelper or by using the addWidget() method. When loading
FormHelper, widgets are defined as a setting:// In View class$this->loadHelper('Form', ['widgets' => ['autocomplete' => ['Autocomplete']]]);
If your widget requires other widgets, you can have FormHelper populate those dependencies by declaring them:$this->loadHelper('Form', ['widgets' => ['autocomplete' => ['App\View\Widget\AutocompleteWidget','text','label']]]);In the above example, the autocomplete widget would depend on the text and label widgets. If your widget needs
access to the View, you should use the _view ‘widget’. When the autocomplete widget is created, it will be passed
the widget objects that are related to the text and label names. To add widgets using the addWidget() method
would look like:

More About Views

411

CakePHP Book, Release 3.10// Using a classname.
$this->Form->addWidget('autocomplete',['Autocomplete', 'text', 'label']);// Using an instance - requires you to resolve dependencies.
// Prior to 3.6.0 use widgetRegistry() to fetch widgets.
$autocomplete = new AutocompleteWidget($this->Form->getTemplater(),$this->Form->getWidgetLocator()->get('text'),$this->Form->getWidgetLocator()->get('label'),);$this->Form->addWidget('autocomplete', $autocomplete);
Once added/replaced, widgets can be used as the control ‘type’:echo $this->Form->control('search', ['type' => 'autocomplete']);This will create the custom widget with a label and wrapping div just like controls() always does. Alternatively,
you can create just the control widget using the magic method:echo $this->Form->autocomplete('search', $options);

Working with SecurityComponent
Cake\Controller\Component\SecurityComponent offers several features that make your forms safer and moresecure. By simply including the SecurityComponent in your controller, you’ll automatically benefit from form
tampering-prevention features.
As mentioned previously when using SecurityComponent, you should always close your forms using end(). This will
ensure that the special _Token inputs are generated.
Cake\View\Helper\FormHelper::unlockField($name)• $name - Optional. The dot-separated name for the field.
Unlocks a field making it exempt from the SecurityComponent field hashing. This also allows the fields to be manipulated by JavaScript. The $name parameter should be the entity property name for the field:$this->Form->unlockField('id');Cake\View\Helper\FormHelper::secure(array $fields = [], array $secureAttributes = [])• $fields - Optional. An array containing the list of fields to use when generating the hash. If not provided, then$this->fields will be used.
• $secureAttributes - Optional. An array of HTML attributes to be passed into the generated hidden input
elements.
Generates a hidden input field with a security hash based on the fields used in the form or an empty string whensecured forms are not in use. If $secureAttributes is set, these HTML attributes will be merged into the hidden
input tags generated for the SecurityComponent. This is especially useful to set HTML5 attributes like 'form'.

412

Chapter 11. Views

CakePHP Book, Release 3.10

Html
class Cake\View\Helper\HtmlHelper(View $view, array $config = [])The role of the HtmlHelper in CakePHP is to make HTML-related options easier, faster, and more resilient to change.
Using this helper will enable your application to be more light on its feet, and more flexible on where it is placed inrelation to the root of a domain.
Many HtmlHelper methods include a $attributes parameter, that allow you to tack on any extra attributes on yourtags. Here are a few examples of how to use the $attributes parameter:
Desired attributes: <tag class="someClass" />Array parameter: ['class' => 'someClass']
Desired attributes: <tag name="foo" value="bar" />Array parameter: ['name' => 'foo', 'value' => 'bar']Inserting Well-Formatted Elements
The most important task the HtmlHelper accomplishes is creating well formed markup. This section will cover someof the methods of the HtmlHelper and how to use them.
Creating Charset Tags
Cake\View\Helper\HtmlHelper::charset($charset=null)
Used to create a meta tag specifying the document’s character. The default value is UTF-8. An example use:echo $this->Html->charset();Will output:<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />Alternatively,
echo $this->Html->charset('ISO-8859-1');
Will output:<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />Linking to CSS Files
Cake\View\Helper\HtmlHelper::css(mixed $path, array $options = [])Creates a link(s) to a CSS style-sheet. If the block option is set to true, the link tags are added to the css block which
you can print inside the head tag of the document.
You can use the block option to control which block the link element will be appended to. By default it will append
to the css block.
If key ‘rel’ in $options array is set to ‘import’ the stylesheet will be imported.

More About Views

413

CakePHP Book, Release 3.10

This method of CSS inclusion assumes that the CSS file specified resides inside the webroot/css directory if path
doesn’t start with a ‘/’.
echo $this->Html->css('forms');
Will output:<link rel="stylesheet" href="/css/forms.css" />The first parameter can be an array to include multiple files.
echo $this->Html->css(['forms', 'tables', 'menu']);Will output:<link rel="stylesheet" href="/css/forms.css" /><link rel="stylesheet" href="/css/tables.css" /><link rel="stylesheet" href="/css/menu.css" />You can include CSS files from any loaded plugin using plugin syntax.
ins/DebugKit/webroot/css/toolbar.css you could use the following:

To include plug-echo $this->Html->css('DebugKit.toolbar.css');If you want to include a CSS file which shares a name with a loaded plugin you can do the following. For example if
you had a Blog plugin, and also wanted to include webroot/css/Blog.common.css, you would:
echo $this->Html->css('Blog.common.css', ['plugin' => false]);Creating CSS ProgramaticallyCake\View\Helper\HtmlHelper::style(array $data, boolean $oneline = true)
Builds CSS style definitions based on the keys and values of the array passed to the method. Especially handy if yourCSS file is dynamic.
echo $this->Html->style(['background' => '#633','border-bottom' => '1px solid #000','padding' => '10px']);
Will output:
background:#633; border-bottom:1px solid #000; padding:10px;

414

Chapter 11. Views

CakePHP Book, Release 3.10

Creating meta Tags
Cake\View\Helper\HtmlHelper::meta(string|array $type, string $url = null, array $options = [])This method is handy for linking to external resources like RSS/Atom feeds and favicons. Like css(), you can specify
whether or not you’d like this tag to appear inline or appended to the meta block by setting the ‘block’ key in the$attributes parameter to true, ie - ['block' => true].
If you set the “type” attribute using the $attributes parameter, CakePHP contains a few shortcuts:
typetranslated value

html
rss
atom
icon

text/html
application/rss+xml
application/atom+xml
image/x-icon<?= $this->Html->meta('favicon.ico','/favicon.ico',['type' => 'icon']);?>// Output (line breaks added)// Note: The helper code makes two meta tags to ensure the// icon is downloaded by both newer and older browsers// which require different rel attribute values.
<linkhref="/subdir/favicon.ico"
type="image/x-icon"
rel="icon"/><linkhref="/subdir/favicon.ico"
type="image/x-icon"
rel="shortcut icon"/><?= $this->Html->meta('Comments','/comments/index.rss',['type' => 'rss']);?>// Output (line breaks added)<link
href="http://example.com/comments/index.rss"
title="Comments"
type="application/rss+xml"
rel="alternate"/>This method can also be used to add the meta keywords and descriptions. Example:

More About Views

415

CakePHP Book, Release 3.10<?= $this->Html->meta('keywords','enter any meta keyword here');?>// Output<meta name="keywords" content="enter any meta keyword here" /><?= $this->Html->meta('description','enter any meta description here');?>// Output<meta name="description" content="enter any meta description here" />In addition to making predefined meta tags, you can create link elements:<?= $this->Html->meta(['link' => 'http://example.com/manifest','rel' => 'manifest']);?>// Output<link href="http://example.com/manifest" rel="manifest"/>Any attributes provided to meta() when called this way will be added to the generated link tag.
Creating DOCTYPE
Cake\View\Helper\HtmlHelper::docType(string $type = 'html5')
Returns a (X)HTML DOCTYPE (document type declaration). Supply the document type according to the following
table:
typetranslated value

html4-strict
html4-transhtml4-frame
html5 (default)
xhtml-strict
xhtml-transxhtml-frame
xhtml11

HTML 4.01 Strict
HTML 4.01 Transitional
HTML 4.01 Frameset
HTML5
XHTML 1.0 Strict
XHTML 1.0 Transitional
XHTML 1.0 Frameset
XHTML 1.1

echo $this->Html->docType();// Outputs: <!DOCTYPE html>
echo $this->Html->docType('html4-trans');// Outputs:(continues on next page)

416

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)// <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"//"http://www.w3.org/TR/html4/loose.dtd">

Linking to Images
Cake\View\Helper\HtmlHelper::image(string $path, array $options = [])Creates a formatted image tag. The path supplied should be relative to webroot/img/.
echo $this->Html->image('cake_logo.png', ['alt' => 'CakePHP']);
Will output:<img src="/img/cake_logo.png" alt="CakePHP" />To create an image link specify the link destination using the url option in $attributes.
echo $this->Html->image("recipes/6.jpg", ["alt" => "Brownies",'url' => ['controller' => 'Recipes', 'action' => 'view', 6]]);Will output:<a href="/recipes/view/6"><img src="/img/recipes/6.jpg" alt="Brownies" /></a>
If you are creating images in emails, or want absolute paths to images you can use the fullBase option:echo $this->Html->image("logo.png", ['fullBase' => true]);Will output:<img src="http://example.com/img/logo.jpg" alt="" />You can include image files from any loaded plugin using plugin syntax.
ins/DebugKit/webroot/img/icon.png You could use the following:

To include plug-echo $this->Html->image('DebugKit.icon.png');
If you want to include an image file which shares a name with a loaded plugin you can do the following. For example
if you had a Blog plugin, and also wanted to include webroot/img/Blog.icon.png, you would:
echo $this->Html->image('Blog.icon.png', ['plugin' => false]);If you would like the prefix of the URL to not be /img, you can override this setting by specifying the prefix in the$options arrayecho $this->Html->image("logo.png", ['pathPrefix' => '']);
Will output:

More About Views

417

CakePHP Book, Release 3.10

<img src="logo.jpg" alt="" />Creating Links
Cake\View\Helper\HtmlHelper::link(string $title, mixed $url = null, array $options = [])General purpose method for creating HTML links. Use $options to specify attributes for the element and whether or
not the $title should be escaped.
echo $this->Html->link('Enter','/pages/home',['class' => 'button', 'target' => '_blank']);
Will output:<a href="/pages/home" class="button" target="_blank">Enter</a>
Use '_full'=>true option for absolute URLs:
echo $this->Html->link('Dashboard',['controller' => 'Dashboards', 'action' => 'index', '_full' => true]);
Will output:<a href="http://www.yourdomain.com/dashboards/index">Dashboard</a>Specify confirm key in options to display a JavaScript confirm() dialog:
echo $this->Html->link('Delete',['controller' => 'Recipes', 'action' => 'delete', 6],['confirm' => 'Are you sure you wish to delete this recipe?']);Will output:<a href="/recipes/delete/6"
onclick="return confirm('Are you sure you wish to delete this recipe?');">
Delete</a>Query strings can also be created with link().
echo $this->Html->link('View image', ['controller' => 'Images','action' => 'view',
1,(continues on next page)

418

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)'?' => ['height' => 400, 'width' => 500]]);
Will output:<a href="/images/view/1?height=400&width=500">View image</a>HTML special characters in $title will be converted to HTML entities. To disable this conversion, set the escapeoption to false in the $options array.
echo $this->Html->link($this->Html->image("recipes/6.jpg", ["alt" => "Brownies"]),"recipes/view/6",['escape' => false]);
Will output:<a href="/recipes/view/6"><img src="/img/recipes/6.jpg" alt="Brownies" /></a>Setting escape to false will also disable escaping of attributes of the link. You can use the option escapeTitle todisable just escaping of title and not the attributes.
echo $this->Html->link($this->Html->image('recipes/6.jpg', ['alt' => 'Brownies']),'recipes/view/6',['escapeTitle' => false, 'title' => 'hi "howdy"']);
Will output:<a href="/recipes/view/6" title="hi &quot;howdy&quot;"><img src="/img/recipes/6.jpg" alt="Brownies" /></a>Also check Cake\View\Helper\UrlHelper::build() method for more examples of different types of URLs.
Linking to Videos and Audio Files
Cake\View\Helper\HtmlHelper::media(string|array $path, array $options)
Options:• type Type of media element to generate, valid values are “audio” or “video”. If type is not provided media typeis guessed based on file’s mime type.
• text Text to include inside the video tag• pathPrefix Path prefix to use for relative URLs, defaults to ‘files/’• fullBase If provided the src attribute will get a full address including domain nameReturns a formatted audio/video tag:More About Views

419

CakePHP Book, Release 3.10<?= $this->Html->media('audio.mp3') ?>// Output<audio src="/files/audio.mp3"></audio><?= $this->Html->media('video.mp4', ['fullBase' => true,'text' => 'Fallback text']) ?>// Output<video src="http://www.somehost.com/files/video.mp4">Fallback text</video><?= $this->Html->media(['video.mp4', ['src' => 'video.ogg', 'type' => "video/ogg; codecs='theora, vorbis'
˓→"]],['autoplay']) ?>// Output<video autoplay="autoplay"><source src="/files/video.mp4" type="video/mp4"/><source src="/files/video.ogg" type="video/ogg;
codecs='theora, vorbis'"/></video>

Linking to Javascript Files
Cake\View\Helper\HtmlHelper::script(mixed $url, mixed $options)
Include a script file(s), contained either locally or as a remote URL.
By default, script tags are added to the document inline. If you override this by setting $options['block'] to true,
the script tags will instead be added to the script block which you can print elsewhere in the document. If you wish
to override which block name is used, you can do so by setting $options['block'].
$options['once'] controls whether or not you want to include this script once per request or more than once. Thisdefaults to true.
You can use $options to set additional properties to the generated script tag. If an array of script tags is used, theattributes will be applied to all of the generated script tags.
This method of JavaScript file inclusion assumes that the JavaScript file specified resides inside the webroot/js directory:echo $this->Html->script('scripts');
Will output:<script src="/js/scripts.js"></script>
You can link to files with absolute paths as well to link files that are not in webroot/js:
echo $this->Html->script('/otherdir/script_file');420

Chapter 11. Views

CakePHP Book, Release 3.10

You can also link to a remote URL:
echo $this->Html->script('https://code.jquery.com/jquery.min.js');
Will output:<script src="https://code.jquery.com/jquery.min.js"></script>
The first parameter can be an array to include multiple files.
echo $this->Html->script(['jquery', 'wysiwyg', 'scripts']);Will output:<script src="/js/jquery.js"></script><script src="/js/wysiwyg.js"></script><script src="/js/scripts.js"></script>
You can append the script tag to a specific block using the block option:echo $this->Html->script('wysiwyg', ['block' => 'scriptBottom']);In your layout you can output all the script tags added to ‘scriptBottom’:echo $this->fetch('scriptBottom');
You can include script files from any loaded plugin using plugin syntax.
ins/DebugKit/webroot/js/toolbar.js You could use the following:

To include plug-echo $this->Html->script('DebugKit.toolbar.js');
If you want to include a script file which shares a name with a loaded plugin you can do the following. For example if
you had a Blog plugin, and also wanted to include webroot/js/Blog.plugins.js, you would:
echo $this->Html->script('Blog.plugins.js', ['plugin' => false]);Creating Inline Javascript Blocks
Cake\View\Helper\HtmlHelper::scriptBlock($code, $options = [])To generate Javascript blocks from PHP view code, you can use one of the script block methods. Scripts can either be
output in place, or buffered into a block:// Define a script block all at once, with the defer attribute.
$this->Html->scriptBlock('alert("hi")', ['defer' => true]);// Buffer a script block to be output later.
$this->Html->scriptBlock('alert("hi")', ['block' => true]);Cake\View\Helper\HtmlHelper::scriptStart($options = [])Cake\View\Helper\HtmlHelper::scriptEnd()You can use the scriptStart() method to create a capturing block that will output into a <script> tag. Captured
script snippets can be output inline, or buffered into a block:More About Views

421CakePHP Book, Release 3.10// Append into the 'script' block.
$this->Html->scriptStart(['block' => true]);echo "alert('I am in the JavaScript');";$this->Html->scriptEnd();Once you have buffered javascript, you can output it as you would any other View Block:// In your layout
echo $this->fetch('script');

Creating Nested Lists
Cake\View\Helper\HtmlHelper::nestedList(array $list, array $options = [], array $itemOptions = [])Build a nested list (UL/OL) out of an associative array:$list = ['Languages' => ['English' => ['American','Canadian','British',],'Spanish','German',]];echo $this->Html->nestedList($list);
Output:// Output (minus the whitespace)<ul><li>Languages<ul><li>English<ul><li>American</li><li>Canadian</li><li>British</li>
</ul>
</li>
<li>Spanish</li><li>German</li>
</ul>
</li>
</ul>

422

Chapter 11. Views

CakePHP Book, Release 3.10

Creating Table Headings
Cake\View\Helper\HtmlHelper::tableHeaders(array $names, array $trOptions = null, array $thOptions =null)
Creates a row of table header cells to be placed inside of <table> tags.
echo $this->Html->tableHeaders(['Date', 'Title', 'Active']);Output:<tr><th>Date</th><th>Title</th><th>Active</th></tr>
echo $this->Html->tableHeaders(['Date', 'Title','Active'],['class' => 'status'],['class' => 'product_table']);
Output:<tr class="status"><th class="product_table">Date</th><th class="product_table">Title</th><th class="product_table">Active</th></tr>
You can set attributes per column, these are used instead of the defaults provided in the $thOptions:echo $this->Html->tableHeaders(['id',['Name' => ['class' => 'highlight']],['Date' => ['class' => 'sortable']]]);Output:<tr><th>id</th><th class="highlight">Name</th><th class="sortable">Date</th></tr>More About Views

423CakePHP Book, Release 3.10

Creating Table Cells
Cake\View\Helper\HtmlHelper::tableCells(array $data, array $oddTrOptions = null, array $evenTrOptions= null, $useCount = false, $continueOddEven = true)
Creates table cells, in rows, assigning <tr> attributes differently for odd- and even-numbered rows. Wrap a single table
cell within an [] for specific <td>-attributes.
echo $this->Html->tableCells([['Jul 7th, 2007', 'Best Brownies', 'Yes'],['Jun 21st, 2007', 'Smart Cookies', 'Yes'],['Aug 1st, 2006', 'Anti-Java Cake', 'No'],]);
Output:<tr><td>Jul 7th, 2007</td><td>Best Brownies</td><td>Yes</td></tr><tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr><tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td>No</td></tr>
echo $this->Html->tableCells([['Jul 7th, 2007', ['Best Brownies', ['class' => 'highlight']] , 'Yes'],['Jun 21st, 2007', 'Smart Cookies', 'Yes'],['Aug 1st, 2006', 'Anti-Java Cake', ['No', ['id' => 'special']]],]);
Output:<tr><td>
Jul 7th, 2007</td>
<td class="highlight">
Best Brownies
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
Jun 21st, 2007
</td>
<td>
Smart Cookies
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
Aug 1st, 2006
(continues on next page)424

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)

</td>
<td>
Anti-Java Cake</td>
<td id="special">
No
</td>
</tr>
echo $this->Html->tableCells([['Red', 'Apple'],['Orange', 'Orange'],['Yellow', 'Banana'],],['class' => 'darker']);
Output:<tr class="darker"><td>Red</td><td>Apple</td></tr><tr><td>Orange</td><td>Orange</td></tr><tr class="darker"><td>Yellow</td><td>Banana</td></tr>

Changing the Tags Output by HtmlHelper
Cake\View\Helper\HtmlHelper::setTemplates(array $templates)
Load an array of templates to add/replace templates:// Load specific templates.
$this->Html->setTemplates(['javascriptlink' => '<script src="{{url}}" type="text/javascript"{{attrs}}></script>']);
You can load a configuration file containing templates using the templater directly:// Load a configuration file with templates.
$this->Html->templater()->load('my_tags');
When loading files of templates, your file should look like:<?php
return ['javascriptlink' => '<script src="{{url}}" type="text/javascript"{{attrs}}></script>'];

Warning: Template strings containing a percentage sign (%) need special attention, you should prefix this characterwith another percentage so it looks like %%. The reason is that internally templates are compiled to be used withsprintf(). Example: <div style="width:{{size}}%%">{{content}}</div>

More About Views

425CakePHP Book, Release 3.10

Creating Breadcrumb Trails with HtmlHelper
Cake\View\Helper\HtmlHelper::addCrumb(string $name, string $link = null, mixed $options = null)Cake\View\Helper\HtmlHelper::getCrumbs(string $separator = '&raquo;', string $startText = false)
Cake\View\Helper\HtmlHelper::getCrumbList(array $options = [], $startText = false)
Many applications have breadcrumb trails to ease end user navigations. You can create a breadcrumb trail in your app
with some help from HtmlHelper. To make bread crumbs, first the following in your layout template:echo $this->Html->getCrumbs(' > ', 'Home');
The $startText option can also accept an array. This gives more control over the generated first link:echo $this->Html->getCrumbs(' > ', ['text' => $this->Html->image('home.png'),'url' => ['controller' => 'Pages', 'action' => 'display', 'home'],'escape' => false]);
Any keys that are not text or url will be passed to link() as the $options parameter.
Now, in your view you’ll want to add the following to start the breadcrumb trails on each of the pages:$this->Html->addCrumb('Users', '/users');$this->Html->addCrumb('Add User', ['controller' => 'Users', 'action' => 'add']);This will add the output of “Home > Users > Add User” in your layout where getCrumbs was added.
You can also fetch the crumbs formatted inside an HTML list:
echo $this->Html->getCrumbList();As options you can use regular HTML parameter that fits in the <ul> (Unordered List) such as class and for the
specific options, you have: separator (will be between the <li> elements), firstClass and lastClass like:echo $this->Html->getCrumbList(['firstClass' => false,'lastClass' => 'active','class' => 'breadcrumb'],'Home');
This method uses Cake\View\Helper\HtmlHelper::tag() to generate list and its elements. Works similar to
getCrumbs(), so it uses options which every crumb was added with. You can use the $startText parameter toprovide the first breadcrumb link/text. This is useful when you always want to include a root link. This option works
the same as the $startText option for getCrumbs().

426

Chapter 11. Views

CakePHP Book, Release 3.10

Numberclass Cake\View\Helper\NumberHelper(View $view, array $config = [])The NumberHelper contains convenient methods that enable display numbers in common formats in your views. Thesemethods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also togive you more flexibility with formatting numbers.
All of these functions return the formatted number; they do not automatically echo the output into the view.
Formatting Currency Values
Cake\View\Helper\NumberHelper::currency(mixed $value, string $currency = null, array $options = [])This method is used to display a number in common currency formats (EUR, GBP, USD). Usage in a view looks like:// Called as NumberHelper
echo $this->Number->currency($value, $currency);// Called as Number
echo Number::currency($value, $currency);
The first parameter, $value, should be a floating point number that represents the amount of money you are expressing.
The second parameter is a string used to choose a predefined currency formatting scheme:$currency

1234.56, formatted by currency type

EUR
GBP
USD

€1.234,56£1,234.56$1,234.56

The third parameter is an array of options for further defining the output. The following options are available:
OptionDescription

beforeafter
zero
placesprecision
localefractionSymbol
fractionPosition
pattern
useIntlCode

Text to display before the rendered number.
Text to display after the rendered number.
The text to use for zero values; can be a string or a number. ie. 0, ‘Free!’.
Number of decimal places to use, ie. 2
Maximal number of decimal places to use, ie. 2
The locale name to use for formatting number, ie. “fr_FR”.
String to use for fraction numbers, ie. ‘ cents’.
Either ‘before’ or ‘after’ to place the fraction symbol.
An ICU number pattern to use for formatting the number ie. #,###.00
Set to true to replace the currency symbol with the international currency code.

If $currency value is null, the default currency will be retrieved from Cake\I18n\Number::defaultCurrency().
To format currencies in an accounting format you should set the currency format:
Number::setDefaultCurrencyFormat(Number::FORMAT_CURRENCY_ACCOUNTING);
New in version 3.9.0: Formatting currency as accounting values was added.

More About Views

427CakePHP Book, Release 3.10

Setting the Default Currency
Cake\View\Helper\NumberHelper::defaultCurrency($currency)
Setter/getter for the default currency. This removes the need to always pass the currency to Cake\I18n\
Number::currency() and change all currency outputs by setting other default. If $currency is set to false, itwill clear the currently stored value. By default, it will retrieve the intl.default_locale if set and ‘en_US’ if not.
Formatting Floating Point Numbers
Cake\View\Helper\NumberHelper::precision(float $value, int $precision = 3, array $options = [])This method displays a number with the specified amount of precision (decimal places). It will round in order tomaintain the level of precision defined.
// Called as NumberHelper
echo $this->Number->precision(456.91873645, 2);// Outputs
456.92// Called as Number
echo Number::precision(456.91873645, 2);

Formatting Percentages
Cake\View\Helper\NumberHelper::toPercentage(mixed $value, int $precision = 2, array $options = [])OptionDescription

multiply

Boolean to indicate whether the value has to be multiplied by 100. Useful for decimal percentages.

Like Cake\I18n\Number::precision(), this method formats a number according to the supplied precision (where
numbers are rounded to meet the given precision). This method also expresses the number as a percentage and appends
the output with a percent sign.
// Called as NumberHelper. Output: 45.69%
echo $this->Number->toPercentage(45.691873645);// Called as Number. Output: 45.69%
echo Number::toPercentage(45.691873645);// Called with multiply. Output: 45.7%
echo Number::toPercentage(0.45691, 1, ['multiply' => true
]);

428

Chapter 11. Views

CakePHP Book, Release 3.10

Interacting with Human Readable Values
Cake\View\Helper\NumberHelper::toReadableSize(string $size)
This method formats data sizes in human readable forms. It provides a shortcut way to convert bytes to KB, MB, GB,
and TB. The size is displayed with a two-digit precision level, according to the size of data supplied (i.e. higher sizes
are expressed in larger terms):// Called as NumberHelper
echo $this->Number->toReadableSize(0); // 0 Byteecho $this->Number->toReadableSize(1024); // 1 KB
echo $this->Number->toReadableSize(1321205.76); // 1.26 MB
echo $this->Number->toReadableSize(5368709120); // 5 GB// Called as Number
echo Number::toReadableSize(0); // 0 Byteecho Number::toReadableSize(1024); // 1 KB
echo Number::toReadableSize(1321205.76); // 1.26 MB
echo Number::toReadableSize(5368709120); // 5 GB

Formatting Numbers
Cake\View\Helper\NumberHelper::format(mixed $value, array $options = [])This method gives you much more control over the formatting of numbers for use in your views (and is used as themain method by most of the other NumberHelper methods). Using this method might looks like:// Called as NumberHelper$this->Number->format($value, $options);// Called as Number
Number::format($value, $options);
The $value parameter is the number that you are planning on formatting for output. With no $options supplied, thenumber 1236.334 would output as 1,236. Note that the default precision is zero decimal places.
The $options parameter is where the real magic for this method resides.
• If you pass an integer then this becomes the amount of precision or places for the function.
• If you pass an associated array, you can use the following keys:
OptionDescription

placesprecision
pattern
localebeforeafter

Number of decimal places to use, ie. 2
Maximum number of decimal places to use, ie. 2
An ICU number pattern to use for formatting the number ie. #,###.00
The locale name to use for formatting number, ie. “fr_FR”.
Text to display before the rendered number.
Text to display after the rendered number.

Example:More About Views

429CakePHP Book, Release 3.10// Called as NumberHelper
echo $this->Number->format('123456.7890', ['places' => 2,'before' => '¥ ','after' => ' !']);// Output '¥ 123,456.79 !'echo $this->Number->format('123456.7890', ['locale' => 'fr_FR']);// Output '123 456,79 !'// Called as Number
echo Number::format('123456.7890', ['places' => 2,'before' => '¥ ','after' => ' !']);// Output '¥ 123,456.79 !'echo Number::format('123456.7890', ['locale' => 'fr_FR']);// Output '123 456,79 !'Cake\View\Helper\NumberHelper::ordinal(mixed $value, array $options = [])This method will output an ordinal number.
Examples:echo Number::ordinal(1);// Output '1st'
echo Number::ordinal(2);// Output '2nd'
echo Number::ordinal(2, ['locale' => 'fr_FR']);// Output '2e'echo Number::ordinal(410);// Output '410th'430

Chapter 11. Views

CakePHP Book, Release 3.10

Format DifferencesCake\View\Helper\NumberHelper::formatDelta(mixed $value, array $options = [])This method displays differences in value as a signed number:// Called as NumberHelper$this->Number->formatDelta($value, $options);// Called as Number
Number::formatDelta($value, $options);
The $value parameter is the number that you are planning on formatting for output. With no $options supplied, thenumber 1236.334 would output as 1,236. Note that the default precision is zero decimal places.
The $options parameter takes the same keys as Number::format() itself:
OptionDescription

placesprecision
localebeforeafter

Number of decimal places to use, ie. 2
Maximum number of decimal places to use, ie. 2
The locale name to use for formatting number, ie. “fr_FR”.
Text to display before the rendered number.
Text to display after the rendered number.

Example:// Called as NumberHelper
echo $this->Number->formatDelta('123456.7890', ['places' => 2,'before' => '[',
'after' => ']']);// Output '[+123,456.79]'// Called as Number
echo Number::formatDelta('123456.7890', ['places' => 2,'before' => '[',
'after' => ']']);// Output '[+123,456.79]'

Warning: All symbols are UTF-8.

More About Views

431

CakePHP Book, Release 3.10

Paginator
class Cake\View\Helper\PaginatorHelper(View $view, array $config = [])The PaginatorHelper is used to output pagination controls such as page numbers and next/previous links. It works intandem with PaginatorComponent.
See also Pagination for information on how to create paginated datasets and do paginated queries.
PaginatorHelper TemplatesInternally PaginatorHelper uses a series of simple HTML templates to generate markup. You can modify these templates to customize the HTML generated by the PaginatorHelper.
Templates use {{var}} style placeholders. It is important to not add any spaces around the {{}} or the replacements
will not work.
Loading Templates from a File
When adding the PaginatorHelper in your controller, you can define the ‘templates’ setting to define a template file toload. This allows you to customize multiple templates and keep your code DRY:// In your AppView.php
public function initialize(){...
$this->loadHelper('Paginator', ['templates' => 'paginator-templates']);}This will load the file located at config/paginator-templates.php. See the example below for how the file should look
like. You can also load templates from a plugin using plugin syntax:// In your AppView.php
public function initialize(){...
$this->loadHelper('Paginator', ['templates' => 'MyPlugin.paginator-templates']);}Whether your templates are in the primary application or a plugin, your templates file should look something like:return ['number' => '<a href="{{url}}">{{text}}</a>',];432

Chapter 11. Views

CakePHP Book, Release 3.10

Changing Templates at Run-time
Cake\View\Helper\PaginatorHelper::setTemplates($templates)
This method allows you to change the templates used by PaginatorHelper at runtime. This can be useful when you wantto customize templates for a particular method call:// Read the current template value.
$result = $this->Paginator->getTemplates('number');// Prior to 3.4$result = $this->Paginator->templates('number');// Change a template$this->Paginator->setTemplates(['number' => '<em><a href="{{url}}">{{text}}</a></em>']);Warning: Template strings containing a percentage sign (%) need special attention, you should prefix this characterwith another percentage so it looks like %%. The reason is that internally templates are compiled to be used withsprintf(). Example: ‘<div style=”width:{{size}}%%”>{{content}}</div>’

Template Names
PaginatorHelper uses the following templates:• nextActive The active state for a link generated by next().
• nextDisabled The disabled state for next().
• prevActive The active state for a link generated by prev().
• prevDisabled The disabled state for prev()• counterRange The template counter() uses when format == range.
• counterPages The template counter() uses when format == pages.
• first The template used for a link generated by first().
• last The template used for a link generated by last()• number The template used for a link generated by numbers().
• current The template used for the current page.
• ellipsis The template used for ellipses generated by numbers().
• sort The template for a sort link with no direction.
• sortAsc The template for a sort link with an ascending direction.
• sortDesc The template for a sort link with a descending direction.

More About Views

433

CakePHP Book, Release 3.10

Creating Sort Links
Cake\View\Helper\PaginatorHelper::sort($key, $title = null, $options = [])Parameters• $key (string) – The name of the column that the recordset should be sorted.
• $title (string) – Title for the link. If $title is null, $key will be used converted to “Title
Case” format and used as the title.
• $options (array) – Options for sorting link.
Generates a sorting link. Sets querystring parameters for the sort and direction. Links will default to sorting by asc.
After the first click, links generated with sort() will handle direction switching automatically. If the resultset is sorted‘asc’ by the specified key the returned link will sort by ‘desc’.
Accepted keys for $options:• escape Whether you want the contents HTML entity encoded, defaults to true.
• model The model to use, defaults to PaginatorHelper::defaultModel().
• direction The default direction to use when this link isn’t active.
• lock Lock direction. Will only use the default direction then, defaults to false.
Assuming you are paginating some posts, and are on page one:echo $this->Paginator->sort('user_id');
Output:<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">User Id</a>
You can use the title parameter to create custom text for your link:echo $this->Paginator->sort('user_id', 'User account');
Output:<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">User account</a>
If you are using HTML like images in your links remember to set escaping off:echo $this->Paginator->sort('user_id','<em>User account</em>',['escape' => false]);
Output:<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc"><em>User account</em></
˓→a>The direction option can be used to set the default direction for a link. Once a link is active, it will automatically switch
directions like normal:

434

Chapter 11. Views

CakePHP Book, Release 3.10

echo $this->Paginator->sort('user_id', null, ['direction' => 'desc']);Output:<a href="/posts/index?page=1&amp;sort=user_id&amp;direction=desc">User Id</a>
The lock option can be used to lock sorting into the specified direction:echo $this->Paginator->sort('user_id', null, ['direction' => 'asc', 'lock' => true]);Cake\View\Helper\PaginatorHelper::sortDir(string $model = null, mixed $options = [])Gets the current direction the recordset is sorted.
Cake\View\Helper\PaginatorHelper::sortKey(string $model = null, mixed $options = [])Gets the current key by which the recordset is sorted.
Creating Page Number Links
Cake\View\Helper\PaginatorHelper::numbers($options = [])Returns a set of numbers for the paged result set. Uses a modulus to decide how many numbers to show on each sideof the current page By default 8 links on either side of the current page will be created if those pages exist. Links will
not be generated for pages that do not exist. The current page is also not a link.
Supported options are:• before Content to be inserted before the numbers.
• after Content to be inserted after the numbers.
• model Model to create numbers for, defaults to PaginatorHelper::defaultModel().
• modulus how many numbers to include on either side of the current page, defaults to 8.
• first Whether you want first links generated, set to an integer to define the number of ‘first’ links to generate.
Defaults to false. If a string is set a link to the first page will be generated with the value as the title:echo $this->Paginator->numbers(['first' => 'First page']);• last Whether you want last links generated, set to an integer to define the number of ‘last’ links to generate.
Defaults to false. Follows the same logic as the first option. There is a last() method to be used separately
as well if you wish.
While this method allows a lot of customization for its output. It is also ok to just call the method without any parameters.
echo $this->Paginator->numbers();
Using the first and last options you can create links to the beginning and end of the page set. The following would
create a set of page links that include links to the first 2 and last 2 pages in the paged results:
echo $this->Paginator->numbers(['first' => 2, 'last' => 2]);More About Views

435CakePHP Book, Release 3.10

Creating Jump Links
In addition to generating links that go directly to specific page numbers, you’ll often want links that go to the previous
and next links, first and last pages in the paged data set.
Cake\View\Helper\PaginatorHelper::prev($title = '<< Previous', $options = [])Parameters• $title (string) – Title for the link.
• $options (mixed) – Options for pagination link.
Generates a link to the previous page in a set of paged records.
$options supports the following keys:• escape Whether you want the contents HTML entity encoded, defaults to true.
• model The model to use, defaults to PaginatorHelper::defaultModel().
• disabledTitle The text to use when the link is disabled. Defaults to the $title parameter.
A simple example would be:echo $this->Paginator->prev(' << ' . __('previous'));If you were currently on the second page of posts, you would get the following:<li class="prev"><a rel="prev" href="/posts/index?page=1&amp;sort=title&amp;order=desc">&lt;&lt; previous
</a>
</li>
If there were no previous pages you would get:<li class="prev disabled"><a href="" onclick="return false;">&lt;&lt; previous</a></˓→li>
To change the templates used by this method see PaginatorHelper Templates.
Cake\View\Helper\PaginatorHelper::next($title = 'Next >>', $options = [])This method is identical to prev() with a few exceptions. It creates links pointing to the next page instead of
the previous one. It also uses next as the rel attribute value instead of prev
Cake\View\Helper\PaginatorHelper::first($first = '<< first', $options = [])Returns a first or set of numbers for the first pages. If a string is given, then only a link to the first page with theprovided text will be created:echo $this->Paginator->first('< first');The above creates a single link for the first page. Will output nothing if you are on the first page. You can also
use an integer to indicate how many first paging links you want generated:echo $this->Paginator->first(3);The above will create links for the first 3 pages, once you get to the third or greater page. Prior to that nothing
will be output.
The options parameter accepts the following:
436

Chapter 11. Views

CakePHP Book, Release 3.10

• model The model to use defaults to PaginatorHelper::defaultModel()• escape Whether or not the text should be escaped. Set to false if your content contains HTML.
Cake\View\Helper\PaginatorHelper::last($last = 'last >>', $options = [])This method works very much like the first() method. It has a few differences though. It will not generate
any links if you are on the last page for a string values of $last. For an integer value of $last no links will be
generated once the user is inside the range of last pages.
Creating Header Link Tags
PaginatorHelper can be used to create pagination link tags in your page <head> elements:// Create next/prev links for the current model.
echo $this->Paginator->meta();// Create next/prev & first/last links for the current model.
echo $this->Paginator->meta(['first' => true, 'last' => true]);
New in version 3.4.0: The first and last options were added in 3.4.0
Checking the Pagination State
Cake\View\Helper\PaginatorHelper::current(string $model = null)Gets the current page of the recordset for the given model:// Our URL is: http://example.com/comments/view/page:3
echo $this->Paginator->current('Comment');// Output is 3
Cake\View\Helper\PaginatorHelper::hasNext(string $model = null)
Returns true if the given result set is not at the last page.
Cake\View\Helper\PaginatorHelper::hasPrev(string $model = null)
Returns true if the given result set is not at the first page.
Cake\View\Helper\PaginatorHelper::hasPage(string $model = null, integer $page = 1)
Returns true if the given result set has the page number given by $page.
Cake\View\Helper\PaginatorHelper::total(string $model = null)
Returns the total number of pages for the provided model.
New in version 3.4.0.
Creating a Page CounterCake\View\Helper\PaginatorHelper::counter($options = [])Returns a counter string for the paged result set. Using a provided format string and a number of options you can create
localized and application specific indicators of where a user is in the paged data set.
There are a number of options for counter(). The supported ones are:More About Views

437CakePHP Book, Release 3.10

• format Format of the counter. Supported formats are ‘range’, ‘pages’ and custom. Defaults to pages which
would output like ‘1 of 10’. In the custom mode the supplied string is parsed and tokens are replaced with actual
values. The available tokens are:
– {{page}} - the current page displayed.
– {{pages}} - total number of pages.
– {{current}} - current number of records being shown.
– {{count}} - the total number of records in the result set.
– {{start}} - number of the first record being displayed.
– {{end}} - number of the last record being displayed.
– {{model}} - The pluralized human form of the model name. If your model was ‘RecipePage’, {{model}}would be ‘recipe pages’.
You could also supply only a string to the counter method using the tokens available. For example:
echo $this->Paginator->counter('Page {{page}} of {{pages}}, showing {{current}} records out of{{count}} total, starting on record {{start}}, ending on {{end}}');
Setting ‘format’ to range would output like ‘1 - 3 of 13’:echo $this->Paginator->counter(['format' => 'range']);• model The name of the model being paginated, defaults to PaginatorHelper::defaultModel(). This isused in conjunction with the custom string on ‘format’ option.
Generating Pagination URLs
Cake\View\Helper\PaginatorHelper::generateUrl(array $options = [], $model = null, $full = false)
By default returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript).
echo $this->Paginator->generateUrl(['sort' => 'title']);Creating a Limit Selectbox Control
Cake\View\Helper\PaginatorHelper::limitControl(array $limits = [], $default = null, array $options = [])Create a dropdown control that changes the limit query parameter:// Use the defaults.
echo $this->Paginator->limitControl();// Define which limit options you want.
echo $this->Paginator->limitControl([25 => 25, 50 => 50]);// Custom limits and set the selected option
echo $this->Paginator->limitControl([25 => 25, 50 => 50], $user->perPage);

438

Chapter 11. Views

CakePHP Book, Release 3.10

The generated form and control will automatically submit on change.
New in version 3.5.0: The limitControl() method was added in 3.5.0
Configuring Pagination Options
Cake\View\Helper\PaginatorHelper::options($options = [])Sets all the options for the PaginatorHelper. Supported options are:• url The URL of the paginating action. ‘url’ has a few sub options as well:– sort The key that the records are sorted by.
– direction The direction of the sorting. Defaults to ‘ASC’.
– page The page number to display.
The above mentioned options can be used to force particular pages/directions. You can also append additional
URL content into all URLs generated in the helper:$this->Paginator->options(['url' => ['sort' => 'email','direction' => 'desc','page' => 6,'lang' => 'en']]);
The above adds the en route parameter to all links the helper will generate. It will also create links with specificsort, direction and page values. By default PaginatorHelper will merge in all of the current passed arguments
and query string parameters.
• escape Defines if the title field for links should be HTML escaped. Defaults to true.
• model The name of the model being paginated, defaults to PaginatorHelper::defaultModel().
Example Usage
It’s up to you to decide how to show records to the user, but most often this will be done inside HTML tables. The
examples below assume a tabular layout, but the PaginatorHelper available in views doesn’t always need to be restricted
as such.
See the details on PaginatorHelper138 in the API. As mentioned, the PaginatorHelper also offers sorting features which
can be integrated into your table column headers:<!-- src/Template/Posts/index.ctp --><table><tr><th><?= $this->Paginator->sort('id', 'ID') ?></th><th><?= $this->Paginator->sort('title', 'Title') ?></th></tr><?php foreach ($recipes as $recipe): ?><tr>(continues on next page)
138 https://api.cakephp.org/3.x/class-Cake.View.Helper.PaginatorHelper.html

More About Views

439CakePHP Book, Release 3.10

(continued from previous page)<td><?= $recipe->id ?> </td><td><?= h($recipe->title) ?> </td></tr><?php endforeach; ?></table>The links output from the sort() method of the PaginatorHelper allow users to click on table headers to toggle thesorting of the data by a given field.
It is also possible to sort a column based on associations:<table><tr><th><?= $this->Paginator->sort('title', 'Title') ?></th><th><?= $this->Paginator->sort('Authors.name', 'Author') ?></th></tr><?php foreach ($recipes as $recipe): ?><tr><td><?= h($recipe->title) ?> </td><td><?= h($recipe->author->name) ?> </td></tr><?php endforeach; ?></table>Note: Sorting by columns in associated models requires setting these in the PaginationComponent::paginate
property. Using the example above, the controller handling the pagination would need to set its sortWhitelist key
as follows:$this->paginate = ['sortWhitelist' => ['Posts.title','Authors.name',],];
For more information on using the sortWhitelist option, please see Control which Fields Used for Ordering.
The final ingredient to pagination display in views is the addition of page navigation, also supplied by the PaginationHelper:// Shows the page numbers<?= $this->Paginator->numbers() ?>// Shows the next and previous links<?= $this->Paginator->prev('« Previous') ?><?= $this->Paginator->next('Next »') ?>// Prints X of Y, where X is current page and Y is number of pages<?= $this->Paginator->counter() ?>The wording output by the counter() method can also be customized using special markers:

440

Chapter 11. Views

CakePHP Book, Release 3.10<?= $this->Paginator->counter(['format' => 'Page {{page}} of {{pages}}, showing {{current}} records out of{{count}} total, starting on record {{start}}, ending on {{end}}']) ?>Paginating Multiple Results
If you are paginating multiple queries you’ll need to set the model option when generating pagination related elements.
You can either use the model option on every method call you make to PaginatorHelper, or use options() to set
the default model:// Pass the model option
echo $this->Paginator->sort('title', ['model' => 'Articles']);// Set the default model.
$this->Paginator->options(['model' => 'Articles']);echo $this->Paginator->sort('title');By using the model option, PaginatorHelper will automatically use the scope defined in when the query waspaginated.
New in version 3.3.0: Multiple Pagination was added in 3.3.0
Rssclass Cake\View\Helper\RssHelper(View $view, array $config = [])The RssHelper makes generating XML for RSS feeds139 easy.
Deprecated since version 3.5.0: RssHelper is deprecated as of 3.5.0, and will be removed in 4.0.0
Creating an RSS Feed with the RssHelperThis example assumes you have a Articles Controller, Articles Table and an Article Entity already created and want tomake an alternative view for RSS.
Creating an XML/RSS version of your Articles index action is a snap with CakePHP. After a few simple steps you
can simply append the desired extension .rss to articles making your URL articles.rss. This will work with
the index action included as well so articles/index would become articles/index.rss Before we jump too far
ahead trying to get our webservice up and running we need to do a few things. First extensions parsing needs to be
activated, this is done in config/routes.php:
Router::extensions('rss');
In the call above we’ve activated the .rss extension. When using Cake\Routing\Router::extensions() you canpass a string or an array of extensions as first argument. This will activate each extension/content-type for use in yourapplication. Now when the address articles.rss is requested you will get an XML version of your articles index
action. However, first we need to edit the controller to add in the rss-specific code.
139 https://en.wikipedia.org/wiki/RSS

More About Views

441

CakePHP Book, Release 3.10

Controller Code
It is a good idea to add RequestHandler to your ArticlesController’s initialize() method. This will allow a lot of
automagic to occur:
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
Before we can make an RSS version of our articles index action we need to get a few things in order. It may be
tempting to put the channel metadata in the controller action and pass it to your view using the Cake\Controller\
Controller::set() method but this is inappropriate. That information can also go in the view. That will comelater though, for now if you have a different set of logic for the data used to make the RSS feed and the data for theHTML view you can use the Cake\Controller\Component\RequestHandler::isRss() method, otherwise yourcontroller can stay the same:// Modify the Articles Controller action that corresponds to// the action which deliver the rss feed, which is the// Index action in our example.
public function index(){
if ($this->RequestHandler->isRss() ) {$articles = $this->Articles->find()->limit(20)->order(['created' => 'desc']);$this->set(compact('articles'));} else {// this is not an Rss request, so deliver// data used by website's interface.
$this->paginate = ['order' => ['created' => 'desc'],'limit' => 10];$this->set('articles', $this->paginate($this->Articles));$this->set('_serialize', ['articles']);}}With all the View variables set we need to create an rss layout.

442

Chapter 11. Views

CakePHP Book, Release 3.10

LayoutAn Rss layout is very simple, put the following contents in src/Template/Layout/rss/default.ctp:
if (!isset($documentData)) {$documentData = [];}if (!isset($channelData)) {$channelData = [];}if (!isset($channelData['title'])) {$channelData['title'] = $this->fetch('title');}$channel = $this->Rss->channel([], $channelData, $this->fetch('content'));echo $this->Rss->document($documentData, $channel);It doesn’t look like much but thanks to the power in the RssHelper it’s doing a lot of lifting for us. We haven’t set$documentData or $channelData in the controller, however in CakePHP your views can pass variables back to thelayout. Which is where our $channelData array will come from setting all of the meta data for our feed.
Next up is view file for my articles index action. Much like the layout file we created, we need to create a
src/Template/Articles/rss/ directory and create a new index.ctp inside that folder. The contents of the file are below.
View
Our view, located at src/Template/Articles/rss/index.ctp, begins by setting the $documentData and $channelData
variables for the layout, these contain all the metadata for our RSS feed. This is done by using the Cake\View\
View::set() method which is analogous to the Cake\Controller\Controller::set() method. Here though weare passing the channel’s metadata back to the layout:$this->set('channelData', ['title' => __("Most Recent Articles"),'link' => $this->Url->build('/', true),'description' => __("Most recent articles."),'language' => 'en-us']);
The second part of the view generates the elements for the actual records of the feed. This is accomplished by looping
through the data that has been passed to the view ($items) and using the RssHelper::item() method. The othermethod you can use, RssHelper::items() which takes a callback and an array of items for the feed. The callback
method is usually called transformRss(). There is one downfall to this method, which is that you cannot use any of
the other helper classes to prepare your data inside the callback method because the scope inside the method does notinclude anything that is not passed inside, thus not giving access to the TimeHelper or any other helper that you may
need. The RssHelper::item() transforms the associative array into an element for each key value pair.
Note: You will need to modify the $link variable as appropriate to your application. You might also want to use avirtual field in your Entity.
foreach ($articles as $article) {$created = strtotime($article->created);(continues on next page)

More About Views

443

CakePHP Book, Release 3.10

(continued from previous page)$link = ['controller' => 'Articles','action' => 'view','year' => date('Y', $created),'month' => date('m', $created),'day' => date('d', $created),'slug' => $article->slug];// Remove & escape any HTML to make sure the feed content will validate.
$body = h(strip_tags($article->body));$body = $this->Text->truncate($body, 400, ['ending' => '...','exact' => true,'html'=> true,]);echo $this->Rss->item([], ['title' => $article->title,'link' => $link,'guid' => ['url' => $link, 'isPermaLink' => 'true'],'description' => $body,'pubDate' => $article->created]);}
You can see above that we can use the loop to prepare the data to be transformed into XML elements. It is importantto filter out any non-plain text characters out of the description, especially if you are using a rich text editor for the
body of your blog. In the code above we used strip_tags() and h() to remove/escape any XML special charactersfrom the content, as they could cause validation errors. Once we have set up the data for the feed, we can then use the
RssHelper::item() method to create the XML in RSS format. Once you have all this setup, you can test your RSS
feed by going to your site /articles.rss and you will see your new feed. It is always important that you validate
your RSS feed before making it live. This can be done by visiting sites that validate the XML such as Feed Validator
or the w3c site at https://validator.w3.org/feed/.
Note: You may need to set the value of ‘debug’ in your core configuration to false to get a valid feed, because of thevarious debug information added automagically under higher debug settings that break XML syntax or feed validation
rules.

Sessionclass Cake\View\Helper\SessionHelper(View $view, array $config = [])Deprecated since version 3.0.0: The SessionHelper is deprecated in 3.x. Instead you should use either the FlashHelperor access the session via the request.
As a natural counterpart to the Session object, the Session Helper replicates most of the object’s functionality andmakes it available in your view.
The major difference between the SessionHelper and the Session object is that the helper does not have the ability towrite to the session.
444

Chapter 11. Views

CakePHP Book, Release 3.10

As with the session object, data is read by using dot notation array structures:['User' => ['username' => 'super@example.com']];
Given the previous array structure, the node would be accessed by User.username, with the dot indicating the nested
array. This notation is used for all SessionHelper methods wherever a $key is used.
Cake\View\Helper\SessionHelper::read(string $key)
Return type
mixed
Read from the Session. Returns a string or array depending on the contents of the session.
Cake\View\Helper\SessionHelper::check(string $key)
Return typebooleanCheck to see whether a key is in the Session. Returns a boolean representing the key’s existence.
Textclass Cake\View\Helper\TextHelper(View $view, array $config = [])The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links,
formatting URLs, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text,
and gracefully truncating long stretches of text.
Linking Email addresses
Cake\View\Helper\TextHelper::autoLinkEmails(string $text, array $options = [])Adds links to the well-formed email addresses in $text, according to any options defined in $options (seeHtmlHelper::link()).
$myText = 'For more information regarding our world-famous ' .
'pastries and desserts, contact info@example.com';$linkedText = $this->Text->autoLinkEmails($myText);
Output:For more information regarding our world-famous pastries and desserts,
contact <a href="mailto:info@example.com">info@example.com</a>This method automatically escapes its input. Use the escape option to disable this if necessary.

More About Views

445CakePHP Book, Release 3.10

Linking URLs
Cake\View\Helper\TextHelper::autoLinkUrls(string $text, array $options = [])Same as autoLinkEmails(), only this method searches for strings that start with https, http, ftp, or nntp and links
them appropriately.
This method automatically escapes its input. Use the escape option to disable this if necessary.
Linking Both URLs and Email Addresses
Cake\View\Helper\TextHelper::autoLink(string $text, array $options = [])Performs the functionality in both autoLinkUrls() and autoLinkEmails() on the supplied $text. All URLs andemails are linked appropriately given the supplied $options.
This method automatically escapes its input. Use the escape option to disable this if necessary.
Converting Text into Paragraphs
Cake\View\Helper\TextHelper::autoParagraph(string $text)
Adds proper <p> around text where double-line returns are found, and <br> where single-line returns are found.
$myText = 'For more information
regarding our world-famous pastries and desserts.
contact info@example.com';$formattedText = $this->Text->autoParagraph($myText);
Output:<p>For more information<br />regarding our world-famous pastries and desserts.</p><p>contact info@example.com</p>Highlighting Substrings
Cake\View\Helper\TextHelper::highlight(string $haystack, string $needle, array $options = [])Highlights $needle in $haystack using the $options['format'] string specified or a default string.
Options:• format string - The piece of HTML with the phrase that will be highlighted• html bool - If true, will ignore any HTML tags, ensuring that only the correct text is highlighted
Example:// Called as TextHelper
echo $this->Text->highlight($lastSentence,'using',(continues on next page)

446

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)['format' => '<span class="highlight">\1</span>']);// Called as Text
use Cake\Utility\Text;
echo Text::highlight($lastSentence,'using',['format' => '<span class="highlight">\1</span>']);Output:Highlights $needle in $haystack <span class="highlight">using</span> the$options['format'] string specified or a default string.

Removing Links
Cake\View\Helper\TextHelper::stripLinks($text)
Strips the supplied $text of any HTML links.
Truncating Text
Cake\View\Helper\TextHelper::truncate(string $text, int $length = 100, array $options)
If $text is longer than $length, this method truncates it at $length and adds a suffix consisting of 'ellipsis',if defined. If 'exact' is passed as false, the truncation will occur at the first whitespace after the point at which$length is exceeded. If 'html' is passed as true, HTML tags will be respected and will not be cut off.
$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:['ellipsis' => '...','exact' => true,'html' => false]
Example:// Called as TextHelper
echo $this->Text->truncate('The killer crept forward and tripped on the rug.',
22,['ellipsis' => '...','exact' => false]);(continues on next page)

More About Views

447

CakePHP Book, Release 3.10

(continued from previous page)// Called as Text
use Cake\Utility\Text;
echo Text::truncate('The killer crept forward and tripped on the rug.',
22,['ellipsis' => '...','exact' => false]);
Output:The killer crept...

Truncating the Tail of a String
Cake\View\Helper\TextHelper::tail(string $text, int $length = 100, array $options)
If $text is longer than $length, this method removes an initial substring with length consisting of the difference andprepends a prefix consisting of 'ellipsis', if defined. If 'exact' is passed as false, the truncation will occur at
the first whitespace prior to the point at which truncation would otherwise take place.
$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:['ellipsis' => '...','exact' => true]
Example:$sampleText = 'I packed my bag and in it I put a PSP, a PS3, a TV, ' .
'a C# program that can divide by zero, death metal t-shirts'// Called as TextHelper
echo $this->Text->tail($sampleText,
70,['ellipsis' => '...','exact' => false]);// Called as Text
use Cake\Utility\Text;
echo Text::tail($sampleText,
70,(continues on next page)

448

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)['ellipsis' => '...','exact' => false]);
Output:...a TV, a C# program that can divide by zero, death metal t-shirts

Extracting an Excerpt
Cake\View\Helper\TextHelper::excerpt(string $haystack, string $needle, integer $radius=100, string$ellipsis="...")
Extracts an excerpt from $haystack surrounding the $needle with a number of characters on each side determined
by $radius, and prefix/suffix with $ellipsis. This method is especially handy for search results. The query stringor keywords can be shown within the resulting document.
// Called as TextHelper
echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');// Called as Text
use Cake\Utility\Text;
echo Text::excerpt($lastParagraph, 'method', 50, '...');
Output:... by $radius, and prefix/suffix with $ellipsis. This method is especiallyhandy for search results. The query...

Converting an Array to Sentence Form
Cake\View\Helper\TextHelper::toList(array $list, $and='and', $separator=', ')Creates a comma-separated list where the last two items are joined with ‘and’:$colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];// Called as TextHelper
echo $this->Text->toList($colors);// Called as Text
use Cake\Utility\Text;
echo Text::toList($colors);
Output:More About Views

449

CakePHP Book, Release 3.10

red, orange, yellow, green, blue, indigo and violetTimeclass Cake\View\Helper\TimeHelper(View $view, array $config = [])The TimeHelper allows for the quick processing of time related information. The TimeHelper has two main tasks thatit can perform:
1. It can format time strings.
2. It can test time.
Using the Helper
A common use of the TimeHelper is to offset the date and time to match a user’s time zone. Lets use a forum as an example. Your forum has many users who may post messages at any time from any part of theworld. An easy way to manage the time is to save all dates and times as GMT+0 or UTC. Uncomment the line
date_default_timezone_set('UTC'); in config/bootstrap.php to ensure your application’s time zone is set to
GMT+0.
Next add a time zone field to your users table and make the necessary modifications to allow your users to set their timezone. Now that we know the time zone of the logged in user we can correct the date and time on our posts using the
TimeHelper:
echo $this->Time->format($post->created,\IntlDateFormatter::FULL,
null,$user->time_zone);// Will display 'Saturday, August 22, 2011 at 11:53:00 PM GMT'// for a user in GMT+0. While displaying,// 'Saturday, August 22, 2011 at 03:53 PM GMT-8:00'// for a user in GMT-8
Most of TimeHelper’s features are intended as backwards compatible interfaces for applications that are upgradingfrom older versions of CakePHP. Because the ORM returns Cake\I18n\Time instances for every timestamp anddatetime column, you can use the methods there to do most tasks. For example, to read about the accepted formatting
strings take a look at the Cake\I18n\Time::i18nFormat()140 method.
Urlclass Cake\View\Helper\UrlHelper(View $view, array $config = [])The UrlHelper makes it easy for you to generate URLs from your other helpers. It also gives you a single place tocustomize how URLs are generated by overriding the core helper with an application one. See the Aliasing Helpers
section for how to do this.
140 https://api.cakephp.org/3.x/class-Cake.I18n.Time.html#_i18nFormat

450

Chapter 11. Views

CakePHP Book, Release 3.10

Generating URLs
Cake\View\Helper\UrlHelper::build(mixed $url = null, boolean|array $full = false)
Returns a URL pointing to a combination of controller and action. If $url is empty, it returns the REQUEST_URI,
otherwise it generates the URL for the controller and action combo. If full is true, the full base URL will be
prepended to the result:echo $this->Url->build(["controller" => "Posts","action" => "view","bar",]);// Output/posts/view/bar
Here are a few more usage examples:
URL with extension:echo $this->Url->build(["controller" => "Posts","action" => "list","_ext" => "rss",]);// Output/posts/list.rss
URL (starting with ‘/’) with the full base URL prepended:echo $this->Url->build('/posts', true);// Output
http://somedomain.com/posts
URL with GET parameters and fragment anchor:echo $this->Url->build(["controller" => "Posts","action" => "search","?" => ["foo" => "bar"],"#" => "first",]);// Output/posts/search?foo=bar#first
The above example uses the ? key which is useful when you want to be explicit about the query string parameters you
are using, or if you want a query string parameter that shares a name with one of your route placeholders.
URL for named route:More About Views

451

CakePHP Book, Release 3.10// Assuming a route is setup as a named route:// $router->connect(//'/products/:slug',//[//'controller' => 'Products',//'action' => 'view',
//
],
//
[
//
'_name' => 'product-page',
//
]
// );
echo $this->Url->build(['_name' => 'product-page', 'slug' => 'i-m-slug']);// Will result in:/products/i-m-slug
The 2nd parameter allows you to define options controlling HTML escaping, and whether or not the base path should
be added:$this->Url->build('/posts', ['escape' => false,'fullBase' => true,]);
URL with asset timestamp wrapped by a <link rel="preload"/>, here pre-loading a font. Note: The file must exist
and Configure::read('Asset.timestamp') must return true or 'force' for the timestamp to be appended:echo $this->Html->meta(['rel' => 'preload','href' => $this->Url->assetUrl('/assets/fonts/yout-font-pack/your-font-name.woff2'),'as' => 'font',]);
New in version 3.3.5: build() accepts an array as the 2nd argument as of 3.3.5
New in version 3.6.0: The timestamp option was added to build().
If you are generating URLs for CSS, Javascript or image files there are helper methods for each of these asset types:// Outputs /img/icon.png$this->Url->image('icon.png');// Outputs /js/app.js$this->Url->script('app.js');// Outputs /css/app.css$this->Url->css('app.css');// Force timestamps for one method call.
$this->Url->css('app.css', ['timestamp' => 'force']);// Or disable timestamps for one method call.
$this->Url->css('app.css', ['timestamp' => false]);452

Chapter 11. Views

CakePHP Book, Release 3.10

New in version 3.2.4: The asset helper methods were added in 3.2.4.
New in version 3.6.0: The timestamp option was added to asset helper methods.
For further information check Router::url141 in the API.
Configuring Helpers
You load helpers in CakePHP by declaring them in a view class. An AppView class comes with every CakePHP
application and is the ideal place to load helpers:class AppView extends View{
public function initialize(){
parent::initialize();$this->loadHelper('Html');$this->loadHelper('Form');$this->loadHelper('Flash');}}To load helpers from plugins use the plugin syntax used elsewhere in CakePHP:$this->loadHelper('Blog.Comment');
You don’t have to explicitly load Helpers that come from CakePHP or your application. These helpers can be lazily
loaded upon first use. For example:// Loads the FormHelper if it has not already been loaded.
$this->Form->create($article);
From within a plugin’s views, plugin helpers can also be lazily loaded. For example, view templates in the ‘Blog’
plugin, can lazily load helpers from the same plugin.
Conditionally Loading Helpers
You can use the current action name to conditionally load helpers:class AppView extends View{
public function initialize(){
parent::initialize();
if ($this->request->getParam('action') === 'index') {$this->loadHelper('ListPage');}}}
You can also use your controller’s beforeRender method to load helpers:
141 https://api.cakephp.org/3.x/class-Cake.Routing.Router.html#_url

More About Views

453

CakePHP Book, Release 3.10

class ArticlesController extends AppController{
public function beforeRender(Event $event){parent::beforeRender($event);$this->viewBuilder()->helpers(['MyHelper']);}}Configuration options
You can pass configuration options to helpers. These options can be used to set attribute values or modify the behaviorof a helper:
namespace App\View\Helper;
use Cake\View\Helper;
use Cake\View\View;
class AwesomeHelper extends Helper{// initialize() hook is available since 3.2. For prior versions you can// override the constructor if required.
public function initialize(array $config){
debug($config);}}
Options can be specified when declaring helpers in controller as shown:namespace App\Controller;
use App\Controller\AppController;class AwesomeController extends AppController{
public $helpers = ['Awesome' => ['option1' => 'value1']];}
By default all configuration options will be merged with the $_defaultConfig property. This property should define
the default values of any configuration your helper requires. For example:
namespace App\View\Helper;
use Cake\View\Helper;
use Cake\View\StringTemplateTrait;class AwesomeHelper extends Helper{
use StringTemplateTrait;(continues on next page)454

Chapter 11. Views

CakePHP Book, Release 3.10

(continued from previous page)

protected $_defaultConfig = ['errorClass' => 'error','templates' => ['label' => '<label for="{{for}}">{{content}}</label>',],];}Any configuration provided to your helper’s constructor will be merged with the default values during construction andthe merged data will be set to _config. You can use the config() method to read runtime configuration:// Read the errorClass config option.
$class = $this->Awesome->config('errorClass');
Using helper configuration allows you to declaratively configure your helpers and keep configuration logic out of yourcontroller actions. If you have configuration options that cannot be included as part of a class declaration, you can set
those in your controller’s beforeRender callback:class PostsController extends AppController{
public function beforeRender(Event $event){parent::beforeRender($event);$builder = $this->viewBuilder();$builder->helpers(['CustomStuff' => $this->_getCustomStuffConfig(),]);}}

Aliasing Helpers
One common setting to use is the className option, which allows you to create aliased helpers in your views. Thisfeature is useful when you want to replace $this->Html or another common Helper reference with a custom implementation:// src/View/AppView.php
class AppView extends View{
public function initialize(){$this->loadHelper('Html', ['className' => 'MyHtml']);}}// src/View/Helper/MyHtmlHelper.php
namespace App\View\Helper;
use Cake\View\Helper\HtmlHelper;(continues on next page)

More About Views

455

CakePHP Book, Release 3.10

(continued from previous page)class MyHtmlHelper extends HtmlHelper{// Add your code to override the core HtmlHelper}
The above would alias MyHtmlHelper to $this->Html in your views.
Note: Aliasing a helper replaces that instance anywhere that helper is used, including inside other Helpers.

Using Helpers
Once you’ve configured which helpers you want to use in your controller, each helper is exposed as a public property
in the view. For example, if you were using the HtmlHelper you would be able to access it by doing the following:echo $this->Html->css('styles');
The above would call the css() method on the HtmlHelper.
$this->{$helperName}.

You can access any loaded helper using

Loading Helpers On The Fly
There may be situations where you need to dynamically load a helper from inside a view. You can use the view’s
Cake\View\HelperRegistry to do this:// Either one works.
$mediaHelper = $this->loadHelper('Media', $mediaConfig);$mediaHelper = $this->helpers()->load('Media', $mediaConfig);
The HelperRegistry is a registry and supports the registry API used elsewhere in CakePHP.
Callback Methods
Helpers feature several callbacks that allow you to augment the view rendering process. See the Helper Class and the
Events System documentation for more information.
Creating Helpers
You can create custom helper classes for use in your application or plugins. Like most components of CakePHP, helperclasses have a few conventions:• Helper class files should be put in src/View/Helper. For example: src/View/Helper/LinkHelper.php• Helper classes should be suffixed with Helper. For example: LinkHelper.
• When referencing helper class names you should omit the Helper suffix.
$this->loadHelper('Link');.

For example:

You’ll also want to extend Helper to ensure things work correctly:

456

Chapter 11. Views

CakePHP Book, Release 3.10/* src/View/Helper/LinkHelper.php */namespace App\View\Helper;
use Cake\View\Helper;class LinkHelper extends Helper{
public function makeEdit($title, $url){// Logic to create specially formatted link goes here...
}}Including Other Helpers
You may wish to use some functionality already existing in another helper. To do so, you can specify helpers you wish
to use with a $helpers array, formatted just as you would in a controller:/* src/View/Helper/LinkHelper.php (using other helpers) */namespace App\View\Helper;
use Cake\View\Helper;class LinkHelper extends Helper{
public $helpers = ['Html'];public function makeEdit($title, $url){// Use the HTML helper to output// Formatted data:$link = $this->Html->link($title, $url, ['class' => 'edit']);return '<div class="editOuter">' . $link . '</div>';}}

Using Your Helper
Once you’ve created your helper and placed it in src/View/Helper/, you can load it in your views:
class AppView extends View{
public function initialize(){
parent::initialize();$this->loadHelper('Link');(continues on next page)

More About Views

457

CakePHP Book, Release 3.10

(continued from previous page)}}
Once your helper has been loaded, you can use it in your views by accessing the matching view property:<!-- make a link using the new helper --><?= $this->Link->makeEdit('Change this Recipe', '/recipes/edit/5') ?>Note: The HelperRegistry will attempt to lazy load any helpers not specifically identified in your Controller.

Accessing View Variables Inside Your Helper
If you would like to access a View variable inside a helper, you can use $this->_View->get() like:class AwesomeHelper extends Helper{
public $helpers = ['Html'];public function someMethod(){// set meta description
echo $this->Html->meta('description', $this->_View->get('metaDescription'), ['block' => 'meta']);}}

Rendering A View Element Inside Your Helper
If you would like to render an Element inside your Helper you can use $this->_View->element() like:class AwesomeHelper extends Helper{
public function someFunction(){// output directly in your helper
echo $this->_View->element('/path/to/element',['foo'=>'bar','bar'=>'foo']);// or return it to your view
return $this->_View->element('/path/to/element',['foo'=>'bar','bar'=>'foo']
);
}
}

458

Chapter 11. Views

CakePHP Book, Release 3.10

Helper Class
class Helper

Callbacks
By implementing a callback method in a helper, CakePHP will automatically subscribe your helper to the relevant
event. Unlike previous versions of CakePHP you should not call parent in your callbacks, as the base Helper classdoes not implement any of the callback methods.
Helper::beforeRenderFile(Event $event, $viewFile)Is called before each view file is rendered. This includes elements, views, parent views and layouts.
Helper::afterRenderFile(Event $event, $viewFile, $content)
Is called after each view file is rendered. This includes elements, views, parent views and layouts. A callback
can modify and return $content to change how the rendered content will be displayed in the browser.
Helper::beforeRender(Event $event, $viewFile)
The beforeRender method is called after the controller’s beforeRender method but before the controller renders
view and layout. Receives the file being rendered as an argument.
Helper::afterRender(Event $event, $viewFile)Is called after the view has been rendered but before layout rendering has started.
Helper::beforeLayout(Event $event, $layoutFile)Is called before layout rendering starts. Receives the layout filename as an argument.
Helper::afterLayout(Event $event, $layoutFile)Is called after layout rendering is complete. Receives the layout filename as an argument.

More About Views

459

CakePHP Book, Release 3.10

460

Chapter 11. Views

CHAPTER 12

Database Access & ORM

In CakePHP working with data through the database is done with two primary object types. The first are repositories ortable objects. These objects provide access to collections of data. They allow you to save new records, modify/delete
existing ones, define relations, and perform bulk operations. The second type of objects are entities. Entities represent
individual records and allow you to define row/record level behavior & functionality.
These two classes are usually responsible for managing almost everything that happens regarding your data, its validity,
interactions and evolution of the information workflow in your domain of work.
CakePHP’s built-in ORM specializes in relational databases, but can be extended to support alternative datasources.
The CakePHP ORM borrows ideas and concepts from both ActiveRecord and Datamapper patterns. It aims to createa hybrid implementation that combines aspects of both patterns to create a fast, simple to use ORM.
Before we get started exploring the ORM, make sure you configure your database connections.
Note: If you are familiar with previous versions of CakePHP, you should read the New ORM Upgrade Guide forimportant differences between CakePHP 3.0 and older versions of CakePHP.

Quick Example
To get started you don’t have to write any code. If you’ve followed the CakePHP conventions for your database tables
you can just start using the ORM. For example if we wanted to load some data from our articles table we could do:
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');(continues on next page)461

CakePHP Book, Release 3.10

(continued from previous page)$query = $articles->find();foreach ($query as $row) {echo $row->title;}
Note that we didn’t have to create any code or wire any configuration up. The conventions in CakePHP allow us to skip
some boilerplate code and allow the framework to insert base classes when your application has not created a concreteclass. If we wanted to customize our ArticlesTable class adding some associations or defining some additional methods
we would add the following to src/Model/Table/ArticlesTable.php after the <?php opening tag:namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{}
Table classes use the CamelCased version of the table name with the Table suffix as the class name. Once your classhas been created you get a reference to it using the TableLocator through TableRegistry as before:
use Cake\ORM\TableRegistry;// Now $articles is an instance of our ArticlesTable class.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');
Now that we have a concrete table class, we’ll probably want to use a concrete entity class. Entity classes let you define
accessor and mutator methods, define custom logic for individual records and much more. We’ll start off by adding thefollowing to src/Model/Entity/Article.php after the <?php opening tag:namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{}
Entities use the singular CamelCase version of the table name as their class name by default. Now that we have created
our entity class, when we load entities from the database we’ll get instances of our new Article class:use Cake\ORM\TableRegistry;// Now an instance of ArticlesTable.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$query = $articles->find();foreach ($query as $row) {// Each row is now an instance of our Article class.
(continues on next page)462

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)echo $row->title;}
CakePHP uses naming conventions to link the Table and Entity class together. If you need to customize which entity atable uses you can use the entityClass() method to set a specific classname.
See the chapters on Table Objects and Entities for more information on how to use table objects and entities in yourapplication.

More Information
Database Basics
The CakePHP database access layer abstracts and provides help with most aspects of dealing with relational databases
such as, keeping connections to the server, building queries, preventing SQL injections, inspecting and altering
schemas, and with debugging and profiling queries sent to the database.
Quick TourThe functions described in this chapter illustrate what is possible to do with the lower-level database access API. If
instead you want to learn more about the complete ORM, you can read the Query Builder and Table Objects sections.
The easiest way to create a database connection is using a DSN string:use Cake\Datasource\ConnectionManager;$dsn = 'mysql://root:password@localhost/my_database';
ConnectionManager::config('default', ['url' => $dsn]);Once created, you can access the connection object to start using it:$connection = ConnectionManager::get('default');

Supported Databases
CakePHP supports the following relational database servers:• MySQL 5.5+
• SQLite 3• PostgreSQL 8.3+
• SQLServer 2008+• Oracle (through a community plugin)
You will need the correct PDO extension installed for each of the above database drivers. Procedural APIs are notsupported.
The Oracle database is supported through the Driver for Oracle Database142 community plugin.
142 https://github.com/CakeDC/cakephp-oracle-driver

More Information463

CakePHP Book, Release 3.10

Running Select Statements
Running raw SQL queries is a breeze:
use Cake\Datasource\ConnectionManager;$connection = ConnectionManager::get('default');$results = $connection->execute('SELECT * FROM articles')->fetchAll('assoc');
You can use prepared statements to insert parameters:$results = $connection->execute('SELECT * FROM articles WHERE id = :id', ['id' => 1])->fetchAll('assoc');
It is also possible to use complex data types as arguments:
use Cake\Datasource\ConnectionManager;
use DateTime;$connection = ConnectionManager::get('default');$results = $connection->execute('SELECT * FROM articles WHERE created >= :created',['created' => new DateTime('1 day ago')],['created' => 'datetime'])->fetchAll('assoc');
Instead of writing the SQL manually, you can use the query builder:$results = $connection->newQuery()->select('*')->from('articles')->where(['created >' => new DateTime('1 day ago')], ['created' => 'datetime'])->order(['title' => 'DESC'])->execute()->fetchAll('assoc');

Running Insert Statements
Inserting rows in the database is usually a matter of a couple lines:
use Cake\Datasource\ConnectionManager;
use DateTime;$connection = ConnectionManager::get('default');$connection->insert('articles', ['title' => 'A New Article','created' => new DateTime('now')], ['created' => 'datetime']);464

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Running Update Statements
Updating rows in the database is equally intuitive, the following example will update the article with id 10:
use Cake\Datasource\ConnectionManager;$connection = ConnectionManager::get('default');$connection->update('articles', ['title' => 'New title'], ['id' => 10]);

Running Delete Statements
Similarly, the delete() method is used to delete rows from the database, the following example deletes the article
with id 10:
use Cake\Datasource\ConnectionManager;$connection = ConnectionManager::get('default');$connection->delete('articles', ['id' => 10]);

Configuration
By convention database connections are configured in config/app.php. The connection information defined in this fileis fed into Cake\Datasource\ConnectionManager creating the connection configuration your application will beusing. Sample connection information can be found in config/app.default.php. A sample connection configuration
would look like:'Datasources' => ['default' => ['className' => 'Cake\Database\Connection','driver' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'localhost','username' => 'my_app','password' => 'secret','database' => 'my_app','encoding' => 'utf8mb4','timezone' => 'UTC','cacheMetadata' => true,]],
The above will create a ‘default’ connection, with the provided parameters. You can define as many connections as
you want in your configuration file. You can also define additional connections at runtime using Cake\Datasource\
ConnectionManager::config(). An example of that would be:
use Cake\Datasource\ConnectionManager;
ConnectionManager::config('default', ['className' => 'Cake\Database\Connection','driver' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'localhost','username' => 'my_app',(continues on next page)

More Information

465

CakePHP Book, Release 3.10

(continued from previous page)'password' => 'secret','database' => 'my_app','encoding' => 'utf8mb4','timezone' => 'UTC','cacheMetadata' => true,]);
Configuration options can also be provided as a DSN string. This is useful when working with environment variables
or PaaS providers:ConnectionManager::config('default', ['url' => 'mysql://my_app:secret@localhost/my_app?encoding=utf8&timezone=UTC&
˓→cacheMetadata=true',]);
When using a DSN string you can define any additional parameters/options as query string arguments.
By default, all Table objects will use the default connection. To use a non-default connection, see Configuring
Connections.
There are a number of keys supported in database configuration. A full list is as follows:className
The fully namespaced class name of the class that represents the connection to a database server. This class is responsible for loading the database driver, providing SQL transaction mechanisms and preparing SQL statements
among other things.
driverThe class name of the driver used to implements all specificities for a database engine. This can either be a shortclassname using plugin syntax, a fully namespaced name, or a constructed driver instance. Examples of shortclassnames are Mysql, Sqlite, Postgres, and Sqlserver.
persistent
Whether or not to use a persistent connection to the database. This option is not supported by SqlServer. As of
CakePHP version 3.4.13 an exception is thrown if you attempt to set persistent to true with SqlServer.
host
The database server’s hostname (or IP address).
username
The username for the account.
password
The password for the account.
database
The name of the database for this connection to use. Avoid using . in your database name. Because of how it
complicates identifier quoting CakePHP does not support . in database names. The path to your SQLite databaseshould be an absolute path (e.g. ROOT . DS . 'my_app.db') to avoid incorrect paths caused by relative paths.
port (optional)
The TCP port or Unix socket used to connect to the server.
encoding
Indicates the character set to use when sending SQL statements to the server. This defaults to the database’s
default encoding for all databases other than DB2.
timezoneServer timezone to set.
466

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

schemaUsed in PostgreSQL database setups to specify which schema to use.
unix_socket
Used by drivers that support it to connect via Unix socket files. If you are using PostgreSQL and want to use
Unix sockets, leave the host key blank.
ssl_key
The file path to the SSL key file. (Only supported by MySQL).
ssl_cert
The file path to the SSL certificate file. (Only supported by MySQL).
ssl_caThe file path to the SSL certificate authority. (Only supported by MySQL).
init
A list of queries that should be sent to the database server as when the connection is created.
log
Set to true to enable query logging. When enabled queries will be logged at a debug level with the queriesLog
scope.
quoteIdentifiers
Set to true if you are using reserved words or special characters in your table or column names. Enabling thissetting will result in queries built using the Query Builder having identifiers quoted when creating SQL. It should
be noted that this decreases performance because each query needs to be traversed and manipulated before being
executed.
flags
An associative array of PDO constants that should be passed to the underlying PDO instance. See the PDO
documentation for the flags supported by the driver you are using.
cacheMetadata
Either boolean true, or a string containing the cache configuration to store meta data in. Having metadata
caching disabled by setting it to false is not advised and can result in very poor performance. See the Metadata
Caching section for more information.
mask
Set the permissions on the generated database file. (Only supported by SQLite)At this point, you might want to take a look at the CakePHP Conventions. The correct naming for your tables (and the
addition of some columns) can score you some free functionality and help you avoid configuration. For example, if you
name your database table big_boxes, your table BigBoxesTable, and your controller BigBoxesController, everything
will work together automatically. By convention, use underscores, lower case, and plural forms for your database tablenames - for example: bakers, pastry_stores, and savory_cakes.
Managing Connectionsclass Cake\Datasource\ConnectionManager
The ConnectionManager class acts as a registry to access database connections your application has. It provides aplace that other objects can get references to existing connections.

More Information

467

CakePHP Book, Release 3.10

Accessing Connections
static Cake\Datasource\ConnectionManager::get($name)Once configured connections can be fetched using Cake\Datasource\ConnectionManager::get(). This method
will construct and load a connection if it has not been built before, or return the existing known connection:
use Cake\Datasource\ConnectionManager;$connection = ConnectionManager::get('default');
Attempting to load connections that do not exist will throw an exception.
Creating Connections at Runtime
Using config() and get() you can create new connections that are not defined in your configuration files at runtime:
ConnectionManager::config('my_connection', $config);$connection = ConnectionManager::get('my_connection');See the Configuration for more information on the configuration data used when creating connections.
Data Types
class Cake\Database\TypeSince not every database vendor includes the same set of data types, or the same names for similar data types, CakePHP
provides a set of abstracted data types for use with the database layer. The types CakePHP supports are:stringGenerally backed by CHAR or VARCHAR columns. Using the fixed option will force a CHAR column. In SQL
Server, NCHAR and NVARCHAR types are used.
text
Maps to TEXT types.
uuid
Maps to the UUID type if a database provides one, otherwise this will generate a CHAR(36) field.
binaryuuid
Maps to the UUID type if the database provides one, otherwise this will generate a BINARY(16) column
integer
Maps to the INTEGER type provided by the database. BIT is not yet supported at this moment.
smallinteger
Maps to the SMALLINT type provided by the database.
tinyinteger
Maps to the TINYINT or SMALLINT type provided by the database. In MySQL TINYINT(1) is treated as aboolean.
biginteger
Maps to the BIGINT type provided by the database.
float
Maps to either DOUBLE or FLOAT depending on the database. The precision option can be used to define theprecision used.
468

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

decimal
Maps to the DECIMAL type. Supports the length and precision options.
booleanMaps to BOOLEAN except in MySQL, where TINYINT(1) is used to represent booleans. BIT(1) is not yet
supported at this moment.
binaryMaps to the BLOB or BYTEA type provided by the database.
date
Maps to a timezone naive DATE column type. The return value of this column type is Cake\I18n\Date which
extends the native DateTime class.
datetime
Maps to a timezone naive DATETIME column type. In PostgreSQL, and SQL Server this turns into a TIMESTAMP
type. The default return value of this column type is Cake\I18n\Time which extends the built-in DateTimeclass and Chronos143 .
timestamp
Maps to the TIMESTAMP type.
time
Maps to a TIME type in all databases.
json
Maps to a JSON type if it’s available, otherwise it maps to TEXT. The ‘json’ type was added in 3.3.0
These types are used in both the schema reflection features that CakePHP provides, and schema generation features
CakePHP uses when using test fixtures.
Each type can also provide translation functions between PHP and SQL representations. These methods are invokedbased on the type hints provided when doing queries. For example a column that is marked as ‘datetime’ will automatically convert input parameters from DateTime instances into a timestamp or formatted datestrings. Likewise, ‘binary’columns will accept file handles, and generate file handles when reading data.
Changed in version 3.3.0: The json type was added.
Changed in version 3.5.0: The smallinteger and tinyinteger types were added.
Changed in version 3.6.0: The binaryuuid type was added.
Adding Custom Types
static Cake\Database\Type::map($name, $class)
If you need to use vendor specific types that are not built into CakePHP you can add additional new types to CakePHP’s
type system. Type classes are expected to implement the following methods:• toPHP: Casts given value from a database type to a PHP equivalent.
• toDatabase: Casts given value from a PHP type to one acceptable by a database.
• toStatement: Casts given value to its Statement equivalent.
• marshal: Marshals flat data into PHP objects.
An easy way to fulfill the basic interface is to extend Cake\Database\Type. For example if we wanted to add a JSON
type, we could make the following type class:
143 https://github.com/cakephp/chronos

More Information469

CakePHP Book, Release 3.10// in src/Database/Type/JsonType.php
namespace App\Database\Type;use Cake\Database\Driver;
use Cake\Database\Type;use PDO;class JsonType extends Type{public function toPHP($value, Driver $driver){
if ($value === null) {return null;}
return json_decode($value, true);}
public function marshal($value){
if (is_array($value) || $value === null) {return $value;}
return json_decode($value, true);}
public function toDatabase($value, Driver $driver){
return json_encode($value);}
public function toStatement($value, Driver $driver){
if ($value === null) {return PDO::PARAM_NULL;}
return PDO::PARAM_STR;}}
By default the toStatement() method will treat values as strings which will work for our new type. Once we’vecreated our new type, we need to add it into the type mapping. During our application bootstrap we should do thefollowing:
use Cake\Database\Type;
Type::map('json', 'App\Database\Type\JsonType');
New in version 3.3.0: The JsonType described in this example was added to the core.
We can then overload the reflected schema data to use our new type, and CakePHP’s database layer will automaticallyconvert our JSON data when creating queries. You can use the custom types you’ve created by mapping the types inyour Table’s _initializeSchema() method:

470

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

use Cake\Database\Schema\TableSchema;class WidgetsTable extends Table{
protected function _initializeSchema(TableSchema $schema){// Prior to 3.5.0 use columnType()$schema->setColumnType('widget_prefs', 'json');return $schema;}}

Mapping Custom Datatypes to SQL Expressions
New in version 3.3.0: Support for mapping custom data types to SQL expressions was added in 3.3.0.
The previous example maps a custom datatype for a ‘json’ column type which is easily represented as a string in a
SQL statement. Complex SQL data types cannot be represented as strings/integers in SQL queries. When working
with these datatypes your Type class needs to implement the Cake\Database\Type\ExpressionTypeInterface
interface. This interface lets your custom type represent a value as a SQL expression. As an example, we’ll build a
simple Type class for handling POINT type data out of MySQL. First we’ll define a ‘value’ object that we can use torepresent POINT data in PHP:// in src/Database/Point.php
namespace App\Database;// Our value object is immutable.
class Point{
protected $_lat;
protected $_long;// Factory method.
public static function parse($value){// Parse the data from MySQL.
return new static($value[0], $value[1]);}public function __construct($lat, $long){$this->_lat = $lat;$this->_long = $long;}
public function lat(){
return $this->_lat;}
public function long(){(continues on next page)

More Information

471

CakePHP Book, Release 3.10

(continued from previous page)

return $this->_long;}}
With our value object created, we’ll need a Type class to map data into this value object and into SQL expressions:namespace App\Database\Type;use App\Database\Point;
use Cake\Database\Expression\FunctionExpression;
use Cake\Database\Type as BaseType;use Cake\Database\Type\ExpressionTypeInterface;class PointType extends BaseType implements ExpressionTypeInterface{
public function toPHP($value, Driver $d){
return Point::parse($value);}
public function marshal($value){
if (is_string($value)) {$value = explode(',', $value);}if (is_array($value)) {return new Point($value[0], $value[1]);}return null;}public function toExpression($value){
if ($value instanceof Point) {return new FunctionExpression('POINT',[$value->lat(),$value->long()]);}
if (is_array($value)) {return new FunctionExpression('POINT', [$value[0], $value[1]]);}// Handle other cases.
}}
The above class does a few interesting things:• The toPHP method handles parsing the SQL query results into a value object.
• The marshal method handles converting, data such as given request data, into our value object. We’re going to
472

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

accept string values like '10.24,12.34 and arrays for now.
• The toExpression method handles converting our value object into the equivalent SQL expressions. In our
example the resulting SQL would be something like POINT(10.24, 12.34).
Once we’ve built our custom type, we’ll need to connect our type to our table class.
Enabling Immutable DateTime Objects
New in version 3.2: Immutable date/time objects were added in 3.2.
Because Date/Time objects are easily mutated in place, CakePHP allows you to enable immutable value objects. Thisis best done in your application’s config/bootstrap.php file:
Type::build('datetime')->useImmutable();Type::build('date')->useImmutable();Type::build('time')->useImmutable();Type::build('timestamp')->useImmutable();Note: New applications will have immutable objects enabled by default.

Connection Classes
class Cake\Database\Connection
Connection classes provide a simple interface to interact with database connections in a consistent way. They areintended as a more abstract interface to the driver layer and provide features for executing queries, logging queries, anddoing transactional operations.
Executing Queries
Cake\Database\Connection::query($sql)
Once you’ve gotten a connection object, you’ll probably want to issue some queries with it. CakePHP’s database
abstraction layer provides wrapper features on top of PDO and native drivers. These wrappers provide a similar interface
to PDO. There are a few different ways you can run queries depending on the type of query you need to run and whatkind of results you need back. The most basic method is query() which allows you to run already completed SQL
queries:$statement = $connection->query('UPDATE articles SET published = 1 WHERE id = 2');
Cake\Database\Connection::execute($sql, $params, $types)
The query() method does not allow for additional parameters. If you need additional parameters you should use theexecute() method, which allows for placeholders to be used:$statement = $connection->execute('UPDATE articles SET published = ? WHERE id = ?',[1, 2]);

More Information

473

CakePHP Book, Release 3.10

Without any type hinting information, execute will assume all placeholders are string values. If you need to bind
specific types of data, you can use their abstract type names when creating a query:$statement = $connection->execute('UPDATE articles SET published_date = ? WHERE id = ?',[new DateTime('now'), 2],['date', 'integer']);Cake\Database\Connection::newQuery()This allows you to use rich data types in your applications and properly convert them into SQL statements. The lastand most flexible way of creating queries is to use the Query Builder. This approach allows you to build complex and
expressive queries without having to use platform specific SQL:
$query = $connection->newQuery();$query->update('articles')->set(['published' => true])->where(['id' => 2]);$statement = $query->execute();When using the query builder, no SQL will be sent to the database server until the execute() method is called, or thequery is iterated. Iterating a query will first execute it and then start iterating over the result set:$query = $connection->newQuery();$query->select('*')->from('articles')->where(['published' => true]);
foreach ($query as $row) {// Do something with the row.
}

Note: When you have an instance of Cake\ORM\Query you can use all() to get the result set for SELECT queries.

Using Transactions
The connection objects provide you a few simple ways you do database transactions. The most basic way of doingtransactions is through the begin(), commit() and rollback() methods, which map to their SQL equivalents:$connection->begin();$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [true, 2]);$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [false, 4]);$connection->commit();Cake\Database\Connection::transactional(callable $callback)In addition to this interface connection instances also provide the transactional() method which makes handlingthe begin/commit/rollback calls much simpler:$connection->transactional(function ($connection) {$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [true, 2]);
(continues on next page)474

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [false, 4]);});
In addition to basic queries, you can execute more complex queries using either the Query Builder or Table Objects.
The transactional method will do the following:• Call begin.
• Call the provided closure.
• If the closure raises an exception, a rollback will be issued. The original exception will be re-thrown.
• If the closure returns false, a rollback will be issued.
• If the closure executes successfully, the transaction will be committed.
Interacting with Statements
When using the lower level database API, you will often encounter statement objects. These objects allow you tomanipulate the underlying prepared statement from the driver. After creating and executing a query object, or using execute() you will have a StatementDecorator instance. It wraps the underlying basic statement object andprovides a few additional features.
Preparing a Statement
You can create a statement object using execute(), or prepare(). The execute() method returns a statement withthe provided values bound to it. While prepare() returns an incomplete statement:// Statements from execute will have values bound to them already.
$statement = $connection->execute('SELECT * FROM articles WHERE published = ?',[true]);// Statements from prepare will be parameters for placeholders.
// You need to bind parameters before attempting to execute it.
$statement = $connection->prepare('SELECT * FROM articles WHERE published = ?');
Once you’ve prepared a statement you can bind additional data and execute it.
Binding Values
Once you’ve created a prepared statement, you may need to bind additional data. You can bind multiple values at once
using the bind() method, or bind individual elements using bindValue:$statement = $connection->prepare('SELECT * FROM articles WHERE published = ? AND created > ?');// Bind multiple values$statement->bind([true, new DateTime('2013-01-01')],(continues on next page)

More Information

475

CakePHP Book, Release 3.10

(continued from previous page)['boolean', 'date']);// Bind a single value$statement->bindValue(1, true, 'boolean');$statement->bindValue(2, new DateTime('2013-01-01'), 'date');When creating statements you can also use named array keys instead of positional ones:$statement = $connection->prepare('SELECT * FROM articles WHERE published = :published AND created > :created');// Bind multiple values$statement->bind(['published' => true, 'created' => new DateTime('2013-01-01')],['published' => 'boolean', 'created' => 'date']);// Bind a single value$statement->bindValue('published', true, 'boolean');$statement->bindValue('created', new DateTime('2013-01-01'), 'date');Warning: You cannot mix positional and named array keys in the same statement.

Executing & Fetching Rows
After preparing a statement and binding data to it, you can execute it and fetch rows. Statements should be executedusing the execute() method. Once executed, results can be fetched using fetch(), fetchAll() or iterating thestatement:$statement->execute();// Read one row.
$row = $statement->fetch('assoc');// Read all rows.
$rows = $statement->fetchAll('assoc');// Read rows through iteration.
foreach ($statement as $row) {// Do work}

Note: Reading rows through iteration will fetch rows in ‘both’ mode. This means you will get both the numericallyindexed and associatively indexed results.

476

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Getting Row Counts
After executing a statement, you can fetch the number of affected rows:$rowCount = count($statement);$rowCount = $statement->rowCount();

Checking Error Codes
If your query was not successful, you can get related error information using the errorCode() and errorInfo()
methods. These methods work the same way as the ones provided by PDO:
$code = $statement->errorCode();$info = $statement->errorInfo();Query Logging
Query logging can be enabled when configuring your connection by setting the log option to true. You can also
toggle query logging at runtime, using enableQueryLogging:// Prior to 3.7.0 use logQueries()// Turn query logging on.
$connection->enableQueryLogging(true);// Turn query logging off$connection->enableQueryLogging(false);
When query logging is enabled, queries will be logged to Cake\Log\Log using the ‘debug’ level, and the ‘queriesLog’
scope. You will need to have a logger configured to capture this level & scope. Logging to stderr can be useful whenworking on unit tests, and logging to files/syslog can be useful when working with web requests:
use Cake\Log\Log;// Console logging
Log::config('queries', ['className' => 'Console','stream' => 'php://stderr','scopes' => ['queriesLog']]);// File logging
Log::config('queries', ['className' => 'File','path' => LOGS,'file' => 'queries.log','scopes' => ['queriesLog']]);

Note: Query logging is only intended for debugging/development uses. You should never leave query logging on in
production as it will negatively impact the performance of your application.

More Information

477

CakePHP Book, Release 3.10

Identifier Quoting
By default CakePHP does not quote identifiers in generated SQL queries. The reason for this is identifier quoting has
a few drawbacks:• Performance overhead - Quoting identifiers is much slower and complex than not doing it.
• Not necessary in most cases - In non-legacy databases that follow CakePHP’s conventions there is no reason toquote identifiers.
If you are using a legacy schema that requires identifier quoting you can enable it using the quoteIdentifiers setting
in your Configuration. You can also enable this feature at runtime:$connection->getDriver()->enableAutoQuoting();
When enabled, identifier quoting will cause additional query traversal that converts all identifiers into
IdentifierExpression objects.
Note: SQL snippets contained in QueryExpression objects will not be modified.

Metadata Caching
CakePHP’s ORM uses database reflection to determine the schema, indexes and foreign keys your application contains. Because this metadata changes infrequently and can be expensive to access, it is typically cached. By default,
metadata is stored in the _cake_model_ cache configuration. You can define a custom cache configuration using thecacheMetatdata option in your datasource configuration:'Datasources' => ['default' => [// Other keys go here.
// Use the 'orm_metadata' cache config for metadata.
'cacheMetadata' => 'orm_metadata',]],
You can also configure the metadata caching at runtime with the cacheMetadata() method:// Disable the cache$connection->cacheMetadata(false);// Enable the cache$connection->cacheMetadata(true);// Use a custom cache config$connection->cacheMetadata('orm_metadata');
CakePHP also includes a CLI tool for managing metadata caches. See the Schema Cache Shell chapter for more
information.

478

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Creating Databases
If you want to create a connection without selecting a database you can omit the database name:$dsn = 'mysql://root:password@localhost/';You can now use your connection object to execute queries that create/modify databases. For example to create a
database:$connection->query("CREATE DATABASE IF NOT EXISTS my_database");Note: When creating a database it is a good idea to set the character set and collation parameters. If these values are
missing, the database will set whatever system default values it uses.

Query Builder
class Cake\ORM\QueryThe ORM’s query builder provides a simple to use fluent interface for creating and running queries. By composing
queries together, you can create advanced queries using unions and subqueries with ease.
Underneath the covers, the query builder uses PDO prepared statements which protect against SQL injection attacks.
The Query Object
The easiest way to create a Query object is to use find() from a Table object. This method will return an incomplete
query ready to be modified. You can also use a table’s connection object to access the lower level Query builder that
does not include ORM features, if necessary. See the Executing Queries section for more information:
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');// Start a new query.
$query = $articles->find();
When inside a controller, you can use the automatic table variable that is created using the conventions system:// Inside ArticlesController.php$query = $this->Articles->find();More Information

479

CakePHP Book, Release 3.10

Selecting Rows From A Table
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$query = TableRegistry::getTableLocator()->get('Articles')->find();foreach ($query as $article) {debug($article->title);}
For the remaining examples, assume that $articles is a Table.
$this->Articles instead of $articles.

When inside controllers, you can use

Almost every method in a Query object will return the same query, this means that Query objects are lazy, and will
not be executed unless you tell them to:$query->where(['id' => 1]); // Return the same query object$query->order(['title' => 'DESC']); // Still same object, no SQL executed
You can of course chain the methods you call on Query objects:$query = $articles->find()->select(['id', 'name'])->where(['id !=' => 1])->order(['created' => 'DESC']);
foreach ($query as $article) {debug($article->created);}
If you try to call debug() on a Query object, you will see its internal state and the SQL that will be executed in the
database:debug($articles->find()->where(['id' => 1]));// Outputs// ...
// 'sql' => 'SELECT * FROM articles where id = ?'// ...
You can execute a query directly without having to use foreach on it. The easiest way is to either call the all() or
toList() methods:$resultsIteratorObject = $articles->find()->where(['id >' => 1])->all();
foreach ($resultsIteratorObject as $article) {debug($article->id);}(continues on next page)

480

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$resultsArray = $articles->find()->where(['id >' => 1])->toList();foreach ($resultsArray as $article) {debug($article->id);}debug($resultsArray[0]->title);
In the above example, $resultsIteratorObject will be an instance of Cake\ORM\ResultSet, an object you caniterate and apply several extracting and traversing methods on.
Often, there is no need to call all(), you can simply iterate the Query object to get its results. Query objects can also
be used directly as the result object; trying to iterate the query, calling toList() or some of the methods inheritedfrom Collection, will result in the query being executed and results returned to you.
Selecting A Single Row From A Table
You can use the first() method to get the first result in the query:$article = $articles->find()->where(['id' => 1])->first();debug($article->title);

Getting A List Of Values From A Column// Use the extract() method from the collections library// This executes the query as well
$allTitles = $articles->find()->extract('title');foreach ($allTitles as $title) {echo $title;}
You can also get a key-value list out of a query result:$list = $articles->find('list');foreach ($list as $id => $title) {echo "$id : $title"}
For more information on how to customize the fields used for populating the list refer to Finding Key/Value Pairs
section.

More Information

481

CakePHP Book, Release 3.10

Queries Are Collection Objects
Once you get familiar with the Query object methods, it is strongly encouraged that you visit the Collection section to
improve your skills in efficiently traversing the data. In short, it is important to remember that anything you can call on
a Collection object, you can also do in a Query object:// Use the combine() method from the collections library// This is equivalent to find('list')$keyValueList = $articles->find()->combine('id', 'title');// An advanced example$results = $articles->find()->where(['id >' => 1])->order(['title' => 'DESC'])->map(function ($row) { // map() is a collection method, it executes the query$row->trimmedTitle = trim($row->title);
return $row;})->combine('id', 'trimmedTitle') // combine() is another collection method->toArray(); // Also a collections library method
foreach ($results as $id => $trimmedTitle) {echo "$id : $trimmedTitle";}

Queries Are Lazily EvaluatedQuery objects are lazily evaluated. This means a query is not executed until one of the following things occur:• The query is iterated with foreach().
• The query’s execute() method is called. This will return the underlying statement object, and is to be usedwith insert/update/delete queries.
• The query’s first() method is called. This will return the first result in the set built by SELECT (it adds LIMIT
1 to the query).
• The query’s all() method is called. This will return the result set and can only be used with SELECT statements.
• The query’s toList() or toArray() method is called.
Until one of these conditions are met, the query can be modified without additional SQL being sent to the database. It
also means that if a Query hasn’t been evaluated, no SQL is ever sent to the database. Once executed, modifying andre-evaluating a query will result in additional SQL being run.
If you want to take a look at what SQL CakePHP is generating, you can turn database query logging on.

482

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Selecting Data
CakePHP makes building SELECT queries simple. To limit the fields fetched, you can use the select() method:$query = $articles->find();$query->select(['id', 'title', 'body']);foreach ($query as $row) {debug($row->title);}
You can set aliases for fields by providing fields as an associative array:// Results in SELECT id AS pk, title AS aliased_title, body ...
$query = $articles->find();$query->select(['pk' => 'id', 'aliased_title' => 'title', 'body']);To select distinct fields, you can use the distinct() method:// Results in SELECT DISTINCT country FROM ...
$query = $articles->find();$query->select(['country'])->distinct(['country']);To set some basic conditions you can use the where() method:// Conditions are combined with AND$query = $articles->find();$query->where(['title' => 'First Post', 'published' => true]);// You can call where() multiple times$query = $articles->find();$query->where(['title' => 'First Post'])->where(['published' => true]);
You can also pass an anonymous function to the where() method. The passed anonymous function will receive an
instance of \Cake\Database\Expression\QueryExpression as its first argument, and \Cake\ORM\Query as its
second:$query = $articles->find();$query->where(function (QueryExpression $exp, Query $q) {return $exp->eq('published', true);});
See the Advanced Conditions section to find out how to construct more complex WHERE conditions.

More Information

483

CakePHP Book, Release 3.10

Selecting Specific Fields
By default a query will select all fields from a table, the exception is when you call the select() function yourself
and pass certain fields:// Only select id and title from the articles table$articles->find()->select(['id', 'title']);If you wish to still select all fields from a table after having called select($fields), you can pass the table instanceto select() for this purpose:// Only all fields from the articles table including// a calculated slug field.
$query = $articlesTable->find();$query->select(['slug' => $query->func()->concat(['title' => 'identifier', '-', 'id' =>˓→'identifier'])])->select($articlesTable); // Select all fields from articles
New in version 3.1: Passing a table object to select() was added in 3.1.
If you want to select all but a few fields on a table, you can use selectAllExcept():$query = $articlesTable->find();// Get all fields except the published field.
$query->selectAllExcept($articlesTable, ['published']);You can also pass an Association object when working with contained associations.
New in version 3.6.0: The selectAllExcept() method was added.
Using SQL Functions
CakePHP’s ORM offers abstraction for some commonly used SQL functions. Using the abstraction allows the ORM to
select the platform specific implementation of the function you want. For example, concat is implemented differently
in MySQL, PostgreSQL and SQL Server. Using the abstraction allows your code to be portable:// Results in SELECT COUNT(*) count FROM ...
$query = $articles->find();$query->select(['count' => $query->func()->count('*')]);
A number of commonly used functions can be created with the func() method:rand()
Generate a random value between 0 and 1 via SQL.
sum()
Calculate a sum. Assumes arguments are literal values.
avg()
Calculate an average. Assumes arguments are literal values.
min()
Calculate the min of a column. Assumes arguments are literal values.

484

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

max()
Calculate the max of a column. Assumes arguments are literal values.
count()
Calculate the count. Assumes arguments are literal values.
concat()Concatenate two values together. Assumes arguments are bound parameters.
coalesce()
Coalesce values. Assumes arguments are bound parameters.
dateDiff()
Get the difference between two dates/times. Assumes arguments are bound parameters.
now()
Defaults to returning date and time, but accepts ‘time’ or ‘date’ to return only those values.
extract()
Returns the specified date part from the SQL expression.
dateAdd()
Add the time unit to the date expression.
dayOfWeek()
Returns a FunctionExpression representing a call to SQL WEEKDAY function.
New in version 3.1: extract(), dateAdd() and dayOfWeek() methods have been added.
New in version 3.7: rand() was added.
Function Arguments
SQL functions called through func() can accept SQL identifiers, literal values, bound parameters or other
ExpressionInterface instances as arguments:$query = $articles->find()->innerJoinWith('Categories');$concat = $query->func()->concat(['Articles.title' => 'identifier',' - CAT: ','Categories.name' => 'identifier',' - Age: ',$query->func()->dateDiff(['NOW()' => 'literal','Articles.created' => 'identifier'])]);$query->select(['link_title' => $concat]);Both literal and identifier arguments allow you to reference other columns and SQL literals while identifier
will be appropriately quoted if auto-quoting is enabled. If not marked as literal or identifier, arguments will be boundparameters allowing you to safely pass user data to the function.
The above example generates something like this in MYSQL.
SELECT CONCAT(
Articles.title,:c0,(continues on next page)

More Information

485

CakePHP Book, Release 3.10

(continued from previous page)

Categories.name,:c1,(DATEDIFF(NOW(), Articles.created))) FROM articles;
The :c0 argument will have ' - CAT:' text bound when the query is executed. The dateDiff expression was translated to the appropriate SQL.
Custom Functions
If func() does not already wrap the SQL function you need, you can call it directly through func() and still safely
pass arguments and user data as described. Make sure you pass the appropriate argument type for custom functions or
they will be treated as bound parameters:$query = $articles->find();$year = $query->func()->year(['created' => 'identifier']);$time = $query->func()->date_format(['created' => 'identifier',"'%H:%i'" => 'literal']);$query->select(['yearCreated' => $year,'timeCreated' => $time]);
These custom function would generate something like this in MYSQL:SELECT YEAR(created) as yearCreated,
DATE_FORMAT(created, '%H:%i') as timeCreated
FROM articles;

Note: Use func() to pass untrusted user data to any SQL function.

Ordering Results
To apply ordering, you can use the order method:$query = $articles->find()->order(['title' => 'ASC', 'id' => 'ASC']);When calling order() multiple times on a query, multiple clauses will be appended. However, when using finders
you may sometimes need to overwrite the ORDER BY. Set the second parameter of order() (as well as orderAsc()or orderDesc()) to Query::OVERWRITE or to true:$query = $articles->find()->order(['title' => 'ASC']);// Later, overwrite the ORDER BY clause instead of appending to it.
(continues on next page)

486

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$query = $articles->find()->order(['created' => 'DESC'], Query::OVERWRITE);
The orderAsc and orderDesc methods can be used when you need to sort on complex expressions:$query = $articles->find();$concat = $query->func()->concat(['title' => 'identifier','synopsis' => 'identifier']);$query->orderAsc($concat);To build complex order clauses, use a Closure to build order expressions:$query->orderAsc(function (QueryExpression $exp, Query $query) {return $exp->addCase(...);});New in version 3.9.0: Using a closure with orderDesc and orderAsc was added in 3.9.0.
Limiting Results
To limit the number of rows or set the row offset you can use the limit() and page() methods:// Fetch rows 50 to 100$query = $articles->find()->limit(50)->page(2);As you can see from the examples above, all the methods that modify the query provide a fluent interface, allowing you
to build a query through chained method calls.
Aggregates - Group and Having
When using aggregate functions like count and sum you may want to use group by and having clauses:$query = $articles->find();$query->select(['count' => $query->func()->count('view_count'),'published_date' => 'DATE(created)'])->group('published_date')->having(['count >' => 3]);More Information

487

CakePHP Book, Release 3.10

Case Statements
The ORM also offers the SQL case expression. The case expression allows for implementing if ... then ...
else logic inside your SQL. This can be useful for reporting on data where you need to conditionally sum or countdata, or where you need to specific data based on a condition.
If we wished to know how many published articles are in our database, we could use the following SQL:
SELECT
COUNT(CASE WHEN published = 'Y' THEN 1 END) AS number_published,
COUNT(CASE WHEN published = 'N' THEN 1 END) AS number_unpublished
FROM articles
To do this with the query builder, we’d use the following code:$query = $articles->find();$publishedCase = $query->newExpr()->addCase($query->newExpr()->add(['published' => 'Y']),1,'integer');$unpublishedCase = $query->newExpr()->addCase($query->newExpr()->add(['published' => 'N']),1,'integer');$query->select(['number_published' => $query->func()->count($publishedCase),'number_unpublished' => $query->func()->count($unpublishedCase)]);
The addCase function can also chain together multiple statements to create if .. then .. [elseif .. then ..
] [ .. else ] logic inside your SQL.
If we wanted to classify cities into SMALL, MEDIUM, or LARGE based on population size, we could do the following:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->addCase([$q->newExpr()->lt('population', 100000),$q->newExpr()->between('population', 100000, 999000),$q->newExpr()->gte('population', 999001),],['SMALL', 'MEDIUM', 'LARGE'], # values matching conditions['string', 'string', 'string'] # type of each value);});# WHERE CASE#
WHEN population < 100000 THEN 'SMALL'#
WHEN population BETWEEN 100000 AND 999000 THEN 'MEDIUM'(continues on next page)

488

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)##

WHEN population >= 999001 THEN 'LARGE'
END

Any time there are fewer case conditions than values, addCase will automatically produce an if .. then .. elsestatement:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->addCase([$q->newExpr()->eq('population', 0),],['DESERTED', 'INHABITED'], # values matching conditions['string', 'string'] # type of each value);});# WHERE CASE#
WHEN population = 0 THEN 'DESERTED' ELSE 'INHABITED' END

Fetching Arrays Instead of Entities
While ORMs and object result sets are powerful, creating entities is sometimes unnecessary. For example, whenaccessing aggregated data, building an Entity may not make sense. The process of converting the database results toentities is called hydration. If you wish to disable this process you can do this:$query = $articles->find();$query->enableHydration(false); // Results as arrays instead of entities$result = $query->toList(); // Execute the query and return the array
After executing those lines, your result should look similar to this:[['id' => 1, 'title' => 'First Article', 'body' => 'Article 1 body' ...],['id' => 2, 'title' => 'Second Article', 'body' => 'Article 2 body' ...],...
]

Adding Calculated Fields
After your queries, you may need to do some post-processing. If you need to add a few calculated fields or derived
data, you can use the formatResults() method. This is a lightweight way to map over the result sets. If you needmore control over the process, or want to reduce results you should use the Map/Reduce feature instead. If you werequerying a list of people, you could calculate their age with a result formatter:// Assuming we have built the fields, conditions and containments.
$query->formatResults(function (\Cake\Collection\CollectionInterface $results) {return $results->map(function ($row) {$row['age'] = $row['birth_date']->diff(new \DateTime)->y;return $row;(continues on next page)

More Information489

CakePHP Book, Release 3.10

(continued from previous page)});});As you can see in the example above, formatting callbacks will get a ResultSetDecorator as their first argument. The
second argument will be the Query instance the formatter was attached to. The $results argument can be traversed
and modified as necessary.
Result formatters are required to return an iterator object, which will be used as the return value for the query. Formatterfunctions are applied after all the Map/Reduce routines have been executed. Result formatters can be applied fromwithin contained associations as well. CakePHP will ensure that your formatters are properly scoped. For example,
doing the following would work as you may expect:// In a method in the Articles table$query->contain(['Authors' => function ($q) {return $q->formatResults(function (\Cake\Collection\CollectionInterface $authors) {return $authors->map(function ($author) {$author['age'] = $author['birth_date']->diff(new \DateTime)->y;return $author;
});
});
}]);
// Get results$results = $query->all();// Outputs 29
echo $results->first()->author->age;
As seen above, the formatters attached to associated query builders are scoped to operate only on the data in theassociation. CakePHP will ensure that computed values are inserted into the correct entity.
Advanced Conditions
The query builder makes it simple to build complex where clauses. Grouped conditions can be expressed by providing
combining where() and expression objects. For simple queries, you can build conditions using an array of conditions:$query = $articles->find()->where(['author_id' => 3,'OR' => [['view_count' => 2], ['view_count' => 3]],]);
The above would generate SQL like:
SELECT * FROM articles WHERE author_id = 3 AND (view_count = 2 OR view_count = 3)
Deprecated since version 3.5.0: Query::orWhere() creates hard to predict SQL based on the current query state. Use
Query::where() instead as it has more predictable and easier to understand behavior.
If you’d prefer to avoid deeply nested arrays, you can use the callback form of where() to build your queries. The
callback accepts a QueryExpression which allows you to use the expression builder interface to build more complex
conditions without arrays. For example:

490

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

$query = $articles->find()->where(function (QueryExpression $exp, Query $query) {// Use add() to add multiple conditions for the same field.
$author = $query->newExpr()->or(['author_id' => 3])->add(['author_id' => 2]);
$published = $query->newExpr()->and(['published' => true, 'view_count' => 10]);return $exp->or(['promoted' => true,$query->newExpr()->and([$author, $published])]);});
The above generates SQL similar to:
SELECT *FROM articles
WHERE ((
(author_id = 2 OR author_id = 3)AND(published = 1 AND view_count > 10))
OR promoted = 1)
The QueryExpression passed to the callback allows you to use both combinators and conditions to build the full
expression.
Combinators
These create new QueryExpression objects and set how the conditions added to that expression are joined
together.
• and() creates new expression objects that joins all conditions with AND.
• or() creates new expression objects that joins all conditions with OR.
Conditions
These are added to the expression and automatically joined together depending on which combinator was used.
The QueryExpression passed to the callback function defaults to and():$query = $articles->find()->where(function (QueryExpression $exp) {return $exp->eq('author_id', 2)->eq('published', true)->notEq('spam', true)->gt('view_count', 10);});In this example, the conditions eq, notEq and gt are joined together by AND:
SELECT *FROM articles
WHERE (
author_id = 2
AND published = 1(continues on next page)

More Information

491

CakePHP Book, Release 3.10

(continued from previous page)

AND spam != 1
AND view_count > 10)
You can build an expression with multiple combinators by using the add condition:$query = $articles->find()->where(function (QueryExpression $exp) {$orConditions = $exp->or(['author_id' => 2])->eq('author_id', 5);return $exp->add($orConditions)->eq('published', true)->gte('view_count', 10);});Which would generate the SQL similar to:
SELECT *FROM articles
WHERE (
(author_id = 2 OR author_id = 5)
AND published = 1
AND view_count >= 10)
The combinators also allow you pass in a callback which takes the new expression object as a parameter if you want
to separate the method chaining:$query = $articles->find()->where(function (QueryExpression $exp) {$orConditions = $exp->or(function (QueryExpression $or) {return $or->eq('author_id', 2)->eq('author_id', 5);});return $exp->not($orConditions)->lte('view_count', 10);});You can negate sub-expressions using not():$query = $articles->find()->where(function (QueryExpression $exp) {$orConditions = $exp->or(['author_id' => 2])->eq('author_id', 5);return $exp->not($orConditions)->lte('view_count', 10);});Which will generate the following SQL looking like:

492

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

SELECT *FROM articles
WHERE (NOT (author_id = 2 OR author_id = 5)
AND view_count <= 10)
It is also possible to build expressions using SQL functions:$query = $articles->find()->where(function (QueryExpression $exp, Query $q) {$year = $q->func()->year(['created' => 'identifier']);return $exp->gte($year, 2014)->eq('published', true);});
Which will generate the following SQL looking like:
SELECT *FROM articles
WHERE (YEAR(created) >= 2014
AND published = 1)
When using the expression objects you can use the following methods to create conditions:• eq() Creates an equality condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->eq('population', '10000');});# WHERE population = 10000• notEq() Creates an inequality condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->notEq('population', '10000');});# WHERE population != 10000• like() Creates a condition using the LIKE operator:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->like('name', '%A%');});# WHERE name LIKE "%A%"• notLike() Creates a negated LIKE condition:
More Information

493

CakePHP Book, Release 3.10

$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->notLike('name', '%A%');});# WHERE name NOT LIKE "%A%"• in() Create a condition using IN:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->in('country_id', ['AFG', 'USA', 'EST']);});# WHERE country_id IN ('AFG', 'USA', 'EST')• notIn() Create a negated condition using IN:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->notIn('country_id', ['AFG', 'USA', 'EST']);});# WHERE country_id NOT IN ('AFG', 'USA', 'EST')• gt() Create a > condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->gt('population', '10000');});# WHERE population > 10000• gte() Create a >= condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->gte('population', '10000');});# WHERE population >= 10000• lt() Create a < condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->lt('population', '10000');});# WHERE population < 10000• lte() Create a <= condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->lte('population', '10000');});# WHERE population <= 10000• isNull() Create an IS NULL condition:
494

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->isNull('population');});# WHERE (population) IS NULL
• isNotNull() Create a negated IS NULL condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->isNotNull('population');});# WHERE (population) IS NOT NULL
• between() Create a BETWEEN condition:$query = $cities->find()->where(function (QueryExpression $exp, Query $q) {return $exp->between('population', 999, 5000000);});# WHERE population BETWEEN 999 AND 5000000,• exists() Create a condition using EXISTS:$subquery = $cities->find()->select(['id'])->where(function (QueryExpression $exp, Query $q) {return $exp->equalFields('countries.id', 'cities.country_id');})->andWhere(['population >' => 5000000]);$query = $countries->find()->where(function (QueryExpression $exp, Query $q) use ($subquery) {return $exp->exists($subquery);});# WHERE EXISTS (SELECT id FROM cities WHERE countries.id = cities.country_id AND␣˓→population > 5000000)• notExists() Create a negated condition using EXISTS:$subquery = $cities->find()->select(['id'])->where(function (QueryExpression $exp, Query $q) {return $exp->equalFields('countries.id', 'cities.country_id');})->andWhere(['population >' => 5000000]);$query = $countries->find()->where(function (QueryExpression $exp, Query $q) use ($subquery) {return $exp->notExists($subquery);});# WHERE NOT EXISTS (SELECT id FROM cities WHERE countries.id = cities.country_id␣
˓→AND population > 5000000)

More Information

495

CakePHP Book, Release 3.10

In situations when you can’t get, or don’t want to use the builder methods to create the conditions you want you canalso use snippets of SQL in where clauses:// Compare two fields to each other$query->where(['Categories.parent_id != Parents.id']);Warning: The field names used in expressions, and SQL snippets should never contain untrusted content. See
the Using SQL Functions section for how to safely include unsafe data into function calls.

Using Identifiers in Expressions
When you need to reference a column or SQL identifier in your queries you can use the identifier() method:$query = $countries->find();$query->select(['year' => $query->func()->year([$query->identifier('created')])])->where(function ($exp, $query) {return $exp->gt('population', 100000);});
You can use identifier() in comparisons to aggregations too:$query = $this->Orders->find();$query->select(['Customers.customer_name', 'total_orders' => $query->func()->count(
˓→'Orders.order_id')])->contain('Customers')->group(['Customers.customer_name'])->having(['total_orders >=' => $query->identifier('Customers.minimum_order_count')]);

Warning: To prevent SQL injections, Identifier expressions should never have untrusted data passed into them.
New in version 3.6.0: Query::identifier() was added in 3.6.0
Automatically Creating IN Clauses
When building queries using the ORM, you will generally not have to indicate the data types of the columns you areinteracting with, as CakePHP can infer the types based on the schema data. If in your queries you’d like CakePHP toautomatically convert equality to IN comparisons, you’ll need to indicate the column data type:$query = $articles->find()->where(['id' => $ids], ['id' => 'integer[]']);// Or include IN to automatically cast to an array.
$query = $articles->find()->where(['id IN' => $ids]);
The above will automatically create id IN (...) instead of id = ?. This can be useful when you do not knowwhether you will get a scalar or array of parameters. The [] suffix on any data type name indicates to the query builder
496

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

that you want the data handled as an array. If the data is not an array, it will first be cast to an array. After that, eachvalue in the array will be cast using the type system. This works with complex types as well. For example, you could
take a list of DateTime objects using:$query = $articles->find()->where(['post_date' => $dates], ['post_date' => 'date[]']);

Automatic IS NULL Creation
When a condition value is expected to be null or any other value, you can use the IS operator to automatically create
the correct expression:$query = $categories->find()->where(['parent_id IS' => $parentId]);
The above will create parent_id` = :c1 or parent_id IS NULL depending on the type of $parentId
Automatic IS NOT NULL Creation
When a condition value is expected not to be null or any other value, you can use the IS NOT operator to automaticallycreate the correct expression:$query = $categories->find()->where(['parent_id IS NOT' => $parentId]);
The above will create parent_id` != :c1 or parent_id IS NOT NULL depending on the type of $parentId
Raw Expressions
When you cannot construct the SQL you need using the query builder, you can use expression objects to add snippets
of SQL to your queries:$query = $articles->find();$expr = $query->newExpr()->add('1 + 1');$query->select(['two' => $expr]);Expression objects can be used with any query builder methods like where(), limit(), group(), select() andmany other methods.
Warning: Using expression objects leaves you vulnerable to SQL injection. You should never use untrusted data
into expressions.

More Information

497

CakePHP Book, Release 3.10

Getting Results
Once you’ve made your query, you’ll want to retrieve rows from it. There are a few ways of doing this:// Iterate the query
foreach ($query as $row) {// Do stuff.
}// Get the results$results = $query->all();
You can use any of the collection methods on your query objects to pre-process or transform the results:// Use one of the collection methods.
$ids = $query->map(function ($row) {return $row->id;});$maxAge = $query->max(function ($max) {return $max->age;});
You can use first or firstOrFail to retrieve a single record. These methods will alter the query adding a LIMIT 1
clause:// Get just the first row$row = $query->first();// Get the first row or an exception.
$row = $query->firstOrFail();

Returning the Total Count of Records
Using a single query object, it is possible to obtain the total number of rows found for a set of conditions:$total = $articles->find()->where(['is_active' => true])->count();
The count() method will ignore the limit, offset and page clauses, thus the following will return the same result:$total = $articles->find()->where(['is_active' => true])->limit(10)->count();
This is useful when you need to know the total result set size in advance, without having to construct another Queryobject. Likewise, all result formatting and map-reduce routines are ignored when using the count() method.
Moreover, it is possible to return the total count for a query containing group by clauses without having to rewrite thequery in any way. For example, consider this query for retrieving article ids and their comments count:$query = $articles->find();$query->select(['Articles.id', $query->func()->count('Comments.id')])->matching('Comments')->group(['Articles.id']);$total = $query->count();

498

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

After counting, the query can still be used for fetching the associated records:$list = $query->all();
Sometimes, you may want to provide an alternate method for counting the total records of a query. One common
use case for this is providing a cached value or an estimate of the total rows, or to alter the query to remove expensive
unneeded parts such as left joins. This becomes particularly handy when using the CakePHP built-in pagination system
which calls the count() method:$query = $query->where(['is_active' => true])->counter(function ($query) {return 100000;});$query->count(); // Returns 100000
In the example above, when the pagination component calls the count method, it will receive the estimated hard-codednumber of rows.
Caching Loaded Results
When fetching entities that don’t change often you may want to cache the results. The Query class makes this simple:$query->cache('recent_articles');Will enable caching on the query’s result set. If only one argument is provided to cache() then the ‘default’ cacheconfiguration will be used. You can control which caching configuration is used with the second parameter:// String config name.
$query->cache('recent_articles', 'dbResults');// Instance of CacheEngine$query->cache('recent_articles', $memcache);In addition to supporting static keys, the cache() method accepts a function to generate the key. The function you give
it will receive the query as an argument. You can then read aspects of the query to dynamically generate the cache key:// Generate a key based on a simple checksum// of the query's where clause$query->cache(function ($q) {return 'articles-' . md5(serialize($q->clause('where')));});
The cache method makes it simple to add cached results to your custom finders or through event listeners.
When the results for a cached query are fetched the following happens:
1. The Model.beforeFind event is triggered.
2. If the query has results set, those will be returned.
3. The cache key will be resolved and cache data will be read. If the cache data is not empty, those results will be
returned.
4. If the cache misses, the query will be executed and a new ResultSet will be created. This ResultSet will be
written to the cache and returned.

More Information

499

CakePHP Book, Release 3.10

Note: You cannot cache a streaming query result.

Loading Associations
The builder can help you retrieve data from multiple tables at the same time with the minimum amount of queries
possible. To be able to fetch associated data, you first need to setup associations between the tables as described in
the Associations - Linking Tables Together section. This technique of combining queries to fetch associated data fromother tables is called eager loading.
Eager loading helps avoid many of the potential performance problems surrounding lazy-loading in an ORM. The
queries generated by eager loading can better leverage joins, allowing more efficient queries to be made. In CakePHP
you define eager loaded associations using the ‘contain’ method:// In a controller or table method.
// As an option to find()$query = $articles->find('all', ['contain' => ['Authors', 'Comments']]);// As a method on the query object$query = $articles->find('all');$query->contain(['Authors', 'Comments']);
The above will load the related author and comments for each article in the result set. You can load nested associations
using nested arrays to define the associations to be loaded:$query = $articles->find()->contain(['Authors' => ['Addresses'], 'Comments' => ['Authors']]);
Alternatively, you can express nested associations using the dot notation:$query = $articles->find()->contain(['Authors.Addresses','Comments.Authors']);
You can eager load associations as deep as you like:$query = $products->find()->contain(['Shops.Cities.Countries','Shops.Managers']);
You can select fields from all associations with multiple easy contain() statements:$query = $this->find()->select(['Realestates.id','Realestates.title','Realestates.description'])->contain(['RealestateAttributes' => [(continues on next page)

500

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'Attributes' => ['fields' => [// Aliased fields in contain() must include// the model prefix to be mapped correctly.
'Attributes__name' => 'attr_name']]]])->contain(['RealestateAttributes' => ['fields' => ['RealestateAttributes.realestate_id','RealestateAttributes.value']]])->where($condition);
If you need to reset the containments on a query you can set the second argument to true:$query = $articles->find();$query->contain(['Authors', 'Comments'], true);

Passing Conditions to Contain
When using contain() you are able to restrict the data returned by the associations and filter them by conditions. To
specify conditions, pass an anonymous function that receives as the first argument a query object, \Cake\ORM\Query:// In a controller or table method.
// Prior to 3.5.0 you would use contain(['Comments' => function () { ... }])$query = $articles->find()->contain('Comments', function (Query $q) {return $q->select(['body', 'author_id'])->where(['Comments.approved' => true]);});
This also works for pagination at the Controller level:$this->paginate['contain'] = ['Comments' => function (Query $query) {return $query->select(['body', 'author_id'])->where(['Comments.approved' => true]);}];

Note: When you limit the fields that are fetched from an association, you must ensure that the foreign key columns
are selected. Failing to select foreign key fields will cause associated data to not be present in the final result.
It is also possible to restrict deeply-nested associations using the dot notation:
More Information

501

CakePHP Book, Release 3.10

$query = $articles->find()->contain(['Comments','Authors.Profiles' => function (Query $q) {return $q->where(['Profiles.is_published' => true]);}]);
In the above example, you’ll still get authors even if they don’t have a published profile. To only get authors with apublished profile use matching(). If you have defined custom finders in your associations, you can use them insidecontain():// Bring all articles, but only bring the comments that are approved and// popular.
$query = $articles->find()->contain('Comments', function (Query $q) {return $q->find('approved')->find('popular');});

Note: For BelongsTo and HasOne associations only the where and select clauses are used when loading theassociated records. For the rest of the association types you can use every clause that the query object provides.
If you need full control over the query that is generated, you can tell contain() to not append the foreignKey
constraints to the generated query. In that case you should use an array passing foreignKey and queryBuilder:$query = $articles->find()->contain(['Authors' => ['foreignKey' => false,'queryBuilder' => function (Query $q) {return $q->where(...); // Full conditions for filtering}]]);
If you have limited the fields you are loading with select() but also want to load fields off of contained associations,
you can pass the association object to select():// Select id & title from articles, but all fields off of Users.
$query = $articles->find()->select(['id', 'title'])->select($articles->Users)->contain(['Users']);Alternatively, if you have multiple associations, you can use enableAutoFields():// Select id & title from articles, but all fields off of Users, Comments// and Tags.
$query->select(['id', 'title'])->contain(['Comments', 'Tags'])->enableAutoFields(true) // Prior to 3.4.0 use autoFields(true)->contain(['Users' => function(Query $q) {return $q->autoFields(true);}]);
New in version 3.1: Selecting columns via an association object was added in 3.1
502

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Sorting Contained Associations
When loading HasMany and BelongsToMany associations, you can use the sort option to sort the data in those associations:$query->contain(['Comments' => ['sort' => ['Comments.created' => 'DESC']]]);

Filtering by Associated Data
A fairly common query case with associations is finding records ‘matching’ specific associated data. For example if
you have ‘Articles belongsToMany Tags’ you will probably want to find Articles that have the CakePHP tag. This isextremely simple to do with the ORM in CakePHP:// In a controller or table method.
$query = $articles->find();$query->matching('Tags', function ($q) {return $q->where(['Tags.name' => 'CakePHP']);});
You can apply this strategy to HasMany associations as well. For example if ‘Authors HasMany Articles’, you could
find all the authors with recently published articles using the following:$query = $authors->find();$query->matching('Articles', function ($q) {return $q->where(['Articles.created >=' => new DateTime('-10 days')]);});
Filtering by deep associations is surprisingly easy, and the syntax should be already familiar to you:// In a controller or table method.
$query = $products->find()->matching('Shops.Cities.Countries', function ($q) {return $q->where(['Countries.name' => 'Japan']);});// Bring unique articles that were commented by 'markstory' using passed variable// Dotted matching paths should be used over nested matching() calls$username = 'markstory';$query = $articles->find()->matching('Comments.Users', function ($q) use ($username) {return $q->where(['username' => $username]);});Note: As this function will create an INNER JOIN, you might want to consider calling distinct on the find query as
you might get duplicate rows if your conditions don’t exclude them already. This might be the case, for example, when
the same users comments more than once on a single article.

More Information503

CakePHP Book, Release 3.10

The data from the association that is ‘matched’ will be available on the _matchingData property of entities. If both
match and contain the same association, you can expect to get both the _matchingData and standard association
properties in your results.
Using innerJoinWith
Sometimes you need to match specific associated data but without actually loading the matching records likematching(). You can create just the INNER JOIN that matching() uses with innerJoinWith():$query = $articles->find();$query->innerJoinWith('Tags', function ($q) {return $q->where(['Tags.name' => 'CakePHP']);});
innerJoinWith() allows you to use the same parameters and dot notation:$query = $products->find()->innerJoinWith('Shops.Cities.Countries', function ($q) {return $q->where(['Countries.name' => 'Japan']);});You can combine innerJoinWith() and contain() with the same association when you want to match specificrecords and load the associated data together. The example below matches Articles that have specific Tags and loads
the same Tags:$filter = ['Tags.name' => 'CakePHP'];$query = $articles->find()->distinct($articles->getPrimaryKey())->contain('Tags', function (Query $q) use ($filter) {return $q->where($filter);})->innerJoinWith('Tags', function (Query $q) use ($filter) {return $q->where($filter);});

Note: If you use innerJoinWith() and want to select() fields from that association, you need to use an alias forthe field:$query->select(['country_name' => 'Countries.name'])->innerJoinWith('Countries');If you don’t use an alias, you will see the data in _matchingData as described by matching() above. This is an edge
case from matching() not knowing you manually selected the field.

Warning: You should not combine innerJoinWith() and matching() with the same association. This willproduce multiple INNER JOIN statements and might not create the query you expected.
New in version 3.1: Query::innerJoinWith() was added in 3.1

504

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Using notMatching
The opposite of matching() is notMatching(). This function will change the query so that it filters results that haveno relation to the specified association:// In a controller or table method.
$query = $articlesTable->find()->notMatching('Tags', function ($q) {return $q->where(['Tags.name' => 'boring']);});
The above example will find all articles that were not tagged with the word boring. You can apply this method to
HasMany associations as well. You could, for example, find all the authors with no published articles in the last 10
days:$query = $authorsTable->find()->notMatching('Articles', function ($q) {return $q->where(['Articles.created >=' => new \DateTime('-10 days')]);});
It is also possible to use this method for filtering out records not matching deep associations. For example, you could
find articles that have not been commented on by a certain user:$query = $articlesTable->find()->notMatching('Comments.Users', function ($q) {return $q->where(['username' => 'jose']);});Since articles with no comments at all also satisfy the condition above, you may want to combine matching() andnotMatching() in the same query. The following example will find articles having at least one comment, but notcommented by a certain user:$query = $articlesTable->find()->notMatching('Comments.Users', function ($q) {return $q->where(['username' => 'jose']);})->matching('Comments');

Note: As notMatching() will create a LEFT JOIN, you might want to consider calling distinct on the find query
as you can get duplicate rows otherwise.
Keep in mind that contrary to the matching() function, notMatching() will not add any data to the _matchingData
property in the results.
New in version 3.1: Query::notMatching() was added in 3.1

More Information505

CakePHP Book, Release 3.10

Using leftJoinWith
On certain occasions you may want to calculate a result based on an association, without having to load all the records
for it. For example, if you wanted to load the total number of comments an article has along with all the article data,
you can use the leftJoinWith() function:$query = $articlesTable->find();$query->select(['total_comments' => $query->func()->count('Comments.id')])->leftJoinWith('Comments')->group(['Articles.id'])->enableAutoFields(true); // Prior to 3.4.0 use autoFields(true);
The results for the above query will contain the article data and the total_comments property for each of them.
leftJoinWith() can also be used with deeply nested associations. This is useful, for example, for bringing the countof articles tagged with a certain word, per author:$query = $authorsTable->find()->select(['total_articles' => $query->func()->count('Articles.id')])->leftJoinWith('Articles.Tags', function ($q) {return $q->where(['Tags.name' => 'awesome']);})->group(['Authors.id'])->enableAutoFields(true); // Prior to 3.4.0 use autoFields(true);
This function will not load any columns from the specified associations into the result set.
New in version 3.1: Query::leftJoinWith() was added in 3.1
Adding Joins
In addition to loading related data with contain(), you can also add additional joins with the query builder:$query = $articles->find()->join(['table' => 'comments','alias' => 'c',
'type' => 'LEFT','conditions' => 'c.article_id = articles.id',]);
You can append multiple joins at the same time by passing an associative array with multiple joins:$query = $articles->find()->join(['c' => ['table' => 'comments','type' => 'LEFT','conditions' => 'c.article_id = articles.id',],'u' => ['table' => 'users','type' => 'INNER',(continues on next page)

506

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'conditions' => 'u.id = articles.user_id',]]);
As seen above, when adding joins the alias can be the outer array key. Join conditions can also be expressed as an arrayof conditions:$query = $articles->find()->join(['c' => ['table' => 'comments','type' => 'LEFT','conditions' => ['c.created >' => new DateTime('-5 days'),'c.moderated' => true,'c.article_id = articles.id']],], ['c.created' => 'datetime', 'c.moderated' => 'boolean']);When creating joins by hand and using array based conditions, you need to provide the datatypes for each column inthe join conditions. By providing datatypes for the join conditions, the ORM can correctly convert data types into SQL.
In addition to join() you can use rightJoin(), leftJoin() and innerJoin() to create joins:// Join with an alias and string conditions$query = $articles->find();$query->leftJoin(['Authors' => 'authors'],['Authors.id = Articles.author_id']);// Join with an alias, array conditions, and types$query = $articles->find();$query->innerJoin(['Authors' => 'authors'],['Authors.promoted' => true,'Authors.created' => new DateTime('-5 days'),'Authors.id = Articles.author_id'],['Authors.promoted' => 'boolean', 'Authors.created' => 'datetime']);It should be noted that if you set the quoteIdentifiers option to true when defining your Connection, join conditions between table fields should be set as follow:$query = $articles->find()->join(['c' => ['table' => 'comments','type' => 'LEFT','conditions' => ['c.article_id' => new \Cake\Database\Expression\IdentifierExpression(
˓→'articles.id')](continues on next page)

More Information507

CakePHP Book, Release 3.10

(continued from previous page)],]);
This ensures that all of your identifiers will be quoted across the Query, avoiding errors with some database Drivers(PostgreSQL notably)
Inserting Data
Unlike earlier examples, you should not use find() to create insert queries. Instead, create a new Query object using
query():$query = $articles->query();$query->insert(['title', 'body'])->values(['title' => 'First post','body' => 'Some body text'])->execute();To insert multiple rows with only one query, you can chain the values() method as many times as you need:$query = $articles->query();$query->insert(['title', 'body'])->values(['title' => 'First post','body' => 'Some body text'])->values(['title' => 'Second post','body' => 'Another body text'])->execute();Generally, it is easier to insert data using entities and save(). By composing a SELECT and INSERT query together,you can create INSERT INTO ... SELECT style queries:$select = $articles->find()->select(['title', 'body', 'published'])->where(['id' => 3]);$query = $articles->query()->insert(['title', 'body', 'published'])->values($select)->execute();Note: Inserting records with the query builder will not trigger events such as Model.afterSave. Instead you should
use the ORM to save data.

508

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Updating Data
As with insert queries, you should not use find() to create update queries. Instead, create new a Query object using
query():$query = $articles->query();$query->update()->set(['published' => true])->where(['id' => $id])->execute();Generally, it is easier to update data using entities and patchEntity().
Note: Updating records with the query builder will not trigger events such as Model.afterSave. Instead you should
use the ORM to save data.

Deleting Data
As with insert queries, you should not use find() to create delete queries. Instead, create new a query object using
query():$query = $articles->query();$query->delete()->where(['id' => $id])->execute();Generally, it is easier to delete data using entities and delete().
SQL Injection Prevention
While the ORM and database abstraction layers prevent most SQL injections issues, it is still possible to leave yourself
vulnerable through improper use.
When using condition arrays, the key/left-hand side as well as single value entries must not contain user data:$query->where([// Data on the key/left-hand side is unsafe, as it will be// inserted into the generated query as-is$userData => $value,// The same applies to single value entries, they are not// safe to use with user data in any form
$userData,"MATCH (comment) AGAINST ($userData)",'created < NOW() - ' . $userData]);
When using the expression builder, column names must not contain user data:$query->where(function (QueryExpression $exp) use ($userData, $values) {// Column names in all expressions are not safe.
(continues on next page)

More Information509

CakePHP Book, Release 3.10

(continued from previous page)

return $exp->in($userData, $values);});
When building function expressions, function names should never contain user data:// Not safe.
$query->func()->{$userData}($arg1);// Also not safe to use an array of// user data in a function expression$query->func()->coalesce($userData);
Raw expressions are never safe:$expr = $query->newExpr()->add($userData);$query->select(['two' => $expr]);Binding values
It is possible to protect against many unsafe situations by using bindings. Similar to binding values to prepared statements, values can be bound to queries using the Cake\Database\Query::bind() method.
The following example would be a safe variant of the unsafe, SQL injection prone example given above:$query->where(['MATCH (comment) AGAINST (:userData)','created < NOW() - :moreUserData'])->bind(':userData', $userData, 'string')->bind(':moreUserData', $moreUserData, 'datetime');

Note:
Unlike Cake\Database\StatementInterface::bindValue(), Query::bind() requires to pass thenamed placeholders including the colon!

More Complex Queries
The query builder is capable of building complex queries like UNION queries and sub-queries.
UnionsUnions are created by composing one or more select queries together:$inReview = $articles->find()->where(['need_review' => true]);$unpublished = $articles->find()->where(['published' => false]);(continues on next page)

510

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$unpublished->union($inReview);
You can create UNION ALL queries using the unionAll() method:$inReview = $articles->find()->where(['need_review' => true]);$unpublished = $articles->find()->where(['published' => false]);$unpublished->unionAll($inReview);

Subqueries
Subqueries are a powerful feature in relational databases and building them in CakePHP is fairly intuitive. By composing queries together, you can make subqueries:// Prior to 3.6.0 use association() instead.
$matchingComment = $articles->getAssociation('Comments')->find()->select(['article_id'])->distinct()->where(['comment LIKE' => '%CakePHP%']);$query = $articles->find()->where(['id IN' => $matchingComment]);
Subqueries are accepted anywhere a query expression can be used. For example, in the select() and join() methods.
Adding Locking Statements
Most relational database vendors support taking out locks when doing select operations. You can use the epilog()
method for this:// In MySQL$query->epilog('FOR UPDATE');The epilog() method allows you to append raw SQL to the end of queries. You should never put raw user data into
epilog().
Executing Complex Queries
While the query builder makes it easy to build most queries, very complex queries can be tedious and complicated tobuild. You may want to execute the desired SQL directly.
Executing SQL directly allows you to fine tune the query that will be run. However, doing so doesn’t let you use
contain or other higher level ORM features.

More Information

511

CakePHP Book, Release 3.10

Table Objects
class Cake\ORM\Table
Table objects provide access to the collection of entities stored in a specific table. Each table in your application shouldhave an associated Table class which is used to interact with a given table. If you do not need to customize the behaviorof a given table CakePHP will generate a Table instance for you to use.
Before trying to use Table objects and the ORM, you should ensure that you have configured your database connection.
Basic Usage
To get started, create a Table class. These classes live in src/Model/Table. Tables are a type model collection specificto relational databases, and the main interface to your database in CakePHP’s ORM. The most basic table class would
look like:// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{}
Note that we did not tell the ORM which table to use for our class. By convention table objects will use a table thatmatches the lower cased and underscored version of the class name. In the above example the articles table will be
used. If our table class was named BlogPosts your table should be named blog_posts. You can specify the table touse by using the setTable() method:
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->setTable('my_table');// Prior to 3.4.0$this->table('my_table');}}No inflection conventions will be applied when specifying a table. By convention the ORM also expects each table tohave a primary key with the name of id. If you need to modify this you can use the setPrimaryKey() method:
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{(continues on next page)

512

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)

public function initialize(array $config){$this->setPrimaryKey('my_id');// Prior to 3.4.0$this->primaryKey('my_id');}}

Customizing the Entity Class a Table Uses
By default table objects use an entity class based on naming conventions. For example if your table class is called
ArticlesTable the entity would be Article. If the table class was PurchaseOrdersTable the entity would
be PurchaseOrder. If however, you want to use an entity that doesn’t follow the conventions you can use thesetEntityClass() method to change things up:
class PurchaseOrdersTable extends Table{
public function initialize(array $config){$this->setEntityClass('App\Model\Entity\PO');// Prior to 3.4.0$this->entityClass('App\Model\Entity\PO');}}As seen in the examples above Table objects have an initialize() method which is called at the end of the constructor. It is recommended that you use this method to do initialization logic instead of overriding the constructor.
Getting Instances of a Table Class
Before you can query a table, you’ll need to get an instance of the table. You can do this by using the TableLocatorclass:// In a controller or table method.
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');
TableLocator provides the various dependencies for constructing a table, and maintains a registry of all the constructed table instances making it easier to build relations and configure the ORM. See Using the TableLocator for
more information.
If your table class is in a plugin, be sure to use the correct name for your table class. Failing to do so can result invalidation rules, or callbacks not being triggered as a default class is used instead of your actual class. To correctly load
plugin table classes use the following:// Plugin table// Prior to 3.6 use TableRegistry::get('PluginName.Articles')(continues on next page)

More Information

513

CakePHP Book, Release 3.10

(continued from previous page)$articlesTable = TableRegistry::getTableLocator()->get('PluginName.Articles');// Vendor prefixed plugin table// Prior to 3.6 use TableRegistry::get('VendorName/PluginName.Articles')$articlesTable = TableRegistry::getTableLocator()->get('VendorName/PluginName.Articles');
Deprecated since version 3.6.0: The static methods on TableRegistry have been replaced by TableLocator. You
can get the TableLocator from TableRegistry using TableRegistry::getTableLocator().
Lifecycle Callbacks
As you have seen above table objects trigger a number of events. Events are useful if you want to hook into the ORM
and add logic in without subclassing or overriding methods. Event listeners can be defined in table or behavior classes.
You can also use a table’s event manager to bind listeners in.
When using callback methods behaviors attached in the initialize() method will have their listeners fired before
the table callback methods are triggered. This follows the same sequencing as controllers & components.
To add an event listener to a Table class or Behavior simply implement the method signatures as described below. See
the Events System for more detail on how to use the events subsystem.
Event List
• Model.initialize• Model.beforeMarshal• Model.beforeFind• Model.buildValidator• Model.buildRules• Model.beforeRules• Model.afterRules• Model.beforeSave• Model.afterSave• Model.afterSaveCommit• Model.beforeDelete• Model.afterDelete• Model.afterDeleteCommit

514

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

initialize
Cake\ORM\Table::initialize(Event $event, ArrayObject $data, ArrayObject $options)
The Model.initialize event is fired after the constructor and initialize methods are called. The Table classes do
not listen to this event by default, and instead use the initialize hook method.
To respond to the Model.initialize event you can create a listener class which implements
EventListenerInterface:
use Cake\Event\EventListenerInterface;class ModelInitializeListener implements EventListenerInterface{
public function implementedEvents(){
return array('Model.initialize' => 'initializeEvent',);}
public function initializeEvent($event){$table = $event->getSubject();// do something here}}
and attach the listener to the EventManager as below:
use Cake\Event\EventManager;$listener = new ModelInitializeListener();
EventManager::instance()->on($listener);
This will call the initializeEvent when any Table class is constructed.
beforeMarshal
Cake\ORM\Table::beforeMarshal(Event $event, ArrayObject $data, ArrayObject $options)
The Model.beforeMarshal event is fired before request data is converted into entities. See the Modifying Request
Data Before Building Entities documentation for more information.
beforeFind
Cake\ORM\Table::beforeFind(Event $event, Query $query, ArrayObject $options, $primary)
The Model.beforeFind event is fired before each find operation. By stopping the event and supplying a return value
you can bypass the find operation entirely. Any changes done to the $query instance will be retained for the rest of thefind. The $primary parameter indicates whether or not this is the root query, or an associated query. All associations
participating in a query will have a Model.beforeFind event triggered. For associations that use joins, a dummy
query will be provided. In your event listener you can set additional fields, conditions, joins or result formatters. These
options/features will be copied onto the root query.

More Information

515

CakePHP Book, Release 3.10

You might use this callback to restrict find operations based on a user’s role, or make caching decisions based on thecurrent load.
In previous versions of CakePHP there was an afterFind callback, this has been replaced with the Modifying Resultswith Map/Reduce features and entity constructors.
buildValidator
Cake\ORM\Table::buildValidator(Event $event, Validator $validator, $name)
The Model.buildValidator event is fired when $name validator is created. Behaviors, can use this hook to add invalidation methods.
buildRules
Cake\ORM\Table::buildRules(Event $event, RulesChecker $rules)
The Model.buildRules event is fired after a rules instance has been created and after the table’s buildRules()method has been called.
beforeRules
Cake\ORM\Table::beforeRules(Event $event, EntityInterface $entity, ArrayObject $options, $operation)
The Model.beforeRules event is fired before an entity has had rules applied. By stopping this event, you can halt
the rules checking and set the result of applying rules.
afterRules
Cake\ORM\Table::afterRules(Event $event, EntityInterface $entity, ArrayObject $options, $result, $operation)
The Model.afterRules event is fired after an entity has rules applied. By stopping this event, you can return the final
value of the rules checking operation.
beforeSave
Cake\ORM\Table::beforeSave(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.beforeSave event is fired before each entity is saved. Stopping this event will abort the save operation.
When the event is stopped the result of the event will be returned.

516

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

afterSave
Cake\ORM\Table::afterSave(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.afterSave event is fired after an entity is saved.
afterSaveCommit
Cake\ORM\Table::afterSaveCommit(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.afterSaveCommit event is fired after the transaction in which the save operation is wrapped has beencommitted. It’s also triggered for non atomic saves where database operations are implicitly committed. The event is
triggered only for the primary table on which save() is directly called. The event is not triggered if a transaction isstarted before calling save.
beforeDelete
Cake\ORM\Table::beforeDelete(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.beforeDelete event is fired before an entity is deleted. By stopping this event you will abort the delete
operation. When the event is stopped the result of the event will be returned.
afterDelete
Cake\ORM\Table::afterDelete(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.afterDelete event is fired after an entity has been deleted.
afterDeleteCommit
Cake\ORM\Table::afterDeleteCommit(Event $event, EntityInterface $entity, ArrayObject $options)
The Model.afterDeleteCommit event is fired after the transaction in which the delete operation is wrapped has been
is committed. It’s also triggered for non atomic deletes where database operations are implicitly committed. The event
is triggered only for the primary table on which delete() is directly called. The event is not triggered if a transaction
is started before calling delete.
Stopping Table Events
To prevent the save from continuing, simply stop event propagation in your callback:public function beforeSave(Event $event, EntityInterface $entity, ArrayObject $options){if (...) {$event->stopPropagation();$event->setResult(false);
return;}...
}More Information

517

CakePHP Book, Release 3.10

Alternatively, you can return false from the callback. This has the same effect as stopping event propagation.
Callback priorities
When using events on your tables and behaviors be aware of the priority and the order listeners are attached. Behavior
events are attached before Table events are. With the default priorities this means that Behavior callbacks are triggered
before the Table event with the same name.
As an example, if your Table is using TreeBehavior the TreeBehavior::beforeDelete() method will be called
before your table’s beforeDelete() method, and you will not be able to work wth the child nodes of the record being
deleted in your Table’s method.
You can manage event priorities in one of a few ways:
1. Change the priority of a Behavior’s listeners using the priority option. This will modify the priority of all
callback methods in the Behavior:// In a Table initialize() method$this->addBehavior('Tree', [// Default value is 10 and listeners are dispatched from the// lowest to highest priority.
'priority' => 2,]);
2. Modify the priority in your Table class by using the Model.implementedEvents() method. This allows
you to assign a different priority per callback-function:// In a Table class.
public function implementedEvents(){$events = parent::implementedEvents();$events['Model.beforeDelete'] = ['callable' => 'beforeDelete','priority' => 3];
return $events;}

Behaviors
Cake\ORM\Table::addBehavior($name, array $options = [])Behaviors provide an easy way to create horizontally re-usable pieces of logic related to table classes. You may bewondering why behaviors are regular classes and not traits. The primary reason for this is event listeners. While traits
would allow for re-usable pieces of logic, they would complicate binding events.
To add a behavior to your table you can call the addBehavior() method. Generally the best place to do this is in theinitialize() method:
namespace App\Model\Table;
use Cake\ORM\Table;(continues on next page)

518

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp');}}As with associations, you can use plugin syntax and provide additional configuration options:namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp', ['events' => ['Model.beforeSave' => ['created_at' => 'new','modified_at' => 'always'
]
]
]);
}
}
You can find out more about behaviors, including the behaviors provided by CakePHP in the chapter on Behaviors.
Configuring Connections
By default all table instances use the default database connection. If your application uses multiple database connections you will want to configure which tables use which connections. This is the defaultConnectionName()method:namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public static function defaultConnectionName() {return 'replica_db';}}

Note: The defaultConnectionName() method must be static.

More Information

519

CakePHP Book, Release 3.10

Using the TableLocatorclass Cake\ORM\TableLocator
As we’ve seen earlier, the TableRegistry class provides an easy way to use factory/registry for accessing your applications table instances. It provides a few other useful features as well.
Configuring Table Objects
Cake\ORM\TableLocator::get($alias, $config)
When loading tables from the registry you can customize their dependencies, or use mock objects by providing an$options array:// Prior to 3.6 use TableRegistry::get()$articles = TableRegistry::getTableLocator()->get('Articles', ['className' => 'App\Custom\ArticlesTable','table' => 'my_articles','connection' => $connectionObject,'schema' => $schemaObject,'entityClass' => 'Custom\EntityClass','eventManager' => $eventManager,'behaviors' => $behaviorRegistry]);
Pay attention to the connection and schema configuration settings, they aren’t string values but objects. The connection
will take an object of Cake\Database\Connection and schema Cake\Database\Schema\Collection.
Note: If your table also does additional configuration in its initialize() method, those values will overwrite theones provided to the registry.
You can also pre-configure the registry using TableLocator::setConfig(). Configuration data is stored per alias,
and can be overridden by an object’s initialize() method:// Prior to 3.6 use TableRegistry::setConfig()
TableRegistry::getTableLocator()->setConfig('Users', ['table' => 'my_users']);Note: You can only configure a table before or during the first time you access that alias. Doing it after the registry
is populated will have no effect.

Flushing the Registry
Cake\ORM\TableLocator::clear()During test cases you may want to flush the registry. Doing so is often useful when you are using mock objects, ormodifying a table’s dependencies:// Prior to 3.6 use TableRegistry::clear()
TableRegistry::getTableLocator()->clear();

520

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Configuring the Namespace to Locate ORM classes
If you have not followed the conventions it is likely that your Table or Entity classes will not be detected by CakePHP.
In order to fix this, you can set a namespace with the Cake\Core\Configure::write method. As an example:
/src
/App
/My
/Namespace/Model/Entity/TableWould be configured with:
Cake\Core\Configure::write('App.namespace', 'App\My\Namespace');

Entitiesclass Cake\ORM\Entity
While Table Objects represent and provide access to a collection of objects, entities represent individual rows or domain
objects in your application. Entities contain methods to manipulate and access the data they contain. Fields can also
be accessed as properties on the object.
Entities are created for you each time you use find() on a table object.
Creating Entity Classes
You don’t need to create entity classes to get started with the ORM in CakePHP. However, if you want to have custom
logic in your entities you will need to create classes. By convention entity classes live in src/Model/Entity/. If ourapplication had an articles table we could create the following entity:// src/Model/Entity/Article.php
namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{}
Right now this entity doesn’t do very much. However, when we load data from our articles table, we’ll get instances ofthis class.
Note: If you don’t define an entity class CakePHP will use the basic Entity class.

More Information

521

CakePHP Book, Release 3.10

Creating Entities
Entities can be directly instantiated:
use App\Model\Entity\Article;$article = new Article();When instantiating an entity you can pass the fields with the data you want to store in them:use App\Model\Entity\Article;$article = new Article(['id' => 1,'title' => 'New Article','created' => new DateTime('now')]);
The preferred way of getting new entities is using the newEntity() method from the Table objects:
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$article = TableRegistry::getTableLocator()->get('Articles')->newEntity();$article = TableRegistry::getTableLocator()->get('Articles')->newEntity(['id' => 1,'title' => 'New Article','created' => new DateTime('now')]);$article will be an instance of App\Model\Entity\Article or fallback to Cake\ORM\Entity instance if you
haven’t created the Article class.
Accessing Entity Data
Entities provide a few ways to access the data they contain. Most commonly you will access the data in an entity using
object notation:
use App\Model\Entity\Article;$article = new Article;$article->title = 'This is my first post';
echo $article->title;
You can also use the get() and set() methods:$article->set('title', 'This is my first post');echo $article->get('title');When using set() you can update multiple fields at once using an array:$article->set(['title' => 'My first post',(continues on next page)522

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'body' => 'It is the best ever!']);Warning: When updating entities with request data you should whitelist which fields can be set with mass assignment.
You can check if fields are defined in your entities with has():$article = new Article(['title' => 'First post','user_id' => null]);$article->has('title'); // true$article->has('user_id'); // false$article->has('undefined'); // false.
The has() method will return true if a field is defined and has a non-null value. You can use isEmpty() andhasValue() to check if a field contains a ‘non-empty’ value:$article = new Article(['title' => 'First post','user_id' => null]);$article->isEmpty('title'); // false$article->hasValue('title'); // true$article->isEmpty('user_id'); // true$article->hasValue('user_id'); // false
New in version 3.6.0: The hasValue() and isEmpty() methods were added in 3.6.0
Accessors & Mutators
In addition to the simple get/set interface, entities allow you to provide accessors and mutator methods. These methods
let you customize how fields are read or set.
Accessors use the convention of _get followed by the CamelCased version of the field name.
Cake\ORM\Entity::get($field)
They receive the basic value stored in the _properties array as their only argument. Accessors will be used whensaving entities, so be careful when defining methods that format data, as the formatted data will be persisted. For
example:namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{
protected function _getTitle($title)(continues on next page)

More Information

523

CakePHP Book, Release 3.10

(continued from previous page){
return ucwords($title);}}
The accessor would be run when getting the field through any of these two ways:
echo $article->title;echo $article->get('title');Note: Code in your accessors is executed each time you reference the field. You can use a local variable to cache it if
you are performing a resource-intensive operation in your accessor like this: $myEntityProp = $entity->my_property.
You can customize how fields get set by defining a mutator:
Cake\ORM\Entity::set($field = null, $value = null)
Mutator methods should always return the value that should be stored in the field. As you can see above, you can alsouse mutators to set other calculated fields. When doing this, be careful to not introduce any loops, as CakePHP will
not prevent infinitely looping mutator methods.
Mutators allow you to convert fields as they are set, or create calculated data. Mutators and accessors are applied whenfields are read using property access, or using get() and set(). For example:
namespace App\Model\Entity;
use Cake\ORM\Entity;
use Cake\Utility\Text;class Article extends Entity{
protected function _setTitle($title){
return Text::slug($title);}}
The mutator would be run when setting the field through any of these two ways:$user->title = 'foo'; // slug is set as well$user->set('title', 'foo'); // slug is set as wellWarning: Accessors are also run before entities are persisted to the database. If you want to transform fields but
not persist that transformation, we recommend using virtual fields as those are not persisted.

524

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Creating Virtual Fields
By defining accessors you can provide access to fields that do not actually exist. For example if your users table has
first_name and last_name you could create a method for the full name:namespace App\Model\Entity;
use Cake\ORM\Entity;class User extends Entity{
protected function _getFullName(){
return $this->first_name . ' ' . $this->last_name;}}
You can access virtual fields as if they existed on the entity. The property name will be the lower case and underscoredversion of the method (full_name):echo $user->full_name;
Do bear in mind that virtual fields cannot be used in finds. If you want them to be part of JSON or array representationsof your entities, see Exposing Virtual Fields.
Checking if an Entity Has Been Modified
Cake\ORM\Entity::dirty($field = null, $dirty = null)
You may want to make code conditional based on whether or not fields have changed in an entity. For example, you
may only want to validate fields when they change:// See if the title has been modified.
// Prior to 3.5 use dirty()$article->isDirty('title');You can also flag fields as being modified. This is handy when appending into array fields as this wouldn’t automaticallymark the field as dirty, only exchanging completely would.:// Add a comment and mark the field as changed.
// Prior to 3.5 use dirty()$article->comments[] = $newComment;$article->setDirty('comments', true);
In addition you can also base your conditional code on the original field values by using the getOriginal() method.
This method will either return the original value of the field if it has been modified or its actual value.
You can also check for changes to any field in the entity:// See if the entity has changed// Prior to 3.5 use dirty()$article->isDirty();
To remove the dirty mark from fields in an entity, you can use the clean() method:

More Information

525

CakePHP Book, Release 3.10

$article->clean();When creating a new entity, you can avoid the fields from being marked as dirty by passing an extra option:$article = new Article(['title' => 'New Article'], ['markClean' => true]);
To get a list of all dirty fields of an Entity you may call:$dirtyFields = $entity->getDirty();
New in version 3.4.3: getDirty() has been added.
New in version 3.5.0: isDirty(), setDirty() were added.
Validation Errors
After you save an entity any validation errors will be stored on the entity itself. You can access any validation errors
using the getErrors(), getError() or hasErrors() methods:// Get all the errors$errors = $user->getErrors();// Prior to 3.4.0$errors = $user->errors();// Get the errors for a single field.
$errors = $user->getError('password');// Prior to 3.4.0$errors = $user->errors('password');// Does the entity or any nested entity have an error.
$user->hasErrors();// Does only the root entity have an error$user->hasErrors(false);
The setErrors() or setError() method can also be used to set the errors on an entity, making it easier to test codethat works with error messages:$user->setError('password', ['Password is required']);$user->setErrors(['password' => ['Password is required'],'username' => ['Username is required']]);// Prior to 3.4.0$user->errors('password', ['Password is required.']);New in version 3.7.0: hasErrors() was added.

526

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Mass Assignment
While setting fields to entities in bulk is simple and convenient, it can create significant security issues. Bulk assigninguser data from the request into an entity allows the user to modify any and all columns. When using anonymous entity
classes or creating the entity class with the Bake Console CakePHP does not protect against mass-assignment.
The _accessible property allows you to provide a map of fields and whether or not they can be mass-assigned. The
values true and false indicate whether a field can or cannot be mass-assigned:
namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{
protected $_accessible = ['title' => true,'body' => true];}
In addition to concrete fields there is a special * field which defines the fallback behavior if a field is not specifically
named:
namespace App\Model\Entity;
use Cake\ORM\Entity;class Article extends Entity{
protected $_accessible = ['title' => true,'body' => true,'*' => false,];}

Note: If the * field is not defined it will default to false.

Avoiding Mass Assignment Protection
When creating a new entity using the new keyword you can tell it to not protect itself against mass assignment:
use App\Model\Entity\Article;$article = new Article(['id' => 1, 'title' => 'Foo'], ['guard' => false]);More Information

527

CakePHP Book, Release 3.10

Modifying the Guarded Fields at Runtime
You can modify the list of guarded fields at runtime using the setAccess() method:// Make user_id accessible.
$article->setAccess('user_id', true);// Prior to 3.5$article->accessible('user_id', true);// Make title guarded.
$article->setAccess('title', false);// Prior to 3.5$article->accessible('title', false);

Note: Modifying accessible fields affects only the instance the method is called on.
When using the newEntity() and patchEntity() methods in the Table objects you can customize mass assignment
protection with options. Please refer to the Changing Accessible Fields section for more information.
Bypassing Field Guarding
There are some situations when you want to allow mass-assignment to guarded fields:$article->set($fields, ['guard' => false]);By setting the guard option to false, you can ignore the accessible field list for a single call to set().
Checking if an Entity was Persisted
It is often necessary to know if an entity represents a row that is already in the database. In those situations use theisNew() method:if (!$article->isNew()) {echo 'This article was saved already!';}
If you are certain that an entity has already been persisted, you can use isNew() as a setter:$article->isNew(false);$article->isNew(true);

528

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Lazy Loading Associations
While eager loading associations is generally the most efficient way to access your associations, there may be times
when you need to lazily load associated data. Before we get into how to lazy load associations, we should discuss thedifferences between eager loading and lazy loading associations:
Eager loading
Eager loading uses joins (where possible) to fetch data from the database in as few queries as possible. When aseparate query is required, like in the case of a HasMany association, a single query is emitted to fetch all the
associated data for the current set of objects.
Lazy loading
Lazy loading defers loading association data until it is absolutely required. While this can save CPU time because
possibly unused data is not hydrated into objects, it can result in many more queries being emitted to the database.
For example looping over a set of articles & their comments will frequently emit N queries where N is the numberof articles being iterated.
While lazy loading is not included by CakePHP’s ORM, you can just use one of the community plugins to do so. We
recommend the LazyLoad Plugin144
After adding the plugin to your entity, you will be able to do the following:$article = $this->Articles->findById($id);// The comments property was lazy loaded
foreach ($article->comments as $comment) {echo $comment->body;}Creating Re-usable Code with Traits
You may find yourself needing the same logic in multiple entity classes. PHP’s traits are a great fit for this. You can
put your application’s traits in src/Model/Entity. By convention traits in CakePHP are suffixed with Trait so they
can be discernible from classes or interfaces. Traits are often a good complement to behaviors, allowing you to provide
functionality for the table and entity objects.
For example if we had SoftDeletable plugin, it could provide a trait. This trait could give methods for marking entities
as ‘deleted’, the method softDelete could be provided by a trait:// SoftDelete/Model/Entity/SoftDeleteTrait.php
namespace SoftDelete\Model\Entity;
trait SoftDeleteTrait{
public function softDelete(){$this->set('deleted', true);}}
You could then use this trait in your entity class by importing it and including it:
144 https://github.com/jeremyharris/cakephp-lazyload

More Information

529

CakePHP Book, Release 3.10

namespace App\Model\Entity;
use Cake\ORM\Entity;
use SoftDelete\Model\Entity\SoftDeleteTrait;class Article extends Entity{
use SoftDeleteTrait;}

Converting to Arrays/JSON
When building APIs, you may often need to convert entities into arrays or JSON data. CakePHP makes this simple:// Get an array.
// Associations will be converted with toArray() as well.
$array = $user->toArray();// Convert to JSON// Associations will be converted with jsonSerialize hook as well.
$json = json_encode($user);
When converting an entity to an JSON, the virtual & hidden field lists are applied. Entities are recursively converted
to JSON as well. This means that if you eager loaded entities and their associations CakePHP will correctly handle
converting the associated data into the correct format.
Exposing Virtual Fields
By default virtual fields are not exported when converting entities to arrays or JSON. In order to expose virtual fields
you need to make them visible. When defining your entity class you can provide a list of virtual field that should be
exposed:namespace App\Model\Entity;
use Cake\ORM\Entity;class User extends Entity{
protected $_virtual = ['full_name'];}This list can be modified at runtime using the setVirtual() method:$user->setVirtual(['full_name', 'is_admin']);// Prior to 3.5$user->virtualProperties(['full_name', 'is_admin']);530

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Hiding Fields
There are often fields you do not want exported in JSON or array formats. For example it is often unwise to expose
password hashes or account recovery questions. When defining an entity class, define which fields should be hidden:
namespace App\Model\Entity;
use Cake\ORM\Entity;class User extends Entity{
protected $_hidden = ['password'];}This list can be modified at runtime using the setHidden() method:$user->setHidden(['password', 'recovery_question']);// Prior to 3.5$user->hiddenProperties(['password', 'recovery_question']);Storing Complex Types
Accessor & Mutator methods on entities are not intended to contain the logic for serializing and unserializing complex
data coming from the database. Refer to the Saving Complex Types section to understand how your application canstore more complex data types like arrays and objects.

Retrieving Data & Results Sets
class Cake\ORM\Table
While table objects provide an abstraction around a ‘repository’ or collection of objects, when you query for individual
records you get ‘entity’ objects. While this section discusses the different ways you can find and load entities, you
should read the Entities section for more information on entities.
Debugging Queries and ResultSets
Since the ORM now returns Collections and Entities, debugging these objects can be more complicated than in previous
CakePHP versions. There are now various ways to inspect the data returned by the ORM.
• debug($query) Shows the SQL and bound parameters, does not show results.
• sql($query) Shows the final rendered SQL, but only when having DebugKit installed.
• debug($query->all()) Shows the ResultSet properties (not the results).
• debug($query->toList()) An easy way to show each of the results.
• debug(iterator_to_array($query)) Shows query results in an array format.
• debug(json_encode($query, JSON_PRETTY_PRINT)) More human readable results.
• debug($query->first()) Show the properties of a single entity.
• debug((string)$query->first()) Show the properties of a single entity as JSON.

More Information

531

CakePHP Book, Release 3.10

Getting a Single Entity by Primary Key
Cake\ORM\Table::get($id, $options = [])It is often convenient to load a single entity from the database when editing or viewing entities and their related data.
You can do this by using get():// In a controller or table method.
// Get a single article$article = $articles->get($id);// Get a single article, and related comments$article = $articles->get($id, ['contain' => ['Comments']]);
If the get operation does not find any results a Cake\Datasource\Exception\RecordNotFoundException will beraised. You can either catch this exception yourself, or allow CakePHP to convert it into a 404 error.
Like find(), get() also has caching integrated. You can use the cache option when calling get() to perform readthrough caching:// In a controller or table method.
// Use any cache config or CacheEngine instance & a generated key$article = $articles->get($id, ['cache' => 'custom',]);// Use any cache config or CacheEngine instance & specific key$article = $articles->get($id, ['cache' => 'custom', 'key' => 'mykey']);// Explicitly disable caching$article = $articles->get($id, ['cache' => false]);
Optionally you can get() an entity using Custom Finder Methods. For example you may want to get all translations
for an entity. You can achieve that by using the finder option:$article = $articles->get($id, ['finder' => 'translations',
]);

532

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Using Finders to Load Data
Cake\ORM\Table::find($type, $options = [])Before you can work with entities, you’ll need to load them. The easiest way to do this is using the find() method.
The find method provides an easy and extensible way to find the data you are interested in:// In a controller or table method.
// Find all the articles$query = $articles->find('all');
The return value of any find() method is always a Cake\ORM\Query object. The Query class allows you to further
refine a query after creating it. Query objects are evaluated lazily, and do not execute until you start fetching rows,
convert it to an array, or when the all() method is called:// In a controller or table method.
// Find all the articles.
// At this point the query has not run.
$query = $articles->find('all');// Iteration will execute the query.
foreach ($query as $row) {}// Calling all() will execute the query// and return the result set.
$results = $query->all();// Once we have a result set we can get all the rows
$data = $results->toList();// Converting the query to a key-value array will also execute it.
$data = $query->toArray();

Note: Once you’ve started a query you can use the Query Builder interface to build more complex queries, adding
additional conditions, limits, or include associations using the fluent interface.
// In a controller or table method.
$query = $articles->find('all')->where(['Articles.created >' => new DateTime('-10 days')])->contain(['Comments', 'Authors'])->limit(10);You can also provide many commonly used options to find(). This can help with testing as there are fewer methods
to mock:// In a controller or table method.
$query = $articles->find('all', ['conditions' => ['Articles.created >' => new DateTime('-10 days')],'contain' => ['Authors', 'Comments'],(continues on next page)

More Information

533

CakePHP Book, Release 3.10

(continued from previous page)'limit' => 10]);
The list of options supported by find() are:• conditions provide conditions for the WHERE clause of your query.
• limit Set the number of rows you want.
• offset Set the page offset you want. You can also use page to make the calculation simpler.
• contain define the associations to eager load.
• fields limit the fields loaded into the entity. Only loading some fields can cause entities to behave incorrectly.
• group add a GROUP BY clause to your query. This is useful when using aggregating functions.
• having add a HAVING clause to your query.
• join define additional custom joins.
• order order the result set.
Any options that are not in this list will be passed to beforeFind listeners where they can be used to modify the query
object. You can use the getOptions() method on a query object to retrieve the options used. While you can pass
query objects to your controllers, we recommend that you package your queries up as Custom Finder Methods instead.
Using custom finder methods will let you re-use your queries and make testing easier.
By default queries and result sets will return Entities objects. You can retrieve basic arrays by disabling hydration:$query->disableHydration();// Prior to 3.7.0$query->enableHydration(false);// Prior to 3.4.0$query->hydrate(false);// $data is ResultSet that contains array data.
$data = $query->all();Getting the First Result
The first() method allows you to fetch only the first row from a query. If the query has not been executed, a LIMIT
1 clause will be applied:// In a controller or table method.
$query = $articles->find('all', ['order' => ['Articles.created' => 'DESC']]);$row = $query->first();This approach replaces find('first') in previous versions of CakePHP. You may also want to use the get() method
if you are loading entities by primary key.
Note: The first() method will return null if no results are found.

534

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Getting a Count of Results
Once you have created a query object, you can use the count() method to get a result count of that query:// In a controller or table method.
$query = $articles->find('all', ['conditions' => ['Articles.title LIKE' => '%Ovens%']]);$number = $query->count();
See Returning the Total Count of Records for additional usage of the count() method.
Finding Key/Value Pairs
It is often useful to generate an associative array of data from your application’s data. For example, this is very usefulwhen creating <select> elements. CakePHP provides a simple to use method for generating ‘lists’ of data:// In a controller or table method.
$query = $articles->find('list');$data = $query->toArray();// Data now looks like$data = [1 => 'First post',
2 => 'Second article I wrote',];
With no additional options the keys of $data will be the primary key of your table, while the values will be the‘displayField’ of the table. The default ‘displayField’ of the table are title or name. While, you can use thesetDisplayField() method on a table object to configure the display field of a table:class ArticlesTable extends Table{
public function initialize(array $config){$this->setDisplayField('label');// Prior to 3.4.0$this->displayField('label');}}When calling list you can configure the fields used for the key and value with the keyField and valueField options
respectively:// In a controller or table method.
$query = $articles->find('list', ['keyField' => 'slug','valueField' => 'label']);$data = $query->toArray();// Data now looks like$data = [(continues on next page)

More Information

535

CakePHP Book, Release 3.10

(continued from previous page)'first-post' => 'First post','second-article-i-wrote' => 'Second article I wrote',];
Results can be grouped into nested sets. This is useful when you want bucketed sets, or want to build <optgroup>
elements with FormHelper:// In a controller or table method.
$query = $articles->find('list', ['keyField' => 'slug','valueField' => 'label','groupField' => 'author_id']);$data = $query->toArray();// Data now looks like$data = [1 => ['first-post' => 'First post','second-article-i-wrote' => 'Second article I wrote',],
2 => [// More data.
]];
You can also create list data from associations that can be reached with joins:$query = $articles->find('list', ['keyField' => 'id','valueField' => 'author.name'])->contain(['Authors']);Customize Key-Value Output
Lastly it is possible to use closures to access entity accessor methods in your list finds.
// In your Authors Entity create a virtual field to be used as the displayField:
protected function _getLabel(){
return $this->_properties['first_name'] . ' ' . $this->_properties['last_name']. ' / ' . __('User ID %s', $this->_properties['user_id']);}This example shows using the _getLabel() accessor method from the Author entity.
// In your finders/controller:$query = $articles->find('list', ['keyField' => 'id','valueField' => function ($article) {return $article->author->get('label');(continues on next page)

536

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)}]);
You can also fetch the label in the list directly using.
// In AuthorsTable::initialize():$this->setDisplayField('label'); // Will utilize Author::_getLabel()// In your finders/controller:$query = $authors->find('list'); // Will utilize AuthorsTable::getDisplayField()

Finding Threaded Data
The find('threaded') finder returns nested entities that are threaded together through a key field. By default thisfield is parent_id. This finder allows you to access data stored in an ‘adjacency list’ style table. All entities matchinga given parent_id are placed under the children attribute:// In a controller or table method.
$query = $comments->find('threaded');// Expanded default values$query = $comments->find('threaded', ['keyField' => $comments->primaryKey(),'parentField' => 'parent_id']);$results = $query->toArray();echo count($results[0]->children);echo $results[0]->children[0]->comment;
The parentField and keyField keys can be used to define the fields that threading will occur on.
Tip: If you need to manage more advanced trees of data, consider using Tree instead.

Custom Finder Methods
The examples above show how to use the built-in all and list finders. However, it is possible and recommended
that you implement your own finder methods. Finder methods are the ideal way to package up commonly used queries,
allowing you to abstract query details into a simple to use method. Finder methods are defined by creating methods
following the convention of findFoo where Foo is the name of the finder you want to create. For example if we wanted
to add a finder to our articles table for finding published articles we would do the following:
use Cake\ORM\Query;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function findOwnedBy(Query $query, array $options){$user = $options['user'];(continues on next page)

More Information

537

CakePHP Book, Release 3.10

(continued from previous page)

return $query->where(['author_id' => $user->id]);}}$query = $articles->find('ownedBy', ['user' => $userEntity]);Finder methods can modify the query as required, or use the $options to customize the finder operation with relevant
application logic. You can also ‘stack’ finders, allowing you to express complex queries effortlessly. Assuming you
have both the ‘published’ and ‘recent’ finders, you could do the following:$query = $articles->find('published')->find('recent');
While all the examples so far have shown finder methods on table classes, finder methods can also be defined on
Behaviors.
If you need to modify the results after they have been fetched you should use a Modifying Results with Map/Reduce
function to modify the results. The map reduce features replace the ‘afterFind’ callback found in previous versions of
CakePHP.
Note: Passing arguments exposed in the config array, $products->find('sizes', ['large', 'medium'])can give unexpected results when chaining custom finders. Always pass options as an associative array,$products->find('sizes', ['values' => ['large', 'medium']])Dynamic Finders
CakePHP’s ORM provides dynamically constructed finder methods which allow you to express simple queries with noadditional code. For example if you wanted to find a user by username you could do:// In a controller// The following two calls are equal.
$query = $this->Users->findByUsername('joebob');$query = $this->Users->findAllByUsername('joebob');
When using dynamic finders you can constrain on multiple fields:$query = $users->findAllByUsernameAndApproved('joebob', 1);
You can also create OR conditions:$query = $users->findAllByUsernameOrEmail('joebob', 'joe@example.com');
While you can use either OR or AND conditions, you cannot combine the two in a single dynamic finder. Other query options like contain are also not supported with dynamic finders. You should use Custom Finder Methods to encapsulate
more complex queries. Lastly, you can also combine dynamic finders with custom finders:$query = $users->findTrollsByUsername('bro');The above would translate into the following:$users->find('trolls', ['conditions' => ['username' => 'bro']
]);

538

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Once you have a query object from a dynamic finder, you’ll need to call first() if you want the first result.
Note: While dynamic finders make it simple to express queries, they add a small amount of overhead. You cannot
call findBy methods from a query object. When using a finder chain the dynamic finder must be called first.

Retrieving Associated Data
When you want to grab associated data, or filter based on associated data, there are two ways:• use CakePHP ORM query functions like contain() and matching()• use join functions like innerJoin(), leftJoin(), and rightJoin()
You should use contain() when you want to load the primary model, and its associated data. While contain() will
let you apply additional conditions to the loaded associations, you cannot constrain the primary model based on theassociations. For more details on the contain(), look at Eager Loading Associations Via Contain.
You should use matching() when you want to restrict the primary model based on associations. For example, youwant to load all the articles that have a specific tag on them. For more details on the matching(), look at Filtering by
Associated Data Via Matching And Joins.
If you prefer to use join functions, you can look at Adding Joins for more information.
Eager Loading Associations Via Contain
By default CakePHP does not load any associated data when using find(). You need to ‘contain’ or eager-load eachassociation you want loaded in your results.
Eager loading helps avoid many of the potential performance problems surrounding lazy-loading in an ORM. The
queries generated by eager loading can better leverage joins, allowing more efficient queries to be made. In CakePHP
you define eager loaded associations using the ‘contain’ method:// In a controller or table method.
// As an option to find()$query = $articles->find('all', ['contain' => ['Authors', 'Comments']]);// As a method on the query object$query = $articles->find('all');$query->contain(['Authors', 'Comments']);
The above will load the related author and comments for each article in the result set. You can load nested associations
using nested arrays to define the associations to be loaded:$query = $articles->find()->contain(['Authors' => ['Addresses'], 'Comments' => ['Authors']]);
Alternatively, you can express nested associations using the dot notation:$query = $articles->find()->contain(['Authors.Addresses','Comments.Authors']);More Information

539

CakePHP Book, Release 3.10

You can eager load associations as deep as you like:$query = $products->find()->contain(['Shops.Cities.Countries','Shops.Managers']);
You can select fields from all associations with multiple easy contain() statements:$query = $this->find()->select(['Realestates.id','Realestates.title','Realestates.description'])->contain(['RealestateAttributes' => ['Attributes' => ['fields' => [// Aliased fields in contain() must include// the model prefix to be mapped correctly.
'Attributes__name' => 'attr_name']]]])->contain(['RealestateAttributes' => ['fields' => ['RealestateAttributes.realestate_id','RealestateAttributes.value']]])->where($condition);
If you need to reset the containments on a query you can set the second argument to true:$query = $articles->find();$query->contain(['Authors', 'Comments'], true);

Passing Conditions to Contain
When using contain() you are able to restrict the data returned by the associations and filter them by conditions. To
specify conditions, pass an anonymous function that receives as the first argument a query object, \Cake\ORM\Query:// In a controller or table method.
// Prior to 3.5.0 you would use contain(['Comments' => function () { ... }])$query = $articles->find()->contain('Comments', function (Query $q) {return $q->select(['body', 'author_id'])->where(['Comments.approved' => true]);
});

540

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

This also works for pagination at the Controller level:$this->paginate['contain'] = ['Comments' => function (Query $query) {return $query->select(['body', 'author_id'])->where(['Comments.approved' => true]);}];

Note: When you limit the fields that are fetched from an association, you must ensure that the foreign key columns
are selected. Failing to select foreign key fields will cause associated data to not be present in the final result.
It is also possible to restrict deeply-nested associations using the dot notation:$query = $articles->find()->contain(['Comments','Authors.Profiles' => function (Query $q) {return $q->where(['Profiles.is_published' => true]);}]);
In the above example, you’ll still get authors even if they don’t have a published profile. To only get authors with apublished profile use matching(). If you have defined custom finders in your associations, you can use them insidecontain():// Bring all articles, but only bring the comments that are approved and// popular.
$query = $articles->find()->contain('Comments', function (Query $q) {return $q->find('approved')->find('popular');});

Note: For BelongsTo and HasOne associations only the where and select clauses are used when loading theassociated records. For the rest of the association types you can use every clause that the query object provides.
If you need full control over the query that is generated, you can tell contain() to not append the foreignKey
constraints to the generated query. In that case you should use an array passing foreignKey and queryBuilder:$query = $articles->find()->contain(['Authors' => ['foreignKey' => false,'queryBuilder' => function (Query $q) {return $q->where(...); // Full conditions for filtering}]]);
If you have limited the fields you are loading with select() but also want to load fields off of contained associations,
you can pass the association object to select():// Select id & title from articles, but all fields off of Users.
$query = $articles->find()(continues on next page)

More Information

541

CakePHP Book, Release 3.10

(continued from previous page)->select(['id', 'title'])->select($articles->Users)->contain(['Users']);Alternatively, if you have multiple associations, you can use enableAutoFields():// Select id & title from articles, but all fields off of Users, Comments// and Tags.
$query->select(['id', 'title'])->contain(['Comments', 'Tags'])->enableAutoFields(true) // Prior to 3.4.0 use autoFields(true)->contain(['Users' => function(Query $q) {return $q->autoFields(true);}]);
New in version 3.1: Selecting columns via an association object was added in 3.1
Sorting Contained Associations
When loading HasMany and BelongsToMany associations, you can use the sort option to sort the data in those associations:$query->contain(['Comments' => ['sort' => ['Comments.created' => 'DESC']]]);

Filtering by Associated Data Via Matching And Joins
A fairly common query case with associations is finding records ‘matching’ specific associated data. For example if
you have ‘Articles belongsToMany Tags’ you will probably want to find Articles that have the CakePHP tag. This isextremely simple to do with the ORM in CakePHP:// In a controller or table method.
$query = $articles->find();$query->matching('Tags', function ($q) {return $q->where(['Tags.name' => 'CakePHP']);});
You can apply this strategy to HasMany associations as well. For example if ‘Authors HasMany Articles’, you could
find all the authors with recently published articles using the following:$query = $authors->find();$query->matching('Articles', function ($q) {return $q->where(['Articles.created >=' => new DateTime('-10 days')]);});
Filtering by deep associations is surprisingly easy, and the syntax should be already familiar to you:

542

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10// In a controller or table method.
$query = $products->find()->matching('Shops.Cities.Countries', function ($q) {return $q->where(['Countries.name' => 'Japan']);});// Bring unique articles that were commented by 'markstory' using passed variable// Dotted matching paths should be used over nested matching() calls$username = 'markstory';$query = $articles->find()->matching('Comments.Users', function ($q) use ($username) {return $q->where(['username' => $username]);});Note: As this function will create an INNER JOIN, you might want to consider calling distinct on the find query as
you might get duplicate rows if your conditions don’t exclude them already. This might be the case, for example, when
the same users comments more than once on a single article.
The data from the association that is ‘matched’ will be available on the _matchingData property of entities. If both
match and contain the same association, you can expect to get both the _matchingData and standard association
properties in your results.
Using innerJoinWith
Sometimes you need to match specific associated data but without actually loading the matching records likematching(). You can create just the INNER JOIN that matching() uses with innerJoinWith():$query = $articles->find();$query->innerJoinWith('Tags', function ($q) {return $q->where(['Tags.name' => 'CakePHP']);});
innerJoinWith() allows you to use the same parameters and dot notation:$query = $products->find()->innerJoinWith('Shops.Cities.Countries', function ($q) {return $q->where(['Countries.name' => 'Japan']);});You can combine innerJoinWith() and contain() with the same association when you want to match specificrecords and load the associated data together. The example below matches Articles that have specific Tags and loads
the same Tags:$filter = ['Tags.name' => 'CakePHP'];$query = $articles->find()->distinct($articles->getPrimaryKey())->contain('Tags', function (Query $q) use ($filter) {return $q->where($filter);})->innerJoinWith('Tags', function (Query $q) use ($filter) {(continues on next page)

More Information

543

CakePHP Book, Release 3.10

(continued from previous page)

return $q->where($filter);});

Note: If you use innerJoinWith() and want to select() fields from that association, you need to use an alias forthe field:$query->select(['country_name' => 'Countries.name'])->innerJoinWith('Countries');If you don’t use an alias, you will see the data in _matchingData as described by matching() above. This is an edge
case from matching() not knowing you manually selected the field.

Warning: You should not combine innerJoinWith() and matching() with the same association. This willproduce multiple INNER JOIN statements and might not create the query you expected.
New in version 3.1: Query::innerJoinWith() was added in 3.1
Using notMatching
The opposite of matching() is notMatching(). This function will change the query so that it filters results that haveno relation to the specified association:// In a controller or table method.
$query = $articlesTable->find()->notMatching('Tags', function ($q) {return $q->where(['Tags.name' => 'boring']);});
The above example will find all articles that were not tagged with the word boring. You can apply this method to
HasMany associations as well. You could, for example, find all the authors with no published articles in the last 10
days:$query = $authorsTable->find()->notMatching('Articles', function ($q) {return $q->where(['Articles.created >=' => new \DateTime('-10 days')]);});
It is also possible to use this method for filtering out records not matching deep associations. For example, you could
find articles that have not been commented on by a certain user:$query = $articlesTable->find()->notMatching('Comments.Users', function ($q) {return $q->where(['username' => 'jose']);
});

544

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Since articles with no comments at all also satisfy the condition above, you may want to combine matching() andnotMatching() in the same query. The following example will find articles having at least one comment, but notcommented by a certain user:$query = $articlesTable->find()->notMatching('Comments.Users', function ($q) {return $q->where(['username' => 'jose']);})->matching('Comments');

Note: As notMatching() will create a LEFT JOIN, you might want to consider calling distinct on the find query
as you can get duplicate rows otherwise.
Keep in mind that contrary to the matching() function, notMatching() will not add any data to the _matchingData
property in the results.
New in version 3.1: Query::notMatching() was added in 3.1
Using leftJoinWith
On certain occasions you may want to calculate a result based on an association, without having to load all the records
for it. For example, if you wanted to load the total number of comments an article has along with all the article data,
you can use the leftJoinWith() function:$query = $articlesTable->find();$query->select(['total_comments' => $query->func()->count('Comments.id')])->leftJoinWith('Comments')->group(['Articles.id'])->enableAutoFields(true); // Prior to 3.4.0 use autoFields(true);
The results for the above query will contain the article data and the total_comments property for each of them.
leftJoinWith() can also be used with deeply nested associations. This is useful, for example, for bringing the countof articles tagged with a certain word, per author:$query = $authorsTable->find()->select(['total_articles' => $query->func()->count('Articles.id')])->leftJoinWith('Articles.Tags', function ($q) {return $q->where(['Tags.name' => 'awesome']);})->group(['Authors.id'])->enableAutoFields(true); // Prior to 3.4.0 use autoFields(true);
This function will not load any columns from the specified associations into the result set.
New in version 3.1: Query::leftJoinWith() was added in 3.1

More Information

545

CakePHP Book, Release 3.10

Changing Fetching Strategies
As you may know already, belongsTo and hasOne associations are loaded using a JOIN in the main finder query.
While this improves query and fetching speed and allows for creating more expressive conditions when retrieving data,
this may be a problem when you want to apply certain clauses to the finder query for the association, such as order()or limit().
For example, if you wanted to get the first comment of an article as an association:$articles->hasOne('FirstComment', ['className' => 'Comments','foreignKey' => 'article_id']);
In order to correctly fetch the data from this association, we will need to tell the query to use the select strategy, since
we want order by a particular column:$query = $articles->find()->contain(['FirstComment' => ['strategy' => 'select','queryBuilder' => function ($q) {return $q->order(['FirstComment.created' =>'ASC'])->limit(1);}]]);
Dynamically changing the strategy in this way will only apply to a specific query. If you want to make the strategy
change permanent you can do:$articles->FirstComment->setStrategy('select');// Prior to 3.4.0$articles->FirstComment->strategy('select');
Using the select strategy is also a great way of making associations with tables in another database, since it would
not be possible to fetch records using joins.
Fetching With The Subquery Strategy
As your tables grow in size, fetching associations from them can become slower, especially if you are querying big
batches at once. A good way of optimizing association loading for hasMany and belongsToMany associations is byusing the subquery strategy:$query = $articles->find()->contain(['Comments' => ['strategy' => 'subquery','queryBuilder' => function ($q) {return $q->where(['Comments.approved' => true]);}]]);
The result will remain the same as with using the default strategy, but this can greatly improve the query and fetchingtime in some databases, in particular it will allow to fetch big chunks of data at the same time in databases that limit
the amount of bound parameters per query, such as Microsoft SQL Server.

546

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

You can also make the strategy permanent for the association by doing:$articles->Comments->setStrategy('subquery');// Prior to 3.4.0$articles->Comments->strategy('subquery');

Lazy Loading Associations
While CakePHP makes it easy to eager load your associations, there may be cases where you need to lazy-load associations. You should refer to the Lazy Loading Associations and Loading Additional Associations sections for more
information.
Working with Result Sets
Once a query is executed with all(), you will get an instance of Cake\ORM\ResultSet. This object offers powerfulways to manipulate the resulting data from your queries. Like Query objects, ResultSets are a Collection and you can
use any collection method on ResultSet objects.
Result set objects will lazily load rows from the underlying prepared statement. By default results will be buffered inmemory allowing you to iterate a result set multiple times, or cache and iterate the results. If you need work with a data
set that does not fit into memory you can disable buffering on the query to stream results:$query->disableBufferedResults();// Prior to 3.7.0$query->enableBufferedResults(false);// Prior to 3.4.0$query->bufferResults(false);
Turning buffering off has a few caveats:
1. You will not be able to iterate a result set more than once.
2. You will also not be able to iterate & cache the results.
3. Buffering cannot be disabled for queries that eager load hasMany or belongsToMany associations, as these association types require eagerly loading all results so that dependent queries can be generated.
Warning: Streaming results will still allocate memory for the entire results when using PostgreSQL and SQL
Server. This is due to limitations in PDO.
Result sets allow you to cache/serialize or JSON encode results for API results:// In a controller or table method.
$results = $query->all();// Serialized$serialized = serialize($results);// Json$json = json_encode($results);

More Information

547

CakePHP Book, Release 3.10

Both serializing and JSON encoding result sets work as you would expect. The serialized data can be unserialized intoa working result set. Converting to JSON respects hidden & virtual field settings on all entity objects within a resultset.
In addition to making serialization easy, result sets are a ‘Collection’ object and support the same methods that collection objects do. For example, you can extract a list of unique tags on a collection of articles by running:// In a controller or table method.
$query = $articles->find()->contain(['Tags']);$reducer = function ($output, $value) {if (!in_array($value, $output)) {$output[] = $value;}
return $output;};$uniqueTags = $query->all()->extract('tags.name')->reduce($reducer, []);
Some other examples of the collection methods being used with result sets are:// Filter the rows by a calculated property$filtered = $results->filter(function ($row) {return $row->is_recent;});// Create an associative array from result properties$results = $articles->find()->contain(['Authors'])->all();$authorList = $results->combine('id', 'author.name');
The Collections chapter has more detail on what can be done with result sets using the collections features. The Adding
Calculated Fields section show how you can add calculated fields, or replace the result set.
Getting the First & Last Record From a ResultSet
You can use the first() and last() methods to get the respective records from a result set:$result = $articles->find('all')->all();// Get the first and/or last result.
$row = $result->first();$row = $result->last();548

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Getting an Arbitrary Index From a ResultSet
You can use skip() and first() to get an arbitrary record from a ResultSet:$result = $articles->find('all')->all();// Get the 5th record$row = $result->skip(4)->first();Checking if a Query or ResultSet is Empty
You can use the isEmpty() method on a Query or ResultSet object to see if it has any rows in it. Calling isEmpty()
on a Query object will evaluate the query:// Check a query.
$query->isEmpty();// Check results$results = $query->all();$results->isEmpty();

Loading Additional Associations
Once you’ve created a result set, you may need to load additional associations. This is the perfect time to lazily eager
load data. You can load additional associations using loadInto():$articles = $this->Articles->find()->all();$withMore = $this->Articles->loadInto($articles, ['Comments', 'Users']);
You can eager load additional data into a single entity, or a collection of entities.
Modifying Results with Map/Reduce
More often than not, find operations require post-processing the data that is found in the database. While entities’ gettermethods can take care of most of the virtual field generation or special data formatting, sometimes you need to change
the data structure in a more fundamental way.
For those cases, the Query object offers the mapReduce() method, which is a way of processing results once they arefetched from the database.
A common example of changing the data structure is grouping results together based on certain conditions. For thistask we can use the mapReduce() function. We need two callable functions the $mapper and the $reducer. The$mapper callable receives the current result from the database as first argument, the iteration key as second argument
and finally it receives an instance of the MapReduce routine it is running:$mapper = function ($article, $key, $mapReduce) {$status = 'published';
if ($article->isDraft() || $article->isInReview()) {$status = 'unpublished';}$mapReduce->emitIntermediate($article, $status);};

More Information549

CakePHP Book, Release 3.10

In the above example $mapper is calculating the status of an article, either published or unpublished, then it calls
emitIntermediate() on the MapReduce instance. This method stores the article in the list of articles labelled aseither published or unpublished.
The next step in the map-reduce process is to consolidate the final results. For each status created in the mapper, the$reducer function will be called so you can do any extra processing. This function will receive the list of articles ina particular “bucket” as the first parameter, the name of the “bucket” it needs to process as the second parameter, andagain, as in the mapper() function, the instance of the MapReduce routine as the third parameter. In our example, we
did not have to do any extra processing, so we just emit() the final results:$reducer = function ($articles, $status, $mapReduce) {$mapReduce->emit($articles, $status);};
Finally, we can put these two functions together to do the grouping:$articlesByStatus = $articles->find()->where(['author_id' => 1])->mapReduce($mapper, $reducer);foreach ($articlesByStatus as $status => $articles) {echo sprintf("There are %d %s articles", count($articles), $status);}
The above will ouput the following lines:
There are 4 published articles
There are 5 unpublished articles
Of course, this is a simplistic example that could actually be solved in another way without the help of a map-reduce
process. Now, let’s take a look at another example in which the reducer function will be needed to do something morethan just emitting the results.
Calculating the most commonly mentioned words, where the articles contain information about CakePHP, as usual weneed a mapper function:$mapper = function ($article, $key, $mapReduce) {if (stripos($article['body'], 'cakephp') === false) {return;}$words = array_map('strtolower', explode(' ', $article['body']));
foreach ($words as $word) {$mapReduce->emitIntermediate($article['id'], $word);}};
It first checks for whether the “cakephp” word is in the article’s body, and then breaks the body into individual words.
Each word will create its own bucket where each article id will be stored. Now let’s reduce our results to only extract
the count:$reducer = function ($occurrences, $word, $mapReduce) {$mapReduce->emit(count($occurrences), $word);}
Finally, we put everything together:
550

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

$wordCount = $articles->find()->where(['published' => true])->andWhere(['published_date >=' => new DateTime('2014-01-01')])->disableHydration() // Prior to 3.7.0 use enableHydration(false). Prior to 3.4.0␣
˓→use hydrate(false)->mapReduce($mapper, $reducer)->toArray();This could return a very large array if we don’t clean stop words, but it could look something like this:['cakephp' => 100,
'awesome' => 39,'impressive' => 57,'outstanding' => 10,'mind-blowing' => 83]
One last example and you will be a map-reduce expert. Imagine you have a friends table and you want to find “fakefriends” in our database, or better said, people who do not follow each other. Let’s start with our mapper() function:$mapper = function ($rel, $key, $mr) {$mr->emitIntermediate($rel['target_user_id'], $rel['source_user_id']);$mr->emitIntermediate(-$rel['source_user_id'], $rel['target_user_id']);};The intermediate array will be like the following:[
1 => [2, 3, 4, 5, -3, -5],
2 => [-1],
3 => [-1, 1, 6],
4 => [-1],
5 => [-1, 1],
6 => [-3],...
]Positive numbers mean that a user, indicated with the first-level key, is following them, and negative numbers meanthat the user is followed by them.
Now it’s time to reduce it. For each call to the reducer, it will receive a list of followers per user:$reducer = function ($friends, $user, $mr) {$fakeFriends = [];foreach ($friends as $friend) {if ($friend > 0 && !in_array(-$friend, $friends)) {$fakeFriends[] = $friend;}}
if ($fakeFriends) {$mr->emit($fakeFriends, $user);(continues on next page)

More Information

551

CakePHP Book, Release 3.10

(continued from previous page)}};
And we supply our functions to a query:$fakeFriends = $friends->find()->disableHydration() // Prior to 3.7.0 use enableHydration(false). Prior to 3.4.0␣
˓→use hydrate(false)->mapReduce($mapper, $reducer)->toArray();This would return an array similar to this:[
1 => [2, 4],
3 => [6]...
]The resulting array means, for example, that user with id 1 follows users 2 and 4, but those do not follow 1 back.
Stacking Multiple Operations
Using mapReduce in a query will not execute it immediately. The operation will be registered to be run as soon as thefirst result is attempted to be fetched. This allows you to keep chaining additional methods and filters to the query evenafter adding a map-reduce routine:$query = $articles->find()->where(['published' => true])->mapReduce($mapper, $reducer);// At a later point in your app:$query->where(['created >=' => new DateTime('1 day ago')]);
This is particularly useful for building custom finder methods as described in the Custom Finder Methods section:
public function findPublished(Query $query, array $options){
return $query->where(['published' => true]);}public function findRecent(Query $query, array $options){
return $query->where(['created >=' => new DateTime('1 day ago')]);}
public function findCommonWords(Query $query, array $options){// Same as in the common words example in the previous section$mapper = ...;
$reducer = ...;
return $query->mapReduce($mapper, $reducer);(continues on next page)

552

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)}$commonWords = $articles->find('commonWords')->find('published')->find('recent');
Moreover, it is also possible to stack more than one mapReduce operation for a single query. For example, if we wanted
to have the most commonly used words for articles, but then filter it to only return words that were mentioned morethan 20 times across all articles:$mapper = function ($count, $word, $mr) {if ($count > 20) {$mr->emit($count, $word);}};$articles->find('commonWords')->mapReduce($mapper);Removing All Stacked Map-reduce Operations
Under some circumstances you may want to modify a Query object so that no mapReduce operations are executed atall. This can be done by calling the method with both parameters as null and the third parameter (overwrite) as true:$query->mapReduce(null, null, true);

Validating Data
Before you save your data you will probably want to ensure the data is correct and consistent. In CakePHP we have
two stages of validation:
1. Before request data is converted into entities, validation rules around data types and formatting can be applied.
2. Before data is saved, domain or application rules can be applied. These rules help ensure that your application’s
data remains consistent.
Validating Data Before Building Entities
When marshalling data into entities, you can validate data. Validating data allows you to check the type, shape andsize of data. By default request data will be validated before it is converted into entities. If any validation rules fail, thereturned entity will contain errors. The fields with errors will not be present in the returned entity:$article = $articles->newEntity($this->request->getData());// Prior to 3.4 use $article->errors()
if ($article->getErrors()) {// Entity failed validation.
}
New in version 3.4.0: The getErrors() function was added.
When building an entity with validation enabled the following occurs:More Information

553

CakePHP Book, Release 3.10

1. The validator object is created.
2. The table and default validation provider are attached.
3. The named validation method is invoked. For example validationDefault.
4. The Model.buildValidator event will be triggered.
5. Request data will be validated.
6. Request data will be type-cast into types that match the column types.
7. Errors will be set into the entity.
8. Valid data will be set into the entity, while fields that failed validation will be excluded.
If you’d like to disable validation when converting request data, set the validate option to false:$article = $articles->newEntity($this->request->getData(),['validate' => false]);
The same can be said about the patchEntity() method:$article = $articles->patchEntity($article, $newData, ['validate' => false]);

Creating A Default Validation Set
Validation rules are defined in the Table classes for convenience. This defines what data should be validated in conjunction with where it will be saved.
To create a default validation object in your table, create the validationDefault() function:
use Cake\ORM\Table;
use Cake\Validation\Validator;
class ArticlesTable extends Table{
public function validationDefault(Validator $validator){$validator->requirePresence('title', 'create')->notEmptyString('title');$validator->allowEmptyString('link')->add('link', 'valid-url', ['rule' => 'url']);...
return $validator;
}
}

554

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

The available validation methods and rules come from the Validator class and are documented in the Creating
Validators section.
Note: Validation objects are intended primarily for validating user input, i.e. forms and any other posted request data.

Using A Different Validation Set
In addition to disabling validation you can choose which validation rule set you want applied:$article = $articles->newEntity($this->request->getData(),['validate' => 'update']);
The above would call the validationUpdate() method on the table instance to build the required rules. By default
the validationDefault() method will be used. An example validator for our articles table would be:class ArticlesTable extends Table{
public function validationUpdate($validator){$validator->notEmptyString('title', __('You need to provide a title'))->notEmptyString('body', __('A body is required'));return $validator;}}
You can have as many validation sets as necessary. See the validation chapter for more information on building validation rule-sets.
Using A Different Validation Set For Associations
Validation sets can also be defined per association. When using the newEntity() or patchEntity() methods, you
can pass extra options to each of the associations to be converted:$data = ['title' => 'My title','body' => 'The text','user_id' => 1,'user' => ['username' => 'mark'],'comments' => [['body' => 'First comment'],['body' => 'Second comment'],]];$article = $articles->patchEntity($article, $data, ['validate' => 'update',(continues on next page)

More Information

555

CakePHP Book, Release 3.10

(continued from previous page)'associated' => ['Users' => ['validate' => 'signup'],'Comments' => ['validate' => 'custom']]]);Combining Validators
Because of how validator objects are built, it is easy to break their construction process into multiple reusable steps:// UsersTable.php
public function validationDefault(Validator $validator){$validator->notEmptyString('username');$validator->notEmptyString('password');$validator->add('email', 'valid-email', ['rule' => 'email']);...
return $validator;}
public function validationHardened(Validator $validator){$validator = $this->validationDefault($validator);$validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]);
return $validator;}
Given the above setup, when using the hardened validation set, it will also contain the validation rules declared in thedefault set.
Validation Providers
Validation rules can use functions defined on any known providers. By default CakePHP sets up a few providers:
1. Methods on the table class or its behaviors are available on the table provider.
2. The core Validation class is setup as the default provider.
When a validation rule is created you can name the provider of that rule. For example, if your table has an isValidRole
method you can use it as a validation rule:use Cake\ORM\Table;
use Cake\Validation\Validator;
class UsersTable extends Table{
public function validationDefault(Validator $validator){$validator(continues on next page)

556

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)->add('role', 'validRole', ['rule' => 'isValidRole','message' => __('You need to provide a valid role'),'provider' => 'table',]);return $validator;}
public function isValidRole($value, array $context){
return in_array($value, ['admin', 'editor', 'author'], true);}}
You can also use closures for validation rules:$validator->add('name', 'myRule', ['rule' => function ($data, $provider) {if ($data > 1) {return true;}
return 'Not a good value.';}]);
Validation methods can return error messages when they fail. This is a simple way to make error messages dynamic
based on the provided value.
Getting Validators From Tables
Once you have created a few validation sets in your table class, you can get the resulting object by name:$defaultValidator = $usersTable->validator('default');$hardenedValidator = $usersTable->validator('hardened');Deprecated since version 3.5.0: validator() is deprecated. Use getValidator() instead.
Default Validator ClassAs stated above, by default the validation methods receive an instance of Cake\Validation\Validator. Instead, if
you want your custom validator’s instance to be used each time, you can use table’s $_validatorClass property:// In your table classpublic function initialize(array $config){$this->_validatorClass = '\FullyNamespaced\Custom\Validator';}More Information

557

CakePHP Book, Release 3.10

Applying Application Rules
While basic data validation is done when request data is converted into entities, many applications also have more
complex validation that should only be applied after basic validation has completed.
Where validation ensures the form or syntax of your data is correct, rules focus on comparing data against the existingstate of your application and/or network.
These types of rules are often referred to as ‘domain rules’ or ‘application rules’. CakePHP exposes this concept through‘RulesCheckers’ which are applied before entities are persisted. Some example domain rules are:• Ensuring email uniqueness• State transitions or workflow steps (e.g., updating an invoice’s status).
• Preventing the modification of soft deleted items.
• Enforcing usage/rate limit caps.
Domain rules are checked when calling the Table save() and delete() methods.
Creating a Rules Checker
Rules checker classes are generally defined by the buildRules() method in your table class. Behaviors and otherevent subscribers can use the Model.buildRules event to augment the rules checker for a given Table class:use Cake\ORM\RulesChecker;// In a table classpublic function buildRules(RulesChecker $rules){// Add a rule that is applied for create and update operations$rules->add(function ($entity, $options) {// Return a boolean to indicate pass/failure}, 'ruleName');// Add a rule for create.
$rules->addCreate(function ($entity, $options) {// Return a boolean to indicate pass/failure}, 'ruleName');// Add a rule for update$rules->addUpdate(function ($entity, $options) {// Return a boolean to indicate pass/failure}, 'ruleName');// Add a rule for the deleting.
$rules->addDelete(function ($entity, $options) {// Return a boolean to indicate pass/failure}, 'ruleName');return $rules;}
Your rules functions can expect to get the Entity being checked and an array of options. The options array will containerrorField, message, and repository. The repository option will contain the table class the rules are attached
to. Because rules accept any callable, you can also use instance functions:558

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

$rules->addCreate([$this, 'uniqueEmail'], 'uniqueEmail');or callable classes:$rules->addCreate(new IsUnique(['email']), 'uniqueEmail');
When adding rules you can define the field the rule is for and the error message as options:$rules->add([$this, 'isValidState'], 'validState', ['errorField' => 'status','message' => 'This invoice cannot be moved to that status.']);
The error will be visible when calling the errors() method on the entity:$entity->errors(); // Contains the domain rules error messages

Creating Unique Field Rules
Because unique rules are quite common, CakePHP includes a simple Rule class that allows you to define unique fieldsets:
use Cake\ORM\Rule\IsUnique;// A single field.
$rules->add($rules->isUnique(['email']));// A list of fields$rules->add($rules->isUnique(['username', 'account_id'],'This username & account_id combination has already been used.'));
When setting rules on foreign key fields it is important to remember, that only the fields listed are used in the rule. Thismeans that setting $user->account->id will not trigger the above rule.
Foreign Key Rules
While you could rely on database errors to enforce constraints, using rules code can help provide a nicer user experience.
Because of this CakePHP includes an ExistsIn rule class:// A single field.
$rules->add($rules->existsIn('article_id', 'Articles'));// Multiple keys, useful for composite primary keys.
$rules->add($rules->existsIn(['site_id', 'article_id'], 'Articles'));
The fields to check existence against in the related table must be part of the primary key.
You can enforce existsIn to pass when nullable parts of your composite foreign key are null:More Information

559

CakePHP Book, Release 3.10// Example: A composite primary key within NodesTable is (id, site_id).
// A Node may reference a parent Node but does not need to. In latter case, parent_id is␣
˓→null.
// Allow this rule to pass, even if fields that are nullable, like parent_id, are null:$rules->add($rules->existsIn(['parent_id', 'site_id'], // Schema: parent_id NULL, site_id NOT NULL
'ParentNodes',['allowNullableNulls' => true]));// A Node however should in addition also always reference a Site.
$rules->add($rules->existsIn(['site_id'], 'Sites'));In most SQL databases multi-column UNIQUE indexes allow multiple null values to exist as NULL is not equal to itself.
While, allowing multiple null values is the default behavior of CakePHP, you can include null values in your uniquechecks using allowMultipleNulls:// Only one null value can exist in `parent_id` and `site_id`$rules->add($rules->existsIn(['parent_id', 'site_id'],'ParentNodes',['allowMultipleNulls' => false]));
New in version 3.3.0: The allowNullableNulls and allowMultipleNulls options were added.
Association Count Rules
If you need to validate that a property or association contains the correct number of values, you can use thevalidCount() rule:// In the ArticlesTable.php file// No more than 5 tags on an article.
$rules->add($rules->validCount('tags', 5, '<=', 'You can only have 5 tags'));When defining count based rules, the third parameter lets you define the comparison operator to use. ==, >=, <=, >, <,and != are the accepted operators. To ensure a property’s count is within a range, use two rules:// In the ArticlesTable.php file// Between 3 and 5 tags
$rules->add($rules->validCount('tags', 3, '>=', 'You must have at least 3 tags'));$rules->add($rules->validCount('tags', 5, '<=', 'You must have at most 5 tags'));
Note that validCount returns false if the property is not countable or does not exist:// The save operation will fail if tags is null.
$rules->add($rules->validCount('tags', 0, '<=', 'You must not have any tags'));
New in version 3.3.0: The validCount() method was added in 3.3.0.

560

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Using Entity Methods as Rules
You may want to use entity methods as domain rules:$rules->add(function ($entity, $options) {return $entity->isOkLooking();}, 'ruleName');Using Conditional Rules
You may want to conditionally apply rules based on entity data:$rules->add(function ($entity, $options) use($rules) {if ($entity->role == 'admin') {$rule = $rules->existsIn('user_id', 'Admins');
return $rule($entity, $options);}
if ($entity->role == 'user') {$rule = $rules->existsIn('user_id', 'Users');
return $rule($entity, $options);}
return false;}, 'userExists');

Conditional/Dynamic Error Messages
Rules, being it custom callables, or rule objects, can either return a boolean, indicating whether they passed, or they
can return a string, which means that the rule did not pass, and that the returned string should be used as the error
message.
Possible existing error messages defined via the message option will be overwritten by the ones returned from the rule:$rules->add(function ($entity, $options) {if (!$entity->length) {return false;}
if ($entity->length < 10) {return 'Error message when value is less than 10';}if ($entity->length > 20) {return 'Error message when value is greater than 20';}
return true;},(continues on next page)

More Information

561

CakePHP Book, Release 3.10

(continued from previous page)'ruleName',['errorField' => 'length','message' => 'Generic error message used when `false` is returned']);

Note: Note that in order for the returned message to be actually used, you must also supply the errorField option,otherwise the rule will just silently fail to pass, ie without an error message being set on the entity!

Creating Custom re-usable Rules
You may want to re-use custom domain rules. You can do so by creating your own invokable rule:use App\ORM\Rule\IsUniqueWithNulls;// ...
public function buildRules(RulesChecker $rules){$rules->add(new IsUniqueWithNulls(['parent_id', 'instance_id', 'name']),˓→'uniqueNamePerParent', ['errorField' => 'name','message' => 'Name must be unique per parent.']);
return $rules;}
See the core rules for examples on how to create such rules.
Creating Custom Rule Objects
If your application has rules that are commonly reused, it is helpful to package those rules into re-usable classes:// in src/Model/Rule/CustomRule.php
namespace App\Model\Rule;
use Cake\Datasource\EntityInterface;class CustomRule{
public function __invoke(EntityInterface $entity, array $options){// Do work
return false;}}// Add the custom ruleuse App\Model\Rule\CustomRule;(continues on next page)

562

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$rules->add(new CustomRule(...), 'ruleName');By creating custom rule classes you can keep your code DRY and make your domain rules easy to test.
Disabling Rules
When saving an entity, you can disable the rules if necessary:$articles->save($article, ['checkRules' => false]);

Validation vs. Application Rules
The CakePHP ORM is unique in that it uses a two-layered approach to validation.
The first layer is validation. Validation rules are intended to operate in a stateless way. They are best leveraged to ensurethat the shape, data types and format of data is correct.
The second layer is application rules. Application rules are best leveraged to check stateful properties of your entities.
For example, validation rules could ensure that an email address is valid, while an application rule could ensure thatthe email address is unique.
As you already discovered, the first layer is done through the Validator objects when calling newEntity() orpatchEntity():$validatedEntity = $articlesTable->newEntity($unsafeData,['validate' => 'customName']);$validatedEntity = $articlesTable->patchEntity($entity,$unsafeData,['validate' => 'customName']);
In the above example, we’ll use a ‘custom’ validator, which is defined using the validationCustomName() method:
public function validationCustomName($validator){$validator->add(// ...
);
return $validator;}
Validation assumes strings or array are passed since that is what is received from any request:// In src/Model/Table/UsersTable.php
public function validatePasswords($validator){$validator->add('confirm_password', 'no-misspelling', [(continues on next page)

More Information

563

CakePHP Book, Release 3.10

(continued from previous page)'rule' => ['compareWith', 'password'],'message' => 'Passwords are not equal',]);// ...
return $validator;}
Validation is not triggered when directly setting properties on your entities:$userEntity->email = 'not an email!!';$usersTable->save($userEntity);In the above example the entity will be saved as validation is only triggered for the newEntity() and patchEntity()
methods. The second level of validation is meant to address this situation.
Application rules as explained above will be checked whenever save() or delete() are called:// In src/Model/Table/UsersTable.php
public function buildRules(RulesChecker $rules){$rules->add($rules->isUnique(['email']));
return $rules;}// Elsewhere in your application code$userEntity->email = 'a@duplicated.email';$usersTable->save($userEntity); // Returns false
While Validation is meant for direct user input, application rules are specific for data transitions generated inside yourapplication:// In src/Model/Table/OrdersTable.php
public function buildRules(RulesChecker $rules){$check = function($order) {if($order->shipping_mode !== 'free'){return true;}
return $order->price >= 100;};
$rules->add($check, ['errorField' => 'shipping_mode','message' => 'No free shipping for orders under 100!']);
return $rules;}// Elsewhere in application code
(continues on next page)

564

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$order->price = 50;$order->shipping_mode = 'free';$ordersTable->save($order); // Returns false

Using Validation as Application Rules
In certain situations you may want to run the same data validation routines for data that was both generated by users
and inside your application. This could come up when running a CLI script that directly sets properties on entities:// In src/Model/Table/UsersTable.php
public function validationDefault(Validator $validator){$validator->add('email', 'valid_email', ['rule' => 'email','message' => 'Invalid email']);// ...
return $validator;}
public function buildRules(RulesChecker $rules){// Add validation rules$rules->add(function($entity) {$data = $entity->extract($this->schema()->columns(), true);$validator = $this->validator('default');// Prior to 3.9 use $validator->errors()$errors = $validator->validate($data, $entity->isNew());$entity->errors($errors);
return empty($errors);});// ...
return $rules;}
When executed the save will fail thanks to the new application rule that was added:$userEntity->email = 'not an email!!!';$usersTable->save($userEntity);$userEntity->errors('email'); // Invalid email
The same result can be expected when using newEntity() or patchEntity():$userEntity = $usersTable->newEntity(['email' => 'not an email!!']);$userEntity->errors('email'); // Invalid email

More Information

565

CakePHP Book, Release 3.10

Saving Data
class Cake\ORM\Table
After you have loaded your data you will probably want to update and save the changes.
A Glance Over Saving Data
Applications will usually have a couple of ways in which data is saved. The first one is obviously through web forms
and the other is by directly generating or changing data in the code to be sent to the database.
Inserting Data
The easiest way to insert data in the database is by creating a new entity and passing it to the save() method in the
Table class:use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$articlesTable = TableRegistry::getTableLocator()->get('Articles');$article = $articlesTable->newEntity();$article->title = 'A New Article';$article->body = 'This is the body of the article';if ($articlesTable->save($article)) {// The $article entity contains the id now$id = $article->id;}The save() method returns the successfully saved entity or false on failure.
Updating Data
Updating your data is equally easy, and the save() method is also used for that purpose:
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('Articles')$articlesTable = TableRegistry::getTableLocator()->get('Articles');$article = $articlesTable->get(12); // Return article with id 12$article->title = 'CakePHP is THE best PHP framework!';$articlesTable->save($article);
CakePHP will know whether to perform an insert or an update based on the return value of the isNew() method.
Entities that were retrieved with get() or find() will always return false when isNew() is called on them.

566

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Saving With Associations
By default the save() method will also save one level of associations:// Prior to 3.6 use TableRegistry::get('Articles')$articlesTable = TableRegistry::getTableLocator()->get('Articles');$author = $articlesTable->Authors->findByUserName('mark')->first();$article = $articlesTable->newEntity();$article->title = 'An article by mark';$article->author = $author;
if ($articlesTable->save($article)) {// The foreign key value was set automatically.
echo $article->author_id;}
The save() method is also able to create new records for associations:$firstComment = $articlesTable->Comments->newEntity();$firstComment->body = 'The CakePHP features are outstanding';$secondComment = $articlesTable->Comments->newEntity();$secondComment->body = 'CakePHP performance is terrific!';$tag1 = $articlesTable->Tags->findByName('cakephp')->first();$tag2 = $articlesTable->Tags->newEntity();$tag2->name = 'awesome';$article = $articlesTable->get(12);$article->comments = [$firstComment, $secondComment];$article->tags = [$tag1, $tag2];$articlesTable->save($article);

Associate Many To Many Records
The previous example demonstrates how to associate a few tags to an article. Another way of accomplishing the samething is by using the link() method in the association:$tag1 = $articlesTable->Tags->findByName('cakephp')->first();$tag2 = $articlesTable->Tags->newEntity();$tag2->name = 'awesome';$articlesTable->Tags->link($article, [$tag1, $tag2]);

More Information

567

CakePHP Book, Release 3.10

Unlink Many To Many Records
Unlinking many to many records is done via the unlink() method:$tags = $articlesTable->Tags->find()->where(['name IN' => ['cakephp', 'awesome']])->toList();$articlesTable->Tags->unlink($article, $tags);
When modifying records by directly setting or changing the properties no validation happens, which is a problem when
accepting form data. The following sections will demonstrate how to efficiently convert form data into entities so thatthey can be validated and saved.
Converting Request Data into Entities
Before editing and saving data back to your database, you’ll need to convert the request data from the array format heldin the request, and the entities that the ORM uses. The Table class provides an easy and efficient way to convert one or
many entities from request data. You can convert a single entity using:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');// Validate and convert to an Entity object$entity = $articles->newEntity($this->request->getData());

Note: If you are using newEntity() and the resulting entities are missing some or all of the data they were passed,
double check that the columns you want to set are listed in the $_accessible property of your entity. See Mass
Assignment.
The request data should follow the structure of your entities. For example if you have an article, which belonged to auser, and had many comments, your request data should resemble:$data = ['title' => 'CakePHP For the Win','body' => 'Baking with CakePHP makes web development fun!','user_id' => 1,'user' => ['username' => 'mark'],'comments' => [['body' => 'The CakePHP features are outstanding'],['body' => 'CakePHP performance is terrific!'],]];By default, the newEntity() method validates the data that gets passed to it, as explained in the Validating Data
Before Building Entities section. If you wish to bypass data validation pass the 'validate' => false option:
568

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

$entity = $articles->newEntity($data, ['validate' => false]);When building forms that save nested associations, you need to define which associations should be marshalled:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');// New entity with nested associations$entity = $articles->newEntity($this->request->getData(), ['associated' => ['Tags', 'Comments' => ['associated' => ['Users']]]]);
The above indicates that the ‘Tags’, ‘Comments’ and ‘Users’ for the Comments should be marshalled. Alternatively,
you can use dot notation for brevity:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');// New entity with nested associations using dot notation$entity = $articles->newEntity($this->request->getData(), ['associated' => ['Tags', 'Comments.Users']]);
You may also disable marshalling of possible nested associations like so:$entity = $articles->newEntity($data, ['associated' => []]);// or...
$entity = $articles->patchEntity($entity, $data, ['associated' => []]);
Associated data is also validated by default unless told otherwise. You may also change the validation set to be used
per association:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');// Bypass validation on Tags association and// Designate 'signup' validation set for Comments.Users$entity = $articles->newEntity($this->request->getData(), ['associated' => ['Tags' => ['validate' => false],'Comments.Users' => ['validate' => 'signup']]]);
The Using A Different Validation Set For Associations chapter has more information on how to use different validators
for associated marshalling.

More Information

569

CakePHP Book, Release 3.10

The following diagram gives an overview of what happens inside the newEntity() or patchEntity() method:You
canalwayscountongettinganentitybackfrom
newEntity().
If validation
fails
your
entitywill
containerrors,andanyinvalidfieldswill
not bepopulatedin thecreatedentity.
Converting BelongsToMany Data
If
you
are
savingbelongsToMany associations you can either use a list of entity data or a list of ids. When using a list of entity data yourrequest data should look like:$data = ['title' => 'My title','body' => 'The text','user_id' => 1,(continues on next page)

570

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'tags' => [['name' => 'CakePHP'],['name' => 'Internet'],]];The above will create 2 new tags. If you want to link an article with existing tags you can use a list of ids. Your request
data should look like:$data = ['title' => 'My title','body' => 'The text','user_id' => 1,'tags' => ['_ids' => [1, 2, 3, 4]]];
If you need to link against some existing belongsToMany records, and create new ones at the same time you can use an
expanded format:$data = ['title' => 'My title','body' => 'The text','user_id' => 1,'tags' => [['name' => 'A new tag'],['name' => 'Another new tag'],['id' => 5],['id' => 21]]];
When the above data is converted into entities, you will have 4 tags. The first two will be new objects, and the second
two will be references to existing records.
When converting belongsToMany data, you can disable entity creation, by using the onlyIds option:$result = $articles->patchEntity($entity, $data, ['associated' => ['Tags' => ['onlyIds' => true]],]);
When used, this option restricts belongsToMany association marshalling to only use the _ids data.
New in version 3.1.0: The onlyIds option was added in 3.1.0

More Information

571

CakePHP Book, Release 3.10

Converting HasMany Data
If you want to update existing hasMany associations and update their properties, you should first ensure your entity isloaded with the hasMany association populated. You can then use request data similar to:$data = ['title' => 'My Title','body' => 'The text','comments' => [['id' => 1, 'comment' => 'Update the first comment'],['id' => 2, 'comment' => 'Update the second comment'],['comment' => 'Create a new comment'],]];
If you are saving hasMany associations and want to link existing records to a new parent record you can use the _ids
format:$data = ['title' => 'My new article','body' => 'The text','user_id' => 1,'comments' => ['_ids' => [1, 2, 3, 4]]];
When converting hasMany data, you can disable the new entity creation, by using the onlyIds option. When enabled,
this option restricts hasMany marshalling to only use the _ids key and ignore all other data.
New in version 3.1.0: The onlyIds option was added in 3.1.0
Converting Multiple Records
When creating forms that create/update multiple records at once you can use newEntities():// In a controller.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$entities = $articles->newEntities($this->request->getData());
In this situation, the request data for multiple articles should look like:$data = [['title' => 'First post','published' => 1],[
'title' => 'Second post','published' => 1
],
];

572

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Once you’ve converted request data into entities you can save() or delete() them:// In a controller.
foreach ($entities as $entity) {// Save entity$articles->save($entity);// Delete entity$articles->delete($entity);}
The above will run a separate transaction for each entity saved. If you’d like to process all the entities as a single
transaction you can use transactional():// In a controller.
$articles->getConnection()->transactional(function () use ($articles, $entities) {foreach ($entities as $entity) {$articles->save($entity, ['atomic' => false]);}});Changing Accessible Fields
It’s also possible to allow newEntity() to write into non accessible fields. For example, id is usually absent from the_accessible property. In such case, you can use the accessibleFields option. It could be useful to keep ids ofassociated entities:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$entity = $articles->newEntity($this->request->getData(), ['associated' => ['Tags', 'Comments' => ['associated' => ['Users' => ['accessibleFields' => ['id' => true]
]
]
]
]
]);
The above will keep the association unchanged between Comments and Users for the concerned entity.
Note: If you are using newEntity() and the resulting entities are missing some or all of the data they were passed,
double check that the columns you want to set are listed in the $_accessible property of your entity. See Mass
Assignment.

More Information573

CakePHP Book, Release 3.10

Merging Request Data Into Entities
In order to update entities you may choose to apply request data directly to an existing entity. This has the advantagethat only the fields that actually changed will be saved, as opposed to sending all fields to the database to be persisted.
You can merge an array of raw data into an existing entity using the patchEntity() method:// In a controller.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->get(1);$articles->patchEntity($article, $this->request->getData());$articles->save($article);

Validation and patchEntity
Similar to newEntity(), the patchEntity method will validate the data before it is copied to the entity. The mechanism is explained in the Validating Data Before Building Entities section. If you wish to disable validation while
patching an entity, pass the validate option as follows:// In a controller.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->get(1);$articles->patchEntity($article, $data, ['validate' => false]);You may also change the validation set used for the entity or any of the associations:$articles->patchEntity($article, $this->request->getData(), ['validate' => 'custom','associated' => ['Tags', 'Comments.Users' => ['validate' => 'signup']]]);Patching HasMany and BelongsToMany
As explained in the previous section, the request data should follow the structure of your entity. The patchEntity()
method is equally capable of merging associations, by default only the first level of associations are merged, but if you
wish to control the list of associations to be merged or merge deeper to deeper levels, you can use the third parameterof the method:// In a controller.
$associated = ['Tags', 'Comments.Users'];$article = $articles->get(1, ['contain' => $associated]);$articles->patchEntity($article, $this->request->getData(), ['associated' => $associated]);$articles->save($article);
Associations are merged by matching the primary key field in the source entities to the corresponding fields in the dataarray. Associations will construct new entities if no previous entity is found for the association’s target property.

574

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

For example give some request data like the following:$data = ['title' => 'My title','user' => ['username' => 'mark']];Trying to patch an entity without an entity in the user property will create a new user entity:// In a controller.
$entity = $articles->patchEntity(new Article, $data);
echo $entity->user->username; // Echoes 'mark'The same can be said about hasMany and belongsToMany associations, with an important caveat:
Note: For belongsToMany associations, ensure the relevant entity has a property accessible for the associated entity.
If a Product belongsToMany Tag:// in the Product Entity
protected $_accessible = [// .. other properties'tags' => true,];

Note: For hasMany and belongsToMany associations, if there were any entities that could not be matched by primary
key to a record in the data array, then those records will be discarded from the resulting entity.
Remember that using either patchEntity() or patchEntities() does not persist the data, it just edits (or creates)
the given entities. In order to save the entity you will have to call the table’s save() method.
For example, consider the following case:$data = ['title' => 'My title','body' => 'The text','comments' => [['body' => 'First comment', 'id' => 1],['body' => 'Second comment', 'id' => 2],]];$entity = $articles->newEntity($data);$articles->save($entity);$newData = ['comments' => [['body' => 'Changed comment', 'id' => 1],['body' => 'A new comment'],]];(continues on next page)

More Information575

CakePHP Book, Release 3.10

(continued from previous page)$articles->patchEntity($entity, $newData);$articles->save($entity);At the end, if the entity is converted back to an array you will obtain the following result:['title' => 'My title','body' => 'The text','comments' => [['body' => 'Changed comment', 'id' => 1],['body' => 'A new comment'],]];
As you can see, the comment with id 2 is no longer there, as it could not be matched to anything in the $newData array.
This happens because CakePHP is reflecting the new state described in the request data.
Some additional advantages of this approach is that it reduces the number of operations to be executed when persisting
the entity again.
Please note that this does not mean that the comment with id 2 was removed from the database, if you wish to remove
the comments for that article that are not present in the entity, you can collect the primary keys and execute a batch
delete for those not in the list:// In a controller.
// Prior to 3.6 use TableRegistry::get('Articles')$comments = TableRegistry::getTableLocator()->get('Comments');$present = (new Collection($entity->comments))->extract('id')->filter()->toList();$comments->deleteAll(['article_id' => $article->id,'id NOT IN' => $present]);
As you can see, this also helps creating solutions where an association needs to be implemented like a single set.
You can also patch multiple entities at once. The consideration made for patching hasMany and belongsToMany
associations apply for patching multiple entities: Matches are done by the primary key field value and missing matches
in the original entities array will be removed and not present in the result:// In a controller.
// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$list = $articles->find('popular')->toList();$patched = $articles->patchEntities($list, $this->request->getData());
foreach ($patched as $entity) {$articles->save($entity);}
Similarly to using patchEntity(), you can use the third argument for controlling the associations that will be mergedin each of the entities in the array:

576

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10// In a controller.
$patched = $articles->patchEntities($list,$this->request->getData(),['associated' => ['Tags', 'Comments.Users']]);

Modifying Request Data Before Building Entities
If you need to modify request data before it is converted into entities, you can use the Model.beforeMarshal event.
This event lets you manipulate the request data just before entities are created:// Include use statements at the top of your file.
use Cake\Event\Event;use ArrayObject;// In a table or behavior classpublic function beforeMarshal(Event $event, ArrayObject $data, ArrayObject $options){
if (isset($data['username'])) {$data['username'] = mb_strtolower($data['username']);}}
The $data parameter is an ArrayObject instance, so you don’t have to return it to change the data used to create
entities.
The main purpose of beforeMarshal is to assist the users to pass the validation process when simple mistakes can be
automatically resolved, or when data needs to be restructured so it can be put into the right fields.
The Model.beforeMarshal event is triggered just at the start of the validation process, one of the reasons is that
beforeMarshal is allowed to change the validation rules and the saving options, such as the field whitelist. Validationis triggered just after this event is finished. A common example of changing the data before it is validated is trimming
all fields before saving:// Include use statements at the top of your file.
use Cake\Event\Event;use ArrayObject;// In a table or behavior classpublic function beforeMarshal(Event $event, ArrayObject $data, ArrayObject $options){foreach ($data as $key => $value) {if (is_string($value)) {$data[$key] = trim($value);}}}
Because of how the marshalling process works, if a field does not pass validation it will automatically be removed fromthe data array and not be copied into the entity. This is to prevent inconsistent data from entering the entity object.
Moreover, the data in beforeMarshal is a copy of the passed data. This is because it is important to preserve theoriginal user input, as it may be used elsewhere.
More Information577

CakePHP Book, Release 3.10

Validating Data Before Building Entities
The Validating Data chapter has more information on how to use the validation features of CakePHP to ensure yourdata stays correct and consistent.
Avoiding Property Mass Assignment Attacks
When creating or merging entities from request data you need to be careful of what you allow your users to change or
add in the entities. For example, by sending an array in the request containing the user_id an attacker could change
the owner of an article, causing undesirable effects:// Contains ['user_id' => 100, 'title' => 'Hacked!'];$data = $this->request->getData();$entity = $this->patchEntity($entity, $data);$this->save($entity);
There are two ways of protecting you against this problem. The first one is by setting the default columns that can besafely set from a request using the Mass Assignment feature in the entities.
The second way is by using the fieldList option when creating or merging data into an entity:// Contains ['user_id' => 100, 'title' => 'Hacked!'];$data = $this->request->getData();// Only allow title to be changed$entity = $this->patchEntity($entity, $data, ['fieldList' => ['title']]);$this->save($entity);
You can also control which properties can be assigned for associations:// Only allow changing the title and tags// and the tag name is the only column that can be set$entity = $this->patchEntity($entity, $data, ['fieldList' => ['title', 'tags'],'associated' => ['Tags' => ['fieldList' => ['name']]]]);$this->save($entity);
Using this feature is handy when you have many different functions your users can access and you want to let your users
edit different data based on their privileges.
The fieldList options is also accepted by the newEntity(), newEntities() and patchEntities() methods.
Deprecated since version 3.4.0: Use fields instead of fieldList.

578

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Saving Entities
Cake\ORM\Table::save(Entity $entity, array $options = [])When saving request data to your database you need to first hydrate a new entity using newEntity() for passing intosave(). For example:// In a controller// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->newEntity($this->request->getData());
if ($articles->save($article)) {// ...
}The ORM uses the isNew() method on an entity to determine whether or not an insert or update should be performed.
If the isNew() method returns true and the entity has a primary key value, an ‘exists’ query will be issued. The‘exists’ query can be suppressed by passing 'checkExisting' => false in the $options argument:$articles->save($article, ['checkExisting' => false]);Once you’ve loaded some entities you’ll probably want to modify them and update your database. This is a pretty
simple exercise in CakePHP:// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->find('all')->where(['id' => 2])->first();$article->title = 'My new title';$articles->save($article);
When saving, CakePHP will apply your rules, and wrap the save operation in a database transaction. It will also only
update properties that have changed. The above save() call would generate SQL like:
UPDATE articles SET title = 'My new title' WHERE id = 2;
If you had a new entity, the following SQL would be generated:
INSERT INTO articles (title) VALUES ('My new title');When an entity is saved a few things happen:
1. Rule checking will be started if not disabled.
2. Rule checking will trigger the Model.beforeRules event. If this event is stopped, the save operation will failand return false.
3. Rules will be checked. If the entity is being created, the create rules will be used. If the entity is being updated,
the update rules will be used.
4. The Model.afterRules event will be triggered.
5. The Model.beforeSave event is dispatched. If it is stopped, the save will be aborted, and save() will returnfalse.
6. Parent associations are saved. For example, any listed belongsTo associations will be saved.
7. The modified fields on the entity will be saved.
More Information579

CakePHP Book, Release 3.10

8. Child associations are saved. For example, any listed hasMany, hasOne, or belongsToMany associations will besaved.
9. The Model.afterSave event will be dispatched.
10. The Model.afterSaveCommit event will be dispatched.
The following diagram illustrates the above process:See the Applying Application Rules section
for more information on creating and using
rules.

Warning: If no changes atity when it is saved, the cal
because no save is perform
The save() method will return the modified entity on success, and false on failure.
You can disable rules and/or transactions using the $options argument for save://␣˓→In a controller or table method.
$articles˓→>save($article, ['checkRules
˓→' => false, 'atomic' => false]);Saving Associations
When you are saving an entity, you can also
elect to save some or all of the associated entities. By default all first level entities will besaved. For example saving an Article, will
also automatically update any dirty entities
that are directly related to articles table.
You can fine tune which associations are
saved by using the associated option:// In a controller.
// Only␣˓→save the comments association$articles->save($entity,␣˓→['associated' => ['Comments']]);
You can define save distant or deeply nested
associations by using dot notation:// Save the company,
˓→ the employees and related␣˓→addresses for each of them.
(continues on next page)

580

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$companies˓→>save($entity, ['associated˓→' => ['Employees.Addresses']]);
Moreover, you can combine the dot notation
for associations with the options array:$companies->save($entity, ['associated' => ['Employees','Employees.Addresses']]);
Your entities should be structured in thesame way as they are when loaded from thedatabase. See the form helper documentation
for how to build inputs for associations.
If you are building or modifying association
data after building your entities you will haveto mark the association property as modified
with setDirty():$company˓→>author->name = 'Master Chef';// Prior to 3.5 use dirty()$company->setDirty('author',␣
˓→true);Saving BelongsTo Associations
When saving belongsTo associations, the ORM expects a single nested entity named with the singular, underscoredversion of the association name. For example:// In a controller.
$data = ['title' => 'First Post','user' => ['id' => 1,'username' => 'mark']];// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->newEntity($data, ['associated' => ['Users']]);$articles->save($article);

More Information

581

CakePHP Book, Release 3.10

Saving HasOne Associations
When saving hasOne associations, the ORM expects a single nested entity named with the singular, underscored versionof the association name. For example:// In a controller.
$data = ['id' => 1,'username' => 'cakephp','profile' => ['twitter' => '@cakephp']];// Prior to 3.6 use TableRegistry::get('Users')$users = TableRegistry::getTableLocator()->get('Users');$user = $users->newEntity($data, ['associated' => ['Profiles']]);$users->save($user);

Saving HasMany Associations
When saving hasMany associations, the ORM expects an array of entities named with the plural, underscored versionof the association name. For example:// In a controller.
$data = ['title' => 'First Post','comments' => [['body' => 'Best post ever'],['body' => 'I really like this.']]];// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->newEntity($data, ['associated' => ['Comments']]);$articles->save($article);
When saving hasMany associations, associated records will either be updated, or inserted. For the case that the record
already has associated records in the database, you have the choice between two saving strategies:
appendAssociated records are updated in the database or, if not matching any existing record, inserted.
replaceAny existing records that do not match the records provided will be deleted from the database. Only provided
records will remain (or be inserted).
By default the append saving strategy is used. See HasMany Associations for details on defining the saveStrategy.

582

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Whenever you add new records to an existing association you should always mark the association property as ‘dirty’.
This lets the ORM know that the association property has to be persisted:$article->comments[] = $comment;// Prior to 3.5 use dirty()$article->setDirty('comments', true);
Without the call to setDirty() the updated comments will not be saved.
If you are creating a new entity, and want to add existing records to a has many/belongs to many association you needto initialize the association property first:$article->comments = [];Without initialization calling $article->comments[] = $comment; will have no effect.
Saving BelongsToMany Associations
When saving belongsToMany associations, the ORM expects an array of entities named with the plural, underscoredversion of the association name. For example:// In a controller.
$data = ['title' => 'First Post','tags' => [['tag' => 'CakePHP'],['tag' => 'Framework']]];// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$article = $articles->newEntity($data, ['associated' => ['Tags']]);$articles->save($article);
When converting request data into entities, the newEntity() and newEntities() methods will handle both arrays ofproperties, as well as a list of ids at the _ids key. Using the _ids key makes it easy to build a select box or checkbox
based form controls for belongs to many associations. See the Converting Request Data into Entities section for more
information.
When saving belongsToMany associations, you have the choice between two saving strategies:
appendOnly new links will be created between each side of this association. This strategy will not destroy existing links
even though they may not be present in the array of entities to be saved.
replace
When saving, existing links will be removed and new links will be created in the junction table. If there areexisting link in the database to some of the entities intended to be saved, those links will be updated, not deleted
and then re-saved.
See BelongsToMany Associations for details on defining the saveStrategy.
By default the replace strategy is used. Whenever you add new records into an existing association you should always
mark the association property as ‘dirty’. This lets the ORM know that the association property has to be persisted:
More Information

583

CakePHP Book, Release 3.10

$article->tags[] = $tag;// Prior to 3.5 use dirty()$article->setDirty('tags', true);
Without the call to setDirty() the updated tags will not be saved.
Often you’ll find yourself wanting to make an association between two existing entities, eg. a user coauthoring anarticle. This is done by using the method link(), like this:$article = $this->Articles->get($articleId);$user = $this->Users->get($userId);$this->Articles->Users->link($article, [$user]);
When saving belongsToMany Associations, it can be relevant to save some additional data to the junction Table. In
the previous example of tags, it could be the vote_type of person who voted on that article. The vote_type can beeither upvote or downvote and is represented by a string. The relation is between Users and Articles.
Saving that association, and the vote_type is done by first adding some data to _joinData and then saving theassociation with link(), example:$article = $this->Articles->get($articleId);$user = $this->Users->get($userId);$user->_joinData = new Entity(['vote_type' => $voteType], ['markNew' => true]);$this->Articles->Users->link($article, [$user]);

Saving Additional Data to the Join Table
In some situations the table joining your BelongsToMany association, will have additional columns on it. CakePHP
makes it simple to save properties into these columns. Each entity in a belongsToMany association has a _joinData
property that contains the additional columns on the junction table. This data can be either an array or an Entity
instance. For example if Students BelongsToMany Courses, we could have a junction table that looks like:
id | student_id | course_id | days_attended | grade
When saving data you can populate the additional columns on the junction table by setting data to the _joinData
property:$student->courses[0]->_joinData->grade = 80.12;$student->courses[0]->_joinData->days_attended = 30;$studentsTable->save($student);
The _joinData property can be either an entity, or an array of data if you are saving entities built from request data.
When saving junction table data from request data your POST data should look like:$data = ['first_name' => 'Sally','last_name' => 'Parker','courses' => [['id' => 10,(continues on next page)

584

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'_joinData' => ['grade' => 80.12,'days_attended' => 30]],// Other courses.
]];$student = $this->Students->newEntity($data, ['associated' => ['Courses._joinData']]);
See the Creating Inputs for Associated Data documentation for how to build inputs with FormHelper correctly.
Saving Complex Types
Tables are capable of storing data represented in basic types, like strings, integers, floats, booleans, etc. But It can also
be extended to accept more complex types such as arrays or objects and serialize this data into simpler types that canbe saved in the database.
This functionality is achieved by using the custom types system. See the Adding Custom Types section to find out how
to build custom column Types:// Only prior to 3.6, you have to add a new type map in config/bootstrap.php
use Cake\Database\Type;
Type::map('json', 'Cake\Database\Type\JsonType');// In src/Model/Table/UsersTable.php
use Cake\Database\Schema\TableSchema;class UsersTable extends Table{
protected function _initializeSchema(TableSchema $schema){$schema->setColumnType('preferences', 'json');// Prior to 3.6 you should use ``columnType`` instead of ``setcolumnType``.
$schema->columnType('preferences', 'json');return $schema;}}
The code above maps the preferences column to the json custom type. This means that when retrieving data forthat column, it will be unserialized from a JSON string in the database and put into an entity as an array.
Likewise, when saved, the array will be transformed back into its JSON representation:$user = new User(['preferences' => ['sports' => ['football', 'baseball'],(continues on next page)

More Information

585

CakePHP Book, Release 3.10

(continued from previous page)'books' => ['Mastering PHP', 'Hamlet']]]);$usersTable->save($user);
When using complex types it is important to validate that the data you are receiving from the end user is the correct
type. Failing to correctly handle complex data could result in malicious users being able to store data they would notnormally be able to.
Strict Saving
Cake\ORM\Table::saveOrFail($entity, $options = [])Using this method will throw an Cake\ORM\Exception\PersistenceFailedException if:• the application rules checks failed• the entity contains errors• the save was aborted by a callback.
Using this can be helpful when you performing complex database operations without human monitoring, for example,
inside a Shell task.
Note: If you use this method in a controller, be sure to catch the PersistenceFailedException that could beraised.
If you want to track down the entity that failed to save, you can use the Cake\ORMException\
PersistenceFailedException::getEntity() method:try {$table->saveOrFail($entity);} catch (\Cake\ORM\Exception\PersistenceFailedException $e) {echo $e->getEntity();}
As this internally perfoms a Cake\ORM\Table::save() call, all corresponding save events will be triggered.
New in version 3.4.1.
Find or Create an Entity
Cake\ORM\Table::findOrCreate($search, $callback = null, $options = [])Find an existing record based on $search or create a new record using the properties in $search and calling theoptional $callback. This method is ideal in scenarios where you need to reduce the chance of duplicate records:$record = $table->findOrCreate(['email' => 'bobbi@example.com'],function ($entity) use ($otherData) {// Only called when a new record is created.
$entity->name = $otherData['name'];(continues on next page)

586

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)});
If your find conditions require custom order, associations or conditions, then the $search parameter can be a callable
or Query object. If you use a callable, it should take a Query as its argument.
The returned entity will have been saved if it was a new record. The supported options for this method are:• atomic Should the find and save operation be done inside a transaction.
• defaults Set to false to not set $search properties into the created entity.
Saving Multiple Entities
Cake\ORM\Table::saveMany($entities, $options = [])Using this method you can save multiple entities atomically. $entities can be an array of entities created using
newEntities() / patchEntities(). $options can have the same options as accepted by save():$data = [['title' => 'First post','published' => 1],[
'title' => 'Second post','published' => 1],];// Prior to 3.6 use TableRegistry::get('Articles')$articles = TableRegistry::getTableLocator()->get('Articles');$entities = $articles->newEntities($data);$result = $articles->saveMany($entities);
The result will be updated entities on success or false on failure.
New in version 3.2.8.
Bulk Updates
Cake\ORM\Table::updateAll($fields, $conditions)
There may be times when updating rows individually is not efficient or necessary. In these cases it is more efficient touse a bulk-update to modify many rows at once, by assigning the new field values, and conditions for the update:// Publish all the unpublished articles.
function publishAllUnpublished(){$this->updateAll([ // fields'published' => true,'publish_date' => FrozenTime::now()(continues on next page)

More Information

587

CakePHP Book, Release 3.10

(continued from previous page)],[ // conditions'published' => false]);}
If you need to do bulk updates and use SQL expressions, you will need to use an expression object as updateAll()
uses prepared statements under the hood:use Cake\Database\Expression\QueryExpression;...
function incrementCounters(){$expression = new QueryExpression('view_count = view_count + 1');
$this->updateAll([$expression], ['published' => true]);}
A bulk-update will be considered successful if 1 or more rows are updated.
Warning: updateAll will not trigger beforeSave/afterSave events. If you need those first load a collection ofrecords and update them.
updateAll() is for convenience only. You can use this more flexible interface as well:// Publish all the unpublished articles.
function publishAllUnpublished(){$this->query()->update()->set(['published' => true])->where(['published' => false])->execute();}Also see: Updating Data.

Deleting Data
class Cake\ORM\Table
Cake\ORM\Table::delete(Entity $entity, $options = [])Once you’ve loaded an entity you can delete it by calling the originating table’s delete method:// In a controller.
$entity = $this->Articles->get(2);$result = $this->Articles->delete($entity);
When deleting entities a few things happen:
588

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

1. The delete rules will be applied. If the rules fail, deletion will be prevented.
2. The Model.beforeDelete event is triggered. If this event is stopped, the delete will be aborted and the event’s
result will be returned.
3. The entity will be deleted.
4. All dependent associations will be deleted. If associations are being deleted as entities, additional events will bedispatched.
5. Any junction table records for BelongsToMany associations will be removed.
6. The Model.afterDelete event will be triggered.
By default all deletes happen within a transaction. You can disable the transaction with the atomic option:$result = $this->Articles->delete($entity, ['atomic' => false]);Cascading Deletes
When deleting entities, associated data can also be deleted. If your HasOne and HasMany associations are configured
as dependent, delete operations will ‘cascade’ to those entities as well. By default entities in associated tables are
removed using Cake\ORM\Table::deleteAll(). You can elect to have the ORM load related entities, and deletethem individually by setting the cascadeCallbacks option to true. A sample HasMany association with both these
options enabled would be:// In a Table's initialize method.
$this->hasMany('Comments', ['dependent' => true,'cascadeCallbacks' => true,]);

Note: Setting cascadeCallbacks to true, results in considerably slower deletes when compared to bulk deletes. The
cascadeCallbacks option should only be enabled when your application has important work handled by event listeners.

Bulk Deletes
Cake\ORM\Table::deleteAll($conditions)
There may be times when deleting rows one by one is not efficient or useful. In these cases it is more performant touse a bulk-delete to remove many rows at once:// Delete all the spamfunction destroySpam(){return $this->deleteAll(['is_spam' => true]);}
A bulk-delete will be considered successful if 1 or more rows are deleted. The function returns the number of deleted
records as an integer.
Warning: deleteAll will not trigger beforeDelete/afterDelete events. If you need callbacks triggered, first load theentities with find() and delete them in a loop.

More Information

589

CakePHP Book, Release 3.10

Strict Deletes
Cake\ORM\Table::deleteOrFail($entity, $options = [])Using this method will throw an Cake\ORM\Exception\PersistenceFailedException if :• the entity is new• the entity has no primary key value• application rules checks failed• the delete was aborted by a callback.
If you want to track down the entity that failed to save, you can use the Cake\ORMException\
PersistenceFailedException::getEntity() method:try {$table->deleteOrFail($entity);} catch (\Cake\ORM\Exception\PersistenceFailedException $e) {echo $e->getEntity();}
As this internally performs a Cake\ORM\Table::delete() call, all corresponding delete events will be triggered.
New in version 3.4.1.

Associations - Linking Tables Together
Defining relations between different objects in your application should be a natural process. For example, an article
may have many comments, and belong to an author. Authors may have many articles and comments. CakePHP makes
managing these associations easy. The four association types in CakePHP are: hasOne, hasMany, belongsTo, andbelongsToMany.
Relationship

Association Type

Exampleone to one
one to many
many to one
many to many

hasOnehasMany
belongsTo
belongsToMany

A user has one profile.
A user can have multiple articles.
Many articles belong to a user.
Tags belong to many articles.

Associations are defined during the initialize() method of your table object. Methods matching the association
type allow you to define the associations in your application. For example if we wanted to define a belongsTo associationin our ArticlesTable:
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->belongsTo('Authors');
}
}

590

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

The simplest form of any association setup takes the table alias you want to associate with. By default all of the detailsof an association will use the CakePHP conventions. If you want to customize how your associations are handled you
can modify them with setters:
class ArticlesTable extends Table{
public function initialize(array $config){$this->belongsTo('Authors', ['className' => 'Publishing.Authors'])->setForeignKey('authorid')->setProperty('person');}}You can also use arrays to customize your associations:$this->belongsTo('Authors', ['className' => 'Publishing.Authors','foreignKey' => 'authorid','propertyName' => 'person']);
However, arrays do not offer the typehinting and autocomplete benefits that the fluent interface does.
The same table can be used multiple times to define different types of associations. For example consider a case where
you want to separate approved comments and those that have not been moderated yet:class ArticlesTable extends Table{
public function initialize(array $config){$this->hasMany('Comments')->setConditions(['approved' => true]);$this->hasMany('UnapprovedComments', ['className' => 'Comments'])->setConditions(['approved' => false])->setProperty('unapproved_comments');}}
As you can see, by specifying the className key, it is possible to use the same table as different associations for thesame table. You can even create self-associated tables to create parent-child relationships:class CategoriesTable extends Table{
public function initialize(array $config){$this->hasMany('SubCategories', ['className' => 'Categories']);(continues on next page)

More Information

591

CakePHP Book, Release 3.10

(continued from previous page)$this->belongsTo('ParentCategories', ['className' => 'Categories']);}}
You can also setup associations in mass by making a single call to Table::addAssociations() which accepts anarray containing a set of table names indexed by association type as an argument:
class PostsTable extends Table{
public function initialize(array $config){$this->addAssociations(['belongsTo' => ['Users' => ['className' => 'App\Model\Table\UsersTable']],'hasMany' => ['Comments'],'belongsToMany' => ['Tags']]);}}
Each association type accepts multiple associations where the keys are the aliases, and the values are association config
data. If numeric keys are used the values will be treated as association aliases.
HasOne Associations
Let’s set up a Users table with a hasOne relationship to the Addresses table.
First, your database tables need to be keyed correctly. For a hasOne relationship to work, one table has to contain aforeign key that points to a record in the other table. In this case, the Addresses table will contain a field called ‘user_id’.
The basic pattern is:
hasOne: the other model contains the foreign key.
Relation

SchemaUsers hasOne Addresses
Doctors hasOne Mentors

addresses.user_id
mentors.doctor_id

Note: It is not mandatory to follow CakePHP conventions, you can override the name of any foreignKey in yourassociations definitions. Nevertheless, sticking to conventions will make your code less repetitive, easier to read and tomaintain.
Once you create the UsersTable and AddressesTable classes, you can make the association with the following code:class UsersTable extends Table{
public function initialize(array $config){(continues on next page)

592

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$this->hasOne('Addresses');}}If you need more control, you can define your associations using the setters. For example, you might want to limit theassociation to include only certain records:
class UsersTable extends Table{
public function initialize(array $config){$this->hasOne('Addresses')->setName('Addresses')->setConditions(['Addresses.primary' => '1'])->setDependent(true);}}If you want to break different addresses into multiple associations, you can do something like:class UsersTable extends Table{
public function initialize(array $config){$this->hasOne('HomeAddress', ['className' => 'Addresses'])->setProperty('home_address')->setConditions(['HomeAddress.label' => 'Home'])->setDependent(true);$this->hasOne('WorkAddress', ['className' => 'Addresses'])->setProperty('work_address')->setConditions(['WorkAddress.label' => 'Work'])->setDependent(true);}}Note: If a column is shared by multiple hasOne associations, you must qualify it with the association alias. In theabove example, the ‘label’ column is qualified with the ‘HomeAddress’ and ‘WorkAddress’ aliases.
Possible keys for hasOne association arrays include:• className: The class name of the other table. This is the same name used when getting an instance of thetable. In the ‘Users hasOne Addresses’ example, it should be ‘Addresses’. The default value is the name of theassociation.
• foreignKey: The name of the foreign key column in the other table. The default value is the underscored, singularname of the current model, suffixed with ‘_id’ such as ‘user_id’ in the above example.
• bindingKey: The name of the column in the current table used to match the foreignKey. The default value isthe primary key of the current table such as ‘id’ of Users in the above example.

More Information

593

CakePHP Book, Release 3.10

• conditions: An array of find() compatible conditions such as ['Addresses.primary' => true]• joinType: The type of the join used in the SQL query. Accepted values are ‘LEFT’ and ‘INNER’. You can use‘INNER’ to get results only where the association is set. The default value is ‘LEFT’.
• dependent: When the dependent key is set to true, and an entity is deleted, the associated model records arealso deleted. In this case we set it to true so that deleting a User will also delete her associated Address.
• cascadeCallbacks: When this and dependent are true, cascaded deletes will load and delete entities so thatcallbacks are properly triggered. When false, deleteAll() is used to remove associated data and no callbacks
are triggered.
• propertyName: The property name that should be filled with data from the associated table into the source table
results. By default this is the underscored & singular name of the association so address in our example.
• strategy: The query strategy used to load matching record from the other table. Accepted values are ‘join’ and‘select’. Using ‘select’ will generate a separate query. The default is ‘join’.
• finder: The finder method to use when loading associated records.
Once this association has been defined, find operations on the Users table can contain the Address record if it exists:// In a controller or table method.
$query = $users->find('all')->contain(['Addresses']);foreach ($query as $user) {echo $user->address->street;}
The above would emit SQL that is similar to:
SELECT * FROM users INNER JOIN addresses ON addresses.user_id = users.id;

BelongsTo Associations
Now that we have Address data access from the User table, let’s define a belongsTo association in the Addresses table inorder to get access to related User data. The belongsTo association is a natural complement to the hasOne and hasMany
associations - it allows us to see related data from the other direction.
When keying your database tables for a belongsTo relationship, follow this convention:
belongsTo: the current model contains the foreign key.
Relation

SchemaAddresses belongsTo Users
Mentors belongsTo Doctors

addresses.user_id
mentors.doctor_id

Tip: If a table contains a foreign key, it belongs to the other table.
We can define the belongsTo association in our Addresses table as follows:class AddressesTable extends Table{
public function initialize(array $config){(continues on next page)

594

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$this->belongsTo('Users');}}
We can also define a more specific relationship using the setters:
class AddressesTable extends Table{
public function initialize(array $config){// Prior to 3.4 version, use foreignKey() and joinType()$this->belongsTo('Users')->setForeignKey('user_id')->setJoinType('INNER');}}
Possible keys for belongsTo association arrays include:• className: The class name of the other table. This is the same name used when getting an instance of thetable. In the ‘Addresses belongsTo Users’ example, it should be ‘Users’. The default value is the name of theassociation.
• foreignKey: The name of the foreign key column in the current table. The default value is the underscored,
singular name of the other model, suffixed with ‘_id’ such as ‘user_id’ in the above example.
• bindingKey: The name of the column in the other table used to match the foreignKey. The default value isthe primary key of the other table such as ‘id’ of Users in the above example.
• conditions: An array of find() compatible conditions or SQL strings such as ['Users.active' => true]• joinType: The type of the join used in the SQL query. Accepted values are ‘LEFT’ and ‘INNER’. You can use‘INNER’ to get results only where the association is set. The default value is ‘LEFT’.
• propertyName: The property name that should be filled with data from the associated table into the source table
results. By default this is the underscored & singular name of the association so user in our example.
• strategy: The query strategy used to load matching record from the other table. Accepted values are ‘join’ and‘select’. Using ‘select’ will generate a separate query. The default is ‘join’.
• finder: The finder method to use when loading associated records.
Once this association has been defined, find operations on the Addresses table can contain the User record if it exists:// In a controller or table method.
$query = $addresses->find('all')->contain(['Users']);foreach ($query as $address) {echo $address->user->username;}
The above would output SQL similar to:
SELECT * FROM addresses LEFT JOIN users ON addresses.user_id = users.id;

More Information

595

CakePHP Book, Release 3.10

HasMany Associations
An example of a hasMany association is “Articles hasMany Comments”. Defining this association will allow us tofetch an article’s comments when the article is loaded.
When creating your database tables for a hasMany relationship, follow this convention:
hasMany: the other model contains the foreign key.
Relation

SchemaArticles hasMany Comments
Products hasMany Options
Doctors hasMany Patients

Comments.article_id
Options.product_id
Patients.doctor_id

We can define the hasMany association in our Articles model as follows:class ArticlesTable extends Table{
public function initialize(array $config){$this->hasMany('Comments');}}
We can also define a more specific relationship using the setters:
class ArticlesTable extends Table{
public function initialize(array $config){$this->hasMany('Comments')->setForeignKey('article_id')->setDependent(true);}}
Sometimes you may want to configure composite keys in your associations:// Within ArticlesTable::initialize() call$this->hasMany('Comments')->setForeignKey(['article_id','article_hash']);
Relying on the example above, we have passed an array containing the desired composite keys to setForeignKey().
By default the bindingKey would be automatically defined as id and hash respectively, but let’s assume that you needto specify different binding fields than the defaults. You can setup it manually with setBindingKey():// Within ArticlesTable::initialize() call$this->hasMany('Comments')->setForeignKey(['article_id','article_hash'(continues on next page)

596

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)])->setBindingKey(['whatever_id','whatever_hash']);Like hasOne associations, foreignKey is in the other (Comments) table and bindingKey is in the current (Articles)
table.
Possible keys for hasMany association arrays include:• className: The class name of the other table. This is the same name used when getting an instance of the table.
In the ‘Articles hasMany Comments’ example, it should be ‘Comments’. The default value is the name of theassociation.
• foreignKey: The name of the foreign key column in the other table. The default value is the underscored, singularname of the current model, suffixed with ‘_id’ such as ‘article_id’ in the above example.
• bindingKey: The name of the column in the current table used to match the foreignKey. The default value isthe primary key of the current table such as ‘id’ of Articles in the above example.
• conditions: an array of find() compatible conditions or SQL strings such as ['Comments.visible' => true]• sort: An array of find() compatible order clauses or SQL strings such as ['Comments.created' => 'ASC']• dependent: When dependent is set to true, recursive model deletion is possible. In this example, Comment
records will be deleted when their associated Article record has been deleted.
• cascadeCallbacks: When this and dependent are true, cascaded deletes will load and delete entities so thatcallbacks are properly triggered. When false, deleteAll() is used to remove associated data and no callbacks
are triggered.
• propertyName: The property name that should be filled with data from the associated table into the source table
results. By default this is the underscored & plural name of the association so comments in our example.
• strategy: Defines the query strategy to use. Defaults to ‘select’. The other valid value is ‘subquery’, which
replaces the IN list with an equivalent subquery.
• saveStrategy: Either ‘append’ or ‘replace’. Defaults to ‘append’. When ‘append’ the current records are appended to any records in the database. When ‘replace’ associated records not in the current set will be removed.
If the foreign key is a nullable column or if dependent is true records will be orphaned.
• finder: The finder method to use when loading associated records.
Once this association has been defined, find operations on the Articles table can contain the Comment records if they
exist:// In a controller or table method.
$query = $articles->find('all')->contain(['Comments']);foreach ($query as $article) {echo $article->comments[0]->text;}
The above would output SQL similar to:
SELECT * FROM articles;
SELECT * FROM comments WHERE article_id IN (1, 2, 3, 4, 5);
When the subquery strategy is used, SQL similar to the following will be generated:

More Information

597

CakePHP Book, Release 3.10

SELECT * FROM articles;
SELECT * FROM comments WHERE article_id IN (SELECT id FROM articles);You may want to cache the counts for your hasMany associations. This is useful when you often need to show the numberof associated records, but don’t want to load all the records just to count them. For example, the comment count on any
given article is often cached to make generating lists of articles more efficient. You can use the CounterCacheBehavior
to cache counts of associated records.
You should make sure that your database tables do not contain columns that match association property names. If
for example you have counter fields that conflict with association properties, you must either rename the association
property, or the column name.
BelongsToMany Associations

Note: In 3.0 and onward hasAndBelongsToMany / HABTM has been renamed to belongsToMany / BTM.
An example of a BelongsToMany association is “Article BelongsToMany Tags”, where the tags from one article areshared with other articles. BelongsToMany is often referred to as “has and belongs to many”, and is a classic “manyto many” association.
The main difference between hasMany and BelongsToMany is that the link between the models in a BelongsToMany
association is not exclusive. For example, we are joining our Articles table with a Tags table. Using ‘funny’ as a Tag
for my Article, doesn’t “use up” the tag. I can also use it on the next article I write.
Three database tables are required for a BelongsToMany association. In the example above we would need tables
for articles, tags and articles_tags. The articles_tags table contains the data that links tags and articles
together. The joining table is named after the two tables involved, separated with an underscore by convention. In its
simplest form, this table consists of article_id and tag_id.
belongsToMany requires a separate join table that includes both model names.
Relationship

Join Table Fields

Articles belongsToMany Tags
Patients belongsToMany Doctors

articles_tags.id, articles_tags.tag_id, articles_tags.article_id
doctors_patients.id, doctors_patients.doctor_id, doctors_patients.patient_id.

We can define the belongsToMany association in both our models as follows:// In src/Model/Table/ArticlesTable.php
class ArticlesTable extends Table{
public function initialize(array $config){$this->belongsToMany('Tags');}}// In src/Model/Table/TagsTable.php
class TagsTable extends Table{
public function initialize(array $config){(continues on next page)

598

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$this->belongsToMany('Articles');}}
We can also define a more specific relationship using configuration:// In src/Model/Table/TagsTable.php
class TagsTable extends Table{
public function initialize(array $config){$this->belongsToMany('Articles', ['joinTable' => 'articles_tags',]);}}
Possible keys for belongsToMany association arrays include:• className: The class name of the other table. This is the same name used when getting an instance of thetable. In the ‘Articles belongsToMany Tags’ example, it should be ‘Tags’. The default value is the name of theassociation.
• joinTable: The name of the join table used in this association (if the current table doesn’t adhere to the naming
convention for belongsToMany join tables). By default this table name will be used to load the Table instancefor the join table.
• foreignKey: The name of the foreign key that references the current model found on the join table, or list in caseof composite foreign keys. This is especially handy if you need to define multiple belongsToMany relationships.
The default value for this key is the underscored, singular name of the current model, suffixed with ‘_id’.
• bindingKey: The name of the column in the current table, that will be used for matching the foreignKey.
Defaults to the primary key.
• targetForeignKey: The name of the foreign key that references the target model found on the join model, or listin case of composite foreign keys. The default value for this key is the underscored, singular name of the target
model, suffixed with ‘_id’.
• conditions: An array of find() compatible conditions. If you have conditions on an associated table, you
should use a ‘through’ model, and define the necessary belongsTo associations on it.
• sort: an array of find() compatible order clauses.
• dependent: When the dependent key is set to false, and an entity is deleted, the data of the join table will not
be deleted.
• through: Allows you to provide either the alias of the Table instance you want used on the join table, or the
instance itself. This makes customizing the join table keys possible, and allows you to customize the behavior of
the pivot table.
• cascadeCallbacks: When this is true, cascaded deletes will load and delete entities so that callbacks are properly
triggered on join table records. When false, deleteAll() is used to remove associated data and no callbacks
are triggered. This defaults to false to help reduce overhead.
• propertyName: The property name that should be filled with data from the associated table into the source table
results. By default this is the underscored & plural name of the association, so tags in our example.
• strategy: Defines the query strategy to use. Defaults to ‘select’. The other valid value is ‘subquery’, which
replaces the IN list with an equivalent subquery.
More Information

599

CakePHP Book, Release 3.10

• saveStrategy: Either ‘append’ or ‘replace’. Defaults to ‘replace’. Indicates the mode to be used for saving
associated entities. The former will only create new links between both side of the relation and the latter will doa wipe and replace to create the links between the passed entities when saving.
• finder: The finder method to use when loading associated records.
Once this association has been defined, find operations on the Articles table can contain the Tag records if they exist:// In a controller or table method.
$query = $articles->find('all')->contain(['Tags']);foreach ($query as $article) {echo $article->tags[0]->text;}
The above would output SQL similar to:
SELECT * FROM articles;
SELECT * FROM tags
INNER JOIN articles_tags ON (tags.id = article_tags.tag_id
AND article_id IN (1, 2, 3, 4, 5));
When the subquery strategy is used, SQL similar to the following will be generated:
SELECT * FROM articles;
SELECT * FROM tags
INNER JOIN articles_tags ON (tags.id = article_tags.tag_id
AND article_id IN (SELECT id FROM articles));

Using the ‘through’ Option
If you plan on adding extra information to the join/pivot table, or if you need to use join columns outside of theconventions, you will need to define the through option. The through option provides you full control over how the
belongsToMany association will be created.
It is sometimes desirable to store additional data with a many to many association. Consider the following:
Student BelongsToMany Course
Course BelongsToMany Student
A Student can take many Courses and a Course can be taken by many Students. This is a simple many to many
association. The following table would suffice:id | student_id | course_id
Now what if we want to store the number of days that were attended by the student on the course and their final grade?
The table we’d want would be:
id | student_id | course_id | days_attended | grade
The way to implement our requirement is to use a join model, otherwise known as a hasMany through association.
That is, the association is a model itself. So, we can create a new model CoursesMemberships. Take a look at thefollowing models:
600

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

class StudentsTable extends Table{
public function initialize(array $config){$this->belongsToMany('Courses', ['through' => 'CoursesMemberships',]);}}class CoursesTable extends Table{
public function initialize(array $config){$this->belongsToMany('Students', ['through' => 'CoursesMemberships',]);}}class CoursesMembershipsTable extends Table{
public function initialize(array $config){$this->belongsTo('Students');$this->belongsTo('Courses');}}
The CoursesMemberships join table uniquely identifies a given Student’s participation on a Course in addition to extra
meta-information.
Default Association Conditions
The finder option allows you to use a custom finder to load associated record data. Using a finder method lets you
encapsulate and reuse your query logic:// When the authors association is loaded,// AuthorsTable::findActive() will be called.
$this->belongsTo('Authors')->setFinder('active')// Pass options to the association finder// The passed options will be added to the ``$options`` parameter// of findActive()$this->belongsTo('Authors')->setFinder(['active' => ['temporary' => true]]);There are some limitations when using finders to load data in associations that are loaded using joins (belongsTo/hasOne). Only the following aspects of the query will be applied to the root query:• WHERE conditions.
• Additional joins.
More Information

601

CakePHP Book, Release 3.10

• Contained associations.
Other aspects of the query, such as selected columns, order, group by, having and other sub-statements, will not beapplied to the root query. Associations that are not loaded through joins (hasMany/belongsToMany), do not have theabove restrictions and can also use result formatters or map/reduce functions.
Loading Associations
Once you’ve defined your associations you can eager load associations when fetching results.

Behaviors
Behaviors are a way to organize and enable horizontal re-use of Model layer logic. Conceptually they are similar totraits. However, behaviors are implemented as separate classes. This allows them to hook into the life-cycle callbacks
that models emit, while providing trait-like features.
Behaviors provide a convenient way to package up behavior that is common across many models. For example,
CakePHP includes a TimestampBehavior. Many models will want timestamp fields, and the logic to manage thesefields is not specific to any one model. It is these kinds of scenarios that behaviors are a perfect fit for.
Using Behaviors
Behaviors provide an easy way to create horizontally re-usable pieces of logic related to table classes. You may bewondering why behaviors are regular classes and not traits. The primary reason for this is event listeners. While traits
would allow for re-usable pieces of logic, they would complicate binding events.
To add a behavior to your table you can call the addBehavior() method. Generally the best place to do this is in theinitialize() method:
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp');}}As with associations, you can use plugin syntax and provide additional configuration options:namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp', ['events' => [(continues on next page)

602

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)'Model.beforeSave' => ['created_at' => 'new','modified_at' => 'always'
]
]
]);
}
}

Core Behaviors
CounterCache
class Cake\ORM\Behavior\CounterCacheBehavior
Often times web applications need to display counts of related objects. For example, when showing a list of articles
you may want to display how many comments it has. Or when showing a user you might want to show how manyfriends/followers she has. The CounterCache behavior is intended for these situations. CounterCache will update afield in the associated models assigned in the options when it is invoked. The fields should exist in the database and beof the type INT.
Basic Usage
You enable the CounterCache behavior like any other behavior, but it won’t do anything until you configure somerelations and the field counts that should be stored on each of them. Using our example below, we could cache thecomment count for each article with the following:class CommentsTable extends Table{
public function initialize(array $config){$this->addBehavior('CounterCache', ['Articles' => ['comment_count']]);}}
The CounterCache configuration should be a map of relation names and the specific configuration for that relation.
The counter’s value will be updated each time an entity is saved or deleted. The counter will not be updated when you
use updateAll() or deleteAll(), or execute SQL you have written.

More Information603

CakePHP Book, Release 3.10

Advanced Usage
If you need to keep a cached counter for less than all of the related records, you can supply additional conditions orfinder methods to generate a counter value:// Use a specific find method.
// In this case find(published)$this->addBehavior('CounterCache', ['Articles' => ['comment_count' => ['finder' => 'published']]]);
If you don’t have a custom finder method you can provide an array of conditions to find records instead:$this->addBehavior('CounterCache', ['Articles' => ['comment_count' => ['conditions' => ['Comments.spam' => false]]]]);
If you want CounterCache to update multiple fields, for example both showing a conditional count and a basic countyou can add these fields in the array:$this->addBehavior('CounterCache', ['Articles' => ['comment_count','published_comment_count' => ['finder' => 'published']]]);
If you want to calculate the CounterCache field value on your own, you can set the ignoreDirty option to true. This
will prevent the field from being recalculated if you’ve set it dirty before:$this->addBehavior('CounterCache', ['Articles' => ['comment_count' => ['ignoreDirty' => true]]]);
Lastly, if a custom finder and conditions are not suitable you can provide a callback function. Your function must returnthe count value to be stored:$this->addBehavior('CounterCache', ['Articles' => ['rating_avg' => function ($event, $entity, $table, $original) {return 4.5;
(continues on next page)

604

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)}]]);Your function can return false to skip updating the counter column, or a Query object that produced the count value.
If you return a Query object, your query will be used as a subquery in the update statement. The $table parameter
refers to the table object holding the behavior (not the target relation) for convenience. The callback is invoked at least
once with $original set to false. If the entity-update changes the association then the callback is invoked a second
time with true, the return value then updates the counter of the previously associated item.
Note: The CounterCache behavior works for belongsTo associations only. For example for “Comments belongsTo
Articles”, you need to add the CounterCache behavior to the CommentsTable in order to generate comment_countfor Articles table.
It is possible though to make this work for belongsToMany associations. You need to enable the CounterCache behavior in a custom through table configured in association options and set the cascadeCallbacks configuration option
to true. See how to configure a custom join table Using the ‘through’ Option.
Changed in version 3.6.0: Returning false to skip updates was added.
Timestampclass Cake\ORM\Behavior\TimestampBehavior
The timestamp behavior allows your table objects to update one or more timestamps on each model event. This is
primarily used to populate data into created and modified fields. However, with some additional configuration, you
can update any timestamp/datetime column on any event a table publishes.
Basic Usage
You enable the timestamp behavior like any other behavior:class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp');}}
The default configuration will do the following:• When a new entity is saved the created and modified fields will be set to the current time.
• When an entity is updated, the modified field is set to the current time.

More Information605

CakePHP Book, Release 3.10

Using and Configuring the Behavior
If you need to modify fields with different names, or want to update additional timestamp fields on custom events you
can use some additional configuration:
class OrdersTable extends Table{
public function initialize(array $config){$this->addBehavior('Timestamp', ['events' => ['Model.beforeSave' => ['created_at' => 'new','updated_at' => 'always',],'Orders.completed' => ['completed_at' => 'always'
]
]
]);
}
}
As you can see above, in addition to the standard Model.beforeSave event, we are also updating the completed_at
column when orders are completed.
Updating Timestamps on Entities
Sometimes you’ll want to update just the timestamps on an entity without changing any other properties. This issometimes referred to as ‘touching’ a record. In CakePHP you can use the touch() method to do exactly this:// Touch based on the Model.beforeSave event.
$articles->touch($article);// Touch based on a specific event.
$orders->touch($order, 'Orders.completed');After you have saved the entity, the field is updated.
Touching records can be useful when you want to signal that a parent resource has changed when a child resource iscreated/updated. For example: updating an article when a new comment is added.
Saving Updates Without Modifying Timestamps
To disable the automatic modification of the updated timestamp column when saving an entity you can mark theattribute as ‘dirty’:// Mark the modified column as dirty making// the current value be set on update.
$order->setDirty('modified', true);(continues on next page)

606

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)// Prior to 3.4.0$order->dirty('modified', true);

Translateclass Cake\ORM\Behavior\TranslateBehavior
The Translate behavior allows you to create and retrieve translated copies of your entities in multiple languages. It doesso by using a separate i18n table where it stores the translation for each of the fields of any given Table object that it’sbound to.
Warning: The TranslateBehavior does not support composite primary keys at this point in time.

A Quick Tour
After creating the i18n table in your database attach the behavior to any Table object you want to make translatable:class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Translate', ['fields' => ['title']]);}}
Now, select a language to be used for retrieving entities by changing the application language, which will affect alltranslations:// In a controller. Change the locale, e.g. to Spanish
I18n::setLocale('es');$this->loadModel('Articles');Then, get an existing entity:$article = $this->Articles->get(12);echo $article->title; // Echoes 'A title', not translated yet
Next, translate your entity:$article->title = 'Un Artículo';$this->Articles->save($article);
You can try now getting your entity again:$article = $this->Articles->get(12);echo $article->title; // Echoes 'Un Artículo', yay piece of cake!
Working with multiple translations can be done by using a special trait in your Entity class:More Information

607

CakePHP Book, Release 3.10

use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;class Article extends Entity{
use TranslateTrait;}
Now you can find all translations for a single entity:$article = $this->Articles->find('translations')->first();echo $article->translation('es')->title; // 'Un Artículo'
echo $article->translation('en')->title; // 'An Article';
It is equally easy to save multiple translations at once:$article->translation('es')->title = 'Otro Título';$article->translation('fr')->title = 'Un autre Titre';$this->Articles->save($article);
If you want to go deeper on how it works or how to tune the behavior for your needs, keep on reading the rest of thischapter.
Initializing the i18n Database Table
In order to use the behavior, you need to create a i18n table with the correct schema. Currently the only way of loading
the i18n table is by manually running the following SQL script in your database:
CREATE TABLE i18n (id int NOT NULL auto_increment,
locale varchar(6) NOT NULL,
model varchar(255) NOT NULL,
foreign_key int(10) NOT NULL,
field varchar(255) NOT NULL,
content text,
PRIMARY KEY(id),
UNIQUE INDEX I18N_LOCALE_FIELD(locale, model, foreign_key, field),
INDEX I18N_FIELD(model, foreign_key, field));
The schema is also available as sql file in /config/schema/i18n.sql.
A note on language abbreviations: The Translate Behavior doesn’t impose any restrictions on the language identifier,the possible values are only restricted by the locale column type/size. locale is defined as varchar(6) in case youwant to use abbreviations like es-419 (Spanish for Latin America, language abbreviation with area code UN M.49145 ).
Tip:
It’s wise to use the same language abbreviations as required for Internationalization and Localization.
Thus you are consistent and switching the language works identical for both, the Translate Behaviour andInternationalization and Localization.
145 https://en.wikipedia.org/wiki/UN_M.49

608

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

So it’s recommended to use either the two letter ISO code of the language like en, fr, de or the full locale name suchas fr_FR, es_AR, da_DK which contains both the language and the country where it is spoken.
Attaching the Translate Behavior to Your Tables
Attaching the behavior can be done in the initialize() method in your Table class:class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Translate', ['fields' => ['title', 'body']]);}}
The first thing to note is that you are required to pass the fields key in the configuration array. This list of fields isneeded to tell the behavior what columns will be able to store translations.
Using a Separate Translations Table
If you wish to use a table other than i18n for translating a particular repository, you can specify the name of the tableclass name for your custom table in the behavior’s configuration. This is common when you have multiple tables totranslate and you want a cleaner separation of the data that is stored for each different table:class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Translate', ['fields' => ['title', 'body'],'translationTable' => 'ArticlesI18n']);}}
You need to make sure that any custom table you use has the columns field, foreign_key, locale and model.
Reading Translated Content
As shown above you can use the setLocale() method to choose the active translation for entities that are loaded:// Load I18n core functions at the beginning of your Controller:
use Cake\I18n\I18n;// Then you can change the language in your action:
I18n::setLocale('es');$this->loadModel('Articles');// All entities in results will contain spanish translation$results = $this->Articles->find()->all();
This method works with any finder in your tables. For example, you can use TranslateBehavior with find('list'):More Information609

CakePHP Book, Release 3.10

I18n::setLocale('es');$data = $this->Articles->find('list')->toArray();// Data will contain[1 => 'Mi primer artículo', 2 => 'El segundo artículo', 15 => 'Otro articulo' ...]

Retrieve All Translations For An Entity
When building interfaces for updating translated content, it is often helpful to show one or more translation(s) at thesame time. You can use the translations finder for this:// Find the first article with all corresponding translations$article = $this->Articles->find('translations')->first();In the example above you will get a list of entities back that have a _translations property set. This property willcontain a list of translation data entities. For example the following properties would be accessible:// Outputs 'en'echo $article->_translations['en']->locale;// Outputs 'title'echo $article->_translations['en']->field;// Outputs 'My awesome post!'
echo $article->_translations['en']->body;
A more elegant way for dealing with this data is by adding a trait to the entity class that is used for your table:
use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;class Article extends Entity{
use TranslateTrait;}
This trait contains a single method called translation, which lets you access or create new translation entities on thefly:// Outputs 'title'echo $article->translation('en')->title;// Adds a new translation data entity to the article$article->translation('de')->title = 'Wunderbar';

610

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Limiting the Translations to be Retrieved
You can limit the languages that are fetched from the database for a particular set of records:$results = $this->Articles->find('translations', ['locales' => ['en', 'es']]);$article = $results->first();$spanishTranslation = $article->translation('es');$englishTranslation = $article->translation('en');Preventing Retrieval of Empty Translations
Translation records can contain any string, if a record has been translated and stored as an empty string (‘’) the translate
behavior will take and use this to overwrite the original field value.
If this is undesired, you can ignore translations which are empty using the allowEmptyTranslations config key:class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Translate', ['fields' => ['title', 'body'],'allowEmptyTranslations' => false]);}}
The above would only load translated data that had content.
Retrieving All Translations For Associations
It is also possible to find translations for any association in a single find operation:$article = $this->Articles->find('translations')->contain(['Categories' => function ($query) {return $query->find('translations');}])->first();// Outputs 'Programación'
echo $article->categories[0]->translation('es')->name;
This assumes that Categories has the TranslateBehavior attached to it. It simply uses the query builder function forthe contain clause to use the translations custom finder in the association.

More Information

611

CakePHP Book, Release 3.10

Retrieving one language without using I18n::setLocale
calling I18n::setLocale('es'); changes the default locale for all translated finds, there may be times you wish to retrieve translated content without modifying the application’s state. For these scenarios use the behavior’s setLocale()method:I18n::setLocale('en'); // reset for illustration$this->loadModel('Articles');// specific locale. Use locale() prior to 3.6$this->Articles->setLocale('es');$article = $this->Articles->get(12);echo $article->title; // Echoes 'Un Artículo', yay piece of cake!
Note that this only changes the locale of the Articles table, it would not affect the language of associated data. To affectassociated data it’s necessary to call the method on each table, for example:
I18n::setLocale('en'); // reset for illustration$this->loadModel('Articles');// Use locale() prior to 3.6$this->Articles->setLocale('es');$this->Articles->Categories->setLocale('es');$data = $this->Articles->find('all', ['contain' => ['Categories']]);
This example also assumes that Categories has the TranslateBehavior attached to it.
Querying Translated Fields
TranslateBehavior does not substitute find conditions by default. You need to use translationField() method tocompose find conditions on translated fields:// Use locale() prior to 3.6$this->Articles->setLocale('es');$data = $this->Articles->find()->where([$this->Articles->translationField('title') => 'Otro Título']);

Saving in Another Language
The philosophy behind the TranslateBehavior is that you have an entity representing the default language, and multiple
translations that can override certain fields in such entity. Keeping this in mind, you can intuitively save translations
for any given entity. For example, given the following setup:// in src/Model/Table/ArticlesTable.php
class ArticlesTable extends Table{
public function initialize(array $config)(continues on next page)

612

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page){$this->addBehavior('Translate', ['fields' => ['title', 'body']]);}}// in src/Model/Entity/Article.php
class Article extends Entity{
use TranslateTrait;}// In a Controller$this->loadModel('Articles');$article = new Article(['title' => 'My First Article','body' => 'This is the content','footnote' => 'Some afterwords']);$this->Articles->save($article);
So, after you save your first article, you can now save a translation for it, there are a couple ways to do it. The first one
is setting the language directly into the entity:$article->_locale = 'es';$article->title = 'Mi primer Artículo';$this->Articles->save($article);
After the entity has been saved, the translated field will be persisted as well, one thing to note is that values from thedefault language that were not overridden will be preserved:// Outputs 'This is the content'echo $article->body;// Outputs 'Mi primer Artículo'
echo $article->title;
Once you override the value, the translation for that field will be saved and can be retrieved as usual:$article->body = 'El contendio';$this->Articles->save($article);
The second way to use for saving entities in another language is to set the default language directly to the table:$article->title = 'Mi Primer Artículo';// Use locale() prior to 3.6$this->Articles->setLocale('es');$this->Articles->save($article);
Setting the language directly in the table is useful when you need to both retrieve and save entities for the same language
or when you need to save multiple entities at once.

More Information

613

CakePHP Book, Release 3.10

Saving Multiple Translations
It is a common requirement to be able to add or edit multiple translations to any database record at the same time. Thiscan be done using the TranslateTrait:
use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;class Article extends Entity{
use TranslateTrait;}
Now, You can populate translations before saving them:$translations = ['fr' => ['title' => "Un article"],'es' => ['title' => 'Un artículo']];
foreach ($translations as $lang => $data) {$article->translation($lang)->set($data, ['guard' => false]);}$this->Articles->save($article);
As of 3.3.0, working with multiple translations has been streamlined. You can create form controls for your translated
fields:// In a view template.
<?= $this->Form->create($article); ?><fieldset><legend>French</legend><?= $this->Form->control('_translations.fr.title'); ?><?= $this->Form->control('_translations.fr.body'); ?></fieldset><fieldset><legend>Spanish</legend><?= $this->Form->control('_translations.es.title'); ?><?= $this->Form->control('_translations.es.body'); ?></fieldset>
In your controller, you can marshal the data as normal:$article = $this->Articles->newEntity($this->request->getData());$this->Articles->save($article);This will result in your article, the french and spanish translations all being persisted. You’ll need to remember to add_translations into the $_accessible fields of your entity as well.

614

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Validating Translated Entities
When attaching TranslateBehavior to a model, you can define the validator that should be used when translation
records are created/modified by the behavior during newEntity() or patchEntity():class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Translate', ['fields' => ['title'],'validator' => 'translated']);}}
The above will use the validator created by validationTranslated to validated translated entities.
New in version 3.3.0: Validating translated entities, and streamlined translation saving was added in 3.3.0
Treeclass Cake\ORM\Behavior\TreeBehavior
It’s fairly common to want to store hierarchical data in a database table. Examples of such data might be categories
with unlimited subcategories, data related to a multilevel menu system or a literal representation of hierarchy such as
departments in a company.
Relational databases are usually not well suited for storing and retrieving this type of data, but there are a few known
techniques that can make them effective for working with multi-level information.
The TreeBehavior helps you maintain a hierarchical data structure in the database that can be queried without muchoverhead and helps reconstruct the tree data for finding and displaying processes.
Requirements
This behavior requires the following columns in your table:• parent_id (nullable) The column holding the ID of the parent row• lft (integer, signed) Used to maintain the tree structure• rght (integer, signed) Used to maintain the tree structure
You can configure the name of those fields should you need to customize them. More information on the meaning of
the fields and how they are used can be found in this article describing the MPTT logic146
Warning: The TreeBehavior does not support composite primary keys at this point in time.
146 https://www.sitepoint.com/hierarchical-data-database-2/

More Information

615

CakePHP Book, Release 3.10

A Quick TourYou enable the Tree behavior by adding it to the Table you want to store hierarchical data in:class CategoriesTable extends Table{
public function initialize(array $config){$this->addBehavior('Tree');}}Once added, you can let CakePHP build the internal structure if the table is already holding some rows:// Prior to 3.6.0$categories = TableRegistry::get('Categories');$categories = TableRegistry::getTableLocator()->get('Categories');$categories->recover();
You can verify it works by getting any row from the table and asking for the count of descendants it has:$node = $categories->get(1);echo $categories->childCount($node);
Getting a flat list of the descendants for a node is equally easy:$descendants = $categories->find('children', ['for' => 1]);
foreach ($descendants as $category) {echo $category->name . "\n";}If you need to pass conditions you do so as per normal:$descendants = $categories->find('children', ['for' => 1])->where(['name LIKE' => '%Foo%']);
foreach ($descendants as $category) {echo $category->name . "\n";}If you instead need a threaded list, where children for each node are nested in a hierarchy, you can stack the ‘threaded’finder:$children = $categories->find('children', ['for' => 1])->find('threaded')->toArray();
foreach ($children as $child) {echo "{$child->name} has " . count($child->children) . " direct children";}

616

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Traversing threaded results usually requires recursive functions in, but if you only require a result set containing a single
field from each level so you can display a list, in an HTML select for example, it is better to use the ‘treeList’ finder:$list = $categories->find('treeList');// In a CakePHP template file:echo $this->Form->control('categories', ['options' => $list]);// Or you can output it in plain text, for example in a CLI script
foreach ($list as $categoryName) {echo $categoryName . "\n";}The output will be similar to:
My Categories_Fun__Sport___Surfing___Skating_Trips__National__International
The treeList finder takes a number of options:• keyPath: A dot separated path to fetch the field to use for the array key, or a closure to return the key out of theprovided row.
• valuePath: A dot separated path to fetch the field to use for the array value, or a closure to return the value outof the provided row.
• spacer: A string to be used as prefix for denoting the depth in the tree for each item
An example of all options in use is:$query = $categories->find('treeList', ['keyPath' => 'url','valuePath' => 'id','spacer' => ' ']);An example using closure:$query = $categories->find('treeList', ['keyPath' => 'url','valuePath' => function($entity){
return $entity->url . ' ' . $entity->id},'spacer' => ' ']);One very common task is to find the tree path from a particular node to the root of the tree. This is useful, for example,
for adding the breadcrumbs list for a menu structure:

More Information

617

CakePHP Book, Release 3.10

$nodeId = 5;
$crumbs = $categories->find('path', ['for' => $nodeId]);
foreach ($crumbs as $crumb) {echo $crumb->name . ' > ';}Trees constructed with the TreeBehavior cannot be sorted by any column other than lft, this is because the internal
representation of the tree depends on this sorting. Luckily, you can reorder the nodes inside the same level without
having to change their parent:$node = $categories->get(5);// Move the node so it shows up one position up when listing children.
$categories->moveUp($node);// Move the node to the top of the list inside the same level.
$categories->moveUp($node, true);// Move the node to the bottom.
$categories->moveDown($node, true);Configuration
If the default column names that are used by this behavior don’t match your own schema, you can provide aliases forthem:public function initialize(array $config){$this->addBehavior('Tree', ['parent' => 'ancestor_id', // Use this instead of parent_id'left' => 'tree_left', // Use this instead of lft'right' => 'tree_right' // Use this instead of rght]);}

Node Level (Depth)
Knowing the depth of tree nodes can be useful when you want to retrieve nodes only upto a certain level for e.g. whengenerating menus. You can use the level option to specify the field that will save level of each node:$this->addBehavior('Tree', ['level' => 'level', // Defaults to null, i.e. no level saving]);
If you don’t want to cache the level using a db field you can use TreeBehavior::getLevel() method to get level ofa node.

618

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Scoping and Multi Trees
Sometimes you want to persist more than one tree structure inside the same table, you can achieve that by using the‘scope’ configuration. For example, in a locations table you may want to create one tree per country:
class LocationsTable extends Table{
public function initialize(array $config){$this->addBehavior('Tree', ['scope' => ['country_name' => 'Brazil']]);}}In the previous example, all tree operations will be scoped to only the rows having the column country_name set to‘Brazil’. You can change the scoping on the fly by using the ‘config’ function:$this->behaviors()->Tree->config('scope', ['country_name' => 'France']);Optionally, you can have a finer grain control of the scope by passing a closure as the scope:$this->behaviors()->Tree->config('scope', function ($query) {$country = $this->getConfigureContry(); // A made-up function
return $query->where(['country_name' => $country]);});

Recovering with custom sort field
New in version 3.0.14.
By default, recover() sorts the items using the primary key. This works great if this is a numeric (auto increment)
column, but can lead to weird results if you use UUIDs.
If you need custom sorting for the recovery, you can set a custom order clause in your config:$this->addBehavior('Tree', ['recoverOrder' => ['country_name' => 'DESC'],]);

Saving Hierarchical Data
When using the Tree behavior, you usually don’t need to worry about the internal representation of the hierarchicalstructure. The positions where nodes are placed in the tree are deduced from the ‘parent_id’ column in each of yourentities:$aCategory = $categoriesTable->get(10);$aCategory->parent_id = 5;$categoriesTable->save($aCategory);
Providing inexistent parent ids when saving or attempting to create a loop in the tree (making a node child of itself)
will throw an exception.

More Information

619

CakePHP Book, Release 3.10

You can make a node a root in the tree by setting the ‘parent_id’ column to null:$aCategory = $categoriesTable->get(10);$aCategory->parent_id = null;$categoriesTable->save($aCategory);
Children for the new root node will be preserved.
Deleting Nodes
Deleting a node and all its sub-tree (any children it may have at any depth in the tree) is trivial:$aCategory = $categoriesTable->get(10);$categoriesTable->delete($aCategory);
The TreeBehavior will take care of all internal deleting operations for you. It is also possible to only delete one nodeand re-assign all children to the immediately superior parent node in the tree:$aCategory = $categoriesTable->get(10);$categoriesTable->removeFromTree($aCategory);$categoriesTable->delete($aCategory);
All children nodes will be kept and a new parent will be assigned to them.
The deletion of a node is based off of the lft and rght values of the entity. This is important to note when looping
through the various children of a node for conditional deletes:$descendants = $teams->find('children', ['for' => 1]);
foreach ($descendants as $descendant) {$team = $teams->get($descendant->id); // search for the up-to-date entity object
if ($team->expired) {$teams->delete($team); // deletion reorders the lft and rght of database entries}}
The TreeBehavior reorders the lft and rght values of records in the table when a node is deleted. As such, the lft andrght values of the entities inside $descendants (saved before the delete operation) will be inaccurate. Entities will
have to be loaded and modified on the fly to prevent inconsistencies in the table.
Creating a Behavior
In the following examples we will create a very simple SluggableBehavior. This behavior will allow us to populate
a slug field with the results of Text::slug() based on another field.
Before we create our behavior we should understand the conventions for behaviors:• Behavior files are located in src/Model/Behavior, or MyPlugin\Model\Behavior.
• Behavior classes should be in the App\Model\Behavior namespace, or MyPlugin\Model\Behavior namespace.
• Behavior class names end in Behavior.
• Behaviors extend Cake\ORM\Behavior.
To create our sluggable behavior. Put the following into src/Model/Behavior/SluggableBehavior.php:
620

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

namespace App\Model\Behavior;
use Cake\ORM\Behavior;class SluggableBehavior extends Behavior{}
Similar to tables, behaviors also have an initialize() hook where you can put your behavior’s initialization code,
if required:public function initialize(array $config){// Some initialization code here}
We can now add this behavior to one of our table classes. In this example we’ll use an ArticlesTable, as articles
often have slug properties for creating friendly URLs:
namespace App\Model\Table;
use Cake\ORM\Table;class ArticlesTable extends Table{
public function initialize(array $config){$this->addBehavior('Sluggable');}}Our new behavior doesn’t do much of anything right now. Next, we’ll add a mixin method and an event listener so thatwhen we save entities we can automatically slug a field.
Defining Mixin Methods
Any public method defined on a behavior will be added as a ‘mixin’ method on the table object it is attached to. If
you attach two behaviors that provide the same methods an exception will be raised. If a behavior provides the same
method as a table class, the behavior method will not be callable from the table. Behavior mixin methods will receive
the exact same arguments that are provided to the table. For example, if our SluggableBehavior defined the following
method:public function slug($value){
return Text::slug($value, $this->_config['replacement']);}
It could be invoked using:$slug = $articles->slug('My article name');More Information

621

CakePHP Book, Release 3.10

Limiting or Renaming Exposed Mixin Methods
When creating behaviors, there may be situations where you don’t want to expose public methods as mixin methods.
In these cases you can use the implementedMethods configuration key to rename or exclude mixin methods. For
example if we wanted to prefix our slug() method we could do the following:protected $_defaultConfig = ['implementedMethods' => ['superSlug' => 'slug',]];
Applying this configuration will make slug() not callable, however it will add a superSlug() mixin method to thetable. Notably if our behavior implemented other public methods they would not be available as mixin methods withthe above configuration.
Since the exposed methods are decided by configuration you can also rename/remove mixin methods when adding abehavior to a table. For example:// In a table's initialize() method.
$this->addBehavior('Sluggable', ['implementedMethods' => ['superSlug' => 'slug',]]);

Defining Event Listeners
Now that our behavior has a mixin method to slug fields, we can implement a callback listener to automatically slug afield when entities are saved. We’ll also modify our slug method to accept an entity instead of just a plain value. Our
behavior should now look like:namespace App\Model\Behavior;use ArrayObject;
use Cake\Datasource\EntityInterface;
use Cake\Event\Event;use Cake\ORM\Behavior;
use Cake\ORM\Entity;
use Cake\ORM\Query;
use Cake\Utility\Text;class SluggableBehavior extends Behavior{
protected $_defaultConfig = ['field' => 'title','slug' => 'slug','replacement' => '-',];
public function slug(EntityInterface $entity){(continues on next page)

622

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

(continued from previous page)$config = $this->config();$value = $entity->get($config['field']);$entity->set($config['slug'], Text::slug($value, $config['replacement']));}
public function beforeSave(Event $event, EntityInterface $entity, ArrayObject$options){$this->slug($entity);}˓→}
The above code shows a few interesting features of behaviors:• Behaviors can define callback methods by defining methods that follow the Lifecycle Callbacks conventions.
• Behaviors can define a default configuration property. This property is merged with the overrides when a behavior
is attached to the table.
To prevent the save from continuing, simply stop event propagation in your callback:public function beforeSave(Event $event, EntityInterface $entity, ArrayObject $options){if (...) {$event->stopPropagation();$event->setResult(false);
return;}$this->slug($entity);}
Alternatively, you can return false from the callback. This has the same effect as stopping event propagation.
Defining Finders
Now that we are able to save articles with slug values, we should implement a finder method so we can fetch articles
by their slug. Behavior finder methods, use the same conventions as Custom Finder Methods do. Our find('slug')
method would look like:public function findSlug(Query $query, array $options){
return $query->where(['slug' => $options['slug']]);}
Once our behavior has the above method we can call it:$article = $articles->find('slug', ['slug' => $value])->first();More Information

623

CakePHP Book, Release 3.10

Limiting or Renaming Exposed Finder Methods
When creating behaviors, there may be situations where you don’t want to expose finder methods, or you need to rename
finders to avoid duplicated methods. In these cases you can use the implementedFinders configuration key to rename
or exclude finder methods. For example if we wanted to rename our find(slug) method we could do the following:protected $_defaultConfig = ['implementedFinders' => ['slugged' => 'findSlug',]];
Applying this configuration will make find('slug') trigger an error. However it will make find('slugged')available. Notably if our behavior implemented other finder methods they would not be available, as they are notincluded in the configuration.
Since the exposed methods are decided by configuration you can also rename/remove finder methods when adding abehavior to a table. For example:// In a table's initialize() method.
$this->addBehavior('Sluggable', ['implementedFinders' => ['slugged' => 'findSlug',]]);

Transforming Request Data into Entity Properties
Behaviors can define logic for how the custom fields they provide are marshalled by implementing the Cake\ORM\
PropertyMarshalInterface. This interface requires a single method to be implemented:
public function buildMarshalMap($marshaller, $map, $options){
return ['custom_behavior_field' => function ($value, $entity) {// Transform the value as necessary
return $value . '123';}];}
The TranslateBehavior has a non-trivial implementation of this interface that you might want to refer to.
New in version 3.3.0: The ability for behaviors to participate in marshalling was added in 3.3.0

624

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Removing Loaded Behaviors
To remove a behavior from your table you can call the removeBehavior() method:// Remove the loaded behavior$this->removeBehavior('Sluggable');Accessing Loaded Behaviors
Once you’ve attached behaviors to your Table instance you can introspect the loaded behaviors, or access specificbehaviors using the BehaviorRegistry:// See which behaviors are loaded$table->behaviors()->loaded();// Check if a specific behavior is loaded.
// Remember to omit plugin prefixes.
$table->behaviors()->has('CounterCache');// Get a loaded behavior// Remember to omit plugin prefixes$table->behaviors()->get('CounterCache');Re-configuring Loaded Behaviors
To modify the configuration of an already loaded behavior you can combine the BehaviorRegistry::get commandwith config command provided by the InstanceConfigTrait trait.
For example if a parent (e.g. an AppTable) class loaded the Timestamp behavior you could do the following to add,
modify or remove the configurations for the behavior. In this case, we will add an event we want Timestamp to respondto:namespace App\Model\Table;
use App\Model\Table\AppTable; // similar to AppController
class UsersTable extends AppTable{
public function initialize(array $options){parent::initialize($options);// e.g. if our parent calls $this->addBehavior('Timestamp');// and we want to add an additional event
if ($this->behaviors()->has('Timestamp')) {$this->behaviors()->get('Timestamp')->config(['events' => ['Users.login' => ['last_login' => 'always'
],
],
]);
(continues on next page)

More Information

625

CakePHP Book, Release 3.10

(continued from previous page)}}}

Schema System
CakePHP features a schema system that is capable of reflecting and generating schema information for tables in SQL
datastores. The schema system can generate/reflect a schema for any SQL platform that CakePHP supports.
The main pieces of the schema system are Cake\Database\Schema\Collection and Cake\Database\Schema\
TableSchema. These classes give you access to database-wide and individual Table object features respectively.
The primary use of the schema system is for Fixtures. However, it can also be used in your application if required.
Schema\TableSchema Objects
class Cake\Database\Schema\TableSchema
The schema subsystem provides a simple TableSchema object to hold data about a table in a database. This object isreturned by the schema reflection features:
use Cake\Database\Schema\TableSchema;// Create a table one column at a time.
$schema = new TableSchema('posts');$schema->addColumn('id', ['type' => 'integer','length' => 11,'null' => false,'default' => null,])->addColumn('title', ['type' => 'string','length' => 255,// Create a fixed length (char field)'fixed' => true])->addConstraint('primary', ['type' => 'primary','columns' => ['id']]);// Schema\TableSchema classes could also be created with array data
$schema = new TableSchema('posts', $columns);
Schema\TableSchema objects allow you to build up information about a table’s schema. It helps to normalize andvalidate the data used to describe a table. For example, the following two forms are equivalent:$schema->addColumn('title', 'string');// and$schema->addColumn('title', ['type' => 'string'
]);

626

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

While equivalent, the 2nd form allows more detail and control. This emulates the existing features available in Schema
files + the fixture schema in 2.x.
Accessing Column Data
Columns are either added as constructor arguments, or via addColumn(). Once fields are added information can be
fetched using column() or columns():// Get the array of data about a column$c = $schema->column('title');// Get the list of all columns.
$cols = $schema->columns();

Indexes and Constraints
Indexes are added using the addIndex(). Constraints are added using addConstraint(). Indexes and constraints
cannot be added for columns that do not exist, as it would result in an invalid state. Indexes are different from constraints,
and exceptions will be raised if you try to mix types between the methods. An example of both methods is:$schema = new TableSchema('posts');$schema->addColumn('id', 'integer')->addColumn('author_id', 'integer')->addColumn('title', 'string')->addColumn('slug', 'string');// Add a primary key.
$schema->addConstraint('primary', ['type' => 'primary','columns' => ['id']]);// Add a unique key$schema->addConstraint('slug_idx', ['columns' => ['slug'],'type' => 'unique',]);// Add index$schema->addIndex('slug_title', ['columns' => ['slug', 'title'],'type' => 'index']);// Add a foreign key$schema->addConstraint('author_id_idx', ['columns' => ['author_id'],'type' => 'foreign','references' => ['authors', 'id'],'update' => 'cascade','delete' => 'cascade']);If you add a primary key constraint to a single integer column it will automatically be converted into a autoincrement/serial column depending on the database platform:
More Information

627

CakePHP Book, Release 3.10

$schema = new TableSchema('posts');$schema->addColumn('id', 'integer')->addConstraint('primary', ['type' => 'primary','columns' => ['id']]);
In the above example the id column would generate the following SQL in MySQL:
CREATE TABLE `posts` (`id` INTEGER AUTO_INCREMENT,PRIMARY KEY (`id`))
If your primary key contains more than one column, none of them will automatically be converted to an auto-increment
value. Instead you will need to tell the table object which column in the composite key you want to auto-increment:$schema = new TableSchema('posts');$schema->addColumn('id', ['type' => 'integer','autoIncrement' => true,])->addColumn('account_id', 'integer')->addConstraint('primary', ['type' => 'primary','columns' => ['id', 'account_id']]);
The autoIncrement option only works with integer and biginteger columns.
Reading Indexes and Constraints
Indexes and constraints can be read out of a table object using accessor methods. Assuming that $schema is a populated
TableSchema instance you could do the following:// Get contraints. Will return the// names of all constraints.
$constraints = $schema->constraints()// Get data about a single constraint.
$constraint = $schema->constraint('author_id_idx')// Get indexes. Will return the// names of all indexes.
$indexes = $schema->indexes()// Get data about a single index.
$index = $schema->index('author_id_idx')

628

Chapter 12. Database Access & ORM

CakePHP Book, Release 3.10

Adding Table Options
Some drivers (primarily MySQL) support and require additional table metadata. In the case of MySQL the CHARSET,COLLATE and ENGINE properties are required for maintaining a table’s structure in MySQL. The following could be
used to add table options:$schema->options(['engine' => 'InnoDB','collate' => 'utf8_unicode_ci',]);
Platform dialects only handle the keys they are interested in and ignore the rest. Not all options are supported on all
platforms.
Converting Tables into SQL
Using the createSql() or dropSql() you can get platform specific SQL for creating or dropping a specific table:$db = ConnectionManager::get('default');$schema = new TableSchema('posts', $fields, $indexes);// Create a table$queries = $schema->createSql($db);
foreach ($queries as $sql) {$db->execute($sql);}// Drop a table$sql = $schema->dropSql($db);$db->execute($sql);
By using a connection’s driver the schema data can be converted into platform specific SQL. The return of createSql
and dropSql is a list of SQL queries required to create a table and the required indexes. Some platforms may require
multiple statements to create tables with comments and/or indexes. An array of queries is always returned.
Schema Collectionsclass Cake\Database\Schema\Collection
Collection provides access to the various tables available on a connection. You can use it to get the list of tables orreflect tables into TableSchema objects. Basic usage of the class looks like:$db = ConnectionManager::get('default');// Create a schema collection.
// Prior to 3.4 use $db->schemaCollection()$collection = $db->getSchemaCollection();// Get the table names$tables = $collection->listTables();// Get a single table (instance of Schema\TableSchema)$tableSchema = $collection->describe('posts');

More Information

629

CakePHP Book, Release 3.10

Schema Cache Shell
The SchemaCacheShell provides a simple CLI tool for managing your application’s metadata caches. In deployment
situations it is helpful to rebuild the metadata cache in-place without clearing the existing cache data. You can do thisby running:bin/cake schema_cache build --connection default
This will rebuild the metadata cache for all tables on the default connection. If you only need to rebuild a single table
you can do that by providing its name:bin/cake schema_cache build --connection default articles
In addition to building cached data, you can use the SchemaCacheShell to remove cached metadata as well:# Clear all metadata
bin/cake schema_cache clear# Clear a single tablebin/cake schema_cache clear articles

Note: Prior to 3.6 you should use orm_cache instead of schema_cache.

630

Chapter 12. Database Access & ORM

CHAPTER 13

Cachingclass Cake\Cache\Cache
Caching can be used to make reading from expensive or slow resources faster, by maintaining a second copy of therequired data in a faster or closer storage system. For example, you can store the results of expensive queries, or remote
webservice access that doesn’t frequently change in a cache. Once in the cache, reading data from the cache is muchcheaper than accessing the remote resource.
Caching in CakePHP is facilitated by the Cache class. This class provides a static interface and uniform API to interact
with various Caching implementations. CakePHP provides several cache engines, and provides a simple interface if
you need to build your own backend. The built-in caching engines are:
• File File cache is a simple cache that uses local files. It is the slowest cache engine, and doesn’t provide as
many features for atomic operations. However, since disk storage is often quite cheap, storing large objects, orelements that are infrequently written work well in files.
• Apcu APCu cache uses the PHP APCu147 extension. This extension uses shared memory on the webserver tostore objects. This makes it very fast, and able to provide atomic read/write features. Prior to 3.6.0 ApcuEngine
was named ApcEngine.
• Wincache Wincache uses the Wincache148 extension. Wincache is similar to APC in features and performance,but optimized for Windows and IIS.
• Memcached Uses the Memcached149 extension.
• Redis Uses the phpredis150 extension. Redis provides a fast and persistent cache system similar to Memcached,also provides atomic operations.
• Array Stores all data in an array. This engine does not provide persistent storage and is intended for use inapplication test suites.
147 https://php.net/apcu
148 https://php.net/wincache
149 https://php.net/memcached
150 https://github.com/phpredis/phpredis631

CakePHP Book, Release 3.10

Regardless of the CacheEngine you choose to use, your application interacts with Cake\Cache\Cache.
New in version 3.7.0: The Array engine was added.

Configuring Cache Engines
static Cake\Cache\Cache::config($key, $config = null)Your application can configure any number of ‘engines’ during its bootstrap process. Cache engine configurations aredefined in config/app.php.
For optimal performance CakePHP requires two cache engines to be defined.
• _cake_core_ is used for storing file maps, and parsed results of Internationalization & Localization files.
• _cake_model_, is used to store schema descriptions for your applications models.
Using multiple engine configurations also lets you incrementally change the storage as needed. For example in yourconfig/app.php you could put the following:// ...
'Cache' => ['short' => ['className' => 'File','duration' => '+1 hours','path' => CACHE,'prefix' => 'cake_short_'],// Using a fully namespaced name.
'long' => ['className' => 'Cake\Cache\Engine\FileEngine','duration' => '+1 week','probability' => 100,
'path' => CACHE . 'long' . DS,]]// ...
Configuration options can also be provided as a DSN string. This is useful when working with environment variables
or PaaS providers:Cache::config('short', ['url' => 'memcached://user:password@cache-host/?timeout=3600&prefix=myapp_',]);
When using a DSN string you can define any additional parameters/options as query string arguments.
You can also configure Cache engines at runtime:// Using a short name
Cache::config('short', ['className' => 'File','duration' => '+1 hours','path' => CACHE,'prefix' => 'cake_short_'(continues on next page)

632

Chapter 13. Caching

CakePHP Book, Release 3.10

(continued from previous page)]);// Using a fully namespaced name.
Cache::config('long', ['className' => 'Cake\Cache\Engine\FileEngine','duration' => '+1 week','probability' => 100,
'path' => CACHE . 'long' . DS,]);// Using a constructed object.
$object = new FileEngine($config);
Cache::config('other', $object);
The name of these engine configurations (‘short’ and ‘long’) are used as the $config parameter for Cake\Cache\
Cache::write() and Cake\Cache\Cache::read(). When configuring cache engines you can refer to the classname using the following syntaxes:// Short name (in App\ or Cake namespaces)
Cache::config('long', ['className' => 'File']);// Plugin short name
Cache::config('long', ['className' => 'MyPlugin.SuperCache']);// Full namespace
Cache::config('long', ['className' => 'Cake\Cache\Engine\FileEngine']);// An object implementing CacheEngineInterface
Cache::config('long', ['className' => $myCache]);Note: When using the FileEngine you might need to use the mask option to ensure cache files are made with thecorrect permissions.

Engine Options
Each engine accepts the following options:• duration Specify how long items in this cache configuration last. Specified as a strtotime() compatible
expression.
• groups List of groups or ‘tags’ associated to every key stored in this config. handy for deleting a complete groupfrom cache.
• prefix Prepended to all entries. Good for when you need to share a keyspace with either another cache config
or another application.
• probability Probability of hitting a cache gc cleanup. Setting to 0 will disable Cache::gc() from ever being
called automatically.

Configuring Cache Engines633

CakePHP Book, Release 3.10

FileEngine Options
FileEngine uses the following engine specific options:• isWindows Automatically populated with whether the host is windows or not• lock Should files be locked before writing to them?
• mask The mask used for created files• path Path to where cachefiles should be saved. Defaults to system’s temp dir.

RedisEngine Options
RedisEngine uses the following engine specific options:• port The port your Redis server is running on.
• host The host your Redis server is running on.
• database The database number to use for connection.
• password Redis server password.
• persistent Should a persistent connection be made to Redis.
• timeout Connection timeout for Redis.
• unix_socket Path to a unix socket for Redist.

MemcacheEngine Options• compress Whether to compress data.
• username Login to access the Memcache server.
• password Password to access the Memcache server.
• persistent The name of the persistent connection. All configurations using the same persistent value will
share a single underlying connection.
• serialize The serializer engine used to serialize data. Available engines are php, igbinary and json. Beside
php, the memcached extension must be compiled with the appropriate serializer support.
• servers String or array of memcached servers. If an array MemcacheEngine will use them as a pool.
• options Additional options for the memcached client. Should be an array of option => value. Use the \Memcached::OPT_* constants as keys.

Configuring Cache Fallbacks
In the event that an engine is not available, such as the FileEngine trying to write to an unwritable folder or theRedisEngine failing to connect to Redis, the engine will fall back to the noop NullEngine and trigger a loggableerror. This prevents the application from throwing an uncaught exception due to cache failure.
You can configure Cache configurations to fall back to a specified config using the fallback configuration key:634

Chapter 13. Caching

CakePHP Book, Release 3.10

Cache::config('redis', ['className' => 'Redis','duration' => '+1 hours','prefix' => 'cake_redis_','host' => '127.0.0.1','port' => 6379,'fallback' => 'default',]);
If the Redis server unexpectedly failed, writing to the redis cache configuration would fall back to writing to thedefault cache configuration. If writing to the default cache configuration also failed in this scenario, the engine
would fall back once again to the NullEngine and prevent the application from throwing an uncaught exception.
You can turn off cache fallbacks with false:
Cache::config('redis', ['className' => 'Redis','duration' => '+1 hours','prefix' => 'cake_redis_','host' => '127.0.0.1','port' => 6379,'fallback' => false]);
When there is no fallback cache failures will be raised as exceptions.
New in version 3.5.0: Cache engine fallbacks were added.
Changed in version 3.6.0: Fallbacks can now be disabled via false

Removing Configured Cache Engines
static Cake\Cache\Cache::drop($key)
Once a configuration is created you cannot change it. Instead you should drop the configuration and re-create it using Cake\Cache\Cache::drop() and Cake\Cache\Cache::config(). Dropping a cache engine will remove theconfig and destroy the adapter if it was constructed.

Writing to a Cache
static Cake\Cache\Cache::write($key, $value, $config = 'default')
Cache::write() will write a $value to the Cache. You can read or delete this value later by referring to it by $key.
You may specify an optional configuration to store the cache in as well. If no $config is specified, default will be
used. Cache::write() can store any type of object and is ideal for storing results of model finds:
if (($posts = Cache::read('posts')) === false) {$posts = $someService->getAllPosts();
Cache::write('posts', $posts);}
Using Cache::write() and Cache::read() to reduce the number of trips made to the database to fetch posts.

Writing to a Cache

635

CakePHP Book, Release 3.10

Note: If you plan to cache the result of queries made with the CakePHP ORM, it is better to use the built-in cache
capabilities of the Query object as described in the Caching Loaded Results section

Writing Multiple Keys at Oncestatic Cake\Cache\Cache::writeMany($data, $config = 'default')
You may find yourself needing to write multiple cache keys at once. While you can use multiple calls to write(),writeMany() allows CakePHP to use more efficient storage APIs where available. For example using writeMany()save multiple network connections when using Memcached:$result = Cache::writeMany(['article-' . $slug => $article,'article-' . $slug . '-comments' => $comments]);// $result will contain['article-first-post' => true, 'article-first-post-comments' => true]

Read Through Cachingstatic Cake\Cache\Cache::remember($key, $callable, $config = 'default')
Cache makes it easy to do read-through caching. If the named cache key exists, it will be returned. If the key does notexist, the callable will be invoked and the results stored in the cache at the provided key.
For example, you often want to cache remote service call results. You could use remember() to make this simple:
class IssueService{
public function allIssues($repo){
return Cache::remember($repo . '-issues', function () use ($repo) {return $this->fetchAll($repo);});}}

Reading From a Cache
static Cake\Cache\Cache::read($key, $config = 'default')
Cache::read() is used to read the cached value stored under $key from the $config. If $config is null the default
config will be used. Cache::read() will return the cached value if it is a valid cache or false if the cache has expiredor doesn’t exist. The contents of the cache might evaluate false, so make sure you use the strict comparison operators:=== or !==.
For example:

636

Chapter 13. Caching

CakePHP Book, Release 3.10

$cloud = Cache::read('cloud');if ($cloud !== false) {return $cloud;}// Generate cloud data// ...
// Store data in cache
Cache::write('cloud', $cloud);return $cloud;Or if you are using another cache configuration called short, you can specify it in Cache::read() and
Cache::write() calls as below:// Read key "cloud", but from short configuration instead of default$cloud = Cache::read('cloud', 'short');if ($cloud !== false) {return $cloud;}// Generate cloud data// ...
// Store data in cache, using short cache configuration instead of default
Cache::write('cloud', $cloud, 'short');return $cloud;Reading Multiple Keys at Oncestatic Cake\Cache\Cache::readMany($keys, $config = 'default')
After you’ve written multiple keys at once, you’ll probably want to read them as well. While you could use multiple
calls to read(), readMany() allows CakePHP to use more efficient storage APIs where available. For example using
readMany() save multiple network connections when using Memcached:$result = Cache::readMany(['article-' . $slug,'article-' . $slug . '-comments']);// $result will contain['article-first-post' => '...', 'article-first-post-comments' => '...']

Reading From a Cache

637

CakePHP Book, Release 3.10

Deleting From a Cache
static Cake\Cache\Cache::delete($key, $config = 'default')
Cache::delete() will allow you to completely remove a cached object from the store:// Remove a key
Cache::delete('my_key');

Deleting Multiple Keys at Oncestatic Cake\Cache\Cache::deleteMany($keys, $config = 'default')
After you’ve written multiple keys at once, you may want to delete them. While you could use multiple calls todelete(), deleteMany() allows CakePHP to use more efficient storage APIs where available. For example using
deleteMany() save multiple network connections when using Memcached:$result = Cache::deleteMany(['article-' . $slug,'article-' . $slug . '-comments']);// $result will contain['article-first-post' => true, 'article-first-post-comments' => true]

Clearing Cached Datastatic Cake\Cache\Cache::clear($check, $config = 'default')
Destroy all cached values for a cache configuration. In engines like: Apcu, Memcached, and Wincache, the cacheconfiguration’s prefix is used to remove cache entries. Make sure that different cache configurations have different
prefixes:// Will only clear expired keys.
Cache::clear(true);// Will clear all keys.
Cache::clear(false);
static Cake\Cache\Cache::gc($config)
Garbage collects entries in the cache configuration. This is primarily used by FileEngine. It should be implemented by
any Cache engine that requires manual eviction of cached data.
Note: Because APCu and Wincache use isolated caches for webserver and CLI they have to be cleared separately(CLI cannot clear webserver and vice versa).

638

Chapter 13. Caching

CakePHP Book, Release 3.10

Using Cache to Store Countersstatic Cake\Cache\Cache::increment($key, $offset = 1, $config = 'default')
static Cake\Cache\Cache::decrement($key, $offset = 1, $config = 'default')
Counters in your application are good candidates for storage in a cache. As an example, a simple countdown forremaining ‘slots’ in a contest could be stored in Cache. The Cache class exposes atomic ways to increment/decrement
counter values in an easy way. Atomic operations are important for these values as it reduces the risk of contention,
and ability for two users to simultaneously lower the value by one, resulting in an incorrect value.
After setting an integer value you can manipulate it using increment() and decrement():
Cache::write('initial_count', 10);// Later on
Cache::decrement('initial_count');// Or
Cache::increment('initial_count');

Note: Incrementing and decrementing do not work with FileEngine. You should use APCu, Wincache, Redis orMemcached instead.

Using Cache to Store Common Query Results
You can greatly improve the performance of your application by putting results that infrequently change, or that are
subject to heavy reads into the cache. A perfect example of this are the results from Cake\ORM\Table::find(). The
Query object allows you to cache results using the cache() method. See the Caching Loaded Results section for more
information.

Using Groups
Sometimes you will want to mark multiple cache entries to belong to certain group or namespace. This is a common
requirement for mass-invalidating keys whenever some information changes that is shared among all entries in the samegroup. This is possible by declaring the groups in cache configuration:
Cache::config('site_home', ['className' => 'Redis','duration' => '+999 days','groups' => ['comment', 'article']]);
Cake\Cache\Cache::clearGroup($group, $config = 'default')
Let’s say you want to store the HTML generated for your homepage in cache, but would also want to automaticallyinvalidate this cache every time a comment or post is added to your database. By adding the groups comment andarticle, we have effectively tagged any key stored into this cache configuration with both group names.

Using Cache to Store Counters639

CakePHP Book, Release 3.10

For instance, whenever a new post is added, we could tell the Cache engine to remove all entries associated to thearticle group:// src/Model/Table/ArticlesTable.php
public function afterSave($event, $entity, $options = []){if ($entity->isNew()) {Cache::clearGroup('article', 'site_home');}}static Cake\Cache\Cache::groupConfigs($group = null)groupConfigs() can be used to retrieve mapping between group and configurations, i.e.: having the same group:// src/Model/Table/ArticlesTable.php/*** A variation of previous example that clears all Cache configurations* having the same group*/public function afterSave($event, $entity, $options = []){if ($entity->isNew()) {$configs = Cache::groupConfigs('article');foreach ($configs['article'] as $config) {Cache::clearGroup('article', $config);}}}
Groups are shared across all cache configs using the same engine and same prefix. If you are using groups and want totake advantage of group deletion, choose a common prefix for all your configs.

Globally Enable or Disable Cache
static Cake\Cache\Cache::disable
You may need to disable all Cache read & writes when trying to figure out cache expiration related issues. You can dothis using enable() and disable():// Disable all cache reads, and cache writes.
Cache::disable();Once disabled, all reads and writes will return null.
static Cake\Cache\Cache::enable
Once disabled, you can use enable() to re-enable caching:// Re-enable all cache reads, and cache writes.
Cache::enable();640

Chapter 13. Caching

CakePHP Book, Release 3.10

static Cake\Cache\Cache::enabled
If you need to check on the state of Cache, you can use enabled().

Creating a Cache Engine
You can provide custom Cache engines in App\Cache\Engine as well as in plugins using $plugin\
Cache\Engine.
Cache engines must be in a cache directory.
If you had a cache engine named
MyCustomCacheEngine it would be placed in either src/Cache/Engine/MyCustomCacheEngine.php. Or in plugins/MyPlugin/src/Cache/Engine/MyCustomCacheEngine.php as part of a plugin. Cache configs from plugins
need to use the plugin dot syntax:
Cache::config('custom', ['className' => 'MyPlugin.MyCustomCache',// ...
]);
Custom Cache engines must extend Cake\Cache\CacheEngine which defines a number of abstract methods as wellas provides a few initialization methods.
The required API for a CacheEngine isclass Cake\Cache\CacheEngine
The base class for all cache engines used with Cache.
Cake\Cache\CacheEngine::write($key, $value)
Returnsboolean for success.
Write value for a key into cache, Return true if the data was successfully cached, false on failure.
Cake\Cache\CacheEngine::read($key)
Returns
The cached value or false for failure.
Read a key from the cache. Return false to indicate the entry has expired or does not exist.
Cake\Cache\CacheEngine::delete($key)
Returns
Boolean true on success.
Delete a key from the cache. Return false to indicate that the entry did not exist or could not be deleted.
Cake\Cache\CacheEngine::clear($check)
Returns
Boolean true on success.
Delete all keys from the cache. If $check is true, you should validate that each value is actually expired.
Cake\Cache\CacheEngine::clearGroup($group)
Returns
Boolean true on success.
Delete all keys from the cache belonging to the same group.

Creating a Cache Engine

641

CakePHP Book, Release 3.10

Cake\Cache\CacheEngine::decrement($key, $offset = 1)
Returns
Boolean true on success.
Decrement a number under the key and return decremented value
Cake\Cache\CacheEngine::increment($key, $offset = 1)
Returns
Boolean true on success.
Increment a number under the key and return incremented value
Cake\Cache\CacheEngine::gc()
Not required, but used to do clean up when resources expire. FileEngine uses this to delete files containing
expired content.

642

Chapter 13. CachingCHAPTER 14

Bake Console

This page has moved151 .

151 https://book.cakephp.org/bake/1.x/en/index.html

643

CakePHP Book, Release 3.10644

Chapter 14. Bake Console

CHAPTER 15

Console Tools, Shells & Tasks

CakePHP features not only a web framework but also a console framework for creating console applications. Console
applications are ideal for handling a variety of background tasks such as maintenance, and completing work outsideof the request-response cycle. CakePHP console applications allow you to reuse your application classes from thecommand line.
CakePHP comes with a number of console applications out of the box. Some of these applications are used in concert
with other CakePHP features (like i18n), and others are for general use to get you working faster.

The CakePHP Console
This section provides an introduction into CakePHP at the command-line. Console tools are ideal for use in cron jobs,
or command line based utilities that don’t need to be accessible from a web browser.
PHP provides a CLI client that makes interfacing with your file system and applications much smoother. The CakePHP
console provides a framework for creating shell scripts. The Console uses a dispatcher-type setup to load a shell ortask, and provide its parameters.
Note: A command-line (CLI) build of PHP must be available on the system if you plan to use the Console.
Before we get into specifics, let’s make sure you can run the CakePHP console. First, you’ll need to bring up a systemterminal. The examples shown in this section will be in bash, but the CakePHP Console is compatible with Windows as
well. This example assumes that you are currently logged into a bash prompt at the root of your CakePHP application.
A CakePHP application contains src/Command, src/Shell and src/Shell/Task directories that contain its shells andtasks. It also comes with an executable in the bin directory:$ cd /path/to/app$ bin/cake645

CakePHP Book, Release 3.10

Note: For Windows, the command needs to be bin\cake (note the backslash).
Deprecated since version 3.6.0: Shells are deprecated as of 3.6.0, but will not be removed until 5.x. Use Console
Commands instead.
Running the Console with no arguments produces this help message:
Welcome to CakePHP v3.6.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
Available Commands:- version- help- cache- completion- i18n- schema_cache- plugin- routes- server- bug- console- event- orm- bake- bake.bake- migrations- migrations.migrations
To run a command, type `cake shell_name [args|options]`
To get help on a specific command, type `cake shell_name --help`
The first information printed relates to paths. This is helpful if you’re running the console from different parts of thefilesystem.
You could then run the any of the listed commands by using its name:# run server shell
bin/cake server# run migrations shell
bin/cake migrations -h# run bake (with plugin prefix)(continues on next page)

646

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)bin/cake bake.bake -hPlugin commands can be invoked without a plugin prefix if the commands’s name does not overlap with an application
or framework shell. In the case that two plugins provide a command with the same name, the first loaded plugin will
get the short alias. You can always use the plugin.command format to unambiguously reference a command.

Console Applications
By default CakePHP will automatically discover all the commands in your application and its plugins. You may
want to reduce the number of exposed commands, when building standalone console applications. You can use your
Application’s console() hook to limit which commands are exposed and rename commands that are exposed:// in src/Application.php
namespace App;use App\Shell\UserShell;use App\Shell\VersionShell;use Cake\Http\BaseApplication;
class Application extends BaseApplication{
public function console($commands){// Add by classname$commands->add('user', UserCommand::class);// Add instance$commands->add('version', new VersionCommand());
return $commands;}}
In the above example, the only commands available would be help, version and user. See the Commands section
for how to add commands in your plugins.
Note: When adding multiple commands that use the same Command class, the help command will display theshortest option.
New in version 3.5.0: The console hook was added.

Console Applications

647

CakePHP Book, Release 3.10

Renaming Commands
There are cases where you will want to rename commands, to create nested commands or subcommands. While thedefault auto-discovery of commands will not do this, you can register your commands to create any desired naming.
You can customize the command names by defining each command in your plugin:public function console($commands){// Add commands with nested naming$commands->add('user dump', UserDumpCommand::class);$commands->add('user:show', UserShowCommand::class);// Rename a command entirely$commands->add('lazer', UserDeleteCommand::class);
return $commands;}
When overriding the console() hook in your application, remember to call $commands->autoDiscover() to add
commands from CakePHP, your application, and plugins.
If you need to rename/remove any attached commands, you can use the Console.buildCommands event on yourapplication event manager to modify the available commands.

Commands
See the Console Commands chapter on how to create your first command. Then learn more about commands:

Console Commands
class Cake\Console\Command
CakePHP comes with a number of built-in commands for speeding up your development, and automating routine tasks.
You can use these same libraries to create commands for your application and plugins.
New in version 3.6.0: Commands were added to replace Shells long term. Shells & Tasks have several shortcomings
that are hard to correct without breaking compatibility.
Creating a Command
Let’s create our first Command. For this example, we’ll create a simple Hello world command. In your application’s
src/Command directory create HelloCommand.php. Put the following code inside it:<?php
namespace App\Command;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;(continues on next page)

648

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)class HelloCommand extends Command{
public function execute(Arguments $args, ConsoleIo $io){
$io->out('Hello world.');}}Command classes must implement an execute() method that does the bulk of their work. This method is called whena command is invoked. Lets call our first command application directory, run:bin/cake hello
You should see the following output:
Hello world.
Our execute() method isn’t very interesting let’s read some input from the command line:<?php
namespace App\Command;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
class HelloCommand extends Command{protected function buildOptionParser(ConsoleOptionParser $parser){$parser->addArgument('name', ['help' => 'What is your name']);return $parser;}
public function execute(Arguments $args, ConsoleIo $io){$name = $args->getArgument('name');$io->out("Hello {$name}.");}}
After saving this file, you should be able to run the following command:bin/cake hello jillian# Outputs
Hello jillian

Commands649

CakePHP Book, Release 3.10

Changing the Default Command Name
CakePHP will use conventions to generate the name your commands use on the command line. If you want to overwrite
the generated name implement the defaultName() method in your command:
public static function defaultName(): string{
return 'oh_hi';}
The above would make our HelloCommand accessible by cake oh_hi instead of cake hello.
Defining Arguments and Options
As we saw in the last example, we can use the buildOptionParser() hook method to define arguments. We can also
define options. For example, we could add a yell option to our HelloCommand:// ...
protected function buildOptionParser(ConsoleOptionParser $parser){$parser->addArgument('name', ['help' => 'What is your name'])->addOption('yell', ['help' => 'Shout the name','boolean' => true]);
return $parser;}
public function execute(Arguments $args, ConsoleIo $io){$name = $args->getArgument('name');if ($args->getOption('yell')) {$name = mb_strtoupper($name);}$io->out("Hello {$name}.");}
See the Option Parsers section for more information.
Creating Output
Commands are provided a ConsoleIo instance when executed. This object allows you to interact with stdout, stderr
and create files. See the Command Input/Output section for more information.

650

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Using Models in Commands
You’ll often need access to your application’s business logic in console commands. You can load models in commands, just as you would in a controller using loadModel(). The loaded models are set as properties attached to yourcommands:<?php
namespace App\Command;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
class UserCommand extends Command{
public function initialize(){
parent::initialize();$this->loadModel('Users');}
protected function buildOptionParser(ConsoleOptionParser $parser){$parser->addArgument('name', ['help' => 'What is your name']);return $parser;}
public function execute(Arguments $args, ConsoleIo $io){$name = $args->getArgument('name');$user = $this->Users->findByUsername($name)->first();$io->out(print_r($user, true));}}
The above command, will fetch a user by username and display the information stored in the database.
Exit Codes and Stopping Execution
When your commands hit an unrecoverable error you can use the abort() method to terminate execution:// ...
public function execute(Arguments $args, ConsoleIo $io){$name = $args->getArgument('name');if (strlen($name) < 5) {// Halt execution, output to stderr, and set exit code to 1
(continues on next page)

Commands

651

CakePHP Book, Release 3.10

(continued from previous page)$io->error('Name must be at least 4 characters long.');$this->abort();}}You can also use abort() on the $io object to emit a message and code:
public function execute(Arguments $args, ConsoleIo $io){$name = $args->getArgument('name');if (strlen($name) < 5) {// Halt execution, output to stderr, and set exit code to 99$io->abort('Name must be at least 4 characters long.', 99);}}
You can pass any desired exit code into abort().
Tip: Avoid exit codes 64 - 78, as they have specific meanings described by sysexits.h. Avoid exit codes above 127,
as these are used to indicate process exit by signal, such as SIGKILL or SIGSEGV.
You can read more about conventional exit codes in the sysexit manual page on most Unix systems (man sysexits),or the System Error Codes help page in Windows.
New in version 3.9.0: ConsoleIo::abort() was added.
Calling other Commands
You may need to call other commands from your command. You can use executeCommand to do that:// You can pass an array of CLI options and arguments.
$this->executeCommand(OtherCommand::class, ['--verbose', 'deploy']);// Can pass an instance of the command if it has constructor args
$command = new OtherCommand($otherArgs);$this->executeCommand($command, ['--verbose', 'deploy']);New in version 3.8.0: executeCommand() was added.
Note: When calling executeCommand() in a loop, it is recommended to pass in the parent command’s ConsoleIo
instance as the optional 3rd argument to avoid a potential “open files” limit that could occur in some environments.

652

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Testing Commands
To make testing console applications easier, CakePHP comes with a ConsoleIntegrationTestTrait trait that canbe used to test console applications and assert against their results.
New in version 3.5.0: The ConsoleIntegrationTestCase was added.
New in version 3.7.0:
The
ConsoleIntegrationTestTrait trait.

ConsoleIntegrationTestCase

class

was

moved

into

the

To get started testing your console application, create a test case that uses the Cake\TestSuite\
ConsoleIntegrationTestTrait trait. This trait contains a method exec() that is used to execute yourcommand. You can pass the same string you would use in the CLI to this method.
Let’s start with a very simple command, located in src/Command/UpdateTableCommand.php:
namespace App\Command;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
class UpdateTableCommand extends Command{protected function buildOptionParser(ConsoleOptionParser $parser){$parser->setDescription('My cool console app');
return $parser;
}
}
To
write
an
integration
test
for
this
shell,
we
would
create
a
test
case
in
tests/TestCase/Command/UpdateTableTest.php
that
uses
the
Cake\TestSuite\
ConsoleIntegrationTestTrait trait. This shell doesn’t do much at the moment, but let’s just test that ourshell’s description is displayed in stdout:
namespace App\Test\TestCase\Command;
use Cake\TestSuite\ConsoleIntegrationTestTrait;
use Cake\TestSuite\TestCase;
class UpdateTableCommandTest extends TestCase{
use ConsoleIntegrationTestTrait;
public function setUp(){
parent::setUp();$this->useCommandRunner();}
public function testDescriptionOutput(){$this->exec('update_table --help');(continues on next page)

Commands653

CakePHP Book, Release 3.10

(continued from previous page)$this->assertOutputContains('My cool console app');}}
Our test passes! While this is very trivial example, it shows that creating an integration test case for console applications
is quite easy. Let’s continue by adding more logic to our command:
namespace App\Command;
use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
use Cake\I18n\FrozenTime;class UpdateTableCommand extends Command{protected function buildOptionParser(ConsoleOptionParser $parser){$parser->setDescription('My cool console app')->addArgument('table', ['help' => 'Table to update','required' => true]);
return $parser;}
public function execute(Arguments $args, ConsoleIo $io){$table = $args->getArgument('table');$this->loadModel($table);$this->{$table}->query()->update()->set(['modified' => new FrozenTime()])->execute();}}This is a more complete shell that has required options and relevant logic. Modify your test case to the following snippetof code:namespace Cake\Test\TestCase\Command;
use Cake\Console\Command;
use Cake\I18n\FrozenTime;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\ConsoleIntegrationTestTrait;
use Cake\TestSuite\TestCase;(continues on next page)

654

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)class UpdateTableCommandTest extends TestCase{
use ConsoleIntegrationTestTrait;
public $fixtures = [// assumes you have a UsersFixture'app.Users'];
public function testDescriptionOutput(){$this->exec('update_table --help');$this->assertOutputContains('My cool console app');}public function testUpdateModified(){$now = new FrozenTime('2017-01-01 00:00:00');
FrozenTime::setTestNow($now);$this->loadFixtures('Users');$this->exec('update_table Users');$this->assertExitCode(Command::CODE_SUCCESS);// Prior to 3.6 use TableRegistry::get('Users')$user = TableRegistry::getTableLocator()->get('Users')->get(1);$this->assertSame($user->modified->timestamp, $now->timestamp);
FrozenTime::setTestNow(null);}}As you can see from the testUpdateModified method, we are testing that our command updates the table that we are
passing as the first argument. First, we assert that the command exited with the proper status code, 0. Then we checkthat our command did its work, that is, updated the table we provided and set the modified column to the current time.
Remember, exec() will take the same string you type into your CLI, so you can include options and arguments in yourcommand string.
Testing Interactive Shells
Consoles are often interactive.
Testing interactive shells with the Cake\TestSuite\
ConsoleIntegrationTestTrait trait only requires passing the inputs you expect as the second parameter ofexec(). They should be included as an array in the order that you expect them.
Continuing with our example command, let’s add an interactive confirmation. Update the command class to the following:namespace App\Command;(continues on next page)

Commands655

CakePHP Book, Release 3.10

(continued from previous page)use Cake\Console\Arguments;
use Cake\Console\Command;
use Cake\Console\ConsoleIo;
use Cake\Console\ConsoleOptionParser;
use Cake\I18n\FrozenTime;class UpdateTableCommand extends Command{protected function buildOptionParser(ConsoleOptionParser $parser){$parser->setDescription('My cool console app')->addArgument('table', ['help' => 'Table to update','required' => true]);
return $parser;}
public function execute(Arguments $args, ConsoleIo $io){$table = $args->getArgument('table');$this->loadModel($table);if ($io->ask('Are you sure?', 'n', ['y', 'n']) === 'n') {$io->error('You need to be sure.');$this->abort();}$this->{$table}->query()->update()->set(['modified' => new FrozenTime()])->execute();}}Now that we have an interactive subcommand, we can add a test case that tests that we receive the proper response, andone that tests that we receive an incorrect response. Remove the testUpdateModified method and, add the following
methods to tests/TestCase/Command/UpdateTableCommandTest.php:
public function testUpdateModifiedSure(){$now = new FrozenTime('2017-01-01 00:00:00');
FrozenTime::setTestNow($now);$this->loadFixtures('Users');$this->exec('update_table Users', ['y']);$this->assertExitCode(Command::CODE_SUCCESS);// Prior to 3.6 use TableRegistry::get('Users')(continues on next page)

656

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)$user = TableRegistry::getTableLocator()->get('Users')->get(1);$this->assertSame($user->modified->timestamp, $now->timestamp);
FrozenTime::setTestNow(null);}public function testUpdateModifiedUnsure(){// Prior to 3.6 use TableRegistry::get('Users')$user = TableRegistry::getTableLocator()->get('Users')->get(1);$original = $user->modified->timestamp;$this->exec('my_console best_framework', ['n']);$this->assertExitCode(Command::CODE_ERROR);$this->assertErrorContains('You need to be sure.');// Prior to 3.6 use TableRegistry::get('Users')$user = TableRegistry::getTableLocator()->get('Users')->get(1);$this->assertSame($original, $user->timestamp);}
In the first test case, we confirm the question, and records are updated. In the second test we don’t confirm and records
are not updated, and we can check that our error message was written to stderr.
Testing the CommandRunner
To test shells that are dispatched using the CommandRunner class, enable it in your test case with the following method:$this->useCommandRunner();
New in version 3.5.0: The CommandRunner class was added.
Assertion methods
The Cake\TestSuite\ConsoleIntegrationTestTrait trait provides a number of assertion methods that make iteasy to assert against console output:// assert that the shell exited as success$this->assertExitSuccess();// assert that the shell exited as an error$this->assertExitError();// assert that the shell exited with the expected code
$this->assertExitCode($expected);// assert that stdout contains a string$this->assertOutputContains($expected);// assert that stderr contains a string(continues on next page)

Commands

657

CakePHP Book, Release 3.10

(continued from previous page)$this->assertErrorContains($expected);// assert that stdout matches a regular expression$this->assertOutputRegExp($expected);// assert that stderr matches a regular expression$this->assertErrorRegExp($expected);

Note: By default, text output (including help texts) longer than 72 characters will be wrapped. Output assertions mustbe split accordingly.

Command Input/Output
class Cake\Console\ConsoleIo
CakePHP provides the ConsoleIo object to commands so that they can interactively read user input and output information to the user.
Command Helpers
Command Helpers can be accessed and used from any command, shell or task:// Output some data as a table.
$io->helper('Table')->output($data);// Get a helper from a plugin.
$io->helper('Plugin.HelperName')->output($data);
You can also get instances of helpers and call any public methods on them:// Get and use the Progress Helper.
$progress = $io->helper('Progress');$progress->increment(10);$progress->draw();

Creating Helpers
While CakePHP comes with a few command helpers you can create more in your application or plugins. As an example,
we’ll create a simple helper to generate fancy headings. First create the src/Command/Helper/HeadingHelper.php
and put the following in it:<?php
namespace App\Command\Helper;
use Cake\Console\Helper;class HeadingHelper extends Helper{(continues on next page)

658

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)

public function output($args){$args += ['', '#', 3];$marker = str_repeat($args[1], $args[2]);$this->_io->out($marker . ' ' . $args[0] . ' ' . $marker);}}
We can then use this new helper in one of our shell commands by calling it:// With ### on either side
$this->helper('Heading')->output(['It works!']);// With ~~~~ on either side
$this->helper('Heading')->output(['It works!', '~', 4]);
Helpers generally implement the output() method which takes an array of parameters. However, because Console
Helpers are vanilla classes they can implement additional methods that take any form of arguments.
Note: Helpers can also live in src/Shell/Helper for backwards compatibility.

Built-In Helpers
Table Helper
The TableHelper assists in making well formatted ASCII art tables. Using it is pretty simple:$data = [['Header 1', 'Header', 'Long Header'],['short', 'Longish thing', 'short'],['Longer thing', 'short', 'Longest Value'],];$io->helper('Table')->output($data);// Outputs+--------------+---------------+---------------+| Header 1| Header| Long Header|+--------------+---------------+---------------+| short| Longish thing | short|| Longer thing | short| Longest Value |+--------------+---------------+---------------+

Commands659

CakePHP Book, Release 3.10

Progress Helper
The ProgressHelper can be used in two different ways. The simple mode lets you provide a callback that is invokeduntil the progress is complete:$io->helper('Progress')->output(['callback' => function ($progress) {// Do work here.
$progress->increment(20);$progress->draw();}]);
You can control the progress bar more by providing additional options:• total The total number of items in the progress bar. Defaults to 100.
• width The width of the progress bar. Defaults to 80.
• callback The callback that will be called in a loop to advance the progress bar.
An example of all the options in use would be:$io->helper('Progress')->output(['total' => 10,'width' => 20,'callback' => function ($progress) {$progress->increment(2);$progress->draw();}]);
The progress helper can also be used manually to increment and re-render the progress bar as necessary:$progress = $io->helper('Progress');$progress->init(['total' => 10,'width' => 20,]);$progress->increment(4);$progress->draw();

Getting User Input
Cake\Console\ConsoleIo::ask($question, $choices = null, $default = null)
When building interactive console applications you’ll need to get user input. CakePHP provides an easy way to do this:// Get arbitrary text from the user.
$color = $io->ask('What color do you like?');// Get a choice from the user.
$selection = $io->askChoice('Red or Green?', ['R', 'G'], 'R');
Selection validation is case-insensitive.

660

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Creating Files
Cake\Console\ConsoleIo::createFile($path, $contents)
Creating files is often important part of many console commands that help automate development and deployment.
The createFile() method gives you a simple interface for creating files with interactive confirmation:// Create a file with confirmation on overwrite$io->createFile('bower.json', $stuff);// Force overwriting without asking$io->createFile('bower.json', $stuff, true);

Creating Output
Writing to stdout and stderr is another routine operation CakePHP makes easy:// Write to stdout$io->out('Normal message');// Write to stderr$io->err('Error message');
In addition to vanilla output methods, CakePHP provides wrapper methods that style output with appropriate ANSI
colours:// Green text on stdout$io->success('Success message');// Cyan text on stdout$io->info('Informational text');// Blue text on stdout$io->comment('Additional context');// Red text on stderr$io->error('Error text');// Yellow text on stderr$io->warning('Warning text');
It also provides two convenience methods regarding the output level:// Would only appear when verbose output is enabled (-v)$io->verbose('Verbose message');// Would appear at all levels.
$io->quiet('Quiet message');
You can also create blank lines or draw lines of dashes:// Output 2 newlines$io->out($io->nl(2));(continues on next page)

Commands

661

CakePHP Book, Release 3.10

(continued from previous page)// Draw a horizontal line$io->hr();Lastly, you can update the current line of text on the screen:$io->out('Counting down');$io->out('10', 0);for ($i = 9; $i > 0; $i--) {sleep(1);$io->overwrite($i, 0, 2);}Note: It is important to remember, that you cannot overwrite text once a new line has been output.

Output Levels
Console applications often need different levels of verbosity. For example, when running as a cron job, most output is
un-necessary. You can use output levels to flag output appropriately. The user of the shell, can then decide what levelof detail they are interested in by setting the correct flag when calling the command. There are 3 levels:• QUIET - Only absolutely important information should be marked for quiet output.
• NORMAL - The default level, and normal usage.
• VERBOSE - Mark messages that may be too noisy for everyday use, but helpful for debugging as VERBOSE.
You can mark output as follows:// Would appear at all levels.
$io->out('Quiet message', 1, ConsoleIo::QUIET);$io->quiet('Quiet message');// Would not appear when quiet output is toggled.
$io->out('normal message', 1, ConsoleIo::NORMAL);$io->out('loud message', 1, ConsoleIo::VERBOSE);$io->verbose('Verbose output');// Would only appear when verbose output is enabled.
$io->out('extra message', 1, ConsoleIo::VERBOSE);$io->verbose('Verbose output');
You can control the output level of shells, by using the --quiet and --verbose options. These options are added bydefault, and allow you to consistently control output levels inside your CakePHP comands.
The --quiet and --verbose options also control how logging data is output to stdout/stderr. Normally info andhigher log messages are output to stdout/stderr. When --verbose is used, debug logs will be output to stdout. When--quiet is used, only warning and higher log messages will be output to stderr.

662

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Styling Output
Styling output is done by including tags - just like HTML - in your output. These tags will be replaced with the correct
ansi code sequence, or stripped if you are on a console that doesn’t support ansi codes. There are several built-in styles,
and you can create more. The built-in ones are• success Success messages. Green text.
• error Error messages. Red text.
• warning Warning messages. Yellow text.
• info Informational messages. Cyan text.
• comment Additional text. Blue text.
• question Text that is a question, added automatically by shell.
You can create additional styles using $io->styles(). To declare a new output style you could do:$io->styles('flashy', ['text' => 'magenta', 'blink' => true]);
This would then allow you to use a <flashy> tag in your shell output, and if ansi colours are enabled, the following would be rendered as blinking magenta text $this->out('<flashy>Whoooa</flashy> Something went
wrong');. When defining styles you can use the following colours for the text and background attributes:• black• blue• cyan• green• magenta• red• white• yellow
You can also use the following options as boolean switches, setting them to a truthy value enables them.
• blink• bold• reverse• underline
Adding a style makes it available on all instances of ConsoleOutput as well, so you don’t have to redeclare styles forboth stdout and stderr objects.

Commands

663

CakePHP Book, Release 3.10

Turning Off Colouring
Although colouring is pretty, there may be times when you want to turn it off, or force it on:$io->outputAs(ConsoleOutput::RAW);The above will put the output object into raw output mode. In raw output mode, no styling is done at all. There arethree modes you can use.
• ConsoleOutput::COLOR - Output with color escape codes in place.
• ConsoleOutput::PLAIN - Plain text output, known style tags will be stripped from the output.
• ConsoleOutput::RAW - Raw output, no styling or formatting will be done. This is a good mode to use if you
are outputting XML or, want to debug why your styling isn’t working.
By default on *nix systems ConsoleOutput objects default to colour output. On Windows systems, plain output is thedefault unless the ANSICON environment variable is present.

Option Parsers
class Cake\Console\ConsoleOptionParser
Console applications typically take options and arguments as the primary way to get information from the terminal into
your commands.
Defining an OptionParser
Commands and Shells provide a buildOptionParser($parser) hook method that you can use to define the options
and arguments for your commands:
protected function buildOptionParser($parser){// Define your options and arguments.
// Return the completed parser
return $parser;}
Shell classes use the getOptionParser() hook method to define their option parser:
public function getOptionParser(){// Get an empty parser from the framework.
$parser = parent::getOptionParser();// Define your options and arguments.
// Return the completed parser
return $parser;}

664

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Using Arguments
Cake\Console\ConsoleOptionParser::addArgument($name, $params = [])Positional arguments are frequently used in command line tools, and ConsoleOptionParser allows you todefine positional arguments as well as make them required. You can add arguments one at a time with$parser->addArgument(); or multiple at once with $parser->addArguments();:$parser->addArgument('model', ['help' => 'The model to bake']);
You can use the following options when creating an argument:• help The help text to display for this argument.
• required Whether this parameter is required.
• index The index for the arg, if left undefined the argument will be put onto the end of the arguments. If you
define the same index twice the first option will be overwritten.
• choices An array of valid choices for this argument. If left empty all values are valid. An exception will beraised when parse() encounters an invalid value.
Arguments that have been marked as required will throw an exception when parsing the command if they have been
omitted. So you don’t have to handle that in your shell.
Adding Multiple Arguments
Cake\Console\ConsoleOptionParser::addArguments(array $args)
If you have an array with multiple arguments you can use $parser->addArguments() to add multiple arguments atonce.
$parser->addArguments(['node' => ['help' => 'The node to create', 'required' => true],'parent' => ['help' => 'The parent node', 'required' => true]]);
As with all the builder methods on ConsoleOptionParser, addArguments can be used as part of a fluent method chain.
Validating Arguments
When creating positional arguments, you can use the required flag, to indicate that an argument must be present whena shell is called. Additionally you can use choices to force an argument to be from a list of valid choices:$parser->addArgument('type', ['help' => 'The type of node to interact with.','required' => true,'choices' => ['aro', 'aco']]);
The above will create an argument that is required and has validation on the input. If the argument is either missing,or has an incorrect value an exception will be raised and the shell will be stopped.

Commands665

CakePHP Book, Release 3.10

Using Options
Cake\Console\ConsoleOptionParser::addOption($name, $options = [])Options or flags are used in command line tools to provide unordered key/value arguments for your commands. Options
can define both verbose and short aliases. They can accept a value (e.g --connection=default) or be boolean options(e.g --verbose). Options are defined with the addOption() method:$parser->addOption('connection', ['short' => 'c','help' => 'connection','default' => 'default',]);
The above would allow you to use either cake myshell --connection=other, cake myshell --connection
other, or cake myshell -c other when invoking the shell.
Boolean switches do not accept or consume values, and their presence just enables them in the parsed parameters:$parser->addOption('no-commit', ['boolean' => true]);
This option when used like cake mycommand --no-commit something would have a value of true, and ‘something’ would be a treated as a positional argument.
When creating options you can use the following options to define the behavior of the option:• short - The single letter variant for this option, leave undefined for none.
• help - Help text for this option. Used when generating help for the option.
• default - The default value for this option. If not defined the default will be true.
• boolean - The option uses no value, it’s just a boolean switch. Defaults to false.
• choices - An array of valid choices for this option. If left empty all values are valid. An exception will be raised
when parse() encounters an invalid value.
Adding Multiple Options
Cake\Console\ConsoleOptionParser::addOptions(array $options)If you have an array with multiple options you can use $parser->addOptions() to add multiple options at once.
$parser->addOptions(['node' => ['short' => 'n', 'help' => 'The node to create'],'parent' => ['short' => 'p', 'help' => 'The parent node']]);
As with all the builder methods on ConsoleOptionParser, addOptions can be used as part of a fluent method chain.
Option values are stored in the $this->params array. You can also use the convenience method $this->param() toavoid errors when trying to access non-present options.

666

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Validating Options
Options can be provided with a set of choices much like positional arguments can be. When an option has defined
choices, those are the only valid choices for an option. All other values will raise an InvalidArgumentException:$parser->addOption('accept', ['help' => 'What version to accept.','choices' => ['working', 'theirs', 'mine']]);

Using Boolean Options
Options can be defined as boolean options, which are useful when you need to create some flag options. Like options
with defaults, boolean options always include themselves into the parsed parameters. When the flags are present they
are set to true, when they are absent they are set to false:$parser->addOption('verbose', ['help' => 'Enable verbose output.','boolean' => true]);
The following option would always have a value in the parsed parameter. When not included its default value would
be false, and when defined it will be true.
Building a ConsoleOptionParser from an Array
Cake\Console\ConsoleOptionParser::buildFromArray($spec)
As previously mentioned, when creating subcommand option parsers, you can define the parser spec as an array forthat method. This can help make building subcommand parsers easier, as everything is an 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 "),__("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')]]]]);
Inside the parser spec, you can define keys for arguments, options, description and epilog. You
cannot define subcommands inside an array style builder.
The values for arguments, and options,should follow the format that Cake\Console\ConsoleOptionParser::addArguments() and Cake\Console\
ConsoleOptionParser::addOptions() use. You can also use buildFromArray on its own, to build an option parser:

Commands

667

CakePHP Book, Release 3.10

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')]]]);}

Merging Option Parsers
Cake\Console\ConsoleOptionParser::merge($spec)
When building a group command, you maybe want to combine several parsers for this:$parser->merge($anotherParser);
Note that the order of arguments for each parser must be the same, and that options must also be compatible for it work.
So do not use keys for different things.
Getting Help from Shells
By defining your options and arguments with the option parser CakePHP can automatically generate rudimentary help
information and add a --help and -h to each of your commands. Using one of these options will allow you to see thegenerated help content:
bin/cake bake --help
bin/cake bake -hWould both generate the help for bake. You can also get help for nested commands:
bin/cake bake model --help
bin/cake bake model -h
The above would get you the help specific to bake’s model command.

668

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Getting Help as XML
When building automated tools or development tools that need to interact with CakePHP shells, it’s nice to have help
available in a machine parse-able format. By providing the xml option when requesting help you can have help content
returned as XML:cake bake --help xml
cake bake -h xml
The above would return an XML document with the generated help, options, arguments and subcommands for theselected shell. A sample XML document would look like:<?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 interactivemode.
</epilog><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.
(continues on next page)

Commands

669

CakePHP Book, Release 3.10

(continued from previous page)Can use Plugin.name to bake plugin fixtures." required=""><choices/></argument></arguments></shell>Customizing Help Output
You can further enrich the generated help content by adding a description, and epilog.
Set the Description
Cake\Console\ConsoleOptionParser::setDescription($text)
The description displays above the argument and option information. By passing in either an array or a string, you can
set the value of the description:// Set multiple lines at once$parser->setDescription(['line one', 'line two']);// Prior to 3.4$parser->description(['line one', 'line two']);// Read the current value$parser->getDescription();Set the Epilog
Cake\Console\ConsoleOptionParser::setEpilog($text)
Gets or sets the epilog for the option parser. The epilog is displayed after the argument and option information. By
passing in either an array or a string, you can set the value of the epilog:// Set multiple lines at once$parser->setEpilog(['line one', 'line two']);// Prior to 3.4$parser->epilog(['line one', 'line two']);// Read the current value$parser->getEpilog();

670

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Adding Subcommands
Cake\Console\ConsoleOptionParser::addSubcommand($name, $options = [])Deprecated since version 3.6.0: Subcommands are deprecated. Instead use nested commands.
Console applications are often made of subcommands, and these subcommands may require special option parsing andhave their own help. A perfect example of this is bake. Bake is made of many separate tasks that all have their own
help and options. ConsoleOptionParser allows you to define subcommands and provide command specific option
parsers so the shell knows how to parse commands for its tasks:$parser->addSubcommand('model', ['help' => 'Bake a model','parser' => $this->Model->getOptionParser()]);
The above is an example of how you could provide help and a specialized option parser for a shell’s task. By calling
the Task’s getOptionParser() we don’t have to duplicate the option parser generation, or mix concerns in our shell.
Adding subcommands in this way has two advantages. First, it lets your shell document its subcommands in thegenerated help. It also gives easy access to the subcommand help. With the above subcommand created you could callcake myshell --help and see the list of subcommands, and also run cake myshell model --help to view thehelp for just the model task.
Note: Once your Shell defines subcommands, all subcommands must be explicitly defined.
When defining a subcommand you can use the following options:• help - Help text for the subcommand.
• parser - A ConsoleOptionParser for the subcommand. This allows you to create method specific option parsers.
When help is generated for a subcommand, if a parser is present it will be used. You can also supply the parser
as an array that is compatible with Cake\Console\ConsoleOptionParser::buildFromArray()Adding subcommands can be done as part of a fluent method chain.
Changed in version 3.5.0: When adding multi-word subcommands you can now invoke those commands using
snake_case in addition to the camelBacked form.

Shell Helpers
New in version 3.1: Shell Helpers were added in 3.1.0
Shell Helpers let you package up complex output generation code. See Command Helpers for more information.

Running Shells as Cron Jobs
A common thing to do with a shell is making it run as a cronjob to clean up the database once in a while or send
newsletters. This is trivial to setup, for example:
*/5
# *
#
#
#

*
*

*
*

*
*

*
*

\

cd /full/path/to/root && bin/cake myshell myparamcommand to execute

day of week (0 - 6) (0 to 6 are Sunday to Saturday,(continues on next page)

Commands

671

CakePHP Book, Release 3.10

(continued from previous page)

# |
#
#
#
# \

|

|

|
\

\
\

or use names)
month (1 - 12)
day of month (1 - 31)
hour (0 - 23)
min (0 - 59)

You can see more info here: https://en.wikipedia.org/wiki/Cron
Tip: Use -q (or –quiet) to silence any output for cronjobs.

Cron Jobs on Shared Hosting
On some shared hostings cd /full/path/to/root && bin/cake myshell myparam might not work. Instead you
can use php /full/path/to/root/bin/cake.php myshell myparam.
Note: register_argc_argv has to be turned on by including register_argc_argv = 1 in your php.ini. If you cannotchange register_argc_argv globally, you can tell the cron job to use your own configuration by specifying it with -dregister_argc_argv=1 parameter. Example: php -d register_argc_argv=1 /full/path/to/root/bin/cake.php myshell myparam

CakePHP Provided Commands
Cache Shell
To help you better manage cached data from a CLI environment, a shell command is available for clearing cached data
your application has:// Clear one cache config
bin/cake cache clear <configname>// Clear all cache configs
bin/cake cache clear_all
New in version 3.3.0: The cache shell was added in 3.3.0

I18N Shell
The i18n features of CakePHP use po files152 as their translation source. PO files integrate with commonly usedtranslation tools like Poedit153 .
The i18n shell provides a quick and easy way to generate po template files. These templates files can then be given
to translators so they can translate the strings in your application. Once you have translations done, pot files can bemerged with existing translations to help update your translations.
152 https://en.wikipedia.org/wiki/GNU_gettext
153 https://www.poedit.net/

672

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Generating POT Files
POT files can be generated for an existing application using the extract command. This command will scan yourentire application for __() style function calls, and extract the message string. Each unique string in your application
will be combined into a single POT file:bin/cake i18n extract
The above will run the extraction shell. The result of this command will be the file src/Locale/default.pot. You use
the pot file as a template for creating po files. If you are manually creating po files from the pot file, be sure to correctly
set the Plural-Forms header line.
Generating POT Files for Plugins
You can generate a POT file for a specific plugin using:bin/cake i18n extract --plugin <Plugin>This will generate the required POT files used in the plugins.
Extracting from multiple folders at once
Sometimes, you might need to extract strings from more than one directory of your application. For instance, if you
are defining some strings in the config directory of your application, you probably want to extract strings from thisdirectory as well as from the src directory. You can do it by using the --paths option. It takes a comma-separated
list of absolute paths to extract:bin/cake i18n extract --paths /var/www/app/config,/var/www/app/src

Excluding Folders
You can pass a comma separated list of folders that you wish to be excluded. Any path containing a path segment withthe provided values will be ignored:
bin/cake i18n extract --exclude vendor,tests

Skipping Overwrite Warnings for Existing POT Files
By adding --overwrite, the shell script will no longer warn you if a POT file already exists and will overwrite by
default:
bin/cake i18n extract --overwrite

CakePHP Provided Commands

673

CakePHP Book, Release 3.10

Extracting Messages from the CakePHP Core Libraries
By default, the extract shell script will ask you if you like to extract the messages used in the CakePHP core libraries.
Set --extract-core to yes or no to set the default behavior:bin/cake i18n extract --extract-core yes// orbin/cake i18n extract --extract-core noCompletion Shell
Working with the console gives the developer a lot of possibilities but having to completely know and write thosecommands can be tedious. Especially when developing new shells where the commands differ per minute iteration.
The Completion Shells aids in this matter by providing an API to write completion scripts for shells like bash, zsh, fishetc.
Sub Commands
The Completion Shell consists of a number of sub commands to assist the developer creating its completion script.
Each for a different step in the autocompletion process.
Commands
For the first step commands outputs the available Shell Commands, including plugin name when applicable. (Allreturned possibilities, for this and the other sub commands, are separated by a space.) For example:
bin/cake Completion commands
Returns:
acl api bake command_list completion console i18n schema server test testsuite upgradeYour completion script can select the relevant commands from that list to continue with. (For this and the following
sub commands.)
subCommands
Once the preferred command has been chosen subCommands comes in as the second step and outputs the possible subcommand for the given shell command. For example:
bin/cake Completion subcommands bake
Returns:
controller db_config fixture model plugin project test view

674

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

options
As the third and final options outputs options for the given (sub) command as set in getOptionParser. (Including thedefault options inherited from Shell.) For example:
bin/cake Completion options bake
Returns:--help -h --verbose -v --quiet -q --everything --connection -c --force -f --plugin -p -˓→prefix --theme -t
You can also pass an additional argument being the shell sub-command : it will output the specific options of thissub-command.
How to enable Bash autocompletion for the CakePHP Console
First, make sure the bash-completion library is installed. If not, you do it with the following command:
apt-get install bash-completion
Create a file named cake in /etc/bash_completion.d/ and put the Bash Completion file content inside it.
Save the file, then restart your console.
Note: If you are using MacOS X, you can install the bash-completion library using homebrew with the commandbrew install bash-completion. The target directory for the cake file will be /usr/local/etc/bash_completion.d/.

Bash Completion file content
This is the code you need to put inside the cake file in the correct location in order to get autocompletion when using
the CakePHP console:## Bash completion file for CakePHP console#_cake(){
local cur prev opts cake
COMPREPLY=()
cake="${COMP_WORDS[0]}"cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
if [[ "$cur" == -* ]] ; thenif [[ ${COMP_CWORD} = 1 ]] ; then
opts=$(${cake} Completion options)elif [[ ${COMP_CWORD} = 2 ]] ; then
opts=$(${cake} Completion options "${COMP_WORDS[1]}")else(continues on next page)

CakePHP Provided Commands

675

CakePHP Book, Release 3.10

(continued from previous page)

opts=$(${cake} Completion options "${COMP_WORDS[1]}" "${COMP_WORDS[2]}")fi
COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )return 0fi
if [[ ${COMP_CWORD} = 1 ]] ; then
opts=$(${cake} Completion commands)
COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )return 0fi
if [[ ${COMP_CWORD} = 2 ]] ; then
opts=$(${cake} Completion subcommands $prev)
COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )if [[ $COMPREPLY = "" ]] ; then_filedir
return 0fi
return 0
fi
opts=$(${cake} Completion fuzzy "${COMP_WORDS[@]:1}")
COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )if [[ $COMPREPLY = "" ]] ; then_filedir
return 0fi
return 0;}
complete -F _cake cake bin/cakeUsing autocompletion
Once enabled, the autocompletion can be used the same way than for other built-in commands, using the TAB key.
Three type of autocompletion are provided. The following output are from a fresh CakePHP install.
Commands
Sample output for commands autocompletion:$ bin/cake <tab>
bake
i18n
consolemigrations

676

schema_cache
pluginroutesserver

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Subcommands
Sample output for subcommands autocompletion:$ bin/cake bake <tab>behavior
helpercellmailercomponent
migration
controller
migration_snapshot
fixturemodel
form
pluginshell
shell_helper
template
test

Options
Sample output for subcommands options autocompletion:$ bin/cake bake -<tab>-c--everything˓→-v--connection -f
˓→theme--verbose--force--help--plugin

-q

-t

-h

-p

--prefix--quiet--␣

Plugin Shell
The plugin shell allows you to load and unload plugins via the command prompt. If you need help, run:bin/cake plugin --help

Loading Plugins
Via the Load task you are able to load plugins in your config/bootstrap.php. You can do this by running:bin/cake plugin load MyPlugin
This will add the following to your src/Application.php:// In the bootstrap method add:
$this->addPlugin('MyPlugin');// Prior to 3.6, add the following to config/bootstrap.php
Plugin::load('MyPlugin');If you are loading a plugin that only provides CLI tools - like bake - you can update your bootstrap_cli.php with:bin/cake plugin load --cli MyPlugin
bin/cake plugin unload --cli MyPlugin
New in version 3.4.0: As of 3.4.0 the --cli option is supported

CakePHP Provided Commands

677

CakePHP Book, Release 3.10

Unloading Plugins
You can unload a plugin by specifying its name:bin/cake plugin unload MyPlugin
This will remove the line $this->addPlugin('MyPlugin',...) from src/Application.php.
Plugin Assets
CakePHP by default serves plugins assets using the AssetMiddleware middleware. While this is a good convenience,
it is recommended to symlink / copy the plugin assets under app’s webroot so that they can be directly served by the
web server without invoking PHP. You can do this by running:bin/cake plugin assets symlink
Running the above command will symlink all plugins assets under app’s webroot. On Windows, which doesn’t support
symlinks, the assets will be copied in respective folders instead of being symlinked.
You can symlink assets of one particular plugin by specifying its name:bin/cake plugin assets symlink MyPlugin

Routes Shell
New in version 3.1: The RoutesShell was added in 3.1
The RoutesShell provides a simple to use CLI interface for testing and debugging routes. You can use it to test how
routes are parsed, and what URLs routing parameters will generate.
Getting a List of all Routes
bin/cake routes

Testing URL parsing
You can quickly see how a URL will be parsed using the check method:bin/cake routes check /bookmarks/edit/1
If your route contains any query string parameters remember to surround the URL in quotes:
bin/cake routes check "/bookmarks/?page=1&sort=title&direction=desc"

678

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

Testing URL Generation
You can see how which URL a routing array will generate using the generate method:bin/cake routes generate controller:Bookmarks action:edit 1

Server Shell
The ServerShell lets you stand up a simple webserver using the built in PHP webserver. While this server is notintended for production use it can be handy in development when you want to quickly try an idea out and don’t want tospend time configuring Apache or Nginx. You can start the server shell with:$ bin/cake server
You should see the server boot up and attach to port 8765. You can visit the CLI server by visiting http://
localhost:8765 in your web-browser. You can close the server by pressing CTRL-C in your terminal.
Note: Try bin/cake server -H 0.0.0.0 if the server is unreachable from other hosts.

Changing the Port and Document RootYou can customize the port and document root using options:$ bin/cake server --port 8080 --document_root path/to/app

Upgrade Shell
The upgrade shell will do most of the work to upgrade your CakePHP application from 2.x to 3.x.
It is provided by a standalone Upgrade plugin154 . Please read the README file to get all information on how to upgrade
your application.

Shellsclass Cake\Console\Shell
Deprecated since version 3.6.0: Shells are deprecated as of 3.6.0, but will not be removed until 5.x. Use Console
Commands instead.
154 https://github.com/cakephp/upgrade

CakePHP Provided Commands

679

CakePHP Book, Release 3.10

Creating a Shell
Let’s create a shell for use in the Console. For this example, we’ll create a simple Hello world shell. In your application’s
src/Shell directory create HelloShell.php. Put the following code inside it:namespace App\Shell;use Cake\Console\Shell;class HelloShell extends Shell{
public function main(){$this->out('Hello world.');}}The conventions for shell classes are that the class name should match the file name, with the suffix of Shell. In ourshell we created a main() method. This method is called when a shell is called with no additional commands. We’ll
add some more commands in a bit, but for now let’s just run our shell. From your application directory, run:bin/cake hello
You should see the following output:
Hello world.
As mentioned before, the main() method in shells is a special method called whenever there are no other commands
or arguments given to a shell. Since our main method wasn’t very interesting let’s add another command that does
something: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);}}
After saving this file, you should be able to run the following command and see your name printed out:
bin/cake hello hey_there your-nameAny public method not prefixed by an _ is allowed to be called from the command line. As you can see, methods invokedfrom the command line are transformed from the underscored shell argument to the correct camel-cased method namein the class.
680

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

In our heyThere() method we can see that positional arguments are provided to our heyThere() function. Positional
arguments are also available in the args property. You can access switches or options on shell applications, which areavailable at $this->params, but we’ll cover that in a bit.
When using a main() method you won’t be able to use the positional arguments. This is because the first positional
argument or option is interpreted as the command name. If you want to use arguments, you should use method names
other than main.
Shell Tasks
There will be times when building more advanced console applications, you’ll want to compose functionality into reusable classes that can be shared across many shells. Tasks allow you to extract commands into classes. For example
the bake command is made almost entirely of tasks. You define a tasks for a shell using the $tasks property:
class UserShell extends Shell{
public $tasks = ['Template'];}You can use tasks from plugins using the standard plugin syntax. Tasks are stored in Shell/Task/ infiles named after their classes. So if we were to create a new ‘FileGenerator’ task, you would create
src/Shell/Task/FileGeneratorTask.php.
Each task must at least implement a main() method. The ShellDispatcher, will call this method when the task isinvoked. A task class looks like:namespace App\Shell\Task;
use Cake\Console\Shell;class FileGeneratorTask extends Shell{
public function main(){}}
A shell can also access its tasks as properties, which makes tasks great for making re-usable chunks of functionality
similar to Components:// Found in src/Shell/SeaShell.php
class SeaShell extends Shell{// Found in src/Shell/Task/SoundTask.php
public $tasks = ['Sound'];public function main(){$this->Sound->main();}}
You can also access tasks directly from the command line:

CakePHP Provided Commands

681

CakePHP Book, Release 3.10

$ cake sea soundNote: In order to access tasks directly from the command line, the task must be included in the shell class’ $tasks
property.
Also, the task name must be added as a sub-command to the Shell’s OptionParser:
public function getOptionParser(){$parser = parent::getOptionParser();$parser->addSubcommand('sound', [// Provide help text for the command list
'help' => 'Execute The Sound Task.',// Link the option parsers together.
'parser' => $this->Sound->getOptionParser(),]);
return $parser;}

Loading Tasks On The Fly with TaskRegistry
You can load tasks on the fly using the Task registry object. You can load tasks that were not declared in $tasks thisway:$project = $this->Tasks->load('Project');
Would load and return a ProjectTask instance. You can load tasks from plugins using:$progressBar = $this->Tasks->load('ProgressBar.ProgressBar');

Using Models in Your Shells
You’ll often need access to your application’s business logic in shell utilities; CakePHP makes that super easy. You canload models in shells, just as you would in a controller using loadModel(). The loaded models are set as properties
attached to your shell:namespace App\Shell;use Cake\Console\Shell;class UserShell extends Shell{
public function initialize(){
parent::initialize();$this->loadModel('Users');}
public function show()(continues on next page)682

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page){if (empty($this->args[0])) {// Use error() before CakePHP 3.2
return $this->abort('Please enter a username.');}$user = $this->Users->findByUsername($this->args[0])->first();$this->out(print_r($user, true));}}
The above shell, will fetch a user by username and display the information stored in the database.
Shell Helpers
If you have complex output generation logic, you can use Shell Helpers to encapsulate this logic in a re-usable way.
Invoking Other Shells from Your Shell
Cake\Console\Shell::dispatchShell($args)
There are still many cases where you will want to invoke one shell from another though. Shell::dispatchShell()gives you the ability to call other shells by providing the argv for the sub shell. You can provide arguments and options
either as var args or as a string:// As a string$this->dispatchShell('schema create Blog --plugin Blog');// As an array$this->dispatchShell('schema', 'create', 'Blog', '--plugin', 'Blog');
The above shows how you can call the schema shell to create the schema for a plugin from inside your plugin’s shell.
Passing extra parameters to the dispatched Shell
New in version 3.1.
It can sometimes be useful to pass on extra parameters (that are not shell arguments) to the dispatched Shell. In orderto do this, you can now pass an array to dispatchShell(). The array is expected to have a command key as well as
an extra key:// Using a command string$this->dispatchShell(['command' => 'schema create Blog --plugin Blog','extra' => ['foo' => 'bar']]);// Using a command array$this->dispatchShell(['command' => ['schema', 'create', 'Blog', '--plugin', 'Blog'],(continues on next page)

CakePHP Provided Commands

683

CakePHP Book, Release 3.10

(continued from previous page)'extra' => ['foo' => 'bar']]);
Parameters passed through extra will be merged in the Shell::$params property and are accessible with theShell::param() method. By default, a requested extra param is automatically added when a Shell is dispatchedusing dispatchShell(). This requested parameter prevents the CakePHP console welcome message from being
displayed on dispatched shells.
Parsing CLI Options
Shells use Option Parsers to define their options, arguments and automate help generation.
Interacting with Input/Output
Shells allow you to access a ConsoleIo instance via the getIo() method. See the Command Input/Output section
for more information.
In addition to the ConsoleIo object, Shell classes offer a suite of shortcut methods. These methods are shortcuts andaliases to those found on ConsoleIo:// Get arbitrary text from the user.
$color = $this->in('What color do you like?');// Get a choice from the user.
$selection = $this->in('Red or Green?', ['R', 'G'], 'R');// Create a file
$this->createFile('bower.json', $stuff);// Write to stdout$this->out('Normal message');// Write to stderr$this->err('Error message');// Write to stderr and raise a stop exception$this->abort('Fatal error');// Before CakePHP 3.2. Write to stderr and exit()$this->error('Fatal error');It also provides two convenience methods regarding the output level:// Would only appear when verbose output is enabled (-v)
$this->verbose('Verbose message');// Would appear at all levels.
$this->quiet('Quiet message');
Shell also includes methods for clearing output, creating blank lines, or drawing a line of dashes:

684

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10// Output 2 newlines$this->out($this->nl(2));// Clear the user's screen$this->clear();// Draw a horizontal line
$this->hr();

Stopping Shell Execution
When your shell commands have reached a condition where you want execution to stop, you can use abort() to raisea StopException that will halt the process:$user = $this->Users->get($this->args[0]);if (!$user) {// Halt with an error message and error code.
$this->abort('User cannot be found', 128);}
New in version 3.2: The abort() method was added in 3.2. In prior versions you can use error() to output a message
and stop execution.
Status and Error Codes
Command-line tools should return 0 to indicate success, or a non-zero value to indicate an error condition. Since
PHP methods usually return true or false, the Cake Shell dispatch function helps to bridge these semantics byconverting your null and true return values to 0, and all other values to 1.
The Cake Shell dispatch function also catches the StopException and uses its exception code value as the shell’s
exit code. As described above, you can use the abort() method to print a message and exit with a specific code, orraise the StopException directly as shown in the example:
namespace App\Shell\Task;
use Cake\Console\Shell;class ErroneousShell extends Shell{
public function main(){return true;}
public function itFails(){
return false;}
public function itFailsSpecifically(){
throw new StopException("", 2);(continues on next page)

CakePHP Provided Commands

685

CakePHP Book, Release 3.10

(continued from previous page)}}The example above will return the following exit codes when executed on a command-line:$ bin/cake erroneousshell ; echo $?
0$ bin/cake erroneousshell itFails ; echo $?
1$ bin/cake erroneousshell itFailsSpecifically ; echo $?
2

Tip: Avoid exit codes 64 - 78, as they have specific meanings described by sysexits.h. Avoid exit codes above 127,
as these are used to indicate process exit by signal, such as SIGKILL or SIGSEGV.

Note: You can read more about conventional exit codes in the sysexit manual page on most Unix systems (mansysexits), or the System Error Codes help page in Windows.

Hook Methods
Cake\Console\Shell::initialize()
Initializes the Shell, acts as constructor for subclasses and allows configuration of tasks prior to shell execution.
Cake\Console\Shell::startup()
Starts up the Shell and displays the welcome message. Allows for checking and configuring prior to commandor main execution.
Tip: Override the startup() method if you want to remove the welcome information, or otherwise modify the
pre-command flow.
Avoid exit codes 64 - 78, as they have specific meanings described by sysexits.h. Avoid exit codes above 127, asthese are used to indicate process exit by signal, such as SIGKILL or SIGSEGV.

Interactive Console (REPL)The CakePHP app skeleton comes with a built in REPL(Read Eval Print Loop) that makes it easy to explore some
CakePHP and your application in an interactive console. You can start the interactive console using:$ bin/cake console
This will bootstrap your application and start an interactive console. At this point you can interact with your application
code and execute queries using your application’s models:$ bin/cake console
Welcome to CakePHP v3.0.0 Console--------------------------------------------------------------(continues on next page)

686

Chapter 15. Console Tools, Shells & Tasks

CakePHP Book, Release 3.10

(continued from previous page)

App : App
Path: /Users/mark/projects/cakephp-app/src/-------------------------------------------------------------->>> $articles = Cake\ORM\TableRegistry::getTableLocator()->get('Articles');// object(Cake\ORM\Table)(//// )>>> $articles->find()->all();
Since your application has been bootstrapped you can also test routing using the REPL:>>> Cake\Routing\Router::parse('/articles/view/1');// [//'controller' => 'Articles',//'action' => 'view',//'pass' => [//0 => '1'//],//'plugin' => NULL// ]You can also test generating URLs:>>> Cake\Routing\Router::url(['controller' => 'Articles', 'action' => 'edit', 99]);// '/articles/edit/99'
To quit the REPL you can use CTRL-C or by typing exit.

ORM Cache Shell
Deprecated since version 3.6.0: The OrmCacheShell is replaced by Schema Cache Shell

Routing in the Console Environment
In command-line interface (CLI), specifically your shells and tasks, env('HTTP_HOST') and other webbrowser specificenvironment variables are not set.
If you generate reports or send emails that make use of Router::url() those will contain the default host http://
localhost/ and thus resulting in invalid URLs. In this case you need to specify the domain manually. You can dothat using the Configure value App.fullBaseUrl from your bootstrap or config, for example.
For sending emails, you should provide Email class with the host you want to send the email with:
use Cake\Mailer\Email;$email = new Email();// Prior to 3.4 use domain()$email->setDomain('www.example.org');
This asserts that the generated message IDs are valid and fit to the domain the emails are sent from.

Routing in the Console Environment

687

CakePHP Book, Release 3.10

688

Chapter 15. Console Tools, Shells & Tasks

CHAPTER 16

Debugging

Debugging is an inevitable and necessary part of any development cycle. While CakePHP doesn’t offer any tools that
directly connect with any IDE or editor, CakePHP does provide several tools to assist in debugging and exposing what
is running under the hood of your application.

Basic Debugging
debug(mixed $var, boolean $showHtml = null, $showFrom = true)
The debug() function is a globally available function that works similarly to the PHP function print_r(). The
debug() function allows you to show the contents of a variable in a number of different ways. First, if you’d like data
to be shown in an HTML-friendly way, set the second parameter to true. The function also prints out the line and file
it is originating from by default.
Output from this function is only shown if the core $debug variable has been set to true.
New in version 3.3.0: Calling this method will return passed $var, so that you can, for instance, place it in returnstatements, for example:
return debug($data); // will return $data in any case.
Also see dd(), pr() and pj().
stackTrace()
The stackTrace() function is available globally, and allows you to output a stack trace wherever the function is called.
breakpoint()
New in version 3.1.

689

CakePHP Book, Release 3.10

If you have Psysh155 installed you can use this function in CLI enviroments to open an interactive console with thecurrent local scope:// Some codeeval(breakpoint());
Will open an interactive console that can be used to check local variables and execute other code. You can exit theinteractive debugger and resume the original execution by running quit or q in the interactive session.

Using the Debugger Class
class Cake\Error\Debugger
To use the debugger, first ensure that Configure::read('debug') is set to true.

Outputting Values
static Cake\Error\Debugger::dump($var, $depth = 3)
Dump prints out the contents of a variable. It will print out all properties and methods (if any) of the supplied variable:$foo = [1,2,3];
Debugger::dump($foo);// Outputs
array(
1,
2,
3)// Simple object$car = new Car();Debugger::dump($car);// Outputs
object(Car) {color => 'red'
make => 'Toyota'
model => 'Camry'
mileage => (int)15000}
155 https://psysh.org/

690

Chapter 16. Debugging

CakePHP Book, Release 3.10

Masking Data
When dumping data with Debugger or rendering error pages, you may want to hide sensitive keys like passwords or
API keys. In your config/bootstrap.php you can mask specific keys:
Debugger::setOutputMask(['password' => 'xxxxx','awsKey' => 'yyyyy',]);
New in version 3.4.0: Output masking was added in 3.4.0

Logging With Stack Traces
static Cake\Error\Debugger::log($var, $level = 7, $depth = 3)
Creates a detailed stack trace log at the time of invocation. The log() method prints out data similar to that done by
Debugger::dump(), but to the debug.log instead of the output buffer. Note your tmp directory (and its contents) must
be writable by the web server for log() to work correctly.

Generating Stack Traces
static Cake\Error\Debugger::trace($options)
Returns the current stack trace. Each line of the trace includes the calling method, including which file and line the calloriginated from:// In PostsController::index()pr(Debugger::trace());// Outputs
PostsController::index() - APP/Controller/DownloadsController.php, line 48
Dispatcher::_invoke() - CORE/src/Routing/Dispatcher.php, line 265
Dispatcher::dispatch() - CORE/src/Routing/Dispatcher.php, line 237[main] - APP/webroot/index.php, line 84
Above is the stack trace generated by calling Debugger::trace() in a controller action. Reading the stack trace
bottom to top shows the order of currently running functions (stack frames).

Getting an Excerpt From a Filestatic Cake\Error\Debugger::excerpt($file, $line, $context)
Grab an excerpt from the file at $path (which is an absolute filepath), highlights line number $line with $context numberof lines around it.
pr(Debugger::excerpt(ROOT . DS . LIBS . 'debugger.php', 321, 2));// Will output the following.
(continues on next page)

Logging With Stack Traces691

CakePHP Book, Release 3.10

(continued from previous page)Array([0] => <code><span style="color: #000000"> * @access public</span></code>[1] => <code><span style="color: #000000"> */</span></code>[2] => <code><span style="color: #000000">function excerpt($file, $line,
˓→$context = 2) {</span></code>[3] => <span class="code-highlight"><code><span style="color: #000000">$data␣
= $lines = array();</span></code></span>[4] => <code><span style="color: #000000">$data = @explode("\n", file_get_
˓→contents($file));</span></code>)˓→

Although this method is used internally, it can be handy if you’re creating your own error messages or log entries forcustom situations.
static Cake\Error\Debugger::getType($var)
Get the type of a variable. Objects will return their class name

Using Logging to Debug
Logging messages is another good way to debug applications, and you can use Cake\Log\Log to do logging in yourapplication. All objects that use LogTrait have an instance method log() which can be used to log messages:$this->log('Got here', 'debug');
The above would write Got here into the debug log. You can use log entries to help debug methods that involve
redirects or complicated loops. You can also use Cake\Log\Log::write() to write log messages. This method canbe called statically anywhere in your application one Log has been loaded:// At the top of the file you want to log in.
use Cake\Log\Log;// Anywhere that Log has been imported.
Log::debug('Got here');Debug Kit
DebugKit is a plugin that provides a number of good debugging tools. It primarily provides a toolbar in the renderedHTML, that provides a plethora of information about your application and the current request. See the DebugKit
Documentation156 for how to install and use DebugKit.

156 https://book.cakephp.org/debugkit/

692

Chapter 16. Debugging

CHAPTER 17

Deployment

Once your application is complete, or even before that you’ll want to deploy it. There are a few things you should dowhen deploying a CakePHP application.

Moving files
You are encouraged to create a git commit and pull or clone that commit or repository on your server and run composer
install. While this requires some knowledge about git and an existing install of git and composer this process willtake care about library dependencies and file and folder permissions.
Be aware that when deploying via FTP you will at least have to fix file and folder permissions.
You can also use this deployment technique to setup a staging- or demo-server (pre-production) and keep it in sync
with your dev box.

Adjust config/app.php
Adjusting app.php, specifically the value of debug is extremely important. Turning debug = false disables a numberof development features that should never be exposed to the Internet at large. Disabling debug changes the following
types of things:• Debug messages, created with pr(), debug() and dd() are disabled.
• Core CakePHP caches are by default flushed every year (about 365 days), instead of every 10 seconds as indevelopment.
• Error views are less informative, and give generic error messages instead.
• PHP Errors are not displayed.
• Exception stack traces are disabled.

693

CakePHP Book, Release 3.10

In addition to the above, many plugins and application extensions use debug to modify their behavior.
You can check against an environment variable to set the debug level dynamically between environments. This will
avoid deploying an application with debug true and also save yourself from having to change the debug level eachtime before deploying to a production environment.
For example, you can set an environment variable in your Apache configuration:
SetEnv CAKEPHP_DEBUG 1
And then you can set the debug level dynamically in app.php:$debug = (bool)getenv('CAKEPHP_DEBUG');
return ['debug' => $debug,
.....
];

Check Your Security
If you’re throwing your application out into the wild, it’s a good idea to make sure it doesn’t have any obvious leaks:• Ensure you are using the Cross Site Request Forgery component or middleware.
• You may want to enable the Security component. It can help prevent several types of form tampering and reduce
the possibility of mass-assignment issues.
• Ensure your models have the correct Validation rules enabled.
• Check that only your webroot directory is publicly visible, and that your secrets (such as your app salt, and any
security keys) are private and unique as well.

Set Document Root
Setting the document root correctly on your application is an important step to keeping your code secure and yourapplication safer. CakePHP applications should have the document root set to the application’s webroot. This makes
the application and configuration files inaccessible through a URL. Setting the document root is different for different
webservers. See the URL Rewriting documentation for webserver specific information.
In all cases you will want to set the virtual host/domain’s document to be webroot/. This removes the possibility offiles outside of the webroot directory being executed.

Improve Your Application’s Performance
Class loading can take a big share of your application’s processing time. In order to avoid this problem, it is recommended that you run this command in your production server once the application is deployed:
php composer.phar dump-autoload -o694

Chapter 17. Deployment

CakePHP Book, Release 3.10

Warning:
If you are using deprecated class names in your project or plugins, don’t combine this with-a/--classmap-authoritative. This breaks the class aliases. Instead, you can use the mentioned option 2b157
instead using --apcu as additional optimization if APCu is installed.
Since handling static assets, such as images, JavaScript and CSS files of plugins, through the Dispatcher is incredibly
inefficient, it is strongly recommended to symlink them for production. This can be done by using the plugin shell:
bin/cake plugin assets symlink
The above command will symlink the webroot directory of all loaded plugins to appropriate path in the app’s webrootdirectory.
If your filesystem doesn’t allow creating symlinks the directories will be copied instead of being symlinked. You canalso explicitly copy the directories using:bin/cake plugin assets copy

Deploying an update
After deployment of an update you might also want to run bin/cake schema_cache clear, part of the Schema
Cache Shell shell.

157 https://getcomposer.org/doc/articles/autoloader-optimization.md#optimization-level-2-b-apcu-cache

Deploying an update695CakePHP Book, Release 3.10

696

Chapter 17. Deployment

CHAPTER 18

Email

Warning: Before version 3.1, the Email and Transport classes were under the Cake\Network\Email namespace instead of the Cake\Mailer namespace.
class Cake\Mailer\Email(mixed $profile = null)
Email is a new class to send email. With this class you can send email from any place inside of your application.

Basic UsageFirst of all, you should ensure the class is loaded:
use Cake\Mailer\Email;
After you’ve loaded Email, you can send an email with the following:$email = new Email('default');$email->from(['me@example.com' => 'My Site'])->to('you@example.com')->subject('About')->send('My message');
Since Email’s setter methods return the instance of the class, you are able to set its properties with method chaining.
Email has several methods for defining recipients - to(), cc(), bcc(), addTo(), addCc() and addBcc(). The maindifference being that the first three will overwrite what was already set and the latter will just add more recipients totheir respective field:

697

CakePHP Book, Release 3.10

$email = new Email();$email->to('to@example.com', 'To Example');$email->addTo('to2@example.com', 'To2 Example');// The email's To recipients are: to@example.com and to2@example.com$email->to('test@example.com', 'ToTest Example');// The email's To recipient is: test@example.com
Deprecated since version 3.4.0: Use setFrom(), setTo(), setCc() , setBcc() and setSubject() instead offrom(), to(), cc(), bcc() and subject()

Choosing the Sender
When sending email on behalf of other people, it’s often a good idea to define the original sender using the Sender
header. You can do so using sender():$email = new Email();$email->sender('app@example.com', 'MyApp emailer');

Note: It’s also a good idea to set the envelope sender when sending mail on another person’s behalf. This prevents
them from getting any messages about deliverability.
Deprecated since version 3.4.0: Use setSender() instead.

Configuration
Configuration for Email defaults is created using config() and configTransport(). You should put your emailpresets in the config/app.php file. The config/app.default.php file is an example of this file. It is not required todefine email configuration in config/app.php. Email can be used without it and use the respective methods to set all
configurations separately or load an array of configs.
By defining profiles and transports, you can keep your application code free of configuration data, and avoid duplicationthat makes maintenance and deployment more difficult.
To load a predefined configuration, you can use the profile() method or pass it to the constructor of Email:$email = new Email();$email->profile('default');// Or in constructor$email = new Email('default');
Instead of passing a string which matches a preset configuration name, you can also just load an array of options:$email = new Email();$email->profile(['from' => 'me@example.org', 'transport' => 'my_custom']);// Or in constructor$email = new Email(['from' => 'me@example.org', 'transport' => 'my_custom']);Changed in version 3.1: The default email profile is automatically set when an Email instance is created.
Deprecated since version 3.4.0: Use setProfile() instead of profile().
698

Chapter 18. EmailCakePHP Book, Release 3.10

Configuring Transports
static Cake\Mailer\Email::configTransport($key, $config)
Email messages are delivered by transports. Different transports allow you to send messages via PHP’s mail() function, SMTP servers, or not at all which is useful for debugging. Configuring transports allows you to keep configuration
data out of your application code and makes deployment simpler as you can simply change the configuration data. An
example transport configuration looks like:use Cake\Mailer\Email;use Cake\Mailer\TransportFactory;// Sample Mail configuration// Prior to 3.7.0 use Email::configTransport()
TransportFactory::setConfig('default', ['className' => 'Mail']);// Sample SMTP configuration.
TransportFactory::setConfig('gmail', ['host' => 'ssl://smtp.gmail.com','port' => 465,
'username' => 'my@gmail.com','password' => 'secret','className' => 'Smtp']);
You can configure SSL SMTP servers, like Gmail. To do so, put the ssl:// prefix in the host and configure the port
value accordingly. You can also enable TLS SMTP using the tls option:
use Cake\Mailer\Email;use Cake\Mailer\TransportFactory;
TransportFactory::setConfig('gmail', ['host' => 'smtp.gmail.com','port' => 587,
'username' => 'my@gmail.com','password' => 'secret','className' => 'Smtp','tls' => true]);
The above configuration would enable TLS communication for email messages.
Warning: You will need to have access for less secure apps enabled in your Google account for this to work:
Allowing less secure apps to access your account158 .

Note: Gmail SMTP settings159 .
158 https://support.google.com/accounts/answer/6010255
159 https://support.google.com/a/answer/176600?hl=en

Configuration

699

CakePHP Book, Release 3.10

Note: To use SSL + SMTP, you will need to have the SSL configured in your PHP install.
Configuration options can also be provided as a DSN string. This is useful when working with environment variables
or PaaS providers:
TransportFactory::setConfig('default', ['url' => 'smtp://my@gmail.com:secret@smtp.gmail.com:587?tls=true',]);// Prior to 3.7.0 use
Email::configTransport('default', ['url' => 'smtp://my@gmail.com:secret@smtp.gmail.com:587?tls=true',]);
When using a DSN string you can define any additional parameters/options as query string arguments.
static Cake\Mailer\Email::dropTransport($key)
Once configured, transports cannot be modified. In order to modify a transport you must first drop it and then reconfigure it.

Configuration Profiles
Defining delivery profiles allows you to consolidate common email settings into re-usable profiles. Your application
can have as many profiles as necessary. The following configuration keys are used:• 'from': Email or array of sender. See Email::from().
• 'sender': Email or array of real sender. See Email::sender().
• 'to': Email or array of destination. See Email::to().
• 'cc': Email or array of carbon copy. See Email::cc().
• 'bcc': Email or array of blind carbon copy. See Email::bcc().
• 'replyTo': Email or array to reply the e-mail. See Email::replyTo().
• 'readReceipt': Email address or an array of addresses to receive the receipt of read.
Email::readReceipt().

See• 'returnPath': Email address or an array of addresses to return if have some error.
Email::returnPath().

See• 'messageId': Message ID of e-mail. See Email::messageId().
• 'subject': Subject of the message. See Email::subject().
• 'message': Content of message. Do not set this field if you are using rendered content.
• 'priority': Priority of the email as numeric value (usually from 1 to 5 with 1 being the highest).
• 'headers': Headers to be included. See Email::headers().
• 'viewRender': If you are using rendered content, set the view classname. See Email::viewRender().
• 'template': If you are using rendered content, set the template name. See Email::template().
• 'theme': Theme used when rendering template. See Email::theme().

700

Chapter 18. EmailCakePHP Book, Release 3.10

• 'layout': If you are using rendered content, set the layout to render. If you want to render a template without
layout, set this field to null. See Email::template().
• 'viewVars': If you are using rendered content, set the array with variables to be used in the view. See
Email::setViewVars().
• 'attachments': List of files to attach. See Email::attachments().
• 'emailFormat': Format of email (html, text or both). See Email::emailFormat().
• 'transport': Transport configuration name. See configTransport().
• 'log': Log level to log the email headers and message. true will use LOG_DEBUG. See also Using Levels.
• 'helpers': Array of helpers used in the email template. Email::helpers().
All these configurations are optional, except 'from'.
Note: The values of above keys using Email or array, like from, to, cc, etc will be passed as first parameter ofcorresponding methods. The equivalent for: Email::from('my@example.com', 'My Site') would be defined as'from' => ['my@example.com' => 'My Site'] in your config

Setting Headers
In Email you are free to set whatever headers you want. When migrating to use Email, do not forget to put the Xprefix in your headers.
See Email::headers() and Email::addHeaders()
Deprecated since version 3.4.0: Use setHeaders() instead of headers().

Sending Templated Emails
Emails are often much more than just a simple text message. In order to facilitate that, CakePHP provides a way tosend emails using CakePHP’s view layer.
The templates for emails reside in a special folder in your application’s Template directory called Email. Email views
can also use layouts and elements just like normal views:$email = new Email();$email->template('welcome', 'fancy')->emailFormat('html')->to('bob@example.com')->from('app@domain.com')->send();
The
above
would
use
src/Template/Email/html/welcome.ctp
for
the
view
and
src/Template/Layout/Email/html/fancy.ctp for the layout. You can send multipart templated email messages
as well:$email = new Email();$email->template('welcome', 'fancy')(continues on next page)

Setting Headers701

CakePHP Book, Release 3.10

(continued from previous page)->emailFormat('both')->to('bob@example.com')->from('app@domain.com')->send();This would use the following template files:• src/Template/Email/text/welcome.ctp• src/Template/Layout/Email/text/fancy.ctp• src/Template/Email/html/welcome.ctp• src/Template/Layout/Email/html/fancy.ctp
When sending templated emails you have the option of sending either text, html or both.
You can set view variables with Email::setViewVars():$email = new Email('templated');$email->setViewVars(['value' => 12345]);
In your email templates you can use these with:<p>Here is your value: <b><?= $value ?></b></p>
You can use helpers in emails as well, much like you can in normal template files. By default only the HtmlHelper isloaded. You can load additional helpers using the helpers() method:$email->helpers(['Html', 'Custom', 'Text']);When setting helpers be sure to include ‘Html’ or it will be removed from the helpers loaded in your email template.
If you want to send email using templates in a plugin you can use the familiar plugin syntax to do so:$email = new Email();$email->template('Blog.new_comment', 'Blog.auto_message');
The above would use template and layout from the Blog plugin as an example.
In some cases, you might need to override the default template provided by plugins. You can do this using themes bytelling Email to use appropriate theme using Email::theme() method:$email = new Email();$email->template('Blog.new_comment', 'Blog.auto_message');$email->theme('TestTheme');This allows you to override the new_comment template in your theme
fying the Blog plugin.
The template file needs to be created in the
src/Template/Plugin/TestTheme/Plugin/Blog/Email/text/new_comment.ctp.

without modifollowing path:

Deprecated since version 3.4.0:
Use viewBuilder()->setTemplate() instead of template().
Use viewBuilder()->setLayout() instead of the layout argument of template().
Use
viewBuilder()->setTheme() instead of theme().

702

Chapter 18. EmailCakePHP Book, Release 3.10

Sending Attachments
Cake\Mailer\Email::attachments($attachments)
You can attach files to email messages as well. There are a few different formats depending on what kind of files you
have, and how you want the filenames to appear in the recipient’s mail client:
1. String: $email->attachments('/full/file/path/file.png') will attach this file with the name file.png.
2. Array: $email->attachments(['/full/file/path/file.png']) will have the same behavior as using astring.
3. Array with key: $email->attachments(['photo.png' => '/full/some_hash.png']) will attach
some_hash.png with the name photo.png. The recipient will see photo.png, not some_hash.png.
4. Nested arrays:$email->attachments(['photo.png' => ['file' => '/full/some_hash.png','mimetype' => 'image/png','contentId' => 'my-unique-id']]);
The above will attach the file with different mimetype and with custom Content ID (when set the content ID theattachment is transformed to inline). The mimetype and contentId are optional in this form.
4.1.
When you are using the contentId, you can use the file in the HTML body like <img
src="cid:my-content-id">.
4.2. You can use the contentDisposition option to disable the Content-Disposition header for an attachment. This is useful when sending ical invites to clients using outlook.
4.3 Instead of the file option you can provide the file contents as a string using the data option. This allows
you to attach files without needing file paths to them.
Deprecated since version 3.4.0: Use setAttachments() instead of attachments().

Using Transports
Transports are classes designed to send the e-mail over some protocol or method. CakePHP supports the Mail (default),
Debug and SMTP transports.
To configure your method, you must use the Cake\Mailer\Email::transport() method or have the transport inyour configuration:$email = new Email();// Use a named transport already configured using Email::configTransport()$email->transport('gmail');// Use a constructed object.
$transport = new DebugTransport();$email->transport($transport);
Deprecated since version 3.4.0: Use setTransport() instead of transport().
Sending Attachments703

CakePHP Book, Release 3.10

Creating Custom Transports
You are able to create your custom transports to integrate with others email systems (like SwiftMailer). To create yourtransport, first create the file src/Mailer/Transport/ExampleTransport.php (where Example is the name of yourtransport). To start off your file should look like:namespace App\Mailer\Transport;
use Cake\Mailer\AbstractTransport;
use Cake\Mailer\Email;class ExampleTransport extends AbstractTransport{public function send(Email $email){// Do something.
}}
You must implement the method send(Email $email) with your custom logic. Optionally, you can implement theconfig($config) method. config() is called before send() and allows you to accept user configurations. By default,
this method puts the configuration in protected attribute $_config.
If you need to call additional methods on the transport before send, you can use Cake\Mailer\
Email::getTransport() to get an instance of the transport object. Example:$yourInstance = $email->getTransport()->transportClass();$yourInstance->myCustomMethod();$email->send();

Relaxing Address Validation Rules
Cake\Mailer\Email::emailPattern($pattern)
If you are having validation issues when sending to non-compliant addresses, you can relax the pattern used to validate
email addresses. This is sometimes necessary when dealing with some ISPs:$email = new Email('default');// Relax the email pattern, so you can send// to non-conformant addresses.
$email->emailPattern($newPattern);
Deprecated since version 3.4.0: Use setEmailPattern() instead of emailPattern().

704

Chapter 18. EmailCakePHP Book, Release 3.10

Sending Messages Quickly
Sometimes you need a quick way to fire off an email, and you don’t necessarily want to setup a bunch of configurationahead of time. Cake\Mailer\Email::deliver() is intended for that purpose.
You can create your configuration using Cake\Mailer\Email::config(), or use an array with all options that you
need and use the static method Email::deliver(). Example:
Email::deliver('you@example.com', 'Subject', 'Message', ['from' => 'me@example.com']);This method will send an email to “you@example.com”, from “me@example.com” with subject “Subject” and content“Message”.
The return of deliver() is a Cake\Mailer\Email instance with all configurations set. If you do not want to send
the email right away, and wish to configure a few things before sending, you can pass the 5th parameter as false.
The 3rd parameter is the content of message or an array with variables (when using rendered content).
The 4th parameter can be an array with the configurations or a string with the name of configuration in Configure.
If you want, you can pass the to, subject and message as null and do all configurations in the 4th parameter (as array orusing Configure). Check the list of configurations to see all accepted configs.

Sending Emails from CLI
When sending emails within a CLI script (Shells, Tasks, . . . ) you should manually set the domain name for Email touse. It will serve as the host name for the message id (since there is no host name in a CLI environment):$email->domain('www.example.org');// Results in message ids like ``<UUID@www.example.org>`` (valid)// Instead of `<UUID@>`` (invalid)
A valid message id can help to prevent emails ending up in spam folders.
Deprecated since version 3.4.0: Use setDomain() instead of domain().

Creating Reusable Emails
New in version 3.1.0.
Mailers allow you to create reusable emails throughout your application. They can also be used to contain multiple
email configurations in one location. This helps keep your code DRYer and keeps email configuration noise out ofother areas in your application.
In this example we will be creating a Mailer that contains user-related emails. To create our UserMailer, create thefile src/Mailer/UserMailer.php. The contents of the file should look like the following:namespace App\Mailer;
use Cake\Mailer\Mailer;
class UserMailer extends Mailer{
public function welcome($user)(continues on next page)

Sending Messages Quickly

705

CakePHP Book, Release 3.10

(continued from previous page){$this->to($user->email)->subject(sprintf('Welcome %s', $user->name))->template('welcome_mail', 'custom'); // By default template with same name␣
˓→as method name is used.
}public function resetPassword($user){$this->to($user->email)->subject('Reset password')->set(['token' => $user->token]);}}In our example we have created two methods, one for sending a welcome email, and another for sending a password
reset email. Each of these methods expect a user Entity and utilizes its properties for configuring each email.
We are now able to use our UserMailer to send out our user-related emails from anywhere in our application. For
example, if we wanted to send our welcome email we could do the following:namespace App\Controller;
use Cake\Mailer\MailerAwareTrait;class UsersController extends AppController{
use MailerAwareTrait;
public function register(){$user = $this->Users->newEntity();if ($this->request->is('post')) {$user = $this->Users->patchEntity($user, $this->request->getData())
if ($this->Users->save($user)) {$this->getMailer('User')->send('welcome', [$user]);}}$this->set('user', $user);}}If we wanted to completely separate sending a user their welcome email from our application’s code, we can have ourUserMailer subscribe to the Model.afterSave event. By subscribing to an event, we can keep our application’suser-related classes completely free of email-related logic and instructions. For example, we could add the following
to our UserMailer:
public function implementedEvents(){
return ['Model.afterSave' => 'onRegistration'(continues on next page)

706

Chapter 18. EmailCakePHP Book, Release 3.10

(continued from previous page)];}
public function onRegistration(Event $event, EntityInterface $entity, ArrayObject
˓→$options){if ($entity->isNew()) {$this->send('welcome', [$entity]);}}
You can now register the mailer as an event listener and the onRegistration() method will be invoked every time
the Model.afterSave event is fired:// attach to Users event manager$this->Users->getEventManager()->on($this->getMailer('User'));Note: For information on how to register event listener objects, please refer to the Registering Listeners documentation.

Testing EmailTo test email, add Cake\TestSuite\EmailTrait to your test case. The EmailTrait provides your test case with acollection of assertions that you can perform on any emails sent by the application.
Adding the EmailTrait to your test case will replace all of your application’s email transports with the Cake\
TestSuite\TestEmailTransport. This transport intercepts emails instead of sending them, and allows you to assert
against them.
Add the trait to your test case to start testing emails:
namespace App\Test\TestCase;
use Cake\TestSuite\EmailTrait;class MyTestCase extends TestCase{
use EmailTrait;}
New in version 3.7.0: Cake\TestSuite\EmailTrait was added.

Testing Email707

CakePHP Book, Release 3.10

Assertion methods
The Cake\TestSuite\EmailTrait trait provides the following assertions:// Reset the state of TestEmailTransport$this->cleanupEmailTrait();// Asserts an expected number of emails were sent
$this->assertMailCount($count);// Asserts that no emails were sent
$this->assertNoMailSent();// Asserts an email was sent to an address$this->assertMailSentTo($address);// Asserts an email was sent from an address$this->assertMailSentFrom($emailAddress);$this->assertMailSentFrom([$emailAddress => $displayName]);// Asserts an email contains expected contents$this->assertMailContains($contents);// Asserts an email contains expected html contents$this->assertMailContainsHtml($contents);// Asserts an email contains expected text contents$this->assertMailContainsText($contents);// Asserts an email contains the expected value within an Email getter (e.g., "subject")$this->assertMailSentWith($expected, $parameter);// Asserts an email at a specific index was sent to an address$this->assertMailSentToAt($at, $address);// Asserts an email at a specific index was sent from an address$this->assertMailSentFromAt($at, $address);// Asserts an email at a specific index contains expected contents$this->assertMailContainsAt($at, $contents);// Asserts an email at a specific index contains expected html contents$this->assertMailContainsHtmlAt($at, $contents);// Asserts an email at a specific index contains expected text contents$this->assertMailContainsTextAt($at, $contents);// Asserts an email at a specific index contains the expected value within an Email␣
˓→getter (e.g., "subject")$this->assertMailSentWithAt($at, $expected, $parameter);

708

Chapter 18. EmailCHAPTER 19

Error & Exception Handling

CakePHP applications come with error and exception handling setup for you. PHP errors are trapped and displayed orlogged. Uncaught exceptions are rendered into error pages automatically.

Error & Exception Configuration
Error configuration is done in your application’s config/app.php file. By default CakePHP uses Cake\Error\
ErrorHandler to handle both PHP errors and exceptions by default. The error configuration allows you to customize
error handling for your application. The following options are supported:• errorLevel - int - The level of errors you are interested in capturing. Use the built-in PHP error constants, andbitmasks to select the level of error you are interested in. You can set this to E_ALL ^ E_USER_DEPRECATED todisable deprecation warnings.
• trace - bool - Include stack traces for errors in log files. Stack traces will be included in the log after each error.
This is helpful for finding where/when errors are being raised.
• exceptionRenderer - string - The class responsible for rendering uncaught exceptions. If you choose a custom
class you should place the file for that class in src/Error. This class needs to implement a render() method.
• log - bool - When true, exceptions + their stack traces will be logged to Cake\Log\Log.
• skipLog - array - An array of exception classnames that should not be logged. This is useful to remove NotFoundExceptions or other common, but uninteresting log messages.
• extraFatalErrorMemory - int - Set to the number of megabytes to increase the memory limit by when a fatal
error is encountered. This allows breathing room to complete logging or error handling.
By default, PHP errors are displayed when debug is true, and logged when debug is false. The fatal error handler
will be called independent of debug level or errorLevel configuration, but the result will be different based on debug
level. The default behavior for fatal errors is show a page to internal server error (debug disabled) or a page with themessage, file and line (debug enabled).

709

CakePHP Book, Release 3.10

Note: If you use a custom error handler, the supported options will depend on your handler.
class ExceptionRenderer(Exception $exception)

Changing Exception Handling
Exception handling offers several ways to tailor how exceptions are handled. Each approach gives you different amountsof control over the exception handling process.
1. Customize the error templates This allows you to change the rendered view templates as you would any othertemplate in your application.
2. Customize the ErrorController This allows you to control how exception pages are rendered.
3. Customize the ExceptionRenderer This allows you to control how exception pages and logging are performed.
4. Create & register your own error handler This gives you complete control over how errors & exceptions arehandled, logged and rendered.

Customize Error Templates
The default error handler renders all uncaught exceptions your application raises with the help of Cake\Error\
ExceptionRenderer, and your application’s ErrorController.
The error page views are located at src/Template/Error/. By default all 4xx errors use the error400.ctp template, andall 5xx errors use the error500.ctp. Your error templates will have the following variables available:• message The exception message.
• code The exception code.
• url The request URL.
• error The exception object.
In debug mode if your error extends Cake\Core\Exception\Exception the data returned by getAttributes()
will be exposed as view variables as well.
Note: You will need to set debug to false, to see your error404 and error500 templates. In debug mode, you’ll see
CakePHP’s development error page.

Customize the Error Page Layout
By default error templates use src/Template/Layout/error.ctp for a layout. You can use the layout property to picka different layout:// inside src/Template/Error/error400.ctp$this->layout = 'my_error';

710

Chapter 19. Error & Exception HandlingCakePHP Book, Release 3.10

The above would use src/Template/Layout/my_error.ctp as the layout for your error pages.
Many exceptions raised by CakePHP will render specific view templates in debug mode. With debug turned off all
exceptions raised by CakePHP will use either error400.ctp or error500.ctp based on their status code.

Customize the ErrorController
The App\Controller\ErrorController class is used by CakePHP’s exception rendering to render the error pageview and receives all the standard request life-cycle events. By modifying this class you can control which components
are used and which templates are rendered.
If your application uses Prefix Routing you can create custom error controllers for each routing prefix. For example, if
you had an admin prefix. You could create the following class:namespace App\Controller\Admin;
use App\Controller\AppController;class ErrorController extends AppController{/*** Initialization hook method.
** @return void*/
public function initialize(){$this->loadComponent('RequestHandler');}/*** beforeRender callback.
** @param \Cake\Event\Event $event Event.
* @return void*/
public function beforeRender(Event $event){$this->viewBuilder()->setTemplatePath('Error');}}This controller would only be used when an error is encountered in a prefixed controller, and allows you to define prefix
specific logic/templates as needed.
New in version 3.7.0: Prefixed error controllers were added.

Customize the ErrorController

711

CakePHP Book, Release 3.10

Change the ExceptionRendererIf you want to control the entire exception rendering and logging process you can use the Error.exceptionRenderer
option in config/app.php to choose a class that will render exception pages. Changing the ExceptionRenderer is usefulwhen you want to provide custom error pages for application specific exception classes.
Your custom exception renderer class should be placed in src/Error. Let’s assume our application uses App\
Exception\MissingWidgetException to indicate a missing widget. We could create an exception renderer that
renders specific error pages when this error is handled:// In src/Error/AppExceptionRenderer.php
namespace App\Error;
use Cake\Error\ExceptionRenderer;
class AppExceptionRenderer extends ExceptionRenderer{
public function missingWidget($error){$response = $this->controller->response;
return $response->withStringBody('Oops that widget is missing.');}}// In config/app.php'Error' => ['exceptionRenderer' => 'App\Error\AppExceptionRenderer',// ...
],// ...
The above would handle our MissingWidgetException, and allow us to provide custom display/handling logic for
those application exceptions.
Exception rendering methods receive the handled exception as an argument, and should return a Response object. You
can also implement methods to add additional logic when handling CakePHP errors:// In src/Error/AppExceptionRenderer.php
namespace App\Error;
use Cake\Error\ExceptionRenderer;
class AppExceptionRenderer extends ExceptionRenderer{
public function notFound($error){// Do something with NotFoundException objects.
}
}

712

Chapter 19. Error & Exception HandlingCakePHP Book, Release 3.10

Changing the ErrorController ClassThe exception renderer dictates which controller is used for exception rendering. If you want to change which controller
is used to render exceptions, override the _getController() method in your exception renderer:// in src/Error/AppExceptionRenderernamespace App\Error;
use App\Controller\SuperCustomErrorController;
use Cake\Error\ExceptionRenderer;
class AppExceptionRenderer extends ExceptionRenderer{
protected function _getController(){
return new SuperCustomErrorController();}}// in config/app.php'Error' => ['exceptionRenderer' => 'App\Error\AppExceptionRenderer',// ...
],// ...

Creating your Own Error Handler
By replacing the error handler you can customize the entire error & exception handling process. By extending Cake\
Error\BaseErrorHandler you can customize display logic more simply. As an example, we could build a classcalled AppError to handle our errors:// In config/bootstrap.php
use App\Error\AppError;$errorHandler = new AppError();$errorHandler->register();// In src/Error/AppError.php
namespace App\Error;
use Cake\Error\BaseErrorHandler;class AppError extends BaseErrorHandler{
public function _displayError($error, $debug){
echo 'There has been an error!';}public function _displayException($exception)(continues on next page)

Creating your Own Error Handler

713

CakePHP Book, Release 3.10

(continued from previous page){echo 'There has been an exception!';}}The BaseErrorHandler defines two abstract methods. _displayError() is used when errors are triggered. The_displayException() method is called when there is an uncaught exception.

Changing Fatal Error Behavior
Error handlers convert fatal errors into exceptions and re-use the exception handling logic to render an error page. If
you do not want to show the standard error page, you can override it:// In src/Error/AppError.php
namespace App\Error;
use Cake\Error\BaseErrorHandler;class AppError extends BaseErrorHandler{// Other methods.
public function handleFatalError($code, $description, $file, $line){
echo 'A fatal error has happened';}}

Creating your own Application Exceptions
You can create your own application exceptions using any of the built in SPL exceptions160 , Exception itself, orCake\Core\Exception\Exception. If your application contained the following exception:
use Cake\Core\Exception\Exception;
class MissingWidgetException extends Exception{}
You could provide nice development errors, by creating src/Template/Error/missing_widget.ctp. When in productionmode, the above error would be treated as a 500 error and use the error500 template.
If your exceptions have a code between 400 and 506 the exception code will be used as the HTTP response code.
The constructor for Cake\Core\Exception\Exception allows you to pass in additional data. This additional data isinterpolated into the the _messageTemplate. This allows you to create data rich exceptions, that provide more context
around your errors:
160 https://php.net/manual/en/spl.exceptions.php

714

Chapter 19. Error & Exception HandlingCakePHP Book, Release 3.10

use Cake\Core\Exception\Exception;
class MissingWidgetException extends Exception{// Context data is interpolated into this format string.
protected $_messageTemplate = 'Seems that %s is missing.';// You can set a default exception code as well.
protected $_defaultCode = 404;}
throw new MissingWidgetException(['widget' => 'Pointy']);When rendered, this your view template would have a $widget variable set. If you cast the exception as a string or use
its getMessage() method you will get Seems that Pointy is missing..

Logging Exceptions
Using the built-in exception handling, you can log all the exceptions that are dealt with by ErrorHandler by setting
the log option to true in your config/app.php. Enabling this will log every exception to Cake\Log\Log and theconfigured loggers.
Note: If you are using a custom exception handler this setting will have no effect. Unless you reference it inside yourimplementation.

Built in Exceptions for CakePHPHTTP Exceptions
There are several built-in exceptions inside CakePHP, outside of the internal framework exceptions, there are several
exceptions for HTTP methods
exception Cake\Http\Exception\BadRequestException
Used for doing 400 Bad Request error.
exception Cake\Http\Exception\UnauthorizedException
Used for doing a 401 Unauthorized error.
exception Cake\Http\Exception\ForbiddenException
Used for doing a 403 Forbidden error.
New in version 3.1: InvalidCsrfTokenException has been added.
exception Cake\Http\Exception\InvalidCsrfTokenException
Used for doing a 403 error caused by an invalid CSRF token.
exception Cake\Http\Exception\NotFoundException
Used for doing a 404 Not found error.
exception Cake\Http\Exception\MethodNotAllowedException
Used for doing a 405 Method Not Allowed error.

Built in Exceptions for CakePHP

715

CakePHP Book, Release 3.10

exception Cake\Http\Exception\NotAcceptableException
Used for doing a 406 Not Acceptable error.
New in version 3.1.7: NotAcceptableException has been added.
exception Cake\Http\Exception\ConflictException
Used for doing a 409 Conflict error.
New in version 3.1.7: ConflictException has been added.
exception Cake\Http\Exception\GoneException
Used for doing a 410 Gone error.
New in version 3.1.7: GoneException has been added.
For more details on HTTP 4xx error status codes see RFC 2616#section-10.4161 .
exception Cake\Http\Exception\InternalErrorException
Used for doing a 500 Internal Server Error.
exception Cake\Http\Exception\NotImplementedException
Used for doing a 501 Not Implemented Errors.
exception Cake\Http\Exception\ServiceUnavailableException
Used for doing a 503 Service Unavailable error.
New in version 3.1.7: Service Unavailable has been added.
For more details on HTTP 5xx error status codes see RFC 2616#section-10.5162 .
You can throw these exceptions from your controllers to indicate failure states, or HTTP errors. An example use of the
HTTP exceptions could be rendering 404 pages for items that have not been found:// Prior to 3.6 use Cake\Network\Exception\NotFoundException
use Cake\Http\Exception\NotFoundException;
public function view($id = null){$article = $this->Articles->findById($id)->first();if (empty($article)) {throw new NotFoundException(__('Article not found'));}$this->set('article', $article);$this->set('_serialize', ['article']);}By using exceptions for HTTP errors, you can keep your code both clean, and give RESTful responses to client applications and users.
161 https://datatracker.ietf.org/doc/html/rfc2616.html#section-10.4
162 https://datatracker.ietf.org/doc/html/rfc2616.html#section-10.5

716

Chapter 19. Error & Exception HandlingCakePHP Book, Release 3.10

Using HTTP Exceptions in your Controllers
You can throw any of the HTTP related exceptions from your controller actions to indicate failure states. For example:
use Cake\Network\Exception\NotFoundException;
public function view($id = null){$article = $this->Articles->findById($id)->first();if (empty($article)) {throw new NotFoundException(__('Article not found'));}$this->set('article', 'article');$this->set('_serialize', ['article']);}
The above would cause the configured exception handler to catch and process the NotFoundException. By default
this will create an error page, and log the exception.

Other Built In Exceptions
In addition, CakePHP uses the following exceptions:
exception Cake\View\Exception\MissingViewException
The chosen view class could not be found.
exception Cake\View\Exception\MissingTemplateException
The chosen template file could not be found.
exception Cake\View\Exception\MissingLayoutException
The chosen layout could not be found.
exception Cake\View\Exception\MissingHelperException
The chosen helper could not be found.
exception Cake\View\Exception\MissingElementException
The chosen element file could not be found.
exception Cake\View\Exception\MissingCellException
The chosen cell class could not be found.
exception Cake\View\Exception\MissingCellViewException
The chosen cell view file could not be found.
exception Cake\Controller\Exception\MissingComponentException
A configured component could not be found.
exception Cake\Controller\Exception\MissingActionException
The requested controller action could not be found.
exception Cake\Controller\Exception\PrivateActionException
Accessing private/protected/_ prefixed actions.
exception Cake\Console\Exception\ConsoleException
A console library class encounter an error.

Built in Exceptions for CakePHP

717

CakePHP Book, Release 3.10

exception Cake\Console\Exception\MissingTaskException
A configured task could not found.
exception Cake\Console\Exception\MissingShellException
The shell class could not be found.
exception Cake\Console\Exception\MissingShellMethodException
The chosen shell class has no method of that name.
exception Cake\Database\Exception\MissingConnectionException
A model’s connection is missing.
exception Cake\Database\Exception\MissingDriverException
A database driver could not be found.
exception Cake\Database\Exception\MissingExtensionException
A PHP extension is missing for the database driver.
exception Cake\ORM\Exception\MissingTableException
A model’s table could not be found.
exception Cake\ORM\Exception\MissingEntityException
A model’s entity could not be found.
exception Cake\ORM\Exception\MissingBehaviorException
A model’s behavior could not be found.
exception Cake\ORM\Exception\PersistenceFailedException
An entity couldn’t be saved/deleted while using Cake\ORM\Table::saveOrFail() or Cake\ORM\
Table::deleteOrFail().
New in version 3.4.1: PersistenceFailedException has been added.
exception Cake\Datasource\Exception\RecordNotFoundException
The requested record could not be found. This will also set HTTP response headers to 404.
exception Cake\Routing\Exception\MissingControllerException
The requested controller could not be found.
exception Cake\Routing\Exception\MissingRouteException
The requested URL cannot be reverse routed or cannot be parsed.
exception Cake\Routing\Exception\MissingDispatcherFilterException
The dispatcher filter could not be found.
exception Cake\Core\Exception\Exception
Base exception class in CakePHP. All framework layer exceptions thrown by CakePHP will extend this class.
These exception classes all extend Exception. By extending Exception, you can create your own ‘framework’ errors.
Cake\Core\Exception\Exception::responseHeader($header = null, $value = null)
See Cake\Network\Request::header()All Http and Cake exceptions extend the Exception class, which has a method to add headers to the response. For
instance when throwing a 405 MethodNotAllowedException the rfc2616 says:"The response MUST include an Allow header containing a list of valid
methods for the requested resource."

718

Chapter 19. Error & Exception HandlingCHAPTER 20

Events System

Creating maintainable applications is both a science and an art. It is well-known that a key for having good quality
code is making your objects loosely coupled and strongly cohesive at the same time. Cohesion means that all methods
and properties for a class are strongly related to the class itself and it is not trying to do the job other objects should
be doing, while loosely coupling is the measure of how little a class is “wired” to external objects, and how much thatclass is depending on them.
There are certain cases where you need to cleanly communicate with other parts of an application, without having tohard code dependencies, thus losing cohesion and increasing class coupling. Using the Observer pattern, which allows
objects to notify other objects and anonymous listeners about changes is a useful pattern to achieve this goal.
Listeners in the observer pattern can subscribe to events and choose to act upon them if they are relevant. If you haveused JavaScript, there is a good chance that you are already familiar with event driven programming.
CakePHP emulates several aspects of how events are triggered and managed in popular JavaScript libraries such as
jQuery. In the CakePHP implementation, an event object is dispatched to all listeners. The event object holds information about the event, and provides the ability to stop event propagation at any point. Listeners can register themselves
or can delegate this task to other objects and have the chance to alter the state and the event itself for the rest of thecallbacks.
The event subsystem is at the heart of Model, Behavior, Controller, View and Helper callbacks. If you’ve ever used anyof them, you are already somewhat familiar with events in CakePHP.

719

CakePHP Book, Release 3.10

Example Event Usage
Let’s suppose you are building a Cart plugin, and you’d like to focus on just handling order logic. You don’t really want
to include shipping logic, emailing the user or decrementing the item from the stock, but these are important tasks tothe people using your plugin. If you were not using events, you may try to implement this by attaching behaviors tomodels, or adding components to your controllers. Doing so represents a challenge most of the time, since you would
have to come up with the code for externally loading those behaviors or attaching hooks to your plugin controllers.
Instead, you can use events to allow you to cleanly separate the concerns of your code and allow additional concerns tohook into your plugin using events. For example, in your Cart plugin you have an Orders model that deals with creatingorders. You’d like to notify the rest of the application that an order has been created. To keep your Orders model clean
you could use events:// Cart/Model/Table/OrdersTable.php
namespace Cart\Model\Table;
use Cake\Event\Event;use Cake\ORM\Table;class OrdersTable extends Table{
public function place($order){
if ($this->save($order)) {$this->Cart->remove($order);$event = new Event('Order.afterPlace', $this, ['order' => $order]);$this->eventManager()->dispatch($event);
return true;}
return false;}}
Deprecated since version 3.5.0: Use getEventManager() instead.
The above code allows you to notify the other parts of the application that an order has been created. You can then dotasks like send email notifications, update stock, log relevant statistics and other tasks in separate objects that focus on
those concerns.

Accessing Event Managers
In CakePHP events are triggered against event managers. Event managers are available in every Table, View andController using getEventManager():$events = $this->getEventManager();
Each model has a separate event manager, while the View and Controller share one. This allows model events to beself contained, and allow components or controllers to act upon events created in the view if necessary.

720

Chapter 20. Events System

CakePHP Book, Release 3.10

Global Event Manager
In addition to instance level event managers, CakePHP provides a global event manager that allows you to listen to any
event fired in an application. This is useful when attaching listeners to a specific instance might be cumbersome ordifficult. The global manager is a singleton instance of Cake\Event\EventManager. Listeners attached to the global
dispatcher will be fired before instance listeners at the same priority. You can access the global manager using a static
method:// In any configuration file or piece of code that executes before the event
use Cake\Event\EventManager;
EventManager::instance()->on('Order.afterPlace',$aCallback);
One important thing you should consider is that there are events that will be triggered having the same name but different
subjects, so checking it in the event object is usually required in any function that gets attached globally in order toprevent some bugs. Remember that with the flexibility of using the global manager, some additional complexity is
incurred.
Cake\Event\EventManager::dispatch() method accepts the event object as an argument and notifies all listenerand callbacks passing this object along. The listeners will handle all the extra logic around the afterPlace event, you
can log the time, send emails, update user statistics possibly in separate objects and even delegating it to offline tasks
if you have the need.

Tracking Events
To keep a list of events that are fired on a particular EventManager, you can enable event tracking. To do so, simply
attach an Cake\Event\EventList to the manager:
EventManager::instance()->setEventList(new EventList());
After firing an event on the manager, you can retrieve it from the event list:$eventsFired = EventManager::instance()->getEventList();$firstEvent = $eventsFired[0];Tracking can be disabled by removing the event list or calling Cake\Event\EventList::trackEvents(false).
New in version 3.2.11: Event tracking and Cake\Event\EventList were added.

Core Events
There are a number of core events within the framework which your application can listen to. Each layer of CakePHPemits events that you can use in your application.
• ORM/Model events• Controller events• View events

Core Events721

CakePHP Book, Release 3.10

Registering Listeners
Listeners are the preferred way to register callbacks for an event. This is done by implementing the Cake\Event\
EventListenerInterface interface in any class you wish to register some callbacks. Classes implementing it needto provide the implementedEvents() method. This method must return an associative array with all event namesthat the class will handle.
To continue our previous example, let’s imagine we have a UserStatistic class responsible for calculating a user’spurchasing history, and compiling into global site statistics. This is a great place to use a listener class. Doing soallows you to concentrate the statistics logic in one place and react to events as necessary. Our UserStatistics
listener might start out like:use Cake\Event\EventListenerInterface;class UserStatistic implements EventListenerInterface{
public function implementedEvents(){
return [// Custom event names let you design your application events// as required.
'Order.afterPlace' => 'updateBuyStatistic',];}
public function updateBuyStatistic($event){// Code to update statistics}}// From your controller, attach the UserStatistic object to the// Order's event manager.
$statistics = new UserStatistic();$this->Orders->getEventManager()->on($statistics);
As you can see in the above code, the on() function will accept instances of the EventListener interface. Internally,
the event manager will use implementedEvents() to attach the correct callbacks.

Registering Anonymous Listeners
While event listener objects are generally a better way to implement listeners, you can also bind any callable as an
event listener. For example if we wanted to put any orders into the log files, we could use a simple anonymous function
to do so:use Cake\Log\Log;// From within a controller or during application bootstrap.
$this->Orders->getEventManager()->on('Order.afterPlace', function ($event) {Log::write('info','A new order was placed with id: ' . $event->getSubject()->id(continues on next page)722

Chapter 20. Events System

CakePHP Book, Release 3.10

(continued from previous page));});In addition to anonymous functions you can use any other callable type that PHP supports:$events = ['email-sending' => 'EmailSender::sendBuyEmail','inventory' => [$this->InventoryManager, 'decrement'],];
foreach ($events as $callable) {$eventManager->on('Order.afterPlace', $callable);}
When working with plugins that don’t trigger specific events, you can leverage event listeners on the default events.
Lets take an example ‘UserFeedback’ plugin which handles feedback forms from users. From your application you
would like to know when a Feedback record has been saved and ultimately act on it. You can listen to the global
Model.afterSave event. However, you can take a more direct approach and only listen to the event you really need:// You can create the following before the// save operation, ie. config/bootstrap.php
use Cake\ORM\TableRegistry;// If sending emails
use Cake\Mailer\Email;
TableRegistry::getTableLocator()->get('ThirdPartyPlugin.Feedbacks')->getEventManager()->on('Model.afterSave', function($event, $entity){// For example we can send an email to the admin// Prior to 3.4 use from()/to()/subject() methods$email = new Email('default');$email->setFrom(['info@yoursite.com' => 'Your Site'])->setTo('admin@yoursite.com')->setSubject('New Feedback - Your Site')->send('Body of message');});
You can use this same approach to bind listener objects.

Interacting with Existing Listeners
Assuming several event listeners have been registered the presence or absence of a particular event pattern can be usedas the basis of some action.:// Attach listeners to EventManager.
$this->getEventManager()->on('User.Registration', [$this, 'userRegistration']);$this->getEventManager()->on('User.Verification', [$this, 'userVerification']);$this->getEventManager()->on('User.Authorization', [$this, 'userAuthorization']);// Somewhere else in your application.
$events = $this->getEventManager()->matchingListeners('Verification');if (!empty($events)) {(continues on next page)

Registering Listeners

723

CakePHP Book, Release 3.10

(continued from previous page)// Perform logic related to presence of 'Verification' event listener.
// For example removing the listener if present.
$this->getEventManager()->off('User.Verification');} else {// Perform logic related to absence of 'Verification' event listener}

Note: The pattern passed to the matchingListeners method is case sensitive.
New in version 3.2.3: The matchingListeners method returns an array of events matching a search pattern.

Establishing Priorities
In some cases you might want to control the order that listeners are invoked. For instance, if we go back to our user
statistics example. It would be ideal if this listener was called at the end of the stack. By calling it at the end of thelistener stack, we can ensure that the event was not cancelled, and that no other listeners raised exceptions. We can also
get the final state of the objects in the case that other listeners have modified the subject or event object.
Priorities are defined as an integer when adding a listener. The higher the number, the later the method will be fired.
The default priority for all listeners is 10. If you need your method to be run earlier, using any value below this default
will work. On the other hand if you desire to run the callback after the others, using a number above 10 will do.
If two callbacks happen to have the same priority value, they will be executed with a the order they were attached. You
set priorities using the on() method for callbacks, and declaring it in the implementedEvents() function for event
listeners:// Setting priority for a callback$callback = [$this, 'doSomething'];$this->getEventManager()->on('Order.afterPlace',['priority' => 2],$callback);// Setting priority for a listenerclass UserStatistic implements EventListenerInterface{
public function implementedEvents(){
return ['Order.afterPlace' => ['callable' => 'updateBuyStatistic','priority' => 100
],
];
}
}
As you see, the main difference for EventListener objects is that you need to use an array for specifying the callable
method and the priority preference. The callable key is a special array entry that the manager will read to know what
function in the class it should be calling.

724

Chapter 20. Events System

CakePHP Book, Release 3.10

Getting Event Data as Function Parameters
When events have data provided in their constructor, the provided data is converted into arguments for the listeners.
An example from the View layer is the afterRender callback:$this->getEventManager()->dispatch(new Event('View.afterRender', $this, ['view' => $viewFileName]));The listeners of the View.afterRender callback should have the following signature:function (Event $event, $viewFileName)
Each value provided to the Event constructor will be converted into function parameters in the order they appear in thedata array. If you use an associative array, the result of array_values will determine the function argument order.
Note: Unlike in 2.x, converting event data to listener arguments is the default behavior and cannot be disabled.

Dispatching Events
Once you have obtained an instance of an event manager you can dispatch events using dispatch(). This method
takes an instance of the Cake\Event\Event class. Let’s look at dispatching an event:// An event listener has to be instantiated before dispatching an event.
// Create a new event and dispatch it.
$event = new Event('Order.afterPlace', $this, ['order' => $order]);$this->getEventManager()->dispatch($event);
Cake\Event\Event accepts 3 arguments in its constructor. The first one is the event name, you should try to keep
this name as unique as possible, while making it readable. We suggest a convention as follows: Layer.eventName
for general events happening at a layer level (e.g. Controller.startup, View.beforeRender) and Layer.
Class.eventName for events happening in specific classes on a layer, for example Model.User.afterRegisteror Controller.Courses.invalidAccess.
The second argument is the subject, meaning the object associated to the event, usually when it is the same classtriggering events about itself, using $this will be the most common case. Although a Component could trigger
controller events too. The subject class is important because listeners will get immediate access to the object properties
and have the chance to inspect or change them on the fly.
Finally, the third argument is any additional event data. This can be any data you consider useful to pass around solisteners can act upon it. While this can be an argument of any type, we recommend passing an associative array.
The dispatch() method accepts an event object as an argument and notifies all subscribed listeners.

Dispatching Events725

CakePHP Book, Release 3.10

Stopping Events
Much like DOM events, you may want to stop an event to prevent additional listeners from being notified. You can see
this in action during model callbacks (e.g. beforeSave) in which it is possible to stop the saving operation if the code
detects it cannot proceed any further.
In order to stop events you can either return false in your callbacks or call the stopPropagation() method on theevent object:public function doSomething($event){// ...
return false; // Stops the event}
public function updateBuyStatistic($event){// ...
$event->stopPropagation();}Stopping an event will prevent any additional callbacks from being called. Additionally the code triggering the event
may behave differently based on the event being stopped or not. Generally it does not make sense to stop ‘after’ events,
but stopping ‘before’ events is often used to prevent the entire operation from occurring.
To check if an event was stopped, you call the isStopped() method in the event object:public function place($order){$event = new Event('Order.beforePlace', $this, ['order' => $order]);$this->getEventManager()->dispatch($event);
if ($event->isStopped()) {return false;}
if ($this->Orders->save($order)) {// ...
}// ...
}In the previous example the order would not get saved if the event is stopped during the beforePlace process.

Getting Event Results
Every time a callback returns a non-null non-false value, it gets stored in the $result property of the event object.
This is useful when you want to allow callbacks to modify the event execution. Let’s take again our beforePlaceexample and let callbacks modify the $order data.
Event results can be altered either using the event object result property directly or returning the value in the callback
itself:// A listener callback
public function doSomething($event){(continues on next page)

726

Chapter 20. Events System

CakePHP Book, Release 3.10

(continued from previous page)// ...
$alteredData = $event->getData('order') + $moreData;
return $alteredData;}// Another listener callback
public function doSomethingElse($event){// ...
$event->setResult(['order' => $alteredData] + $this->result());}// Using the event result
public function place($order){$event = new Event('Order.beforePlace', $this, ['order' => $order]);$this->getEventManager()->dispatch($event);
if (!empty($event->getResult()['order'])) {$order = $event->getResult()['order'];}
if ($this->Orders->save($order)) {// ...
}// ...
}
It is possible to alter any event object property and have the new data passed to the next callback. In most of the cases,
providing objects as event data or result and directly altering the object is the best solution as the reference is kept thesame and modifications are shared across all callback calls.

Removing Callbacks and Listeners
If for any reason you want to remove any callback from the event manager just call the Cake\Event\
EventManager::off() method using as arguments the first two parameters you used for attaching it:// Attaching a function$this->getEventManager()->on('My.event', [$this, 'doSomething']);// Detaching the function$this->getEventManager()->off('My.event', [$this, 'doSomething']);// Attaching an anonymous function.
$myFunction = function ($event) { ... };$this->getEventManager()->on('My.event', $myFunction);// Detaching the anonymous function$this->getEventManager()->off('My.event', $myFunction);// Adding a EventListener$listener = new MyEventLister();$this->getEventManager()->on($listener);(continues on next page)

Dispatching Events727

CakePHP Book, Release 3.10

(continued from previous page)// Detaching a single event key from a listener$this->getEventManager()->off('My.event', $listener);// Detaching all callbacks implemented by a listener$this->getEventManager()->off($listener);
Events are a great way of separating concerns in your application and make classes both cohesive and decoupled fromeach other. Events can be utilized to de-couple application code and make extensible plugins.
Keep in mind that with great power comes great responsibility. Using too many events can make debugging harder andrequire additional integration testing.

Additional Reading• Behaviors• Components• Helpers• Testing Events

728

Chapter 20. Events System

CHAPTER 21

Internationalization & Localization

One of the best ways for an application to reach a larger audience is to cater to multiple languages. This can often prove
to be a daunting task, but the internationalization and localization features in CakePHP make it much easier.
First, it’s important to understand some terminology. Internationalization refers to the ability of an application to
be localized. The term localization refers to the adaptation of an application to meet specific language (or culture)requirements (i.e. a “locale”). Internationalization and localization are often abbreviated as i18n and l10n respectively;
18 and 10 are the number of characters between the first and last character.

Setting Up Translations
There are only a few steps to go from a single-language application to a multi-lingual application, the first of which is
to make use of the __() function in your code. Below is an example of some code for a single-language application:<h2>Popular Articles</h2>
To internationalize your code, all you need to do is to wrap strings in __() like so:<h2><?= __('Popular Articles') ?></h2>
Doing nothing else, these two code examples are functionally identical - they will both send the same content to thebrowser. The __() function will translate the passed string if a translation is available, or return it unmodified.

729

CakePHP Book, Release 3.10

Language Files
Translations can be made available by using language files stored in the application. The default format for CakePHP
translation files is the Gettext163 format. Files need to be placed under src/Locale/ and within this directory, there
should be a subfolder for each language the application needs to support:/src/Locale/en_US
default.po/en_GBdefault.po
validation.po/esdefault.po
The default domain is ‘default’, therefore the locale folder should at least contain the default.po file as shown above.
A domain refers to any arbitrary grouping of translation messages. When no group is used, then the default group isselected.
The core strings messages extracted from the CakePHP library can be stored separately in a file named cake.po in
src/Locale/. The CakePHP localized library164 houses translations for the client-facing translated strings in the core(the cake domain). To use these files, link or copy them into their expected location: src/Locale/<locale>/cake.po. If
your locale is incomplete or incorrect, please submit a PR in this repository to fix it.
Plugins can also contain translation files, the convention is to use the under_scored version of the plugin name as thedomain for the translation messages:
MyPlugin/src/Locale/fr
my_plugin.po/demy_plugin.po
Translation folders can be the two or three letter ISO code of the language or the full locale name such as fr_FR, es_AR,
da_DK which contains both the language and the country where it is spoken.
An example translation file could look like this:msgid "My name is {0}"msgstr "Je m'appelle {0}"msgid "I'm {0,number} years old"
msgstr "J'ai {0,number} ans"
163 https://en.wikipedia.org/wiki/Gettext
164 https://github.com/cakephp/localized

730

Chapter 21. Internationalization & Localization

CakePHP Book, Release 3.10

Extract Pot Files with I18n Shell
To create the pot files from __() and other internationalized types of messages that can be found in the application code,
you can use the i18n shell. Please read the following chapter to learn more.

Setting the Default Locale
The default locale can be set in your config/app.php file by setting App.defaultLocale:'App' => [...
'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),...
]This will control several aspects of the application, including the default translations language, the date format, number
format and currency whenever any of those is displayed using the localization libraries that CakePHP provides.

Changing the Locale at Runtime
To change the language for translated strings you can call this method:use Cake\I18n\I18n;// Prior to 3.5 use I18n::locale()I18n::setLocale('de_DE');This will also change how numbers and dates are formatted when using one of the localization tools.

Using Translation Functions
CakePHP provides several functions that will help you internationalize your application. The most frequently used one
is __(). This function is used to retrieve a single translation message or return the same string if no translation was
found:
echo __('Popular Articles');If you need to group your messages, for example, translations inside a plugin, you can use the __d() function to fetch
messages from another domain:echo __d('my_plugin', 'Trending right now');Note:
If you want to translate your plugins and they’re namespaced, you must name your domain string
Namespace/PluginName. But the related language file will become plugins/Namespace/PluginName/src/
Locale/plugin_name.po inside your plugin folder.
Sometimes translations strings can be ambiguous for people translating them. This can happen if two strings are
identical but refer to different things. For example, ‘letter’ has multiple meanings in English. To solve that problem,
you can use the __x() function:

Using Translation Functions

731

CakePHP Book, Release 3.10

echo __x('written communication', 'He read the first letter');echo __x('alphabet learning', 'He read the first letter');
The first argument is the context of the message and the second is the message to be translated.
msgctxt "written communication"
msgid "He read the first letter"
msgstr "Er las den ersten Brief"

Using Variables in Translation Messages
Translation functions allow you to interpolate variables into the messages using special markers defined in the message
itself or in the translated string:echo __("Hello, my name is {0}, I'm {1} years old", ['Sara', 12]);Markers are numeric, and correspond to the keys in the passed array. You can also pass variables as independentarguments to the function:echo __("Small step for {0}, Big leap for {1}", 'Man', 'Humanity');
All translation functions support placeholder replacements:__d('validation', 'The field {0} cannot be left empty', 'Name');__x('alphabet', 'He read the letter {0}', 'Z');
The ' (single quote) character acts as an escape code in translation messages. Any variables between single quotes will
not be replaced and is treated as literal text. For example:__("This variable '{0}' be replaced.", 'will not');
By using two adjacent quotes your variables will be replaced properly:__("This variable ''{0}'' be replaced.", 'will');
These functions take advantage of the ICU MessageFormatter165 so you can translate messages and localize dates,
numbers and currency at the same time:echo __('Hi {0}, your balance on the {1,date} is {2,number,currency}',['Charles', new FrozenTime('2014-01-13 11:12:00'), 1354.37]);// Returns
Hi Charles, your balance on the Jan 13, 2014, 11:12 AM is $ 1,354.37
Numbers in placeholders can be formatted as well with fine grain control of the output:
165 https://php.net/manual/en/messageformatter.format.php

732

Chapter 21. Internationalization & Localization

CakePHP Book, Release 3.10

echo __('You have traveled {0,number} kilometers in {1,number,integer} weeks',[5423.344, 5.1]);// Returns
You have traveled 5,423.34 kilometers in 5 weeks
echo __('There are {0,number,#,###} people on earth', 6.1 * pow(10, 8));// Returns
There are 6,100,000,000 people on earth
This is the list of formatter specifiers you can put after the word number:• integer: Removes the decimal part• currency: Puts the locale currency symbol and rounds decimals• percent: Formats the number as a percentage
Dates can also be formatted by using the word date after the placeholder number. A list of extra options follows:• short• medium• long• fullThe word time after the placeholder number is also accepted and it understands the same options as date.
Note: Named placeholders are supported in PHP 5.5+ and are formatted as {name}. When using named placeholders
pass the variables in an array using key/value pairs, for example ['name' => 'Sara', 'age' => 12].
It is recommended to use PHP 5.5 or higher when making use of internationalization features in CakePHP. The
php5-intl extension must be installed and the ICU version should be above 48.x.y (to check the ICU version
Intl::getIcuVersion()).

Plurals
One crucial part of internationalizing your application is getting your messages pluralized correctly depending on thelanguage they are shown. CakePHP provides a couple ways to correctly select plurals in your messages.
Using ICU Plural Selection
The first one is taking advantage of the ICU message format that comes by default in the translation functions. In thetranslations file you could have the following strings
msgid "{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{# resultados}}"
msgid "{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1}␣(continues on next page)

Using Translation Functions733

CakePHP Book, Release 3.10

(continued from previous page)records}}"
msgstr "{placeholder,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"˓→

And in the application use the following code to output either of the translations for such string:__('{0,plural,=0{No records found }=1{Found 1 record} other{Found # records}}', [0]);// Returns "Ningún resultado" as the argument {0} is 0__('{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}', [1]);// Returns "1 resultado" because the argument {0} is 1__('{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}
˓→', [0, 'many', 'placeholder' => 2])// Returns "many resultados" because the argument {placeholder} is 2 and// argument {1} is 'many'
A closer look to the format we just used will make it evident how messages are built:{ [count placeholder],plural, case1{message} case2{message} case3{...} ... }The [count placeholder] can be the array key number of any of the variables you pass to the translation function.
It will be used for selecting the correct plural form.
Note that to reference [count placeholder] within {message} you have to use #.
You can of course use simpler message ids if you don’t want to type the full plural selection sequence in your code
msgid "search.results"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"
Then use the new string in your code:__('search.results', [2, 2]);// Returns: "2 resultados"
The latter version has the downside that there is a need to have a translation messages file even for the default language,
but has the advantage that it makes the code more readable and leaves the complicated plural selection strings in thetranslation files.
Sometimes using direct number matching in plurals is impractical. For example, languages like Arabic require a different plural when you refer to few things and other plural form for many things. In those cases you can use the ICU
matching aliases. Instead of writing:=0{No results} =1{...} other{...}
You can do:zero{No Results} one{One result} few{...} many{...} other{...}
Make sure you read the Language Plural Rules Guide166 to get a complete overview of the aliases you can use for each
166 https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html

734

Chapter 21. Internationalization & Localization

CakePHP Book, Release 3.10

language.
Using Gettext Plural Selection
The second plural selection format accepted is using the built-in capabilities of Gettext. In this case, plurals will be
stored in the .po file by creating a separate message translation line per plural form:# One message identifier for singularmsgid "One file removed"# Another one for plural
msgid_plural "{0} files removed"# Translation in singularmsgstr[0] "Un fichero eliminado"# Translation in plural
msgstr[1] "{0} ficheros eliminados"
When using this other format, you are required to use another translation function:// Returns: "10 ficheros eliminados"$count = 10;__n('One file removed', '{0} files removed', $count, $count);// It is also possible to use it inside a domain__dn('my_plugin', 'One file removed', '{0} files removed', $count, $count);
The number inside msgstr[] is the number assigned by Gettext for the plural form of the language. Some languages
have more than two plural forms, for example Croatian:msgid "One file removed"
msgid_plural "{0} files removed"
msgstr[0] "{0} datoteka je uklonjena"
msgstr[1] "{0} datoteke su uklonjene"
msgstr[2] "{0} datoteka je uklonjeno"
Please visit the Launchpad languages page167 for a detailed explanation of the plural form numbers for each language.

Creating Your Own Translators
If you need to diverge from CakePHP conventions regarding where and how translation messages are stored, you cancreate your own translation message loader. The easiest way to create your own translator is by defining a loader for asingle domain and locale:use Aura\Intl\Package;
I18n::setTranslator('animals', function () {$package = new Package('default', // The formatting strategy (ICU)'default' // The fallback domain);$package->setMessages([(continues on next page)
167 https://translations.launchpad.net/+languages

Creating Your Own Translators

735

CakePHP Book, Release 3.10

(continued from previous page)'Dog' => 'Chien','Cat' => 'Chat','Bird' => 'Oiseau'...
]);
return $package;}, 'fr_FR');The above code can be added to your config/bootstrap.php so that translations can be found before any translation
function is used. The absolute minimum that is required for creating a translator is that the loader function should
return a Aura\Intl\Package object. Once the code is in place you can use the translation functions as usual:// Prior to 3.5 use I18n::locale()I18n::setLocale('fr_FR');__d('animals', 'Dog'); // Returns "Chien"As you see, Package objects take translation messages as an array. You can pass the setMessages() method however
you like: with inline code, including another file, calling another function, etc. CakePHP provides a few loader functions
you can reuse if you just need to change where messages are loaded. For example, you can still use .po files, but loaded
from another location:
use Cake\I18n\MessagesFileLoader as Loader;// Load messages from src/Locale/folder/sub_folder/filename.po// Prior to 3.5 use translator()
I18n::setTranslator('animals',
new Loader('filename', 'folder/sub_folder', 'po'),'fr_FR');

Creating Message Parsers
It is possible to continue using the same conventions CakePHP uses, but use a message parser other than
PoFileParser. For example, if you wanted to load translation messages using YAML, you will first need to created theparser class:namespace App\I18n\Parser;
class YamlFileParser{
public function parse($file){
return yaml_parse_file($file);}}
The file should be created in the src/I18n/Parser directory of your application. Next, create the translations file undersrc/Locale/fr_FR/animals.yaml

736

Chapter 21. Internationalization & Localization

CakePHP Book, Release 3.10

Dog: Chien
Cat: Chat
Bird: Oiseau
And finally, configure the translation loader for the domain and locale:use Cake\I18n\MessagesFileLoader as Loader;// Prior to 3.5 use translator()
I18n::setTranslator('animals',
new Loader('animals', 'fr_FR', 'yaml'),'fr_FR');

Creating Generic Translators
Configuring translators by calling I18n::setTranslator() for each domain and locale you need to support can betedious, specially if you need to support more than a few different locales. To avoid this problem, CakePHP lets you
define generic translator loaders for each domain.
Imagine that you wanted to load all translations for the default domain and for any language from an external service:
use Aura\Intl\Package;
I18n::config('default', function ($domain, $locale) {$locale = Locale::parseLocale($locale);$language = $locale['language'];$messages = file_get_contents("http://example.com/translations/$lang.json");return new Package('default', // Formatter
null, // Fallback (none for default domain)
json_decode($messages, true))});
The above example calls an example external service to load a JSON file with the translations and then just build a
Package object for any locale that is requested in the application.
If you’d like to change how packages are loaded for all packages, that don’t have specific loaders set you can replace
the fallback package loader by using the _fallback package:
I18n::config('_fallback', function ($domain, $locale) {// Custom code that yields a package here.
});
New in version 3.4.0: Replacing the _fallback loader was added in 3.4.0

Creating Your Own Translators

737

CakePHP Book, Release 3.10

Plurals and Context in Custom Translators
The arrays used for setMessages() can be crafted to instruct the translator to store messages under different domains
or to trigger Gettext-style plural selection. The following is an example of storing translations for the same key indifferent contexts:['He reads the letter {0}' => ['alphabet' => 'Él lee la letra {0}','written communication' => 'Él lee la carta {0}']]Similarly, you can express Gettext-style plurals using the messages array by having a nested array key per plural form:['I have read one book' => 'He leído un libro','I have read {0} books' => ['He leído un libro','He leído {0} libros']]Using Different Formatters
In previous examples we have seen that Packages are built using default as first argument, and it was indicated with acomment that it corresponded to the formatter to be used. Formatters are classes responsible for interpolating variables
in translation messages and selecting the correct plural form.
If you’re dealing with a legacy application, or you don’t need the power offered by the ICU message formatting,
CakePHP also provides the sprintf formatter:
return Package('sprintf', 'fallback_domain', $messages);
The messages to be translated will be passed to the sprintf() function for interpolating the variables:__('Hello, my name is %s and I am %d years old', 'José', 29);
It is possible to set the default formatter for all translators created by CakePHP before they are used for the first time.
This does not include manually created translators using the setTranslator() and config() methods:
I18n::defaultFormatter('sprintf');

Localizing Dates and Numbers
When outputting Dates and Numbers in your application, you will often need that they are formatted according to thepreferred format for the country or region that you wish your page to be displayed.
In order to change how dates and numbers are displayed you just need to change the current locale setting and use theright classes:

738

Chapter 21. Internationalization & Localization

CakePHP Book, Release 3.10

use Cake\I18n\I18n;
use Cake\I18n\Time;
use Cake\I18n\Number;// Prior to 3.5 use I18n::locale()I18n::setLocale('fr-FR');$date = new Time('2015-04-05 23:00:00');
echo $date; // Displays 05/04/2015 23:00
echo Number::format(524.23); // Displays 524,23
Make sure you read the Date & Time and Number sections to learn more about formatting options.
By default dates returned for the ORM results use the Cake\I18n\Time class, so displaying them directly in you
application will be affected by changing the current locale.

Parsing Localized Datetime Data
When accepting localized data from the request, it is nice to accept datetime information in a user’s localized format.
In a controller, or Dispatcher Filters you can configure the Date, Time, and DateTime types to parse localized formats:use Cake\Database\Type;// Enable default locale format parsing.
Type::build('datetime')->useLocaleParser();// Configure a custom datetime format parser format.
Type::build('datetime')->useLocaleParser()->setLocaleFormat('dd-M-y');// You can also use IntlDateFormatter constants.
Type::build('datetime')->useLocaleParser()->setLocaleFormat([IntlDateFormatter::SHORT, -1]);
The default parsing format is the same as the default string format.

Automatically Choosing the Locale Based on Request Data
By using the LocaleSelectorFilter in your application, CakePHP will automatically set the locale based on thecurrent user:// in src/Application.php
use Cake\I18n\Middleware\LocaleSelectorMiddleware;// Update the middleware function, adding the new middleware
public function middleware($middleware){// Add middleware and set the valid locales$middleware->add(new LocaleSelectorMiddleware(['en_US', 'fr_FR']));}(continues on next page)

Automatically Choosing the Locale Based on Request Data739

CakePHP Book, Release 3.10

(continued from previous page)// Prior to 3.3.0, use the DispatchFilter// in config/bootstrap.php
DispatcherFactory::add('LocaleSelector');// Restrict the locales to only en_US, fr_FR
DispatcherFactory::add('LocaleSelector', ['locales' => ['en_US', 'fr_FR']]);The LocaleSelectorFilter will use the Accept-Language header to automatically set the user’s preferred locale.
You can use the locale list option to restrict which locales will automatically be used.

740

Chapter 21. Internationalization & Localization

CHAPTER 22

Logging

While CakePHP core Configure Class settings can really help you see what’s happening under the hood, there arecertain times that you’ll need to log data to the disk in order to find out what’s going on. With technologies like SOAP,
AJAX, and REST APIs, debugging can be rather difficult.
Logging can also be a way to find out what’s been going on in your application over time. What search terms are being
used? What sorts of errors are my users being shown? How often is a particular query being executed?
Logging data in CakePHP is easy - the log() function is provided by the LogTrait, which is the common ancestor for
many CakePHP classes. If the context is a CakePHP class (Controller, Component, View,. . . ), you can log your data.
You can also use Log::write() directly. See Writing to Logs.

Logging Configuration
Configuring Log should be done during your application’s bootstrap phase. The config/app.php file is intended forjust this. You can define as many or as few loggers as your application needs. Loggers should be configured usingCake\Log\Log. An example would be:
use Cake\Log\Log;// Short classname
Log::config('debug', ['className' => 'File','path' => LOGS,'levels' => ['notice', 'info', 'debug'],'file' => 'debug',]);// Fully namespaced name.
Log::config('error', [(continues on next page)741

CakePHP Book, Release 3.10

(continued from previous page)'className' => 'Cake\Log\Engine\FileLog','path' => LOGS,'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'],'file' => 'error',]);
The above creates two loggers. One named debug the other named error. Each is configured to handle different levelsof messages. They also store their log messages in separate files, so it’s easy to separate debug/notice/info logs from
more serious errors. See the section on Using Levels for more information on the different levels and what they mean.
Once a configuration is created you cannot change it. Instead you should drop the configuration and re-create it usingCake\Log\Log::drop() and Cake\Log\Log::config().
It is also possible to create loggers by providing a closure. This is useful when you need full control over how the logger
object is built. The closure has to return the constructed logger instance. For example:
Log::config('special', function () {return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']);});Configuration options can also be provided as a DSN string. This is useful when working with environment variables
or PaaS providers:
Log::config('error', ['url' => 'file:///?levels[]=warning&levels[]=error&file=error',]);

Note: Loggers are required to implement the Psr\Log\LoggerInterface interface.

Creating Log Adapters
Log adapters can be part of your application, or part of plugins. If for example you had a database logger called
DatabaseLog. As part of your application it would be placed in src/Log/Engine/DatabaseLog.php. As part of aplugin it would be placed in plugins/LoggingPack/src/Log/Engine/DatabaseLog.php. To configure log adapters
you should use Cake\Log\Log::config(). For example configuring our DatabaseLog would look like:// For src/Log
Log::config('otherFile', ['className' => 'Database','model' => 'LogEntry',// ...
]);// For plugin called LoggingPack
Log::config('otherFile', ['className' => 'LoggingPack.Database','model' => 'LogEntry',// ...
]);
When configuring a log adapter the className parameter is used to locate and load the log handler. All of the otherconfiguration properties are passed to the log adapter’s constructor as an array.
742

Chapter 22. Logging

CakePHP Book, Release 3.10

namespace App\Log\Engine;
use Cake\Log\Engine\BaseLog;
class DatabaseLog extends BaseLog{
public function __construct($options = []){parent::__construct($options);// ...
}
public function log($level, $message, array $context = []){// Write to the database.
}}
CakePHP requires that all logging adapters implement Psr\Log\LoggerInterface.
The class
CakeLogEngineBaseLog is an easy way to satisfy the interface as it only requires you to implement the log()
method.
FileLog engine takes the following options:• size Used to implement basic log file rotation. If log file size reaches specified size the existing file is renamedby appending timestamp to filename and new log file is created. Can be integer bytes value or human readable
string values like ‘10MB’, ‘100KB’ etc. Defaults to 10MB.
• rotate Log files are rotated specified times before being removed. If value is 0, old versions are removed rather
then rotated. Defaults to 10.
• mask Set the file permissions for created files. If left empty the default permissions are used.
Warning: Engines have the suffix Log. You should avoid class names like SomeLogLog which include the suffix
twice at the end.

Note: You should configure loggers during bootstrapping. config/app.php is the conventional place to configure log
adapters.
In debug mode missing directories will be automatically created to avoid unnecessary errors thrown when using theFileEngine.

Error and Exception Logging
Errors and Exceptions can also be logged. By configuring the corresponding values in your app.php file. Errors will
be displayed when debug is true and logged when debug is false. To log uncaught exceptions, set the log option totrue. See Configuration for more information.

Error and Exception Logging

743

CakePHP Book, Release 3.10

Interacting with Log Streams
You can introspect the configured streams with Cake\Log\Log::configured(). The return of configured() is anarray of all the currently configured streams. You can remove streams using Cake\Log\Log::drop(). Once a log
stream has been dropped it will no longer receive messages.

Using the FileLog Adapter
As its name implies FileLog writes log messages to files. The level of log message being written determines the nameof the file the message is stored in. If a level is not supplied, LOG_ERR is used which writes to the error log. The default
log location is logs/$level.log:// Executing this inside a CakePHP class$this->log("Something didn't work!");// Results in this being appended to logs/error.log// 2007-11-02 10:22:02 Error: Something didn't work!
The configured directory must be writable by the web server user in order for logging to work correctly.
You can configure additional/alternate FileLog locations when configuring a logger. FileLog accepts a path whichallows for custom paths to be used:
Log::config('custom_path', ['className' => 'File','path' => '/path/to/custom/place/']);

Warning: If you do not configure a logging adapter, log messages will not be stored.

Logging to Syslog
In production environments it is highly recommended that you setup your system to use syslog instead of the files
logger. This will perform much better as any writes will be done in a (almost) non-blocking fashion and your operating
system logger can be configured separately to rotate files, pre-process writes or use a completely different storage foryour logs.
Using syslog is pretty much like using the default FileLog engine, you just need to specify Syslog as the engine to be
used for logging. The following configuration snippet will replace the default logger with syslog, this should be donein the bootstrap.php file:
Log::config('default', ['engine' => 'Syslog']);
The configuration array accepted for the Syslog logging engine understands the following keys:• format: An sprintf template string with two placeholders, the first one for the error level, and the second for themessage itself. This key is useful to add additional information about the server or process in the logged message.

744

Chapter 22. Logging

CakePHP Book, Release 3.10

For example: %s - Web Server 1 - %s will look like error - Web Server 1 - An error occurredin this request after replacing the placeholders.
• prefix: An string that will be prefixed to every logged message.
• flag: An integer flag to be used for opening the connection to the logger, by default LOG_ODELAY will be used.
See openlog documentation for more options• facility: The logging slot to use in syslog. By default LOG_USER is used. See syslog documentation for
more options

Writing to Logs
Writing to the log files can be done in 2 different ways. The first is to use the static Cake\Log\Log::write() method:
Log::write('debug', 'Something did not work');
The second is to use the log() shortcut function available on any class using the LogTrait. Calling log() will internallycall Log::write():// Executing this inside a class using LogTrait$this->log("Something did not work!", 'debug');
All configured log streams are written to sequentially each time Cake\Log\Log::write() is called. If you have notconfigured any logging adapters log() will return false and no log messages will be written.

Using Levels
CakePHP supports the standard POSIX set of logging levels. Each level represents an increasing level of severity:• Emergency: system is unusable• Alert: action must be taken immediately• Critical: critical conditions• Error: error conditions• Warning: warning conditions• Notice: normal but significant condition• Info: informational messages• Debug: debug-level messages
You can refer to these levels by name when configuring loggers, and when writing log messages. Alternatively, you
can use convenience methods like Cake\Log\Log::error() to clearly indicate the logging level. Using a level thatis not in the above levels will result in an exception.
Note: When levels is set to an empty value in a logger’s configuration, it will take messages of any level.

Writing to Logs

745

CakePHP Book, Release 3.10

Logging Scopes
Often times you’ll want to configure different logging behavior for different subsystems or parts of your application.
Take for example an e-commerce shop. You’ll probably want to handle logging for orders and payments differently
than you do other less critical logs.
CakePHP exposes this concept as logging scopes. When log messages are written you can include a scope name. If
there is a configured logger for that scope, the log messages will be directed to those loggers. For example:// Configure logs/shops.log to receive all levels, but only// those with `orders` and `payments` scope.
Log::config('shops', ['className' => 'File','path' => LOGS,'levels' => [],'scopes' => ['orders', 'payments'],'file' => 'shops.log',]);// Configure logs/payments.log to receive all levels, but only// those with `payments` scope.
Log::config('payments', ['className' => 'File','path' => LOGS,'levels' => [],'scopes' => ['payments'],'file' => 'payments.log',]);
Log::warning('this gets written only to shops.log', ['scope' => ['orders']]);
Log::warning('this gets written to both shops.log and payments.log', ['scope' => [˓→'payments']]);
Scopes can also be passed as a single string or a numerically indexed array. Note that using this form will limit theability to pass more data as context:
Log::warning('This is a warning', ['orders']);Log::warning('This is a warning', 'payments');

Note: When scopes is set to an empty array or null in a logger’s configuration, it will take messages of any scope.
Setting it to false will only match messages without scope.

Log API
class Cake\Log\Log
A simple class for writing to logs.
static Cake\Log\Log::config($key, $config)
Parameters• $name (string) – Name for the logger being connected, used to drop a logger later on.
746

Chapter 22. Logging

CakePHP Book, Release 3.10

• $config (array) – Array of configuration information and constructor arguments for thelogger.
Get or set the configuration for a Logger. See Logging Configuration for more information.
static Cake\Log\Log::configured
Returns
An array of configured loggers.
Get the names of the configured loggers.
static Cake\Log\Log::drop($name)Parameters• $name (string) – Name of the logger you wish to no longer receive messages.
static Cake\Log\Log::write($level, $message, $scope = [])Write a message into all the configured loggers. $level indicates the level of log message being created.
$message is the message of the log entry being written to. $scope is the scope(s) a log message is being
created in.
static Cake\Log\Log::levels
Call this method without arguments, eg: Log::levels() to obtain current level configuration.

Convenience Methods
The following convenience methods were added to log $message with the appropriate log level.
static Cake\Log\Log::emergency($message, $scope = [])static Cake\Log\Log::alert($message, $scope = [])static Cake\Log\Log::critical($message, $scope = [])static Cake\Log\Log::error($message, $scope = [])static Cake\Log\Log::warning($message, $scope = [])static Cake\Log\Log::notice($message, $scope = [])static Cake\Log\Log::info($message, $scope = [])static Cake\Log\Log::debug($message, $scope = [])Logging Trait
trait Cake\Log\LogTrait
A trait that provides shortcut methods for logging
Cake\Log\LogTrait::log($msg, $level = LOG_ERR)
Log a message to the logs. By default messages are logged as ERROR messages. If $msg isn’t a string it will be
converted with print_r before being logged.

Logging Trait

747

CakePHP Book, Release 3.10

Using Monolog
Monolog is a popular logger for PHP. Since it implements the same interfaces as the CakePHP loggers, it is easy to use
in your application as the default logger.
After installing Monolog using composer, configure the logger using the Log::setConfig() method:// config/bootstrap.php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
Log::setConfig('default', function () {$log = new Logger('app');$log->pushHandler(new StreamHandler('path/to/your/combined.log'));return $log;});// Optionally stop using the now redundant default loggers
Log::drop('debug');
Log::drop('error');Use similar methods if you want to configure a different logger for your console:// config/bootstrap_cli.php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
Log::setConfig('default', function () {$log = new Logger('cli');$log->pushHandler(new StreamHandler('path/to/your/combined-cli.log'));return $log;});// Optionally stop using the now redundant default CLI loggers
Configure::delete('Log.debug');
Configure::delete('Log.error');

Note: When using a console specific logger, make sure to conditionally configure your application logger. This will
prevent duplicate log entries.

748

Chapter 22. Logging

CHAPTER 23

Modelless Forms

class Cake\Form\Form
Most of the time you will have forms backed by ORM entities and ORM tables or other persistent stores, but there aretimes when you’ll need to validate user input and then perform an action if the data is valid. The most common exampleof this is a contact form.

Creating a Form
Generally when using the Form class you’ll want to use a subclass to define your form. This makes testing easier, andlets you re-use your form. Forms are put into src/Form and usually have Form as a class suffix. For example, a simple
contact form would look like:// in src/Form/ContactForm.php
namespace App\Form;
use Cake\Form\Form;
use Cake\Form\Schema;
use Cake\Validation\Validator;
class ContactForm extends Form{protected function _buildSchema(Schema $schema){
return $schema->addField('name', 'string')->addField('email', ['type' => 'string'])->addField('body', ['type' => 'text']);}(continues on next page)749

CakePHP Book, Release 3.10

(continued from previous page)

public function validationDefault(Validator $validator){$validator->add('name', 'length', ['rule' => ['minLength', 5],'message' => 'A name is required'])->add('email', 'format', ['rule' => 'email','message' => 'A valid email address is required',]);
return $validator;}
protected function _execute(array $data){// Send an email.
return true;}}
In the above example we see the 3 hook methods that forms provide:• _buildSchema is used to define the schema data that is used by FormHelper to create an HTML form. You candefine field type, length, and precision.
• validationDefault Gets a Cake\Validation\Validator instance that you can attach validators to.
• _execute lets you define the behavior you want to happen when execute() is called and the data is valid.
You can always define additional public methods as you need as well.

Setting Form Values
You can set default values for modelless forms using the setData() method. Values set with this method will overwrite
existing data in the form object:// In a controller
namespace App\Controller;
use App\Controller\AppController;
use App\Form\ContactForm;class ContactController extends AppController{
public function index(){$contact = new ContactForm();
if ($this->request->is('post')) {if ($contact->execute($this->request->getData())) {$this->Flash->success('We will get back to you soon.');(continues on next page)

750

Chapter 23. Modelless Forms

CakePHP Book, Release 3.10

(continued from previous page)} else {$this->Flash->error('There was a problem submitting your form.');}}if ($this->request->is('get')) {$contact->setData(['name' => 'John Doe','email' => 'john.doe@example.com']);}$this->set('contact', $contact);}}
Prior to 3.7.0 you must set default values for form by modifying the request:// Set default values on get
if ($this->request->is('get')) {// Values from the User Model e.g.
$this->request->data('name', 'John Doe');$this->request->data('email','john.doe@example.com');}
Values should only be defined if the request method is GET, otherwise you will overwrite your previous POST Data
which might have validation errors that need corrections.
New in version 3.7.0: Form::setData() was added.

Getting Form Values
You can get values from modelless forms using the getData() method:// In a controller
namespace App\Controller;
use App\Controller\AppController;
use App\Form\ContactForm;class ContactController extends AppController{
public function index(){$contact = new ContactForm();
if ($this->request->is('post')) {if ($contact->execute($this->request->getData())) {$contact->setData($this->request->getData());$name = $contact->getData('name');$this->Flash->success("Dear $name, we will get back to you soon.");} else {(continues on next page)

Getting Form Values751CakePHP Book, Release 3.10

(continued from previous page)$this->Flash->error('There was a problem submitting your form.');}}if ($this->request->is('get')) {$contact->setData(['name' => 'John Doe','email' => 'john.doe@example.com']);}$this->set('contact', $contact);}}
New in version 3.7.0: Form::getData() was added.

Processing Request Data
Once you’ve defined your form, you can use it in your controller to process and validate request data:// In a controller
namespace App\Controller;
use App\Controller\AppController;
use App\Form\ContactForm;class ContactController extends AppController{
public function index(){$contact = new ContactForm();
if ($this->request->is('post')) {if ($contact->execute($this->request->getData())) {$this->Flash->success('We will get back to you soon.');} else {$this->Flash->error('There was a problem submitting your form.');}}$this->set('contact', $contact);}}
In the above example, we use the execute() method to run our form’s _execute() method only when the data isvalid, and set flash messages accordingly. We could have also used the validate() method to only validate the request
data:$isValid = $form->validate($this->request->getData());

752

Chapter 23. Modelless Forms

CakePHP Book, Release 3.10

Getting Form Errors
Once a form has been validated you can retrieve the errors from it:$errors = $form->getErrors(); // $form->errors(); // prior to 3.7.0/* $errors contains['email' => ['A valid email address is required']]*/
New in version 3.7.0: errors() has been deprecated in favor of getErrors()

Invalidating Individual Form Fields from Controller
It is possible to invalidate individual fields from the controller without the use of the Validator class. The most common
use case for this is when the validation is done on a remote server. In such case, you must manually invalidate the fields
accordingly to the feedback from the remote server:// in src/Form/ContactForm.php
public function setErrors($errors){$this->_errors = $errors;}
Changed in version 3.5.1: You are not required to specify setErrors anymore as this has already been included in theForm class for your convenience.
According to how the validator class would have returned the errors, $errors must be in this format:["fieldName" => ["validatorName" => "The error message to display"]]
Now you will be able to invalidate form fields by setting the fieldName, then set the error messages:// In a controller$contact = new ContactForm();$contact->setErrors(["email" => ["_required" => "Your email is required"]]);
Proceed to Creating HTML with FormHelper to see the results.

Creating HTML with FormHelper
Once you’ve created a Form class, you’ll likely want to create an HTML form for it. FormHelper understands Formobjects just like ORM entities:
echo $this->Form->create($contact);echo $this->Form->control('name');echo $this->Form->control('email');echo $this->Form->control('body');echo $this->Form->button('Submit');echo $this->Form->end();

Getting Form Errors

753

CakePHP Book, Release 3.10

The above would create an HTML form for the ContactForm we defined earlier. HTML forms created with
FormHelper will use the defined schema and validator to determine field types, maxlengths, and validation errors.

754

Chapter 23. Modelless Forms

CHAPTER 24

Plugins

CakePHP allows you to set up a combination of controllers, models, and views and release them as a pre-packaged
application plugin that others can use in their CakePHP applications. If you’ve created great user management, a
simple blog, or web service adapters in one of your applications, why not package it as a CakePHP plugin? This way
you can reuse it in your other applications, and share with the community!
A CakePHP plugin is separate from the host application itself and generally provides some well-defined functionalitythat can be packaged up neatly, and reused with little effort in other applications. The application and the plugin
operate in their own respective spaces, but share the application’s configuration data (e.g. database connections, emailtransports)
In CakePHP 3.0 each plugin defines its own top-level namespace. For example: DebugKit. By convention, plugins
use their package name as their namespace. If you’d like to use a different namespace, you can configure the plugin
namespace, when plugins are loaded.

Installing a Plugin With Composer
Many plugins are available on Packagist168 and can be installed with Composer. To install DebugKit, you would do
the following:
php composer.phar require cakephp/debug_kit
This would install the latest version of DebugKit and update your composer.json, composer.lock file, update
vendor/cakephp-plugins.php, and update your autoloader.
168 https://packagist.org

755

CakePHP Book, Release 3.10

Manually Installing a Plugin
If the plugin you want to install is not available on packagist.org, you can clone or copy the plugin code into your plugins
directory. Assuming you want to install a plugin named ‘ContactManager’, you should have a folder in plugins named‘ContactManager’. In this directory are the plugin’s src, tests and any other directories.

Manually Autoloading Plugin Classes
If you install your plugins via composer or bake you shouldn’t need to configure class autoloading for your plugins.
If we were installing a plugin named MyPlugin manually you would need to modify your application’s composer.json
file to contain the following information:{"autoload": {"psr-4": {"MyPlugin\\": "plugins/MyPlugin/src/"}},"autoload-dev": {"psr-4": {"MyPlugin\\Test\\": "plugins/MyPlugin/tests/"}}}
If you are using vendor namespaces for your plugins, the namespace to path mapping should resemble the following:{"autoload": {"psr-4": {"AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/","AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/"}}}
Additionally, you will need to tell Composer to refresh its autoloading cache:php composer.phar dumpautoload
If you are unable to use Composer for any reason, you can also configure autoloading with Plugin:
Plugin::load('ContactManager', ['autoload' => true]);
Deprecated since version 3.7.0: Plugin::load() and autoload option are deprecated.
Note: IMPORTANT: autoload option is not available on addPlugin(), you should use composer dumpautoload
instead.

756

Chapter 24. Plugins

CakePHP Book, Release 3.10

Loading a Plugin
If you want to use a plugin’s routes, console commands, middleware, or event listeners you will need to load the plugin.
Plugins are loaded in your application’s bootstrap() function:// In src/Application.php. Requires at least 3.6.0
use Cake\Http\BaseApplication;
use ContactManager\Plugin as ContactManagerPlugin;class Application extends BaseApplication {public function bootstrap(){
parent::bootstrap();// Load the contact manager plugin by class name$this->addPlugin(ContactManagerPlugin::class);// Load a plugin with a vendor namespace by 'short name'$this->addPlugin('AcmeCorp/ContactManager');// Load a dev dependency that will not exist in production builds.
$this->addOptionalPlugin('AcmeCorp/ContactManager');}}If you just want to use helpers, behaviors or components from a plugin you do not need to load a plugin.
Prior to 3.6.0, you should use Plugin::load():// In config/bootstrap.php// Loads a single plugin
Plugin::load('ContactManager');// Loads a plugin with a vendor namespace at top level.
Plugin::load('AcmeCorp/ContactManager');
There is also a handy shell command to enable the plugin. Execute the following line:
bin/cake plugin load ContactManager
This would update your application’s bootstrap method, or put the $this->addPlugin('ContactManager'); snippet in the bootstrap for you.
New in version 3.6.0: addPlugin() was added.
New in version 3.9.0: The addOptionalPlugin() method was added.

Loading a Plugin757

CakePHP Book, Release 3.10

Plugin Hook Configuration
Plugins offer several hooks that allow a plugin to inject itself into the appropriate parts of your application. The hooksare:• bootstrap Used to load plugin default configuration files, define constants and other global functions.
• routes Used to load routes for a plugin. Fired after application routes are loaded.
• middleware Used to add plugin middleware to an application’s middleware queue.
• console Used to add console commands to an application’s command collection.
When loading plugins you can configure which hooks are enabled. By default plugins without a Plugin Objects have
all hooks disabled. New style plugins allow plugin authors to set defaults, which can be configured by you in yourappliation:// In Application::bootstrap()
use ContactManager\Plugin as ContactManagerPlugin;// Disable routes for the ContactManager plugin$this->addPlugin(ContactManagerPlugin::class, ['routes' => false]);You can configure hooks with array options, or the methods provided by plugin classes:// In Application::bootstrap()
use ContactManager\Plugin as ContactManagerPlugin;// Use the disable/enable to configure hooks.
$plugin = new ContactManagerPlugin();$plugin->disable('bootstrap');$plugin->enable('routes');$this->addPlugin($plugin);
Plugin objects also know their names and path information:$plugin = new ContactManagerPlugin();// Get the plugin name.
$name = $plugin->getName();// Path to the plugin root, and other paths.
$path = $plugin->getPath();$path = $plugin->getConfigPath();$path = $plugin->getClassPath();758

Chapter 24. Plugins

CakePHP Book, Release 3.10

Old Style Plugins
Prior to 3.6.0, you will need to enable the bootstrap and routes hooks. Old style plugins do not support middlewareand console hooks:// In config/bootstrap.php,// or in Application::bootstrap()// Using loadAll()
Plugin::loadAll(['Blog' => ['routes' => true],'ContactManager' => ['bootstrap' => true],'WebmasterTools' => ['bootstrap' => true, 'routes' => true],]);
Or you can load the plugins individually:// Loading just the blog and include routes
Plugin::load('Blog', ['routes' => true]);// Include bootstrap configuration/initializer file.
Plugin::load('ContactManager', ['bootstrap' => true]);With either approach you no longer need to manually include() or require() a plugin’s configuration or routes file– it happens automatically at the right time and place.
You can specify a set of defaults for loadAll() which will apply to every plugin that doesn’t have a more specificconfiguration.
The following example will load the bootstrap file from all plugins, and additionally the routes from the Blog plugin:
Plugin::loadAll([['bootstrap' => true],'Blog' => ['routes' => true]]);
Note that all files specified should actually exist in the configured plugin(s) or PHP will give warnings for each file itcannot load. You can avoid potential warnings by using the ignoreMissing option:
Plugin::loadAll([['ignoreMissing' => true, 'bootstrap' => true],'Blog' => ['routes' => true]]);
When loading plugins, the plugin name used should match the namespace. For example, if you have a plugin with top
level namespace Users you would load it using:Plugin::load('User');If you prefer to have your vendor name as top level and have a namespace like AcmeCorp/Users, then you would load
the plugin as:
Plugin::load('AcmeCorp/Users');
This will ensure that classnames are resolved properly when using plugin syntax.
Most plugins will indicate the proper procedure for configuring them and setting up the database in their documentation.
Plugin Hook Configuration759

CakePHP Book, Release 3.10

Deprecated since version 3.7.0: Plugin::load() and Plugin::loadAll() are deprecated.

Using Plugin Classes
You can reference a plugin’s controllers, models, components, behaviors, and helpers by prefixing the name of theplugin.
For example, say you wanted to use the ContactManager plugin’s ContactInfoHelper to output formatted contact information in one of your views. In your controller, your $helpers array could look like this:public $helpers = ['ContactManager.ContactInfo'];

Note: This dot separated class name is referred to as plugin syntax.
You would then be able to access the ContactInfoHelper just like any other helper in your view, such as:
echo $this->ContactInfo->address($contact);
Plugins can use the models, components, behaviors and helpers provided by the application, or other plugins if necessary:// Use an application component$this->loadComponent('AppFlash');// Use another plugin's behavior$this->addBehavior('OtherPlugin.AuditLog');Creating Your Own Plugins
As a working example, let’s begin to create the ContactManager plugin referenced above. To start out, we’ll set up our
plugin’s basic directory structure. It should look like this:/src/plugins/ContactManager/config/src/Plugin.php/Controller/Component/Model/Table/Entity/Behavior/View/Helper/Template/Layout/tests(continues on next page)

760

Chapter 24. Plugins

CakePHP Book, Release 3.10

(continued from previous page)/TestCase/Fixture/webroot
Note the name of the plugin folder, ‘ContactManager’. It is important that this folder has the same name as the plugin.
Inside the plugin folder, you’ll notice it looks a lot like a CakePHP application, and that’s basically what it is. You don’t
have to include any of the folders you are not using. Some plugins might only define a Component and a Behavior, andin that case they can completely omit the ‘Template’ directory.
A plugin can also have basically any of the other directories that your application can, such as Config, Console, webroot,etc.

Creating a Plugin Using Bake
The process of creating plugins can be greatly simplified by using bake.
In order to bake a plugin, use the following command:bin/cake bake plugin ContactManager
Bake can be used to create classes in your plugin. For example to generate a plugin controller you could run:bin/cake bake controller --plugin ContactManager Contacts
Please refer to the chapter /bake/usage if you have any problems with using the command line. Be sure to re-generate
your autoloader once you’ve created your plugin:php composer.phar dumpautoload

Plugin Objects
Plugin Objects allow a plugin author to define set-up logic, define default hooks, load routes, middleware and consolecommands. Plugin objects live in src/Plugin.php. For our ContactManager plugin, our plugin class could look like:namespace ContactManager;
use Cake\Core\BasePlugin;
use Cake\Core\PluginApplicationInterface;class Plugin extends BasePlugin{
public function middleware($middleware){// Add middleware here.
$middleware = parent::middleware($middleware);return $middleware;}
public function console($commands)(continues on next page)

Plugin Objects

761

CakePHP Book, Release 3.10

(continued from previous page){// Add console commands here.
$commands = parent::console($commands);
return $commands;}
public function bootstrap(PluginApplicationInterface $app){// Add constants, load configuration defaults.
// By default will load `config/bootstrap.php` in the plugin.
parent::bootstrap($app);// Load another plugin through this plugin$app->addPlugin(\My\Plugin::class);}
public function routes($routes){// Add routes.
// By default will load `config/routes.php` in the plugin.
parent::routes($routes);}}
New in version 3.6.0: Plugin Objects were added in 3.6.0

Plugin Routes
Plugins can provide routes files containing their routes. Each plugin can contain a config/routes.php file. This routes
file can be loaded when the plugin is added, or in the application’s routes file. To create the ContactManager pluginroutes, put the following into plugins/ContactManager/config/routes.php:<?php
use Cake\Routing\Route\DashedRoute;
use Cake\Routing\Router;
Router::plugin('ContactManager',['path' => '/contact-manager'],function ($routes) {$routes->get('/contacts', ['controller' => 'Contacts']);$routes->get('/contacts/:id', ['controller' => 'Contacts', 'action' => 'view']);$routes->put('/contacts/:id', ['controller' => 'Contacts', 'action' => 'update
˓→']);});
The above will connect default routes for your plugin. You can customize this file with more specific routes later on.
Before you can access your controllers, you’ll need to ensure the plugin is loaded and the plugin routes are loaded. In
your src/Application.php add the following:

762

Chapter 24. Plugins

CakePHP Book, Release 3.10

$this->addPlugin('ContactManager', ['routes' => true]);
You can also load plugin routes in your application’s routes list. Doing this provides you more control on how pluginroutes are loaded and allows you to wrap plugin routes in additional scopes or prefixes:
Router::scope('/', function ($routes) {// Connect other routes.
$routes->scope('/backend', function ($routes) {$routes->loadPlugin('ContactManager');});});
The above would result in URLs like /backend/contact-manager/contacts.
New in version 3.5.0: RouteBuilder::loadPlugin() was added in 3.5.0

Plugin Controllers
Controllers for our ContactManager plugin will be stored in plugins/ContactManager/src/Controller/. Since themain thing we’ll be doing is managing contacts, we’ll need a ContactsController for this plugin.
So, we place our new ContactsController in plugins/ContactManager/src/Controller and it looks like so:// plugins/ContactManager/src/Controller/ContactsController.php
namespace ContactManager\Controller;
use ContactManager\Controller\AppController;class ContactsController extends AppController{
public function index()
{
//...
}
}
Also make the AppController if you don’t have one already:// plugins/ContactManager/src/Controller/AppController.php
namespace ContactManager\Controller;
use App\Controller\AppController as BaseController;class AppController extends BaseController{}
A plugin’s AppController can hold controller logic common to all controllers in a plugin but is not required if you
don’t want to use one.
If you want to access what we’ve got going thus far, visit /contact-manager/contacts. You should get a “Missing
Model” error because we don’t have a Contact model defined yet.

Plugin Controllers

763

CakePHP Book, Release 3.10

If your application includes the default routing CakePHP provides you will be able to access your plugin controllers
using URLs like:// Access the index route of a plugin controller.
/contact-manager/contacts// Any action on a plugin controller.
/contact-manager/contacts/view/1
If your application defines routing prefixes, CakePHP’s default routing will also connect routes that use the following
pattern:/:prefix/:plugin/:controller/:prefix/:plugin/:controller/:action
See the section on Plugin Hook Configuration for information on how to load plugin specific route files.
For plugins you did not create with bake, you will also need to edit the composer.json file to add your plugin to the
autoload classes, this can be done as per the documentation Manually Autoloading Plugin Classes.

Plugin Models
Models for the plugin are stored in plugins/ContactManager/src/Model. We’ve already defined a ContactsController
for this plugin, so let’s create the table and entity for that controller:// plugins/ContactManager/src/Model/Entity/Contact.php:
namespace ContactManager\Model\Entity;
use Cake\ORM\Entity;class Contact extends Entity{}// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
use Cake\ORM\Table;class ContactsTable extends Table{}
If you need to reference a model within your plugin when building associations or defining entity classes, you need toinclude the plugin name with the class name, separated with a dot. For example:// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
use Cake\ORM\Table;class ContactsTable extends Table{(continues on next page)

764

Chapter 24. Plugins

CakePHP Book, Release 3.10

(continued from previous page)

public function initialize(array $config){$this->hasMany('ContactManager.AltName');}}If you would prefer that the array keys for the association not have the plugin prefix on them, use the alternative syntax:// plugins/ContactManager/src/Model/Table/ContactsTable.php:
namespace ContactManager\Model\Table;
use Cake\ORM\Table;class ContactsTable extends Table{
public function initialize(array $config){$this->hasMany('AltName', ['className' => 'ContactManager.AltName',]);}}
You can use TableRegistry to load your plugin tables using the familiar plugin syntax:
use Cake\ORM\TableRegistry;// Prior to 3.6 use TableRegistry::get('ContactManager.Contacts')$contacts = TableRegistry::getTableLocator()->get('ContactManager.Contacts');
Alternatively, from a controller context, you can use:
$this->loadModel('ContactsManager.Contacts');

Plugin Templates
Views behave exactly as they do in normal applications. Just place them in the right folder inside of theplugins/[PluginName]/src/Template/ folder. For our ContactManager plugin, we’ll need a view for our
ContactsController::index() action, so let’s include that as well:// plugins/ContactManager/src/Template/Contacts/index.ctp:<h1>Contacts</h1><p>Following is a sortable list of your contacts</p><!-- A sortable list of contacts would go here....-->
Plugins can provide their own layouts. To add plugin layouts, place your template files inside plugins/[PluginName]/src/Template/Layout. To use a plugin layout in your controller you can do the following:
public $layout = 'ContactManager.admin';If the plugin prefix is omitted, the layout/view file will be located normally.

Plugin Templates

765CakePHP Book, Release 3.10

Note: For information on how to use elements from a plugin, look up Elements

Overriding Plugin Templates from Inside Your Application
You can override any plugin views from inside your app using special paths. If you have a plugin called ‘ContactManager’ you can override the template files of the plugin with application specific view logic by creating files using
the following template src/Template/Plugin/[Plugin]/[Controller]/[view].ctp. For the Contacts controller you could
make the following file:src/Template/Plugin/ContactManager/Contacts/index.ctp
Creating this file would allow you to override plugins/ContactManager/src/Template/Contacts/index.ctp.
If your plugin is in a composer dependency (i.e. ‘Company/ContactManager’), the path to the ‘index’ view of theContacts controller will be:
src/Template/Plugin/Company/ContactManager/Contacts/index.ctp
Creating this file would allow you to override vendor/Company/ContactManager/src/Template/Contacts/index.ctp.
If the plugin implements a routing prefix, you must include the routing prefix in your application template overrides.
For example, if the ‘ContactManager’ plugin implemented an ‘admin’ prefix the overridng path would be:
src/Template/Plugin/Company/ContactManager/Admin/Contact/index.ctp

Plugin Assets
A plugin’s web assets (but not PHP files) can be served through the plugin’s webroot directory, just like the main
application’s assets:/plugins/ContactManager/webroot/
css/
js/
img/
flash/
pdf/
You may put any type of file in any directory, just like a regular webroot.
Warning: Handling static assets (such as images, JavaScript and CSS files) through the Dispatcher is very inefficient. See Improve Your Application’s Performance for more information.

766

Chapter 24. Plugins

CakePHP Book, Release 3.10

Linking to Assets in Plugins
You can use the plugin syntax when linking to plugin assets using the HtmlHelper’s script, image, or css methods:// Generates a URL of /contact_manager/css/styles.css
echo $this->Html->css('ContactManager.styles');// Generates a URL of /contact_manager/js/widget.js
echo $this->Html->script('ContactManager.widget');// Generates a URL of /contact_manager/img/logo.jpg
echo $this->Html->image('ContactManager.logo');Plugin assets are served using the AssetMiddleware middleware by default. This is only recommended for development. In production you should symlink plugin assets to improve performance.
If you are not using the helpers, you can prepend /plugin_name/ to the beginning of the URL for an asset within that plugin to serve it. Linking to ‘/contact_manager/js/some_file.js’ would serve the asset plugins/ContactManager/webroot/js/some_file.js.

Components, Helpers and Behaviors
A plugin can have Components, Helpers and Behaviors just like a CakePHP application. You can even create plugins
that consist only of Components, Helpers or Behaviors which can be a great way to build reusable components that canbe dropped into any project.
Building these components is exactly the same as building it within a regular application, with no special naming
convention.
Referring to your component from inside or outside of your plugin requires only that you prefix the plugin name before
the name of the component. For example:// Component defined in 'ContactManager' plugin
namespace ContactManager\Controller\Component;
use Cake\Controller\Component;
class ExampleComponent extends Component{}// Within your controllers
public function initialize(){
parent::initialize();$this->loadComponent('ContactManager.Example');}The same technique applies to Helpers and Behaviors.

Components, Helpers and Behaviors

767

CakePHP Book, Release 3.10

Commands
Plugins can register their commands inside the console() hook. By default all shells and commands in the plugin are
auto-discovered and added to the application’s command list. Plugin commands are prefixed with the plugin name. For
example, the UserCommand provided by the ContactManager plugin would be registered as both contact_manager.
user and user. The un-prefixed name will only be taken by a plugin if it is not used by the application, or anotherplugin.
You can customize the command names by defining each command in your plugin:public function console($commands){// Create nested commands$commands->add('bake model', ModelCommand::class);$commands->add('bake controller', ControllerCommand::class);
return $commands;}

Testing your Plugin
If you are testing controllers or generating URLs, make sure your plugin connects routes tests/bootstrap.php.
For more information see testing plugins page.

Publishing your Plugin
CakePHP plugins should be published to the packagist169 . This way other people can use it as composer dependency.
You can also propose your plugin to the awesome-cakephp list170 .
Choose a semantically meaningful name for the package name. This should ideally be prefixed with the dependency,
in this case “cakephp” as the framework. The vendor name will usually be your GitHub username. Do not use the
CakePHP namespace (cakephp) as this is reserved to CakePHP owned plugins. The convention is to use lowercase
letters and dashes as separator.
So if you created a plugin “Logging” with your GitHub account “FooBar”, a good name would be foo-bar/cakephplogging. And the CakePHP owned “Localized” plugin can be found under cakephp/localized respectively.

Plugin Map File
When installing plugins via Composer, you may notice that vendor/cakephp-plugins.php is created. This configuration file contains a map of plugin names and their paths on the filesystem. It makes it possible for plugins to be installed
into the standard vendor directory which is outside of the normal search paths. The Plugin class will use this file tolocate plugins when they are loaded with load() or loadAll(). You generally won’t need to edit this file by hand, as
Composer and the plugin-installer package will manage it for you.
169 https://packagist.org
170 https://github.com/FriendsOfCake/awesome-cakephp

768

Chapter 24. Plugins

CakePHP Book, Release 3.10

Manage Your Plugins using Mixer
Another way to discover and manage plugins into your CakePHP application is Mixer171 . It is a CakePHP plugin whichhelps you to install plugins from Packagist. It also helps you to manage your existing plugins.
Note: IMPORTANT: Do not use this in production environment.

171 https://github.com/CakeDC/mixer

Manage Your Plugins using Mixer

769

CakePHP Book, Release 3.10

770

Chapter 24. Plugins

CHAPTER 25

REST

Many newer application programmers are realizing the need to open their core functionality to a greater audience.
Providing easy, unfettered access to your core API can help get your platform accepted, and allows for mashups andeasy integration with other systems.
While other solutions exist, REST is a great way to provide easy access to the logic you’ve created in your application.
It’s simple, usually XML-based (we’re talking simple XML, nothing like a SOAP envelope), and depends on HTTP
headers for direction. Exposing an API via REST in CakePHP is simple.

The Simple Setup
The fastest way to get up and running with REST is to add a few lines to setup resource routes in your config/routes.php
file.
Once the router has been set up to map REST requests to certain controller actions, we can move on to creating the
logic in our controller actions. A basic controller might look something like this:// src/Controller/RecipesController.php
class RecipesController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
public function index(){$recipes = $this->Recipes->find('all');$this->set([(continues on next page)771

CakePHP Book, Release 3.10

(continued from previous page)'recipes' => $recipes,'_serialize' => ['recipes']]);}
public function view($id){$recipe = $this->Recipes->get($id);$this->set(['recipe' => $recipe,'_serialize' => ['recipe']]);}
public function add(){$this->request->allowMethod(['post', 'put']);$recipe = $this->Recipes->newEntity($this->request->getData());
if ($this->Recipes->save($recipe)) {$message = 'Saved';} else {$message = 'Error';}$this->set(['message' => $message,'recipe' => $recipe,'_serialize' => ['message', 'recipe']]);}
public function edit($id){$this->request->allowMethod(['patch', 'post', 'put']);$recipe = $this->Recipes->get($id);$recipe = $this->Recipes->patchEntity($recipe, $this->request->getData());
if ($this->Recipes->save($recipe)) {$message = 'Saved';} else {$message = 'Error';}$this->set(['message' => $message,'_serialize' => ['message']]);}
public function delete($id){$this->request->allowMethod(['delete']);$recipe = $this->Recipes->get($id);$message = 'Deleted';if (!$this->Recipes->delete($recipe)) {(continues on next page)772

Chapter 25. REST

CakePHP Book, Release 3.10

(continued from previous page)$message = 'Error';}$this->set(['message' => $message,'_serialize' => ['message']]);}}
RESTful controllers often use parsed extensions to serve up different views based on different kinds of requests. Since
we’re dealing with REST requests, we’ll be making XML views. You can make JSON views using CakePHP’s built-in
JSON and XML views. By using the built in XmlView we can define a _serialize view variable. This special view
variable is used to define which view variables XmlView should serialize into XML.
If we wanted to modify the data before it is converted into XML we should not define the _serialize view variable,
and instead use template files. We place the REST views for our RecipesController inside src/Template/Recipes/xml.
We can also use the Xml for quick-and-easy XML output in those views. Here’s what our index view might look like:// src/Template/Recipes/xml/index.ctp// Do some formatting and manipulation on// the $recipes array.
$xml = Xml::fromArray(['response' => $recipes]);echo $xml->asXML();
When serving up a specific content type using Cake\Routing\Router::extensions(), CakePHP automatically
looks for a view helper that matches the type. Since we’re using XML as the content type, there is no built-in helper,
however if you were to create one it would automatically be loaded for our use in those views.
The rendered XML will end up looking something like this:<recipes><recipe><id>234</id><created>2008-06-13</created><modified>2008-06-14</modified><author><id>23423</id><first_name>Billy</first_name><last_name>Bob</last_name></author><comment><id>245</id><body>Yummy yummmy</body></comment></recipe>...
</recipes>
Creating the logic for the edit action is a bit trickier, but not by much. Since you’re providing an API that outputs XML, it’s a natural choice to receive XML as input. Not to worry, the Cake\Controller\Component\
RequestHandler and Cake\Routing\Router classes make things much easier. If a POST or PUT request has
an XML content-type, then the input is run through CakePHP’s Xml class, and the array representation of the data
is assigned to $this->request->getData(). Because of this feature, handling XML and POST data in parallel is seamless: no changes are required to the controller or model code. Everything you need should end up in

The Simple Setup773

CakePHP Book, Release 3.10

$this->request->getData().

Accepting Input in Other Formats
Typically REST applications not only output content in alternate data formats, but also accept data in different formats. In CakePHP, the RequestHandlerComponent helps facilitate this. By default, it will decode any incoming JSON/XML input data for POST/PUT requests and supply the array version of that data in$this->request->getData(). You can also wire in additional deserializers for alternate formats if you need them,using RequestHandler::addInputType().

RESTful Routing
CakePHP’s Router makes connecting RESTful resource routes easy. See the section on RESTful Routing for more
information.

774

Chapter 25. RESTCHAPTER 26

Security

CakePHP provides you some tools to secure your application. The following sections cover those tools:

Security Utility
class Cake\Utility\Security
The security library172 handles basic security measures such as providing methods for hashing and encrypting data.

Encrypting and Decrypting Datastatic Cake\Utility\Security::encrypt($text, $key, $hmacSalt = null)static Cake\Utility\Security::decrypt($cipher, $key, $hmacSalt = null)
Encrypt $text using AES-256. The $key should be a value with a lots of variance in the data much like a good
password. The returned result will be the encrypted value with an HMAC checksum.
This method will use either openssl173 or mcrypt174 based on what is available on your system. Data encrypted in one
implementation is portable to the other.
Warning: The mcrypt175 extension has been deprecated in PHP7.1
This method should never be used to store passwords. Instead you should use the one way hashing methods provided
by hash(). An example use would be:
172 https://api.cakephp.org/3.x/class-Cake.Utility.Security.html
173 https://php.net/openssl
174 https://php.net/mcrypt
175 https://php.net/mcrypt775CakePHP Book, Release 3.10// Assuming key is stored somewhere it can be re-used for// decryption later.
$key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';$result = Security::encrypt($value, $key);
If you do not supply an HMAC salt, the Security.salt value will be used. Encrypted values can be decrypted usingCake\Utility\Security::decrypt().
Decrypt a previously encrypted value. The $key and $hmacSalt parameters must match the values used to encrypt or
decryption will fail. An example use would be:// Assuming the key is stored somewhere it can be re-used for// Decryption later.
$key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';$cipher = $user->secrets;$result = Security::decrypt($cipher, $key);
If the value cannot be decrypted due to changes in the key or HMAC salt false will be returned.
Choosing a Specific Crypto Implementation
If you are upgrading an application from CakePHP 2.x, data encrypted in 2.x is not compatible with openssl. This isbecause the encrypted data is not fully AES compliant. If you don’t want to go through the trouble of re-encrypting
your data, you can force CakePHP to use mcrypt using the engine() method:// In config/bootstrap.php
use Cake\Utility\Crypto\Mcrypt;
Security::engine(new Mcrypt());
The above will allow you to seamlessly read data from older versions of CakePHP, and encrypt new data to be compatible
with OpenSSL.

Hashing Datastatic Cake\Utility\Security::hash($string, $type = NULL, $salt = false)
Create a hash from string using given method. Fallback on next available method. If $salt is set to true, the application’s salt value will be used:// Using the application's salt value$sha1 = Security::hash('CakePHP Framework', 'sha1', true);// Using a custom salt value$sha1 = Security::hash('CakePHP Framework', 'sha1', 'my-salt');// Using the default hash algorithm$hash = Security::hash('CakePHP Framework');
The hash() method supports the following hashing strategies:
• md5

776

Chapter 26. Security

CakePHP Book, Release 3.10

• sha1• sha256
And any other hash algorithmn that PHP’s hash() function supports.
Warning: You should not be using hash() for passwords in new applications. Instead you should use theDefaultPasswordHasher class which uses bcrypt by default.

Getting Secure Random Datastatic Cake\Utility\Security::randomBytes($length)
Get $length number of bytes from a secure random source. This function draws data from one of the following
sources:• PHP’s random_bytes function.
• openssl_random_pseudo_bytes from the SSL extension.
If neither source is available a warning will be emitted and an unsafe value will be used for backwards compatibility
reasons.
New in version 3.2.3: The randomBytes method was added.
static Cake\Utility\Security::randomString($length)
Get a random string $length long from a secure random source. This method draws from the same random source as
randomBytes() and will encode the data as a hexadecimal string.
New in version 3.6.0: The randomString method was added.

Security Utility

777

CakePHP Book, Release 3.10

778

Chapter 26. Security

CHAPTER 27

Sessions

CakePHP provides a wrapper and suite of utility features on top of PHP’s native session extension. Sessions allow
you to identify unique users across requests and store persistent data for specific users. Unlike Cookies, session data
is not available on the client side. Usage of $_SESSION is generally avoided in CakePHP, and instead usage of theSession classes is preferred.

Session Configuration
Session configuration is generally defined in /config/app.php. The available options are:• Session.timeout - The number of minutes before CakePHP’s session handler expires the session.
• Session.defaults - Allows you to use the built-in default session configurations as a base for your session
configuration. See below for the built-in defaults.
• Session.handler - Allows you to define a custom session handler. The core database and cache session handlers use this. See below for additional information on Session handlers.
• Session.ini - Allows you to set additional session ini settings for your config. This combined with Session.
handler replace the custom session handling features of previous versions• Session.cookie - The name of the cookie to use. Defaults to ‘CAKEPHP’.
• Session.cookiePath - The url path for which session cookie is set. Maps to the session.cookie_path
php.ini config. Defaults to base path of app.
CakePHP’s defaults session.cookie_secure to true, when your application is on an SSL protocol. If your application serves from both SSL and non-SSL protocols, then you might have problems with sessions being lost. If you
need access to the session on both SSL and non-SSL domains you will want to disable this:Configure::write('Session', ['defaults' => 'php',(continues on next page)779

CakePHP Book, Release 3.10

(continued from previous page)'ini' => ['session.cookie_secure' => false]]);
The session cookie path defaults to app’s base path. To change this you can use the session.cookie_path ini value.
For example if you want your session to persist across all subdomains you can do:
Configure::write('Session', ['defaults' => 'php','ini' => ['session.cookie_path' => '/',
'session.cookie_domain' => '.yourdomain.com']]);
By default PHP sets the session cookie to expire as soon as the browser is closed, regardless of the configured Session.
timeout value. The cookie timeout is controlled by the session.cookie_lifetime ini value and can be configured
using:
Configure::write('Session', ['defaults' => 'php','ini' => [// Invalidate the cookie after 30 minutes without visiting// any page on the site.
'session.cookie_lifetime' => 1800]]);
The difference between Session.timeout and the session.cookie_lifetime value is that the latter relies on theclient telling the truth about the cookie. If you require stricter timeout checking, without relying on what the client
reports, you should use Session.timeout.
Please note that Session.timeout corresponds to the total time of inactivity for a user (i.e. the time without visiting
any page where the session is used), and does not limit the total amount of minutes a user can stay on the site.

Built-in Session Handlers & Configuration
CakePHP comes with several built-in session configurations. You can either use these as the basis for your session
configuration, or you can create a fully custom solution. To use defaults, simply set the ‘defaults’ key to the name ofthe default you want to use. You can then override any sub setting by declaring it in your Session config:
Configure::write('Session', ['defaults' => 'php']);
The above will use the built-in ‘php’ session configuration. You could augment part or all of it by doing the following:
Configure::write('Session', ['defaults' => 'php','cookie' => 'my_app',(continues on next page)

780

Chapter 27. Sessions

CakePHP Book, Release 3.10

(continued from previous page)'timeout' => 4320 // 3 days]);
The above overrides the timeout and cookie name for the ‘php’ session configuration. The built-in configurations are:• php - Saves sessions with the standard settings in your php.ini file.
• cake - Saves sessions as files inside tmp/sessions. This is a good option when on hosts that don’t allow you
to write outside your own home dir.
• database - Use the built-in database sessions. See below for more information.
• cache - Use the built-in cache sessions. See below for more information.

Session Handlers
Session handlers can also be defined in the session config array. By defining the ‘handler.engine’ config key,
you can name the class name, or provide a handler instance. The class/object must implement the native PHP
SessionHandlerInterface. Implementing this interface will allow Session to automatically map the methods
for the handler. Both the core Cache and Database session handlers use this method for saving sessions. Additionalsettings for the handler should be placed inside the handler array. You can then read those values out from inside yourhandler:'Session' => ['handler' => ['engine' => 'DatabaseSession','model' => 'CustomSessions']]
The above shows how you could setup the Database session handler with an application model. When using classnames as your handler.engine, CakePHP will expect to find your class in the Http\Session namespace. For example,
if you had an AppSessionHandler class, the file should be src/Http/Session/AppSessionHandler.php, and the classname should be App\Http\Session\AppSessionHandler. You can also use session handlers from inside plugins.
By setting the engine to MyPlugin.PluginSessionHandler.
Note: Prior to 3.6.0 session adapter files should be placed in src/Network/Session/AppHandler.php.

Database Sessions
If you need to use a database to store your session data, configure as follows:'Session' => ['defaults' => 'database']This configuration requires a database table, having this schema:
CREATE TABLE `sessions` (`id` char(40) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,`created` datetime DEFAULT CURRENT_TIMESTAMP, -- Optional(continues on next page)

Built-in Session Handlers & Configuration

781

CakePHP Book, Release 3.10

(continued from previous page)`modified` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, -- Optional`data` blob DEFAULT NULL, -- for PostgreSQL use bytea instead of blob
`expires` int(10) unsigned DEFAULT NULL,PRIMARY KEY (`id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8;
You can find a copy of the schema for the sessions table in the application skeleton176 in config/schema/sessions.
sql.
You can also use your own Table class to handle the saving of the sessions:'Session' => ['defaults' => 'database','handler' => ['engine' => 'DatabaseSession','model' => 'CustomSessions']]
The above will tell Session to use the built-in ‘database’ defaults, and specify that a Table called CustomSessions
will be the delegate for saving session information to the database.

Cache Sessions
The Cache class can be used to store sessions as well. This allows you to store sessions in a cache like APCu, orMemcached. There are some caveats to using cache sessions, in that if you exhaust the cache space, sessions will start
to expire as records are evicted.
To use Cache based sessions you can configure you Session config like:
Configure::write('Session', ['defaults' => 'cache','handler' => ['config' => 'session']]);
This will configure Session to use the CacheSession class as the delegate for saving the sessions. You can use the‘config’ key which cache configuration to use. The default cache configuration is 'default'.

Setting ini directives
The built-in defaults attempt to provide a common base for session configuration. You may need to tweak specificini flags as well. CakePHP exposes the ability to customize the ini settings for both default configurations, as well as
custom ones. The ini key in the session settings, allows you to specify individual configuration values. For example
you can use it to control settings like session.gc_divisor:
Configure::write('Session', ['defaults' => 'php',(continues on next page)
176 https://github.com/cakephp/app

782

Chapter 27. Sessions

CakePHP Book, Release 3.10

(continued from previous page)'ini' => ['session.cookie_name' => 'MyCookie','session.cookie_lifetime' => 1800, // Valid for 30 minutes'session.gc_divisor' => 1000,'session.cookie_httponly' => true]]);

Creating a Custom Session Handler
Creating a custom session handler is straightforward in CakePHP. In this example we’ll create a session handler that
stores sessions both in the Cache (APC) and the database. This gives us the best of fast IO of APC, without having toworry about sessions evaporating when the cache fills up.
First we’ll need to create our custom class and put it in src/Http/Session/ComboSession.php. The class should looksomething like:namespace App\Http\Session;
use Cake\Cache\Cache;
use Cake\Core\Configure;use Cake\Http\Session\DatabaseSession;class ComboSession extends DatabaseSession{
public $cacheKey;
public function __construct(){$this->cacheKey = Configure::read('Session.handler.cache');parent::__construct();}// Read data from the session.
public function read($id){$result = Cache::read($id, $this->cacheKey);
if ($result) {return $result;}
return parent::read($id);}// Write data into the session.
public function write($id, $data){
Cache::write($id, $data, $this->cacheKey);
return parent::write($id, $data);}// Destroy a session.
(continues on next page)

Creating a Custom Session Handler

783

CakePHP Book, Release 3.10

(continued from previous page)

public function destroy($id){
Cache::delete($id, $this->cacheKey);
return parent::destroy($id);}// Removes expired sessions.
public function gc($expires = null){
return Cache::gc($this->cacheKey) && parent::gc($expires);}}Our class extends the built-in DatabaseSession so we don’t have to duplicate all of its logic and behavior. We wrap
each operation with a Cake\Cache\Cache operation. This lets us fetch sessions from the fast cache, and not have toworry about what happens when we fill the cache. Using this session handler is also easy. In your app.php make thesession block look like the following:'Session' => ['defaults' => 'database','handler' => ['engine' => 'ComboSession','model' => 'Session','cache' => 'apc']],// Make sure to add a apc cache config'Cache' => ['apc' => ['engine' => 'Apc']]
Now our application will start using our custom session handler for reading and writing session data.
class Session

Accessing the Session Object
You can access the session data any place you have access to a request object. This means the session is accessible
from:• Controllers• Views• Helpers• Cells• Components
In addition to the basic session object, you can also use the Cake\View\Helper\SessionHelper to interact with thesession in your views. A basic example of session usage would be:

784

Chapter 27. Sessions

CakePHP Book, Release 3.10// Prior to 3.6.0 use session() instead.
$name = $this->getRequest()->getSession()->read('User.name');// If you are accessing the session multiple times,// you will probably want a local variable.
$session = $this->getRequest()->getSession();$name = $session->read('User.name');Reading & Writing Session Data
Session::read($key)
You can read values from the session using Hash::extract() compatible syntax:$session->read('Config.language');
Session::write($key, $value)$key should be the dot separated path you wish to write $value to:$session->write('Config.language', 'en');
You may also specify one or multiple hashes like so:$session->write(['Config.theme' => 'blue','Config.language' => 'en',]);
Session::delete($key)
When you need to delete data from the session, you can use delete():$session->delete('Some.value');static Session::consume($key)
When you need to read and delete data from the session, you can use consume():$session->consume('Some.value');
Session::check($key)
If you want to see if data exists in the session, you can use check():if ($session->check('Config.language')) {// Config.language exists and is not null.
}Reading & Writing Session Data

785

CakePHP Book, Release 3.10

Destroying the Session
Session::destroy()
Destroying the session is useful when users log out. To destroy a session, use the destroy() method:$session->destroy();
Destroying a session will remove all serverside data in the session, but will not remove the session cookie.

Rotating Session Identifiers
Session::renew()
While AuthComponent automatically renews the session id when users login and logout, you may need to rotate thesession id’s manually. To do this use the renew() method:$session->renew();

Flash Messages
Flash messages are small messages displayed to end users once. They are often used to present error messages, orconfirm that actions took place successfully.
To set and display flash messages you should use Flash and Flash786

Chapter 27. Sessions

CHAPTER 28

Testing

CakePHP comes with comprehensive testing support built-in. CakePHP comes with integration for PHPUnit177 . In
addition to the features offered by PHPUnit, CakePHP offers some additional features to make testing easier. Thissection will cover installing PHPUnit, and getting started with Unit Testing, and how you can use the extensions that
CakePHP offers.

Installing PHPUnit
CakePHP uses PHPUnit as its underlying test framework. PHPUnit is the de-facto standard for unit testing in PHP.
It offers a deep and powerful set of features for making sure your code does what you think it does. PHPUnit can beinstalled through using either a PHAR package178 or Composer179 .

Install PHPUnit with Composer
To install PHPUnit with Composer:$ php composer.phar require --dev phpunit/phpunit:"^5.7|^6.0"// Before CakePHP 3.4.1$ php composer.phar require --dev phpunit/phpunit:"<6.0"This will add the dependency to the require-dev section of your composer.json, and then install PHPUnit alongwith any dependencies.
You can now run PHPUnit using:
177 https://phpunit.de
178 https://phpunit.de/#download
179 https://getcomposer.org

787

CakePHP Book, Release 3.10

$ vendor/bin/phpunit

Using the PHAR File
After you have downloaded the phpunit.phar file, you can use it to run your tests:
php phpunit.phar

Tip: As a convenience you can make phpunit.phar available globally on Unix or Linux with the following:
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version
Please refer to the PHPUnit documentation for instructions regarding Globally installing the PHPUnit PHAR on Windows180 .

Test Database Setup
Remember to have debug enabled in your config/app.php file before running any tests. Before running any tests you
should be sure to add a test datasource configuration to config/app.php. This configuration is used by CakePHP for
fixture tables and data:'Datasources' => ['test' => ['datasource' => 'Cake\Database\Driver\Mysql','persistent' => false,'host' => 'dbhost','username' => 'dblogin','password' => 'dbpassword','database' => 'test_database'],],Note: It’s a good idea to make the test database and your actual database different databases. This will prevent
embarrassing mistakes later.
180 https://phpunit.de/manual/current/en/installation.html#installation.phar.windows

788

Chapter 28. TestingCakePHP Book, Release 3.10

Checking the Test Setup
After installing PHPUnit and setting up your test datasource configuration you can make sure you’re ready to write
and run your own tests by running your application’s tests:# For phpunit.phar$ php phpunit.phar# For Composer installed phpunit$ vendor/bin/phpunit
The above should run any tests you have, or let you know that no tests were run. To run a specific test you can supply
the path to the test as a parameter to PHPUnit. For example, if you had a test case for ArticlesTable class you could run
it with:$ vendor/bin/phpunit tests/TestCase/Model/Table/ArticlesTableTest
You should see a green bar with some additional information about the tests run, and number passed.
Note: If you are on a Windows system you probably won’t see any colours.

Test Case Conventions
Like most things in CakePHP, test cases have some conventions. Concerning tests:
1. PHP files containing tests should be in your tests/TestCase/[Type] directories.
2. The filenames of these files should end in Test.php instead of just .php.
3. The classes containing tests should extend Cake\TestSuite\TestCase,
IntegrationTestCase or \PHPUnit\Framework\TestCase.

Cake\TestSuite\

4. Like other classnames, the test case classnames should match the filename. RouterTest.php should containclass RouterTest extends TestCase.
5. The name of any method containing a test (i.e. containing an assertion) should begin with test, as in
testPublished(). You can also use the @test annotation to mark methods as test methods.
New in version 3.4.1: Support for PHPUnit 6 was addded. If you’re using a PHPUnit version lower than 5.7.0, yourtests classes should either extends CakePHP’s classes or PHPUnit_Framework_TestCase.

Creating Your First Test CaseIn the following example, we’ll create a test case for a very simple helper method. The helper we’re going to test will
be formatting progress bar HTML. Our helper looks like:namespace App\View\Helper;
use Cake\View\Helper;class ProgressHelper extends Helper(continues on next page)

Checking the Test Setup

789

CakePHP Book, Release 3.10

(continued from previous page){
public function bar($value){$width = round($value / 100, 2) * 100;
return sprintf('<div class="progress-container"><div class="progress-bar" style="width: %s%%"></div></div>', $width);}}
This is a very simple example, but it will be useful to show how you can create a simple test case. After creating andsaving our helper, we’ll create the test case file in tests/TestCase/View/Helper/ProgressHelperTest.php. In that file
we’ll start with the following:namespace App\Test\TestCase\View\Helper;
use App\View\Helper\ProgressHelper;
use Cake\TestSuite\TestCase;
use Cake\View\View;
class ProgressHelperTest extends TestCase{
public function setUp(){}
public function testBar(){}}We’ll flesh out this skeleton in a minute. We’ve added two methods to start with. First is setUp(). This method iscalled before every test method in a test case class. Setup methods should initialize the objects needed for the test, anddo any configuration needed. In our setup method we’ll add the following:
public function setUp(){
parent::setUp();$View = new View();$this->Progress = new ProgressHelper($View);}
Calling the parent method is important in test cases, as TestCase::setUp() does a number things like backing up
the values in Configure and, storing the paths in App.
Next, we’ll fill out the test method. We’ll use some assertions to ensure that our code creates the output we expect:public function testBar(){$result = $this->Progress->bar(90);$this->assertContains('width: 90%', $result);$this->assertContains('progress-bar', $result);(continues on next page)

790

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)$result = $this->Progress->bar(33.3333333);$this->assertContains('width: 33%', $result);}
The above test is a simple one but shows the potential benefit of using test cases. We use assertContains() to ensurethat our helper is returning a string that contains the content we expect. If the result did not contain the expected content
the test would fail, and we would know that our code is incorrect.
By using test cases you can describe the relationship between a set of known inputs and their expected output. This helps
you be more confident of the code you’re writing as you can ensure that the code you wrote fulfills the expectations andassertions your tests make. Additionally because tests are code, they are easy to re-run whenever you make a change.
This helps prevent the creation of new bugs.
Note: EventManager is refreshed for each test method. This means that when running multiple tests at once, you willlose your event listeners that were registered in config/bootstrap.php as the bootstrap is only executed once.

Running Tests
Once you have PHPUnit installed and some test cases written, you’ll want to run the test cases very frequently. It’s agood idea to run tests before committing any changes to help ensure you haven’t broken anything.
By using phpunit you can run your application tests. To run your application’s tests you can simply run:# composer installs$ vendor/bin/phpunit# phar filephp phpunit.phar
If you have cloned the CakePHP source from GitHub181 and wish to run CakePHP’s unit-tests don’t forget to executethe following Composer command prior to running phpunit so that any dependencies are installed:$ composer install
From your application’s root directory. To run tests for a plugin that is part of your application source, first cd into theplugin directory, then use phpunit command that matches how you installed phpunit:
cd plugins# Using composer installed phpunit../vendor/bin/phpunit# Using phar filephp ../phpunit.phar
To run tests on a standalone plugin, you should first install the project in a separate directory and install its dependencies:
181 https://github.com/cakephp/cakephp

Running Tests

791

CakePHP Book, Release 3.10

git clone https://github.com/cakephp/debug_kit.git
cd debug_kit
php ~/composer.phar installphp ~/phpunit.phar

Filtering Test Cases
When you have larger test cases, you will often want to run a subset of the test methods when you are trying to workon a single failing case. With the CLI runner you can use an option to filter test methods:$ phpunit --filter testSave tests/TestCase/Model/Table/ArticlesTableTest
The filter parameter is used as a case-sensitive regular expression for filtering which test methods to run.

Generating Code Coverage
You can generate code coverage reports from the command line using PHPUnit’s built-in code coverage tools. PHPUnit
will generate a set of static HTML files containing the coverage results. You can generate coverage for a test case by
doing the following:$ phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/ArticlesTableTest
This will put the coverage results in your application’s webroot directory. You should be able to view the results bygoing to http://localhost/your_app/coverage.
If you are using PHP 5.6.0 or greater, you can use phpdbg to generate coverage instead of xdebug. phpdbg is generally
faster at generating coverage:$ phpdbg -qrr phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/
˓→ArticlesTableTest

Combining Test Suites for Plugins
Often times your application will be composed of several plugins. In these situations it can be pretty tedious to run tests
for each plugin. You can make running tests for each of the plugins that compose your application by adding additional<testsuite> sections to your application’s phpunit.xml.dist file:<testsuites><testsuite name="app"><directory>./tests/TestCase/</directory></testsuite><!-- Add your plugin suites --><testsuite name="forum"><directory>./plugins/Forum/tests/TestCase/</directory></testsuite></testsuites>
Any additional test suites added to the <testsuites> element will automatically be run when you use phpunit.
If you are using <testsuites> to use fixtures from plugins that you have installed with composer, the plugin’s
composer.json file should add the fixture namespace to the autoload section. Example:
792

Chapter 28. TestingCakePHP Book, Release 3.10

"autoload-dev": {"psr-4": {"PluginName\\Test\\Fixture\\": "tests/Fixture/"}},

Test Case Lifecycle Callbacks
Test cases have a number of lifecycle callbacks you can use when doing testing:• setUp is called before every test method. Should be used to create the objects that are going to be tested, andinitialize any data for the test. Always remember to call parent::setUp()• tearDown is called after every test method. Should be used to cleanup after the test is complete. Always remember to call parent::tearDown().
• setupBeforeClass is called once before test methods in a case are started. This method must be static.
• tearDownAfterClass is called once after test methods in a case are started. This method must be static.

Fixtures
When testing code that depends on models and the database, one can use fixtures as a way to generate temporary datatables loaded with sample data that can be used by the test. The benefit of using fixtures is that your test has no chanceof disrupting live application data. In addition, you can begin testing your code prior to actually developing live content
for an application.
CakePHP uses the connection named test in your config/app.php configuration file. If this connection is not usable,
an exception will be raised and you will not be able to use database fixtures.
CakePHP performs the following during the course of a fixture based test case:
1. Creates tables for each of the fixtures needed.
2. Populates tables with data, if data is provided in fixture.
3. Runs test methods.
4. Empties the fixture tables.
5. Removes fixture tables from database.

Test Connections
By default CakePHP will alias each connection in your application. Each connection defined in your application’s bootstrap that does not start with test_ will have a test_ prefixed alias created. Aliasing connections ensures, you don’t
accidentally use the wrong connection in test cases. Connection aliasing is transparent to the rest of your application.
For example if you use the default connection, instead you will get the test connection in test cases. If you use thereplica connection, the test suite will attempt to use test_replica.

Test Case Lifecycle Callbacks

793

CakePHP Book, Release 3.10

PHPUnit Configuration
Before you can use fixtures you should double check that your phpunit.xml contains the fixture listener:<!-- in phpunit.xml --><!-- Setup a listener for fixtures --><listeners><listenerclass="\Cake\TestSuite\Fixture\FixtureInjector"><arguments><object class="\Cake\TestSuite\Fixture\FixtureManager" /></arguments></listener></listeners>
The listener is included in your application and plugins generated by bake by default.

Creating Fixtures
When creating a fixture you will mainly define two things: how the table is created (which fields are part of the table),and which records will be initially populated to the table. Let’s create our first fixture, that will be used to test our own
Article model. Create a file named ArticlesFixture.php in your tests/Fixture directory, with the following content:
namespace App\Test\Fixture;
use Cake\TestSuite\Fixture\TestFixture;class ArticlesFixture extends TestFixture{// Optional. Set this property to load fixtures to a different test datasource
public $connection = 'test';
public $fields = ['id' => ['type' => 'integer'],'title' => ['type' => 'string', 'length' => 255, 'null' => false],'body' => 'text','published' => ['type' => 'integer', 'default' => '0', 'null' => false],'created' => 'datetime','modified' => 'datetime','_constraints' => ['primary' => ['type' => 'primary', 'columns' => ['id']]]];public $records = [['title' => 'First Article','body' => 'First Article Body','published' => '1',
'created' => '2007-03-18 10:39:23','modified' => '2007-03-18 10:41:31'],['title' => 'Second Article',(continues on next page)

794

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)'body' => 'Second Article Body','published' => '1',
'created' => '2007-03-18 10:41:23','modified' => '2007-03-18 10:43:31'],['title' => 'Third Article','body' => 'Third Article Body','published' => '1',
'created' => '2007-03-18 10:43:23','modified' => '2007-03-18 10:45:31']];}

Note: It is recommended to not manually add values to auto incremental columns, as it interferes with the sequence
generation in PostgreSQL and SQLServer.
The $connection property defines the datasource of which the fixture will use. If your application uses multiple
datasources, you should make the fixtures match the model’s datasources but prefixed with test_. For example if yourmodel uses the mydb datasource, your fixture should use the test_mydb datasource. If the test_mydb connection
doesn’t exist, your models will use the default test datasource. Fixture datasources must be prefixed with test to
reduce the possibility of accidentally truncating all your application’s data when running tests.
We use $fields to specify which fields will be part of this table, and how they are defined. The format used to define
these fields is the same used with Cake\Database\Schema\Table. The keys available for table definition are:type
CakePHP internal data type. Currently supported:• string: maps to VARCHAR or CHAR
• uuid: maps to UUID
• text: maps to TEXT
• integer: maps to INT• biginteger: maps to BIGINTEGER• decimal: maps to DECIMAL• float: maps to FLOAT• datetime: maps to DATETIME• timestamp: maps to TIMESTAMP• time: maps to TIME
• date: maps to DATE
• binary: maps to BLOB
fixed
Used with string types to create CHAR columns in platforms that support them.
lengthSet to the specific length the field should take.

Fixtures795

CakePHP Book, Release 3.10

precision
Set the number of decimal places used on float & decimal fields.
null
Set to either true (to allow NULLs) or false (to disallow NULLs).
default
Default value the field takes.
We can define a set of records that will be populated after the fixture table is created. The format is fairly straightforward, $records is an array of records. Each item in $records should be a single row. Inside each row, should be
an associative array of the columns and values for the row. Just keep in mind that each record in the $records arraymust have a key for every field specified in the $fields array. If a field for a particular record needs to have a nullvalue, just specify the value of that key as null.

Dynamic Data and Fixtures
Since records for a fixture are declared as a class property, you cannot use functions or other dynamic data to define
fixtures. To solve this problem, you can define $records in the init() function of your fixture. For example if you
wanted all the created and modified timestamps to reflect today’s date you could do the following:namespace App\Test\Fixture;
use Cake\TestSuite\Fixture\TestFixture;class ArticlesFixture extends TestFixture{
public $fields = ['id' => ['type' => 'integer'],'title' => ['type' => 'string', 'length' => 255, 'null' => false],'body' => 'text','published' => ['type' => 'integer', 'default' => '0', 'null' => false],'created' => 'datetime','modified' => 'datetime','_constraints' => ['primary' => ['type' => 'primary', 'columns' => ['id']],]];public function init(){$this->records = [['title' => 'First Article','body' => 'First Article Body','published' => '1',
'created' => date('Y-m-d H:i:s'),'modified' => date('Y-m-d H:i:s'),],];parent::init();}}
When overriding init() remember to always call parent::init().
796

Chapter 28. TestingCakePHP Book, Release 3.10

Importing Table Information
Defining the schema in fixture files can be really handy when creating plugins or libraries or if you are creating anapplication that needs to be portable between database vendors. Redefining the schema in fixtures can become difficult
to maintain in larger applications. Because of this CakePHP provides the ability to import the schema from an existing
connection and use the reflected table definition to create the table definition used in the test suite.
Let’s start with an example. Assuming you have a table named articles available in your application, change the example
fixture given in the previous section (tests/Fixture/ArticlesFixture.php) to:class ArticlesFixture extends TestFixture{
public $import = ['table' => 'articles'];}If you want to use a different connection use:class ArticlesFixture extends TestFixture{
public $import = ['table' => 'articles', 'connection' => 'other'];}
New in version 3.1.7.
Usually, you have a Table class along with your fixture, as well. You can also use that to retrieve the table name:class ArticlesFixture extends TestFixture{
public $import = ['model' => 'Articles'];}
Since this uses TableRegistry::getTableLocator()->get(), it also supports plugin syntax.
You can naturally import your table definition from an existing model/table, but have your records defined directly on
the fixture as it was shown on previous section. For example:
class ArticlesFixture extends TestFixture{
public $import = ['table' => 'articles'];public $records = [['title' => 'First Article','body' => 'First Article Body','published' => '1',
'created' => '2007-03-18 10:39:23','modified' => '2007-03-18 10:41:31'],['title' => 'Second Article','body' => 'Second Article Body','published' => '1',
'created' => '2007-03-18 10:41:23','modified' => '2007-03-18 10:43:31'],[(continues on next page)

Fixtures797

CakePHP Book, Release 3.10

(continued from previous page)'title' => 'Third Article','body' => 'Third Article Body','published' => '1',
'created' => '2007-03-18 10:43:23','modified' => '2007-03-18 10:45:31']];}
Finally, it’s possible to not load/create any schema in a fixture. This is useful if you already have a test database setup
with all the empty tables created. By defining neither $fields nor $import, a fixture will only insert its records andtruncate the records on each test method.

Loading Fixtures in your Test Cases
After you’ve created your fixtures, you’ll want to use them in your test cases. In each test case you should load the
fixtures you will need. You should load a fixture for every model that will have a query run against it. To load fixtures
you define the $fixtures property in your model:
class ArticlesTest extends TestCase{
public $fixtures = ['app.Articles', 'app.Comments'];}

Note: You can also override TestCase::getFixtures() instead of defining the $fixtures property:
public function getFixtures(){return ['app.Articles', 'app.Comments'];}

The above will load the Article and Comment fixtures from the application’s Fixture directory. You can also load
fixtures from CakePHP core, or plugins:class ArticlesTest extends TestCase{
public $fixtures = ['plugin.DebugKit.Articles','plugin.MyVendorName/MyPlugin.Messages','core.Comments'];}
Using the core prefix will load fixtures from CakePHP, and using a plugin name as the prefix, will load the fixture
from the named plugin.
You can control when your fixtures are loaded by setting Cake\TestSuite\TestCase::$autoFixtures to false
and later load them using Cake\TestSuite\TestCase::loadFixtures():

798

Chapter 28. TestingCakePHP Book, Release 3.10

class ArticlesTest extends TestCase{
public $fixtures = ['app.Articles', 'app.Comments'];
public $autoFixtures = false;
public function testMyFunction(){$this->loadFixtures('Articles', 'Comments');}}
You can load fixtures in subdirectories. Using multiple directories can make it easier to organize your fixtures if you
have a larger application. To load fixtures in subdirectories, simply include the subdirectory name in the fixture name:class ArticlesTest extends CakeTestCase{
public $fixtures = ['app.Blog/Articles', 'app.Blog/Comments'];}
In the above example, both fixtures would be loaded from tests/Fixture/Blog/.

Fixture Factories
As your application grows, so does the number and the size of your test fixtures. You might find it difficult to maintain them and to keep track of their content. The fixture factories plugin182 proposes an alternative for large sized
applications.
The plugin uses its own phpunit listener183 which will perform the following actions:
1. Run migrations once on the test DB (see the migrator)184 .
2. Truncate dirty tables before each test.
3. Run tests.
The following command will help you bake your factories:
bin/cake bake fixture_factory -hOnce your factories are tuned185 , you are ready to create test fixtures in no time.
Unnecessary interaction with the database will slow down your tests as well as your application. You can create test
fixtures without persisting them which can be useful for testing methods without DB interaction:$article = ArticleFactory::make()->getEntity();
In order to persist:$article = ArticleFactory::make()->persist();The factories help creating associated fixtures too. Assuming that articles belongs to many authors, we can now, forexample, create 5 articles each with 2 authors:
182 https://github.com/vierge-noire/cakephp-fixture-factories
183 https://github.com/vierge-noire/cakephp-test-suite-light
184 https://github.com/vierge-noire/cakephp-test-migrator
185 https://github.com/vierge-noire/cakephp-fixture-factories/blob/main/docs/factories.md

Fixtures799

CakePHP Book, Release 3.10

$articles = ArticleFactory::make(5)->with('Authors', 2)->getEntities();
Note that the fixture factories do not require any fixture creation or declaration. Still, they are fully compatible with the
fixtures that come with cakephp. You will find additional insights and documentation here186 .

Testing Table Classes
Let’s say we already have our Articles Table class defined in src/Model/Table/ArticlesTable.php, and it looks like:namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\ORM\Query;class ArticlesTable extends Table{
public function findPublished(Query $query, array $options){$query->where([$this->alias() . '.published' => 1]);
return $query;}}We now want to set up a test that will test this table class. Let’s now create a file named ArticlesTableTest.php in yourtests/TestCase/Model/Table directory, with the following contents:
namespace App\Test\TestCase\Model\Table;
use App\Model\Table\ArticlesTable;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\TestCase;
class ArticlesTableTest extends TestCase{
public $fixtures = ['app.Articles'];}In our test cases’ variable $fixtures we define the set of fixtures that we’ll use. You should remember to include all
the fixtures that will have queries run against them.
186 https://github.com/vierge-noire/cakephp-fixture-factories

800

Chapter 28. TestingCakePHP Book, Release 3.10

Creating a Test Method
Let’s now add a method to test the function published() in the Articles table.
tests/TestCase/Model/Table/ArticlesTableTest.php so it now looks like this:Edit the filenamespace App\Test\TestCase\Model\Table;
use App\Model\Table\ArticlesTable;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\TestCase;
class ArticlesTableTest extends TestCase{
public $fixtures = ['app.Articles'];public function setUp(){
parent::setUp();$this->Articles = TableRegistry::getTableLocator()->get('Articles');}public function testFindPublished(){$query = $this->Articles->find('published');$this->assertInstanceOf('Cake\ORM\Query', $query);$result = $query->enableHydration(false)->toArray();$expected = [['id' => 1, 'title' => 'First Article'],['id' => 2, 'title' => 'Second Article'],['id' => 3, 'title' => 'Third Article']];$this->assertEquals($expected, $result);}}
You can see we have added a method called testFindPublished(). We start by creating an instance of our
ArticlesTable class, and then run our find('published') method. In $expected we set what we expect shouldbe the proper result (that we know since we have defined which records are initially populated to the article table.) We
test that the result equals our expectation by using the assertEquals() method. See the Running Tests section for
more information on how to run your test case.
Using the fixture factories, the test would now look like this:namespace App\Test\TestCase\Model\Table;
use App\Model\Table\ArticlesTable;
use App\Test\Factory\ArticleFactory;
use Cake\TestSuite\TestCase;
class ArticlesTableTest extends TestCase{
public function setUp(): void
{ ... }
(continues on next page)

Testing Table Classes

801CakePHP Book, Release 3.10

(continued from previous page)

public function testFindPublished(): void{// Persist 3 published articles$articles = ArticleFactory::make(['published' => 1], 3)->persist();// Persist 2 unpublished articles
ArticleFactory::make(['published' => 0], 2)->persist();$result = $this->Articles->find('published')->find('list')->toArray();$expected = [$articles[0]->id => $articles[0]->title,$articles[1]->id => $articles[1]->title,$articles[2]->id => $articles[2]->title,];$this->assertEquals($expected, $result);}}
No fixtures need to be loaded. The 5 articles created will exist only in this test.

Mocking Model Methods
There will be times you’ll want to mock methods on models when testing them. You should use getMockForModelto create testing mocks of table classes. It avoids issues with reflected properties that normal mocks have:public function testSendingEmails(){$model = $this->getMockForModel('EmailVerification', ['send']);$model->expects($this->once())->method('send')->will($this->returnValue(true));$model->verifyEmail('test@example.com');}
In your tearDown() method be sure to remove the mock with:
TableRegistry::clear();Controller Integration Testing
While you can test controller classes in a similar fashion to Helpers, Models, and Components, CakePHP offers a
specialized IntegrationTestTrait trait. Using this trait in your controller test cases allows you to test controllers
from a high level.
New in version 3.7.0: The IntegrationTestCase class was moved into the IntegrationTestTrait trait.
If you are unfamiliar with integration testing, it is a testing approach that makes it easy to test multiple units in concert.
The integration testing features in CakePHP simulate an HTTP request being handled by your application. For example,
802

Chapter 28. TestingCakePHP Book, Release 3.10

testing your controller will also exercise any components, models and helpers that would be involved in handling a given
request. This gives you a more high level test of your application and all its working parts.
Say you have a typical ArticlesController, and its corresponding model. The controller code looks like:namespace App\Controller;
use App\Controller\AppController;class ArticlesController extends AppController{
public $helpers = ['Form', 'Html'];public function index($short = null){
if ($this->request->is('post')) {$article = $this->Articles->newEntity($this->request->getData());
if ($this->Articles->save($article)) {// Redirect as per PRG patternreturn $this->redirect(['action' => 'index']);}}if (!empty($short)) {$result = $this->Articles->find('all', ['fields' => ['id', 'title']]);} else {$result = $this->Articles->find();}$this->set(['title' => 'Articles','articles' => $result]);}}
Create a file named ArticlesControllerTest.php in your tests/TestCase/Controller directory and put the following
inside:namespace App\Test\TestCase\Controller;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\IntegrationTestTrait;
use Cake\TestSuite\TestCase;
class ArticlesControllerTest extends TestCase{
use IntegrationTestTrait;
public $fixtures = ['app.Articles'];public function testIndex(){(continues on next page)

Controller Integration Testing803

CakePHP Book, Release 3.10

(continued from previous page)$this->get('/articles');$this->assertResponseOk();// More asserts.
}
public function testIndexQueryData(){$this->get('/articles?page=1');$this->assertResponseOk();// More asserts.
}
public function testIndexShort(){$this->get('/articles/index/short');$this->assertResponseOk();$this->assertResponseContains('Articles');// More asserts.
}
public function testIndexPostData(){$data = ['user_id' => 1,'published' => 1,'slug' => 'new-article','title' => 'New Article','body' => 'New Body'];$this->post('/articles', $data);$this->assertResponseSuccess();$articles = TableRegistry::getTableLocator()->get('Articles');$query = $articles->find()->where(['title' => $data['title']]);$this->assertEquals(1, $query->count());}}
This example shows a few of the request sending methods and a few of the assertions that IntegrationTestTrait
provides. Before you can do any assertions you’ll need to dispatch a request. You can use one of the following methods
to send a request:• get() Sends a GET request.
• post() Sends a POST request.
• put() Sends a PUT request.
• delete() Sends a DELETE request.
• patch() Sends a PATCH request.
• options() Sends an OPTIONS request.
804

Chapter 28. TestingCakePHP Book, Release 3.10

• head() Sends a HEAD request.
All of the methods except get() and delete() accept a second parameter that allows you to send a request body.
After dispatching a request you can use the various assertions provided by IntegrationTestTrait or PHPUnit toensure your request had the correct side-effects.
New in version 3.5.0: options() and head() were added in 3.5.0.

Setting up the Request
The IntegrationTestTrait trait comes with a number of helpers to make it easy to configure the requests you will
send to your application under test:// Set cookies$this->cookie('name', 'Uncle Bob');// Set session data
$this->session(['Auth.User.id' => 1]);// Configure headers$this->configRequest(['headers' => ['Accept' => 'application/json']]);
The state set by these helper methods is reset in the tearDown() method.

Testing Actions That Require Authentication
If you are using AuthComponent you will need to stub out the session data that AuthComponent uses to validate a user’s identity. You can use helper methods in IntegrationTestTrait to do this. Assuming you had an
ArticlesController that contained an add method, and that add method required authentication, you could write
the following tests:
public function testAddUnauthenticatedFails(){// No session data set.
$this->get('/articles/add');$this->assertRedirect(['controller' => 'Users', 'action' => 'login']);}public function testAddAuthenticated(){// Set session data
$this->session(['Auth' => ['User' => ['id' => 1,'username' => 'testing',// other keys.
]]]);(continues on next page)

Controller Integration Testing805

CakePHP Book, Release 3.10

(continued from previous page)$this->get('/articles/add');$this->assertResponseOk();// Other assertions.
}

Testing Stateless Authentication and APIs
To test APIs that use stateless authentication, such as Basic authentication, you can configure the request to injectenvironment conditions or headers that simulate actual authentication request headers.
When testing Basic or Digest Authentication, you can add the environment variables that PHP creates187 automatically.
These environment variables used in the authentication adapter outlined in Using Basic Authentication:
public function testBasicAuthentication(){$this->configRequest(['environment' => ['PHP_AUTH_USER' => 'username','PHP_AUTH_PW' => 'password',]]);$this->get('/api/posts');$this->assertResponseOk();}
If you are testing other forms of authentication, such as OAuth2, you can set the Authorization header directly:
public function testOauthToken(){$this->configRequest(['headers' => ['authorization' => 'Bearer: oauth-token']]);$this->get('/api/posts');$this->assertResponseOk();}
The headers key in configRequest() can be used to configure any additional HTTP headers needed for an action.
187 https://php.net/manual/en/features.http-auth.php

806

Chapter 28. TestingCakePHP Book, Release 3.10

Testing Actions Protected by CsrfComponent or SecurityComponent
When testing actions protected by either SecurityComponent or CsrfComponent you can enable automatic token generation to ensure your tests won’t fail due to token mismatches:
public function testAdd(){$this->enableCsrfToken();$this->enableSecurityToken();$this->post('/posts/add', ['title' => 'Exciting news!']);}
It is also important to enable debug in tests that use tokens to prevent the SecurityComponent from thinking the debug
token is being used in a non-debug environment. When testing with other methods like requireSecure() you can
use configRequest() to set the correct environment variables:// Fake out SSL connections.
$this->configRequest(['environment' => ['HTTPS' => 'on']]);
If your action requires unlocked fields you can declare them with setUnlockedFields():$this->setUnlockedFields(['dynamic_field']);New in version 3.1.2: The enableCsrfToken() and enableSecurityToken() methods were added in 3.1.2
New in version 3.8.3: The setUnlockedFields() method was added.

Integration Testing PSR-7 Middleware
Integration testing can also be used to test your entire PSR-7 application and /controllers/middleware. By default
IntegrationTestTrait will auto-detect the presence of an App\Application class and automatically enable integration testing of your Application. You can toggle this behavior with the useHttpServer() method:
public function setUp(){// Enable PSR-7 integration testing.
$this->useHttpServer(true);// Disable PSR-7 integration testing.
$this->useHttpServer(false);}
You can customize the application class name used, and the constructor arguments, by using theconfigApplication() method:
public function setUp(){$this->configApplication('App\App', [CONFIG]);}
After enabling the PSR-7 mode, and possibly configuring your application class, you can use the remaining
IntegrationTestTrait features as normal.

Controller Integration Testing807

CakePHP Book, Release 3.10

You should also take care to try and use Application::bootstrap() to load any plugins containing events/routes. Doing so
will ensure that your events/routes are connected for each test case. Alternatively if you wish to load plugins manuallyin a test you can use the loadPlugins() method:use Cake\Routing\Router;public function testRouteCount(){// Assert the amount of routes from the application, without loading plugins$this->assertCount(35, Router::routes(), 'App route count does not match');// Assert the amount of routes from the application including a specific plugin"SomePlugin"$this->loadPlugins(['SomePlugin']);$this->assertCount(40, Router::routes(), 'App & SomePlugin route count does not match
˓→');
˓→

// Assert the amount of routes from the application including all plugins$this->loadPlugins();$this->assertCount(60, Router::routes(), 'App & plugin route count does not match');}New in version 3.3.0: PSR-7 Middleware and the useHttpServer() method were added in 3.3.0.

Testing with Encrypted Cookies
If you use the Cake\Controller\Component\CookieComponent in your controllers, your cookies are likely encrypted. As of 3.1.7, CakePHP provides helper methods for interacting with encrypted cookies in your test cases:// Set a cookie using AES and the default key.
$this->cookieEncrypted('my_cookie', 'Some secret values');// Assume this action modifies the cookie.
$this->get('/bookmarks/index');$this->assertCookieEncrypted('An updated value', 'my_cookie');
New in version 3.1.7: assertCookieEncrypted and cookieEncrypted were added in 3.1.7.

Testing Flash Messages
If you want to assert the presence of flash messages in the session and not the rendered HTML, you can use
enableRetainFlashMessages() in your tests to retain flash messages in the session so you can write assertions:$this->enableRetainFlashMessages();$this->get('/bookmarks/delete/9999');$this->assertSession('That bookmark does not exist', 'Flash.flash.0.message');
As of 3.7.0 there are additional test helpers for flash messages:

808

Chapter 28. TestingCakePHP Book, Release 3.10

$this->enableRetainFlashMessages();$this->get('/bookmarks/delete/9999');// Assert a flash message in the 'flash' key.
$this->assertFlashMessage('Bookmark deleted', 'flash');// Assert the second flash message, also in the 'flash' key.
$this->assertFlashMessageAt(1, 'Bookmark really deleted');// Assert a flash message in the 'auth' key at the first position$this->assertFlashMessageAt(0, 'You are not allowed to enter this dungeon!', 'auth');// Assert a flash messages uses the error element$this->assertFlashElement('Flash/error');// Assert the second flash message element$this->assertFlashElementAt(1, 'Flash/error');
New in version 3.4.7: enableRetainFlashMessages() was added in 3.4.7
New in version 3.7.0: Flash message assertions were added.

Testing a JSON Responding Controller
JSON is a friendly and common format to use when building a web service. Testing the endpoints of your web service
is very simple with CakePHP. Let us begin with a simple example controller that responds in JSON:
class MarkersController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('RequestHandler');}
public function view($id){$marker = $this->Markers->get($id);$this->set(['_serialize' => ['marker'],'marker' => $marker,]);}}
Now we create the file tests/TestCase/Controller/MarkersControllerTest.php and make sure our web service isreturning the proper response:class MarkersControllerTest extends IntegrationTestCase{
public function testGet(){$this->configRequest([(continues on next page)

Controller Integration Testing809

CakePHP Book, Release 3.10

(continued from previous page)'headers' => ['Accept' => 'application/json']]);$result = $this->get('/markers/view/1.json');// Check that the response was a 200$this->assertResponseOk();$expected = [['id' => 1, 'lng' => 66, 'lat' => 45],];
$expected = json_encode($expected, JSON_PRETTY_PRINT);$this->assertEquals($expected, (string)$this->_response->getBody());}}
We use the JSON_PRETTY_PRINT option as CakePHP’s built in JsonView will use that option when debug is enabled.

Disabling Error Handling Middleware in Tests
When debugging tests that are failing because your application is encountering errors it can be helpful totemporarily disable the error handling middleware to allow the underlying error to bubble up. You can use
disableErrorHandlerMiddleware() to do this:public function testGetMissing(){$this->disableErrorHandlerMiddleware();$this->get('/markers/not-there');$this->assertResponseCode(404);}
In the above example, the test would fail and the underlying exception message and stack trace would be displayed
instead of the rendered error page being checked.
New in version 3.5.0.

Assertion methods
The IntegrationTestTrait trait provides a number of assertion methods that make testing responses much simpler.
Some examples are:// Check for a 2xx response code
$this->assertResponseOk();// Check for a 2xx/3xx response code
$this->assertResponseSuccess();// Check for a 4xx response code
$this->assertResponseError();// Check for a 5xx response code
$this->assertResponseFailure();(continues on next page)

810

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)// Check for a specific response code, e.g. 200$this->assertResponseCode(200);// Check the Location header$this->assertRedirect(['controller' => 'Articles', 'action' => 'index']);// Check that no Location header has been set$this->assertNoRedirect();// Check a part of the Location header$this->assertRedirectContains('/articles/edit/');// Added in 3.7.0$this->assertRedirectNotContains('/articles/edit/');// Assert not empty response content$this->assertResponseNotEmpty();// Assert empty response content$this->assertResponseEmpty();// Assert response content$this->assertResponseEquals('Yeah!');// Assert response content doesn't equal$this->assertResponseNotEquals('No!');// Assert partial response content$this->assertResponseContains('You won!');$this->assertResponseNotContains('You lost!');// Assert file sent back$this->assertFileResponse('/absolute/path/to/file.ext');// Assert layout$this->assertLayout('default');// Assert which template was rendered (if any)
$this->assertTemplate('index');// Assert data in the session$this->assertSession(1, 'Auth.User.id');// Assert response header.
$this->assertHeader('Content-Type', 'application/json');$this->assertHeaderContains('Content-Type', 'html');// Added in 3.7.0$this->assertHeaderNotContains('Content-Type', 'xml');// Assert view variables(continues on next page)

Controller Integration Testing811

CakePHP Book, Release 3.10

(continued from previous page)$user = $this->viewVariable('user');$this->assertEquals('jose', $user->username);// Assert cookies in the response$this->assertCookie('1', 'thingid');// Check the content type$this->assertContentType('application/json');In addition to the above assertion methods, you can also use all of the assertions in TestSuite188 and those found in
PHPUnit189 .

Comparing test results to a file
For some types of test, it may be easier to compare the result of a test to the contents of a file - for example, when
testing the rendered output of a view. The StringCompareTrait adds a simple assert method for this purpose.
Usage involves using the trait, setting the comparison base path and calling assertSameAsFile:use Cake\TestSuite\StringCompareTrait;
use Cake\TestSuite\TestCase;
class SomeTest extends TestCase{
use StringCompareTrait;
public function setUp(){$this->_compareBasePath = APP . 'tests' . DS . 'comparisons' . DS;
parent::setUp();}public function testExample(){$result = ...;
$this->assertSameAsFile('example.php', $result);}}
The above example will compare $result to the contents of the file APP/tests/comparisons/example.php.
A mechanism is provided to write/update test files,
by setting the environment variable
UPDATE_TEST_COMPARISON_FILES, which will create and/or update test comparison files as they are referenced:
phpunit...
FAILURES!
Tests: 6, Assertions: 7, Failures: 1
UPDATE_TEST_COMPARISON_FILES=1 phpunit(continues on next page)188 https://api.cakephp.org/3.x/class-Cake.TestSuite.TestCase.html
189 https://phpunit.readthedocs.io/en/8.5/assertions.html

812

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)...
OK (6 tests, 7 assertions)git status...
# Changes not staged for commit:#(use "git add <file>..." to update what will be committed)#(use "git checkout -- <file>..." to discard changes in working directory)##
modified:
tests/comparisons/example.php

Console Integration Testing
See Testing Commands for information on testing shells and commands.

Testing Views
Generally most applications will not directly test their HTML code. Doing so is often results in fragile, difficult tomaintain test suites that are prone to breaking. When writing functional tests using IntegrationTestTrait you caninspect the rendered view content by setting the return option to ‘view’. While it is possible to test view content using
IntegrationTestTrait, a more robust and maintainable integration/view testing can be accomplished using tools
like Selenium webdriver190 .

Testing Components
Let’s pretend we have a component called PagematronComponent in our application. This component helps us
set the pagination limit value across all the controllers that use it. Here is our example component located in
src/Controller/Component/PagematronComponent.php:
class PagematronComponent extends Component{
public $controller = null;public function setController($controller){$this->controller = $controller;// Make sure the controller is using pagination
if (!isset($this->controller->paginate)) {$this->controller->paginate = [];}}public function startup(Event $event){$this->setController($event->getSubject());(continues on next page)
190 https://www.selenium.dev/

Console Integration Testing813

CakePHP Book, Release 3.10

(continued from previous page)}
public function adjust($length = 'short'){
switch ($length) {case 'long':$this->controller->paginate['limit'] = 100;
break;
case 'medium':$this->controller->paginate['limit'] = 50;
break;
default:$this->controller->paginate['limit'] = 20;
break;}}}
Now we can write tests to ensure our paginate limit parameter is being set correctly by the adjust() method in ourcomponent. We create the file tests/TestCase/Controller/Component/PagematronComponentTest.php:
namespace App\Test\TestCase\Controller\Component;
use App\Controller\Component\PagematronComponent;
use Cake\Controller\Controller;
use Cake\Controller\ComponentRegistry;
use Cake\Event\Event;use Cake\Http\ServerRequest;
use Cake\Http\Response;
use Cake\TestSuite\TestCase;
class PagematronComponentTest extends TestCase{
protected $component;
protected $controller;
public function setUp(){
parent::setUp();// Setup our component and fake test controller$request = new ServerRequest();$response = new Response();$this->controller = $this->getMockBuilder('Cake\Controller\Controller')->setConstructorArgs([$request, $response])->setMethods(null)->getMock();$registry = new ComponentRegistry($this->controller);$this->component = new PagematronComponent($registry);$event = new Event('Controller.startup', $this->controller);$this->component->startup($event);}(continues on next page)

814

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)

public function testAdjust(){// Test our adjust method with different parameter settings$this->component->adjust();$this->assertEquals(20, $this->controller->paginate['limit']);$this->component->adjust('medium');$this->assertEquals(50, $this->controller->paginate['limit']);$this->component->adjust('long');$this->assertEquals(100, $this->controller->paginate['limit']);}public function tearDown(){
parent::tearDown();// Clean up after we're done
unset($this->component, $this->controller);}}

Testing Helpers
Since a decent amount of logic resides in Helper classes, it’s important to make sure those classes are covered by test
cases.
First we create an example helper to test. The CurrencyRendererHelper will help us display currencies in our views
and for simplicity only has one method usd():// src/View/Helper/CurrencyRendererHelper.php
namespace App\View\Helper;
use Cake\View\Helper;class CurrencyRendererHelper extends Helper{
public function usd($amount){return 'USD ' . number_format($amount, 2, '.', ',');}}
Here we set the decimal places to 2, decimal separator to dot, thousands separator to comma, and prefix the formatted
number with ‘USD’ string.
Now we create our tests:// tests/TestCase/View/Helper/CurrencyRendererHelperTest.php
namespace App\Test\TestCase\View\Helper;(continues on next page)

Testing Helpers

815CakePHP Book, Release 3.10

(continued from previous page)use App\View\Helper\CurrencyRendererHelper;
use Cake\TestSuite\TestCase;
use Cake\View\View;
class CurrencyRendererHelperTest extends TestCase{
public $helper = null;// Here we instantiate our helper
public function setUp(){
parent::setUp();$View = new View();$this->helper = new CurrencyRendererHelper($View);}// Testing the usd() function
public function testUsd(){$this->assertEquals('USD 5.30', $this->helper->usd(5.30));// We should always have 2 decimal digits$this->assertEquals('USD 1.00', $this->helper->usd(1));$this->assertEquals('USD 2.05', $this->helper->usd(2.05));// Testing the thousands separator$this->assertEquals('USD 12,000.70',$this->helper->usd(12000.70));}}
Here, we call usd() with different parameters and tell the test suite to check if the returned values are equal to what is
expected.
Save this and execute the test. You should see a green bar and messaging indicating 1 pass and 4 assertions.
When you are testing a Helper which uses other helpers, be sure to mock the View clases loadHelpers method.

Testing EventsThe Events System is a great way to decouple your application code, but sometimes when testing, you tend to test theresults of events in the test cases that execute those events. This is an additional form of coupling that can be removed
by using assertEventFired and assertEventFiredWith instead.
Expanding on the Orders example, say we have the following tables:class OrdersTable extends Table{
public function place($order){(continues on next page)

816

Chapter 28. TestingCakePHP Book, Release 3.10

(continued from previous page)if ($this->save($order)) {// moved cart removal to CartsTable$event = new Event('Model.Order.afterPlace', $this, ['order' => $order]);$this->eventManager()->dispatch($event);
return true;}
return false;}}class CartsTable extends Table{
public function implementedEvents(){
return ['Model.Order.afterPlace' => 'removeFromCart'];}
public function removeFromCart(Event $event){$order = $event->getData('order');$this->delete($order->cart_id);}}

Note: To assert that events are fired, you must first enable Tracking Events on the event manager you wish to assert
against.
To test the OrdersTable above, we enable tracking in setUp() then assert that the event was fired, and assert that the$order entity was passed in the event data:namespace App\Test\TestCase\Model\Table;
use App\Model\Table\OrdersTable;
use Cake\Event\EventList;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\TestCase;
class OrdersTableTest extends TestCase{
public $fixtures = ['app.Orders'];
public function setUp(){
parent::setUp();$this->Orders = TableRegistry::getTableLocator()->get('Orders');// enable event tracking$this->Orders->getEventManager()->setEventList(new EventList());(continues on next page)

Testing Events817

CakePHP Book, Release 3.10

(continued from previous page)}
public function testPlace(){$order = new Order(['user_id' => 1,'item' => 'Cake','quantity' => 42,]);$this->assertTrue($this->Orders->place($order));$this->assertEventFired('Model.Order.afterPlace', $this->Orders->
getEventManager());$this->assertEventFiredWith('Model.Order.afterPlace', 'order', $order, $this->
˓→Orders->getEventManager());}}˓→

By default, the global EventManager is used for assertions, so testing global events does not require passing the event
manager:$this->assertEventFired('My.Global.Event');$this->assertEventFiredWith('My.Global.Event', 'user', 1);
New in version 3.2.11: Event tracking, assertEventFired(), and assertEventFiredWith were added.

Testing EmailSee Testing Email for information on testing email.

Creating Test Suites
If you want several of your tests to run at the same time, you can create a test suite. A test suite is composed of several
test cases. You can either create test suites in your application’s phpunit.xml file. A simple example would be:<testsuites><testsuite name="Models"><directory>src/Model</directory><file>src/Service/UserServiceTest.php</file><exclude>src/Model/Cloud/ImagesTest.php</exclude></testsuite></testsuites>

818

Chapter 28. TestingCakePHP Book, Release 3.10

Creating Tests for Plugins
Tests for plugins are created in their own directory inside the plugins folder.
/src/plugins/Blog/tests/TestCase/Fixture
They work just like normal tests but you have to remember to use the naming conventions for plugins when importingclasses. This is an example of a testcase for the BlogPost model from the plugins chapter of this manual. A difference
from other tests is in the first line where ‘Blog.BlogPost’ is imported. You also need to prefix your plugin fixtures withplugin.Blog.BlogPosts:
namespace Blog\Test\TestCase\Model\Table;
use Blog\Model\Table\BlogPostsTable;
use Cake\TestSuite\TestCase;
class BlogPostsTableTest extends TestCase{// Plugin fixtures located in /plugins/Blog/tests/Fixture/public $fixtures = ['plugin.Blog.BlogPosts'];
public function testSomething(){// Test something.
}}
If you want to use plugin fixtures in the app tests you can reference them using plugin.pluginName.fixtureName
syntax in the $fixtures array. Additionally if you use vendor plugin name or fixture directories you can use thefollowing: plugin.vendorName/pluginName.folderName/fixtureName.
Before you can use fixtures you should ensure you have the fixture listener configured in your phpunit.xml file. You
should also ensure that your fixtures are loadable. Ensure the following is present in your composer.json file:"autoload-dev": {"psr-4": {"MyPlugin\\Test\\": "plugins/MyPlugin/tests/"}}

Note: Remember to run composer.phar dump-autoload when adding new autoload mappings.

Creating Tests for Plugins

819

CakePHP Book, Release 3.10

Generating Tests with Bake
If you use bake to generate scaffolding, it will also generate test stubs. If you need to re-generate test case skeletons, or
if you want to generate test skeletons for code you wrote, you can use bake:bin/cake bake test <type> <name><type> should be one of:
1. Entity
2. Table
3. Controller
4. Component
5. Behavior
6. Helper
7. Shell
8. Task
9. ShellHelper
10. Cell
11. Form
12. Mailer
13. Command
While <name> should be the name of the object you want to bake a test skeleton for.

Integration with Jenkins
Jenkins191 is a continuous integration server, that can help you automate the running of your test cases. This helps
ensure that all your tests stay passing and your application is always ready.
Integrating a CakePHP application with Jenkins is fairly straightforward. The following assumes you’ve already installed Jenkins on *nix system, and are able to administer it. You also know how to create jobs, and run builds. If you
are unsure of any of these, refer to the Jenkins documentation192 .

Create a Job
Start off by creating a job for your application, and connect your repository so that jenkins can access your code.
191 https://jenkins-ci.org
192 https://jenkins-ci.org/

820

Chapter 28. TestingCakePHP Book, Release 3.10

Add Test Database Config
Using a separate database just for Jenkins is generally a good idea, as it stops bleed through and avoids a number ofbasic problems. Once you’ve created a new database in a database server that jenkins can access (usually localhost).
Add a shell script step to the build that contains the following:
cat > config/app_local.php <<'CONFIG'<?php
return ['Datasources' => ['test' => ['datasource' => 'Database/Mysql','host'=> 'localhost','database'=> 'jenkins_test','username'=> 'jenkins','password'=> 'cakephp_jenkins','encoding'=> 'utf8']]];
CONFIG
Then uncomment the following line in your config/bootstrap.php file://Configure::load('app_local', 'default');
By creating an app_local.php file, you have an easy way to define configuration specific to Jenkins. You can use thissame configuration file to override any other configuration files you need on Jenkins.
It’s often a good idea to drop and re-create the database before each build as well. This insulates you from chained
failures, where one broken build causes others to fail. Add another shell script step to the build that contains thefollowing:
mysql -u jenkins -pcakephp_jenkins -e 'DROP DATABASE IF EXISTS jenkins_test; CREATE␣˓→DATABASE jenkins_test';

Add your Tests
Add another shell script step to your build. In this step install your dependencies and run the tests for your application.
Creating a junit log file, or clover coverage is often a nice bonus, as it gives you a nice graphical view of your testing
results:# Download Composer if it is missing.
test -f 'composer.phar' || curl -sS https://getcomposer.org/installer | php# Install dependencies
php composer.phar install
vendor/bin/phpunit --log-junit junit.xml --coverage-clover clover.xml
If you use clover coverage, or the junit results, make sure to configure those in Jenkins as well. Failing to configure
those steps will mean you won’t see the results.

Integration with Jenkins

821

CakePHP Book, Release 3.10

Run a Build
You should be able to run a build now. Check the console output and make any necessary changes to get a passingbuild.

822

Chapter 28. TestingCHAPTER 29

Validation

The validation package in CakePHP provides features to build validators that can validate arbitrary arrays of data withease. You can find a list of available Validation rules in the API193 .

Creating Validatorsclass Cake\Validation\Validator
Validator objects define the rules that apply to a set of fields. Validator objects contain a mapping between fields andvalidation sets. In turn, the validation sets contain a collection of rules that apply to the field they are attached to.
Creating a validator is simple:
use Cake\Validation\Validator;$validator = new Validator();Once created, you can start defining sets of rules for the fields you want to validate:// Prior to 3.7 you must use allowEmpty() or notEmpty().
$validator->requirePresence('title')->notEmptyString('title', 'Please fill this field')->add('title', ['length' => ['rule' => ['minLength', 10],'message' => 'Titles need to be at least 10 characters long',]])(continues on next page)
193 https://api.cakephp.org/3.x/class-Cake.Validation.Validation.html

823

CakePHP Book, Release 3.10

(continued from previous page)->allowEmptyDateTime('published')->add('published', 'boolean', ['rule' => 'boolean'])->requirePresence('body')->add('body', 'length', ['rule' => ['minLength', 50],
'message' => 'Articles must have a substantial body.']);
As seen in the example above, validators are built with a fluent interface that allows you to define rules for each field
you want to validate.
There were a few methods called in the example above, so let’s go over the various features. The add() method allows
you to add new rules to a validator. You can either add rules individually or in groups as seen above.

Requiring Field Presence
The requirePresence() method requires the field to be present in any validated array. If the field is absent, validation
will fail. The requirePresence() method has 4 modes:• true The field’s presence is always required.
• false The field’s presence is not required.
• create The field’s presence is required when validating a create operation.
• update The field’s presence is required when validating an update operation.
By default, true is used. Key presence is checked by using array_key_exists() so that null values will count aspresent. You can set the mode using the second parameter:$validator->requirePresence('author_id', 'create');If you have multiple fields that are required, you can define them as a list:// Define multiple fields for create$validator->requirePresence(['author_id', 'title'], 'create');// Define multiple fields for mixed modes$validator->requirePresence(['author_id' => ['mode' => 'create','message' => 'An author is required.',],'published' => ['mode' => 'update','message' => 'The published state is required.',]]);
New in version 3.3.0: requirePresence() accepts an array of fields as of 3.3.0

824

Chapter 29. Validation

CakePHP Book, Release 3.10

Allowing Empty Fields
Validators offer several methods to control which fields accept empty values and which empty values are accepted andnot forwarded to other validation rules for the named field. CakePHP provides empty value support for five different
shapes of data:
1. allowEmptyString() Should be used when you want to only accept an empty string.
2. allowEmptyArray() Should be used when you want to accept an array.
3. allowEmptyDate() Should be used when you want to accept an empty string, or an array that is marshalled
into a date field.
4. allowEmptyTime() Should be used when you want to accept an empty string, or an array that is marshalled
into a time field.
5. allowEmptyDateTime() Should be used when you want to accept an empty string or an array that is marshalled
into a datetime or timestamp field.
6. allowEmptyFile() Should be used when you want to accept an array that is contains an empty uploaded file.
You can also use notEmpty() to mark a field invalid if any ‘empty’ value is used. In general, it is recommended
that you do not use notEmpty() and use more specific validators instead: notEmptyString(), notEmptyArray(),
notEmptyFile(), notEmptyDate(), notEmptyTime(), notEmptyDateTime().
The allowEmpty* methods support a when parameter that allows you to control when a field can or cannot be empty:• false The field is not allowed to be empty.
• create The field can be empty when validating a create operation.
• update The field can be empty when validating an update operation.
• A callback that returns true or false to indicate whether a field is allowed to be empty. See the Conditional
Validation section for examples on how to use this parameter.
An example of these methods in action is:// Prior to 3.7 you must use allowEmpty() or notEmpty().
$validator->allowEmptyDateTime('published')->allowEmptyString('title', 'Title cannot be empty', false)->allowEmptyString('body', 'Body cannot be empty', 'update')->allowEmptyFile('header_image', 'update');->allowEmptyDateTime('posted', 'update');Adding Validation Rules
The Validator class provides methods that make building validators simple and expressive. For example adding
validation rules to a username could look like:$validator = new Validator();$validator->email('username')->ascii('username')->lengthBetween('username', [4, 8]);See the Validator API documentation194 for the full set of validator methods.
New in version 3.2: Rule building methods were added in 3.2.0
194 https://api.cakephp.org/3.x/class-Cake.Validation.Validator.html

Creating Validators

825

CakePHP Book, Release 3.10

Using Custom Validation Rules
In addition to using methods on the Validator, and coming from providers, you can also use any callable, including
anonymous functions, as validation rules:// Use a global function$validator->add('title', 'custom', ['rule' => 'validate_title','message' => 'The title is not valid']);// Use an array callable that is not in a provider$validator->add('title', 'custom', ['rule' => [$this, 'method'],'message' => 'The title is not valid']);// Use a closure$extra = 'Some additional value needed inside the closure';$validator->add('title', 'custom', ['rule' => function ($value, $context) use ($extra) {// Custom logic that returns true/false},'message' => 'The title is not valid']);// Use a rule from a custom provider$validator->add('title', 'custom', ['rule' => 'customRule','provider' => 'custom','message' => 'The title is not unique enough']);Closures or callable methods will receive 2 arguments when called. The first will be the value for the field being
validated. The second is a context array containing data related to the validation process:• data: The original data passed to the validation method, useful if you plan to create rules comparing values.
• providers: The complete list of rule provider objects, useful if you need to create complex rules by calling
multiple providers.
• newRecord: Whether the validation call is for a new record or a preexisting one.
If you need to pass additional data to your validation methods such as the current user’s id, you can use a custom
dynamic provider from your controller.
$this->Examples->validator('default')->provider('passed', ['count' => $countFromController,'userid' => $this->Auth->user('id')]);
Then ensure that your validation method has the second context parameter.
public function customValidationMethod($check, array $context){(continues on next page)

826

Chapter 29. Validation

CakePHP Book, Release 3.10

(continued from previous page)$userid = $context['providers']['passed']['userid'];}
Closures should return boolean true if the validation passes. If it fails, return boolean false or for a custom error message
return a string, see the Conditional/Dynamic Error Messages section for further details.

Conditional/Dynamic Error Messages
Validation rule methods, being it custom callables, or methods supplied by providers, can either return a boolean,
indicating whether the validation succeeded, or they can return a string, which means that the validation failed, andthat the returned string should be used as the error message.
Possible existing error messages defined via the message option will be overwritten by the ones returned from thevalidation rule method:$validator->add('length', 'custom', ['rule' => function ($value, $context) {if (!$value) {return false;}
if ($value < 10) {return 'Error message when value is less than 10';}if ($value > 20) {return 'Error message when value is greater than 20';}
return true;},'message' => 'Generic error message used when `false` is returned']);

Conditional Validation
When defining validation rules, you can use the on key to define when a validation rule should be applied. If left
undefined, the rule will always be applied. Other valid values are create and update. Using one of these values will
make the rule apply to only create or update operations.
Additionally, you can provide a callable function that will determine whether or not a particular rule should be applied:$validator->add('picture', 'file', ['rule' => ['mimeType', ['image/jpeg', 'image/png']],'on' => function ($context) {return !empty($context['data']['show_profile_picture']);}]);
You can access the other submitted field values using the $context['data'] array. The above example will makethe rule for ‘picture’ optional depending on whether the value for show_profile_picture is empty. You could also
use the uploadedFile validation rule to create optional file upload inputs:
Creating Validators

827

CakePHP Book, Release 3.10

$validator->add('picture', 'file', ['rule' => ['uploadedFile', ['optional' => true]],]);
The allowEmpty*, notEmpty() and requirePresence() methods will also accept a callback function as their lastargument. If present, the callback determines whether or not the rule should be applied. For example, a field issometimes allowed to be empty:$validator->allowEmptyString('tax', function ($context) {return !$context['data']['is_taxable'];});Likewise, a field can be required to be populated when certain conditions are met:
$validator->notEmpty('email_frequency', 'This field is required', function ($context) {return !empty($context['data']['wants_newsletter']);});In the above example, the email_frequency field cannot be left empty if the the user wants to receive the newsletter.
Further it’s also possible to require a field to be present under certain conditions only:$validator->requirePresence('full_name', function ($context) {if (isset($context['data']['action'])) {return $context['data']['action'] === 'subscribe';}
return false;});$validator->requirePresence('email');This would require the full_name field to be present only in case the user wants to create a subscription, while theemail field would always be required.
The $context parameter passed to custom conditional callbacks contains the following keys:• data The data being validated.
• newRecord a boolean indicating whether a new or existing record is being validated.
• field The current field being validated.
• providers The validation providers attached to the current validator.
New in version 3.1.1: The callable support for requirePresence() was added in 3.1.1

Marking Rules as the Last to Run
When fields have multiple rules, each validation rule will be run even if the previous one has failed. This allows you
to collect as many validation errors as you can in a single pass. However, if you want to stop execution after a specificrule has failed, you can set the last option to true:$validator = new Validator();$validator->add('body', ['minLength' => ['rule' => ['minLength', 10],(continues on next page)

828

Chapter 29. Validation

CakePHP Book, Release 3.10

(continued from previous page)'last' => true,'message' => 'Comments must have a substantial body.'],'maxLength' => ['rule' => ['maxLength', 250],'message' => 'Comments cannot be too long.']]);
If the minLength rule fails in the example above, the maxLength rule will not be run.

Adding Validation Providers
The Validator, ValidationSet and ValidationRule classes do not provide any validation methods themselves.
Validation rules come from ‘providers’. You can bind any number of providers to a Validator object. Validator instances
come with a ‘default’ provider setup automatically. The default provider is mapped to the Validation class. This
makes it simple to use the methods on that class as validation rules. When using Validators and the ORM together,
additional providers are configured for the table and entity objects. You can use the setProvider() method to add
any additional providers your application needs:$validator = new Validator();// Use an object instance.
$validator->setProvider('custom', $myObject);// Use a class name. Methods must be static.
$validator->setProvider('custom', 'App\Model\Validation');Validation providers can be objects, or class names. If a class name is used the methods must be static. To use a provider
other than ‘default’, be sure to set the provider key in your rule:// Use a rule from the table provider$validator->add('title', 'custom', ['rule' => 'customTableMethod','provider' => 'table']);
If you wish to add a provider to all Validator objects that are created in the future, you can use theaddDefaultProvider() method as follows:
use Cake\Validation\Validator;// Use an object instance.
Validator::addDefaultProvider('custom', $myObject);// Use a class name. Methods must be static.
Validator::addDefaultProvider('custom', 'App\Model\Validation');Note: DefaultProviders must be added before the Validator object is created therefore config/bootstrap.php is thebest place to set up your default providers.

Creating Validators

829

CakePHP Book, Release 3.10

New in version 3.5.0.
You can use the Localized plugin195 to get providers based on countries. With this plugin, you’ll be able to validate
model fields, depending on a country, ie:namespace App\Model\Table;
use Cake\ORM\Table;
use Cake\Validation\Validator;
class PostsTable extends Table{
public function validationDefault(Validator $validator){// add the provider to the validator$validator->setProvider('fr', 'Localized\Validation\FrValidation');// use the provider in a field validation rule$validator->add('phoneField', 'myCustomRuleNameForPhone', ['rule' => 'phone','provider' => 'fr']);
return $validator;}}
The localized plugin uses the two letter ISO code of the countries for validation, like en, fr, de.
There are a few methods that are common to all classes, defined through the ValidationInterface interface196 :phone() to check a phone number
postal() to check a postal code
personId() to check a country specific person ID

Nesting Validators
New in version 3.0.5.
When validating Modelless Forms with nested data, or when working with models that contain array data types, it isnecessary to validate the nested data you have. CakePHP makes it simple to add validators to specific attributes. For
example, assume you are working with a non-relational database and need to store an article and its comments:$data = ['title' => 'Best article','comments' => [['comment' => '']]];To validate the comments you would use a nested validator:
195 https://github.com/cakephp/localized
196 https://github.com/cakephp/localized/blob/master/src/Validation/ValidationInterface.php

830

Chapter 29. Validation

CakePHP Book, Release 3.10

$validator = new Validator();$validator->add('title', 'not-blank', ['rule' => 'notBlank']);$commentValidator = new Validator();$commentValidator->add('comment', 'not-blank', ['rule' => 'notBlank']);// Connect the nested validators.
$validator->addNestedMany('comments', $commentValidator);// Prior to 3.9 use $validator->errors()// Get all errors including those from nested validators.
$validator->validate($data);
You can create 1:1 ‘relationships’ with addNested() and 1:N ‘relationships’ with addNestedMany(). With bothmethods, the nested validator’s errors will contribute to the parent validator’s errors and influence the final result. Likeother validator features, nested validators support error messages and conditional application:$validator->addNestedMany('comments',$commentValidator,'Invalid comment','create');
The error message for a nested validator can be found in the _nested key.
New in version 3.6.0: message and conditions for nested validators were added.

Creating Reusable Validators
While defining validators inline where they are used makes for good example code, it doesn’t lead to maintainableapplications. Instead, you should create Validator sub-classes for your reusable validation logic:// In src/Model/Validation/ContactValidator.php
namespace App\Model\Validation;
use Cake\Validation\Validator;
class ContactValidator extends Validator{
public function __construct(){parent::__construct();// Add validation rules here.
}}

Creating Validators

831

CakePHP Book, Release 3.10

Validating Data
Now that you’ve created a validator and added the rules you want to it, you can start using it to validate data. Validators
are able to validate array data. For example, if you wanted to validate a contact form before creating and sending anemail you could do the following:
use Cake\Validation\Validator;$validator = new Validator();$validator->requirePresence('email')->add('email', 'validFormat', ['rule' => 'email','message' => 'E-mail must be valid'])->requirePresence('name')->notEmpty('name', 'We need your name.')->requirePresence('comment')->notEmpty('comment', 'You need to give a comment.');// Prior to 3.9 use $validator->errors()$errors = $validator->validate($this->request->getData());
if (empty($errors)) {// Send an email.
}The errors() method will return a non-empty array when there are validation failures. The returned array of errors
will be structured like:$errors = ['email' => ['E-mail must be valid']];
If you have multiple errors on a single field, an array of error messages will be returned per field. By default theerrors() method applies rules for the ‘create’ mode. If you’d like to apply ‘update’ rules you can do the following:// Prior to 3.9 use $validator->errors()$errors = $validator->validate($this->request->getData(), false);
if (empty($errors)) {// Send an email.
}Note: If you need to validate entities you should use methods like newEntity(), newEntities(), patchEntity(),
patchEntities() as they are designed for that.

832

Chapter 29. Validation

CakePHP Book, Release 3.10

Validating Entity Data
Validation is meant for checking request data coming from forms or other user interfaces used to populate the entities.
The request data is validated automatically when using the newEntity(), newEntities(), patchEntity() orpatchEntities() methods of Table class:// In the ArticlesController class$article = $this->Articles->newEntity($this->request->getData());
if ($article->errors()) {// Do work to show error messages.
}
Similarly, when you need to validate multiple entities at a time, you can use the newEntities() method:// In the ArticlesController class$entities = $this->Articles->newEntities($this->request->getData());
foreach ($entities as $entity) {if (!$entity->errors()) {$this->Articles->save($entity);}}
The newEntity(), patchEntity(), newEntities() and patchEntities() methods allow you to specify whichassociations are validated, and which validation sets to apply using the options parameter:$valid = $this->Articles->newEntity($article, ['associated' => ['Comments' => ['associated' => ['User'],'validate' => 'special',]]]);
Apart from validating user provided data maintaining integrity of data regardless where it came from is important. To
solve this problem CakePHP offers a second level of validation which is called “application rules”. You can read more
about them in the Applying Application Rules section.

Core Validation Rules
CakePHP provides a basic suite of validation methods in the Validation class. The Validation class contains a variety
of static methods that provide validators for several common validation situations.
The API documentation197 for the Validation class provides a good list of the validation rules that are available, andtheir basic usage.
Some of the validation methods accept additional parameters to define boundary conditions or valid options. You canprovide these boundary conditions and options as follows:
197 https://api.cakephp.org/3.x/class-Cake.Validation.Validation.html

Validating Entity Data

833

CakePHP Book, Release 3.10

$validator = new Validator();$validator->add('title', 'minLength', ['rule' => ['minLength', 10]])->add('rating', 'validValue', ['rule' => ['range', 1, 5]]);
Core rules that take additional parameters should have an array for the rule key that contains the rule as the firstelement, and the additional parameters as the remaining parameters.

834

Chapter 29. Validation

CHAPTER 30

App Classclass Cake\Core\App
The App class is responsible for resource location and path management.

Finding Classes
static Cake\Core\App::classname($name, $type = '', $suffix = '')This method is used to resolve classnames throughout CakePHP. It resolves the short form names CakePHP uses andreturns the fully resolved classname:// Resolve a short classname with the namespace + suffix.
App::classname('Auth', 'Controller/Component', 'Component');// Returns Cake\Controller\Component\AuthComponent// Resolve a plugin name.
App::classname('DebugKit.Toolbar', 'Controller/Component', 'Component');// Returns DebugKit\Controller\Component\ToolbarComponent// Names with \ in them will be returned unaltered.
App::classname('App\Cache\ComboCache');// Returns App\Cache\ComboCache
When resolving classes, the App namespace will be tried, and if the class does not exist the Cake namespace will be
attempted. If both classnames do not exist, false will be returned.

835

CakePHP Book, Release 3.10

Finding Paths to Namespaces
static Cake\Core\App::path(string $package, string $plugin = null)
Used to get locations for paths based on conventions:// Get the path to Controller/ in your application
App::path('Controller');This can be done for all namespaces that are part of your application. You can also fetch paths for a plugin:// Returns the component paths in DebugKit
App::path('Component', 'DebugKit');
App::path() will only return the default path, and will not be able to provide any information about additional paths
the autoloader is configured for.
static Cake\Core\App::core(string $package)
Used for finding the path to a package inside CakePHP:// Get the path to Cache engines.
App::core('Cache/Engine');Locating Plugins
static Cake\Core\Plugin::path(string $plugin)
Plugins can be located with Plugin. Using Plugin::path('DebugKit'); for example, will give you the full path tothe DebugKit plugin:$path = Plugin::path('DebugKit');

Locating Themes
Since themes are plugins, you can use the methods above to get the path to a theme.

Loading Vendor Files
Ideally vendor files should be autoloaded with Composer, if you have vendor files that cannot be autoloaded or installedwith Composer you will need to use require to load them.
If you cannot install a library with Composer, it is best to install each library in a directory following Composer’s
convention of vendor/$author/$package. If you had a library called AcmeLib, you could install it into vendor/
Acme/AcmeLib. Assuming it did not use PSR-0 compatible classnames you could autoload the classes within it usingclassmap in your application’s composer.json:

836

Chapter 30. App ClassCakePHP Book, Release 3.10

"autoload": {"psr-4": {"App\\": "src/","App\\Test\\": "tests/"},"classmap": ["vendor/Acme/AcmeLib"]}
If your vendor library does not use classes, and instead provides functions, you can configure Composer to load thesefiles at the beginning of each request using the files autoloading strategy:"autoload": {"psr-4": {"App\\": "src/","App\\Test\\": "tests/"},"files": ["vendor/Acme/AcmeLib/functions.php"]}
After configuring the vendor libraries you will need to regenerate your application’s autoloader using:$ php composer.phar dump-autoload
If you happen to not be using Composer in your application, you will need to manually load all vendor libraries yourself.

Loading Vendor Files

837

CakePHP Book, Release 3.10

838

Chapter 30. App ClassCHAPTER 31

Collectionsclass Cake\Collection\Collection
The collection classes provide a set of tools to manipulate arrays or Traversable objects. If you have ever used
underscore.js, you have an idea of what you can expect from the collection classes.
Collection instances are immutable; modifying a collection will instead generate a new collection. This makes working
with collection objects more predictable as operations are side-effect free.

Quick Example
Collections can be created using an array or Traversable object. You’ll also interact with collections every time you
interact with the ORM in CakePHP. A simple use of a Collection would be:
use Cake\Collection\Collection;$items = ['a' => 1, 'b' => 2, 'c' => 3];$collection = new Collection($items);// Create a new collection containing elements// with a value greater than one.
$overOne = $collection->filter(function ($value, $key, $iterator) {return $value > 1;});
You can also use the collection() helper function instead of new Collection():$items = ['a' => 1, 'b' => 2, 'c' => 3];// These both make a Collection instance.
(continues on next page)839

CakePHP Book, Release 3.10

(continued from previous page)$collectionA = new Collection($items);$collectionB = collection($items);
The benefit of the helper method is that it is easier to chain off of than (new Collection($items)).
The CollectionTrait allows you to integrate collection-like features into any Traversable object you have in yourapplication as well.

List of Methods
appendbuffered
combinecountBy
extract
firstMatchinsertlistNested
max
nest
reduceshufflesortBytake
unfoldappendItem
chunkcompileeachfiltergroupBy
isEmptymap
medianprependrejectskip
stopWhenthroughzip

avg
chunkWithKeys
contains
every
first
indexBy
last
match
min
prependItem
samplesome
sumOftranspose

IteratingCake\Collection\Collection::each(callable $c)
Collections can be iterated and/or transformed into new collections with the each() and map() methods. The each()method will not create a new collection, but will allow you to modify any objects within the collection:$collection = new Collection($items);$collection = $collection->each(function ($value, $key) {echo "Element $key: $value";});
The return of each() will be the collection object. Each will iterate the collection immediately applying the callback
to each value in the collection.
Cake\Collection\Collection::map(callable $c)
The map() method will create a new collection based on the output of the callback being applied to each object in theoriginal collection:$items = ['a' => 1, 'b' => 2, 'c' => 3];$collection = new Collection($items);(continues on next page)

840

Chapter 31. Collections

CakePHP Book, Release 3.10

(continued from previous page)$new = $collection->map(function ($value, $key) {return $value * 2;});// $result contains [2, 4, 6];$result = $new->toList();// $result contains ['a' => 2, 'b' => 4, 'c' => 6];$result = $new->toArray();
The map() method will create a new iterator which lazily creates the resulting items when iterated.
Cake\Collection\Collection::extract($matcher)
One of the most common uses for a map() function is to extract a single column from a collection. If you are looking
to build a list of elements containing the values for a particular property, you can use the extract() method:$collection = new Collection($people);$names = $collection->extract('name');// $result contains ['mark', 'jose', 'barbara'];$result = $names->toList();As with many other functions in the collection class, you are allowed to specify a dot-separated path for extracting
columns. This example will return a collection containing the author names from a list of articles:$collection = new Collection($articles);$names = $collection->extract('author.name');// $result contains ['Maria', 'Stacy', 'Larry'];$result = $names->toList();Finally, if the property you are looking after cannot be expressed as a path, you can use a callback function to return it:$collection = new Collection($articles);$names = $collection->extract(function ($article) {return $article->author->name . ', ' . $article->author->last_name;});
Often, the properties you need to extract a common key present in multiple arrays or objects that are deeply nested
inside other structures. For those cases you can use the {*} matcher in the path key. This matcher is often helpful whenmatching HasMany and BelongsToMany association data:$data = [['name' => 'James','phone_numbers' => [['number' => 'number-1'],['number' => 'number-2'],['number' => 'number-3'],]],['name' => 'James',(continues on next page)

Iterating841

CakePHP Book, Release 3.10

(continued from previous page)'phone_numbers' => [['number' => 'number-4'],['number' => 'number-5'],]]];$numbers = (new Collection($data))->extract('phone_numbers.{*}.number');$numbers->toList();// Returns ['number-1', 'number-2', 'number-3', 'number-4', 'number-5']
This last example uses toList() unlike other examples, which is important when we’re getting results with possibly
duplicate keys. By using toList() we’ll be guaranteed to get all values even if there are duplicate keys.
Unlike Cake\Utility\Hash::extract() this method only supports the {*} wildcard. All other wildcard and attributes matchers are not supported.
Cake\Collection\Collection::combine($keyPath, $valuePath, $groupPath = null)Collections allow you to create a new collection made from keys and values in an existing collection. Both the key andvalue paths can be specified with dot notation paths:$items = [['id' => 1, 'name' => 'foo', 'parent' => 'a'],['id' => 2, 'name' => 'bar', 'parent' => 'b'],['id' => 3, 'name' => 'baz', 'parent' => 'a'],];$combined = (new Collection($items))->combine('id', 'name');// Result will look like this when converted to array[
1 => 'foo',
2 => 'bar',
3 => 'baz',];You can also optionally use a groupPath to group results based on a path:$combined = (new Collection($items))->combine('id', 'name', 'parent');// Result will look like this when converted to array['a' => [1 => 'foo', 3 => 'baz'],'b' => [2 => 'bar']];
Finally you can use closures to build keys/values/groups paths dynamically, for example when working with entities
and dates (converted to Cake/Time instances by the ORM) you may want to group results by date:$combined = (new Collection($entities))->combine('id',function ($entity) { return $entity; },function ($entity) { return $entity->date->toDateString(); });(continues on next page)

842

Chapter 31. Collections

CakePHP Book, Release 3.10

(continued from previous page)// Result will look like this when converted to array['date string like 2015-05-01' => ['entity1->id' => entity1, 'entity2->id' => entity2,
˓→ ..., 'entityN->id' => entityN]'date string like 2015-06-01' => ['entity1->id' => entity1, 'entity2->id' => entity2,
˓→ ..., 'entityN->id' => entityN]]
Cake\Collection\Collection::stopWhen(callable $c)
You can stop the iteration at any point using the stopWhen() method. Calling it in a collection will create a new one
that will stop yielding results if the passed callable returns true for one of the elements:$items = [10, 20, 50, 1, 2];$collection = new Collection($items);$new = $collection->stopWhen(function ($value, $key) {// Stop on the first value bigger than 30
return $value > 30;});// $result contains [10, 20];
$result = $new->toList();
Cake\Collection\Collection::unfold(callable $c)
Sometimes the internal items of a collection will contain arrays or iterators with more items. If you wish to flatten theinternal structure to iterate once over all elements you can use the unfold() method. It will create a new collectionthat will yield every single element nested in the collection:$items = [[1, 2, 3], [4, 5]];$collection = new Collection($items);$new = $collection->unfold();// $result contains [1, 2, 3, 4, 5];$result = $new->toList();When passing a callable to unfold() you can control what elements will be unfolded from each item in the originalcollection. This is useful for returning data from paginated services:$pages = [1, 2, 3, 4];$collection = new Collection($pages);$items = $collection->unfold(function ($page, $key) {// An imaginary web service that returns a page of results
return MyService::fetchPage($page)->toList();});$allPagesItems = $items->toList();If you are using PHP 5.5+, you can use the yield keyword inside unfold() to return as many elements for each itemin the collection as you may need:

Iterating843

CakePHP Book, Release 3.10

$oddNumbers = [1, 3, 5, 7];$collection = new Collection($oddNumbers);$new = $collection->unfold(function ($oddNumber) {yield $oddNumber;yield $oddNumber + 1;});// $result contains [1, 2, 3, 4, 5, 6, 7, 8];$result = $new->toList();
Cake\Collection\Collection::chunk($chunkSize)
When dealing with large amounts of items in a collection, it may make sense to process the elements in batches insteadof one by one. For splitting a collection into multiple arrays of a certain size, you can use the chunk() function:$items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];$collection = new Collection($items);$chunked = $collection->chunk(2);$chunked->toList(); // [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10], [11]]The chunk function is particularly useful when doing batch processing, for example with a database result:$collection = new Collection($articles);$collection->map(function ($article) {// Change a property in the article$article->property = 'changed';})->chunk(20)->each(function ($batch) {myBulkSave($batch); // This function will be called for each batch});
Cake\Collection\Collection::chunkWithKeys($chunkSize)
Much like chunk(), chunkWithKeys() allows you to slice up a collection into smaller batches but with keys preserved.
This is useful when chunking associative arrays:$collection = new Collection(['a' => 1,'b' => 2,'c' => 3,'d' => [4, 5]]);$chunked = $collection->chunkWithKeys(2)->toList();// Creates[['a' => 1, 'b' => 2],['c' => 3, 'd' => [4, 5]]]
New in version 3.4.0: chunkWithKeys() was added in 3.4.0

844

Chapter 31. Collections

CakePHP Book, Release 3.10

Filtering
Cake\Collection\Collection::filter(callable $c)
Collections make it easy to filter and create new collections based on the result of callback functions. You can use
filter() to create a new collection of elements matching a criteria callback:$collection = new Collection($people);$ladies = $collection->filter(function ($person, $key) {return $person->gender === 'female';});$guys = $collection->filter(function ($person, $key) {return $person->gender === 'male';});Cake\Collection\Collection::reject(callable $c)
The inverse of filter() is reject(). This method does a negative filter, removing elements that match the filter
function:$collection = new Collection($people);$ladies = $collection->reject(function ($person, $key) {return $person->gender === 'male';});Cake\Collection\Collection::every(callable $c)
You can do truth tests with filter functions. To see if every element in a collection matches a test you can use every():$collection = new Collection($people);$allYoungPeople = $collection->every(function ($person) {return $person->age < 21;});
Cake\Collection\Collection::some(callable $c)
You can see if the collection contains at least one element matching a filter function using the some() method:$collection = new Collection($people);$hasYoungPeople = $collection->some(function ($person) {return $person->age < 21;});
Cake\Collection\Collection::match(array $conditions)If you need to extract a new collection containing only the elements that contain a given set of properties, you should
use the match() method:$collection = new Collection($comments);$commentsFromMark = $collection->match(['user.name' => 'Mark']);Cake\Collection\Collection::firstMatch(array $conditions)
The property name can be a dot-separated path. You can traverse into nested entities and match the values they contain.
When you only need the first matching element from a collection, you can use firstMatch():

Filtering845

CakePHP Book, Release 3.10

$collection = new Collection($comments);$comment = $collection->firstMatch(['user.name' => 'Mark','active' => true]);
As you can see from the above, both match() and firstMatch() allow you to provide multiple conditions to match
on. In addition, the conditions can be for different paths, allowing you to express complex conditions to match against.

Aggregation
Cake\Collection\Collection::reduce(callable $c)
The counterpart of a map() operation is usually a reduce. This function will help you build a single result out of all
the elements in a collection:$totalPrice = $collection->reduce(function ($accumulated, $orderLine) {return $accumulated + $orderLine->price;}, 0);In the above example, $totalPrice will be the sum of all single prices contained in the collection. Note the second
argument for the reduce() function takes the initial value for the reduce operation you are performing:$allTags = $collection->reduce(function ($accumulated, $article) {return array_merge($accumulated, $article->tags);}, []);
Cake\Collection\Collection::min(string|callable $callback, $type = SORT_NUMERIC)To extract the minimum value for a collection based on a property, just use the min() function. This will return thefull element from the collection and not just the smallest value found:$collection = new Collection($people);$youngest = $collection->min('age');echo $youngest->name;
You are also able to express the property to compare by providing a path or a callback function:$collection = new Collection($people);$personYoungestChild = $collection->min(function ($person) {return $person->child->age;});$personWithYoungestDad = $collection->min('dad.age');Cake\Collection\Collection::max(string|callable $callback, $type = SORT_NUMERIC)The same can be applied to the max() function, which will return a single element from the collection having thehighest property value:

846

Chapter 31. Collections

CakePHP Book, Release 3.10

$collection = new Collection($people);$oldest = $collection->max('age');$personOldestChild = $collection->max(function ($person) {return $person->child->age;});$personWithOldestDad = $collection->max('dad.age');Cake\Collection\Collection::sumOf(string|callable $callback)Finally, the sumOf() method will return the sum of a property of all elements:$collection = new Collection($people);$sumOfAges = $collection->sumOf('age');$sumOfChildrenAges = $collection->sumOf(function ($person) {return $person->child->age;});$sumOfDadAges = $collection->sumOf('dad.age');Cake\Collection\Collection::avg($matcher = null)Calculate the average value of the elements in the collection. Optionally provide a matcher path, or function to extract
values to generate the average for:$items = [['invoice' => ['total' => 100]],['invoice' => ['total' => 200]],];// Average: 150$average = (new Collection($items))->avg('invoice.total');
New in version 3.5.0.
Cake\Collection\Collection::median($matcher = null)Calculate the median value of a set of elements. Optionally provide a matcher path, or function to extract values togenerate the median for:$items = [['invoice' => ['total' => 400]],['invoice' => ['total' => 500]],['invoice' => ['total' => 100]],['invoice' => ['total' => 333]],['invoice' => ['total' => 200]],];// Median: 333$median = (new Collection($items))->median('invoice.total');
New in version 3.5.0.

Aggregation

847

CakePHP Book, Release 3.10

Grouping and Counting
Cake\Collection\Collection::groupBy($callback)Collection values can be grouped by different keys in a new collection when they share the same value for a property:$students = [['name' => 'Mark', 'grade' => 9],['name' => 'Andrew', 'grade' => 10],['name' => 'Stacy', 'grade' => 10],['name' => 'Barbara', 'grade' => 9]];$collection = new Collection($students);$studentsByGrade = $collection->groupBy('grade');// Result will look like this when converted to array:[
10 => [['name' => 'Andrew', 'grade' => 10],['name' => 'Stacy', 'grade' => 10]],
9 => [['name' => 'Mark', 'grade' => 9],['name' => 'Barbara', 'grade' => 9]]]
As usual, it is possible to provide either a dot-separated path for nested properties or your own callback function to
generate the groups dynamically:$commentsByUserId = $comments->groupBy('user.id');$classResults = $students->groupBy(function ($student) {return $student->grade > 6 ? 'approved' : 'denied';});Cake\Collection\Collection::countBy($callback)If you only wish to know the number of occurrences per group, you can do so by using the countBy() method. It takes
the same arguments as groupBy so it should be already familiar to you:$classResults = $students->countBy(function ($student) {return $student->grade > 6 ? 'approved' : 'denied';});// Result could look like this when converted to array:['approved' => 70, 'denied' => 20]
Cake\Collection\Collection::indexBy($callback)
There will be certain cases where you know an element is unique for the property you want to group by. If you wish asingle result per group, you can use the function indexBy():$usersById = $users->indexBy('id');(continues on next page)

848

Chapter 31. Collections

CakePHP Book, Release 3.10

(continued from previous page)// When converted to array result could look like[
1 => 'markstory',
3 => 'jose_zap',
4 => 'jrbasso']
As with the groupBy() function you can also use a property path or a callback:$articlesByAuthorId = $articles->indexBy('author.id');$filesByHash = $files->indexBy(function ($file) {return md5($file);});
Cake\Collection\Collection::zip($elements)
The elements of different collections can be grouped together using the zip() method. It will return a new collection
containing an array grouping the elements from each collection that are placed at the same position:$odds = new Collection([1, 3, 5]);$pairs = new Collection([2, 4, 6]);$combined = $odds->zip($pairs)->toList(); // [[1, 2], [3, 4], [5, 6]]
You can also zip multiple collections at once:$years = new Collection([2013, 2014, 2015, 2016]);$salaries = [1000, 1500, 2000, 2300];$increments = [0, 500, 500, 300];$rows = $years->zip($salaries, $increments)->toList();// Returns:[[2013, 1000, 0],[2014, 1500, 500],[2015, 2000, 500],[2016, 2300, 300]]
As you can already see, the zip() method is very useful for transposing multidimensional arrays:$data = [2014 => ['jan' => 100, 'feb' => 200],
2015 => ['jan' => 300, 'feb' => 500],
2016 => ['jan' => 400, 'feb' => 600],]// Getting jan and feb data together$firstYear = new Collection(array_shift($data));$firstYear->zip($data[0], $data[1])->toList();// Or $firstYear->zip(...$data) in PHP >= 5.6(continues on next page)

Aggregation

849

CakePHP Book, Release 3.10

(continued from previous page)// Returns[[100, 300, 400],[200, 500, 600]]

SortingCake\Collection\Collection::sortBy($callback)Collection values can be sorted in ascending or descending order based on a column or custom function. To create a
new sorted collection out of the values of another one, you can use sortBy:$collection = new Collection($people);$sorted = $collection->sortBy('age');
As seen above, you can sort by passing the name of a column or property that is present in the collection values. You
are also able to specify a property path instead using the dot notation. The next example will sort articles by theirauthor’s name:$collection = new Collection($articles);$sorted = $collection->sortBy('author.name');The sortBy() method is flexible enough to let you specify an extractor function that will let you dynamically selectthe value to use for comparing two different values in the collection:$collection = new Collection($articles);$sorted = $collection->sortBy(function ($article) {return $article->author->name . '-' . $article->title;});
In order to specify in which direction the collection should be sorted, you need to provide either SORT_ASC or
SORT_DESC as the second parameter for sorting in ascending or descending direction respectively. By default, collections are sorted in descending direction:$collection = new Collection($people);$sorted = $collection->sortBy('age', SORT_ASC);
Sometimes you will need to specify which type of data you are trying to compare so that you get consistent results. For
this purpose, you should supply a third argument in the sortBy() function with one of the following constants:• SORT_NUMERIC: For comparing numbers• SORT_STRING: For comparing string values• SORT_NATURAL: For sorting string containing numbers and you’d like those numbers to be order in a naturalway. For example: showing “10” after “2”.
• SORT_LOCALE_STRING: For comparing strings based on the current locale.
By default, SORT_NUMERIC is used:

850

Chapter 31. Collections

CakePHP Book, Release 3.10

$collection = new Collection($articles);$sorted = $collection->sortBy('title', SORT_ASC, SORT_NATURAL);

Warning: It is often expensive to iterate sorted collections more than once. If you plan to do so, consider convertingthe collection to an array or simply use the compile() method on it.

Working with Tree Data
Cake\Collection\Collection::nest($idPath, $parentPath, $nestingKey = 'children')Not all data is meant to be represented in a linear way. Collections make it easier to construct and flatten hierarchicalor nested structures. Creating a nested structure where children are grouped by a parent identifier property is easy with
the nest() method.
Two parameters are required for this function. The first one is the property representing the item identifier. The second
parameter is the name of the property representing the identifier for the parent item:$collection = new Collection([['id' => 1, 'parent_id' => null, 'name' => 'Birds'],['id' => 2, 'parent_id' => 1, 'name' => 'Land Birds'],['id' => 3, 'parent_id' => 1, 'name' => 'Eagle'],['id' => 4, 'parent_id' => 1, 'name' => 'Seagull'],['id' => 5, 'parent_id' => 6, 'name' => 'Clown Fish'],['id' => 6, 'parent_id' => null, 'name' => 'Fish'],]);$collection->nest('id', 'parent_id')->toList();// Returns[['id' => 1,'parent_id' => null,'name' => 'Birds','children' => [['id' => 2, 'parent_id' => 1, 'name' => 'Land Birds', 'children' => []],['id' => 3, 'parent_id' => 1, 'name' => 'Eagle', 'children' => []],['id' => 4, 'parent_id' => 1, 'name' => 'Seagull', 'children' => []],]],[
'id' => 6,'parent_id' => null,'name' => 'Fish','children' => [['id' => 5, 'parent_id' => 6, 'name' => 'Clown Fish', 'children' => []],]]];
Children elements are nested inside the children property inside each of the items in the collection. This type of data
representation is helpful for rendering menus or traversing elements up to certain level in the tree.
Working with Tree Data

851

CakePHP Book, Release 3.10

Cake\Collection\Collection::listNested($dir = 'desc', $nestingKey = 'children')
The inverse of nest() is listNested(). This method allows you to flatten a tree structure back into a linear structure.
It takes two parameters; the first one is the traversing mode (asc, desc or leaves), and the second one is the name of theproperty containing the children for each element in the collection.
Taking the input the nested collection built in the previous example, we can flatten it:$nested->listNested()->toList();// Returns[['id' => 1, 'parent_id' => null, 'name' => 'Birds', 'children' => [...]],['id' => 2, 'parent_id' => 1, 'name' => 'Land Birds'],['id' => 3, 'parent_id' => 1, 'name' => 'Eagle'],['id' => 4, 'parent_id' => 1, 'name' => 'Seagull'],['id' => 6, 'parent_id' => null, 'name' => 'Fish', 'children' => [...]],['id' => 5, 'parent_id' => 6, 'name' => 'Clown Fish']]By default, the tree is traversed from the root to the leaves. You can also instruct it to only return the leaf elements inthe tree:$nested->listNested()->toList();// Returns[['id' => 3, 'parent_id' => 1, 'name' => 'Eagle'],['id' => 4, 'parent_id' => 1, 'name' => 'Seagull'],['id' => 5, 'parent_id' => 6, 'name' => 'Clown Fish']]Once you have converted a tree into a nested list, you can use the printer() method to configure how the list output
should be formatted:$nested->listNested()->printer('name', 'id', '--')->toArray();// Returns[
3 => 'Eagle',
4 => 'Seagull',
5 -> '--Clown Fish',]
The printer() method also lets you use a callback to generate the keys and or values:$nested->listNested()->printer(function ($el) {return $el->name;},function ($el) {return $el->id;
}
);

852

Chapter 31. Collections

CakePHP Book, Release 3.10

Other Methods
Cake\Collection\Collection::isEmpty()
Allows you to see if a collection contains any elements:$collection = new Collection([]);// Returns true$collection->isEmpty();$collection = new Collection([1]);// Returns false$collection->isEmpty();Cake\Collection\Collection::contains($value)
Collections allow you to quickly check if they contain one particular value: by using the contains() method:$items = ['a' => 1, 'b' => 2, 'c' => 3];$collection = new Collection($items);$hasThree = $collection->contains(3);Comparisons are performed using the === operator. If you wish to do looser comparison types you can use the some()
method.
Cake\Collection\Collection::shuffle()
Sometimes you may wish to show a collection of values in a random order. In order to create a new collection that will
return each value in a randomized position, use the shuffle:$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);// This could return [2, 3, 1]$collection->shuffle()->toList();
Cake\Collection\Collection::transpose()
When you transpose a collection, you get a new collection containing a row made of the each of the original columns:$items = [['Products', '2012', '2013', '2014'],['Product A', '200', '100', '50'],['Product B', '300', '200', '100'],['Product C', '400', '300', '200'],]$transpose = (new Collection($items))->transpose()->toList();// Returns[['Products', 'Product A', 'Product B', 'Product C'],['2012', '200', '300', '400'],['2013', '100', '200', '300'],['2014', '50', '100', '200'],]
New in version 3.3.0: Collection::transpose() was added in 3.3.0.
Other Methods853

CakePHP Book, Release 3.10

Withdrawing Elements
Cake\Collection\Collection::sample(int $size)
Shuffling a collection is often useful when doing quick statistical analysis. Another common operation when doing
this sort of task is withdrawing a few random values out of a collection so that more tests can be performed on those.
For example, if you wanted to select 5 random users to which you’d like to apply some A/B tests to, you can use thesample() function:$collection = new Collection($people);// Withdraw maximum 20 random users from this collection$testSubjects = $collection->sample(20);sample() will take at most the number of values you specify in the first argument. If there are not enough elements inthe collection to satisfy the sample, the full collection in a random order is returned.
Cake\Collection\Collection::take(int $size, int $from)
Whenever you want to take a slice of a collection use the take() function, it will create a new collection with at mostthe number of values you specify in the first argument, starting from the position passed in the second argument:$topFive = $collection->sortBy('age')->take(5);// Take 5 people from the collection starting from position 4$nextTopFive = $collection->sortBy('age')->take(5, 4);
Positions are zero-based, therefore the first position number is 0.
Cake\Collection\Collection::skip(int $positions)
While the second argument of take() can help you skip some elements before getting them from the collection, you
can also use skip() for the same purpose as a way to take the rest of the elements after a certain position:$collection = new Collection([1, 2, 3, 4]);
$allExceptFirstTwo = $collection->skip(2)->toList(); // [3, 4]
Cake\Collection\Collection::first()
One of the most common uses of take() is getting the first element in the collection. A shortcut method for achieving
the same goal is using the first() method:$collection = new Collection([5, 4, 3, 2]);$collection->first(); // Returns 5
Cake\Collection\Collection::last()
Similarly, you can get the last element of a collection using the last() method:$collection = new Collection([5, 4, 3, 2]);$collection->last(); // Returns 2

854

Chapter 31. Collections

CakePHP Book, Release 3.10

Expanding Collections
Cake\Collection\Collection::append(array|Traversable $items)
You can compose multiple collections into a single one. This enables you to gather data from various sources, concatenate it, and apply other collection functions to it very smoothly. The append() method will return a new collection
containing the values from both sources:$cakephpTweets = new Collection($tweets);$myTimeline = $cakephpTweets->append($phpTweets);// Tweets containing cakefest from both sources$myTimeline->filter(function ($tweet) {return strpos($tweet, 'cakefest');});
Cake\Collection\Collection::appendItem($value, $key)
Allows you to append an item with an optional key to the collection. If you specify a key that already exists in thecollection, the value will not be overwritten:$cakephpTweets = new Collection($tweets);$myTimeline = $cakephpTweets->appendItem($newTweet, 99);
New in version 3.6.0: appendItem() was added.
Cake\Collection\Collection::prepend(array|Traversable $items)
The prepend() method will return a new collection containing the values from both sources:$cakephpTweets = new Collection($tweets);$myTimeline = $cakephpTweets->prepend($phpTweets);
New in version 3.6.0: prepend() was added.
Cake\Collection\Collection::prependItem($value, $key)
Allows you to prepend an item with an optional key to the collection. If you specify a key that already exists in thecollection, the value will not be overwritten:$cakephpTweets = new Collection($tweets);$myTimeline = $cakephpTweets->prependItem($newTweet, 99);
New in version 3.6.0: prependItem() was added.
Warning: When appending from different sources, you can expect some keys from both collections to be thesame. For example, when appending two simple arrays. This can present a problem when converting a collection
to an array using toArray(). If you do not want values from one collection to override others in the previous one
based on their key, make sure that you call toList() in order to drop the keys and preserve all values.

Other Methods855

CakePHP Book, Release 3.10

Modifiying Elements
Cake\Collection\Collection::insert(string $path, array|Traversable $items)
At times, you may have two separate sets of data that you would like to insert the elements of one set into each of theelements of the other set. This is a very common case when you fetch data from a data source that does not support
data-merging or joins natively.
Collections offer an insert() method that will allow you to insert each of the elements in one collection into a property
inside each of the elements of another collection:$users = [['username' => 'mark'],['username' => 'juan'],['username' => 'jose']];$languages = [['PHP', 'Python', 'Ruby'],['Bash', 'PHP', 'Javascript'],['Javascript', 'Prolog']];$merged = (new Collection($users))->insert('skills', $languages);
When converted to an array, the $merged collection will look like this:[['username' => 'mark', 'skills' => ['PHP', 'Python', 'Ruby']],['username' => 'juan', 'skills' => ['Bash', 'PHP', 'Javascript']],['username' => 'jose', 'skills' => ['Javascript', 'Prolog']]];
The first parameter for the insert() method is a dot-separated path of properties to follow so that the elements canbe inserted at that position. The second argument is anything that can be converted to a collection object.
Please observe that elements are inserted by the position they are found, thus, the first element of the second collection
is merged into the first element of the first collection.
If there are not enough elements in the second collection to insert into the first one, then the target property will befilled with null values:$languages = [['PHP', 'Python', 'Ruby'],['Bash', 'PHP', 'Javascript']];$merged = (new Collection($users))->insert('skills', $languages);// Will yield[['username' => 'mark', 'skills' => ['PHP', 'Python', 'Ruby']],['username' => 'juan', 'skills' => ['Bash', 'PHP', 'Javascript']],['username' => 'jose', 'skills' => null]];

856

Chapter 31. Collections

CakePHP Book, Release 3.10

The insert() method can operate array elements or objects implementing the ArrayAccess interface.

Making Collection Methods Reusable
Using closures for collection methods is great when the work to be done is small and focused, but it can get messy
very quickly. This becomes more obvious when a lot of different methods need to be called or when the length of theclosure methods is more than just a few lines.
There are also cases when the logic used for the collection methods can be reused in multiple parts of your application.
It is recommended that you consider extracting complex collection logic to separate classes. For example, imagine alengthy closure like this one:$collection->map(function ($row, $key) {if (!empty($row['items'])) {$row['total'] = collection($row['items'])->sumOf('price');}if (!empty($row['total'])) {$row['tax_amount'] = $row['total'] * 0.25;}// More code here...
return $modifiedRow;});This can be refactored by creating another class:class TotalOrderCalculator{
public function __invoke($row, $key){
if (!empty($row['items'])) {$row['total'] = collection($row['items'])->sumOf('price');}if (!empty($row['total'])) {$row['tax_amount'] = $row['total'] * 0.25;}// More code here...
return $modifiedRow;}}// Use the logic in your map() call$collection->map(new TotalOrderCalculator)
Cake\Collection\Collection::through(callable $c)
Sometimes a chain of collection method calls can become reusable in other parts of your application, but only if they
are called in that specific order. In those cases you can use through() in combination with a class implementing

Other Methods857

CakePHP Book, Release 3.10__invoke to distribute your handy data processing calls:$collection->map(new ShippingCostCalculator)->map(new TotalOrderCalculator)->map(new GiftCardPriceReducer)->buffered()...
The above method calls can be extracted into a new class so they don’t need to be repeated every time:class FinalCheckOutRowProcessor{
public function __invoke($collection){
return $collection->map(new ShippingCostCalculator)->map(new TotalOrderCalculator)->map(new GiftCardPriceReducer)->buffered()...
}}// Now you can use the through() method to call all methods at once$collection->through(new FinalCheckOutRowProcessor);

Optimizing Collections
Cake\Collection\Collection::buffered()Collections often perform most operations that you create using its functions in a lazy way. This means that even though
you can call a function, it does not mean it is executed right away. This is true for a great deal of functions in this class.
Lazy evaluation allows you to save resources in situations where you don’t use all the values in a collection. You might
not use all the values when iteration stops early, or when an exception/failure case is reached early.
Additionally, lazy evaluation helps speed up some operations. Consider the following example:$collection = new Collection($oneMillionItems);$collection = $collection->map(function ($item) {return $item * 2;});$itemsToShow = $collection->take(30);
Had the collections not been lazy, we would have executed one million operations, even though we only wanted to show
30 elements out of it. Instead, our map operation was only applied to the 30 elements we used. We can also derive
benefits from this lazy evaluation for smaller collections when we do more than one operation on them. For example:
calling map() twice and then filter().
Lazy evaluation comes with its downside too. You could be doing the same operations more than once if you optimize
a collection prematurely. Consider this example:$ages = $collection->extract('age');(continues on next page)

858

Chapter 31. Collections

CakePHP Book, Release 3.10

(continued from previous page)$youngerThan30 = $ages->filter(function ($item) {return $item < 30;});$olderThan30 = $ages->filter(function ($item) {return $item > 30;});
If we iterate both youngerThan30 and olderThan30, the collection would unfortunately execute the extract()
operation twice. This is because collections are immutable and the lazy-extracting operation would be done for both
filters.
Luckily we can overcome this issue with a single function. If you plan to reuse the values from certain operations morethan once, you can compile the results into another collection using the buffered() function:$ages = $collection->extract('age')->buffered();$youngerThan30 = ...
$olderThan30 = ...
Now, when both collections are iterated, they will only call the extracting operation once.
New in version 3.5.0: Collections initialized with an array are no longer iterated lazily in order to improve performance.

Making Collections Rewindable
The buffered() method is also useful for converting non-rewindable iterators into collections that can be iterated
more than once:// In PHP 5.5+
public function results(){...
foreach ($transientElements as $e) {yield $e;}}$rewindable = (new Collection(results()))->buffered();Cloning Collections
Cake\Collection\Collection::compile(bool $preserveKeys = true)
Sometimes you need to get a clone of the elements from another collection. This is useful when you need to iterate
the same set from different places at the same time. In order to clone a collection out of another use the compile()
method:$ages = $collection->extract('age')->compile();foreach ($ages as $age) {foreach ($collection as $element) {echo h($element->name) . ' - ' . $age;(continues on next page)

Other Methods859

CakePHP Book, Release 3.10

(continued from previous page)

}
}

860

Chapter 31. Collections

CHAPTER 32

Folder & File

The Folder and File utilities are convenience classes to help you read from and write/append to files; list files within afolder and other common directory related tasks.

Basic Usage
Ensure the classes are loaded:
use Cake\Filesystem\Folder;use Cake\Filesystem\File;
Then we can setup a new folder instance:$dir = new Folder('/path/to/folder');and search for all .ctp files within that folder using regex:$files = $dir->find('.*\.ctp');
Now we can loop through the files and read from or write/append to the contents or simply delete the file:foreach ($files as $file) {$file = new File($dir->pwd() . DS . $file);$contents = $file->read();// $file->write('I am overwriting the contents of this file');// $file->append('I am adding to the bottom of this file.');// $file->delete(); // I am deleting this file
$file->close(); // Be sure to close the file when you're done}

861

CakePHP Book, Release 3.10

Folder API
class Cake\Filesystem\Folder(string $path = false, boolean $create = false, string|boolean $mode = false)// Create a new folder with 0755 permissions$dir = new Folder('/path/to/folder', true, 0755);
property Cake\Filesystem\Folder::$path
Path of the current folder. Folder::pwd() will return the same information.
property Cake\Filesystem\Folder::$sort
Whether or not the list results should be sorted by name.
property Cake\Filesystem\Folder::$mode
Mode to be used when creating folders. Defaults to 0755. Does nothing on Windows machines.
static Cake\Filesystem\Folder::addPathElement(string $path, string $element)
Returns $path with $element added, with correct slash in-between:$path = Folder::addPathElement('/a/path/for', 'testing');// $path equals /a/path/for/testing$element can also be an array:$path = Folder::addPathElement('/a/path/for', ['testing', 'another']);// $path equals /a/path/for/testing/anotherCake\Filesystem\Folder::cd($path)
Change directory to $path. Returns false on failure:$folder = new Folder('/foo');echo $folder->path; // Prints /foo
$folder->cd('/bar');echo $folder->path; // Prints /bar$false = $folder->cd('/non-existent-folder');Cake\Filesystem\Folder::chmod(string $path, integer $mode = false, boolean $recursive = true, array$exceptions = [])Change the mode on a directory structure recursively. This includes changing the mode on files as well:$dir = new Folder();$dir->chmod('/path/to/folder', 0755, true, ['skip_me.php']);Cake\Filesystem\Folder::copy(array|string $options = [])Recursively copy a directory. The only parameter $options can either be a path into copy to or an array of options:$folder1 = new Folder('/path/to/folder1');$folder1->copy('/path/to/folder2');// Will put folder1 and all its contents into folder2$folder = new Folder('/path/to/folder');$folder->copy(['to' => '/path/to/new/folder',(continues on next page)862

Chapter 32. Folder & FileCakePHP Book, Release 3.10

(continued from previous page)'from' => '/path/to/copy/from', // Will cause a cd() to occur'mode' => 0755,'skip' => ['skip-me.php', '.git'],'scheme' => Folder::SKIP // Skip directories/files that already exist.
]);
There are 3 supported schemes:• Folder::SKIP skip copying/moving files & directories that exist in the destination directory.
• Folder::MERGE merge the source/destination directories. Files in the source directory will replace files inthe target directory. Directory contents will be merged.
• Folder::OVERWRITE overwrite existing files & directories in the target directory with those in the source
directory. If both the target and destination contain the same subdirectory, the target directory’s contents
will be removed and replaced with the source’s.
static Cake\Filesystem\Folder::correctSlashFor(string $path)
Returns a correct set of slashes for given $path (’\’ for Windows paths and ‘/’ for other paths).
Cake\Filesystem\Folder::create(string $pathname, integer $mode = false)
Create a directory structure recursively. Can be used to create deep path structures like /foo/bar/baz/shoe/horn:$folder = new Folder();
if ($folder->create('foo' . DS . 'bar' . DS . 'baz' . DS . 'shoe' . DS . 'horn')) {// Successfully created the nested folders}
Cake\Filesystem\Folder::delete(string $path = null)
Recursively remove directories if the system allows:$folder = new Folder('foo');if ($folder->delete()) {// Successfully deleted foo and its nested folders}
Cake\Filesystem\Folder::dirsize()
Returns the size in bytes of this Folder and its contents.
Cake\Filesystem\Folder::errors()
Get the error from latest method.
Cake\Filesystem\Folder::find(string $regexpPattern = '.*', boolean $sort = false)
Returns an array of all matching files in the current directory:// Find all .png in your webroot/img/ folder and sort the results$dir = new Folder(WWW_ROOT . 'img');$files = $dir->find('.*\.png', true);
/*
Array
(
[0] => cake.icon.png[1] => test-error-icon.png[2] => test-fail-icon.png[3] => test-pass-icon.png(continues on next page)

Folder API

863

CakePHP Book, Release 3.10

(continued from previous page)[4] => test-skip-icon.png)*/

Note: The folder find and findRecursive methods will only find files. If you would like to get folders and files see
Folder::read() or Folder::tree()Cake\Filesystem\Folder::findRecursive(string $pattern = '.*', boolean $sort = false)
Returns an array of all matching files in and below the current directory:// Recursively find files beginning with test or index$dir = new Folder(WWW_ROOT);$files = $dir->findRecursive('(test|index).*');
/*
Array
(
[0] => /var/www/cake/webroot/index.php[1] => /var/www/cake/webroot/test.php[2] => /var/www/cake/webroot/img/test-skip-icon.png[3] => /var/www/cake/webroot/img/test-fail-icon.png[4] => /var/www/cake/webroot/img/test-error-icon.png[5] => /var/www/cake/webroot/img/test-pass-icon.png)*/
Cake\Filesystem\Folder::inCakePath(string $path = '')Returns true if the file is in a given CakePath.
Cake\Filesystem\Folder::inPath(string $path = '', boolean $reverse = false)
Returns true if the file is in the given path:$Folder = new Folder(WWW_ROOT);$result = $Folder->inPath(APP);// $result = false, /var/www/example/src/ is not in /var/www/example/webroot/$result = $Folder->inPath(WWW_ROOT . 'img' . DS, true);// $result = true, /var/www/example/webroot/img/ is in /var/www/example/webroot/
static Cake\Filesystem\Folder::isAbsolute(string $path)
Returns true if the given $path is an absolute path.
static Cake\Filesystem\Folder::isSlashTerm(string $path)
Returns true if given $path ends in a slash (i.e. is slash-terminated):$result = Folder::isSlashTerm('/my/test/path');// $result = false$result = Folder::isSlashTerm('/my/test/path/');// $result = true
static Cake\Filesystem\Folder::isWindowsPath(string $path)
Returns true if the given $path is a Windows path.

864

Chapter 32. Folder & FileCakePHP Book, Release 3.10

Cake\Filesystem\Folder::messages()
Get the messages from the latest method.
Cake\Filesystem\Folder::move(array $options)
Recursive directory move.
static Cake\Filesystem\Folder::normalizeFullPath(string $path)
Returns a path with slashes normalized for the operating system.
New in version 3.7.0.
Cake\Filesystem\Folder::pwd()
Return current path.
Cake\Filesystem\Folder::read(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath =false)
Returns an array of the contents of the current directory. The returned array holds two sub arrays: One of
directories and one of files:$dir = new Folder(WWW_ROOT);$files = $dir->read(true, ['files', 'index.php']);
/*
Array
(
[0] => Array // Folders([0] => css[1] => img[2] => js)[1] => Array // Files([0] => .htaccess[1] => favicon.ico[2] => test.php))*/
Cake\Filesystem\Folder::realpath(string $path)Get the real path (taking “..” and such into account).
static Cake\Filesystem\Folder::slashTerm(string $path)
Returns $path with added terminating slash (corrected for Windows or other OS).
Cake\Filesystem\Folder::tree(null|string $path = null, array|boolean $exceptions = true, null|string $type =null)
Returns an array of nested directories and files in each directory.

Folder API

865

CakePHP Book, Release 3.10

File API
class Cake\Filesystem\File(string $path, boolean $create = false, integer $mode = 755)// Create a new file with 0644 permissions$file = new File('/path/to/file.php', true, 0644);
property Cake\Filesystem\File::$Folder
The Folder object of the file.
property Cake\Filesystem\File::$name
The name of the file with the extension. Differs from File::name() which returns the name without the extension.
property Cake\Filesystem\File::$info
An array of file info. Use File::info() instead.
property Cake\Filesystem\File::$handle
Holds the file handler resource if the file is opened.
property Cake\Filesystem\File::$lock
Enable locking for file reading and writing.
property Cake\Filesystem\File::$path
The current file’s absolute path.
Cake\Filesystem\File::append(string $data, boolean $force = false)
Append the given data string to the current file.
Cake\Filesystem\File::close()
Closes the current file if it is opened.
Cake\Filesystem\File::copy(string $dest, boolean $overwrite = true)
Copy the file to the absolute path $dest.
Cake\Filesystem\File::create()
Creates the file.
Cake\Filesystem\File::delete()
Deletes the file.
Cake\Filesystem\File::executable()
Returns true if the file is executable.
Cake\Filesystem\File::exists()
Returns true if the file exists.
Cake\Filesystem\File::ext()
Returns the file extension.
Cake\Filesystem\File::Folder()Returns the current folder.
Cake\Filesystem\File::group()
Returns the file’s group, or false in case of an error.

866

Chapter 32. Folder & FileCakePHP Book, Release 3.10

Cake\Filesystem\File::info()
Returns the file info.
Cake\Filesystem\File::lastAccess()
Returns last access time.
Cake\Filesystem\File::lastChange()
Returns last modified time, or false in case of an error.
Cake\Filesystem\File::md5(integer|boolean $maxsize = 5)
Get the MD5 Checksum of file with previous check of filesize, or false in case of an error.
Cake\Filesystem\File::name()
Returns the file name without extension.
Cake\Filesystem\File::offset(integer|boolean $offset = false, integer $seek = 0)
Sets or gets the offset for the currently opened file.
Cake\Filesystem\File::open(string $mode = 'r', boolean $force = false)
Opens the current file with the given $mode.
Cake\Filesystem\File::owner()
Returns the file’s owner.
Cake\Filesystem\File::perms()
Returns the “chmod” (permissions) of the file.
static Cake\Filesystem\File::prepare(string $data, boolean $forceWindows = false)
Prepares a ascii string for writing. Converts line endings to the correct terminator for the current platform. For
Windows “\r\n” will be used, “\n” for all other platforms.
Cake\Filesystem\File::pwd()
Returns the full path of the file.
Cake\Filesystem\File::read(string $bytes = false, string $mode = 'rb', boolean $force = false)
Return the contents of the current file as a string or return false on failure.
Cake\Filesystem\File::readable()
Returns true if the file is readable.
Cake\Filesystem\File::safe(string $name = null, string $ext = null)
Makes filename safe for saving.
Cake\Filesystem\File::size()
Returns the filesize in bytes.
Cake\Filesystem\File::writable()
Returns true if the file is writable.
Cake\Filesystem\File::write(string $data, string $mode = 'w', boolean$force = false)
Write given data to the current file.
Cake\Filesystem\File::mime()
Get the file’s mimetype, returns false on failure.
Cake\Filesystem\File::replaceText($search, $replace)
Replaces text in a file. Returns false on failure and true on success.

File API867

CakePHP Book, Release 3.10

868

Chapter 32. Folder & FileCHAPTER 33

Hashclass Cake\Utility\Hash
Array management, if done right, can be a very powerful and useful tool for building smarter, more optimized code.
CakePHP offers a very useful set of static utilities in the Hash class that allow you to do just that.
CakePHP’s Hash class can be called from any model or controller in the same way Inflector is called. Example:
Hash::combine().

Hash Path Syntax
The path syntax described below is used by all the methods in Hash. Not all parts of the path syntax are available inall methods. A path expression is made of any number of tokens. Tokens are composed of two groups. Expressions,
are used to traverse the array data, while matchers are used to qualify elements. You apply matchers to expression
elements.

Expression Types
Expression

Definition

{n}
{s}
{*}
Foo

Represents a numeric key. Will match any string or numeric key.
Represents a string. Will match any string value including numeric string values.
Matches any value.
Matches keys with the exact same value.

All expression elements are supported by all methods. In addition to expression elements, you can use attribute matching with certain methods. They are extract(), combine(), format(), check(), map(), reduce(), apply(),sort(), insert(), remove() and nest().

869

CakePHP Book, Release 3.10

Attribute Matching Types
MatcherDefinition[id][id=2][id!=2][id>2][id>=2][id<2][id<=2][text=/.../]

Match elements with a given array key.
Match elements with id equal to 2.
Match elements with id not equal to 2.
Match elements with id greater than 2.
Match elements with id greater than or equal to 2.
Match elements with id less than 2
Match elements with id less than or equal to 2.
Match elements that have values matching the regular expression inside ....

static Cake\Utility\Hash::get(array|\ArrayAccess $data, $path, $default = null)get() is a simplified version of extract(), it only supports direct path expressions. Paths with {n}, {s}, {*}or matchers are not supported. Use get() when you want exactly one value out of an array. If a matching pathis not found the default value will be returned.
static Cake\Utility\Hash::extract(array|\ArrayAccess $data, $path)
Hash::extract() supports all expression, and matcher components of Hash Path Syntax. You can use extract
to retrieve data from arrays or object implementing ArrayAccess interface, along arbitrary paths quickly without
having to loop through the data structures. Instead you use path expressions to qualify which elements you want
returned// Common Usage:$users = [['id' => 1, 'name' => 'mark'],['id' => 2, 'name' => 'jane'],['id' => 3, 'name' => 'sally'],['id' => 4, 'name' => 'jose'],];$results = Hash::extract($users, '{n}.id');// $results equals:// [1,2,3,4];
static Cake\Utility\Hash::insert(array $data, $path, $values = null)
Inserts $values into an array as defined by $path:$a = ['pages' => ['name' => 'page']];$result = Hash::insert($a, 'files', ['name' => 'files']);// $result now looks like:[[pages] => [[name] => page]
[files] => [[name] => files]]
You can use paths using {n}, {s} and {*} to insert data into multiple points:

870

Chapter 33. Hash

CakePHP Book, Release 3.10

$users = Hash::insert($users, '{n}.new', 'value');
Attribute matchers work with insert() as well:$data = [0 => ['up' => true, 'Item' => ['id' => 1, 'title' => 'first']],1 => ['Item' => ['id' => 2, 'title' => 'second']],2 => ['Item' => ['id' => 3, 'title' => 'third']],3 => ['up' => true, 'Item' => ['id' => 4, 'title' => 'fourth']],4 => ['Item' => ['id' => 5, 'title' => 'fifth']],];$result = Hash::insert($data, '{n}[up].Item[id=4].new', 9);/* $result now looks like:[['up' => true, 'Item' => ['id' => 1, 'title' => 'first']],['Item' => ['id' => 2, 'title' => 'second']],['Item' => ['id' => 3, 'title' => 'third']],['up' => true, 'Item' => ['id' => 4, 'title' => 'fourth', 'new' => 9]],['Item' => ['id' => 5, 'title' => 'fifth']],]*/static Cake\Utility\Hash::remove(array $data, $path)
Removes all elements from an array that match $path.
$a = ['pages' => ['name' => 'page'],'files' => ['name' => 'files']];$result = Hash::remove($a, 'files');/* $result now looks like:[[pages] => [[name] => page]]*/
Using {n}, {s} and {*} will allow you to remove multiple values at once. You can also use attribute matcherswith remove():$data = [0 => ['clear' => true, 'Item' => ['id' => 1, 'title' => 'first']],1 => ['Item' => ['id' => 2, 'title' => 'second']],2 => ['Item' => ['id' => 3, 'title' => 'third']],3 => ['clear' => true, 'Item' => ['id' => 4, 'title' => 'fourth']],4 => ['Item' => ['id' => 5, 'title' => 'fifth']],];$result = Hash::remove($data, '{n}[clear].Item[id=4]');/* $result now looks like:[['clear' => true, 'Item' => ['id' => 1, 'title' => 'first']],(continues on next page)

Hash Path Syntax

871

CakePHP Book, Release 3.10

(continued from previous page)['Item' => ['id' => 2, 'title' => 'second']],['Item' => ['id' => 3, 'title' => 'third']],['clear' => true],['Item' => ['id' => 5, 'title' => 'fifth']],]*/static Cake\Utility\Hash::combine(array $data, $keyPath, $valuePath = null, $groupPath = null)
Creates an associative array using a $keyPath as the path to build its keys, and optionally $valuePath as pathto get the values. If $valuePath is not specified, or doesn’t match anything, values will be initialized to null.
You can optionally group the values by what is obtained when following the path specified in $groupPath.
$a = [['User' => ['id' => 2,'group_id' => 1,'Data' => ['user' => 'mariano.iglesias','name' => 'Mariano Iglesias']]],['User' => ['id' => 14,'group_id' => 2,'Data' => ['user' => 'phpnut','name' => 'Larry E. Masters'
]
]
],
];
$result = Hash::combine($a, '{n}.User.id');/* $result now looks like:[[2] =>[14] =>]*/$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data.user');/* $result now looks like:[[2] => 'mariano.iglesias'[14] => 'phpnut']*/$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data');(continues on next page)872

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)/* $result now looks like:[[2] => [[user] => mariano.iglesias[name] => Mariano Iglesias][14] => [[user] => phpnut[name] => Larry E. Masters]]*/$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data.name');/* $result now looks like:[[2] => Mariano Iglesias[14] => Larry E. Masters]*/$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data', '{n}.User.group_id');/* $result now looks like:[[1] => [[2] => [[user] => mariano.iglesias[name] => Mariano Iglesias]][2] => [[14] => [[user] => phpnut[name] => Larry E. Masters]]]*/$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data.name', '{n}.User.group_id
˓→');/* $result now looks like:[[1] => [[2] => Mariano Iglesias][2] => [[14] => Larry E. Masters]]*/(continues on next page)

Hash Path Syntax873

CakePHP Book, Release 3.10

(continued from previous page)// As of 3.9.0 $keyPath can be null
$result = Hash::combine($a, null, '{n}.User.Data.name');/* $result now looks like:[[0] => Mariano Iglesias[1] => Larry E. Masters]*/
You can provide arrays for both $keyPath and $valuePath. If you do this, the first value will be used as aformat string, for values extracted by the other paths:$result = Hash::combine($a,'{n}.User.id',['%s: %s', '{n}.User.Data.user', '{n}.User.Data.name'],'{n}.User.group_id');/* $result now looks like:[[1] => [[2] => mariano.iglesias: Mariano Iglesias][2] => [[14] => phpnut: Larry E. Masters]]*/$result = Hash::combine($a,['%s: %s', '{n}.User.Data.user', '{n}.User.Data.name'],'{n}.User.id');/* $result now looks like:[[mariano.iglesias: Mariano Iglesias] => 2
[phpnut: Larry E. Masters] => 14]*/
static Cake\Utility\Hash::format(array $data, array $paths, $format)
Returns a series of values extracted from an array, formatted with a format string:$data = [['Person' => ['first_name' => 'Nate','last_name' => 'Abele','city' => 'Boston','state' => 'MA','something' => '42'
(continues on next page)874

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)]],['Person' => ['first_name' => 'Larry','last_name' => 'Masters','city' => 'Boondock','state' => 'TN','something' => '{0}']],['Person' => ['first_name' => 'Garrett','last_name' => 'Woodworth','city' => 'Venice Beach','state' => 'CA','something' => '{1}']]];$res = Hash::format($data, ['{n}.Person.first_name', '{n}.Person.something'], '%2$d,
˓→ %1$s');/*[[0] => 42, Nate[1] => 0, Larry[2] => 0, Garrett]*/$res = Hash::format($data, ['{n}.Person.first_name', '{n}.Person.something'], '%1$s,
˓→ %2$d');/*[[0] => Nate, 42[1] => Larry, 0[2] => Garrett, 0]*/static Cake\Utility\Hash::contains(array $data, array $needle)
Determines if one Hash or array contains the exact keys and values of another:$a = [
0 => ['name' => 'main'],
1 => ['name' => 'about']];$b = [
0 => ['name' => 'main'],
1 => ['name' => 'about'],(continues on next page)

Hash Path Syntax875

CakePHP Book, Release 3.10

(continued from previous page)2 => ['name' => 'contact'],'a' => 'b'];$result = Hash::contains($a, $a);// true$result = Hash::contains($a, $b);// false$result = Hash::contains($b, $a);// truestatic Cake\Utility\Hash::check(array $data, string $path = null)
Checks if a particular path is set in an array:$set = ['My Index 1' => ['First' => 'The first item']];$result = Hash::check($set, 'My Index 1.First');// $result == true
$result = Hash::check($set, 'My Index 1');// $result == true
$set = ['My Index 1' => ['First' => ['Second' => ['Third' => ['Fourth' => 'Heavy. Nesting.'
]
]
]
]
];
$result = Hash::check($set, 'My Index 1.First.Second');// $result == true
$result = Hash::check($set, 'My Index 1.First.Second.Third');// $result == true
$result = Hash::check($set, 'My Index 1.First.Second.Third.Fourth');// $result == true
$result = Hash::check($set, 'My Index 1.First.Seconds.Third.Fourth');// $result == false
static Cake\Utility\Hash::filter(array $data, $callback = ['Hash', 'filter'])
Filters empty elements out of array, excluding ‘0’. You can also supply a custom $callback to filter the arrayelements. You callback should return false to remove elements from the resulting array:$data = ['0',(continues on next page)876

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)

false,
true,
0,['one thing', 'I can tell you', 'is you got to be', false]];$res = Hash::filter($data);/* $res now looks like:[[0] => 0[2] => true[3] => 0[4] => [[0] => one thing[1] => I can tell you[2] => is you got to be]]*/static Cake\Utility\Hash::flatten(array $data, string $separator = '.')
Collapses a multi-dimensional array into a single dimension:$arr = [['Post' => ['id' => '1', 'title' => 'First Post'],'Author' => ['id' => '1', 'user' => 'Kyle'],],['Post' => ['id' => '2', 'title' => 'Second Post'],'Author' => ['id' => '3', 'user' => 'Crystal'],],];$res = Hash::flatten($arr);/* $res now looks like:[[0.Post.id] => 1
[0.Post.title] => First Post
[0.Author.id] => 1
[0.Author.user] => Kyle
[1.Post.id] => 2
[1.Post.title] => Second Post
[1.Author.id] => 3
[1.Author.user] => Crystal]*/
static Cake\Utility\Hash::expand(array $data, string $separator = '.')
Expands an array that was previously flattened with Hash::flatten():$data = ['0.Post.id' => 1,(continues on next page)

Hash Path Syntax877

CakePHP Book, Release 3.10

(continued from previous page)'0.Post.title' => First Post,'0.Author.id' => 1,'0.Author.user' => Kyle,'1.Post.id' => 2,'1.Post.title' => Second Post,'1.Author.id' => 3,'1.Author.user' => Crystal,];$res = Hash::expand($data);/* $res now looks like:[['Post' => ['id' => '1', 'title' => 'First Post'],'Author' => ['id' => '1', 'user' => 'Kyle'],],['Post' => ['id' => '2', 'title' => 'Second Post'],'Author' => ['id' => '3', 'user' => 'Crystal'],],];*/static Cake\Utility\Hash::merge(array $data, array $merge[, array $n ])This function can be thought of as a hybrid between PHP’s array_merge and array_merge_recursive. The
difference to the two is that if an array key contains another array then the function behaves recursive (unlike
array_merge) but does not do if for keys containing strings (unlike array_merge_recursive).
Note: This function will work with an unlimited amount of arguments and typecasts non-array parameters into
arrays.
$array = [['id' => '48c2570e-dfa8-4c32-a35e-0d71cbdd56cb','name' => 'mysql raleigh-workshop-08 < 2008-09-05.sql ','description' => 'Importing an sql dump'],['id' => '48c257a8-cf7c-4af2-ac2f-114ecbdd56cb','name' => 'pbpaste | grep -i Unpaid | pbcopy','description' => 'Remove all lines that say "Unpaid".',]];$arrayB = 4;
$arrayC = [0 => "test array", "cats" => "dogs", "people" => 1267];$arrayD = ["cats" => "felines", "dog" => "angry"];$res = Hash::merge($array, $arrayB, $arrayC, $arrayD);/* $res now looks like:[[0] => [(continues on next page)

878

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)[id] => 48c2570e-dfa8-4c32-a35e-0d71cbdd56cb[name] => mysql raleigh-workshop-08 < 2008-09-05.sql[description] => Importing an sql dump]
[1] => [[id] => 48c257a8-cf7c-4af2-ac2f-114ecbdd56cb[name] => pbpaste | grep -i Unpaid | pbcopy[description] => Remove all lines that say "Unpaid".
][2] => 4[3] => test array[cats] => felines[people] => 1267
[dog] => angry]*/
static Cake\Utility\Hash::numeric(array $data)
Checks to see if all the values in the array are numeric:$data = ['one'];$res = Hash::numeric(array_keys($data));// $res is true
$data = [1 => 'one'];$res = Hash::numeric($data);// $res is false
static Cake\Utility\Hash::dimensions(array $data)
Counts the dimensions of an array. This method will only consider the dimension of the first element in the array:$data = ['one', '2', 'three'];$result = Hash::dimensions($data);// $result == 1
$data = ['1' => '1.1', '2', '3'];$result = Hash::dimensions($data);// $result == 1
$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => '3.1.1']];$result = Hash::dimensions($data);// $result == 2$data = ['1' => '1.1', '2', '3' => ['3.1' => '3.1.1']];$result = Hash::dimensions($data);// $result == 1
$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => ['3.1.1' => '3.1.1.1']]];$result = Hash::dimensions($data);// $result == 2
static Cake\Utility\Hash::maxDimensions(array $data)
Similar to dimensions(), however this method returns, the deepest number of dimensions of any element inHash Path Syntax879

CakePHP Book, Release 3.10

the array:$data = ['1' => '1.1', '2', '3' => ['3.1' => '3.1.1']];$result = Hash::maxDimensions($data);// $result == 2$data = ['1' => ['1.1' => '1.1.1'], '2', '3' => ['3.1' => ['3.1.1' => '3.1.1.1']]];$result = Hash::maxDimensions($data);// $result == 3
static Cake\Utility\Hash::map(array $data, $path, $function)
Creates a new array, by extracting $path, and mapping $function across the results. You can use both expression and matching elements with this method:// Call the noop function $this->noop() on every element of $data$result = Hash::map($data, "{n}", [$this, 'noop']);public function noop(array $array){// Do stuff to array and return the result
return $array;}static Cake\Utility\Hash::reduce(array $data, $path, $function)
Creates a single value, by extracting $path, and reducing the extracted results with $function. You can use
both expression and matching elements with this method.
static Cake\Utility\Hash::apply(array $data, $path, $function)
Apply a callback to a set of extracted values using $function. The function will get the extracted values as thefirst argument:$data = [['date' => '01-01-2016', 'booked' => true],['date' => '01-01-2016', 'booked' => false],['date' => '02-01-2016', 'booked' => true]];$result = Hash::apply($data, '{n}[booked=true].date', 'array_count_values');/* $result now looks like:['01-01-2016' => 1,'02-01-2016' => 1,]*/
static Cake\Utility\Hash::sort(array $data, $path, $dir, $type = 'regular')
Sorts an array by any value, determined by a Hash Path Syntax Only expression elements are supported by thismethod:$a = [
0 => ['Person' => ['name' => 'Jeff']],
1 => ['Shirt' => ['color' => 'black']]];$result = Hash::sort($a, '{n}.Person.name', 'asc');/* $result now looks like:(continues on next page)

880

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)[[0] => [[Shirt] => [[color] => black]][1] => [[Person] => [[name] => Jeff]]]*/
$dir can be either asc or desc. $type can be one of the following values:• regular for regular sorting.
• numeric for sorting values as their numeric equivalents.
• string for sorting values as their string value.
• natural for sorting values in a human friendly way. Will sort foo10 below foo2 as an example.
static Cake\Utility\Hash::diff(array $data, array $compare)Computes the difference between two arrays:$a = [
0 => ['name' => 'main'],
1 => ['name' => 'about']];$b = [
0 => ['name' => 'main'],
1 => ['name' => 'about'],
2 => ['name' => 'contact']];$result = Hash::diff($a, $b);/* $result now looks like:[[2] => [[name] => contact]]*/
static Cake\Utility\Hash::mergeDiff(array $data, array $compare)This function merges two arrays and pushes the differences in data to the bottom of the resultant array.
Example 1$array1 = ['ModelOne' => ['id' => 1001, 'field_one' => 'a1.m1.f1', 'field_two' =>˓→'a1.m1.f2']];$array2 = ['ModelOne' => ['id' => 1003, 'field_one' => 'a3.m1.f1', 'field_two' =>˓→'a3.m1.f2', 'field_three' => 'a3.m1.f3']];(continues on next page)

Hash Path Syntax

881

CakePHP Book, Release 3.10

(continued from previous page)$res = Hash::mergeDiff($array1, $array2);/* $res now looks like:[[ModelOne] => [[id] => 1001
[field_one] => a1.m1.f1[field_two] => a1.m1.f2[field_three] => a3.m1.f3]]*/
Example 2$array1 = ["a" => "b", 1 => 20938, "c" => "string"];$array2 = ["b" => "b", 3 => 238, "c" => "string", ["extra_field"]];$res = Hash::mergeDiff($array1, $array2);/* $res now looks like:[[a] => b[1] => 20938[c] => string[b] => b[3] => 238[4] => [[0] => extra_field]]*/static Cake\Utility\Hash::normalize(array $data, $assoc = true)
Normalizes an array. If $assoc is true, the resulting array will be normalized to be an associative array. Numeric keys with values, will be converted to string keys with null values. Normalizing an array, makes using theresults with Hash::merge() easier:$a = ['Tree', 'CounterCache','Upload' => ['folder' => 'products','fields' => ['image_1_id', 'image_2_id']]];$result = Hash::normalize($a);/* $result now looks like:[[Tree] => null[CounterCache] => null
[Upload] => [[folder] => products[fields] => [[0] => image_1_id[1] => image_2_id(continues on next page)882

Chapter 33. Hash

CakePHP Book, Release 3.10

(continued from previous page)

]
]
]
*/
$b = ['Cacheable' => ['enabled' => false],'Limit','Bindable','Validator','Transactional'];$result = Hash::normalize($b);/* $result now looks like:[[Cacheable] => [[enabled] => false][Limit] => null
[Bindable] => null[Validator] => null[Transactional] => null]*/static Cake\Utility\Hash::nest(array $data, array $options = [])Takes a flat array set, and creates a nested, or threaded data structure.
Options:• children The key name to use in the result set for children. Defaults to ‘children’.
• idPath The path to a key that identifies each entry. Should be compatible with Hash::extract(). Defaults to {n}.$alias.id• parentPath The path to a key that identifies the parent of each entry. Should be compatible with
Hash::extract(). Defaults to {n}.$alias.parent_id• root The id of the desired top-most result.
For example, if you had the following array of data:$data = [['ThreadPost' => ['id' => 1, 'parent_id' => null]],['ThreadPost' => ['id' => 2, 'parent_id' => 1]],['ThreadPost' => ['id' => 3, 'parent_id' => 1]],['ThreadPost' => ['id' => 4, 'parent_id' => 1]],['ThreadPost' => ['id' => 5, 'parent_id' => 1]],['ThreadPost' => ['id' => 6, 'parent_id' => null]],['ThreadPost' => ['id' => 7, 'parent_id' => 6]],['ThreadPost' => ['id' => 8, 'parent_id' => 6]],['ThreadPost' => ['id' => 9, 'parent_id' => 6]],['ThreadPost' => ['id' => 10, 'parent_id' => 6]]];(continues on next page)

Hash Path Syntax883

CakePHP Book, Release 3.10

(continued from previous page)$result = Hash::nest($data, ['root' => 6]);/* $result now looks like:[(int) 0 => ['ThreadPost' => ['id' => (int) 6,'parent_id' => null],'children' => [(int) 0 => ['ThreadPost' => ['id' => (int) 7,'parent_id' => (int) 6],'children' => []],(int) 1 => ['ThreadPost' => ['id' => (int) 8,'parent_id' => (int) 6],'children' => []],(int) 2 => ['ThreadPost' => ['id' => (int) 9,'parent_id' => (int) 6],'children' => []],(int) 3 => ['ThreadPost' => ['id' => (int) 10,'parent_id' => (int) 6],'children' => []
]
]
]
]
*/

884

Chapter 33. Hash

CHAPTER 34

Http Clientclass Cake\Http\Client(mixed $config = [])CakePHP includes a basic but powerful HTTP client which can be used for making requests. It is a great way tocommunicate with webservices, and remote APIs.
Changed in version 3.3.0: Prior to 3.3.0 you should use Cake\Network\Http\Client.

Doing Requests
Doing requests is simple and straight forward. Doing a GET request looks like:use Cake\Http\Client;$http = new Client();// Simple get$response = $http->get('http://example.com/test.html');// Simple get with querystring$response = $http->get('http://example.com/search', ['q' => 'widget']);// Simple get with querystring & additional headers$response = $http->get('http://example.com/search', ['q' => 'widget'], ['headers' => ['X-Requested-With' => 'XMLHttpRequest']]);
Doing POST and PUT requests is equally simple:

885

CakePHP Book, Release 3.10// Send a POST request with application/x-www-form-urlencoded encoded data
$http = new Client();$response = $http->post('http://example.com/posts/add', ['title' => 'testing','body' => 'content in the post']);// Send a PUT request with application/x-www-form-urlencoded encoded data
$response = $http->put('http://example.com/posts/add', ['title' => 'testing','body' => 'content in the post']);// Other methods as well.
$http->delete(...);$http->head(...);$http->patch(...);Creating Multipart Requests with Files
You can include files in request bodies by including a filehandle in the array:$http = new Client();$response = $http->post('http://example.com/api', ['image' => fopen('/path/to/a/file', 'r'),]);
The filehandle will be read until its end; it will not be rewound before being read.
Warning: For compatibility reasons, earlier versions of CakePHP will treat strings beginning with @ as local or
remote file paths. This functionality was deprecated in CakePHP 3.0.5 and was removed in 3.7.

Building Multipart Request Bodies by Hand
There may be times when you need to build a request body in a very specific way. In these situations you can often use
Cake\Http\Client\FormData to craft the specific multipart HTTP request you want:
use Cake\Http\Client\FormData;$data = new FormData();// Create an XML part$xml = $data->newPart('xml', $xmlString);// Set the content type.
$xml->type('application/xml');$data->add($xml);// Create a file upload with addFile()// This will append the file to the form data as well.
(continues on next page)

886

Chapter 34. Http ClientCakePHP Book, Release 3.10

(continued from previous page)$file = $data->addFile('upload', fopen('/some/file.txt', 'r'));$file->contentId('abc123');$file->disposition('attachment');// Send the request.
$response = $http->post('http://example.com/api',(string)$data,['headers' => ['Content-Type' => $data->contentType()]]);

Sending Request Bodies
When dealing with REST APIs you often need to send request bodies that are not form encoded. Http\Client exposes
this through the type option:// Send a JSON request body.
$http = new Client();$response = $http->post('http://example.com/tasks',
json_encode($data),['type' => 'json']);
The type key can either be a one of ‘json’, ‘xml’ or a full mime type. When using the type option, you should provide
the data as a string. If you’re doing a GET request that needs both querystring parameters and a request body you cando the following:// Send a JSON body in a GET request with query string parameters.
$http = new Client();$response = $http->get('http://example.com/tasks',['q' => 'test', '_content' => json_encode($data)],['type' => 'json']);Request Method Options
Each HTTP method takes an $options parameter which is used to provide addition request information. The following
keys can be used in $options:• headers - Array of additional headers• cookie - Array of cookies to use.
• proxy - Array of proxy information.
• auth - Array of authentication data, the type key is used to delegate to an authentication strategy. By default
Basic auth is used.
• ssl_verify_peer - defaults to true. Set to false to disable SSL certification verification (not recommended).

Sending Request Bodies

887

CakePHP Book, Release 3.10

• ssl_verify_peer_name - defaults to true. Set to false to disable host name verification when verifying SSL
certificates (not recommended).
• ssl_verify_depth - defaults to 5. Depth to traverse in the CA chain.
• ssl_verify_host - defaults to true. Validate the SSL certificate against the host name.
• ssl_cafile - defaults to built in cafile. Overwrite to use custom CA bundles.
• timeout - Duration to wait before timing out in seconds.
• type - Send a request body in a custom content type. Requires $data to either be a string, or the _content
option to be set when doing GET requests.
• redirect - Number of redirects to follow. Defaults to false.
The options parameter is always the 3rd parameter in each of the HTTP methods. They can also be used when constructing Client to create scoped clients.

Authentication
Cake\Http\Client supports a few different authentication systems. Different authentication strategies can be added
by developers. Auth strategies are called before the request is sent, and allow headers to be added to the request context.

Using Basic Authentication
An example of basic authentication:$http = new Client();$response = $http->get('http://example.com/profile/1', [], ['auth' => ['username' => 'mark', 'password' => 'secret']]);
By default Cake\Http\Client will use basic authentication if there is no 'type' key in the auth option.

Using Digest Authentication
An example of basic authentication:$http = new Client();$response = $http->get('http://example.com/profile/1', [], ['auth' => ['type' => 'digest','username' => 'mark','password' => 'secret','realm' => 'myrealm','nonce' => 'onetimevalue','qop' => 1,'opaque' => 'someval']]);
By setting the ‘type’ key to ‘digest’, you tell the authentication subsystem to use digest authentication.

888

Chapter 34. Http ClientCakePHP Book, Release 3.10

OAuth 1 Authentication
Many modern web-services require OAuth authentication to access their APIs. The included OAuth authentication
assumes that you already have your consumer key and consumer secret:$http = new Client();$response = $http->get('http://example.com/profile/1', [], ['auth' => ['type' => 'oauth','consumerKey' => 'bigkey','consumerSecret' => 'secret','token' => '...','tokenSecret' => '...','realm' => 'tickets',]]);

OAuth 2 Authentication
Because OAuth2 is often a single header, there is not a specialized authentication adapter. Instead you can create aclient with the access token:$http = new Client(['headers' => ['Authorization' => 'Bearer ' . $accessToken]]);$response = $http->get('https://example.com/api/profile/1');

Proxy Authentication
Some proxies require authentication to use them. Generally this authentication is Basic, but it can be implemented byany authentication adapter. By default Http\Client will assume Basic authentication, unless the type key is set:$http = new Client();$response = $http->get('http://example.com/test.php', [], ['proxy' => ['username' => 'mark','password' => 'testing','proxy' => '127.0.0.1:8080',]]);
The second proxy parameter must be a string with an IP or a domain without protocol. The username andpassword information will be passed through the request headers, while the proxy string will be passed throughstream_context_create()198 .
198 https://php.net/manual/en/function.stream-context-create.php

Authentication889

CakePHP Book, Release 3.10

Creating Scoped Clients
Having to re-type the domain name, authentication and proxy settings can become tedious & error prone. To reducethe chance for mistake and relieve some of the tedium, you can create scoped clients:// Create a scoped client.
$http = new Client(['host' => 'api.example.com','scheme' => 'https','auth' => ['username' => 'mark', 'password' => 'testing']]);// Do a request to api.example.com$response = $http->get('/test.php');
The following information can be used when creating a scoped client:• host• scheme• proxy• auth• port• cookies• timeout• ssl_verify_peer• ssl_verify_depth• ssl_verify_host
Any of these options can be overridden by specifying them when doing requests. host, scheme, proxy, port are overridden in the request URL:// Using the scoped client we created earlier.
$response = $http->get('http://foo.com/test.php');
The above will replace the domain, scheme, and port. However, this request will continue using all the other options defined when the scoped client was created. See Request Method Options for more information on the options
supported.

Setting and Managing Cookies
Http\Client can also accept cookies when making requests. In addition to accepting cookies, it will also automaticallystore valid cookies set in responses. Any response with cookies, will have them stored in the originating instance of
Http\Client. The cookies stored in a Client instance are automatically included in future requests to domain + path
combinations that match:$http = new Client(['host' => 'cakephp.org']);(continues on next page)

890

Chapter 34. Http ClientCakePHP Book, Release 3.10

(continued from previous page)// Do a request that sets some cookies$response = $http->get('/');// Cookies from the first request will be included// by default.
$response2 = $http->get('/changelogs');
You can always override the auto-included cookies by setting them in the request’s $options parameters:// Replace a stored cookie with a custom value.
$response = $http->get('/changelogs', [], ['cookies' => ['sessionid' => '123abc']]);
You can add cookie objects to the client after creating it using the addCookie() method:use Cake\Http\Cookie\Cookie;$http = new Client(['host' => 'cakephp.org']);$http->addCookie(new Cookie('session', 'abc123'));New in version 3.5.0: addCookie() was added in 3.5.0

Response Objects
class Cake\Http\Client\Response
Response objects have a number of methods for inspecting the response data.
Changed in version 3.3.0: As of 3.3.0 Cake\Http\Client\Response implements the PSR-7 ResponseInterface199 .

Reading Response Bodies
You read the entire response body as a string:// Read the entire response as a string.
$response->getStringBody();// Prior to 3.7.0 use$response->body();// or$response->body;
You can also access the stream object for the response and use its methods:
199 https://www.php-fig.org/psr/psr-7/#3-3-psr-http-message-responseinterface

Response Objects

891

CakePHP Book, Release 3.10// Get a Psr\Http\Message\StreamInterface containing the response body$stream = $response->getBody();// Read a stream 100 bytes at a time.
while (!$stream->eof()) {echo $stream->read(100);}

Reading JSON and XML Response Bodies
Since JSON and XML responses are commonly used, response objects provide easy to use accessors to read decoded
data. JSON data is decoded into an array, while XML data is decoded into a SimpleXMLElement tree:// Get some XML$http = new Client();$response = $http->get('http://example.com/test.xml');$xml = $response->getXml();// Prior to 3.7.0$xml = $response->xml;// Get some JSON
$http = new Client();$response = $http->get('http://example.com/test.json');$json = $response->getJson();// Prior to 3.7.0$json = $response->json;
The decoded response data is stored in the response object, so accessing it multiple times has no additional cost.

Accessing Response Headers
You can access headers through a few different methods. Header names are always treated as case-insensitive values
when accessing them through methods:// Get all the headers as an associative array.
$response->getHeaders();// Get a single header as an array.
$response->getHeader('content-type');// Get a header as a string$response->getHeaderLine('content-type');// Get the response encoding$response->getEncoding();892

Chapter 34. Http ClientCakePHP Book, Release 3.10

Accessing Cookie Data
You can read cookies with a few different methods depending on how much data you need about the cookies:// Get all cookies (full data)$response->getCookies();// Get a single cookie's value.
$response->getCookie('session_id');// Get a the complete data for a single cookie// includes value, expires, path, httponly, secure keys.
$response->getCookieData('session_id');

Checking the Status CodeResponse objects provide a few methods for checking status codes:// Was the response a 20x$response->isOk();// Was the response a 30x$response->isRedirect();// Get the status code
$response->getStatusCode();Changing Transport Adapters
By default Http\Client will prefer using a curl based transport adapter. If the curl extension is not available a stream
based adapter will be used instead. You can force select a transport adapter using a constructor option:
use Cake\Http\Client\Adapter\Stream;$client = new Client(['adapter' => Stream::class]);

Changing Transport Adapters893

CakePHP Book, Release 3.10

894

Chapter 34. Http ClientCHAPTER 35

Inflector

class Cake\Utility\Inflector
The Inflector class takes a string and can manipulate it to handle word variations such as pluralizations or camelizing
and is normally accessed statically. Example: Inflector::pluralize('example') returns “examples”.
You can try out the inflections online at inflector.cakephp.org200 .

Summary of Inflector Methods and Their Output
Quick summary of the Inflector built-in methods and the results they output when provided a multi-word argument:
200 https://inflector.cakephp.org/

895

CakePHP Book, Release 3.10

MethodArgument

Outputpluralize()

BigApplebig_apple
BigApples
big_apples
big_apples
big apple
BigApples
Big Apples
big_apples
bigApplebig_apples
big apple
BigApples
big apple
BigApple
Big Apple
big_apple
big apples
Big Apple
BigApples

BigApples
big_apples
BigApplebig_apple
BigApples
BigApplebig_apples
big apples
Big Apples
BigApple
BigApple
BigApplebig-apples
big apple
big_apples
big apples
bigApple
bigApplesbig-apple
BigApples

singularize()camelize()
underscore()humanize()classify()
dasherize()
tableize()variable()slug()Creating Plural & Singular Forms
static Cake\Utility\Inflector::singularize($singular)
static Cake\Utility\Inflector::pluralize($singular)
Both pluralize and singularize() work on most English nouns. If you need to support other languages, you canuse Inflection Configuration to customize the rules used:// Applesecho Inflector::pluralize('Apple');Note: pluralize() may not always correctly convert a noun that is already in its plural form.
// Person
echo Inflector::singularize('People');Note: singularize() may not always correctly convert a noun that is already in its singular form.

896

Chapter 35. Inflector

CakePHP Book, Release 3.10

Creating CamelCase and under_scored Forms
static Cake\Utility\Inflector::camelize($underscored)
static Cake\Utility\Inflector::underscore($camelCase)
These methods are useful when creating class names, or property names:// ApplePie
Inflector::camelize('Apple_pie')// apple_pie
Inflector::underscore('ApplePie');
It should be noted that underscore will only convert camelCase formatted words. Words that contains spaces will belower-cased, but will not contain an underscore.

Creating Human Readable Forms
static Cake\Utility\Inflector::humanize($underscored)
This method is useful when converting underscored forms into “Title Case” forms for human readable values:// Apple PieInflector::humanize('apple_pie');

Creating Table and Class Name Forms
static Cake\Utility\Inflector::classify($underscored)
static Cake\Utility\Inflector::dasherize($dashed)static Cake\Utility\Inflector::tableize($camelCase)
When generating code, or using CakePHP’s conventions you may need to inflect table names or class names:// UserProfileSetting
Inflector::classify('user_profile_settings');// user-profile-setting
Inflector::dasherize('UserProfileSetting');// user_profile_settings
Inflector::tableize('UserProfileSetting');

Creating CamelCase and under_scored Forms

897

CakePHP Book, Release 3.10

Creating Variable Names
static Cake\Utility\Inflector::variable($underscored)
Variable names are often useful when doing meta-programming tasks that involve generating code or doing work basedon conventions:// applePie
Inflector::variable('apple_pie');

Creating URL Safe Strings
static Cake\Utility\Inflector::slug($word, $replacement = '-')
Slug converts special characters into latin versions and converting unmatched characters and spaces to dashes. The
slug method expects UTF-8 encoding:// apple-puree
Inflector::slug('apple purée');Note: Inflector::slug() has been deprecated since 3.2.7. Use Text::slug() instead.

Inflection Configuration
CakePHP’s naming conventions can be really nice - you can name your database table big_boxes, your model
BigBoxes, your controller BigBoxesController, and everything just works together automatically. The way
CakePHP knows how to tie things together is by inflecting the words between their singular and plural forms.
There are occasions (especially for our non-English speaking friends) where you may run into situations where
CakePHP’s inflector (the class that pluralizes, singularizes, camelCases, and under_scores) might not work as you’d
like. If CakePHP won’t recognize your Foci or Fish, you can tell CakePHP about your special cases.

Loading Custom Inflections
static Cake\Utility\Inflector::rules($type, $rules, $reset = false)
Define new inflection and transliteration rules for Inflector to use.
fig/bootstrap.php:

Often, this method is used in your con-Inflector::rules('singular', ['/^(bil)er$/i' => '\1', '/^(inflec|contribu)tors$/i' => '\˓→1ta']);
Inflector::rules('uninflected', ['singulars']);Inflector::rules('irregular', ['phylum' => 'phyla']); // The key is singular form, value␣˓→is plural form
The supplied rules will be merged into the respective inflection sets defined in Cake/Utility/Inflector, with theadded rules taking precedence over the core rules. You can use Inflector::reset() to clear rules and restore theoriginal Inflector state.
898

Chapter 35. Inflector

CHAPTER 36

Numberclass Cake\I18n\Number
If you need NumberHelper functionalities outside of a View, use the Number class:namespace App\Controller;
use Cake\I18n\Number;class UsersController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Auth');}public function afterLogin(){$storageUsed = $this->Auth->user('storage_used');if ($storageUsed > 5000000) {// Notify users of quota$this->Flash->success(__('You are using {0} storage', Number::toReadableSize(˓→$storageUsed)));}}}All of these functions return the formatted number; they do not automatically echo the output into the view.

899

CakePHP Book, Release 3.10

Formatting Currency Values
Cake\I18n\Number::currency(mixed $value, string $currency = null, array $options = [])This method is used to display a number in common currency formats (EUR, GBP, USD). Usage in a view looks like:// Called as NumberHelper
echo $this->Number->currency($value, $currency);// Called as Number
echo Number::currency($value, $currency);
The first parameter, $value, should be a floating point number that represents the amount of money you are expressing.
The second parameter is a string used to choose a predefined currency formatting scheme:$currency

1234.56, formatted by currency type

EUR
GBP
USD

€1.234,56£1,234.56$1,234.56

The third parameter is an array of options for further defining the output. The following options are available:
OptionDescription

beforeafter
zero
placesprecision
localefractionSymbol
fractionPosition
pattern
useIntlCode

Text to display before the rendered number.
Text to display after the rendered number.
The text to use for zero values; can be a string or a number. ie. 0, ‘Free!’.
Number of decimal places to use, ie. 2
Maximal number of decimal places to use, ie. 2
The locale name to use for formatting number, ie. “fr_FR”.
String to use for fraction numbers, ie. ‘ cents’.
Either ‘before’ or ‘after’ to place the fraction symbol.
An ICU number pattern to use for formatting the number ie. #,###.00
Set to true to replace the currency symbol with the international currency code.

If $currency value is null, the default currency will be retrieved from Cake\I18n\Number::defaultCurrency().
To format currencies in an accounting format you should set the currency format:
Number::setDefaultCurrencyFormat(Number::FORMAT_CURRENCY_ACCOUNTING);
New in version 3.9.0: Formatting currency as accounting values was added.

900

Chapter 36. NumberCakePHP Book, Release 3.10

Setting the Default Currency
Cake\I18n\Number::defaultCurrency($currency)
Setter/getter for the default currency. This removes the need to always pass the currency to Cake\I18n\
Number::currency() and change all currency outputs by setting other default. If $currency is set to false, itwill clear the currently stored value. By default, it will retrieve the intl.default_locale if set and ‘en_US’ if not.

Formatting Floating Point Numbers
Cake\I18n\Number::precision(float $value, int $precision = 3, array $options = [])This method displays a number with the specified amount of precision (decimal places). It will round in order tomaintain the level of precision defined.
// Called as NumberHelper
echo $this->Number->precision(456.91873645, 2);// Outputs
456.92// Called as Number
echo Number::precision(456.91873645, 2);

Formatting Percentages
Cake\I18n\Number::toPercentage(mixed $value, int $precision = 2, array $options = [])OptionDescription

multiply

Boolean to indicate whether the value has to be multiplied by 100. Useful for decimal percentages.

Like Cake\I18n\Number::precision(), this method formats a number according to the supplied precision (where
numbers are rounded to meet the given precision). This method also expresses the number as a percentage and appends
the output with a percent sign.
// Called as NumberHelper. Output: 45.69%
echo $this->Number->toPercentage(45.691873645);// Called as Number. Output: 45.69%
echo Number::toPercentage(45.691873645);// Called with multiply. Output: 45.7%
echo Number::toPercentage(0.45691, 1, ['multiply' => true]);

Setting the Default Currency901

CakePHP Book, Release 3.10

Interacting with Human Readable Values
Cake\I18n\Number::toReadableSize(string $size)
This method formats data sizes in human readable forms. It provides a shortcut way to convert bytes to KB, MB, GB,
and TB. The size is displayed with a two-digit precision level, according to the size of data supplied (i.e. higher sizes
are expressed in larger terms):// Called as NumberHelper
echo $this->Number->toReadableSize(0); // 0 Byteecho $this->Number->toReadableSize(1024); // 1 KB
echo $this->Number->toReadableSize(1321205.76); // 1.26 MB
echo $this->Number->toReadableSize(5368709120); // 5 GB// Called as Number
echo Number::toReadableSize(0); // 0 Byteecho Number::toReadableSize(1024); // 1 KB
echo Number::toReadableSize(1321205.76); // 1.26 MB
echo Number::toReadableSize(5368709120); // 5 GB

Formatting Numbers
Cake\I18n\Number::format(mixed $value, array $options = [])This method gives you much more control over the formatting of numbers for use in your views (and is used as themain method by most of the other NumberHelper methods). Using this method might looks like:// Called as NumberHelper$this->Number->format($value, $options);// Called as Number
Number::format($value, $options);
The $value parameter is the number that you are planning on formatting for output. With no $options supplied, thenumber 1236.334 would output as 1,236. Note that the default precision is zero decimal places.
The $options parameter is where the real magic for this method resides.
• If you pass an integer then this becomes the amount of precision or places for the function.
• If you pass an associated array, you can use the following keys:
OptionDescription

placesprecision
pattern
localebeforeafter

Number of decimal places to use, ie. 2
Maximum number of decimal places to use, ie. 2
An ICU number pattern to use for formatting the number ie. #,###.00
The locale name to use for formatting number, ie. “fr_FR”.
Text to display before the rendered number.
Text to display after the rendered number.

Example:902

Chapter 36. NumberCakePHP Book, Release 3.10// Called as NumberHelper
echo $this->Number->format('123456.7890', ['places' => 2,'before' => '¥ ','after' => ' !']);// Output '¥ 123,456.79 !'echo $this->Number->format('123456.7890', ['locale' => 'fr_FR']);// Output '123 456,79 !'// Called as Number
echo Number::format('123456.7890', ['places' => 2,'before' => '¥ ','after' => ' !']);// Output '¥ 123,456.79 !'echo Number::format('123456.7890', ['locale' => 'fr_FR']);// Output '123 456,79 !'Cake\I18n\Number::ordinal(mixed $value, array $options = [])This method will output an ordinal number.
Examples:echo Number::ordinal(1);// Output '1st'
echo Number::ordinal(2);// Output '2nd'
echo Number::ordinal(2, ['locale' => 'fr_FR']);// Output '2e'echo Number::ordinal(410);// Output '410th'

Formatting Numbers

903

CakePHP Book, Release 3.10

Format DifferencesCake\I18n\Number::formatDelta(mixed $value, array $options = [])This method displays differences in value as a signed number:// Called as NumberHelper$this->Number->formatDelta($value, $options);// Called as Number
Number::formatDelta($value, $options);
The $value parameter is the number that you are planning on formatting for output. With no $options supplied, thenumber 1236.334 would output as 1,236. Note that the default precision is zero decimal places.
The $options parameter takes the same keys as Number::format() itself:
OptionDescription

placesprecision
localebeforeafter

Number of decimal places to use, ie. 2
Maximum number of decimal places to use, ie. 2
The locale name to use for formatting number, ie. “fr_FR”.
Text to display before the rendered number.
Text to display after the rendered number.

Example:// Called as NumberHelper
echo $this->Number->formatDelta('123456.7890', ['places' => 2,'before' => '[',
'after' => ']']);// Output '[+123,456.79]'// Called as Number
echo Number::formatDelta('123456.7890', ['places' => 2,'before' => '[',
'after' => ']']);// Output '[+123,456.79]'

Configure formatters
Cake\I18n\Number::config(string $locale, int $type = NumberFormatter::DECIMAL, array $options = [])This method allows you to configure formatter defaults which persist across calls to various methods.
Example:904

Chapter 36. NumberCakePHP Book, Release 3.10

Number::config('en_IN', \NumberFormatter::CURRENCY, ['pattern' => '#,##,##0']);

Configure formatters905

CakePHP Book, Release 3.10

906

Chapter 36. Number

CHAPTER 37

Registry Objects

The registry classes provide a simple way to create and retrieve loaded instances of a given object type. There areregistry classes for Components, Helpers, Tasks, and Behaviors.
While the examples below will use Components, the same behavior can be expected for Helpers, Behaviors, and Tasks
in addition to Components.

Loading Objects
Objects can be loaded on-the-fly using add<registry-object>() Example:$this->loadComponent('Acl.Acl');$this->addHelper('Flash');This will result in the Acl property and Flash helper being loaded. Configuration can also be set on-the-fly. Example:$this->loadComponent('Cookie', ['name' => 'sweet']);Any keys and values provided will be passed to the Component’s constructor. The one exception to this rule isclassName. Classname is a special key that is used to alias objects in a registry. This allows you to have component names that do not reflect the classnames, which can be helpful when extending core components:$this->Auth = $this->loadComponent('Auth', ['className' => 'MyCustomAuth']);$this->Auth->user(); // Actually using MyCustomAuth::user();907

CakePHP Book, Release 3.10

Triggering Callbacks
Callbacks are not provided by registry objects. You should use the events system to dispatch any events/callbacks foryour application.

Disabling Callbacks
In previous versions, collection objects provided a disable() method to disable objects from receiving callbacks.
You should use the features in the events system to accomplish this now. For example, you could disable component
callbacks in the following way:// Remove Auth from callbacks.
$this->eventManager()->off($this->Auth);// Re-enable Auth for callbacks.
$this->eventManager()->on($this->Auth);908

Chapter 37. Registry Objects

CHAPTER 38

Textclass Cake\Utility\Text
The Text class includes convenience methods for creating and manipulating strings and is normally accessed statically.
Example: Text::uuid().
If you need Cake\View\Helper\TextHelper functionalities outside of a View, use the Text class:namespace App\Controller;
use Cake\Utility\Text;class UsersController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Auth')};public function afterLogin(){$message = $this->Users->find('new_message');if (!empty($message)) {// Notify user of new message$this->Flash->success(__('You have a new message: {0}',Text::truncate($message['Message']['body'], 255, ['html' => true])
));
}
}
}

909

CakePHP Book, Release 3.10

Convert Strings into ASCII
static Cake\Utility\Text::transliterate($string, $transliteratorId = null)Transliterate by default converts all characters in provided string into equivalent ASCII characters. The method expects
UTF-8 encoding. The character conversion can be controlled using transliteration identifiers which you can pass using
the $transliteratorId argument or change the default identifier string using Text::setTransliteratorId().
ICU transliteration identifiers are basically of form <source script>:<target script> and you can specify multiple conversion pairs separated by ;. You can find more info about transliterator identifiers here201 :// apple puree
Text::transliterate('apple purée');// Ubermensch (only latin characters are transliterated)
Text::transliterate('Übérmensch', 'Latin-ASCII;');

Creating URL Safe Strings
static Cake\Utility\Text::slug($string, $options = [])Slug transliterates all characters into ASCII versions and converting unmatched characters and spaces to dashes. The
slug method expects UTF-8 encoding.
You can provide an array of options that controls slug. $options can also be a string in which case it will be used as
replacement string. The supported options are:• replacement Replacement string, defaults to ‘-‘.
• transliteratorId A valid tranliterator id string. If default null Text::$_defaultTransliteratorId to
be used. If false no transliteration will be done, only non words will be removed.
• preserve Specific non-word character to preserve. Defaults to null. For e.g. this option can be set to ‘.’ togenerate clean file names:// apple-puree
Text::slug('apple purée');// apple_puree
Text::slug('apple purée', '_');// foo-bar.tar.gz
Text::slug('foo bar.tar.gz', ['preserve' => '.']);
201 https://unicode-org.github.io/icu/userguide/transforms/general/#transliterator-identifiers

910

Chapter 38. Text

CakePHP Book, Release 3.10

Generating UUIDs
static Cake\Utility\Text::uuid
The UUID method is used to generate unique identifiers as per RFC 4122202 . The UUID is a 128-bit string in theformat of 485fc381-e790-47a3-9794-1337c0a8fe68.
Text::uuid(); // 485fc381-e790-47a3-9794-1337c0a8fe68

Simple String Parsing
static Cake\Utility\Text::tokenize($data, $separator = ', ', $leftBound = '(', $rightBound = ')')
Tokenizes a string using $separator, ignoring any instance of $separator that appears between $leftBound and$rightBound.
This method can be useful when splitting up data that has regular formatting such as tag lists:$data = "cakephp 'great framework' php";$result = Text::tokenize($data, ' ', "'", "'");// Result contains['cakephp', "'great framework'", 'php'];
Cake\Utility\Text::parseFileSize(string $size, $default)This method unformats a number from a human-readable byte size to an integer number of bytes:$int = Text::parseFileSize('2GB');

Formatting Strings
static Cake\Utility\Text::insert($string, $data, $options = [])The insert method is used to create string templates and to allow for key/value replacements:
Text::insert('My name is :name and I am :age years old.',['name' => 'Bob', 'age' => '65']);// Returns: "My name is Bob and I am 65 years old."
static Cake\Utility\Text::cleanInsert($string, $options = [])Cleans up a Text::insert formatted string with given $options depending on the ‘clean’ key in $options. The
default method used is text but html is also available. The goal of this function is to replace all whitespace and unneededmarkup around placeholders that did not get replaced by Text::insert.
You can use the following options in the options array:
202 https://datatracker.ietf.org/doc/html/rfc4122.html

Generating UUIDs

911

CakePHP Book, Release 3.10

$options = ['clean' => ['method' => 'text', // or html],
'before' => '','after' => ''];Wrapping Text
static Cake\Utility\Text::wrap($text, $options = [])Wraps a block of text to a set width and indents blocks as well. Can intelligently wrap text so words are not sliced
across lines:$text = 'This is the song that never ends.';$result = Text::wrap($text, 22);// Returns
This is the song thatnever ends.
You can provide an array of options that control how wrapping is done. The supported options are:• width The width to wrap to. Defaults to 72.
• wordWrap Whether or not to wrap whole words. Defaults to true.
• indent The character to indent lines with. Defaults to ‘’.
• indentAt The line number to start indenting text. Defaults to 0.
static Cake\Utility\Text::wrapBlock($text, $options = [])If you need to ensure that the total width of the generated block won’t exceed a certain length even with internal
identation, you need to use wrapBlock() instead of wrap(). This is particulary useful to generate text for the console
for example. It accepts the same options as wrap():$text = 'This is the song that never ends. This is the song that never ends.';$result = Text::wrapBlock($text, ['width' => 22,'indent' => ' → ','indentAt' => 1]);// Returns
This is the song that→ never ends. This
→ is the song that→ never ends.

912

Chapter 38. Text

CakePHP Book, Release 3.10

Highlighting Substrings
Cake\Utility\Text::highlight(string $haystack, string $needle, array $options = [])Highlights $needle in $haystack using the $options['format'] string specified or a default string.
Options:• format string - The piece of HTML with the phrase that will be highlighted• html bool - If true, will ignore any HTML tags, ensuring that only the correct text is highlighted
Example:// Called as TextHelper
echo $this->Text->highlight($lastSentence,'using',['format' => '<span class="highlight">\1</span>']);// Called as Text
use Cake\Utility\Text;
echo Text::highlight($lastSentence,'using',['format' => '<span class="highlight">\1</span>']);Output:Highlights $needle in $haystack <span class="highlight">using</span> the$options['format'] string specified or a default string.

Removing Links
Cake\Utility\Text::stripLinks($text)
Strips the supplied $text of any HTML links.

Truncating Text
Cake\Utility\Text::truncate(string $text, int $length = 100, array $options)
If $text is longer than $length, this method truncates it at $length and adds a suffix consisting of 'ellipsis',if defined. If 'exact' is passed as false, the truncation will occur at the first whitespace after the point at which$length is exceeded. If 'html' is passed as true, HTML tags will be respected and will not be cut off.
$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

Highlighting Substrings913

CakePHP Book, Release 3.10[
'ellipsis' => '...','exact' => true,'html' => false]
Example:// Called as TextHelper
echo $this->Text->truncate('The killer crept forward and tripped on the rug.',
22,['ellipsis' => '...','exact' => false]);// Called as Text
use Cake\Utility\Text;
echo Text::truncate('The killer crept forward and tripped on the rug.',
22,['ellipsis' => '...','exact' => false]);
Output:The killer crept...

Truncating the Tail of a String
Cake\Utility\Text::tail(string $text, int $length = 100, array $options)
If $text is longer than $length, this method removes an initial substring with length consisting of the difference andprepends a prefix consisting of 'ellipsis', if defined. If 'exact' is passed as false, the truncation will occur at
the first whitespace prior to the point at which truncation would otherwise take place.
$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:['ellipsis' => '...','exact' => true]
Example:914

Chapter 38. Text

CakePHP Book, Release 3.10

$sampleText = 'I packed my bag and in it I put a PSP, a PS3, a TV, ' .
'a C# program that can divide by zero, death metal t-shirts'// Called as TextHelper
echo $this->Text->tail($sampleText,
70,['ellipsis' => '...','exact' => false]);// Called as Text
use Cake\Utility\Text;
echo Text::tail($sampleText,
70,['ellipsis' => '...','exact' => false]);
Output:...a TV, a C# program that can divide by zero, death metal t-shirts

Extracting an Excerpt
Cake\Utility\Text::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")
Extracts an excerpt from $haystack surrounding the $needle with a number of characters on each side determined
by $radius, and prefix/suffix with $ellipsis. This method is especially handy for search results. The query stringor keywords can be shown within the resulting document.
// Called as TextHelper
echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');// Called as Text
use Cake\Utility\Text;
echo Text::excerpt($lastParagraph, 'method', 50, '...');
Output:... by $radius, and prefix/suffix with $ellipsis. This method is especiallyhandy for search results. The query...

Extracting an Excerpt915CakePHP Book, Release 3.10

Converting an Array to Sentence Form
Cake\Utility\Text::toList(array $list, $and='and', $separator=', ')Creates a comma-separated list where the last two items are joined with ‘and’:$colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];// Called as TextHelper
echo $this->Text->toList($colors);// Called as Text
use Cake\Utility\Text;
echo Text::toList($colors);
Output:red, orange, yellow, green, blue, indigo and violet

916

Chapter 38. Text

CHAPTER 39

Date & Timeclass Cake\I18n\TimeIf you need TimeHelper functionalities outside of a View, use the Time class:use Cake\I18n\Time;class UsersController extends AppController{
public function initialize(){
parent::initialize();$this->loadComponent('Auth');}public function afterLogin(){$time = new Time($this->Auth->user('date_of_birth'));if ($time->isToday()) {// Greet user with a happy birthday message$this->Flash->success(__('Happy birthday to you...'));}}}
Under the hood, CakePHP uses Chronos203 to power its Time utility. Anything you can do with Chronos and
DateTime, you can do with Time and Date.
203 https://github.com/cakephp/chronos

917

CakePHP Book, Release 3.10

Note: Prior to 3.2.0 CakePHP used Carbon204 .
For more details on Chronos please see the API documentation205 .

Creating Time Instances
There are a few ways to create Time instances:use Cake\I18n\Time;// Create from a string datetime.
$time = Time::createFromFormat('Y-m-d H:i:s',$datetime,'America/New_York');// Create from a timestamp$time = Time::createFromTimestamp($ts);// Get the current time.
$time = Time::now();// Or just use 'new'$time = new Time('2014-01-10 11:11', 'America/New_York');$time = new Time('2 hours ago');
The Time class constructor can take any parameter that the internal DateTime PHP class can. When passing a number
or numeric string, it will be interpreted as a UNIX timestamp.
In test cases you can mock out now() using setTestNow():// Fixate time.
$now = new Time('2014-04-12 12:22:30');
Time::setTestNow($now);// Returns '2014-04-12 12:22:30'$now = Time::now();// Returns '2014-04-12 12:22:30'$now = Time::parse('now');
204 https://github.com/briannesbitt/Carbon
205 https://api.cakephp.org/chronos/1.0/

918

Chapter 39. Date & TimeCakePHP Book, Release 3.10

Manipulation
Once created, you can manipulate Time instances using setter methods:$now = Time::now();$now->year(2013)->month(10)->day(31);You can also use the methods provided by PHP’s built-in DateTime class:$now->setDate(2013, 10, 31);
Dates can be modified through subtraction and addition of their components:$now = Time::now();$now->subDays(5);$now->addMonth(1);// Using strtotime strings.
$now->modify('+5 days');
You can get the internal components of a date by accessing its properties:$now = Time::now();
echo $now->year; // 2014
echo $now->month; // 5
echo $now->day; // 10
echo $now->timezone; // America/New_York
It is also allowed to directly assign those properties to modify the date:$time->year = 2015;$time->timezone = 'Europe/Paris';

Formatting
static Cake\I18n\Time::setJsonEncodeFormat($format)
This method sets the default format used when converting an object to json:
Time::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss'); // For any mutable DateTime
FrozenTime::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss'); // For any immutable DateTime
Date::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss'); // For any mutable Date
FrozenDate::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss'); // For any immutable Date// Added in 3.9.0
FrozenDate::setJsonEncodeFormat(static function($time) {return $time->format(DATE_ATOM);});

Manipulation

919

CakePHP Book, Release 3.10

Note: This method must be called statically.
Changed in version 3.9.0: The callable parameter type was added.
Cake\I18n\Time::i18nFormat($format = null, $timezone = null, $locale = null)
A very common thing to do with Time instances is to print out formatted dates. CakePHP makes this a snap:$now = Time::parse('2014-10-31');// Prints a localized datetime stamp.
echo $now;// Outputs '10/31/14, 12:00 AM' for the en-US locale$now->i18nFormat();// Use the full date and time format$now->i18nFormat(\IntlDateFormatter::FULL);// Use full date but short time format$now->i18nFormat([\IntlDateFormatter::FULL, \IntlDateFormatter::SHORT]);// Outputs '2014-10-31 00:00:00'$now->i18nFormat('yyyy-MM-dd HH:mm:ss');
It is possible to specify the desired format for the string to be displayed. You can either pass IntlDateFormatter constants206 as the first argument of this function, or pass a full ICU date formatting string as specified in the following
resource: https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax.
You can also format dates with non-gregorian calendars:// Outputs 'Friday, Aban 9, 1393 AP at 12:00:00 AM GMT'
$result = $now->i18nFormat(\IntlDateFormatter::FULL, null, 'en-IR@calendar=persian');
The following calendar types are supported:• japanese• buddhist• chinese• persian• indian• islamic• hebrew• coptic• ethiopic
New in version 3.1: Non-gregorian calendar support was added in 3.1
206 https://www.php.net/manual/en/class.intldateformatter.php

920

Chapter 39. Date & TimeCakePHP Book, Release 3.10

Note: For constant strings i.e. IntlDateFormatter::FULL Intl uses ICU library that feeds its data from CLDR
(https://cldr.unicode.org/) which version may vary depending on PHP installation and give different results.
Cake\I18n\Time::nice()
Print out a predefined ‘nice’ format:$now = Time::parse('2014-10-31');// Outputs 'Oct 31, 2014 12:00 AM' in en-US
echo $now->nice();
You can alter the timezone in which the date is displayed without altering the Time object itself. This is useful when
you store dates in one timezone, but want to display them in a user’s own timezone:$now->i18nFormat(\IntlDateFormatter::FULL, 'Europe/Paris');Leaving the first parameter as null will use the default formatting string:$now->i18nFormat(null, 'Europe/Paris');Finally, it is possible to use a different locale for displaying a date:echo $now->i18nFormat(\IntlDateFormatter::FULL, 'Europe/Paris', 'fr-FR');echo $now->nice('Europe/Paris', 'fr-FR');

Setting the Default Locale and Format String
The default locale in which dates are displayed when using nice i18nFormat is taken from the directive
intl.default_locale207 . You can, however, modify this default at runtime:
Time::setDefaultLocale('es-ES'); // For any mutable DateTime
FrozenTime::setDefaultLocale('es-ES'); // For any immutable DateTime
Date::setDefaultLocale('es-ES'); // For any mutable Date
FrozenDate::setDefaultLocale('es-ES'); // For any immutable Date
From now on, datetimes will be displayed in the Spanish preferred format unless a different locale is specified directlyin the formatting method.
Likewise, it is possible to alter the default formatting string to be used for i18nFormat:
Time::setToStringFormat(\IntlDateFormatter::SHORT); // For any mutable DateTime
FrozenTime::setToStringFormat(\IntlDateFormatter::SHORT); // For any immutable DateTime
Date::setToStringFormat(\IntlDateFormatter::SHORT); // For any mutable Date
FrozenDate::setToStringFormat(\IntlDateFormatter::SHORT); // For any immutable Date// The same method exists on Date, FrozenDate and FrozenTime
Time::setToStringFormat([\IntlDateFormatter::FULL,\IntlDateFormatter::SHORT(continues on next page)
207 https://www.php.net/manual/en/intl.configuration.php#ini.intl.default-locale

Formatting921

CakePHP Book, Release 3.10

(continued from previous page)]);// The same method exists on Date, FrozenDate and FrozenTime
Time::setToStringFormat('yyyy-MM-dd HH:mm:ss');
It is recommended to always use the constants instead of directly passing a date format string.

Formatting Relative TimesCake\I18n\Time::timeAgoInWords(array $options = [])Often it is useful to print times relative to the present:$now = new Time('Aug 22, 2011');echo $now->timeAgoInWords(['format' => 'MMM d, YYY', 'end' => '+1 year']);// On Nov 10th, 2011 this would display: 2 months, 2 weeks, 6 days ago
The end option lets you define at which point after which relative times should be formatted using the format option.
The accuracy option lets us control what level of detail should be used for each interval range:// If $timestamp is 1 month, 1 week, 5 days and 6 hours ago
echo $timestamp->timeAgoInWords(['accuracy' => ['month' => 'month'],'end' => '1 year']);// Outputs '1 month ago'
By setting accuracy to a string, you can specify what is the maximum level of detail you want output:$time = new Time('+23 hours');// Outputs 'in about a day'$result = $time->timeAgoInWords(['accuracy' => 'day']);

Conversion
Cake\I18n\Time::toQuarter()Once created, you can convert Time instances into timestamps or quarter values:$time = new Time('2014-06-15');$time->toQuarter();$time->toUnixString();922

Chapter 39. Date & TimeCakePHP Book, Release 3.10

Comparing With the Present
Cake\I18n\Time::isYesterday()Cake\I18n\Time::isThisWeek()
Cake\I18n\Time::isThisMonth()Cake\I18n\Time::isThisYear()
You can compare a Time instance with the present in a variety of ways:$time = new Time('2014-06-15');
echo $time->isYesterday();echo $time->isThisWeek();echo $time->isThisMonth();echo $time->isThisYear();Each of the above methods will return true/false based on whether or not the Time instance matches the present.

Comparing With Intervals
Cake\I18n\Time::isWithinNext($interval)
You can see if a Time instance falls within a given range using wasWithinLast() and isWithinNext():$time = new Time('2014-06-15');// Within 2 days.
echo $time->isWithinNext(2);// Within 2 next weeks.
echo $time->isWithinNext('2 weeks');
Cake\I18n\Time::wasWithinLast($interval)
You can also compare a Time instance within a range in the past:// Within past 2 days.
echo $time->wasWithinLast(2);// Within past 2 weeks.
echo $time->wasWithinLast('2 weeks');

Comparing With the Present923CakePHP Book, Release 3.10

Dates
New in version 3.2.
The Date class in CakePHP implements the same API and methods as Cake\I18n\Time does. The main difference
between Time and Date is that Date does not track time components, and is always in UTC. As an example:
use Cake\I18n\Date;$date = new Date('2015-06-15');$date->modify('+2 hours');// Outputs 2015-06-15 00:00:00
echo $date->format('Y-m-d H:i:s');$date->modify('+36 hours');// Outputs 2015-06-15 00:00:00
echo $date->format('Y-m-d H:i:s');Attempts to modify the timezone on a Date instance are also ignored:
use Cake\I18n\Date;$date = new Date('2015-06-15');$date->setTimezone(new \DateTimeZone('America/New_York'));// Outputs UTC
echo $date->format('e');

Immutable Dates and Times
class Cake\I18n\FrozenTime
class Cake\I18n\FrozenDate
CakePHP offers immutable date and time classes that implement the same interface as their mutable siblings. Immutable objects are useful when you want to prevent accidental changes to data, or when you want to avoid order based
dependency issues. Take the following code:
use Cake\I18n\Time;$time = new Time('2015-06-15 08:23:45');$time->modify('+2 hours');// This method also modifies the $time instance$this->someOtherFunction($time);// Output here is unknown.
echo $time->format('Y-m-d H:i:s');If the method call was re-ordered, or if someOtherFunction changed the output could be unexpected. The mutabilityof our object creates temporal coupling. If we were to use immutable objects, we could avoid this issue:
use Cake\I18n\FrozenTime;$time = new FrozenTime('2015-06-15 08:23:45');(continues on next page)924

Chapter 39. Date & TimeCakePHP Book, Release 3.10

(continued from previous page)$time = $time->modify('+2 hours');// This method's modifications don't change $time$this->someOtherFunction($time);// Output here is known.
echo $time->format('Y-m-d H:i:s');
Immutable dates and times are useful in entities as they prevent accidental modifications, and force changes to be
explicit. Using immutable objects helps the ORM to more easily track changes, and ensure that date and datetime
columns are persisted correctly:// This change will be lost when the article is saved.
$article->updated->modify('+1 hour');// By replacing the time object the property will be saved.
$article->updated = $article->updated->modify('+1 hour');

Accepting Localized Request Data
When creating text inputs that manipulate dates, you’ll probably want to accept and parse localized datetime strings.
See the Parsing Localized Datetime Data.

Supported Timezones
CakePHP supports all valid PHP timezones. For a list of supported timezones, see this page208 .

208 http://php.net/manual/en/timezones.php

Accepting Localized Request Data

925

CakePHP Book, Release 3.10

926

Chapter 39. Date & TimeCHAPTER 40

Xmlclass Cake\Utility\Xml
The Xml class allows you to transform arrays into SimpleXMLElement or DOMDocument objects, and back into arrays
again.

Loading XML documents
static Cake\Utility\Xml::build($input, array $options = [])You can load XML-ish data using Xml::build(). Depending on your $options parameter, this method will returna SimpleXMLElement (default) or DOMDocument object. You can use Xml::build() to build XML objects from avariety of sources. For example, you can load XML from strings:$text = '<?xml version="1.0" encoding="utf-8"?><post><id>1</id><title>Best post</title><body> ... </body></post>';$xml = Xml::build($text);
You can also build Xml objects from local files:// Local file
$xml = Xml::build('/home/awesome/unicorns.xml');
You can also build Xml objects using an array:927

CakePHP Book, Release 3.10

$data = ['post' => ['id' => 1,'title' => 'Best post','body' => ' ... ']];$xml = Xml::build($data);
If your input is invalid, the Xml class will throw an exception:$xmlString = 'What is XML?';try {$xmlObject = Xml::build($xmlString); // Here will throw an exception} catch (\Cake\Utility\Exception\XmlException $e) {throw new InternalErrorException();}Note: DOMDocument209 and SimpleXML210 implement different APIs. Be sure to use the correct methods on theobject you request from Xml.

Loading HTML documents
HTML documents can be parsed into SimpleXmlElement or DOMDocument objects with loadHtml():$html = Xml::loadHtml($htmlString, ['return' => 'domdocument']);By default entity loading and huge document parsing are disabled.
loadEntities and parseHuge options respectively.

These modes can be enabled with the

New in version 3.7.0.

Transforming a XML String in Array
toArray($obj);
Converting XML strings into arrays is simple with the Xml class as well. By default you’ll get a SimpleXml object
back:$xmlString = '<?xml version="1.0"?><root><child>value</child></root>';$xmlArray = Xml::toArray(Xml::build($xmlString));
If your XML is invalid a Cake\Utility\Exception\XmlException will be raised.
209 https://php.net/domdocument
210 https://php.net/simplexml

928

Chapter 40. Xml

CakePHP Book, Release 3.10

Transforming an Array into a String of XML$xmlArray = ['root' => ['child' => 'value']];// You can use Xml::build() too.
$xmlObject = Xml::fromArray($xmlArray, ['format' => 'tags']);$xmlString = $xmlObject->asXML();Your array must have only one element in the “top level” and it can not be numeric. If the array is not in this format,
Xml will throw an exception. Examples of invalid arrays:// Top level with numeric key[['key' => 'value']];// Multiple keys in top level['key1' => 'first value','key2' => 'other value'];
By default array values will be output as XML tags. If you want to define attributes or text values you can prefix thekeys that are supposed to be attributes with @. For value text, use @ as the key:
$xmlArray = ['project' => ['@id' => 1,'name' => 'Name of project, as tag','@' => 'Value of project']];$xmlObject = Xml::fromArray($xmlArray);$xmlString = $xmlObject->asXML();The content of $xmlString will be:<?xml version="1.0"?><project id="1">Value of project<name>Name of project, as tag</name></project>

Using Namespaces
To use XML Namespaces, create a key in your array with the name xmlns: in a generic namespace or input the prefix
xmlns: in a custom namespace. See the samples:$xmlArray = ['root' => ['xmlns:' => 'https://cakephp.org','child' => 'value']];$xml1 = Xml::fromArray($xmlArray);(continues on next page)

Transforming an Array into a String of XML

929

CakePHP Book, Release 3.10

(continued from previous page)$xmlArray('root' => ['tag' => ['xmlns:pref' => 'https://cakephp.org','pref:item' => ['item 1','item 2']]]);
$xml2 = Xml::fromArray($xmlArray);
The value of $xml1 and $xml2 will be, respectively:<?xml version="1.0"?><root xmlns="https://cakephp.org"><child>value</child><?xml version="1.0"?><root><tag xmlns:pref="https://cakephp.org"><pref:item>item 1</pref:item><pref:item>item␣
˓→2</pref:item></tag></root>

Creating a Child
After you have created your XML document, you just use the native interfaces for your document type to add, remove,or manipulate child nodes:// Using SimpleXML$myXmlOriginal = '<?xml version="1.0"?><root><child>value</child></root>';$xml = Xml::build($myXmlOriginal);$xml->root->addChild('young', 'new value');// Using DOMDocument$myXmlOriginal = '<?xml version="1.0"?><root><child>value</child></root>';$xml = Xml::build($myXmlOriginal, ['return' => 'domdocument']);$child = $xml->createElement('young', 'new value');$xml->firstChild->appendChild($child);

Tip: After manipulating your XML using SimpleXMLElement or DomDocument you can use Xml::toArray()without a problem.

930

Chapter 40. Xml

CHAPTER 41

Constants & Functions

While most of your day-to-day work in CakePHP will be utilizing core classes and methods, CakePHP features anumber of global convenience functions that may come in handy. Many of these functions are for use with CakePHP
classes (loading model or component classes), but many others make working with arrays or strings a little easier.
We’ll also cover some of the constants available in CakePHP applications. Using these constants will help makeupgrades more smooth, but are also convenient ways to point to certain files or directories in your CakePHP application.

Global Functions
Here are CakePHP’s globally available functions. Most of them are just convenience wrappers for other CakePHP
functionality, such as debugging and translating content.
\_\_(string $string_id, [$formatArgs])
This function handles localization in CakePHP applications. The $string_id identifies the ID for a translation.
You can supply additional arguments to replace placeholders in your string:__('You have {0} unread messages', $number);
You can also provide a name-indexed array of replacements:__('You have {unread} unread messages', ['unread' => $number]);

Note: Check out the Internationalization & Localization section for more information.
__d(string $domain, string $msg, mixed $args = null)
Allows you to override the current domain for a single message lookup.
Useful when internationalizing a plugin: echo __d('PluginName', 'This is my plugin');931

CakePHP Book, Release 3.10__dn(string $domain, string $singular, string $plural, integer $count, mixed $args = null)
Allows you to override the current domain for a single plural message lookup. Returns correct plural form of
message identified by $singular and $plural for count $count from domain $domain.
__dx(string $domain, string $context, string $msg, mixed $args = null)
Allows you to override the current domain for a single message lookup. It also allows you to specify a context.
The context is a unique identifier for the translations string that makes it unique within the same domain.
__dxn(string $domain, string $context, string $singular, string $plural, integer $count, mixed $args = null)
Allows you to override the current domain for a single plural message lookup. It also allows you to specify acontext. Returns correct plural form of message identified by $singular and $plural for count $count fromdomain $domain. Some languages have more than one form for plural messages dependent on the count.
The context is a unique identifier for the translations string that makes it unique within the same domain.
__n(string $singular, string $plural, integer $count, mixed $args = null)
Returns correct plural form of message identified by $singular and $plural for count $count. Some languages have more than one form for plural messages dependent on the count.
__x(string $context, string $msg, mixed $args = null)
The context is a unique identifier for the translations string that makes it unique within the same domain.
__xn(string $context, string $singular, string $plural, integer $count, mixed $args = null)
Returns correct plural form of message identified by $singular and $plural for count $count from domain$domain. It also allows you to specify a context. Some languages have more than one form for plural messages
dependent on the count.
The context is a unique identifier for the translations string that makes it unique within the same domain.
collection(mixed $items)
Convenience wrapper for instantiating a new Cake\Collection\Collection object, wrapping the passed argument. The $items parameter takes either a Traversable object or an array.
debug(mixed $var, boolean $showHtml = null, $showFrom = true)
Changed in version 3.3.0: Calling this method will return passed $var, so that you can, for instance, place it inreturn statements.
If the core $debug variable is true, $var is printed out. If $showHTML is true or left as null, the data isrendered to be browser-friendly. If $showFrom is not set to false, the debug output will start with the line fromwhich it was called. Also see Debugging
dd(mixed $var, boolean $showHtml = null)
It behaves like debug(), but execution is also halted. If the core $debug variable is true, $var is printed. If$showHTML is true or left as null, the data is rendered to be browser-friendly. Also see Debugging
pr(mixed $var)
Changed in version 3.3.0: Calling this method will return passed $var, so that you can, for instance, place it inreturn statements.
Convenience wrapper for print_r(), with the addition of wrapping <pre> tags around the output.
pj(mixed $var)
Changed in version 3.3.0: Calling this method will return passed $var, so that you can, for instance, place it inreturn statements.
JSON pretty print convenience function, with the addition of wrapping <pre> tags around the output.
It is meant for debugging the JSON representation of objects and arrays.

932

Chapter 41. Constants & Functions

CakePHP Book, Release 3.10

env(string $key, string $default = null)
Changed in version 3.1.1: The $default parameter has been added.
Gets an environment variable from available sources. Used as a backup if $_SERVER or $_ENV are disabled.
This function also emulates PHP_SELF and DOCUMENT_ROOT on unsupporting servers. In fact, it’s a good idea toalways use env() instead of $_SERVER or getenv() (especially if you plan to distribute the code), since it’s afull emulation wrapper.
h(string $text, boolean $double = true, string $charset = null)Convenience wrapper for htmlspecialchars().
pluginSplit(string $name, boolean $dotAppend = false, string $plugin = null)
Splits a dot syntax plugin name into its plugin and class name. If $name does not have a dot, then index 0 willbe null.
Commonly used like list($plugin, $name) = pluginSplit('Users.User');namespaceSplit(string $class)
Split the namespace from the classname.
Commonly used like list($namespace, $className) = namespaceSplit('Cake\Core\App');

Core Definition Constants
Most of the following constants refer to paths in your application.
constant APP
Absolute path to your application directory, including a trailing slash.
constant APP_DIR
Equals app or the name of your application directory.
constant CACHE
Path to the cache files directory. It can be shared between hosts in a multi-server setup.
constant CAKE
Path to the cake directory.
constant CAKE_CORE_INCLUDE_PATHPath to the root lib directory.
constant CONFIG
Path to the config directory.
constant CORE_PATHPath to the CakePHP directory with ending directory slash.
constant DS
Short for PHP’s DIRECTORY_SEPARATOR, which is / on Linux and \ on Windows.
constant LOGS
Path to the logs directory.
constant ROOT
Path to the root directory.

Core Definition Constants

933

CakePHP Book, Release 3.10

constant TESTSPath to the tests directory.
constant TMP
Path to the temporary files directory.
WWW\_ROOT
Full path to the webroot.

Timing Definition Constants
constant TIME_START
Unix timestamp in microseconds as a float from when the application started.
constant SECOND
Equals 1
constant MINUTE
Equals 60
constant HOUR
Equals 3600
constant DAY
Equals 86400
constant WEEK
Equals 604800
constant MONTH
Equals 2592000
constant YEAR
Equals 31536000

934

Chapter 41. Constants & Functions

CHAPTER 42

Chronos

This page has moved211 .

211 https://book.cakephp.org/chronos/1.x/en/935

CakePHP Book, Release 3.10

936

Chapter 42. ChronosCHAPTER 43

Debug Kit

This page has moved212 .

212 https://book.cakephp.org/debugkit/3.x/en/937

CakePHP Book, Release 3.10

938

Chapter 43. Debug Kit

CHAPTER 44

Migrations

This page has moved213 .

213 https://book.cakephp.org/migrations/2.x/en/939

CakePHP Book, Release 3.10

940

Chapter 44. Migrations

CHAPTER 45

ElasticSearchThis page has moved214 .

214 https://book.cakephp.org/elasticsearch/2.x/en/941

CakePHP Book, Release 3.10

942

Chapter 45. ElasticSearch

CHAPTER 46

Appendices

Appendices contain information regarding the new features introduced in each version and the migration path between
versions.

3.x Migration Guide
Forwards Compatibility Shimming
FC shimming can prepare your 3.x app for the next major release (4.x).
If you already want to shim 4.x behavior in 3.x, check out the Shim plugin215 that can help mitigate some BC breaking
changes. The closer your 3.x app is to 4.x, the smaller will be the diff of changes, and the smoother will be the final
upgrade.

General Information
CakePHP Development Process
Here we attempt to explain the process we use when developing the CakePHP framework. We rely heavily on community interaction through tickets and IRC chat. IRC is the best place to find members of the development team216 anddiscuss ideas, the latest code, and make general comments. If something more formal needs to be proposed or there isa problem with a release, the ticket system is the best place to share your thoughts.
We currently maintain 4 versions of CakePHP.
215 https://github.com/dereuromark/cakephp-shim
216 https://github.com/cakephp?tab=members

943

CakePHP Book, Release 3.10

• tagged release : Tagged releases intended for production where stability is more important than features. Issues
filed against these releases will be fixed in the related branch, and be part of the next release.
• mainline branch : These branches are where all bugfixes are merged into. Stable releases are tagged from thesebranches. master is the mainline branch for the current release series. 2.x is the maintenance branch for the 2.x
release series. If you are using a stable release and need fixes that haven’t made their way into a tagged releasecheck here.
• development branches : Development branches contain leading edge fixes and features. They are named after
the major version they are for. E.g 3.next. Once development branches have reached a stable release point they
are merged into the mainline branch.
• feature branches : Feature branches contain unfinished or possibly unstable features and are recommended
only for power users interested in the most advanced feature set and willing to contribute back to the community.
Feature branches are named with the following convention version-feature. An example would be 3.3-router
Which would contain new features for the Router for 3.3.
Hopefully this will help you understand what version is right for you. Once you pick your version you may feel compelled to contribute a bug report or make general comments on the code.
• If you are using a stable version or maintenance branch, please submit tickets or discuss with us on IRC.
• If you are using the development branch or feature branch, the first place to go is IRC. If you have a commentand cannot reach us in IRC after a day or two, please submit a ticket.
If you find an issue, the best answer is to write a test. The best advice we can offer in writing tests is to look at the ones
included in the core.
As always, if you have any questions or comments, visit us at #cakephp on irc.freenode.net.

Glossary
CDN
Content Delivery Network. A 3rd party vendor you can pay to help distribute your content to data centers aroundthe world. This helps put your static assets closer to geographically distributed users.
columns
Used in the ORM when referring to the table columns in an database table.
CSRF
Cross Site Request Forgery. Prevents replay attacks, double submissions and forged requests from other domains.
DSN
Data Source Name. A connection string format that is formed like a URI. CakePHP supports DSNs for Cache,
Database, Log and Email connections.
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'](continues on next page)

944

Chapter 46. Appendices

CakePHP Book, Release 3.10

(continued from previous page)]]
DRY
Don’t 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.
fieldsA generic term used to describe both entity properties, or database columns. Often used in conjunction with theFormHelper.
HTML attributes
An array of key => values that are composed into HTML attributes. For example:// Given['class' => 'my-class', 'target' => '_blank']// Would generateclass="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"
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
properties
Used when referencing columns mapped onto an ORM entity.
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'
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.
routing array
An array of attributes that are passed to Router::url(). They typically look like:['controller' => 'Posts', 'action' => 'view', 5]General Information

945

CakePHP Book, Release 3.10

946

Chapter 46. Appendices

PHP Namespace IndexcCake\Cache, 631
Cake\Collection, 839
Cake\Console, 679
Cake\Console\Exception, 717
Cake\Controller, 283
Cake\Controller\Component, 321
Cake\Controller\Exception, 717
Cake\Core, 222
Cake\Core\Exception, 718
Cake\Database, 468
Cake\Database\Exception, 718
Cake\Database\Schema, 626
Cake\Datasource, 467
Cake\Datasource\Exception, 718
Cake\Error, 690
Cake\Filesystem, 861
Cake\Form, 749
Cake\Http, 885
Cake\Http\Client, 891
Cake\Http\Cookie, 281
Cake\Http\Exception, 715
Cake\I18n, 917
Cake\Log, 746
Cake\Mailer, 697
Cake\ORM, 512
Cake\ORM\Behavior, 615
Cake\ORM\Exception, 718
Cake\Routing, 229
Cake\Routing\Exception, 718
Cake\Utility, 927
Cake\Validation, 823
Cake\View, 337
Cake\View\Exception, 717
Cake\View\Helper, 450

947

CakePHP Book, Release 3.10

948

PHP Namespace Index

IndexSymbols

afterDelete() (Cake\ORM\Table method), 517
afterDeleteCommit() (Cake\ORM\Table method), 517() ( method), 336
afterFilter()(Cake\Controller\Controller method),:action, 231
291:controller, 231
afterLayout() (Helper method), 459:plugin, 231
afterRender() (Helper method), 459$this->request, 261
afterRenderFile() (Helper method), 459$this->response, 271
afterRules() (Cake\ORM\Table method), 516__d() (global function), 931
afterSave() (Cake\ORM\Table method), 517__dn() (global function), 931
afterSaveCommit() (Cake\ORM\Table method), 517__dx() (global function), 932
alert() (Cake\Log\Log method), 747__dxn() (global function), 932
allControls()(Cake\View\Helper\FormHelper__n() (global function), 932
method), 408__x() (global function), 932
allow() (AuthComponent method), 307__xn() (global function), 932
allowMethod() (Cake\Http\ServerRequest method), 269
App (class in Cake\Core), 835
A
APP (global constant), 933
acceptLanguage() (Cake\Http\ServerRequest method),
app.php, 217
271
APP_DIR (global constant), 933
accepts() (Cake\Http\ServerRequest method), 271
app_local.example.php, 217
accepts() (RequestHandlerComponent method), 327
append() (Cake\Collection\Collection method), 855
addArgument() (Cake\Console\ConsoleOptionParser
append() (Cake\Filesystem\File method), 866
method), 665
appendItem() (Cake\Collection\Collection method),
addArguments() (Cake\Console\ConsoleOptionParser
855
method), 665
application exceptions, 714
addBehavior() (Cake\ORM\Table method), 518
apply() (Cake\Utility\Hash method), 880
addCrumb() (Cake\View\Helper\HtmlHelper method),ask() (Cake\Console\ConsoleIo method), 660
426
attachments() (Cake\Mailer\Email method), 703
addDetector() (Cake\Http\ServerRequest method), 267
AuthComponent (class), 292
addOption()(Cake\Console\ConsoleOptionParser
autoLink() (Cake\View\Helper\TextHelper method),
method), 666
446
addOptions()(Cake\Console\ConsoleOptionParser
autoLinkEmails()(Cake\View\Helper\TextHelper
method), 666
method), 445
addPathElement() (Cake\Filesystem\Folder method),
autoLinkUrls()(Cake\View\Helper\TextHelper862
method), 446
addSubcommand() (Cake\Console\ConsoleOptionParser
autoParagraph()(Cake\View\Helper\TextHelper
method), 671
method), 446
admin routing, 239
avg() (Cake\Collection\Collection method), 847
949

CakePHP Book, Release 3.10

B

Cake\Http\Exception (namespace), 715
Cake\I18n (namespace), 899, 917
BadRequestException, 715
Cake\Log (namespace), 746
beforeDelete() (Cake\ORM\Table method), 517
Cake\Mailer(namespace), 697
beforeFilter() (Cake\Controller\Controller method),
Cake\ORM(namespace),
479, 512, 521, 531, 566, 588
291
Cake\ORM\Behavior(namespace),603, 605, 607, 615
beforeFind() (Cake\ORM\Table method), 515
Cake\ORM\Exception(namespace),718
beforeLayout() (Helper method), 459
Cake\Routing(namespace),229
beforeMarshal() (Cake\ORM\Table method), 515
beforeRender() (Cake\Controller\Controller method), Cake\Routing\Exception (namespace), 718
Cake\Utility (namespace), 775, 869, 895, 909, 927
291
Cake\Validation (namespace), 823
beforeRender() (Helper method), 459
Cake\View (namespace), 337
beforeRenderFile() (Helper method), 459
Cake\View\Exception (namespace), 717
beforeRules() (Cake\ORM\Table method), 516
Cake\View\Helper (namespace), 361, 364, 365, 413,
beforeSave() (Cake\ORM\Table method), 516
427, 432, 441, 444, 445, 450
blackHole() (SecurityComponent method), 317
camelize()(Cake\Utility\Inflector method), 897
BreadcrumbsHelper (class in Cake\View\Helper), 361
cd()(Cake\Filesystem\Folder
method), 862
breakpoint() (global function), 689
CDN,
944
buffered() (Cake\Collection\Collection method), 858
charset() (Cake\View\Helper\HtmlHelper method),build() (Cake\Utility\Xml method), 927
413
build() (Cake\View\Helper\UrlHelper method), 451
check()(Cake\Controller\Component\CookieComponent
buildFromArray() (Cake\Console\ConsoleOptionParser
method), 312
method), 667
check()(Cake\Core\Configure
method), 224
buildRules() (Cake\ORM\Table method), 516
check()(Cake\Utility\Hashmethod),876
buildValidator() (Cake\ORM\Table method), 516
check()(Cake\View\Helper\SessionHelper
method),button() (Cake\View\Helper\FormHelper method), 402
445
check() (Session method), 785
Ccheckbox() (Cake\View\Helper\FormHelper method),
Cache (class in Cake\Cache), 631
382
CACHE (global constant), 933
checkNotModified()(Cake\Http\Response method),cache() (Cake\View\View method), 348
279
CacheEngine (class in Cake\Cache), 641
chmod() (Cake\Filesystem\Folder method), 862
CAKE (global constant), 933
chunk() (Cake\Collection\Collection method), 844
CAKE_CORE_INCLUDE_PATH (global constant), 933
chunkWithKeys()(Cake\Collection\Collection
Cake\Cache (namespace), 631
method),844
Cake\Collection (namespace), 839
classify() (Cake\Utility\Inflector method), 897
Cake\Console (namespace), 645, 648, 658, 664, 679
classname()(Cake\Core\App method), 835
Cake\Console\Exception (namespace), 717
cleanInsert()(Cake\Utility\Text method), 911
Cake\Controller (namespace), 283
clear()(Cake\Cache\Cache
method), 638
Cake\Controller\Component (namespace), 310, 314,
clear()(Cake\Cache\CacheEngine
method), 641
321
clear()(Cake\ORM\TableLocatormethod),520
Cake\Controller\Exception (namespace), 717
clearGroup()(Cake\Cache\Cache
method),639
Cake\Core (namespace), 222, 835
clearGroup()(Cake\Cache\CacheEngine
method),641
Cake\Core\Exception (namespace), 718
Client(classin
Cake\Http),
885
Cake\Database (namespace), 468
clientIp() (Cake\Http\ServerRequest method), 270
Cake\Database\Exception (namespace), 718
close()(Cake\Filesystem\File method), 866
Cake\Database\Schema (namespace), 626
Collection(class in Cake\Collection), 839
Cake\Datasource (namespace), 467
Collection(classin Cake\Database\Schema), 629
Cake\Datasource\Exception (namespace), 718
collection()(globalfunction), 932
Cake\Error (namespace), 690
columns,944
Cake\Filesystem (namespace), 861
combine() (Cake\Collection\Collection method), 842
Cake\Form (namespace), 749
combine()(Cake\Utility\Hash method), 872
Cake\Http (namespace), 261, 885
Command(classin Cake\Console), 648
Cake\Http\Client (namespace), 891
compile()(Cake\Collection\Collection
method), 859
Cake\Http\Cookie (namespace), 281
950

Index

CakePHP Book, Release 3.10

components (Cake\Controller\Controller property), 290
CONFIG (global constant), 933
config() (Cake\Cache\Cache method), 632
config() (Cake\Core\Configure method), 225
config() (Cake\I18n\Number method), 904
config() (Cake\Log\Log method), 746
configTransport() (Cake\Mailer\Email method), 699
configuration, 217
Configure (class in Cake\Core), 222
configured() (Cake\Log\Log method), 747
ConflictException, 716
Connection (class in Cake\Database), 473
ConnectionManager (class in Cake\Datasource), 467
ConsoleException, 717
ConsoleIo (class in Cake\Console), 658
ConsoleOptionParser (class in Cake\Console), 664
consume() (Cake\Core\Configure method), 224
consume() (Session method), 785
consumeOrFail() (Cake\Core\Configure method), 224
contains() (Cake\Collection\Collection method), 853
contains() (Cake\Utility\Hash method), 875
control() (Cake\View\Helper\FormHelper method),
370
Controller (class in Cake\Controller), 283
controls() (Cake\View\Helper\FormHelper method),407
Cookie (class in Cake\Http\Cookie), 281
CookieCollection (class in Cake\Http\Cookie), 281
CookieComponent(classin
Cake\Controller\Component), 310
copy() (Cake\Filesystem\File method), 866
copy() (Cake\Filesystem\Folder method), 862
core() (Cake\Core\App method), 836
CORE_PATH (global constant), 933
correctSlashFor() (Cake\Filesystem\Folder method),863
countBy() (Cake\Collection\Collection method), 848
counter()(Cake\View\Helper\PaginatorHelper
method), 437
CounterCacheBehavior(classin
Cake\ORM\Behavior), 603
create() (Cake\Filesystem\File method), 866
create() (Cake\Filesystem\Folder method), 863
create() (Cake\View\Helper\FormHelper method), 365
createFile() (Cake\Console\ConsoleIo method), 661
critical() (Cake\Log\Log method), 747
CSRF, 944
css() (Cake\View\Helper\HtmlHelper method), 413
currency() (Cake\I18n\Number method), 900
currency()(Cake\View\Helper\NumberHelper
method), 427
current()(Cake\View\Helper\PaginatorHelper
method), 437

Index

D
dasherize() (Cake\Utility\Inflector method), 897
date() (Cake\View\Helper\FormHelper method), 393
dateTime() (Cake\View\Helper\FormHelper method),391
DAY (global constant), 934
day() (Cake\View\Helper\FormHelper method), 396
dd() (global function), 932
debug() (Cake\Log\Log method), 747
debug() (global function), 932
Debugger (class in Cake\Error), 690
decrement() (Cake\Cache\Cache method), 639
decrement() (Cake\Cache\CacheEngine method), 641
decrypt() (Cake\Utility\Security method), 775
defaultCurrency() (Cake\I18n\Number method), 901
defaultCurrency() (Cake\View\Helper\NumberHelper
method), 428
defaultRouteClass() (Cake\Routing\Router method),254
delete() (Cake\Cache\Cache method), 638
delete() (Cake\Cache\CacheEngine method), 641
delete() (Cake\Controller\Component\CookieComponent
method), 312
delete() (Cake\Core\Configure method), 224delete() (Cake\Filesystem\File method), 866
delete() (Cake\Filesystem\Folder method), 863
delete() (Cake\ORM\Table method), 588
delete() (Session method), 785
deleteAll() (Cake\ORM\Table method), 589
deleteMany() (Cake\Cache\Cache method), 638
deleteOrFail() (Cake\ORM\Table method), 590
deny() (AuthComponent method), 308
destroy() (Session method), 786
diff() (Cake\Utility\Hash method), 881
dimensions() (Cake\Utility\Hash method), 879
dirsize() (Cake\Filesystem\Folder method), 863
dirty() (Cake\ORM\Entity method), 525
disable() (Cake\Cache\Cache method), 640
dispatchShell() (Cake\Console\Shell method), 683
doc (role), 185
docType() (Cake\View\Helper\HtmlHelper method),416
domain() (Cake\Http\ServerRequest method), 269
dot notation, 944
drop() (Cake\Cache\Cache method), 635
drop() (Cake\Core\Configure method), 225
drop() (Cake\Log\Log method), 747
dropTransport() (Cake\Mailer\Email method), 700
DRY, 945
DS (global constant), 933
DSN, 944
dump() (Cake\Core\Configure method), 226dump() (Cake\Error\Debugger method), 690

951

CakePHP Book, Release 3.10

Eeach() (Cake\Collection\Collection method), 840
element() (Cake\View\View method), 346
Email (class in Cake\Mailer), 697
emailPattern() (Cake\Mailer\Email method), 704
emergency() (Cake\Log\Log method), 747
enable() (Cake\Cache\Cache method), 640
enabled() (Cake\Cache\Cache method), 640
encrypt() (Cake\Utility\Security method), 775
end() (Cake\View\Helper\FormHelper method), 402
Entity (class in Cake\ORM), 521
env() (Cake\Http\ServerRequest method), 265
env() (global function), 932
error() (Cake\Log\Log method), 747
error() (Cake\View\Helper\FormHelper method), 399
errors() (Cake\Filesystem\Folder method), 863
every() (Cake\Collection\Collection method), 845
Exception, 718
ExceptionRenderer (class), 710
excerpt() (Cake\Error\Debugger method), 691
excerpt() (Cake\Utility\Text method), 915
excerpt() (Cake\View\Helper\TextHelper method), 449
executable() (Cake\Filesystem\File method), 866
execute() (Cake\Database\Connection method), 473
exists() (Cake\Filesystem\File method), 866
expand() (Cake\Utility\Hash method), 877
ext() (Cake\Filesystem\File method), 866
extensions() (Cake\Routing\Router method), 244
extract() (Cake\Collection\Collection method), 841
extract() (Cake\Utility\Hash method), 870

Folder (class in Cake\Filesystem), 862
Folder() (Cake\Filesystem\File method), 866
ForbiddenException, 715
Form (class in Cake\Form), 749
format() (Cake\I18n\Number method), 902
format() (Cake\Utility\Hash method), 874
format() (Cake\View\Helper\NumberHelper method),429
formatDelta() (Cake\I18n\Number method), 904
formatDelta()(Cake\View\Helper\NumberHelper
method), 431
FormHelper (class in Cake\View\Helper), 365
FrozenDate (class in Cake\I18n), 924
FrozenTime (class in Cake\I18n), 924

G

gc() (Cake\Cache\Cache method), 638
gc() (Cake\Cache\CacheEngine method), 642
generateUrl() (Cake\View\Helper\PaginatorHelper
method), 438
get() (Cake\Datasource\ConnectionManager method),468
get() (Cake\ORM\Entity method), 523
get() (Cake\ORM\Table method), 532
get() (Cake\ORM\TableLocator method), 520
get() (Cake\Utility\Hash method), 870
getCrumbList()(Cake\View\Helper\HtmlHelper
method), 426
getCrumbs() (Cake\View\Helper\HtmlHelper method),426
getData() (Cake\Http\ServerRequest method), 263
F
getMethod() (Cake\Http\ServerRequest method), 269
getQuery() (Cake\Http\ServerRequest method), 262
fallbacks() (Cake\Routing\Router method), 254
getType() (Cake\Error\Debugger method), 692
fields, 945
getUploadedFile()(Cake\Http\ServerRequest
File (class in Cake\Filesystem), 866
method),264
file extensions, 244
getUploadedFiles()(Cake\Http\ServerRequest
file() (Cake\View\Helper\FormHelper method), 389
method),264
filter() (Cake\Collection\Collection method), 845
GoneException, 716
filter() (Cake\Utility\Hash method), 876
greedy star, 231find() (Cake\Filesystem\Folder method), 863
group() (Cake\Filesystem\File method), 866
find() (Cake\ORM\Table method), 533
groupBy() (Cake\Collection\Collection method), 848
findOrCreate() (Cake\ORM\Table method), 586
findRecursive() (Cake\Filesystem\Folder method), groupConfigs() (Cake\Cache\Cache method), 640
864
H
first() (Cake\Collection\Collection method), 854
first() (Cake\View\Helper\PaginatorHelper method), h() (global function), 933
436
handle (Cake\Filesystem\File property), 866
firstMatch() (Cake\Collection\Collection method), Hash (class in Cake\Utility), 869
845
hash() (Cake\Utility\Security method), 776
FlashComponent(classin hasNext()(Cake\View\Helper\PaginatorHelper
Cake\Controller\Component), 314
method), 437
FlashHelper (class in Cake\View\Helper), 364
hasPage()(Cake\View\Helper\PaginatorHelper
flatten() (Cake\Utility\Hash method), 877
method), 437
Folder (Cake\Filesystem\File property), 866
952

Index

CakePHP Book, Release 3.10

hasPrev()(Cake\View\Helper\PaginatorHelper
method), 437
Helper (class), 459
helpers (Cake\Controller\Controller property), 291
hidden() (Cake\View\Helper\FormHelper method), 377
highlight() (Cake\Utility\Text method), 913
highlight() (Cake\View\Helper\TextHelper method),446
host() (Cake\Http\ServerRequest method), 269
HOUR (global constant), 934
hour() (Cake\View\Helper\FormHelper method), 397
HTML attributes, 945
HtmlHelper (class in Cake\View\Helper), 413
humanize() (Cake\Utility\Inflector method), 897

I
i18nFormat() (Cake\I18n\Time method), 920
identify() (AuthComponent method), 296
image() (Cake\View\Helper\HtmlHelper method), 417
inCakePath() (Cake\Filesystem\Folder method), 864
increment() (Cake\Cache\Cache method), 639
increment() (Cake\Cache\CacheEngine method), 642
indexBy() (Cake\Collection\Collection method), 848
Inflector (class in Cake\Utility), 895
info (Cake\Filesystem\File property), 866
info() (Cake\Filesystem\File method), 866
info() (Cake\Log\Log method), 747
initialize() (Cake\Console\Shell method), 686
initialize() (Cake\ORM\Table method), 515
inPath() (Cake\Filesystem\Folder method), 864
input() (Cake\Http\ServerRequest method), 265
insert() (Cake\Collection\Collection method), 856
insert() (Cake\Utility\Hash method), 870
insert() (Cake\Utility\Text method), 911
InternalErrorException, 716
InvalidCsrfTokenException, 715
is() (Cake\Http\ServerRequest method), 266
isAbsolute() (Cake\Filesystem\Folder method), 864
isAtom() (RequestHandlerComponent method), 328
isEmpty() (Cake\Collection\Collection method), 853
isFieldError()(Cake\View\Helper\FormHelper
method), 400
isMobile() (RequestHandlerComponent method), 328
isRss() (RequestHandlerComponent method), 328
isSlashTerm() (Cake\Filesystem\Folder method), 864
isThisMonth() (Cake\I18n\Time method), 923
isThisWeek() (Cake\I18n\Time method), 923
isThisYear() (Cake\I18n\Time method), 923
isWap() (RequestHandlerComponent method), 329
isWindowsPath() (Cake\Filesystem\Folder method),864
isWithinNext() (Cake\I18n\Time method), 923
isXml() (RequestHandlerComponent method), 328
isYesterday() (Cake\I18n\Time method), 923
Index

J
JsonView (class), 359

Llabel() (Cake\View\Helper\FormHelper method), 398
last() (Cake\Collection\Collection method), 854
last() (Cake\View\Helper\PaginatorHelper method),437
lastAccess() (Cake\Filesystem\File method), 867
lastChange() (Cake\Filesystem\File method), 867
levels() (Cake\Log\Log method), 747
limitControl() (Cake\View\Helper\PaginatorHelper
method), 438
link() (Cake\View\Helper\HtmlHelper method), 418
listNested() (Cake\Collection\Collection method),851
load() (Cake\Core\Configure method), 225
loadComponent()(Cake\Controller\Controller
method), 290
loadModel() (Cake\Controller\Controller method), 289
lock (Cake\Filesystem\File property), 866
Log (class in Cake\Log), 746
log() (Cake\Error\Debugger method), 691
log() (Cake\Log\LogTrait method), 747
logout() (AuthComponent method), 305
LOGS (global constant), 933
LogTrait (trait in Cake\Log), 747

Mmap() (Cake\Collection\Collection method), 840
map() (Cake\Database\Type method), 469
map() (Cake\Utility\Hash method), 880
match() (Cake\Collection\Collection method), 845
max() (Cake\Collection\Collection method), 846
maxDimensions() (Cake\Utility\Hash method), 879
md5() (Cake\Filesystem\File method), 867
media() (Cake\View\Helper\HtmlHelper method), 419
median() (Cake\Collection\Collection method), 847
merge() (Cake\Console\ConsoleOptionParser method),668
merge() (Cake\Utility\Hash method), 878
mergeDiff() (Cake\Utility\Hash method), 881
meridian() (Cake\View\Helper\FormHelper method),398
messages() (Cake\Filesystem\Folder method), 864
meta() (Cake\View\Helper\HtmlHelper method), 415
MethodNotAllowedException, 715
mime() (Cake\Filesystem\File method), 867
min() (Cake\Collection\Collection method), 846
MINUTE (global constant), 934
minute() (Cake\View\Helper\FormHelper method), 397
MissingActionException, 717
MissingBehaviorException, 718

953

CakePHP Book, Release 3.10

MissingCellException, 717
MissingCellViewException, 717
MissingComponentException, 717
MissingConnectionException, 718
MissingControllerException, 718
MissingDispatcherFilterException, 718
MissingDriverException, 718
MissingElementException, 717
MissingEntityException, 718
MissingExtensionException, 718
MissingHelperException, 717
MissingLayoutException, 717
MissingRouteException, 718
MissingShellException, 718
MissingShellMethodException, 718
MissingTableException, 718
MissingTaskException, 717
MissingTemplateException, 717
MissingViewException, 717
mode (Cake\Filesystem\Folder property), 862
MONTH (global constant), 934
month() (Cake\View\Helper\FormHelper method), 395
move() (Cake\Filesystem\Folder method), 865

options()(Cake\View\Helper\PaginatorHelper
method), 439
ordinal() (Cake\I18n\Number method), 903
ordinal() (Cake\View\Helper\NumberHelper method),430
owner() (Cake\Filesystem\File method), 867

P

PaaS, 945
paginate() (Cake\Controller\Controller method), 290
PaginatorComponent(classin
Cake\Controller\Component), 321
PaginatorHelper (class in Cake\View\Helper), 432
parseFileSize() (Cake\Utility\Text method), 911
passed arguments, 250
password() (Cake\View\Helper\FormHelper method),377
path (Cake\Filesystem\File property), 866
path (Cake\Filesystem\Folder property), 862
path() (Cake\Core\App method), 836
path() (Cake\Core\Plugin method), 836
perms() (Cake\Filesystem\File method), 867
PersistenceFailedException, 718
php:attr (directive), 187N
php:attr (role), 188
name (Cake\Filesystem\File property), 866
php:class (directive), 186
name() (Cake\Filesystem\File method), 867
php:class (role), 187
namespaceSplit() (global function), 933
php:const (directive), 186nest() (Cake\Collection\Collection method), 851
php:const (role), 187nest() (Cake\Utility\Hash method), 883
php:exc (role), 188nested commands, 647
php:exception (directive), 186nestedList() (Cake\View\Helper\HtmlHelper method), php:func (role), 187422
php:function (directive), 186
newQuery() (Cake\Database\Connection method), 474
php:global (directive), 186next() (Cake\View\Helper\PaginatorHelper method), php:global (role), 187436
php:meth (role), 187
nice() (Cake\I18n\Time method), 921
php:method (directive), 186
normalize() (Cake\Utility\Hash method), 882
php:staticmethod (directive), 187
normalizeFullPath()(Cake\Filesystem\Folder pj() (global function), 932
method), 865
plugin routing, 241
NotAcceptableException, 715
plugin syntax, 945
NotFoundException, 715
plugin() (Cake\Routing\Router method), 241
notice() (Cake\Log\Log method), 747
pluginSplit() (global function), 933
NotImplementedException, 716
pluralize() (Cake\Utility\Inflector method), 896
Number (class in Cake\I18n), 899
postButton()(Cake\View\Helper\FormHelper
NumberHelper (class in Cake\View\Helper), 427
method), 403
numbers()(Cake\View\Helper\PaginatorHelper postLink() (Cake\View\Helper\FormHelper method),
method), 435
404
numeric() (Cake\Utility\Hash method), 879
pr() (global function), 932
precision() (Cake\I18n\Number method), 901
O
precision()(Cake\View\Helper\NumberHelper
method),428
offset() (Cake\Filesystem\File method), 867
prefers() (RequestHandlerComponent method), 330
open() (Cake\Filesystem\File method), 867
prefix routing, 239
954

Index

CakePHP Book, Release 3.10

prefix() (Cake\Routing\Router method), 239
prepare() (Cake\Filesystem\File method), 867
prepend() (Cake\Collection\Collection method), 855
prependItem() (Cake\Collection\Collection method),855
prev() (Cake\View\Helper\PaginatorHelper method),436
PrivateActionException, 717
properties, 945
pwd() (Cake\Filesystem\File method), 867
pwd() (Cake\Filesystem\Folder method), 865

Q
Query (class in Cake\ORM), 479
query() (Cake\Database\Connection method), 473

Rradio() (Cake\View\Helper\FormHelper method), 383
randomBytes() (Cake\Utility\Security method), 777
randomString() (Cake\Utility\Security method), 777
read() (Cake\Cache\Cache method), 636
read() (Cake\Cache\CacheEngine method), 641
read() (Cake\Controller\Component\CookieComponent
method), 312read() (Cake\Core\Configure method), 223read() (Cake\Filesystem\File method), 867
read() (Cake\Filesystem\Folder method), 865
read() (Cake\View\Helper\SessionHelper method), 445
read() (Session method), 785
readable() (Cake\Filesystem\File method), 867
readMany() (Cake\Cache\Cache method), 637
readOrFail() (Cake\Core\Configure method), 223
realpath() (Cake\Filesystem\Folder method), 865
RecordNotFoundException, 718
redirect() (Cake\Controller\Controller method), 288
redirectUrl() (AuthComponent method), 297
reduce() (Cake\Collection\Collection method), 846
reduce() (Cake\Utility\Hash method), 880
ref (role), 185
referer() (Cake\Http\ServerRequest method), 270
reject() (Cake\Collection\Collection method), 845
remember() (Cake\Cache\Cache method), 636
remove() (Cake\Utility\Hash method), 871
render() (Cake\Controller\Controller method), 287
renderAs() (RequestHandlerComponent method), 330
renew() (Session method), 786
replaceText() (Cake\Filesystem\File method), 867
RequestHandlerComponent (class), 327
requireAuth() (SecurityComponent method), 318
requireSecure() (SecurityComponent method), 318
respondAs() (RequestHandlerComponent method), 330
Response (class in Cake\Http), 272
Response (class in Cake\Http\Client), 891

Index

responseHeader() (Cake\Core\Exception\Exception
method), 718
responseType() (RequestHandlerComponent method),330
restore() (Cake\Core\Configure method), 226
RFC
RFC 2606, 202
RFC 2616#section-10.4, 716
RFC 2616#section-10.5, 716
RFC 4122, 911
ROOT (global constant), 933
Router (class in Cake\Routing), 229
routes.php, 229, 945
routing array, 945
RssHelper (class in Cake\View\Helper), 441
rules() (Cake\Utility\Inflector method), 898

S
safe() (Cake\Filesystem\File method), 867
sample() (Cake\Collection\Collection method), 854
save() (Cake\ORM\Table method), 579
saveMany() (Cake\ORM\Table method), 587
saveOrFail() (Cake\ORM\Table method), 586
script() (Cake\View\Helper\HtmlHelper method), 420
scriptBlock()(Cake\View\Helper\HtmlHelper
method), 421
scriptEnd() (Cake\View\Helper\HtmlHelper method),421
scriptStart()(Cake\View\Helper\HtmlHelper
method), 421
SECOND (global constant), 934
secure() (Cake\View\Helper\FormHelper method), 412
Security (class in Cake\Utility), 775
SecurityComponent (class), 316
select() (Cake\View\Helper\FormHelper method), 385
ServerRequest (class in Cake\Http), 261
ServiceUnavailableException, 716
Session (class), 784
SessionHelper (class in Cake\View\Helper), 444
set() (Cake\Controller\Controller method), 286
set() (Cake\ORM\Entity method), 524
set() (Cake\View\View method), 340
setAction() (Cake\Controller\Controller method), 289
setDescription() (Cake\Console\ConsoleOptionParser
method), 670
setEpilog()(Cake\Console\ConsoleOptionParser
method), 670
setJsonEncodeFormat() (Cake\I18n\Time method),919
setTemplates()(Cake\View\Helper\HtmlHelper
method), 425
setTemplates() (Cake\View\Helper\PaginatorHelper
method), 433
setUser() (AuthComponent method), 304
955

CakePHP Book, Release 3.10

Shell (class in Cake\Console), 679
shuffle() (Cake\Collection\Collection method), 853
singularize() (Cake\Utility\Inflector method), 896
size() (Cake\Filesystem\File method), 867
skip() (Cake\Collection\Collection method), 854
slashTerm() (Cake\Filesystem\Folder method), 865
slug() (Cake\Utility\Inflector method), 898
slug() (Cake\Utility\Text method), 910
some() (Cake\Collection\Collection method), 845
sort (Cake\Filesystem\Folder property), 862
sort() (Cake\Utility\Hash method), 880
sort() (Cake\View\Helper\PaginatorHelper method),434
sortBy() (Cake\Collection\Collection method), 850
sortDir()(Cake\View\Helper\PaginatorHelper
method), 435
sortKey()(Cake\View\Helper\PaginatorHelper
method), 435
stackTrace() (global function), 689
startup() (Cake\Console\Shell method), 686
stopWhen() (Cake\Collection\Collection method), 843
store() (Cake\Core\Configure method), 226
stripLinks() (Cake\Utility\Text method), 913
stripLinks() (Cake\View\Helper\TextHelper method),447
style() (Cake\View\Helper\HtmlHelper method), 414
subcommands, 647
subdomains() (Cake\Http\ServerRequest method), 269
submit() (Cake\View\Helper\FormHelper method), 401
sumOf() (Cake\Collection\Collection method), 847

TimeHelper (class in Cake\View\Helper), 450
TimestampBehavior (class in Cake\ORM\Behavior),
605
TMP (global constant), 934
tokenize() (Cake\Utility\Text method), 911
toList() (Cake\Utility\Text method), 916
toList() (Cake\View\Helper\TextHelper method), 449
toPercentage() (Cake\I18n\Number method), 901
toPercentage()(Cake\View\Helper\NumberHelper
method), 428
toQuarter() (Cake\I18n\Time method), 922
toReadableSize() (Cake\I18n\Number method), 902
toReadableSize() (Cake\View\Helper\NumberHelper
method), 429
total() (Cake\View\Helper\PaginatorHelper method),437
trace() (Cake\Error\Debugger method), 691
trailing star, 231
transactional()(Cake\Database\Connection
method), 474
TranslateBehavior (class in Cake\ORM\Behavior),
607
transliterate() (Cake\Utility\Text method), 910
transpose() (Cake\Collection\Collection method), 853
tree() (Cake\Filesystem\Folder method), 865
TreeBehavior (class in Cake\ORM\Behavior), 615
truncate() (Cake\Utility\Text method), 913
truncate() (Cake\View\Helper\TextHelper method),
447
Type (class in Cake\Database), 468

T

U

Table (class in Cake\ORM), 531
tableCells() (Cake\View\Helper\HtmlHelper method),424
tableHeaders()(Cake\View\Helper\HtmlHelper
method), 423
tableize() (Cake\Utility\Inflector method), 897
TableLocator (class in Cake\ORM), 520
TableSchema (class in Cake\Database\Schema), 626
tail() (Cake\Utility\Text method), 914
tail() (Cake\View\Helper\TextHelper method), 448
take() (Cake\Collection\Collection method), 854
TESTS (global constant), 933
Text (class in Cake\Utility), 909
text() (Cake\View\Helper\FormHelper method), 377
textarea() (Cake\View\Helper\FormHelper method),
378
TextHelper (class in Cake\View\Helper), 445
through() (Cake\Collection\Collection method), 857
Time (class in Cake\I18n), 917
time() (Cake\View\Helper\FormHelper method), 394
TIME_START (global constant), 934
timeAgoInWords() (Cake\I18n\Time method), 922

UnauthorizedException, 715
underscore() (Cake\Utility\Inflector method), 897
unfold() (Cake\Collection\Collection method), 843
unlockField()(Cake\View\Helper\FormHelper
method), 412
updateAll() (Cake\ORM\Table method), 587
url() (Cake\Routing\Router method), 251
UrlHelper (class in Cake\View\Helper), 450
user() (AuthComponent method), 305
uuid() (Cake\Utility\Text method), 911

956

VValidator (class in Cake\Validation), 823
variable() (Cake\Utility\Inflector method), 898
vendor/cakephp-plugins.php, 768
View (class in Cake\View), 337

W
warning() (Cake\Log\Log method), 747
wasWithinLast() (Cake\I18n\Time method), 923
WEEK (global constant), 934
withBody() (Cake\Http\Response method), 274
IndexCakePHP Book, Release 3.10

withCache() (Cake\Http\Response method), 276
withCharset() (Cake\Http\Response method), 275
withDisabledCache() (Cake\Http\Response method),
276
withEtag() (Cake\Http\Response method), 278
withExpires() (Cake\Http\Response method), 277
withFile() (Cake\Http\Response method), 272
withHeader() (Cake\Http\Response method), 274
withModified() (Cake\Http\Response method), 278
withSharable() (Cake\Http\Response method), 277
withStringBody() (Cake\Http\Response method), 274
withType() (Cake\Http\Response method), 272
withUploadedFiles()(Cake\Http\ServerRequest
method), 264
withVary() (Cake\Http\Response method), 279
wrap() (Cake\Utility\Text method), 912
wrapBlock() (Cake\Utility\Text method), 912
writable() (Cake\Filesystem\File method), 867
write() (Cake\Cache\Cache method), 635
write() (Cake\Cache\CacheEngine method), 641
write() (Cake\Controller\Component\CookieComponent
method), 312
write() (Cake\Core\Configure method), 223
write() (Cake\Filesystem\File method), 867
write() (Cake\Log\Log method), 747
write() (Session method), 785
writeMany() (Cake\Cache\Cache method), 636X
Xml (class in Cake\Utility), 927
XmlView (class), 358

Y
YEAR (global constant), 934
year() (Cake\View\Helper\FormHelper method), 395Z
zip() (Cake\Collection\Collection method), 849

Index957