Let’s say you want to add a custom column to your query, let’s say “points remaining” for the sake of example.

  $c->addAsColumn('points_remaining', '('.UserPointsPeer::TOTAL_POINTS.' - '.UserPointsPeer::POINTS_EARNED.')');

And now you want to limit your query to just users who have a certain number of points remaining. Since this is on a custom column, you have to use the addHaving() method. This gets a bit more tricky because when adding criteria based on custom columns, Propel wants to generate criterion objects using column names which include the column’s table name and dot separator. So, we have to rely on the Criteria::CUSTOM functionality. No doubt this is a hack and it completely circumvents any built-in query escaping that is essential, but if you are careful about sanitizing your input, you can do the following. Note this code sample assumes that $pointsFilter['from'] and $pointsFilter['to'] contain the GET or POST input parameters for use in your query:

// first version where we want to fetch a custom column
if (!empty($pointsFilter['from'])) {
  $pointsFilter['from'] = (int) $pointsFilter['from'];
  $criterion = $c->getNewCriterion(UserPointsPeer::ID, 'points_remaining >= '.$pointsFilter['from'], Criteria::CUSTOM);
}
 
if (!empty($pointsFilter['to'])) {
  $pointsFilter['to'] = (int) $pointsFilter['to'];
  if (isset($criterion)) {
    $criterion->addAnd($c->getNewCriterion(UserPointsPeer::ID, 'points_remaining <= '.$pointsFilter['to'], Criteria::CUSTOM));
  } else {
    $criterion = $c->getNewCriterion(UserPointsPeer::ID, 'points_remaining <= '.$pointsFilter['to'], Criteria::CUSTOM);
  }
}
 
if (isset($criterion)) {
  $c->addHaving($criterion);
}

Note that we have to use addHaving() to add our condition to our custom column.

If you don’t need to retrieve the custom column in your query but still want to limit your results on that criteria, you can use the add() method, but you have to change it up a bit:

// second version without adding a custom column
if (!empty($pointsFilter['from'])) {
  $pointsFilter['from'] = (int) $pointsFilter['from'];
  $criterion = $c->getNewCriterion(
    UserPointsPeer::ID, // can be any column in your table, really
    '('.CurriculumPeer::TOTAL_POINTS.' - '.UserPointsPeer::POINTS_EARNED.') >= '.$pointsFilter['from'], 
    Criteria::CUSTOM
  );
}
 
if (!empty($pointsFilter['to'])) {
  $pointsFilter['to'] = (int) $pointsFilter['to'];
  $pointsFilterToCriterion = $c->getNewCriterion(
    UserPointsPeer::ID, 
    '('.CurriculumPeer::TOTAL_POINTS.' - '.UserPointsPeer::POINTS_EARNED.') <= '.$pointsFilter['to'],
    Criteria::CUSTOM
  );
 
  if (isset($criterion)) {
    $criterion->addAnd($pointsFilterToCriterion);
  } else {
    $criterion = $pointsFilterToCriterion;
  }
}
 
if (isset($criterion)) {
  $c->add($criterion);
}

Note that in this example I’m typecasting our input parameters are integers, but you could mysql_real_escape_string() or any other sanitizing method you like.

1) Use another table to list the enum options. Pros: most flexible. Works nicely within symfony. Cons: means more joins in your queries.

2) Use enum anyway. You can add custom column types using a little known trick in your schema:

status:
  id:
  name: { type: varchar, sqltype:enum, size: "'inactive','active'", default: inactive }

Pros: You get your enum. Cons: Not very portable, a bit of a hack.

3) Simulate an enum column using your model. I typically end up doing this for columns that have a finite number of defined options *that will not change*. Pros: Fast. Cons: Not as flexible as optino 1. Example:

class UserProfilePeer extends BaseUserProfilePeer
{
  static protected $USER_TYPE_INTEGERS = array('student', 'supervisor', 'coordinator', 'researcher', 'admin');
  static protected $USER_TYPE_VALUES = null;

  /**
   * Returns a user type label from an index value.
   *
   * @param integer $index
   * @return string user type label
   * @author Scott Meves
   */
  static public function getUserTypeFromIndex($index)
  {
    return self::$USER_TYPE_INTEGERS[$index];
  }

  /**
   * Returns the user type index from a string value
   *
   * @param string $value
   * @return integer $index
   * @author Scott Meves
   */
  static public function getUserTypeFromValue($value)
  {
    if (!self::$USER_TYPE_VALUES)
    {
      self::$USER_TYPE_VALUES = array_flip(self::$USER_TYPE_INTEGERS);
    }

    $values = strtolower($value);

    if (!isset(self::$USER_TYPE_VALUES[$value]))
    {
      throw new PropelException(sprintf('User type cannot take "%s" as a value', $value));
    }

    return self::$USER_TYPE_VALUES[strtolower($value)];
  }

