From 2922c9aff6e11757629b86996fa23d8ed7b93c56 Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Fri, 9 Feb 2007 20:56:04 +0000
Subject: [PATCH] caching docs

---
 lib/Doctrine/Adapter/Statement/Interface.php |  2 +-
 lib/Doctrine/Cache.php                       |  3 +-
 lib/Doctrine/Db.php                          |  2 +
 lib/Doctrine/Db/Statement.php                |  4 +-
 manual/docs/Caching - Availible options.php  | 12 ++++++
 manual/docs/Caching - Introduction.php       | 45 ++++++++++++++++++++
 manual/documentation.php                     | 30 +++++++++++--
 7 files changed, 90 insertions(+), 8 deletions(-)
 create mode 100644 manual/docs/Caching - Availible options.php
 create mode 100644 manual/docs/Caching - Introduction.php

diff --git a/lib/Doctrine/Adapter/Statement/Interface.php b/lib/Doctrine/Adapter/Statement/Interface.php
index d028b7cce..3a22d57c8 100644
--- a/lib/Doctrine/Adapter/Statement/Interface.php
+++ b/lib/Doctrine/Adapter/Statement/Interface.php
@@ -133,7 +133,7 @@ interface Doctrine_Adapter_Statement_Interface
      *                                  bound parameters in the SQL statement being executed.
      * @return boolean                  Returns TRUE on success or FALSE on failure.
      */
-    public function execute(array $params = array());
+    public function execute($params = null);
     /**
      * fetch
      *
diff --git a/lib/Doctrine/Cache.php b/lib/Doctrine/Cache.php
index 1f9807526..2aec1a010 100644
--- a/lib/Doctrine/Cache.php
+++ b/lib/Doctrine/Cache.php
@@ -18,6 +18,7 @@
  * and is licensed under the LGPL. For more information, see
  * <http://www.phpdoctrine.com>.
  */
+Doctrine::autoload('Doctrine_Db_EventListener');
 /**
  * Doctrine_Cache
  *
@@ -234,7 +235,7 @@ class Doctrine_Cache extends Doctrine_Db_EventListener implements Countable, Ite
             while ($i--) {
                 $element = next($stats);
                 $query   = key($stats);
-                
+
                 $hash = md5($query);
 
                 $this->_driver->delete($hash);
diff --git a/lib/Doctrine/Db.php b/lib/Doctrine/Db.php
index 2ef5c1a94..750ab65a8 100644
--- a/lib/Doctrine/Db.php
+++ b/lib/Doctrine/Db.php
@@ -428,7 +428,9 @@ class Doctrine_Db implements Countable, IteratorAggregate, Doctrine_Adapter_Inte
 
         if ( ! empty($params)) {
             $stmt = $this->dbh->prepare($statement);
+
             return $stmt->execute($params);
+            
         } else {
             if ( ! $skip) {
                 $stmt = $this->dbh->query($statement);
diff --git a/lib/Doctrine/Db/Statement.php b/lib/Doctrine/Db/Statement.php
index 13cc79e39..20c03e77a 100644
--- a/lib/Doctrine/Db/Statement.php
+++ b/lib/Doctrine/Db/Statement.php
@@ -52,7 +52,7 @@ class Doctrine_Db_Statement implements Doctrine_Adapter_Statement_Interface
     }
     public function getStatement()
     {
-        return $this->stmt;	
+        return $this->stmt;
     }
     public function getQuery()
     {
@@ -194,7 +194,7 @@ class Doctrine_Db_Statement implements Doctrine_Adapter_Statement_Interface
      *                                  bound parameters in the SQL statement being executed.
      * @return boolean                  Returns TRUE on success or FALSE on failure.
      */
