Table Of Content

CakePHP Cookbook Documentation Release 2.x Cake Software Foundation October20,2012 Contents 1 GettingStarted 1 2 BlogTutorial 3 GettingCake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 CreatingtheBlogDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 CakeDatabaseConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 OptionalConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 ANoteonmod_rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3 BlogTutorial-Addingalayer 9 CreateaPostModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 CreateaPostsController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 CreatingPostViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 AddingPosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 DataValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 EditingPosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 DeletingPosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 AdditionalReading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4 Installation 29 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 DownloadingCakePHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 AdvancedInstallationandserverspecificconfiguration . . . . . . . . . . . . . . . . . . . . . . . 32 i FireItUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 5 CakePHPOverview 39 WhatisCakePHP?WhyUseit? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 UnderstandingModel-View-Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 WheretoGetHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 6 Controllers 45 TheAppController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Requestparameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Controlleractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 RequestLife-cyclecallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 ControllerMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 ControllerAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Moreoncontrollers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 7 Views 77 ViewTemplates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Usingviewblocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 ViewAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 MoreaboutViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 8 Models 99 UnderstandingModels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Moreonmodels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 9 CoreLibraries 201 GeneralPurpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 10 Plugins 521 InstallingaPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Pluginconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Advancedbootstrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 UsingaPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 CreatingYourOwnPlugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 PluginControllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 PluginModels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 PluginViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Pluginassets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Components,HelpersandBehaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 ExpandYourPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 PluginTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 ii 11 ConsoleandShells 529 TheCakePHPconsole. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Creatingashell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Shelltasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 Invokingothershellsfromyourshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Consoleoutputlevels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Stylingoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 Configuringoptionsandgeneratinghelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 ShellAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 Moretopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 12 Development 561 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 ErrorHandling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 DispatcherFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 Vendorpackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 13 Deployment 641 Checkyoursecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 Setdocumentroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 Updatecore.php . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 MultipleCakePHPapplicationsusingthesamecore . . . . . . . . . . . . . . . . . . . . . . . . . 642 14 Tutorials&Examples 643 BlogTutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 BlogTutorial-Addingalayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 SimpleAuthenticationandAuthorizationApplication . . . . . . . . . . . . . . . . . . . . . . . . 657 SimpleAclcontrolledApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 SimpleAclcontrolledApplication-part2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 15 Appendices 675 2.3MigrationGuide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 2.2MigrationGuide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 2.1MigrationGuide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686 2.0MigrationGuide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 Migrationfrom1.2to1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 GeneralInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 16 Indicesandtables 753 Index 755 iii iv CHAPTER 1 Getting Started The CakePHP framework provides a robust base for your application. It can handle every aspect, from the user’sinitialrequestallthewaytothefinalrenderingofawebpage. Andsincetheframeworkfollowsthe principlesofMVC,itallowsyoutoeasilycustomizeandextendmostaspectsofyourapplication. Theframeworkalsoprovidesabasicorganizationalstructure,fromfilenamestodatabasetablenames,keep- ingyourentireapplicationconsistentandlogical. Thisconceptissimplebutpowerful. Followtheconven- tionsandyou’llalwaysknowexactlywherethingsareandhowthey’reorganized. ThebestwaytoexperienceandlearnCakePHPistositdownandbuildsomething. Tostartoffwe’llbuild asimpleblogapplication. 1 CakePHP Cookbook Documentation, Release 2.x 2 Chapter 1. Getting Started CHAPTER 2 Blog Tutorial WelcometoCakePHP.You’reprobablycheckingoutthistutorialbecauseyouwanttolearnmoreabouthow CakePHPworks. It’souraimtoincreaseproductivityandmakecodingmoreenjoyable: wehopeyou’llsee thisasyoudiveintothecode. Thistutorialwillwalkyouthroughthecreationofasimpleblogapplication. We’llbegettingandinstalling Cake,creatingandconfiguringadatabase,andcreatingenoughapplicationlogictolist,add,edit,anddelete blogposts. Here’swhatyou’llneed: 1. Arunningwebserver. We’regoingtoassumeyou’reusingApache,thoughtheinstructionsforusing otherserversshouldbeverysimilar. Wemighthavetoplayalittlewiththeserverconfiguration,but most folks can get Cake up and running without any configuration at all. Make sure you have PHP 5.2.8orgreater. 2. Adatabaseserver. We’regoingtobeusingMySQLserverinthistutorial. You’llneedtoknowenough aboutSQLinordertocreateadatabase: Cakewillbetakingthereinsfromthere. Sincewe’reusing MySQL,alsomakesurethatyouhavepdo_mysqlenabledinPHP. 3. Basic PHP knowledge. The more object-oriented programming you’ve done, the better: but fear not ifyou’reaproceduralfan. 4. Finally, you’ll need a basic knowledge of the MVC programming pattern. A quick overview can be foundinUnderstandingModel-View-Controller. Don’tworry,it’sonlyahalfapageorso. Let’sgetstarted! Getting Cake First,let’sgetacopyoffreshCakecode. To get a fresh download, visit the CakePHP project on GitHub: http://github.com/cakephp/cakephp/downloadsanddownloadthelatestreleaseof2.0 3 CakePHP Cookbook Documentation, Release 2.x You can also clone the repository using git (http://git-scm.com/). git clone git://github.com/cakephp/cakephp.git Regardless of how you downloaded it, place the code inside of your DocumentRoot. Once finished, your directorysetupshouldlooksomethinglikethefollowing: /path_to_document_root /app /lib /plugins /vendors .htaccess index.php README Now might be a good time to learn a bit about how Cake’s directory structure works: check out CakePHP FolderStructuresection. Creating the Blog Database Next, lets set up the underlying database for our blog. if you haven’t already done so, create an empty database for use in this tutorial, with a name of your choice. Right now, we’ll just create a single table to storeourposts. We’llalsothrowinafewpostsrightnowtousefortestingpurposes. Executethefollowing SQLstatementsintoyourdatabase: /* First, create our posts table: */ CREATE TABLE posts ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, title VARCHAR(50), body TEXT, created DATETIME DEFAULT NULL, modified DATETIME DEFAULT NULL ); /* Then insert some posts for testing: */ INSERT INTO posts (title,body,created) VALUES (’The title’, ’This is the post body.’, NOW()); INSERT INTO posts (title,body,created) VALUES (’A title once again’, ’And the post body follows.’, NOW()); INSERT INTO posts (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 Cake’s database naming conventions,andCake’sclassnamingconventions(bothoutlinedinCakePHPConventions),you’llbeabletotake advantage of a lot of free functionality and avoid configuration. Cake is flexible enough to accommodate eventheworstlegacydatabaseschema,butadheringtoconventionwillsaveyoutime. Check out CakePHP Conventions for more information, but suffice it to say that naming our table ‘posts’ automaticallyhooksittoourPostmodel,andhavingfieldscalled‘modified’and‘created’willbeautomag- icallymanagedbyCake. 4 Chapter 2. Blog Tutorial