From 94c7b9f6ef036758b7a0e82b1e91320818572599 Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Mon, 6 Aug 2007 20:01:36 +0000
Subject: [PATCH]

---
 .../dealing-with-relations.txt                | 136 ++++++++++--------
 1 file changed, 76 insertions(+), 60 deletions(-)

diff --git a/manual/new/docs/en/working-with-objects/dealing-with-relations.txt b/manual/new/docs/en/working-with-objects/dealing-with-relations.txt
index b13198116..8ac5f7469 100644
--- a/manual/new/docs/en/working-with-objects/dealing-with-relations.txt
+++ b/manual/new/docs/en/working-with-objects/dealing-with-relations.txt
@@ -1,64 +1,80 @@
-+++ Creating related records
-
-When accessing related records and if those records do not exists Doctrine automatically creates new records.
-
-<code type="php">
-// NOTE: related record have always the first letter in uppercase
-$email = $user->Email;
-
-$email->address = 'jackdaniels@drinkmore.info';
-
-$user->save();
-
-// alternative:
-
-$user->Email->address = 'jackdaniels@drinkmore.info';
-
-$user->save();
-</code>
-
++++ Creating related records
 
-+++ Retrieving related records
-
-You can retrieve related records by the very same {{Doctrine_Record}} methods you've already propably used for accessing record properties. When accessing related record you just simply use the class names. 
-
-<code type="php">
-print $user->Email['address'];
-
-print $user->Phonenumber[0]->phonenumber;
-
-print $user->Group[0]->name;
-</code>
-
+Accessing related records in Doctrine is easy: you can use exactly the same getters and setters as for the record properties. 
 
-+++ 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>
-
+You can use any of the three ways above, however the last one is the recommended one for array portability purposes.
 
-+++ Deleting related records
-
-You can delete related records individually be calling {{delete()}} on each record. If you want to delete a whole record graph just call delete on the owner record.
-
-<code type="php">
-$user->Email->delete();
-
-$user->Phonenumber[3]->delete();
-
-// deleting user and all related objects:
-
-$user->delete();
-</code>
-
+<code type="php">
+$user->Email;
 
-+++ Working with associations
+$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 relations 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>
+
++++ Retrieving related records
+
+You can retrieve related records by the very same {{Doctrine_Record}} methods you've already propably used for accessing record properties. When accessing related record you just simply use the class names. 
+
+<code type="php">
+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 each record. If you want to delete a whole record graph just call delete on the owner record.
+
+<code type="php">
+$user->Email->delete();
+
+$user->Phonenumber[3]->delete();
+
+// deleting user and all related objects:
+
+$user->delete();
+</code>