Changeset 10809 for plugins/sfPropelFinderPlugin/README
- Timestamp:
- 08/12/08 15:40:27 (3 months ago)
- Files:
-
- plugins/sfPropelFinderPlugin/README (modified) (26 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
plugins/sfPropelFinderPlugin/README
r10808 r10809 18 18 The idea behind this plugin is to write queries to retrieve model objects through an ORM, but fast. Inspired by Doctrine, Rails has_finder plugin and SQLAlchemy, `DbFinder` can be seen as "jQuery for symfony's model layer". It also aims at putting the things in the right order, meaning that writing a `find()` query will feel natural for those familiar with SQL. 19 19 20 [php] 20 21 // With Propel Peer and Criteria 21 22 $c = new Criteria() … … 37 38 You can also implement your own business logic to encapsulate complex queries, so that your queries look like real language: 38 39 40 [php] 39 41 // ArticleFinder extends sfPropelFinder. See how below 40 42 $finder = new ArticleFinder(); … … 57 59 ### Finding objects 58 60 61 [php] 59 62 // Finding all Articles 60 63 $articles = DbFinder::from('Article')->find(); … … 70 73 ### Adding WHERE clause 71 74 75 [php] 72 76 $articleFinder = DbFinder::from('Article'); 73 77 // Finding all Articles where title = 'foo' … … 99 103 ### Ordering results 100 104 105 [php] 101 106 $articleFinder = DbFinder::from('Article'); 102 107 // Finding all Articles ordered by created_at (ascending order by default) … … 117 122 The methods of the `DbFinder` object return the current finder object, so you can chain them together in a single call, and finish by any of the `find()` methods to launch the query. 118 123 124 [php] 119 125 // everything chained together 120 126 $articles = DbFinder::from('Article')->where('Title', 'like', '%world')->where('IsPublished', true)->orderBy('CreatedAt')->find(); … … 130 136 ### Finding records related to another one 131 137 138 [php] 132 139 // Propel way 133 140 $comments = $article->getComments(); … … 144 151 Since the finder way is longer than the native Propel way, what is the interest of using this `relatedTo()`? You get a `DbFinder` object when you use `relatedTo()`, so it allows you to do things that the generated Propel getter don't allow: 145 152 153 [php] 146 154 // Retrieving the related comments, orderd by date 147 155 $comments = $commentFinder-> … … 158 166 **Tip**: Alternatively, a finder can be initialized from an array of Propel object. The resulting SQL query contains a 'IN ()' clause, so use this possibility with caution. 159 167 168 [php] 160 169 // Retrieving the last one of the related comments 161 170 $comments = DbFinder::from($article->getComments())-> … … 164 173 ### Joins 165 174 175 [php] 166 176 // Test data 167 177 $article1 = new Article(); … … 241 251 ### Complex logic 242 252 253 [php] 243 254 // where() and orWhere() only allow simple logical operations on a single condition 244 255 // For more complex logic, you have to use combine() … … 282 293 Even if you do a Join, Propel or Doctrine will issue new queries when you fetch related objects: 283 294 295 [php] 284 296 $comment = DbFinder::from('Comment')-> 285 297 join('Article')-> … … 290 302 Just as Propel offers generated `doSelectJoinXXX()` methods, `DbFinder` allows you to hydrate related objects in a single query - you just have to call the `with()` method to specify which objects the main object should be hydrated with. 291 303 304 [php] 292 305 $comment = DbFinder::from('Comment')-> 293 306 with('Article')-> … … 299 312 The power of the `with()` method is that it can guess relationships just as well as `join()`, and will add the call to `join()` if you didn't do it yourself. So you can do for instance: 300 313 314 [php] 301 315 $category1 = new Category(); 302 316 $category1->setName('Category1'); … … 321 335 The `with()` method can also hydrate the related I18n objects, thus providing an equivalent to symfony's `doSelectWithI18n()` methods. 322 336 337 [php] 323 338 // Consider the following schema 324 339 //article: … … 349 364 Warning: The `withColumn()` feature requires symfony's Behavior system. It will only work if you enable behaviors in `propel.ini` and rebuild your model afterwards. 350 365 366 [php] 351 367 $article = DbFinder::from('Article')-> 352 368 join('Category')-> … … 395 411 ### Counting objects 396 412 413 [php] 397 414 // Counting all Articles 398 415 $nbArticles = DbFinder::from('Article')->count(); … … 400 417 ### Getting a paginated list of results 401 418 419 [php] 402 420 // Getting an initialized sfPropelPager object 403 421 $pager = DbFinder::from('Article')->paginate($currentPage = 1, $maxResultsPerPage = 10); … … 414 432 ### Deleting objects 415 433 434 [php] 416 435 // Deleting all Articles 417 436 $nbArticles = DbFinder::from('Article')->delete(); … … 423 442 ### Updating objects 424 443 444 [php] 425 445 $article1 = new Article; 426 446 $article1->setTitle('foo'); … … 453 473 For instance, you can create an child of `DbFinder` to retrieve Propel `Article` objects. This new finder has access to a protected query object by way of `getQueryObject()`. This object is a Propel Criteria that can be augmented in the usual way. Don't forget to return the current object (`$this`) in the new methods. 454 474 475 [php] 455 476 class ArticleFinder extends DbFinder 456 477 { … … 471 492 **Tip**: Once you define an `ArticleFinder` class, any call to `DbFinder::from('Article')` will return an instance of `ArticleFinder` instead of an instance of `DbFinder`. So the following also works: 472 493 494 [php] 473 495 $articleFinder = DbFinder::from('Article')-> 474 496 recent()-> … … 480 502 ### Finding Objects From A Primary Key 481 503 504 [php] 482 505 $article = DbFinder::from('Article')->findPk(123); 483 506 // is equivalent to … … 496 519 ### Using Class Shortcuts 497 520 521 [php] 498 522 $article = DbFinder::from('Article a')-> 499 523 where('a.Title', 'foo')-> … … 508 532 If the finder doesn't (yet) provide the method to build the query you need, you can still call `Criteria` methods on the `sfPropelFinder` objects, or call `Doctrine_Query` methods on the `sfDoctrineFinder` objects, and they will be applied to the finder's internal query object. 509 533 534 [php] 510 535 $articles = DbFinder::from('Article')-> 511 536 where('Title', 'like', 'foo%')-> … … 515 540 If you're not sure about what query is issued by the finder, you can always check the SQL code before executing a termination method by calling `getCriteria()->toString()`, or after executing a termination method by calling the `getLatestQuery()` method. 516 541 542 [php] 517 543 $finder = DbFinder::from('Article')->where('Title', 'foo'); 518 544 echo $finder->getCriteria()->toString();
