Finding resources and using the find options

Often you'll want to find another resource (or a collection of resources) other than the one loaded with the request. Given an adapter, Tonic provide two methods for finding and returning resources.

Resource Resource::find(Adapter, str, str[])

To find a single resource, we can use the find method. We pass in an adapter to look in, the URL of the resource to find, and an array of find options. It returns the single resource that matches the URL or NULL if nothing was found.

$resource = Resource::find($adapter, '/a/resource/to/load');
find() method example

Resource Resource::findAll(Adapter, str, str[])

To find a collection of resources, the findAll method should be used. It works just like the find method but returns an array of resources that match the URL and find options. Obviously a URL identifies a single resource, when finding multiple resources the given URL is used to match against the beginning of resources URLs.

$resources = Resource::findAll(
	$adapter,
	'/collection/of/resources',
	array(
		TONIC_FIND_DEFAULT_METADATA => array(
			'title' => 'Default title'
		),
		TONIC_FIND_FROM => 11,
		TONIC_FIND_TO => 20
	)
);
find() method example

Find options

The optional options array allows us to tailor the way the find methods work and the resources they return. Each option is a constant that should used as the key in the array with either the required value or the value TRUE.

TONIC_FIND_EXACT Only find resources that match the given URL exactly. Without this set you'll the find method will find all resources whose URLs start with the given URL. This option is set by default by the find method.
TONIC_FIND_DEFAULT_METADATA An array of properties that we want to add to any found resources if they don't already have a value for that property. The array should contain key/value pairs where the key is the name of the property to set.
TONIC_FIND_FORCE_METADATA An array of properties that we want to add to any found resources whether they already have a value for that property or not. The array should contain key/value pairs where the key is the name of the property to set.
TONIC_FIND_BY_METADATA An array of key/value pairs of properties and values to use to find resources. All resources that have all of the given properties set to the given values will be found.
TONIC_SORT_BY_METADATA An array of property names to sort the resulting resources array by. To sort in decending order rather than ascending order, postfix the property name with "DESC" (like in a SQL ORDER clause).
TONIC_FIND_FROM The location in the resulting resource array to start returning resources from.
TONIC_FIND_TO The location in the resulting resource array to end returning resources at.
TONIC_CALC_FOUND_RESOURCES Whether to set the foundResources property of the adapter to the total number of resources found (before any TONIC_FIND_FROM and TONIC_FIND_TO options were applied).
TONIC_FIND_BY_SQL A complete SQL statement to use to find resources. This will by-pass all other options and just execute the SQL and turn the resultset into resources. This option only works with SQL based adapters.
Back to documentation home
Created Feb 17, 2008, last modified Feb 17, 2008