Another way to easily create a link between two related components is by using Doctrine_Record::link(). It often happens that you have two existing records that you would like to relate (or link) to one another. In this case, if there is a relation defined between the involved record classes, you only need the identifiers of the related record(s):
<code type="php">
// We keep track of the new phone number identifiers
$phoneIds = array();
// Some phone numbers are created...
$phone1 = new Phonenumber();
$phone1['phonenumber'] = '555 202 7890';
$phone1->save();
$phoneIds[] = $phone1['id'];
$phone2 = new Phonenumber();
$phone2['phonenumber'] = '555 100 7890';
$phone2->save();
$phoneIds[] = $phone2['id'];
// Some user is created...
$user = new User();
$user['name'] = 'Werner Mollentze';
$user->save();
// Let's link the phone numbers to the user, since the relation to Phonenumber exists for the User record...
$user->link('Phonenumber', $phoneIds);
</code>
If a relation to the User record class is defined for the Phonenumber record class, you may even do this:
<code type="php">
// Some user is created...
$user = new User();
$user['name'] = 'wernerm';
$user->save();
// Some phone numbers are created and linked to the User on-the-fly...
// This is possible if a relation to User exists for the Phonenumber record
$phone1 = new Phonenumber();
$phone1['phonenumber'] = '555 202 7890';
$phone1->save();
// Let's link this Phonenumber to our User...
$phone1->link('User', array($user['id']));
// We create another phone number...
$phone2 = new Phonenumber();
$phone2['phonenumber'] = '555 100 7890';
$phone2->save();
// Let's link this Phonenumber to our User too...
$phone2->link('User', array($user['id']));
</code>
+++ Retrieving related records
You can retrieve related records by the very same {{Doctrine_Record}} methods as in the previous subchapter. Please note that whenever you access a related component that isn't already loaded Doctrine uses one SQL SELECT statement for the fetching, hence the following example executes 4 SQL SELECTs.
