From cb79beca1704eac5d7dc12ad53c67c9760eb69e4 Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Sat, 3 Mar 2007 13:16:03 +0000
Subject: [PATCH] docs for unique constraint

---
 ... - Constraints and validators - Unique.php | 30 +++++++++++
 ...Foreign key constraints - Introduction.php | 53 ++++++++++++-------
 2 files changed, 65 insertions(+), 18 deletions(-)
 create mode 100644 manual/docs/Object relational mapping - Constraints and validators - Unique.php

diff --git a/manual/docs/Object relational mapping - Constraints and validators - Unique.php b/manual/docs/Object relational mapping - Constraints and validators - Unique.php
new file mode 100644
index 000000000..6d4b71bb1
--- /dev/null
+++ b/manual/docs/Object relational mapping - Constraints and validators - Unique.php	
@@ -0,0 +1,30 @@
+Unique constraints ensure that the data contained in a column or a group of columns is unique with respect to all the rows in the table.
+
+The following definition uses a unique constraint for column 'name'.
+
+<code type='php'>
+class User extends Doctrine_Record
+{
+    public function setTableDefinition()
+    {
+        $this->hasColumn('name', 'string', 200, array('unique' => true));
+    }
+}
+</code>
+
+>> Note: You should only use unique constraints for other than primary key columns. Primary key columns are always unique.
+
+The following definition adds a unique constraint for columns 'name' and 'age'.
+
+<code type='php'>
+class User extends Doctrine_Record
+{
+    public function setTableDefinition()
+    {
+        $this->hasColumn('name', 'string', 200);
+        $this->hasColumn('age', 'integer', 2);
+        
+        $this->unique(array('name', 'age'));
+    }
+}
+</code> 
diff --git a/manual/docs/Object relational mapping - Relations - Foreign key constraints - Introduction.php b/manual/docs/Object relational mapping - Relations - Foreign key constraints - Introduction.php
index 080274886..c831c872d 100644
--- a/manual/docs/Object relational mapping - Relations - Foreign key constraints - Introduction.php	
+++ b/manual/docs/Object relational mapping - Relations - Foreign key constraints - Introduction.php	
@@ -1,29 +1,46 @@
-A foreign key constraint specifies that the values in a column (or a group of columns) must match the values appearing in some row of another table. We say this maintains the referential integrity between two related tables.
+A foreign key constraint specifies that the values in a column (or a group of columns) must match the values appearing in some row of another table. In other words foreign key constraints maintain the referential integrity between two related tables.
 
-Say you have the product table that we have used several times already:
+Say you have the product table with the following definition:
 
-CREATE TABLE products (
-    product_no integer PRIMARY KEY,
-    name text,
-    price numeric
-);
+<code type='php'>
+class Product extends Doctrine_Record 
+{
+    public function setTableDefinition() 
+    {
+        $this->hasColumn('id', 'integer', null, 'primary');
+        $this->hasColumn('name', 'string');
+        $this->hasColumn('price', 'numeric');
+    }
+}
+</code>
 
-Let's also assume you have a table storing orders of those products. We want to ensure that the orders table only contains orders of products that actually exist. So we define a foreign key constraint in the orders table that references the products table:
+Let's also assume you have a table storing orders of those products. We want to ensure that the order table only contains orders of products that actually exist. So we define a foreign key constraint in the orders table that references the products table:
+
+<code type='php'>
+class Order extends Doctrine_Record
+{
+    public function setTableDefinition() 
+    {
+        $this->hasColumn('order_id', 'integer', null, 'primary');
+        $this->hasColumn('product_id', 'integer');
+        $this->hasColumn('quantity', 'integer');
+    }
+    public function setUp()
+    {
+        $this->hasOne('Product', 'Order.product_id', array('constraint' => true));
+    }
+}
+</code>
+
+When exported the class 'Order' would execute the following sql: 
 
 CREATE TABLE orders (
     order_id integer PRIMARY KEY,
-    product_no integer REFERENCES products (product_no),
+    product_no integer REFERENCES products (id),
     quantity integer
-);
+)
 
-Now it is impossible to create orders with product_no entries that do not appear in the products table. 
+Now it is impossible to create orders with product_no entries that do not appear in the products table.
 
 We say that in this situation the orders table is the referencing table and the products table is the referenced table. Similarly, there are referencing and referenced columns. 
 
-You can also shorten the above command to
-
-CREATE TABLE orders (
-    order_id integer PRIMARY KEY,
-    product_no integer REFERENCES products,
-    quantity integer
-);