[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: ConnectionCommon.php,v 1.5 2005/10/17 19:03:51 dlawson_mi Exp $
   4   *
   5   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   6   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   7   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   8   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   9   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  10   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  11   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  12   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  13   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  14   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  15   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  16   *
  17   * This software consists of voluntary contributions made by many individuals
  18   * and is licensed under the LGPL. For more information please see
  19   * <http://creole.phpdb.org>.
  20   */
  21  
  22  /**
  23   * Class that contains some shared/default information for connections.  Classes may wish to extend this so
  24   * as not to worry about the sleep/wakeup methods, etc.
  25   * 
  26   * In reality this class is not very useful yet, so there's not much incentive for drivers to extend this.
  27   * 
  28   * @author    Hans Lellelid <hans@xmpl.org>
  29   * @version   $Revision: 1.5 $
  30   * @package   creole.common
  31   */
  32  abstract class ConnectionCommon {
  33  
  34      // Constants that define transaction isolation levels.
  35      // [We don't have any code using these yet, so there's no need
  36      // to initialize these values at this point.]
  37      // const TRANSACTION_NONE = 0;
  38      // const TRANSACTION_READ_UNCOMMITTED = 1;
  39      // const TRANSACTION_READ_COMMITTED = 2;
  40      // const TRANSACTION_REPEATABLE_READ = 3;
  41      // const TRANSACTION_SERIALIZABLE = 4;
  42      
  43         /**
  44       * The depth level of current transaction.
  45       * @var int
  46       */ 
  47      protected $transactionOpcount = 0;
  48      
  49      /**
  50       * DB connection resource id.     
  51       * @var resource
  52       */ 
  53      protected $dblink;
  54      
  55      /**
  56       * Array hash of connection properties.
  57       * @var array
  58       */
  59      protected $dsn;
  60  
  61      /**
  62       * Flags (e.g. Connection::PERSISTENT) for current connection.
  63       * @var int
  64       */
  65      protected $flags = 0;
  66          
  67      /**
  68       * This "magic" method is invoked upon serialize() and works in tandem with the __wakeup()
  69       * method to ensure that your database connection is serializable.
  70       * 
  71       * This method returns an array containing the names of any members of your class
  72       * which need to be serialized in order to allow the class to re-connect to the database
  73       * when it is unserialized.
  74       * 
  75       * <p>
  76       * Developers:
  77       * 
  78       * Note that you cannot serialize resources (connection links) and expect them to 
  79       * be valid when you unserialize.  For this reason, you must re-connect to the database in the
  80       * __wakeup() method.
  81       * 
  82       * It's up to your class implimentation to ensure that the necessary data is serialized. 
  83       * You probably at least need to serialize:
  84       * 
  85       *  (1) the DSN array used by connect() method
  86       *  (2) Any flags that were passed to the connection
  87       *  (3) Possibly the autocommit state
  88       * 
  89       * @return array The class variable names that should be serialized.
  90       * @see __wakeup()
  91       * @see DriverManager::getConnection()
  92       * @see DatabaseInfo::__sleep()
  93       */
  94      public function __sleep()
  95      {
  96          return array('dsn', 'flags');
  97      }
  98      
  99      /**
 100       * This "magic" method is invoked upon unserialize().
 101       * This method will re-connects to the database using the information that was
 102       * stored using the __sleep() method.
 103       * @see __sleep()
 104       */
 105      public function __wakeup() 
 106      {
 107          $this->connect($this->dsn, $this->flags);
 108      }
 109     
 110      /**
 111       * @see Connection::getResource()
 112       */
 113      public function getResource()
 114      {
 115          return $this->dblink;
 116      }
 117      
 118      /**
 119       * @see Connection::getDSN()
 120       */
 121      public function getDSN() {
 122          return $this->dsn;
 123      }
 124         
 125      /**
 126       * @see Connection::getFlags()
 127       */
 128      public function getFlags()
 129      {
 130          return $this->flags;
 131      }    
 132  
 133      /**
 134       * Creates a CallableStatement object for calling database stored procedures.
 135       * 
 136       * @param string $sql
 137       * @return CallableStatement
 138       */
 139      public function prepareCall($sql) 
 140      {
 141          throw new SQLException("Current driver does not support stored procedures using CallableStatement.");
 142      }    
 143      
 144      /**
 145       * Driver classes should override this if they support transactions.
 146       * 
 147       * @return boolean
 148       */
 149      public function supportsNestedTrans() 
 150      {
 151          return false;
 152      }
 153      
 154      /**
 155       * Begins a transaction (if supported).
 156       */
 157      public function begin() 
 158      {
 159          if ($this->transactionOpcount === 0 || $this->supportsNestedTrans()) {
 160              $this->beginTrans();
 161          }
 162          $this->transactionOpcount++;
 163      }
 164  
 165      /**
 166       * Commits statements in a transaction.
 167       */
 168      public function commit() 
 169      {
 170          if ($this->transactionOpcount > 0) {
 171              if ($this->transactionOpcount == 1 || $this->supportsNestedTrans()) {
 172                  $this->commitTrans();
 173              }
 174              $this->transactionOpcount--;       
 175          }
 176      }
 177      
 178      /**
 179       * Rollback changes in a transaction.
 180       */
 181      public function rollback() 
 182      {
 183          if ($this->transactionOpcount > 0) {
 184              if ($this->transactionOpcount == 1 || $this->supportsNestedTrans()) {
 185                  $this->rollbackTrans();
 186              }
 187              $this->transactionOpcount--;       
 188          }
 189      }
 190  
 191      /**
 192       * Enable/disable automatic commits.
 193       * 
 194       * Pushes SQLWarning onto $warnings stack if the autocommit value is being changed mid-transaction. This function
 195       * is overridden by driver classes so that they can perform the necessary begin/end transaction SQL.
 196       * 
 197       * If auto-commit is being set to TRUE, then the current transaction will be committed immediately.
 198       * 
 199       * @param boolean $bit New value for auto commit.
 200       * @return void
 201       */
 202      public function setAutoCommit($bit) 
 203      {
 204          if ($this->transactionOpcount > 0) {
 205              trigger_error("Changing autocommit in mid-transaction; committing " . $this->transactionOpcount . " uncommitted statements.", E_USER_WARNING);
 206          }
 207  
 208          if (!$bit) {
 209              $this->begin();
 210          }
 211          else {
 212              $this->commit();
 213          }
 214      }
 215  
 216      /**
 217       * Get auto-commit status.
 218       *
 219       * @return boolean
 220       */
 221      public function getAutoCommit() 
 222      {
 223          return ($this->transactionOpcount == 0);
 224      }
 225      
 226      /**
 227       * Begin new transaction.
 228       * Driver classes should override this method if they support transactions.
 229       */
 230      protected function beginTrans()
 231      {
 232      }
 233      
 234      /**
 235       * Commit the current transaction.
 236       * Driver classes should override this method if they support transactions.
 237       */
 238      protected function commitTrans() 
 239      {
 240      }
 241      
 242      /**
 243       * Roll back (undo) the current transaction.
 244       * Driver classes should override this method if they support transactions.
 245       */
 246      protected function rollbackTrans() 
 247      {
 248      }
 249   
 250      /**
 251       * Returns false if connection is closed.
 252       * @return boolean
 253       */
 254      public function isConnected()
 255      {
 256          return !empty($this->dblink);
 257      }
 258  }