Permalink
Browse files

Adding some additional documentation for Model::find(). Fixes #952

  • Loading branch information...
markstory committed Jul 28, 2010
1 parent b5d7f64 commit d81d33ffe6aca13d65c577653da6bdf8676f9f19
Showing with 23 additions and 5 deletions.
  1. +23 −5 cake/libs/model/model.php
View
@@ -1997,7 +1997,7 @@ function hasAny($conditions = null) {
}
/**
- * Returns a result set array.
+ * Queries the datasource and returns a result set array.
*
* Also used to perform new-notation finds, where the first argument is type of find operation to perform
* (all / first / count / neighbors / list / threaded ),
@@ -2006,15 +2006,33 @@ function hasAny($conditions = null) {
*
* Eg:
* {{{
- * find('all', array(
- * 'conditions' => array('name' => 'Thomas Anderson'),
+ * find('all', array(
+ * 'conditions' => array('name' => 'Thomas Anderson'),
* 'fields' => array('name', 'email'),
* 'order' => 'field3 DESC',
* 'recursive' => 2,
* 'group' => 'type'
* ));
* }}}
*
+ * In addition to the standard query keys above, you can provide Datasource, and behavior specific
+ * keys. For example, when using a SQL based datasource you can use the joins key to specify additional
+ * joins that should be part of the query.
+ *
+ * {{{
+ * find('all', array(
+ * 'conditions' => array('name' => 'Thomas Anderson'),
+ * 'joins' => array(
+ * 'alias' => 'Thought',
+ * 'table' => 'thoughts',
+ * 'type' => 'LEFT',
+ * 'conditions' => '`Thought`.`person_id` = `Person`.`id`'
+ * )
+ * ));
+ * }}}
+ *
+ * Behaviors and find types can also define custom finder keys which are passed into find().
+ *
* Specifying 'fields' for new-notation 'list':
*
* - If no fields are specified, then 'id' is used for key and 'model->displayField' is used for value.
@@ -2023,9 +2041,9 @@ function hasAny($conditions = null) {
* - Otherwise, first and second fields are used for key and value.
*
* @param array $conditions SQL conditions array, or type of find operation (all / first / count /
- * neighbors / list / threaded)
+ * neighbors / list / threaded)
* @param mixed $fields Either a single string of a field name, or an array of field names, or
- * options for matching
+ * options for matching
* @param string $order SQL ORDER BY conditions (e.g. "price DESC" or "name ASC")
* @param integer $recursive The number of levels deep to fetch associated records
* @return array Array of records

0 comments on commit d81d33f

Please sign in to comment.