Filters¶
It is often desirable to create reusable queries that can be used to
extract particular subsets of data without repeating large sections of
code. Paris allows this by providing a method called filter
which
can be chained in queries alongside the existing Idiorm query API. The
filter method takes the name of a public static method on the
current Model subclass as an argument. The supplied method will be
called at the point in the chain where filter
is called, and will be
passed the ORM
object as the first parameter. It should return the
ORM object after calling one or more query methods on it. The method
chain can then be continued if necessary.
It is easiest to illustrate this with an example. Imagine an application
in which users can be assigned a role, which controls their access to
certain pieces of functionality. In this situation, you may often wish
to retrieve a list of users with the role ‘admin’. To do this, add a
static method called (for example) admins
to your Model class:
<?php
class User extends Model {
public static function admins($orm) {
return $orm->where('role', 'admin');
}
}
You can then use this filter in your queries:
<?php
$admin_users = Model::factory('User')->filter('admins')->find_many();
You can also chain it with other methods as normal:
<?php
$young_admins = Model::factory('User')
->filter('admins')
->where_lt('age', 18)
->find_many();
Filters with arguments¶
You can also pass arguments to custom filters. Any additional arguments
passed to the filter
method (after the name of the filter to apply)
will be passed through to your custom filter as additional arguments
(after the ORM instance).
For example, let’s say you wish to generalise your role filter (see above) to allow you to retrieve users with any role. You can pass the role name to the filter as an argument:
<?php
class User extends Model {
public static function has_role($orm, $role) {
return $orm->where('role', $role);
}
}
$admin_users = Model::factory('User')->filter('has_role', 'admin')->find_many();
$guest_users = Model::factory('User')->filter('has_role', 'guest')->find_many();
These examples may seem simple (filter('has_role', 'admin')
could
just as easily be achieved using where('role', 'admin')
), but
remember that filters can contain arbitrarily complex code - adding
raw_where
clauses or even complete raw_query
calls to perform
joins, etc. Filters provide a powerful mechanism to hide complexity in
your model’s query API.