# sfPropelFinder plugin

The `sfPropelFinder` is a symfony plugin that provides an easy API for finding Propel objects - that is, easier than the Peer methods and the Criteria stuff.

## Overview

The idea behind this plugin is to write queries to retrieve Propel objects, but fast. Think of `sfPropelFinder` as "jQuery for Propel". 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.

    
    [php]
    <?php
    // With Peer and Criteria
    $c = new Criteria()
    $c->add(ArticlePeer::TITLE, '%world', Criteria::LIKE);
    $c->add(ArticlePeer::IS_PUBLISHED, true);
    $c->addAscendingOrderByColumn(ArticlePeer::CREATED_AT);
    $articles = ArticlePeer::doSelect($c);
    
    // with sfPropelFinder
    $articles = sfPropelFinder::from('Article')->whereTitle('like', '%world')->whereIsPublished(true)->orderByCreatedAt()->find();
    

`sfPropelFinder` uses the same fluid interface as the `sfFinder`, so you won't be lost.

You can also implement your own business logic to encapsulate complex queries, so that your queries look like real language:

    
    [php]
    <?php
    $finder = new ArticleFinder();
    $articles = $finder->recent()->withComments()->notAnonymous()->wellRated()->find();
    

## Installation

  * Install the plugin
  
        
    [sh]
    > php symfony plugin-install http://plugins.symfony-project.com/sfPropelFinderPlugin
        

  * Clear the cache

        
    [sh]
    > php symfony cc
        

## Usage

### Finding objects

    
    [php]
    <?php
    // Finding all Articles
    $articles = sfPropelFinder::from('Article')->find();
    // Finding 3 Articles
    $articles = sfPropelFinder::from('Article')->find(3);
    // Finding a single Article
    $article = sfPropelFinder::from('Article')->findOne();
    

### Adding WHERE clause

    
    [php]
    <?php
    $articleFinder = sfPropelFinder::from('Article');
    // Finding all Articles where title = 'foo'
    $articles = $articleFinder->whereTitle('foo')->find();
    // Finding all Articles where title like 'foo%'
    $articles = $articleFinder->whereTitle('like', 'foo%')->find();
    // Finding all Articles where published_at less than time()
    $articles = $articleFinder->wherePublishedAt('<', time())->find();
    // The whereXXX method accepts simple or composed column names
    $articles = $articleFinder->whereArticle_PublishedAt('<', time())->find();
    

### Ordering results

    
    [php]
    <?php
    $articleFinder = sfPropelFinder::from('Article');
    // Finding all Articles ordered by created_at ('asc')
    $articles = $articleFinder->orderByCreatedAt()->find();
    // Finding all Articles ordered by created_at desc
    $articles = $articleFinder->orderByCreatedAt('desc')->find();
    

### Counting objects

    
    [php]
    <?php
    // Counting all Articles
    $nbArticles = sfPropelFinder::from('Article')->count();
    

### Combining methods

The methods of the `sfPropelFinder` object return the current finder object, so you can chain them together in a single call, and finish by a `find()` to launch the query.

    
    [php]
    <?php
    // everything chained together
    $articles = sfPropelFinder::from('Article')->whereTitle('like', '%world')->whereIsPublished(true)->orderByCreatedAt()->find();
    // You can write it in several lines, too
    $articles = sfPropelFinder::from('Article')->
      whereTitle('like', '%world')->
      whereIsPublished(true)->
      orderByCreatedAt()->
      find();
    

The syntax should remind you of `sfFinder` and `sfTestBrowser`.

### Joins

    
    [php]
    <?php
    $article1 = new Article();
    $article1->setTitle('Hello, world!');
    $article1->save();
    $comment = new Comment();
    $comment->setContent('You rock!');
    $comment->setArticle($article1);
    $comment->save();
    // Add a join statement
    // No need to tell the finder which columns to use for the join, just the related Class
    // After all, the columns of the FK are already defined in the schema
    $article = sfPropelFinder::from('Article')->
      joinComment()->
      whereComment_Content('You rock!')->
      findOne();
    // You can chain joins if you want to make it more complex
    $article2 = new Article();
    $article2->setTitle('Hello gain, world!');
    $article2->save();
    $author1 = new Author();
    $author1->setName('John');
    $author1->save();
    $comment = new Comment();
    $comment->setContent('You rock!');
    $comment->setArticle($article2);
    $comment->setAuthor($author1);
    $comment->save();
    $article = sfPropelFinder::from('Article')->
      joinComment()->
      joinAuthor()->
      whereAuthor_Name('John')->
      findOne();
    

### Deleting objects

    
    [php]
    <?php
    // Deleting all Articles
    $nbArticles = sfPropelFinder::from('Article')->delete();
    // Deleting a selection of Articles
    $nbArticles = sfPropelFinder::from('Article')->whereTitle('like', 'foo%')->delete();
    

### Writing your own business logic into a finder

You can create a new finder for your objects, with custom methods. The only prerequisites are to extend `sfPropelFinder` and to define a protected `$peerClass` property. Then, the object has access to a protected `$criteria` property, which 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.

For instance, to add a `recent()` method to an article finder:

    
    [php]
    <?php
    class ArticleFinder extends sfPropelFinder
    {
      protected $peerClass = 'ArticlePeer';
    
      public function recent()
      {
        $this->criteria->add(
          ArticlePeer::CREATED_AT,
          time() - sfConfig::get('app_recent_days', 5) * 24 * 60 * 60,
          Criteria::GREATER_THAN
        );
        return $this;
      }
    }
    

### Hacking the finder

If the finder doesn't (yet) provide the method to build the query you need, you can still call `Criteria` methods on the finder objects, and they will be applied to the finder's internal `Criteria` object.

    
    [php]
    <?php
    $articles = sfPropelFinder::from('Article')->
      whereTitle('like', 'foo%')->
      addOr(ArticlePeer::TITLE, 'bar%', Criteria::LIKE)-> // that's a Criteria method
      findOne();
    

If you're not sure about what query is issued by the finder, you can always check the SQL code after executing a termination method (`find()`, `findOne()`, `findPk()`, `count()`, `delete()`) by calling the `getLatestQuery()` method.

    
    [php]
    <?php
    $finder = sfPropelFinder::from('Article')->whereTitle('foo');
    $finder->findOne();
    $query = $finder->getLatestQuery();
    // 'SELECT article.ID, article.VERSION, article.TITLE, article.CATEGORY_ID FROM article WHERE article.TITLE=\'foo\' LIMIT 1'
    

## TODO

  * Allow hydrating of related objects (doSelectJoinXXX equivalent)
  * Add And
  * Add Or
  * Put as a parent class in the PeerBuilder so that every Peer class can be a finder
  * Merge with sfPropelImpersonatorPlugin!

## Changelog

### 2008-03-28 | 0.2.0 Beta

  * francois: Added support for Criteria methods (no more limit to what you can do with a finder!)
  * francois: Added `sfPropelFinder::getLatestQuery()` method
  * francois: Added `sfPropelFinder::delete()` method
  * francois: Added `sfPropelFinder::joinXXX()` method
  * francois: Added `sfPropelFinder::join()` method
  * francois: Added complete `whereClassName_ColumnName()` syntax
  * francois: Added `sfPropelFinder::count()` method
 
### 2008-03-27 | 0.1.0 Alpha

  * francois: Initial public release.