Doctrine ORM for PHP.pdf

Table of Contents Introduction....................................................................................................13 Code Examples........................................................................................................13 What is Doctrine?....................................................................................................13 What is an ORM?.....................................................................................................13 What is the Problem?...............................................................................................13 Minimum Requirements..........................................................................................14 Basic Overview........................................................................................................14 Doctrine Explained..................................................................................................15 Key Concepts...........................................................................................................16 Further Reading......................................................................................................17 Conclusion...............................................................................................................17 Getting Started...............................................................................................18 Checking Requirements...........................................................................................18 Installing..................................................................................................................19 Sandbox..............................................................................................................................19 SVN.....................................................................................................................................19 Installing.........................................................................................................................................19 Updating.........................................................................................................................................20 SVN Externals....................................................................................................................20 PEAR Installer....................................................................................................................20 Download Pear Package.....................................................................................................21 Implementing...........................................................................................................21 Including Doctrine Libraries..............................................................................................21 Require Doctrine Base Class..............................................................................................21 Register Autoloader............................................................................................................22 Autoloading Explained....................................................................................................................22 Bootstrap File.....................................................................................................................23 Test Script..........................................................................................................................23 Conclusion...............................................................................................................24 Introduction to Connections...........................................................................25 DSN, the Data Source Name...................................................................................25 Examples............................................................................................................................27 Opening New Connections......................................................................................27 Lazy Database Connecting......................................................................................28 Testing your Connection..........................................................................................28 Conclusion...............................................................................................................29 Configuration..................................................................................................30 Levels of Configuration............................................................................................30 Portability................................................................................................................31 Portability Mode Attributes................................................................................................31 Table of Contents ii ----------------- Brought to you by Examples............................................................................................................................32 Identifier quoting.....................................................................................................32 Exporting.................................................................................................................33 Naming convention attributes.................................................................................34 Index name format.............................................................................................................34 Sequence name format.......................................................................................................34 Table name format.............................................................................................................34 Database name format.......................................................................................................34 Validation attributes...........................................................................................................35 Validation mode constants.................................................................................................35 Examples............................................................................................................................35 Optional String Syntax............................................................................................35 Conclusion...............................................................................................................36 Connections....................................................................................................37 Introduction.............................................................................................................37 Opening Connections...............................................................................................37 Retrieve Connections...............................................................................................37 Current Connection.................................................................................................38 Change Current Connection....................................................................................38 Iterating Connections..............................................................................................38 Get Connection Name..............................................................................................38 Close Connection.....................................................................................................39 Get All Connections.................................................................................................39 Count Connections...................................................................................................40 Creating and Dropping Database............................................................................40 Conclusion...............................................................................................................40 Introduction to Models...................................................................................42 Introduction.............................................................................................................42 Generating Models..................................................................................................42 Existing Databases.............................................................................................................43 Making the first import...................................................................................................................43 Schema Files......................................................................................................................46 Manually Writing Models........................................................................................48 Autoloading Models.................................................................................................48 Conservative.......................................................................................................................48 Aggressive..........................................................................................................................49 Conclusion...............................................................................................................50 Defining Models..............................................................................................51 Columns...................................................................................................................51 Column Lengths.................................................................................................................51 Column Aliases...................................................................................................................52 Default values.....................................................................................................................52 Data types...........................................................................................................................53 Introduction....................................................................................................................................53 Type modifiers................................................................................................................................54 Boolean...........................................................................................................................................54 Integer............................................................................................................................................55 Float................................................................................................................................................55 Decimal...........................................................................................................................................56 String..............................................................................................................................................57 Array...............................................................................................................................................57 Object.............................................................................................................................................58 Table of Contents iii ----------------- Brought to you by Blob.................................................................................................................................................58 Clob.................................................................................................................................................58 Timestamp......................................................................................................................................59 Time................................................................................................................................................59 Date................................................................................................................................................60 Enum...............................................................................................................................................60 Gzip.................................................................................................................................................61 Examples............................................................................................................................61 Relationships...........................................................................................................64 Introduction........................................................................................................................64 Foreign Key Associations...................................................................................................69 One to One......................................................................................................................................69 One to Many and Many to One.......................................................................................................70 Tree Structure................................................................................................................................72 Join Table Associations.......................................................................................................73 Many to Many.................................................................................................................................73 Self Referencing (Nest Relations)..................................................................................................77 Non-Equal Nest Relations............................................................................................................................77 Equal Nest Relations....................................................................................................................................78 Foreign Key Constraints.....................................................................................................80 Introduction....................................................................................................................................80 Integrity Actions.............................................................................................................................82 Indexes.....................................................................................................................84 Introduction........................................................................................................................84 Adding indexes...................................................................................................................84 Index options......................................................................................................................86 Special indexes...................................................................................................................87 Checks.....................................................................................................................87 Table Options...........................................................................................................88 Transitive Persistence.............................................................................................89 Application-Level Cascades................................................................................................89 Save Cascades................................................................................................................................90 Delete Cascades..............................................................................................................................90 Database-Level Cascades...................................................................................................91 Conclusion...............................................................................................................92 Working with Models......................................................................................93 Define Test Schema.................................................................................................93 Dealing with Relations.............................................................................................97 Creating Related Records..................................................................................................97 Retrieving Related Records................................................................................................99 Updating Related Records................................................................................................100 Deleting Related Records.................................................................................................100 Working with Related Records.........................................................................................101 Testing the Existence of a Relation..............................................................................................101 Many-to-Many Relations........................................................................................102 Creating a New Link.........................................................................................................102 Deleting a Link.................................................................................................................102 Fetching Objects....................................................................................................103 Sample Queries................................................................................................................105 Field Lazy Loading...........................................................................................................111 Arrays and Objects................................................................................................112 To Array............................................................................................................................112 From Array.......................................................................................................................112 Synchronize With Array....................................................................................................112 Overriding the Constructor...................................................................................113 Conclusion.............................................................................................................114 Table of Contents iv ----------------- Brought to you by DQL (Doctrine Query Language)..................................................................115 Introduction...........................................................................................................115 SELECT queries.....................................................................................................117 Aggregate values..............................................................................................................121 UPDATE queries....................................................................................................122 DELETE Queries....................................................................................................123 FROM clause.........................................................................................................124 JOIN syntax............................................................................................................124 ON keyword......................................................................................................................126 WITH keyword..................................................................................................................126 INDEXBY keyword.................................................................................................127 WHERE clause.......................................................................................................128 Conditional expressions.........................................................................................129 Literals.............................................................................................................................129 Input parameters..............................................................................................................131 Operators and operator precedence................................................................................132 In expressions...................................................................................................................133 Like Expressions...............................................................................................................134 Exists Expressions............................................................................................................135 All and Any Expressions...................................................................................................137 Subqueries........................................................................................................................137 Functional Expressions..........................................................................................139 String functions................................................................................................................139 Arithmetic functions.........................................................................................................141 Subqueries.............................................................................................................141 Introduction......................................................................................................................141 Comparisons using subqueries.........................................................................................141 GROUP BY, HAVING clauses.................................................................................142 ORDER BY clause..................................................................................................144 Introduction......................................................................................................................144 Sorting by an aggregate value.........................................................................................145 Using random order.........................................................................................................145 LIMIT and OFFSET clauses...................................................................................146 Driver Portability..............................................................................................................146 The limit-subquery-algorithm...........................................................................................147 Named Queries......................................................................................................148 Creating a Named Query..................................................................................................149 Accessing Named Query...................................................................................................149 Executing a Named Query................................................................................................150 Cross-Accessing Named Query........................................................................................150 BNF........................................................................................................................150 Magic Finders........................................................................................................154 Debugging Queries................................................................................................155 Conclusion.............................................................................................................155 Component Overview....................................................................................156 Manager.................................................................................................................156 Retrieving Connections....................................................................................................156 Connection.............................................................................................................157 Available Drivers..............................................................................................................157 Creating Connections.......................................................................................................157 Flushing the Connection..................................................................................................157 Table......................................................................................................................158 Table of Contents v ----------------- Brought to you by Getting a Table Object......................................................................................................158 Getting Column Information.............................................................................................158 Getting Relation Information............................................................................................159 Finder Methods................................................................................................................161 Custom Table Classes...................................................................................................................162 Custom Finders................................................................................................................162 Record....................................................................................................................163 Properties.........................................................................................................................163 Updating Records.............................................................................................................166 Replacing Records............................................................................................................167 Refreshing Records..........................................................................................................167 Refreshing relationships...................................................................................................168 Deleting Records..............................................................................................................169 Using Expression Values..................................................................................................170 Getting Record State........................................................................................................170 Getting Object Copy.........................................................................................................171 Saving a Blank Record.....................................................................................................172 Mapping Custom Values...................................................................................................172 Serializing.........................................................................................................................172 Checking Existence..........................................................................................................172 Function Callbacks for Columns......................................................................................173 Collection...............................................................................................................173 Accessing Elements..........................................................................................................173 Adding new Elements.......................................................................................................174 Getting Collection Count..................................................................................................174 Saving the Collection........................................................................................................175 Deleting the Collection.....................................................................................................175 Key Mapping.....................................................................................................................175 Loading Related Records.................................................................................................176 Validator................................................................................................................177 More Validation................................................................................................................178 Valid or Not Valid.............................................................................................................179 Implicit Validation........................................................................................................................179 Explicit Validation.........................................................................................................................179 Profiler...................................................................................................................180 Basic Usage......................................................................................................................181 Locking Manager...................................................................................................181 Optimistic Locking...........................................................................................................181 Pessimistic Locking..........................................................................................................182 Examples..........................................................................................................................182 Technical Details..............................................................................................................183 Views......................................................................................................................183 Using Views......................................................................................................................183 Conclusion.............................................................................................................184 Native SQL....................................................................................................185 Introduction...........................................................................................................185 Component Queries...............................................................................................185 Fetching from Multiple Components.....................................................................186 Conclusion.............................................................................................................187 YAML Schema Files.......................................................................................188 Introduction...........................................................................................................188 Abbreviated Syntax................................................................................................188 Verbose Syntax......................................................................................................189 Table of Contents vi ----------------- Brought to you by Relationships.........................................................................................................189 Detect Relations...............................................................................................................190 Customizing Relationships...............................................................................................190 One to One........................................................................................................................191 One to Many.....................................................................................................................191 Many to Many...................................................................................................................192 Features & Examples.............................................................................................193 Connection Binding..........................................................................................................193 Attributes..........................................................................................................................193 Enums...............................................................................................................................194 ActAs Behaviors................................................................................................................194 Listeners...........................................................................................................................195 Options.............................................................................................................................196 Indexes.............................................................................................................................196 Inheritance.......................................................................................................................197 Simple Inheritance.......................................................................................................................197 Concrete Inheritance....................................................................................................................197 Column Aggregation Inheritance.................................................................................................198 Column Aliases.................................................................................................................199 Packages...........................................................................................................................199 Package Custom Path...................................................................................................................199 Global Schema Information..............................................................................................199 Using Schema Files...............................................................................................200 Conclusion.............................................................................................................201 Data Validation.............................................................................................202 Introduction...........................................................................................................202 Examples................................................................................................................204 Not Null............................................................................................................................204 Email.................................................................................................................................205 Not Blank..........................................................................................................................206 No Space..........................................................................................................................207 Past...................................................................................................................................208 Future...............................................................................................................................208 Min Length.......................................................................................................................209 Country.............................................................................................................................210 IP Address........................................................................................................................211 HTML Color......................................................................................................................212 Range................................................................................................................................213 Unique..............................................................................................................................214 Regular Expression..........................................................................................................215 Credit Card.......................................................................................................................216 Read Only.........................................................................................................................217 Unsigned..........................................................................................................................217 US State...........................................................................................................................218 Conclusion.............................................................................................................219 Inheritance....................................................................................................220 Simple....................................................................................................................220 Concrete................................................................................................................221 Column Aggregation..............................................................................................224 Conclusion.............................................................................................................227 Behaviors......................................................................................................228 Introduction...........................................................................................................228 Simple Templates..................................................................................................229 Table of Contents vii ----------------- Brought to you by Templates with Relations......................................................................................230 Delegate Methods..................................................................................................234 Creating Behaviors................................................................................................235 Core Behaviors......................................................................................................236 Introduction......................................................................................................................236 Versionable.......................................................................................................................236 Timestampable.................................................................................................................238 Sluggable..........................................................................................................................240 I18n..................................................................................................................................242 NestedSet.........................................................................................................................244 Searchable........................................................................................................................246 Geographical....................................................................................................................247 SoftDelete.........................................................................................................................250 Nesting Behaviors..................................................................................................252 Generating Files....................................................................................................253 Querying Generated Classes.................................................................................254 Conclusion.............................................................................................................255 Searching......................................................................................................256 Introduction...........................................................................................................256 Index structure......................................................................................................258 Index Building........................................................................................................258 Text Analyzers.......................................................................................................259 Query language......................................................................................................260 Performing Searches.............................................................................................260 File searches..........................................................................................................263 Conclusion.............................................................................................................264 Hierarchical Data..........................................................................................265 Introduction...........................................................................................................265 Nested Set.............................................................................................................266 Introduction......................................................................................................................266 Setting Up........................................................................................................................266 Multiple Trees..................................................................................................................267 Working with Trees..........................................................................................................267 Creating a Root Node...................................................................................................................268 Inserting a Node...........................................................................................................................268 Deleting a Node............................................................................................................................268 Moving a Node..............................................................................................................................269 Examining a Node.........................................................................................................................269 Examining and Retrieving Siblings..............................................................................................270 Examining and Retrieving Descendants.......................................................................................270 Rendering a Simple Tree..............................................................................................................271 Advanced Usage...............................................................................................................271 Fetching a Tree with Relations.....................................................................................................272 Rendering with Indention.................................................................................................273 Conclusion.............................................................................................................273 Data Fixtures.................................................................................................274 Importing...............................................................................................................274 Dumping................................................................................................................274 Implement..............................................................................................................275 Writing...................................................................................................................275 Fixtures For Nested Sets.......................................................................................279 Fixtures For I18n...................................................................................................280 Table of Contents viii ----------------- Brought to you by Conclusion.............................................................................................................280 Database Abstraction Layer..........................................................................281 Export....................................................................................................................281 Introduction......................................................................................................................281 Creating Databases..........................................................................................................282 Creating Tables................................................................................................................282 Creating Foreign Keys......................................................................................................284 Altering table....................................................................................................................285 Creating Indexes..............................................................................................................287 Deleting database elements.............................................................................................287 Import....................................................................................................................288 Introduction......................................................................................................................288 Listing Databases.............................................................................................................289 Listing Sequences............................................................................................................289 Listing Constraints...........................................................................................................289 Listing Table Columns......................................................................................................289 Listing Table Indexes.......................................................................................................289 Listing Tables...................................................................................................................290 Listing Views....................................................................................................................290 DataDict.................................................................................................................290 Introduction......................................................................................................................290 Getting portable declaration............................................................................................290 Getting Native Declaration...............................................................................................291 Drivers...................................................................................................................291 Mysql................................................................................................................................291 Setting table type.........................................................................................................................291 Conclusion.............................................................................................................292 Transactions..................................................................................................293 Introduction...........................................................................................................293 Nesting..................................................................................................................294 Savepoints.............................................................................................................295 Isolation Levels......................................................................................................296 Conclusion.............................................................................................................297 Event Listeners.............................................................................................298 Introduction...........................................................................................................298 Connection Listeners.............................................................................................299 Creating a New Listener..................................................................................................299 Attaching listeners...........................................................................................................300 Pre and Post Connect.......................................................................................................300 Transaction Listeners.......................................................................................................301 Query Execution Listeners...............................................................................................301 Hydration Listeners...............................................................................................302 Record Listeners....................................................................................................303 Record Hooks.........................................................................................................304 DQL Hooks.............................................................................................................305 Chaining Listeners.................................................................................................308 The Event object....................................................................................................308 Getting the Invoker..........................................................................................................308 Event Codes......................................................................................................................308 Getting the Invoker..........................................................................................................308 Skip Next Operation.........................................................................................................309 Skip Next Listener............................................................................................................310 Table of Contents ix ----------------- Brought to you by Conclusion.............................................................................................................310 Caching.........................................................................................................311 Introduction...........................................................................................................311 Drivers...................................................................................................................311 Memcache........................................................................................................................311 APC...................................................................................................................................312 Db.....................................................................................................................................312 Query Cache & Result Cache................................................................................313 Introduction......................................................................................................................313 Query Cache.....................................................................................................................313 Using the Query Cache.................................................................................................................313 Fine Tuning...................................................................................................................................314 Result Cache.....................................................................................................................314 Using the Result Cache................................................................................................................314 Fine Tuning...................................................................................................................................315 Conclusion.............................................................................................................315 Migrations.....................................................................................................316 Performing Migrations..........................................................................................316 Implement..............................................................................................................317 Writing Migration Classes.....................................................................................317 Available Operations........................................................................................................319 Create Table.................................................................................................................................319 Drop Table....................................................................................................................................319 Rename Table...............................................................................................................................320 Create Constraint.........................................................................................................................320 Drop Constraint............................................................................................................................320 Create Foreign Key.......................................................................................................................320 Drop Foreign Key..........................................................................................................................321 Add Column..................................................................................................................................321 Rename Column............................................................................................................................321 Change Column............................................................................................................................321 Remove Column............................................................................................................................322 Irreversible Migration..................................................................................................................322 Add Index......................................................................................................................................322 Remove Index...............................................................................................................................322 Pre and Post Hooks..........................................................................................................322 Generating Migrations.....................................................................................................323 From Database.............................................................................................................................324 From Existing Models...................................................................................................................324 Conclusion.............................................................................................................324 Utilities..........................................................................................................325 Pagination..............................................................................................................325 Introduction......................................................................................................................325 Working with Pager..........................................................................................................325 Controlling Range Styles..................................................................................................327 Sliding...........................................................................................................................................328 Jumping.........................................................................................................................................328 Advanced layouts with pager...........................................................................................329 Mask.............................................................................................................................................329 Template.......................................................................................................................................330 Customizing pager layout.................................................................................................332 Facade...................................................................................................................335 Creating & Dropping Databases......................................................................................335 Convenience Methods......................................................................................................335 Tasks.................................................................................................................................337 Table of Contents x ----------------- Brought to you by Command Line Interface.......................................................................................338 Introduction......................................................................................................................338 Tasks.................................................................................................................................338 Usage................................................................................................................................339 Sandbox.................................................................................................................339 Installation........................................................................................................................339 Conclusion.............................................................................................................340 Unit Testing..................................................................................................341 Running tests.........................................................................................................341 CLI....................................................................................................................................341 Browser............................................................................................................................342 Writing Tests.........................................................................................................342 Ticket Tests......................................................................................................................343 Methods for testing..........................................................................................................343 Assert Equal..................................................................................................................................343 Assert Not Equal...........................................................................................................................344 Assert Identical.............................................................................................................................344 Assert True...................................................................................................................................344 Assert False..................................................................................................................................344 Mock Drivers....................................................................................................................344 Test Class Guidelines.......................................................................................................345 Test Method Guidelines....................................................................................................345 Conclusion.............................................................................................................346 Improving Performance................................................................................347 Introduction...........................................................................................................347 Compile..................................................................................................................347 Conservative Fetching...........................................................................................348 Bundle your Class Files.........................................................................................350 Use a Bytecode Cache...........................................................................................350 Free Objects...........................................................................................................350 Other Tips..............................................................................................................351 Conclusion.............................................................................................................352 Technology....................................................................................................353 Introduction...........................................................................................................353 Architecture...........................................................................................................353 Doctrine CORE.................................................................................................................353 Doctrine DBAL..................................................................................................................354 Doctrine ORM...................................................................................................................354 Design Patterns Used............................................................................................354 Speed.....................................................................................................................355 Conclusion.............................................................................................................356 Exceptions and Warnings.............................................................................357 Manager exceptions...............................................................................................357 Relation exceptions.............................