ZF-4076

- Added persistence patch for Zend_Db
- Altered docs to reflect new feature

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@16920 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Db_Adapter.xml

@@ -1716,14 +1716,30 @@ $db->closeConnection();
         <note>
             <title>Does Zend_Db Support Persistent Connections?</title>
             <para>
-                The usage of persistent connections is not supported
-                or encouraged in <classname>Zend_Db</classname>.
-            </para>
+                Yes, persistence is supported through the addition of
+                the <code>persistent</code> flag set to true in the
+                configuration (not driver_configuration) of an adapter
+                in <classname>Zend_Db</classname>.
+            </para>
+            
+            <example id="zend.db.adapter.connecting.persistence.example">
+                <title>Using the Persitence Flag with the Oracle Adapter</title>
+                <programlisting language="php"><![CDATA[
+$db = Zend_Db::factory('Oracle', array(
+    'host'       => '127.0.0.1',
+    'username'   => 'webuser',
+    'password'   => 'xxxxxxxx',
+    'dbname'     => 'test',
+    'persistent' => true
+));
+]]></programlisting>
+            </example>
+            
             <para>
-                Using persistent connections can cause an excess of idle
-                connections on the RDBMS server, which causes more problems
-                than any performance gain you might achieve by reducing the
-                overhead of making connections.
+                Please note that using persistent connections can cause an 
+                excess of idle connections on the RDBMS server, which causes 
+                more problems than any performance gain you might achieve by 
+                reducing the overhead of making connections.
             </para>
             <para>
                 Database connections have state. That is, some objects in the
@@ -1734,6 +1750,10 @@ $db->closeConnection();
                 application could access invalid or privileged data that were
                 created in a previous PHP request.
             </para>
+            <para>
+                Currently, only Oracle, DB2, and the PDO adapters (where
+                specified by PHP) support persistence in Zend_Db.
+            </para>
         </note>
 
     </sect2>

library/Zend/Db/Adapter/Abstract.php

@@ -209,6 +209,10 @@ abstract class Zend_Db_Adapter_Abstract
         if (!isset($config['charset'])) {
             $config['charset'] = null;
         }
+        
+        if (!isset($config['persistent'])) {
+            $config['persistent'] = false;
+        }
 
         $this->_config = array_merge($this->_config, $config);
         $this->_config['options'] = $options;

library/Zend/Db/Adapter/Oracle.php

@@ -48,13 +48,14 @@ class Zend_Db_Adapter_Oracle extends Zend_Db_Adapter_Abstract
      * password => (string) Password associated with the username.
      * dbname   => Either the name of the local Oracle instance, or the
      *             name of the entry in tnsnames.ora to which you want to connect.
-     *
+     * persistent => (boolean) Set TRUE to use a persistent connection
      * @var array
      */
     protected $_config = array(
         'dbname'       => null,
         'username'     => null,
         'password'     => null,
+        'persistent'   => false
     );
 
     /**
@@ -118,7 +119,9 @@ class Zend_Db_Adapter_Oracle extends Zend_Db_Adapter_Abstract
             throw new Zend_Db_Adapter_Oracle_Exception('The OCI8 extension is required for this adapter but the extension is not loaded');
         }
 
-        $this->_connection = @oci_connect(
+        $connectionFuncName = ($this->_config['persistent'] == true) ? 'oci_pconnect' : 'oci_connect';
+        
+        $this->_connection = @$connectionFuncName(
                 $this->_config['username'],
                 $this->_config['password'],
                 $this->_config['dbname'],

library/Zend/Db/Adapter/Pdo/Abstract.php

@@ -62,11 +62,12 @@ abstract class Zend_Db_Adapter_Pdo_Abstract extends Zend_Db_Adapter_Abstract
         // baseline of DSN parts
         $dsn = $this->_config;
 
-        // don't pass the username, password, and driver_options in the DSN
+        // don't pass the username, password, charset, persistent and driver_options in the DSN
         unset($dsn['username']);
         unset($dsn['password']);
         unset($dsn['options']);
         unset($dsn['charset']);
+        unset($dsn['persistent']);
         unset($dsn['driver_options']);
 
         // use all remaining parts in the DSN
@@ -114,6 +115,11 @@ abstract class Zend_Db_Adapter_Pdo_Abstract extends Zend_Db_Adapter_Abstract
         // create PDO connection
         $q = $this->_profiler->queryStart('connect', Zend_Db_Profiler::CONNECT);
 
+        // add the persistence flag if we find it in our config array
+        if (isset($this->_config['persistent']) && ($this->_config['persistent'] == true)) {
+            $this->_config['driver_options'][PDO::ATTR_PERSISTENT] = true;
+        }
+        
         try {
             $this->_connection = new PDO(
                 $dsn,