finished converting chapter 2 to docbook

manual/docbook/book/conn-mgt.xml

@@ -188,4 +188,186 @@ phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value
       </programlisting>
     </example>
   </sect1>
+  <sect1 id="new-conn">
+    <title>Opening a new connection</title>
+
+    <para>
+      Opening a new database connection in Doctrine is very easy. If you wish
+      to use PDO (<ulink url="http://www.php.net/PDO">www.php.net/PDO</ulink>)
+      you can just initalize a new PDO object:
+    </para>
+    
+    <programlisting role="php"><![CDATA[
+<?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();
+  }
+?>]]></programlisting>
+
+    <para>
+     If your database extension isn't supported by PDO you can use special
+     Doctrine_Adapter class (if availible). The following example uses DB2
+     adapter:
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?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();
+  }
+?>]]></programlisting>
+
+    <para>
+      The next step is opening a new Doctrine_Connection.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  $conn = Doctrine_Manager::connection($dbh);
+?>]]></programlisting>
+  </sect1>
+  <sect1 id="lazy-conn">
+    <title>Lazy Connections</title>
+    <para>
+      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).
+    </para>
+
+    <para>
+      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.
+    </para>
+    <programlisting role="php"><![CDATA[
+<?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');
+?>]]></programlisting>
+  </sect1>
+  <sect1 id="managing-conn">
+    <title>Managing Connections</title>
+    <para>
+      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.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  // Doctrine_Manager controls all the connections
+  $manager = Doctrine_Manager::getInstance();
+
+  // open first connection
+  $conn = $manager->openConnection(new PDO('dsn','username','password'), 'connection 1');
+?>]]></programlisting>
+
+    <para>
+      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.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  // open first connection
+  $conn = Doctrine_Manager::connection(new PDO('dsn','username','password'), 'connection 1');
+
+  $conn2 = Doctrine_Manager::connection();
+  // $conn2 == $conn
+?>]]></programlisting>
+
+    <para>
+      The current connection is the lastly opened connection. 
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  // open second connection
+  $conn2 = $manager->openConnection(new PDO('dsn2','username2','password2'), 'connection 2');
+
+  $manager->getCurrentConnection(); // $conn2
+?>]]></programlisting>
+
+    <para>
+      You can change the current connection by calling setCurrentConnection(). 
+    </para>
+
+
+    <programlisting role="php"><![CDATA[
+<?php
+
+  $manager->setCurrentConnection('connection 1');
+
+  $manager->getCurrentConnection(); // $conn
+
+?>]]></programlisting>
+
+
+    <para>
+      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.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  // iterating through connections
+  foreach($manager as $conn) {
+
+  }
+?>]]></programlisting>
+  </sect1>
+  <sect1 id="conn-component-binding">
+    <title>Connection-component binding</title>
+
+    <para>
+      Doctrine allows you to bind connections to components (= your
+      ActiveRecord? classes). This means everytime a component issues a query
+      or data is being fetched from the table the component is pointing at
+      Doctrine will use the bound connection.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+<?php
+  $conn = $manager->openConnection(new PDO('dsn','username','password'), 'connection 1');
+
+  $conn2 = $manager->openConnection(new PDO('dsn2','username2','password2'), 'connection 2');
+
+  $manager->bindComponent('User', 'connection 1');
+
+  $manager->bindComponent('Group', 'connection 2');
+
+  $q = new Doctrine_Query();
+
+  // Doctrine uses 'connection 1' for fetching here
+  $users = $q->from('User u')->where('u.id IN (1,2,3)')->execute();
+
+  // Doctrine uses 'connection 2' for fetching here
+  $groups = $q->from('Group g')->where('g.id IN (1,2,3)')->execute();
+?>]]></programlisting>
+  </sect1>
 </chapter>