FuzzyRecord documentation

Finding objects

FuzzyRecord has a powerful set of tools for finding objects. It offers a range of approaches that will make sense in different situations.

What follows are some examples - this is not an exhaustive list of ways you can fetch objects, but it should give you enough to figure out what you need.

Keys things you need to know:

• Methods starting with 'find_all' will return an array of object, this may be empty if there were no matches
• Methods starting with just 'find' will return a single object if one is found, or NULL otherwise.
• Methods starting with 'count' work with all the same options as 'find_all', but they return the number of matches instead
• You separate multiple clauses with '_and_'

Basic operations

Find an object using the value of one of its properties:

$user = User::find_by_email("ben@allseeing-i.com");

Find an object using the value of one of several of its properties:

$user = User::find_by_first_name_and_last_name("Ben","Copsey");

Find a set of objects with a particular value:

$users = User::find_all_by_first_name("Ben"); //Returns an array of users

Find the number of objects with a particular value:

$count = User::count_by_first_name("Ben"); //Returns the number of users called Ben

Find all instances of an object:

$user = User::find_all();

Find the total number of instances of an object:

$count = User::count();

Get all photos that belong to a user:

$user = User::find_by_email("ben@allseeing-i.com");
$photos = $user->photos();

Does the same thing:

$user = User::find_by_email("ben@allseeing-i.com");
$photos = $user->photos;

Find the owner of a photo:

$photo = new Photo(123);
$user = User::find_by_photo($photo);

Does the same thing:

$photo = new Photo(123);
$user = $photo->user;

More complex queries

Find all the objects without a particular value:

$users = User::find_all_by_first_name_not("Ben");

Returns an array of articles with a date after 7th July 2008:

$articles = Article::find_all_by_date_posted_greater_than("2008-07-07");

Returns an array of very tall users that know their height in metric:

$user = User::find_all_by_height_greater_than_and_height_less_than(200,300);

All users whose last name starts with the letter C (case-insensitive):

$user = User::find_all_by_last_name_like("c%");

Find all users that don't have 'super' in their name:

$user = User::find_all_by_first_name_not_like("%super%");

Write the where query yourself:

$users = User::find_all_where("first_name = 'Ben'");

Remember to escape untrusted input when using find_all_where and find_where, to avoid SQL injection. You only ever need to do this when using find_where, quoting input is handled automatically elsewhere:

$location = "John 'O Groats";
$users = User::find_all_where("location = ".DB::quote($location))

Find 5 users called Ben:

$users = User::find_all_by_first_name("Ben",5);

Find 5 users called Ben, starting from record 10:

$users = User::find_all_by_first_name("Ben",10,5);

Using find

The find() function offers the most power, and the methods above all use find() to perform searches behind the scenes. It takes an associative array as its single argument, and returns an array of objects.

$users = User::find("first_name" => "Ben", "start_from" => 10, 
"order_by" => "last_name", "sort" => "ascending", "where" => "status = "validated");

You can also pass in an array as the final parameter when using the auto-generated API.

$users = User::find_all_by_first_name("Ben",array("limit" => 5, "start_from" => 10, 
"order_by" => "last_name", "sort" => "descending"));

Like searches across multiple fields

As we have seen, you can specify a particular field for a like search:

$user = User::find_all_by_last_name_like("c%");

or

$user = User::find("last_name_like" => "c%");

If you specify a set of properties as like_searchable in your model:

...
"title" => array("min_length" => 2,"max_length" => 64,"required","like_searchable"),
"body" => array("required","like_searchable"),
...

You can also do:

$pages = Page::find("like" => "c%");

This will return all pages where title or body matches 'c%'.