  public static function getUserTypeOptions()
  {
    return self::$USER_TYPE_INTEGERS;
  }
}

Let’s say you would like to allow users to upload PDF files to your site. You store data related to these file uploads in an “article” table in your database. This table has a column named “file” that stores the file name of the uploaded pdf.

The symfony forms framework will generate the basic (and not so basic) code to get you started. If you haven’t yet generated your form classes yet, you can do so with the command:

./symfony propel:build-forms

Now navigate to lib/form/ArticleForm.class.php. To convert the file column to a file input field, we do the following:

class ArtistResumeForm extends BaseArtistResumeForm
{
  public function configure()
  {
    $this->widgetSchema['file']        = new sfWidgetFormInputFile();
 
    $this->validatorSchema['file']     = new sfValidatorFile(array('path' => sfConfig::get('sf_upload_dir').'/articles', 'required' => false));
  }
}

Now, whenever you call $form->save(), your files will automatically be uploaded to the server, and the field “file” in your propel object will be updated with the new file name so you can easily retrieve it later.

If you are interested in getting this to work with embedded forms, check out this other post on uploading files within embedded forms with symfony 1.2.

What happens when you want to do a left join in your documentation query, so that if present both the related category and sub_category objects get included in the results?

$c->addJoin(DocumentationPeer::CATEGORY, CategoryPeer::ID, Criteria::LEFT_JOIN);
$c->addJoin(DocumentationPeer::SUB_CATEGORY, CategoryPeer::alias('c2', CategoryPeer::ID), Criteria::LEFT_JOIN);
$c->addAlias('c2', CategoryPeer::TABLE_NAME);

Done and done!

This will rebuild your db and model from schema.yml, insert the new structure into your db, and load data from the fixtures in /data/fixtures:

./symfony propel-build-all-load frontend

To load in additional data from a specific fixture file, you can use this command:

./symfony propel-load-data frontend dev data/fixtures/[filename].yml append

In this example, I wanted to create a select menu to use as a filter in the admin generator within symfony. We have a category table, and the categories are themselves have a “type” column, which is a plain text field that contains the “type” of category, like documentation, podcasts or faqs. To create a nice drop down with these options, we want to select all of the distinct values of the “type” column in this table. We can accomplish this easily with a Criteria object. Check it out:

// from our CategoryPeer class
public static function getTypes() {
  $c = new Criteria();
  $c->addSelectColumn(self::TYPE);
  $c->setDistinct();
  $c->addAscendingOrderByColumn(self::TYPE);
  $rs = BasePeer::doSelect($c);
  $types = array();
  while ($rs->next()) {
    $types[] = $rs->getString(1);
  }
 
  return array_combine($types, $types);
}

This ends up generating the following SQL statement:

DISTINCT category.TYPE, UPPER(category.TYPE) FROM category ORDER BY UPPER(category.TYPE) ASC

Perfect!

Perhaps the easiest way for newcomers to Propel are custom queries written using standard SQL.

$con = Propel::getConnection(DATABASE_NAME);
$sql = "SELECT books.* FROM books 
    WHERE NOT EXISTS (SELECT id FROM review WHERE book_id = book.id)";
$stmt = $con->createStatement();
$rs = $stmt->executeQuery($sql, ResultSet::FETCHMODE_NUM);
$books = BookPeer::populateObjects($rs);

Another method would be to use the peer class to gain some more flexibility in case down the line you decide to change your column names. For this we will use the PrepareStatement() method. This example also returns specific data from the query rather than entire propel objects.

public function getTotals($banner_id = NULL, $letter = NULL) {
	$con = Propel::getConnection();
 
	$sql = "SELECT SUM(".LetterBannerPeer::VIEWS.") AS view_total,
		SUM(".LetterBannerPeer::CLICKS.") AS click_total
		FROM ".LetterBannerPeer::TABLE_NAME."
		WHERE ".LetterBannerPeer::LETTER." = ?
		AND ".LetterBannerPeer::REGION_ID." = ?
		GROUP BY (".LetterBannerPeer::LETTER.")";
 
	$stmt = $con->PrepareStatement($sql);
	$stmt->setString(1, $letter);
	$stmt->setInt(2, REGION_ID);
 
	$rs = $stmt->executeQuery();
	while ($rs->next()) {
		$totals['views'] = $rs->getInt('view_total');
		$totals['clicks'] = $rs->getInt('click_total');
	}
	return $totals;
}

