Changeset 4962 for trunk/lib/Doctrine

Show
Ignore:
Timestamp:
09/13/08 11:28:29 (4 months ago)
Author:
romanb
Message:

minor refactorings on code and API docs

Location:
trunk/lib/Doctrine
Files:
1 added
10 modified

Legend:

Unmodified
Added
Removed

  • trunk/lib/Doctrine/DBAL/Connection.php

    r4951 r4962  
    2727 
    2828/** 
    29  * A wrapper around a Doctrine::DBAL::Connection that adds features like 
    30  * events, transaction isolation levels, configuration, emulated transaction nesting 
    31  * and more. 
     29 * A wrapper around a Doctrine::DBAL::Driver::Connection that adds features like 
     30 * events, transaction isolation levels, configuration, emulated transaction nesting, 
     31 * lazy connecting and more. 
    3232 * 
    3333 * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL 
    … …  
    5454 * Doctrine::DBAL could ship with a simple standard broker that uses a primitive 
    5555 * round-robin approach to distribution. User can provide its own brokers. 
    56  * @todo Rename to ConnectionWrapper 
    5756 */ 
    5857class Doctrine_DBAL_Connection 
    5958{ 
     59    /** 
     60     * Constant for transaction isolation level READ UNCOMMITTED. 
     61     */ 
    6062    const TRANSACTION_READ_UNCOMMITTED = 1; 
     63    /** 
     64     * Constant for transaction isolation level READ COMMITTED. 
     65     */ 
    6166    const TRANSACTION_READ_COMMITTED = 2; 
     67    /** 
     68     * Constant for transaction isolation level REPEATABLE READ. 
     69     */ 
    6270    const TRANSACTION_REPEATABLE_READ = 3; 
     71    /** 
     72     * Constant for transaction isolation level SERIALIZABLE. 
     73     */ 
    6374    const TRANSACTION_SERIALIZABLE = 4; 
    6475     
    … …  
    8596     
    8697    /** 
    87      * The name of this connection driver. 
    88      * 
    89      * @var string $driverName                   
    90      */ 
    91     protected $_driverName; 
    92      
    93     /** 
    9498     * Whether or not a connection has been established. 
    9599     * 
    … …  
    97101     */ 
    98102    protected $_isConnected = false; 
    99      
    100     /** 
    101      * Boolean flag that indicates whether identifiers should get quoted. 
    102      * 
    103      * @var boolean 
    104      */ 
    105     protected $_quoteIdentifiers; 
    106      
    107     /** 
    108      * @var array 
    109      */ 
    110     protected $_serverInfo = array(); 
    111103     
    112104    /** 
    … …  
    132124     
    133125    /** 
    134      * List of all available drivers. 
    135      *  
    136      * @var array $availableDrivers 
    137      * @todo Move elsewhere.        
    138      */ 
    139     private static $_availableDrivers = array( 
    140             'Mysql', 'Pgsql', 'Oracle', 'Informix', 'Mssql', 'Sqlite', 'Firebird' 
    141             ); 
    142      
    143     /** 
    144126     * The query count. Represents the number of executed database queries by the connection. 
    145127     * 
    … …  
    155137     */ 
    156138    protected $_platform; 
    157  
    158     /** 
    159      * The transaction object. 
    160      * 
    161      * @var Doctrine::DBAL::Transaction 
    162      */ 
    163     protected $_transaction; 
    164139     
    165140    /** 
    … …  
    169144     */ 
    170145    protected $_schemaManager; 
     146     
     147    /** 
     148     * The used DBAL driver. 
     149     * 
     150     * @var Doctrine::DBAL::Driver 
     151     */ 
     152    protected $_driver; 
    171153     
    172154    /** 
    … …  
    230212     
    231213    /** 
    232      * Returns an array of available PDO drivers 
    233      * @todo Move elsewhere. 
    234      */ 
    235     public static function getAvailableDrivers() 
    236     { 
    237         return PDO::getAvailableDrivers(); 
    238     } 
    239  
    240     /** 
    241      * Gets the name of the instance driver 
    242      * 
    243      * @return void 
    244      */ 
    245     public function getDriverName() 
    246     { 
    247         return $this->_driverName; 
    248     } 
    249      
    250     /** 
    251      * Gets the PDO handle used by the connection. 
    252      * 
    253      * @return PDO 
    254      */ 
    255     public function getPdo() 
    256     { 
    257         $this->connect(); 
    258         return $this->_conn; 
    259     } 
    260      
    261     /** 
    262214     * Establishes the connection with the database. 
    263215     * 
    … …  
    268220        if ($this->_isConnected) { 
    269221            return false; 
    270         } 
    271  
    272         // TODO: the extension_loaded check can happen earlier, maybe in the factory 
    273         if ( ! extension_loaded('pdo')) { 
    274             throw new Doctrine_Connection_Exception("Couldn't locate driver named " . $e[0]); 
    275222        } 
    276223         
    … …  
    281228        $password = isset($this->_params['password']) ? 
    282229                $this->_params['password'] : null; 
    283         $this->_conn = new PDO( 
    284                 $this->_constructPdoDsn(), 
     230         
     231        $this->_conn = $this->_driver->connect( 
     232                $this->_params, 
    285233                $user, 
    286234                $password, 
    287235                $driverOptions 
    288236                ); 
    289         $this->_conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); 
    290         $this->_conn->setAttribute(PDO::ATTR_CASE, PDO::CASE_LOWER); 
    291237 
    292238        $this->_isConnected = true; 
    … …  
    296242     
    297243    /** 
    298      * Establishes the connection with the database. 
     244     * Whether an actual connection to the database is established. 
    299245     * 
    300246     * @return boolean 
    301247     */ 
    302     public function connect2() 
    303     { 
    304         if ($this->_isConnected) { 
    305             return false; 
    306         } 
    307          
    308         $driverOptions = isset($this->_params['driverOptions']) ? 
    309                 $this->_params['driverOptions'] : array(); 
    310         $user = isset($this->_params['user']) ? 
    311                 $this->_params['user'] : null; 
    312         $password = isset($this->_params['password']) ? 
    313                 $this->_params['password'] : null; 
    314                  
    315         $this->_conn = $this->_driver->connect($this->_params, $user, $password, $driverOptions); 
    316          
    317         $this->_conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); 
    318         $this->_conn->setAttribute(PDO::ATTR_CASE, PDO::CASE_LOWER); 
    319  
    320         $this->_isConnected = true; 
    321  
    322         return true; 
    323     } 
    324      
    325     /** 
    326      * Constructs the PDO DSN for use in the PDO constructor. 
    327      * Concrete connection implementations override this implementation to 
    328      * create the proper DSN. 
    329      *  
    330      * @return string 
    331      * @todo make abstract, implement in subclasses. 
    332      * @todo throw different exception? 
    333      */ 
    334     protected function _constructPdoDsn() 
    335     { 
    336         throw Doctrine_Exception::notImplemented('_constructPdoDsn', get_class($this)); 
     248    public function isConnected() 
     249    { 
     250        return $this->_isConnected; 
    337251    } 
    338252 
    … …  
    464378     *   + sqlite 
    465379     * 
    466      * InterBase doesn't seem to be able to use delimited identifiers 
    467      * via PHP 4.  They work fine under PHP 5. 
    468      * 
    469380     * @param string $str           identifier name to be quoted 
    470381     * @param bool $checkOption     check the 'quote_identifier' option 
    471382     * 
    472383     * @return string               quoted identifier string 
    473      * @todo Moved to DatabasePlatform 
    474      * @deprecated 
    475384     */ 
    476385    public function quoteIdentifier($str) 
    … …  
    480389 
    481390    /** 
    482      * Quotes given input parameter. 
     391     * Quotes a given input parameter. 
    483392     * 
    484393     * @param mixed $input  Parameter to be quoted. 
    … …  
    578487     
    579488    /** 
    580      * prepare 
     489     * Prepares an SQL statement. 
    581490     * 
    582491     * @param string $statement 
     492     * @return Doctrine::DBAL::Statement 
    583493     */ 
    584494    public function prepare($statement) 
    … …  
    676586     * 
    677587     * @return integer 
    678      * @todo Better name: getQueryCount() 
    679588     */ 
    680589    public function getQueryCount() 
    … …  
    702611    public function setTransactionIsolation($level) 
    703612    { 
    704         $sql = ""; 
    705         switch ($level) { 
    706             case Doctrine_DBAL_Connection::TRANSACTION_READ_UNCOMMITTED: 
    707                 $sql = $this->_platform->getSetTransactionIsolationReadUncommittedSql(); 
    708                 break; 
    709             case Doctrine_DBAL_Connection::TRANSACTION_READ_COMMITTED: 
    710                 $sql = $this->_platform->getSetTransactionIsolationReadCommittedSql(); 
    711                 break; 
    712             case Doctrine_DBAL_Connection::TRANSACTION_REPEATABLE_READ: 
    713                 $sql = $this->_platform->getSetTransactionIsolationRepeatableReadSql(); 
    714                 break; 
    715             case Doctrine_DBAL_Connection::TRANSACTION_SERIALIZABLE: 
    716                 $sql = $this->_platform->getSetTransactionIsolationSerializableSql(); 
    717                 break; 
    718             default: 
    719                 throw new Doctrine_Common_Exceptions_DoctrineException('isolation level is not supported: ' . $isolation); 
    720         } 
    721613        $this->_transactionIsolationLevel = $level; 
    722          
    723         return $this->exec($sql); 
     614        return $this->exec($this->_platform->getSetTransactionIsolationSql($level)); 
    724615    } 
    725616     
    … …  
    735626 
    736627    /** 
    737      * Returns the current total transaction nesting level. 
     628     * Returns the current transaction nesting level. 
    738629     * 
    739630     * @return integer  The nesting level. A value of 0 means theres no active transaction. 
    … …  
    786677     * if trying to set a savepoint and there is no active transaction 
    787678     * a new transaction is being started. 
    788      * 
    789      * @param string $savepoint                 name of a savepoint to set 
    790      * @throws Doctrine_Transaction_Exception   if the transaction fails at database level 
    791      * @return integer                          current transaction nesting level 
     679     *  
     680     * @return boolean 
    792681     */ 
    793682    public function beginTransaction() 
    … …  
    805694     * auto-committing is disabled, otherwise it will fail. 
    806695     * 
    807      * @param string $savepoint                 name of a savepoint to release 
    808      * @throws Doctrine_Transaction_Exception   if the transaction fails at PDO level 
    809      * @throws Doctrine_Validator_Exception     if the transaction fails due to record validations 
    810      * @return boolean                          false if commit couldn't be performed, true otherwise 
     696     * @return boolean FALSE if commit couldn't be performed, TRUE otherwise 
    811697     */ 
    812698    public function commit() 
    … …  
    973859    { 
    974860        if ( ! $this->_schemaManager) { 
    975             $this->_schemaManager = $this->_driver->getSchemaManager(); 
     861            $this->_schemaManager = $this->_driver->getSchemaManager($this); 
    976862        } 
    977863        return $this->_schemaManager; 

  • trunk/lib/Doctrine/DBAL/Driver/PDOConnection.php

    r4951 r4962  
    11<?php 
    22 
     3/** 
     4 * PDO implementation of the driver Connection interface. 
     5 * Used by all PDO-based drivers. 
     6 * 
     7 * @since 2.0 
     8 */ 
    39class Doctrine_DBAL_Driver_PDOConnection extends PDO implements Doctrine_DBAL_Driver_Connection 
    410{ 
    … …  
    713        parent::__construct($dsn, $user, $password, $options); 
    814        $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('Doctrine_DBAL_Driver_PDOStatement', array())); 
     15        $this->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); 
     16        $this->setAttribute(PDO::ATTR_CASE, PDO::CASE_LOWER); 
    917    } 
    1018} 

  • trunk/lib/Doctrine/DBAL/Driver/PDOSqlite/Driver.php

    r4951 r4962  
    55#use Doctrine::DBAL::Driver; 
    66 
     7/** 
     8 * The PDO Sqlite driver. 
     9 * 
     10 * @since 2.0 
     11 */ 
    712class Doctrine_DBAL_Driver_PDOSqlite_Driver implements Doctrine_DBAL_Driver 
    813{ 
    9      
     14    /** 
     15     * Tries to establish a database connection to SQLite. 
     16     * 
     17     * @param array $params 
     18     * @param unknown_type $username 
     19     * @param unknown_type $password 
     20     * @param array $driverOptions 
     21     * @return unknown 
     22     */ 
    1023    public function connect(array $params, $username = null, $password = null, array $driverOptions = array()) 
    1124    { 
    … …  
    3548    } 
    3649     
     50    /** 
     51     * Gets the database platform that is relevant for this driver. 
     52     */ 
    3753    public function getDatabasePlatform() 
    3854    { 
    … …  
    4056    } 
    4157     
     58    /** 
     59     * Gets the schema manager that is relevant for this driver. 
     60     * 
     61     * @param Doctrine::DBAL::Connection $conn 
     62     * @return Doctrine::DBAL::Schema::AbstractSchemaManager 
     63     */ 
    4264    public function getSchemaManager(Doctrine_DBAL_Connection $conn) 
    4365    { 

  • trunk/lib/Doctrine/DBAL/DriverManager.php

    r4951 r4962  
    2323 
    2424/** 
    25  * Factory for creating dbms-specific Connection instances. 
     25 * Factory for creating Doctrine::DBAL::Connection instances. 
    2626 * 
    2727 * @author Roman Borschel <roman@code-factory.org> 
    2828 * @since 2.0 
    2929 */ 
    30 class Doctrine_DBAL_DriverManager 
     30final class Doctrine_DBAL_DriverManager 
    3131{ 
    3232    /** 
    … …  
    3535     * @var array 
    3636     */ 
    37      private $_drivers = array( 
     37     private static $_driverMap = array( 
    3838            'pdo_mysql'  => 'Doctrine_DBAL_Driver_PDOMySql_Driver', 
    3939            'pdo_sqlite' => 'Doctrine_DBAL_Driver_PDOSqlite_Driver', 
    … …  
    4545            ); 
    4646     
    47     public function __construct() 
    48     { 
    49          
    50     } 
    51      
     47    private function __construct() {} 
     48             
    5249    /** 
    53      * Creates a connection object with the specified parameters. 
     50     * Creates a connection object based on the specified parameters. 
     51     * This method returns a Doctrine::DBAL::Connection which wraps the underlying 
     52     * driver connection. 
    5453     * 
    55      * @param array $params 
    56      * @return Connection 
     54     * $params must contain at least one of the following. 
     55     *  
     56     * Either 'driver' with one of the following values: 
     57     *     pdo_mysql 
     58     *     pdo_sqlite 
     59     *     pdo_pgsql 
     60     *     pdo_oracle 
     61     *     pdo_mssql 
     62     *     pdo_firebird 
     63     *     pdo_informix 
     64     *  
     65     * OR 'driverClass' that contains the full class name (with namespace) of the 
     66     * driver class to instantiate. 
     67     *  
     68     * Other (optional) parameters: 
     69     *  
     70     * <b>user (string)</b>: 
     71     * The username to use when connecting.  
     72     *  
     73     * <b>password (string)</b>: 
     74     * The password to use when connecting. 
     75     *  
     76     * <b>driverOptions (array)</b>: 
     77     * Any additional driver-specific options for the driver. These are just passed 
     78     * through to the driver. 
     79     *  
     80     * <b>pdo</b>: 
     81     * You can pass an existing PDO instance through this parameter. The PDO 
     82     * instance will be wrapped in a Doctrine::DBAL::Connection. 
     83     *  
     84     * <b>wrapperClass</b>: 
     85     * You may specify a custom wrapper class through the 'wrapperClass' 
     86     * parameter but this class MUST inherit from Doctrine::DBAL::Connection. 
     87     *  
     88     * @param array $params The parameters. 
     89     * @param Doctrine::Common::Configuration The configuration to use. 
     90     * @param Doctrine::Common::EventManager The event manager to use. 
     91     * @return Doctrine::DBAL::Connection 
    5792     */ 
    58     public function getConnection(array $params, Doctrine_Common_Configuration $config = null, 
     93    public static function getConnection(array $params, Doctrine_Common_Configuration $config = null, 
    5994            Doctrine_Common_EventManager $eventManager = null) 
    6095    { 
    … …  
    73108            $params['driver'] = $params['pdo']->getAttribute(PDO::ATTR_DRIVER_NAME); 
    74109        } else { 
    75             $this->_checkParams($params); 
     110            self::_checkParams($params); 
    76111        } 
    77112        if (isset($params['driverClass'])) { 
    78113            $className = $params['driverClass']; 
    79114        } else { 
    80             $className = $this->_drivers[$params['driver']]; 
     115            $className = self::$_driverMap[$params['driver']]; 
    81116        } 
    82117         
    … …  
    84119         
    85120        $wrapperClass = 'Doctrine_DBAL_Connection'; 
    86         if (isset($params['wrapperClass'])) { 
     121        if (isset($params['wrapperClass']) && is_subclass_of($params['wrapperClass'], $wrapperClass)) { 
    87122            $wrapperClass = $params['wrapperClass']; 
    88123        } 
    … …  
    96131     * @param array $params 
    97132     */ 
    98     private function _checkParams(array $params) 
     133    private static function _checkParams(array $params) 
    99134    {         
    100135        // check existance of mandatory parameters 
    … …  
    108143         
    109144        // driver 
    110         if ( isset($params['driver']) && ! isset($this->_drivers[$params['driver']])) { 
     145        if ( isset($params['driver']) && ! isset(self::$_driverMap[$params['driver']])) { 
    111146            throw Doctrine_DBAL_Exceptions_DBALException::unknownDriver($params['driver']); 
    112147        } 

  • trunk/lib/Doctrine/ORM/EntityManager.php

    r4952 r4962  
    2424#use Doctrine::Common::Configuration; 
    2525#use Doctrine::Common::EventManager; 
    26 #use Doctrine::Common::NullObject; 
    27 #use Doctrine::DBAL::Connections::Connection; 
     26#use Doctrine::DBAL::Connection; 
    2827#use Doctrine::ORM::Exceptions::EntityManagerException; 
    2928#use Doctrine::ORM::Internal::UnitOfWork; 
    … …  
    356355    } 
    357356     
     357    /** 
     358     * Checks whether the given value is a valid flush mode. 
     359     * 
     360     * @param string $value 
     361     * @return boolean 
     362     */ 
    358363    private function _isFlushMode($value) 
    359364    { 
    … …  
    396401    { 
    397402        $this->_closed = true; 
    398     } 
    399      
    400     /** 
    401      * Gets the result cache driver used by the EntityManager. 
    402      * 
    403      * @return Doctrine::ORM::Cache::CacheDriver The cache driver. 
    404      */ 
    405     public function getResultCacheDriver() 
    406     { 
    407         if ( ! $this->getAttribute(Doctrine::ATTR_RESULT_CACHE)) { 
    408             throw new Doctrine_Exception('Result Cache driver not initialized.'); 
    409         } 
    410          
    411         return $this->getAttribute(Doctrine::ATTR_RESULT_CACHE); 
    412     } 
    413  
    414     /** 
    415      * getQueryCacheDriver 
    416      * 
    417      * @return Doctrine_Cache_Interface 
    418      */ 
    419     public function getQueryCacheDriver() 
    420     { 
    421         if ( ! $this->getAttribute(Doctrine::ATTR_QUERY_CACHE)) { 
    422             throw new Doctrine_Exception('Query Cache driver not initialized.'); 
    423         } 
    424          
    425         return $this->getAttribute(Doctrine::ATTR_QUERY_CACHE); 
    426403    } 
    427404     
    … …  
    650627    } 
    651628     
     629    /** 
     630     * Throws an exception if the EntityManager is closed or currently not active. 
     631     */ 
    652632    private function _errorIfNotActiveOrClosed() 
    653633    { 
    … …  
    703683    { 
    704684        if (is_array($conn)) { 
    705             $connFactory = new Doctrine_DBAL_DriverManager(); 
    706             $conn = $connFactory->getConnection($conn, $config, $eventManager); 
    707         } else if ( ! $conn instanceof Doctrine_Connection) { 
     685            $conn = Doctrine_DBAL_DriverManager::getConnection($conn, $config, $eventManager); 
     686        } else if ( ! $conn instanceof Doctrine_DBAL_Connection) { 
    708687            throw new Doctrine_Exception("Invalid parameter '$conn'."); 
    709688        } 
    … …  
    723702     
    724703    /** 
    725      * Gets the currently active EntityManager. 
     704     * Static lookup to get the currently active EntityManager. 
     705     * This is used in the Entity constructor as well as unserialize() to connect 
     706     * the Entity with an EntityManager. 
    726707     * 
    727708     * @return Doctrine::ORM::EntityManager 

  • trunk/lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

    r4926 r4962  
    2727 * 
    2828 * @since 2.0 
    29  * @todo Rename to: CommitOrderCalculator 
    3029 * @author Roman Borschel <roman@code-factory.org>  
    3130 */ 
    … …  
    8988    } 
    9089     
     90    /** 
     91     * Adds a node to consider when ordering. 
     92     * 
     93     * @param mixed $key Somme arbitrary key for the node (must be unique!). 
     94     * @param unknown_type $node 
     95     */ 
    9196    public function addNode($key, $node) 
    9297    { 
    … …  
    9499    } 
    95100     
     101    /** 
     102     * Enter description here... 
     103     * 
     104     * @param unknown_type $key 
     105     * @param unknown_type $item 
     106     */ 
    96107    public function addNodeWithItem($key, $item) 
    97108    { 
    … …  
    99110    } 
    100111     
     112    /** 
     113     * Enter description here... 
     114     * 
     115     * @param unknown_type $key 
     116     * @return unknown 
     117     */ 
    101118    public function getNodeForKey($key)