Associations

Version 10 (Bill Zhao, 2013-09-30 03:13 AM)

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 8 Kien La
* "has_many through (many to many)":/projects/main/wiki/Associations#has_many_through
6 1
* "belongs_to":/projects/main/wiki/Associations#belongs_to
7 1
* "has_one":/projects/main/wiki/Associations#has_one
8 1
* "Self-referential":/projects/main/wiki/Associations#self-referential
9 1
10 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.
11 1
12 2 Kien La
h4(#common-options). Common options
13 1
14 1
These are available amongst each type of association.
15 1
16 1
*conditions*: string/array of "finder conditions":/projects/main/wiki/Finders#conditions
17 1
*readonly*: whether associated objects can be "saved/destroyed":/projects/main/wiki/Finders#read-only
18 1
*select*: specify fields in the "select clause":/projects/main/wiki/Finders#select
19 1
*class_name*: the class name of the associated model
20 1
*foreign_key*: name of foreign_key
21 1
22 1
Let's take a look at these options with a few different association types
23 1
24 2 Kien La
h5. conditions
25 1
26 1
Below, we specify that associated payments of an order object should not be void.
27 1
28 1
<pre class="code"><code class="php">
29 1
class Order extends ActiveRecord\Model {
30 1
  static $has_many = array(
31 1
    array('payments', 'conditions' => array('void = ?' => array(0)))
32 1
  );
33 1
}
34 1
</code></pre>
35 1
 
36 1
h5. readonly
37 1
38 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.
39 1
40 1
<pre class="code"><code class="php">
41 1
class Payment extends ActiveRecord\Model {
42 1
  static $belongs_to = array(
43 1
    array('user', 'readonly' => true)
44 1
  );
45 1
}
46 1
 
47 1
$payment = Payment::first();
48 1
$payment->paid = 1;
49 1
$payment->save(); # this will save just fine
50 1
51 1
$payment->user->first_name = 'John';
52 1
$payment->user->save(); # this will throw a ReadOnlyException
53 1
</code></pre>
54 1
55 1
h5. select
56 1
57 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.
58 1
59 1
<pre class="code"><code class="php">
60 1
class Payment extends ActiveRecord\Model {
61 1
  static $belongs_to = array(
62 1
    array('person', 'select' => 'id, first_name, last_name')
63 1
  );
64 1
}
65 1
</code></pre>
66 1
 
67 5 Kien La
h5(#class_name). class_name
68 1
69 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.
70 1
71 1
<pre class="code"><code class="php">
72 1
class Payment extends ActiveRecord\Model {
73 1
  static $belongs_to = array(
74 1
    array('person', 'class_name' => 'User')
75 1
  );
76 1
}
77 1
</code></pre>
78 1
 
79 4 Kien La
h4(#has_many). has_many
80 1
81 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.
82 1
83 1
<pre class="code"><code class="php">
84 1
# one-to-many association with the model "Payment"
85 1
class User extends ActiveRecord\Model {
86 1
  static $has_many = array(
87 1
    array('payments')
88 1
  );
89 1
}
90 1
 
91 1
$user = User::first();
92 1
print_r($user->payments); # => will print an array of Payment objects
93 10 Bill Zhao
# build|create for associations.
94 10 Bill Zhao
$payment = $user->create_payment(array('paid' => 1));
95 7 Kien La
</code></pre>
96 1
97 7 Kien La
!/images/guides/has_many.png!
98 7 Kien La
99 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
100 1
101 2 Kien La
*limit/offset*: limit the number of records
102 2 Kien La
*primary_key*: name of the primary_key of the association (assumed to be "id")
103 2 Kien La
*group*: GROUP BY clause
104 2 Kien La
*order*: ORDER BY clause
105 2 Kien La
*through*: the association used to go "through"
106 1
107 1
<pre class="code"><code class="php">
108 1
class Order extends ActiveRecord\Model {
109 1
  static $has_many = array(
110 1
    array('payments', 'limit' => 5),
111 1
    array('items', 'order' => 'name asc', 'group' => 'type')
112 1
  );
113 1
}
114 1
</code></pre>
115 1
 
116 8 Kien La
h5(#has_many_through). has_many through (many to many)
117 1
118 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.
119 1
120 1
<pre class="code"><code class="php">
121 1
class Order extends ActiveRecord\Model {
122 1
  static $has_many = array(
123 1
    array('payments'),
124 1
    array('users', 'through' => 'payments')
125 1
  );
126 1
}
127 1
 
128 1
class Payment extends ActiveRecord\Model {
129 1
  static $belongs_to = array(
130 1
    array('user'),
131 1
    array('order')
132 1
  );
133 1
}
134 1
 
135 1
class User extends ActiveRecord\Model {
136 1
  static $has_many = array(
137 1
    array('payments')
138 1
  );
139 1
}
140 1
 
141 1
$order = Order::first();
142 1
# direct access to users
143 1
print_r($order->users); # will print an array of User object
144 1
</code></pre>
145 1
146 7 Kien La
!/images/guides/has_many_through.png!
147 7 Kien La
148 2 Kien La
h4(#belongs_to). belongs_to
149 1
150 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.
151 1
152 1
<pre class="code"><code class="php">
153 1
class Payment extends ActiveRecord\Model {
154 1
  static $belongs_to = array(
155 1
    array('user')
156 1
  );
157 1
}
158 1
 
159 1
$payment = Payment::first();
160 1
echo $payment->user->first_name; # first_name of associated User object
161 1
</code></pre> 
162 1
163 7 Kien La
!/images/guides/belongs_to.png!
164 7 Kien La
165 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
166 1
167 1
*primary_key*: name of the primary_key of the association (assumed to be "id")
168 4 Kien La
169 4 Kien La
h4(#has_one). has_one
170 1
171 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.
172 1
173 1
<pre class="code"><code class="php">
174 1
class Payment extends ActiveRecord\Model {
175 1
  static $has_one = array(
176 1
    array('receipt')
177 1
  );
178 1
}
179 7 Kien La
</code></pre>
180 1
181 7 Kien La
!/images/guides/has_one.png!
182 7 Kien La
183 2 Kien La
Options (not part of "common options":/projects/main/wiki/Associations#common-options)
184 1
185 2 Kien La
*primary_key*: name of the primary_key of the association (assumed to be "id")
186 2 Kien La
*through*: the association used to go "through"
187 1
188 2 Kien La
h5. has_one through
189 2 Kien La
190 1
A one-to-one association. In this example, an owner has a quarter_back by going through its team association.
191 1
192 1
<pre class="code"><code class="php">
193 1
class Owner extends ActiveRecord\Model {
194 1
  static $has_one = array(
195 1
    array('team'),
196 1
    array('quarter_back', 'through' => 'team')
197 1
  );
198 1
}
199 1
 
200 1
class Team extends ActiveRecord\Model {
201 1
  static $belongs_to = array(
202 1
    array('owner')
203 1
  );
204 1
 
205 1
  static $has_one = array(
206 1
    array('quarter_back')
207 1
  );
208 1
}
209 1
 
210 1
class QuarterBack extends ActiveRecord\Model {
211 1
  static $belongs_to = array(
212 1
    array('team')
213 1
  );
214 1
}
215 1
</code></pre>
216 1
217 7 Kien La
!/images/guides/has_one_through.png!
218 7 Kien La
219 2 Kien La
h4(#self-referential). Self-referential
220 1
221 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.
222 1
223 1
<pre class="code"><code class="php">
224 1
class Post extends ActiveRecord\Model {
225 1
  static $belongs_to = array(array('parent_post', 'class_name' => 'Post'));
226 1
}
227 1
</code></pre> 
228 7 Kien La
229 7 Kien La
!/images/guides/belongs_to_self_referential.png!