added some docs for the upcoming new Doctrine_DB

manual/codes/Basic Components - Connection - Querying the database.php

@@ -2,9 +2,13 @@
 
 // select all users
 
-$conn->query("FROM User");
+$users = $conn->query("FROM User");
 
 // select all users where user email is jackdaniels@drinkmore.info
 
-$conn->query("FROM User WHERE User.Email.address = 'jackdaniels@drinkmore.info'");
+$users = $conn->query("FROM User WHERE User.Email.address = 'jackdaniels@drinkmore.info'");
+
+// using prepared statements
+
+$users = $conn->query("FROM User WHERE User.name = ?", array('Jack'));
 ?>

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

+<?php
+
+// using PDO dsn for connecting sqlite memory table
+
+$dbh = Doctrine_DB::getConnection('sqlite::memory:');
+
+class Counter extends Doctrine_DB_EventListener {
+    private $queries = 0;
+
+    public function onQuery(Doctrine_DB $dbh, $query, $params) {
+        $this->queries++;
+    }
+    public function count() {
+        return count($this->queries);
+    }
+}
+class OutputLogger extends Doctrine_Overloadable {
+    public function __call($m, $a) {
+        print $m." called!";
+    }
+}
+$counter = new Counter();
+
+$dbh->addListener($counter);
+$dbh->addListener(new OutputLogger());
+
+$dbh->query("SELECT * FROM foo"); 
+// prints:
+// onPreQuery called!
+// onQuery called!
+
+print $counter->count(); // 1
+
+?>

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

+<?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

+<?php
+
+// using PDO dsn for connecting sqlite memory table
+
+$dbh = Doctrine_DB::getConnection('sqlite::memory:');
+
+class MyLogger extends Doctrine_DB_EventListener {
+    public function onPreQuery(Doctrine_DB $dbh, $query, $params) {
+        print "database is going to be queried!";
+    }
+    public function onQuery(Doctrine_DB $dbh, $query, $params) {
+        print "executed: $query";
+    }
+}
+
+$dbh->setListener(new MyLogger());
+
+$dbh->query("SELECT * FROM foo"); 
+// prints:
+// database is going to be queried
+// executed: SELECT * FROM foo
+
+
+class MyLogger2 extends Doctrine_Overloadable {
+    public function __call($m, $a) {
+        print $m." called!";
+    }
+}
+
+$dbh->setListener(new MyLogger2());
+
+$dbh->exec("DELETE FROM foo");
+// prints:
+// onPreExec called!
+// onExec called!
+?>

manual/codes/Basic Components - Record - Checking existence.php

+<?php
+$record = new User();
+
+$record->exists(); // false
+
+$record->name = 'someone';
+$record->save();
+
+$record->exists(); // true
+?>

manual/codes/Basic Components - Record - Getting record state.php

@@ -3,27 +3,27 @@ $state = $record->getState();
 
 switch($state):
     case Doctrine_Record::STATE_PROXY:
-        // data access object is in proxy state, 
+        // record is in proxy state, 
         // meaning its persistent but not all of its properties are
         // loaded from the database
     break;
     case Doctrine_Record::STATE_TCLEAN:
-        // data access object is transient clean,
+        // record is transient clean,
         // meaning its transient and 
         // none of its properties are changed
     break;
     case Doctrine_Record::STATE_TDIRTY:
-        // data access object is transient dirty, 
+        // record is transient dirty,
         // meaning its transient and 
         // some of its properties are changed
     break;
     case Doctrine_Record::STATE_DIRTY:
-        // data access object is dirty, 
+        // record is dirty, 
         // meaning its persistent and 
         // some of its properties are changed
     break;
     case Doctrine_Record::STATE_CLEAN:
-        // data access object is clean, 
+        // record is clean,
         // meaning its persistent and 
         // none of its properties are changed
     break;

manual/docs/Basic Components - Connection - Querying the database.php

+Doctrine_Connection::query() is a simple method for efficient object retrieval. It takes one parameter (DQL query) and optionally prepared statement params.

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

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

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

+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
+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().
+<br \><br \>
+4. Supports PEAR-like data source names as well as PDO data source names.

manual/documentation.php

@@ -144,7 +144,7 @@ $menu = array("Getting started" =>
                                          "Getting record state",
                                          "Getting object copy",
                                          "Serializing",
-                                         "Existence checking",
+                                         "Checking Existence",
                                          "Callbacks"),
                         "Connection"
                                 => array("Introduction",
@@ -194,7 +194,8 @@ $menu = array("Getting started" =>
                         "DB"     => array(
                                          "Introduction",
                                          "Connecting to a database",
-                                         "Using event listeners"),
+                                         "Using event listeners",
+                                         "Chaining listeners"),
                                          /**
                         "Statement - <font color='red'>UNDER CONSTRUCTION</font>" => array("Introduction",
                                              "Setting parameters",