Updated Doctrine_Db docs

manual/codes/Basic Components - DB - Chaining listeners.php

@@ -2,12 +2,12 @@
 
 // using PDO dsn for connecting sqlite memory table
 
-$dbh = Doctrine_DB::getConnection('sqlite::memory:');
+$dbh = Doctrine_Db::getConnection('sqlite::memory:');
 
-class Counter extends Doctrine_DB_EventListener {
+class Counter extends Doctrine_Db_EventListener {
     private $queries = 0;
 
-    public function onQuery(Doctrine_DB $dbh, $query, $params) {
+    public function onQuery(Doctrine_Db_Event $event) {
         $this->queries++;
     }
     public function count() {

manual/codes/Basic Components - DB - Connecting to a database.php

@@ -1,11 +1 @@
-<?php
 
-// using PDO dsn for connecting sqlite memory table
-
-$dbh = Doctrine_DB::getConnection('sqlite::memory:');
-
-// using PEAR like dsn for connecting mysql database
-
-$dsn = 'mysql://root:password@localhost/test';
-$dbh = Doctrine_DB::getConnection($dsn);
-?>

manual/codes/Basic Components - DB - Using event listeners.php

@@ -2,14 +2,14 @@
 
 // using PDO dsn for connecting sqlite memory table
 
-$dbh = Doctrine_DB::getConnection('sqlite::memory:');
+$dbh = Doctrine_Db::getConnection('sqlite::memory:');
 
-class MyLogger extends Doctrine_DB_EventListener {
+class MyLogger extends Doctrine_Db_EventListener {
-    public function onPreQuery(Doctrine_DB $dbh, $query, $params) {
+    public function onPreQuery(Doctrine_Db_Event $event) {
         print "database is going to be queried!";
     }
-    public function onQuery(Doctrine_DB $dbh, $query, $params) {
+    public function onQuery(Doctrine_Db_Event $event) {
-        print "executed: $query";
+        print "executed: " . $event->getQuery();
     }
 }
 

manual/docs/Basic Components - DB - Chaining listeners.php

@@ -0,0 +1,7 @@
+Doctrine_Db supports event listener chaining. It means multiple listeners can be attached for 
+listening the events of a single instance of Doctrine_Db. 
+<br \><br \>
+For example you might want to add different aspects to your Doctrine_Db instance on-demand. These aspects may include
+caching, query profiling etc.
+<br \><br \>
+

manual/docs/Basic Components - DB - Connecting to a database.php

@@ -1,14 +1,56 @@
+<?php ?>
+Doctrine_Db allows both PEAR-like DSN (data source name) as well as PDO like DSN as constructor parameters.
+<br \><br \>
+Getting an instance of Doctrine_Db using PEAR-like DSN:
+<br \><br \>
 <?php
+$str = "<?php
+// using PEAR like dsn for connecting pgsql database
 
-// using PDO like dsn for connecting sqlite memory table
+\$dbh = new Doctrine_Db('pgsql://root:password@localhost/mydb');
-
-$dbh = Doctrine_DB::getConnection('sqlite::memory:');
-
-// using PDO like dsn for connecting pgsql database
-
-$dbh = Doctrine_DB::getConnection('pgsql://root:password@localhost/mydb');
 
 // using PEAR like dsn for connecting mysql database
 
-$dbh = Doctrine_DB::getConnection('mysql://root:password@localhost/test');
+\$dbh = new Doctrine_Db('mysql://root:password@localhost/test');
+?>";
+renderCode($str);
+?>
+<br \><br \>
+Getting an instance of Doctrine_Db using PDO-like DSN (PDO mysql driver):
+<br \><br \>
+<?php
+$str = "<?php
+\$dbh = new Doctrine_Db('mysql:host=localhost;dbname=test', 
+                        \$user, \$pass);
+?>";
+renderCode($str);
+?>
+<br \><br \>
+Getting an instance of Doctrine_Db using PDO-like DSN (PDO sqlite with memory tables):
+<br \> <br \>
+<?php
+$str = "<?php
+\$dbh = new Doctrine_Db('sqlite::memory:');
+?>";
+renderCode($str);
+?>
+<br \><br \>
+
+Handling connection errors:
+
+<?php
+$str = "<?php
+try {
+   \$dbh = new Doctrine_Db('mysql:host=localhost;dbname=test', 
+                           \$user, \$pass);
+   foreach (\$dbh->query('SELECT * FROM foo') as \$row) {
+     print_r(\$row);
+   }
+   \$dbh = null;
+} catch (PDOException \$e) {
+   print 'Error!: ' . \$e->getMessage() . '<br />';
+   die();
+}
+?>";
+renderCode($str);
 ?>

manual/docs/Basic Components - DB - Introduction.php

@@ -1,10 +1,10 @@
-Doctrine_DB is a wrapper for PDO database object. Why should you consider using Doctrine_DB instead of PDO? 
+Doctrine_Db is a wrapper for PDO database object. Why should you consider using Doctrine_Db instead of PDO? 
 <br \><br \>
 1. It provides efficient eventlistener architecture, hence its easy to add new aspects to existing methods like on-demand-caching
 <br \><br \>
-2. Doctrine_DB lazy-connects database. Creating an instance of Doctrine_DB doesn't directly connect database, hence
+2. Doctrine_Db lazy-connects database. Creating an instance of Doctrine_Db doesn't directly connect database, hence
-Doctrine_DB fits perfectly for application using for example page caching.
+Doctrine_Db fits perfectly for application using for example page caching.
 <br \><br \>
-3. It has many short cuts for commonly used fetching methods like Doctrine_DB::fetchOne().
+3. It has many short cuts for commonly used fetching methods like Doctrine_Db::fetchOne().
 <br \><br \>
 4. Supports PEAR-like data source names as well as PDO data source names.

manual/docs/Basic Components - DB - Using event listeners.php

@@ -0,0 +1,39 @@
+<?php ?>
+Doctrine_Db has a pluggable event listener architecture. It provides before and after
+listeners for all relevant methods. Every listener method takes one parameter: a Doctrine_Db_Event object, which
+holds info about the occurred event.
+<br \><br \>
+Every listener object must either implement the Doctrine_Db_EventListener_Interface or Doctrine_Overloadable interface. 
+Using Doctrine_Overloadable interface
+only requires you to implement __call() which is then used for listening all the events.  <br \><br \>
+<?php
+
+$str = "<?php
+class OutputLogger extends Doctrine_Overloadable {
+    public function __call(\$m, \$a) {
+        print \$m . ' called!';
+    }
+}
+?>";
+renderCode($str);
+?>
+<br \><br \>
+For convience
+you may want to make your listener class extend Doctrine_Db_EventListener which has empty listener methods, hence allowing you not to define
+all the listener methods by hand. The following listener, 'MyLogger', is used for listening only onPreQuery and onQuery methods.<br \><br \>
+<?php
+$str = "<?php
+class MyLogger extends Doctrine_Db_EventListener {
+    public function onPreQuery(Doctrine_Db_Event \$event) {
+        print 'database is going to be queried!';
+    }
+    public function onQuery(Doctrine_Db_Event \$event) {
+        print 'executed: ' . \$event->getQuery();
+    }
+}
+?>";
+renderCode($str);
+?>
+<br \><br \>
+Now the next thing we need to do is bind the eventlistener objects to our database handler.
+<br \><br \>

manual/documentation.php

@@ -59,15 +59,17 @@ function render_block($name) {
         renderCode($c);
     }
 }
+
 function renderCode($c = null) {
+    global $h;
     if( ! empty($c)) {
-        $h = new PHP_Highlight;
+
         $h->loadString($c);
 
         print "<table width=500 border=1 class='dashed' cellpadding=0 cellspacing=0>";
         print "<tr><td>";
 
-        print $h->toHtml();
+        $h->toHtml();
         print "</td></tr>";
         print "</table>";
     }
@@ -197,7 +199,7 @@ $menu = array("Getting started" =>
                                          "Using SQL",
                                          "Adding components",
                                          "Method overloading"),
-                        "DB"     => array(
+                        "Db"     => array(
                                          "Introduction",
                                          "Connecting to a database",
                                          "Using event listeners",