-    public function execute(array $params = array())
+    public function execute($params = null)
     {
         $event = new Doctrine_Db_Event($this, Doctrine_Db_Event::EXECUTE, $this->stmt->queryString, $params);
 
diff --git a/manual/docs/Caching - Availible options.php b/manual/docs/Caching - Availible options.php
new file mode 100644
index 000000000..a59fb9816
--- /dev/null
+++ b/manual/docs/Caching - Availible options.php	
@@ -0,0 +1,12 @@
+Doctrine_Cache offers many options for performance fine-tuning:
+<ul>
+<li \> savePropability <br \>
+Option that defines the propability of which
+a query is getting cached.
+<br \><br \>
+<li \> cleanPropability <br \>
+Option that defines the propability the actual cleaning will occur
+when calling Doctrine_Cache::clean();
+<br \><br \>
+<li \> statsPropability
+<ul \>
diff --git a/manual/docs/Caching - Introduction.php b/manual/docs/Caching - Introduction.php
new file mode 100644
index 000000000..127e6e208
--- /dev/null
+++ b/manual/docs/Caching - Introduction.php	
@@ -0,0 +1,45 @@
+<?php ?>
+Doctrine_Cache offers an intuitive and easy-to-use query caching solution. It provides the following things:
+<ul>
+    <li \> Multiple cache backends to choose from (including Memcached, APC and Sqlite)
+    <br \><br \>
+
+    <li \> Manual tuning and/or self-optimization. Doctrine_Cache knows how to optimize itself, yet it leaves user
+    full freedom of whether or not he/she wants to take advantage of this feature.
+    <br \><br \>
+
+    <li \> Advanced options for fine-tuning. Doctrine_Cache has many options for fine-tuning performance.
+    <br \><br \>
+
+    <li \> Cache hooks itself directly into Doctrine_Db eventlistener system allowing it to be easily added on-demand.
+</ul>
+
+<br \><br \>
+Doctrine_Cache hooks into Doctrine_Db eventlistener system allowing pluggable caching.
+It evaluates queries and puts SELECT statements in cache. The caching is based on propabalistics. For example
+if savePropability = 0.1 there is a 10% chance that a query gets cached. 
+<br \><br \>
+Now eventually the cache would grow very big, hence Doctrine uses propabalistic cache cleaning. 
+When calling Doctrine_Cache::clean() with cleanPropability = 0.25 there is a 25% chance of the clean operation being invoked.
+What the cleaning does is that it first reads all the queries in the stats file and sorts them by the number of times occurred.
+Then if the size is set to 100 it means the cleaning operation will leave 100 most issued queries in cache and delete all other cache entries.
+<br \><br \>
+
+
+<br \><br \>
+Initializing a new cache instance:
+<br \><br \>
+<?php
+renderCode("<?php
+\$dbh   = new Doctrine_Db('mysql:host=localhost;dbname=test', \$user, \$pass);
+
+\$cache = new Doctrine_Cache('memcache');
+
+// register it as a Doctrine_Db listener
+
+\$dbh->addListener(\$cache);
+?>");
+?>
+<br \><br \>
+Now you know how to set up the query cache. In the next chapter you'll learn how to tweak the cache in order to get maximum performance.
+<br \><br \>
diff --git a/manual/documentation.php b/manual/documentation.php
index 1518a78dd..ea5626277 100644
--- a/manual/documentation.php
+++ b/manual/documentation.php
@@ -102,6 +102,7 @@ $menu = array('Getting started' =>
                                         'Introduction',
                                         'Table and class naming',
                                         'Field(Column) naming',
+                                        'Column aliases',
                                         'Table options',
                                         'Data types and lengths',
                                         'Constraints and validators',
@@ -114,7 +115,13 @@ $menu = array('Getting started' =>
                                         'Autoincremented',
                                         'Natural',
                                         'Composite',
-                                        'Sequence')
+                                        'Sequence'),
+                        'Indexes' => array(
+                                     'Introduction',
+                                     'Adding indexes',
+                                     'Index options',
+                                     'Special indexes',
+                                    ),
                         ),
            'Connection management' =>
                         array(
@@ -372,7 +379,10 @@ $menu = array('Getting started' =>
 
                             array(
                                   'Introduction',
-                                  'SELECT queries',
+                                  'SELECT queries' =>
+                                        array('DISTINCT keyword',
+                                              'Aggregate values',
+                                              ),
                                   'UPDATE queries',
                                   'DELETE queries',
                                   'FROM clause',
@@ -380,7 +390,6 @@ $menu = array('Getting started' =>
                                   'Conditional expressions' =>
                                         array('Literals',
                                               'Input parameters',
-
                                               'Operators and operator precedence',
                                               'Between expressions',
                                               'In expressions',
@@ -398,7 +407,10 @@ $menu = array('Getting started' =>
                                               'Collection functions'),
 
                                   'GROUP BY, HAVING clauses',
-                                  'ORDER BY clause',
+                                  'ORDER BY clause' 
+                                        => array('Introduction',
+                                                 'Sorting by an aggregate value',
+                                                 'Using random order'),
                                   'LIMIT and OFFSET clauses' =>
                                         array('Introduction',
                                               'Driver portability',
@@ -421,6 +433,16 @@ $menu = array('Getting started' =>
                         'Isolation levels',
                         'Deadlocks',
 
+                        ),
+           'Caching' => array(
+                        'Introduction',
+                        'Availible options',
+                        'Drivers' =>
+                            array('Memcache',
+                                  'APC',
+                                  'Sqlite'
+                                ),
+
                         ),
            'Native SQL' => array(
                         'Scalar queries',