Retrieving Data

The find() method is the all-purpose method for retrieving data from a model. It takes a single argument, an associative array of options for the find. Here's an example that shows the available options (it isn't a practical example, though):

<?php
// controllers/events_controller.php
class EventsController extends MvcPublicController {
  
  public function index() {
    $objects = $this->Event->find(array(
      'joins' => array('Venue'),
      'includes' => array('Venue'),
      'selects' => array('Venue.id', 'Venue.name', 'Event.date', 'Event.active'),
      'additional_selects' => array('Event.date'),
      'conditions' => array(
        'Event.active' => 1,
        'Event.date >=' => date('Y-m-d'),
        'Venue.id' => array(56, 83) // Venue.id IN (56, 83)
      ),
      'group' => 'Event.id',
      'order' => 'Event.date DESC',
      'page' => 1
      'per_page' => 20
    ));
    $this->set('objects', $objects);
  }
  
}
?>

joins

An array of associated models that will be included as joins in the query and in the results.

includes

An array of associated models that will be added to the object via additional SELECT queries after the initial SELECT query has been made. These can't be referenced in conditions, but unlike joins, has_many and has_and_belongs_to many associations can be safely used here.

selects

An array of columns that will be selected in the query. This will replace the default selected fields that are defined in the model.

additional_selects

An array of columns that will be merged with the default selected fields that are defined in the model; all of the columns in the resulting merged array will be selected in the query.

conditions

An array of conditions for the WHERE part of the query. Conditions are joined with an AND by default, but OR conditions can be done like this:

<?php
// Find all Events that are active or are happening on or after today
$objects = $this->Event->find(array(
  'conditions' => array(
    'OR' => array(
      'Event.active' => 1,
      'Event.date >=' => date('Y-m-d'),
    )
  )
);
?>

To group conditions together, use an 'AND' or 'OR' in the same way that the 'OR' above is used.

group

A string specifying the value for a GROUP BY clause.

order

A string specifying the value for an ORDER clause.

page

An integer specifying which page of results should be returned. The number of results per page defaults to the per_page property of the model, but can be overwritten with a per_page key in the find options.

per_page

An integer specifying the number of results per page. This is only relevant when the page option is also set.

<?php
class VenuesController extends MvcPublicController {
  
  public function show() {
    $object = this->Venue->find_one(array(
      'slug' => $this->params['slug'],
      'includes' => array('Event')
    ));
    $this->set('object', $object);
  }
  
}
?>

This behaves almost identically to find(), except that it has two arguments: the first is an id, the second is the options array that find() uses. It finds the record with a primary key value of the specified id, but also handles the options array in the same way that find() does.

<?php
class VenuesController extends MvcPublicController {
  
  public function show() {
    $object = this->Venue->find_by_id($this->params['id'], array(
      'includes' => array('Event')
    ));
    $this->set('object', $object);
  }
  
}
?>

For every attribute of a model, WP MVC will provide a find_by_* method that returns all records with that value for that column.

For example, if Event has a column venue_id:

<?php
$event_model = mvc_model('Event');
$events = $event_model->find_by_venue_id(4);
?>

For every attribute of a model, WP MVC will provide a find_one_by_* method that returns the first record with that value for that column.

For example, if Event has a column venue_id:

<?php
$event_model = mvc_model('Event');
$event = $event_model->find_one_by_venue_id(4);
?>

paginate() is similar to find(), but it adds some functionality that is useful for creating paginated retrievals of data. It returns a "collection," which is an array that contains the returned objects in the 'objects' key, but also contains information that is useful for creating pagination (total number of results, number of results per page, etc).

<?php
class EventsController extends MvcPublicController {

  public function index() {
  
    $params = $this->params;
    $params['page'] = empty($this->params['page']) ? 1 : $this->params['page'];
    $params['conditions'] = array('is_public' => true);
    $collection = $this->model->paginate($params);
    $this->set('objects', $collection['objects']);
    $this->set_pagination($collection);
  
  }

}
?>

Returns the number of records matching the query (using a COUNT() MySQL query).

<?php
$venue_model = mvc_model('Venue');
$total_count = $venue_model->count();
$public_count = $venue_model->count(array(
  'conditions' => array(
    'is_public' => 1
  )
));
?>

Returns the maximum value of the column (using a MAX() MySQL query). An optional second argument can be used to specify conditions or other query qualifiers.

<?php
// If the Venue table has columns 'event_count' and 'is_public':
$venue_model = mvc_model('Venue');
$max_event_count = $venue_model->max('event_count');
$public_max_event_count = $venue_model->max('event_count', array(
  'conditions' => array(
    'is_public' => 1
  )
));
?>

Returns the minimum value of the column (using a MIN() MySQL query). An optional second argument can be used to specify conditions or other query qualifiers.

<?php
// If the Venue table has columns 'event_count' and 'is_public':
$venue_model = mvc_model('Venue');
$min_event_count = $venue_model->min('event_count');
$public_min_event_count = $venue_model->min('event_count', array(
  'conditions' => array(
    'is_public' => 1
  )
));
?>

Returns the sum of the values of a column (using a SUM() MySQL query). An optional second argument can be used to specify conditions or other query qualifiers.

<?php
// If the Venue table has columns 'event_count' and 'is_public':
$venue_model = mvc_model('Venue');
$event_count_sum = $venue_model->sum('event_count');
$public_event_count_sum = $venue_model->sum('event_count', array(
  'conditions' => array(
    'is_public' => 1
  )
));
?>

Returns the average of the values of a column (using a AVERAGE() MySQL query). An optional second argument can be used to specify conditions or other query qualifiers.

<?php
// If the Venue table has columns 'event_count' and 'is_public':
$venue_model = mvc_model('Venue');
$event_count_average = $venue_model->average('event_count');
$public_event_count_average = $venue_model->average('event_count', array(
  'conditions' => array(
    'is_public' => 1
  )
));
?>