Phalcon PHP Framework Documentation Release 1.2.0 Phalcon Team Mar 23, 2017 Contents 1 What is Phalcon? 3 2 Table of Contents 5 2.1 Our motivation..............................................5 2.1.1 The Question..........................................5 2.1.2 Why?..............................................5 2.1.3 Inner workings of PHP?....................................6 2.1.4 How traditional PHP frameworks work?............................6 2.1.5 How does a PHP C-extension work?..............................6 2.1.6 How does Phalcon work?....................................6 2.1.7 Conclusion...........................................6 2.2 Framework Benchmarks.........................................7 2.2.1 What was the test environment?................................7 2.2.2 List of Benchmarks.......................................7 2.2.3 ChangeLog........................................... 22 2.2.4 External Resources....................................... 23 2.3 Installation................................................ 23 2.3.1 Windows............................................ 23 2.3.2 Linux/Solaris/Mac....................................... 31 2.3.3 FreeBSD............................................ 32 2.3.4 Installation Notes........................................ 32 2.4 Tutorial 1: Let’s learn by example.................................... 41 2.4.1 Checking your installation................................... 41 2.4.2 Creating a project........................................ 43 2.4.3 Conclusion........................................... 52 2.4.4 Sample Applications...................................... 52 2.5 Tutorial 2: Explaining INVO....................................... 53 2.5.1 Project Structure........................................ 53 2.5.2 Routing............................................. 53 2.5.3 Configuration.......................................... 53 2.5.4 Autoloaders........................................... 54 2.5.5 Handling the Request...................................... 55 2.5.6 Dependency Injection...................................... 55 2.5.7 Log into the Application.................................... 56 2.5.8 Securing the Backend...................................... 58 2.5.9 User Components........................................ 62 i 2.5.10 Working with the CRUD.................................... 63 2.5.11 Changing the Title Dynamically................................ 69 2.5.12 Conclusion........................................... 70 2.6 Tutorial 3: Creating a Simple REST API................................ 70 2.6.1 Defining the API........................................ 70 2.6.2 Creating the Application.................................... 70 2.6.3 Creating a Model........................................ 71 2.6.4 Retrieving Data......................................... 73 2.6.5 Inserting Data.......................................... 74 2.6.6 Updating Data.......................................... 75 2.6.7 Deleting Data.......................................... 76 2.6.8 Testing our Application..................................... 76 2.6.9 Conclusion........................................... 78 2.7 List of examples............................................. 78 2.8 Dependency Injection/Service Location................................. 78 2.8.1 Our approach.......................................... 84 2.8.2 Registering services in the Container.............................. 84 2.8.3 Resolving Services....................................... 90 2.8.4 Shared services......................................... 91 2.8.5 Manipulating services individually............................... 91 2.8.6 Instantiating classes via the Service Container......................... 92 2.8.7 Automatic Injecting of the DI itself............................... 92 2.8.8 Avoiding service resolution................................... 93 2.8.9 Organizing services in files................................... 93 2.8.10 Accessing the DI in a static way................................ 94 2.8.11 Factory Default DI....................................... 94 2.8.12 Service Name Conventions................................... 94 2.8.13 Implementing your own DI................................... 95 2.9 The MVC Architecture.......................................... 95 2.9.1 Models............................................. 96 2.9.2 Views.............................................. 96 2.9.3 Controllers........................................... 96 2.10 Using Controllers............................................. 96 2.10.1 Dispatch Loop......................................... 98 2.10.2 Initializing Controllers..................................... 98 2.10.3 Injecting Services........................................ 99 2.10.4 Request and Response..................................... 100 2.10.5 Session Data.......................................... 101 2.10.6 Using Services as Controllers.................................. 101 2.10.7 Creating a Base Controller................................... 102 2.10.8 Events in Controllers...................................... 103 2.11 Working with Models.......................................... 103 2.11.1 Creating Models........................................ 103 2.11.2 Models in Namespaces..................................... 105 2.11.3 Understanding Records To Objects............................... 105 2.11.4 Finding Records......................................... 106 2.11.5 Initializing fetched records................................... 111 2.11.6 Relationships between Models................................. 111 2.11.7 Virtual Foreign Keys...................................... 119 2.11.8 Generating Calculations.................................... 120 2.11.9 Hydration Modes........................................ 122 2.11.10 Creating Updating/Records................................... 123 2.11.11 Skipping Columns....................................... 134 2.11.12 Deleting Records........................................ 136 ii 2.11.13 Validation Failed Events.................................... 137 2.11.14 Behaviors............................................ 137 2.11.15 Transactions........................................... 142 2.11.16 Independent Column Mapping................................. 145 2.11.17 Operations over Resultsets................................... 146 2.11.18 Record Snapshots........................................ 147 2.11.19 Models Meta-Data....................................... 148 2.11.20 Pointing to a different schema................................. 152 2.11.21 Setting multiple databases................................... 152 2.11.22 Logging Low-Level SQL Statements.............................. 154 2.11.23 Profiling SQL Statements.................................... 155 2.11.24 Injecting services into Models................................. 156 2.11.25 Disabling/Enabling Features.................................. 157 2.11.26 Stand-Alone component.................................... 157 2.12 Phalcon Query Language (PHQL).................................... 158 2.12.1 Usage Example......................................... 158 2.12.2 Creating PHQL Queries.................................... 159 2.12.3 Selecting Records........................................ 160 2.12.4 Inserting Data.......................................... 165 2.12.5 Updating Data.......................................... 166 2.12.6 Deleting Data.......................................... 167 2.12.7 Creating queries using the Query Builder........................... 167 2.12.8 Disabling Literals........................................ 170 2.12.9 Escaping Reserved Words................................... 171 2.12.10 PHQL Lifecycle......................................... 171 2.12.11 Using Raw SQL......................................... 171 2.12.12 Troubleshooting......................................... 172 2.13 Caching in the ORM........................................... 173 2.13.1 Caching Resultsets....................................... 173 2.13.2 Overriding find/findFirst.................................... 174 2.13.3 Forcing Cache.......................................... 177 2.13.4 Caching PHQL Queries..................................... 178 2.13.5 Reusable Related Records................................... 178 2.13.6 Caching Related Records.................................... 180 2.13.7 Caching Related Records Recursively............................. 181 2.13.8 Caching based on Conditions.................................. 183 2.13.9 Caching of PHQL planning................................... 186 2.14 ODM (Object-Document Mapper).................................... 187 2.14.1 Creating Models........................................ 188 2.14.2 Understanding Documents To Objects............................. 188 2.14.3 Models in Namespaces..................................... 188 2.14.4 Setting a Connection...................................... 189 2.14.5 Finding Documents....................................... 189 2.14.6 Aggregations.......................................... 191 2.14.7 Creating Updating/Records................................... 191 2.14.8 Deleting Records........................................ 197 2.14.9 Validation Failed Events.................................... 198 2.14.10 Implicit Ids vs. User Primary Keys............................... 198 2.14.11 Setting multiple databases................................... 198 2.14.12 Injecting services into Models................................