DataMapper ORM


Working with Join Fields

Join fields are fields that are stored on the join table for Many to Many relationships. They can be used to store additional information that is only relevant to the relationship itself, as opposed to information that belongs to one of the models.

A good example of this is a system that can fire alarms. Each alarm can be assigned to multiple users, and each user can have multiple alarms. An alarm needs to be fired individually for each user, and they only get fired when the user logs in.

To keep track of this, we add a column to our alarms_users table that is called wasfired. It defaults to FALSE.

alarms_users

id alarm_id user_id wasfired
1 1 4 FALSE
2 1 5 TRUE
3 2 1 TRUE

Querying the Join Field

Please see Get (Advanced): _join_field for details on how to query join fields.

Reading the Join Field

Please see Get (Advanced): include_join_fields for details on how to include join fields in the result set.

Setting the Join Field

You can set the join field for one or more rows using set_join_field

$object->set_join_field($model, $column, $value)

Store $value into $column on the table that relates $object and $model (which can be an object OR a field name when an object is related multiple times.

Example time!

// Create objects
$u = new User();
$u->get_by_id($userid);

$alarm = new Alarm();
$alarm->get_by_id($alarmid);

// relate this alarm to the user
$u->save($alarm);

// mark this alarm as fired
$alarm->set_join_field($u, 'wasfired', TRUE);

set_join_field runs an UPDATE query on the relation table, so make sure the two objects are related before using this method!