DataMapper


Get By

Get By is a dynamic method that gives you an easier way to lookup records based on a single where condition. For example, normally you might lookup a user's record based on their id in this way:

// We'll assume $id was populated via their Session Cookie

// Get user by ID
$u = new User();
$u->where('id', $id)->get();

Using the Get By method, you can do exactly as above in this way:

// We'll assume $id was populated via their Session Cookie

// Get user by ID
$u = new User();
$u->get_by_id($id);

I mentioned that Get By is a dynamic method. What I mean by this is, you can Get By any fields belonging to the object. For example, a user object might have a username field. So, to Get By username:

// We'll assume $username was populated via a POST request

// Get user by username
$u = new User();
$u->get_by_username($username);

Likewise, if they had an email field, you could Get By email:

// We'll assume $email was populated via a POST request

// Get user by email
$u = new User();
$u->get_by_email($email);

Get By is primarily a convenience method for developers. Whether you choose to use it instead of specifying the where clause yourself is up to you, but whatever your choice, I recommend being consistent with it.

 

Get By (Advanced)

Similarly to the advanced queries available in Get (Advanced), there is a Get By Related equivelant for where_related clauses. Here's the example of a simple where_related() usage:

Here's how you would do the above, but using an advanced query:

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

// Get users that are related to the Moderator group
$u->where_related_group('name', 'Moderator')->get();

// ...

And here's how you do the exact same thing but using Get By Related:

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

// Get users that are related to the Moderator group
$u->get_by_related_group('name', 'Moderator');

// ...

$object->get_by_related_{model}($field, $value);

Just like with the different usage formats in Get (Advanced), there are different ways you can use Get By Related.

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

// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
$u->get_by_related_group('name', 'Moderator');

$object->get_by_related($model, $field, $value);

Alternatively, rather than specifying the related model as part of the method, you could instead supply it as the first parameter.

Here's an example using the where query:

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

// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
$u->get_by_related('group', 'name', 'Moderator');

$object->get_by_related($related_object, $field, $value);

Note:  Both the $field and $value parameters are optional if the $related_object contains a valid id.

Here's an example using the where query:

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

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

// Get all users relating to the Moderator group (goes by 'group', 'id', $g->id)
$u->get_by_related($g);

Here's a similar way of doing the above, but with an unpopulated related object (no id):

// Create and get the Moderator group
$g = new Group();

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

// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
$u->get_by_related($g, 'name', 'Moderator');

Which of the available usage formats you use will depend on your personal preference, although you should be consistent with your choice. It also might depend on whether you have a related object already available to use.

Note:  For Self Referencing Relationships, you can only use the usage format where you pass a related object with an id, for example:

$object->get_by_related($related_object);