+++ Creating related records

Accessing related records in Doctrine is easy: you can use exactly the same getters and setters as for the record properties.

You can use any of the three ways above, however the last one is the recommended one for array portability purposes.

<code type="php">
$user->Email;

$user->get('Email');

$user['Email'];
</code>

When accessing a one-to-one related record that doesn't exist, Doctrine automatically creates the object. So for example the following code is possible:

<code type="php">
$user = new User();
$user->name = 'some user';

$user->Email->address = 'some@one.info';
// saves the user and the associated email
$user->save();
</code>

When accessing one-to-many related records, Doctrine creates a Doctrine_Collection for the related component. Lets say we have users and phonenumbers and their relation is one-to-many. You can add phonenumbers easily as shown above:

<code type="php">
$user = new User();
$user->name = 'some user';

$user->Phonenumber[]->phonenumber = '123 123';
$user->Phonenumber[]->phonenumber = '456 123';
$user->Phonenumber[]->phonenumber = '123 777';

// saves the user and the associated phonenumbers
$user->save();
</code>

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.

<code type="php">
$user = $conn->getTable('User')->find(5);

print $user->Email['address'];

print $user->Phonenumber[0]->phonenumber;

print $user->Group[0]->name;
</code>

Much more efficient way of doing this is using DQL. The following example uses only one SQL query for the retrieval of related components.

<code type="php">
$user = Doctrine_Query::create()
        ->from('User u')
        ->leftJoin('u.Email e')
        ->leftJoin('u.Phonenumber p')
        ->leftJoin('u.Group g')
        ->execute();

print $user->Email['address'];

print $user->Phonenumber[0]->phonenumber;

print $user->Group[0]->name;
</code>


+++ Updating related records

You can update the related records by calling save for each related object / collection individually or by calling save on the object that owns the other objects. You can also call {{Doctrine_Connection::flush}} which saves all pending objects.

<code type="php">
$user->Email['address'] = 'koskenkorva@drinkmore.info';

$user->Phonenumber[0]->phonenumber = '123123';

$user->save();

// saves the email and phonenumber
</code>


+++ Deleting related records

You can delete related records individually be calling {{delete()}} on a record or on a collection.

<code type="php">
$user->Email->delete();

$user->Phonenumber[3]->delete();

// deleting user and all related objects:

$user->delete();
</code>

Usually in a typical web application the primary keys of the related objects that are to be deleted come from a form. In this case the most efficient way of deleting the related records is using DQL DELETE statement. Lets say we have once again users and phonenumbers with their relation being one-to-many. Deleting the given phonenumbers for given user id can be achieved as follows:

<code type="php">
$deleted = Doctrine_Query::create()
           ->delete()
           ->from('Phonenumber')
           ->addWhere('user_id = ?', array($userId))
           ->whereIn('id', $phonenumberIds);
           ->execute();
// print out the number of deleted phonenumbers
print $deleted;
</code>

Sometimes you may not want to delete the phonenumber records but to simply unlink the relations by setting the foreing key fields to null. This can ofcourse be achieved with DQL but perhaps to most elegant way of doing this is by using Doctrine_Record::unlink(). Please note that the unlink method is very smart. It not only sets the foreign fields for related phonenumbers to null but it also removes all given phonenumber references from the User object.

Lets say we have a User who has 3 Phonenumbers (with identifiers 1, 2 and 3). Now unlinking the Phonenumbers 1 and 3 can be achieved as easily as:

<code type="php">
$user->unlink('Phonenumber', array(1, 3));

$user->Phonenumber->count(); // 1
</code>

+++ Working with related records

++++ Testing the existance of a relation
<code type="php">
$obj = new Model();
if(isset($obj->Relation())) { // returns false
        ...
}
$obj->Relation = new Relation();
if(isset($obj->Relation())) { // returns true
        ...
}
</code>