Associations

Version 3 (Kien La, 2010-06-19 06:35 PM)

1 1
h2. Associations
2 1
3 3 Kien La
*(#topic-list) "Common options":/projects/main/wiki/Associations#common-options
4 1
* "has_many":/projects/main/wiki/Associations#has_many
5 1
* "belongs_to":/projects/main/wiki/Associations#belongs_to
6 1
* "has_one":/projects/main/wiki/Associations#has_one
7 1
* "Self-referential":/projects/main/wiki/Associations#self-referential
8 1
9 1
What are associations? By declaring associations on your models, you allow them to communicate with each other. These associations should match the way data in your tables relate to each other.
10 1
11 2 Kien La
h4(#common-options). Common options
12 1
13 1
These are available amongst each type of association.
14 1
15 1
*conditions*: string/array of "finder conditions":/projects/main/wiki/Finders#conditions
16 1
*readonly*: whether associated objects can be "saved/destroyed":/projects/main/wiki/Finders#read-only
17 1
*select*: specify fields in the "select clause":/projects/main/wiki/Finders#select
18 1
*class_name*: the class name of the associated model
19 1
*foreign_key*: name of foreign_key
20 1
21 1
Let's take a look at these options with a few different association types
22 1
23 2 Kien La
h5. conditions
24 1
25 1
Below, we specify that associated payments of an order object should not be void.
26 1
27 1
<pre class="code"><code class="php">
28 1
class Order extends ActiveRecord\Model {
29 1
  static $has_many = array(
30 1
    array('payments', 'conditions' => array('void = ?' => array(0)))
31 1
  );
32 1
}
33 1
</code></pre>
34 1
 
35 1
h5. readonly
36 1
37 1
If you add a readonly option to your association, then the associatied object cannot be saved, although, the base object can still be saved.
38 1
39 1
<pre class="code"><code class="php">
40 1
class Payment extends ActiveRecord\Model {
41 1
  static $belongs_to = array(
42 1
    array('user', 'readonly' => true)
43 1
  );
44 1
}
45 1
 
46 1
$payment = Payment::first();
47 1
$payment->paid = 1;
48 1
$payment->save(); # this will save just fine
49 1
50 1
$payment->user->first_name = 'John';
51 1
$payment->user->save(); # this will throw a ReadOnlyException
52 1
</code></pre>
53 1
54 1
h5. select
55 1
56 1
Sometimes you may not need all of the fields back from one of your associations (e.g. it may be a ridiculously large table) and so you can specify the particular fields you want.
57 1
58 1
<pre class="code"><code class="php">
59 1
class Payment extends ActiveRecord\Model {
60 1
  static $belongs_to = array(
61 1
    array('person', 'select' => 'id, first_name, last_name')
62 1
  );
63 1
}
64 1
</code></pre>
65 1
 
66 1
h5. class_name
67 1
68 1
In this example payment has a one-to-one relationship with a user, but we want to access the association thru "person." Thus, we have to provide the class name of the associated model; otherwise, ActiveRecord would try to look for a "Person" class.
69 1
70 1
<pre class="code"><code class="php">
71 1
class Payment extends ActiveRecord\Model {
72 1
  static $belongs_to = array(
73 1
    array('person', 'class_name' => 'User')
74 1
  );
75 1
}
76 1
</code></pre>
77 1
 
78 1
h5. has_many
79 1
80 2 Kien La
A one-to-many relationship. You should use a pluralized form of the associated model when declaring a has_many association, unless you want to use the "class_name":/projects/main/wiki/Associations#class_name option.
81 1
82 1
<pre class="code"><code class="php">
83 1
# one-to-many association with the model "Payment"
84 1
class User extends ActiveRecord\Model {
85 1
  static $has_many = array(
86 1
    array('payments')
87 1
  );
88 1
}
89 1
 
90 1
$user = User::first();
91 1
print_r($user->payments); # => will print an array of Payment objects
92 1
</code></pre> 
93 1
94 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
95 1
96 2 Kien La
*limit/offset*: limit the number of records
97 2 Kien La
*primary_key*: name of the primary_key of the association (assumed to be "id")
98 2 Kien La
*group*: GROUP BY clause
99 2 Kien La
*order*: ORDER BY clause
100 2 Kien La
*through*: the association used to go "through"
101 1
102 1
<pre class="code"><code class="php">
103 1
class Order extends ActiveRecord\Model {
104 1
  static $has_many = array(
105 1
    array('payments', 'limit' => 5),
106 1
    array('items', 'order' => 'name asc', 'group' => 'type')
107 1
  );
108 1
}
109 1
</code></pre>
110 1
 
111 1
has_many through
112 1
113 1
This is a convenient way to configure a many-to-many association. In this example an order is associated with users by going the its payments association.
114 1
115 1
<pre class="code"><code class="php">
116 1
class Order extends ActiveRecord\Model {
117 1
  static $has_many = array(
118 1
    array('payments'),
119 1
    array('users', 'through' => 'payments')
120 1
  );
121 1
}
122 1
 
123 1
class Payment extends ActiveRecord\Model {
124 1
  static $belongs_to = array(
125 1
    array('user'),
126 1
    array('order')
127 1
  );
128 1
}
129 1
 
130 1
class User extends ActiveRecord\Model {
131 1
  static $has_many = array(
132 1
    array('payments')
133 1
  );
134 1
}
135 1
 
136 1
$order = Order::first();
137 1
# direct access to users
138 1
print_r($order->users); # will print an array of User object
139 1
</code></pre>
140 1
141 2 Kien La
h4(#belongs_to). belongs_to
142 1
143 2 Kien La
This indicates a one-to-one relationship. Its difference from "has_one":/projects/main/wiki/Associations#has_one is that the foreign key will be on the table which declares a belongs_to association. You should use a singular form of the associated model when declaring this association, unless you want to use the "class_name":/projects/main/wiki/Associations#class_name option.
144 1
145 1
<pre class="code"><code class="php">
146 1
class Payment extends ActiveRecord\Model {
147 1
  static $belongs_to = array(
148 1
    array('user')
149 1
  );
150 1
}
151 1
 
152 1
$payment = Payment::first();
153 1
echo $payment->user->first_name; # first_name of associated User object
154 1
</code></pre> 
155 1
156 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
157 1
158 2 Kien La
*primary_key*: name of the primary_key of the association (assumed to be "id")
159 1
has_one
160 1
161 2 Kien La
This indicates a one-to-one relationship. A has_one will have the foreign key on the associated table unlike "belongs_to":/projects/main/wiki/Associations#belongs_to. You should use a singular form of the associated model when declaring this association, unless you want to use the "class_name":/projects/main/wiki/Associations#class_name option.
162 1
163 1
<pre class="code"><code class="php">
164 1
class Payment extends ActiveRecord\Model {
165 1
  static $has_one = array(
166 1
    array('receipt')
167 1
  );
168 1
}
169 1
</code></pre> 
170 1
171 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
172 1
173 2 Kien La
*primary_key*: name of the primary_key of the association (assumed to be "id")
174 2 Kien La
*through*: the association used to go "through"
175 1
176 2 Kien La
h5. has_one through
177 2 Kien La
178 1
A one-to-one association. In this example, an owner has a quarter_back by going through its team association.
179 1
180 1
<pre class="code"><code class="php">
181 1
class Owner extends ActiveRecord\Model {
182 1
  static $has_one = array(
183 1
    array('team'),
184 1
    array('quarter_back', 'through' => 'team')
185 1
  );
186 1
}
187 1
 
188 1
class Team extends ActiveRecord\Model {
189 1
  static $belongs_to = array(
190 1
    array('owner')
191 1
  );
192 1
 
193 1
  static $has_one = array(
194 1
    array('quarter_back')
195 1
  );
196 1
}
197 1
 
198 1
class QuarterBack extends ActiveRecord\Model {
199 1
  static $belongs_to = array(
200 1
    array('team')
201 1
  );
202 1
}
203 1
</code></pre>
204 1
205 2 Kien La
h4(#self-referential). Self-referential
206 1
207 1
Model's can declare associations to themselves. This can be helpful for table auditing, or in the example below, where a post would need to know about its parent.
208 1
209 1
<pre class="code"><code class="php">
210 1
class Post extends ActiveRecord\Model {
211 1
  static $belongs_to = array(array('parent_post', 'class_name' => 'Post'));
212 1
}
213 1
</code></pre>