= 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->wherePublisheAt('<', 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();
}}}

=== 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`.

=== 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 acces to a protected `$criteria` proprty, whici is a Propel Criteria that can be augmented in the usual wqy. 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;
  }
}
}}}

== TODO ==

 * Handle Joins
 * Add more magic!
 * Merge with sfPropelImpersonatorPlugin ?

== Changelog ==

=== 2008-03-27 | 0.1.0 alpha ===

 * francois: Initial public release.