DataMapper ORM

Counting

There are several methods available to get the number of rows or results in a query.

Subsections:

$object->result_count()

Returns the number of results from the last get. This is the recommended way of counting the number of results from a query.

This is a simple convenience method for count($object->all), but it also returns the number of rows when using get_iterated.

The main purpose of this method is that it makes for easy switching between a normal get and get_iterated.

$object->count()

Count has a different result depending on the object you use it on and whether you have setup any query clauses. If you use it directly on an object, it returns the total number of records of that object type, that you have in the database. For example, let's say we have 10 users:

// Create user object
$u = new User();

// Outputs: 10
echo $u->count();

Now, lets say you wanted to get a specific count of only active users, and we knew we only had 7 of them. You can use query clauses to help with this. For example:

// Create user object
$u = new User();

// Outputs: 7
echo $u->where('active', TRUE)->count();

Count behaves slightly differently when used on a related object, as the count will be based on the total number of related records. For example, let's say we wanted to see how many active Users were in the Moderator Group:

// Create user object
$u = new User();

// Create group object
$g = new Group();
$g->get_by_name('Moderator');

// Outputs: 2 out of 7 users are moderators.
echo $g->user->where('active', TRUE)->count() . ' out of ' . $u->where('active', TRUE)->count() . ' ' . plural($u) . ' are ' . plural($g) . '.';

Excluding IDs from the Count

If you want to count all objects except one or more IDs, count can accept an optional array of IDs to exclude.

Continuing from above, lets say that we want all active users, except user #1 and user #2:

// Create user object
$u = new User();

// We want to exclude these users from the result
$excluded_ids = array(1, 2);

// Outputs: 5
echo $u->where('active', TRUE)->count($excluded_ids);

This works even if ids in the list were not in the result set, so you can exclude users that may or may not be active.

$object->count_distinct()

If you know your query may have duplicate rows, you can use count_distinct to only count distinct rows.

This method accepts the same $exclude_ids parameter as count. It also has a second parameter, which is rarely needed, but allows you to override the distinct column. (By default, id.)

Note: COUNT(DISTINCT `id`) is not supported on all databases. Please make sure your database supports this function.

Counting related items

If you just want the number of related items for an already retrieved object, you can use count like above:

$user = new User($user_id);
$number_of_bugs = $user->bug->count();

Including a Related Count

If you want to get the related count in the same query as the parent object, please see include_related_count.

If you want to check to see if two objects are related in the database, you can use this convenience method.

You can call it either with an already-retrieved object, or with just the relationship name and ID.

Already Retrieved Object

$group = new Group($group_id);
$user = new User($user_id);

// Is this user already in the group?
if($group->is_related_to($user)) {
    // do something
}

Using the Related Field

$user = new User($user_id);

if($user->is_related_to('group', $group_id)) {
    // do something
}