Notice how anytime you want to insert actual values into the query, you put in a ? (question mark) as a place holder which is then automatically escaped for the query by calling the $stmt->setString($position, $value) function.

For our third example we will use the Criterion Object. This function returns a propel object.

public static function getResponseTypes($message_type_id)
{
	$c = new Criteria();
	$c->addJoin(MessageTypePeer::ID, 
		MessageTypeResponsePeer::RESPONSE_TYPE_ID, Criteria::LEFT_JOIN);
	// think of a Criterion object as one 'XX=YY' within the WHERE clause
	$cton1 = $c->getNewCriterion(
		MessageTypeResponsePeer::MESSAGE_TYPE_ID, $message_type_id
	);
	$cton2 = $c->getNewCriterion(
		MessageTypePeer::NAME, 'general'
	);
	$cton1->addOr($cton2);  // combine them into one (XX=YY OR AA=BB) clause
	$c->add($cton1); 		// add to Criteria
 
	return MessageTypePeer::doSelect($c);
}

The Criteria object provides some other useful functions for generating queries. This is a great example of how to use addAsColumn(), addGroupByColumn(), and addDescendingOrderByColumn().

$c = new Criteria();
$c->addJoin(BookPeer::ID, FavoriteBookPeer::BOOK_ID, Criteria::LEFT_JOIN);
$c->addAsColumn('cnt', 'COUNT('.FavoriteBookPeer::BOOK_ID.')');
$c->addGroupByColumn(BookPeer::ID);
$c->addDescendingOrderByColumn('cnt');
$book = BookPeer::doSelect($c);

If you want to use a criteria object but only select certain columns, you can do something like this:

$c = new Criteria();
$c->clearSelectColumns()
$c->addSelectColumn(self::PAYABLE_TO);
$c->add(self::ID, $id);
 
$rs = self::doSelectRS($c);
$payable_to = false;
if ($rs->next()) {
  $payable_to = $rs->getInt(1);
}

If you want to do a subselect, you can use Criteria::CUSTOM.

$c = new Criteria();
$subSelect = "users.user_type_id IN (
    SELECT
          user_type.ID
    FROM
          user_type
    WHERE
         user_type.name = 'public'
    )";
$c->add(UserPeer::USER_TYPE_ID, $subSelect, Criteria::CUSTOM);
$publicUsers = UserPeer::doSelect($c);

You of course could rewrite that query using JOINS if you thought that was too messy.

This custom criterion type is also useful when you want to compare two fields from the same table.

$c = new Criteria();
$c->add(MyTablePeer::COL1, MyTablePeer::COL1.'>='.MyTablePeer::COL2, Criteria::CUSTOM);

Take a look at snippets 75 and 53 for more information.

…its database neutrality and logical simplicity make it a good choice for expressing many common queries; however, for a very complex query, it may prove more effective (and less painful) to simply use a custom SQL query to hydrate your Propel objects. (propel trac)

In building a complex search system for a client, I benefited greatly from being able to add and remove columns and conditions to a criteria object on the fly without having to worry about the actual SQL syntax. However, eventually I hit a wall when I needed to add a left join using multiple columns. Adding left joins to a criteria object is typically done like this:

$c = new Criteria();
$c->addJoin(TABLE_A::ID, TABLE_B::ID, Criteria::LEFT_JOIN);
/* equivalent to: "...left join TABLE_B ON (TABLE_A.ID=TABLE_B.ID)" */

However, this syntax does not support a join with multiple conditions, so you can’t produce something like this:

...left join TABLE_B ON (TABLE_A.ID=TABLE_B.ID AND TABLE_B.VALUE > 100)

In playing around quite a bit and examining the source code, I realized you could hack the addJoin method call and trick it into adding the extra column for you. The addJoin method actually is creating a new Join object that has a left and right column definition as defined in the method call. These are used to build the join condition:

$condition = $join->getLeftColumn() . '=' . $join->getRightColumn();

(see the source)

So, if you add the extra columns to the RightColumn like so:

$c->addJoin(TABLE_A::ID, TABLE_B::ID.' AND '.TABLE_B::VALUE.' > 0', Criteria::LEFT_JOIN);

the generated SQL will yield something like this:

...LEFT JOIN TABLE_B ON (TABLE_A.ID = TABLE_B.ID AND TABLE_B.VALUE > 0)

Although it’s a hack and it may not work under all conditions, so far it has been a suitable workaround.