From ac34e4bfc00a8d23830f86fd19997384fd0a5fcb Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Thu, 14 Dec 2006 13:27:10 +0000
Subject: [PATCH] added connection management docs

---
 ...nagement - Lazy-connecting to database.php | 21 ++++++
 ...tion management - Managing connections.php | 71 +++++++++++++++++++
 ... management - Opening a new connection.php | 40 +++++++++++
 ...Doctrine Query Language) - FROM clause.php |  2 +-
 4 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 manual/docs/Connection management - Lazy-connecting to database.php
 create mode 100644 manual/docs/Connection management - Managing connections.php
 create mode 100644 manual/docs/Connection management - Opening a new connection.php

diff --git a/manual/docs/Connection management - Lazy-connecting to database.php b/manual/docs/Connection management - Lazy-connecting to database.php
new file mode 100644
index 000000000..44646ea6b
--- /dev/null
+++ b/manual/docs/Connection management - Lazy-connecting to database.php	
@@ -0,0 +1,21 @@
+<?php ?>
+Lazy-connecting to database is handled via Doctrine_Db wrapper. When using Doctrine_Db instead of PDO / Doctrine_Adapter, lazy-connecting 
+to database is being performed (that means Doctrine will only connect to database when needed). <br \><br \>This feature can be very useful
+when using for example page caching, hence not actually needing a database connection on every request. Remember connecting to database is an expensive operation.
+<br \> <br \>
+<?php
+renderCode("<?php
+// we may use PDO / PEAR like DSN
+// here we use PEAR like DSN
+\$dbh = new Doctrine_Db('mysql://username:password@localhost/test');
+// !! no actual database connection yet !!
+
+// initalize a new Doctrine_Connection
+\$conn = Doctrine_Manager::connection(\$dbh);
+// !! no actual database connection yet !!
+
+// connects database and performs a query
+\$conn->query('FROM User u');
+
+?>");
+?>
diff --git a/manual/docs/Connection management - Managing connections.php b/manual/docs/Connection management - Managing connections.php
new file mode 100644
index 000000000..4279c5c3b
--- /dev/null
+++ b/manual/docs/Connection management - Managing connections.php	
@@ -0,0 +1,71 @@
+<?php ?>
+From the start Doctrine has been designed to work with multiple connections. Unless separately specified Doctrine always uses the current connection 
+for executing the queries. The following example uses openConnection() second argument as an optional
+connection alias.
+<br \><br \>
+<?php
+renderCode("<?php
+// Doctrine_Manager controls all the connections
+
+\$manager = Doctrine_Manager::getInstance();
+
+// open first connection
+ 
+\$conn = \$manager->openConnection(new PDO('dsn','username','password'), 'connection 1');
+?>
+");
+?>
+<br \><br \>
+For convenience Doctrine_Manager provides static method connection() which opens new connection when arguments are given to it and returns the current
+connection when no arguments have been speficied.
+<br \><br \>
+<?php
+renderCode("<?php
+// open first connection
+ 
+\$conn = Doctrine_Manager::connection(new PDO('dsn','username','password'), 'connection 1');
+
+\$conn2 = Doctrine_Manager::connection();
+
+// \$conn2 == \$conn
+?>
+");
+?>
+
+
+<br \><br \>
+The current connection is the lastly opened connection. 
+<br \><br \>
+<?php
+renderCode("<?php
+// open second connection
+
+\$conn2 = \$manager->openConnection(new PDO('dsn2','username2','password2'), 'connection 2');
+
+\$manager->getCurrentConnection(); // \$conn2
+?>");
+?>
+<br \><br \>
+You can change the current connection by calling setCurrentConnection(). 
+<br \><br \>
+<?php
+renderCode("<?php
+\$manager->setCurrentConnection('connection 1');
+
+\$manager->getCurrentConnection(); // \$conn
+?>
+");
+?>
+<br \><br \>
+You can iterate over the opened connection by simple passing the manager object to foreach clause. This is possible since Doctrine_Manager implements
+special IteratorAggregate interface.
+<br \><br \>
+<?php
+renderCode("<?php
+// iterating through connections
+
+foreach(\$manager as \$conn) {
+
+}
+?>");
+?>
diff --git a/manual/docs/Connection management - Opening a new connection.php b/manual/docs/Connection management - Opening a new connection.php
new file mode 100644
index 000000000..0b6dffa9d
--- /dev/null
+++ b/manual/docs/Connection management - Opening a new connection.php	
@@ -0,0 +1,40 @@
+<?php ?>
+Opening a new database connection in Doctrine is very easy. If you wish to use PDO (www.php.net/PDO) you can just initalize a new PDO object:
+<br \> <br \>
+<?php
+renderCode("<?php
+\$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
+\$user = 'dbuser';
+\$password = 'dbpass';
+
+try {
+    \$dbh = new PDO(\$dsn, \$user, \$password);
+} catch (PDOException \$e) {
+    echo 'Connection failed: ' . \$e->getMessage();
+}
+?>");
+?>
+<br \><br \>
+If your database extension isn't supported by PDO you can use special Doctrine_Adapter class (if availible). The following example uses db2 adapter:
+<br \><br \>
+<?php
+renderCode("<?php
+\$dsn = 'db2:dbname=testdb;host=127.0.0.1';
+\$user = 'dbuser';
+\$password = 'dbpass';
+
+try {
+    \$dbh = Doctrine_Adapter::connect(\$dsn, \$user, \$password);
+} catch (PDOException \$e) {
+    echo 'Connection failed: ' . \$e->getMessage();
+}
+?>");
+?>
+<br \><br \>
+The next step is opening a new Doctrine_Connection.
+<br \><br \>
+<?php
+renderCode("<?php
+\$conn = Doctrine_Manager::connection(\$dbh);
+?>");
+?>
diff --git a/manual/docs/DQL (Doctrine Query Language) - FROM clause.php b/manual/docs/DQL (Doctrine Query Language) - FROM clause.php
index 53c91ef2d..084b837a6 100644
--- a/manual/docs/DQL (Doctrine Query Language) - FROM clause.php	
+++ b/manual/docs/DQL (Doctrine Query Language) - FROM clause.php	
@@ -21,7 +21,7 @@ SELECT u.*, p.* FROM User u, u.Phonenumber p
 </pre>
 </div>  
 
-<li \><i>INNER JOIN</i> produces a Cartesian product between two specified components (that is, each and every record in the first component is joined to each and every record in the second component).
+<li \><i>INNER JOIN</i> produces an intersection between two specified components (that is, each and every record in the first component is joined to each and every record in the second component).
 So basically <i>INNER JOIN</i> can be used when you want to efficiently fetch for example all users which have one or more phonenumbers.
 <div class='sql'>
 <pre>