From 0c94b003b1e30d0d5fad73a9028e2c08e6b675da Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Fri, 29 Sep 2006 11:49:50 +0000
Subject: [PATCH] added some docs for the upcoming new Doctrine_DB

---
 ...s - Connection - Querying the database.php |  8 +++--
 ...c Components - DB - Chaining listeners.php | 34 ++++++++++++++++++
 ...onents - DB - Connecting to a database.php | 11 ++++++
 ...omponents - DB - Using event listeners.php | 36 +++++++++++++++++++
 ...mponents - Record - Checking existence.php | 10 ++++++
 ...onents - Record - Getting record state.php | 10 +++---
 ...s - Connection - Querying the database.php |  1 +
 ...onents - DB - Connecting to a database.php | 10 ++++++
 .../Basic Components - DB - Introduction.php  | 10 ++++++
 manual/documentation.php                      |  5 +--
 10 files changed, 126 insertions(+), 9 deletions(-)
 create mode 100644 manual/codes/Basic Components - DB - Chaining listeners.php
 create mode 100644 manual/codes/Basic Components - DB - Connecting to a database.php
 create mode 100644 manual/codes/Basic Components - DB - Using event listeners.php
 create mode 100644 manual/codes/Basic Components - Record - Checking existence.php
 create mode 100644 manual/docs/Basic Components - DB - Connecting to a database.php
 create mode 100644 manual/docs/Basic Components - DB - Introduction.php

diff --git a/manual/codes/Basic Components - Connection - Querying the database.php b/manual/codes/Basic Components - Connection - Querying the database.php
index 0af62777c..2a493abc3 100644
--- a/manual/codes/Basic Components - Connection - Querying the database.php	
+++ b/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'));
 ?>
diff --git a/manual/codes/Basic Components - DB - Chaining listeners.php b/manual/codes/Basic Components - DB - Chaining listeners.php
new file mode 100644
index 000000000..f3925ffec
--- /dev/null
+++ b/manual/codes/Basic Components - DB - Chaining listeners.php	
@@ -0,0 +1,34 @@
+<?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
+
+?>
diff --git a/manual/codes/Basic Components - DB - Connecting to a database.php b/manual/codes/Basic Components - DB - Connecting to a database.php
new file mode 100644
index 000000000..d8af8dde3
--- /dev/null
+++ b/manual/codes/Basic Components - DB - Connecting to a database.php	
@@ -0,0 +1,11 @@
+<?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);
+?>
diff --git a/manual/codes/Basic Components - DB - Using event listeners.php b/manual/codes/Basic Components - DB - Using event listeners.php
new file mode 100644
index 000000000..a2a2feb2e
--- /dev/null
+++ b/manual/codes/Basic Components - DB - Using event listeners.php	
@@ -0,0 +1,36 @@
+<?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!
+?>
diff --git a/manual/codes/Basic Components - Record - Checking existence.php b/manual/codes/Basic Components - Record - Checking existence.php
new file mode 100644
index 000000000..19b2d36c3
--- /dev/null
+++ b/manual/codes/Basic Components - Record - Checking existence.php	
@@ -0,0 +1,10 @@
+<?php
+$record = new User();
+
+$record->exists(); // false
+
+$record->name = 'someone';
+$record->save();
+
+$record->exists(); // true
+?>
diff --git a/manual/codes/Basic Components - Record - Getting record state.php b/manual/codes/Basic Components - Record - Getting record state.php
index 21148fca2..fd2bd3b4a 100644
--- a/manual/codes/Basic Components - Record - Getting record state.php	
+++ b/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;
diff --git a/manual/docs/Basic Components - Connection - Querying the database.php b/manual/docs/Basic Components - Connection - Querying the database.php
index e69de29bb..62cab24de 100644
--- a/manual/docs/Basic Components - Connection - Querying the database.php	
+++ b/manual/docs/Basic Components - Connection - Querying the database.php	
@@ -0,0 +1 @@
+Doctrine_Connection::query() is a simple method for efficient object retrieval. It takes one parameter (DQL query) and optionally prepared statement params.
diff --git a/manual/docs/Basic Components - DB - Connecting to a database.php b/manual/docs/Basic Components - DB - Connecting to a database.php
new file mode 100644
index 000000000..bc6c43de3
--- /dev/null
+++ b/manual/docs/Basic Components - DB - Connecting to a database.php	
@@ -0,0 +1,10 @@
+<?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');
+?>
diff --git a/manual/docs/Basic Components - DB - Introduction.php b/manual/docs/Basic Components - DB - Introduction.php
new file mode 100644
index 000000000..27351d0a4
--- /dev/null
+++ b/manual/docs/Basic Components - DB - Introduction.php	
@@ -0,0 +1,10 @@
+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.
diff --git a/manual/documentation.php b/manual/documentation.php
index 8f56dfff9..6ee7d1077 100644
--- a/manual/documentation.php
+++ b/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",