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.

$model: One of the following
- A specific object (most common)
- A one-item associative array in the form of array('relationship_key' => $related_object)
- A model name*
- A relationship key*
* In the case of the latter two, every row that is related to $object will be updated.
$column: The column to set
$value: The value to set on the column

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);