[2.0] More docblocks. Renamed methods Type::addCustomType to Type::addType and...

[2.0] More docblocks. Renamed methods Type::addCustomType to Type::addType and Connection::exec to Connection::executeUpdate. Added Type::hasType.

lib/Doctrine/DBAL/Configuration.php

@@ -26,8 +26,14 @@ use Doctrine\DBAL\Types\Type;
 /**
  * Configuration container for the Doctrine DBAL.
  *
- * @author Roman Borschel <roman@code-factory.org>
- * @since 2.0
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ *
  * @internal When adding a new configuration option just write a getter/setter
  *           pair and add the option to the _attributes array with a proper default value.
  */
@@ -43,6 +49,7 @@ class Configuration
     
     /**
      * Creates a new configuration that can be used for Doctrine.
+     *
      */
     public function __construct()
     {
@@ -71,13 +78,28 @@ class Configuration
         return $this->_attributes['sqlLogger'];
     }
 
-    public function setCustomTypes(array $types)
+    /**
+     * Defines new custom types to be supported by Doctrine
+     *
+     * @param array $types Key-value map of types to include
+     * @param boolean $override Optional flag to support only inclusion or also override
+     * @throws DoctrineException
+     */
+    public function setCustomTypes(array $types, $override = false)
     {
         foreach ($types as $name => $typeClassName) {
-            Type::addCustomType($name, $typeClassName);
+            $method = (Type::hasType($name) ? 'override' : 'add') . 'Type';
+            
+            Type::$method($name, $typeClassName);
         }
     }
 
+    /**
+     * Overrides existent types in Doctrine
+     *
+     * @param array $types Key-value map of types to override
+     * @throws DoctrineException
+     */
     public function setTypeOverrides(array $overrides)
     {
         foreach ($override as $name => $typeClassName) {

lib/Doctrine/DBAL/Connection.php

 <?php
 /*
- *  $Id: Connection.php 4933 2008-09-12 10:58:33Z romanb $
+ *  $Id$
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
@@ -29,12 +29,15 @@ use Doctrine\Common\DoctrineException;
  * events, transaction isolation levels, configuration, emulated transaction nesting,
  * lazy connecting and more.
  *
- * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @since       1.0
- * @version     $Revision: 4933 $
- * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
- * @author      Lukas Smith <smith@pooteeweet.org> (MDB2 library)
- * @author      Roman Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ * @author  Konsta Vesterinen <kvesteri@cc.hut.fi>
+ * @author  Lukas Smith <smith@pooteeweet.org> (MDB2 library)
  */
 class Connection
 {
@@ -42,14 +45,17 @@ class Connection
      * Constant for transaction isolation level READ UNCOMMITTED.
      */
     const TRANSACTION_READ_UNCOMMITTED = 1;
+    
     /**
      * Constant for transaction isolation level READ COMMITTED.
      */
     const TRANSACTION_READ_COMMITTED = 2;
+    
     /**
      * Constant for transaction isolation level REPEATABLE READ.
      */
     const TRANSACTION_REPEATABLE_READ = 3;
+    
     /**
      * Constant for transaction isolation level SERIALIZABLE.
      */
@@ -165,6 +171,7 @@ class Connection
         if ( ! $config) {
             $config = new Configuration();
         }
+        
         if ( ! $eventManager) {
             $eventManager = new EventManager();
         }
@@ -291,7 +298,6 @@ class Connection
                 $this->_params['password'] : null;
 
         $this->_conn = $this->_driver->connect($this->_params, $user, $password, $driverOptions);
-
         $this->_isConnected = true;
 
         return true;
@@ -366,16 +372,17 @@ class Connection
     public function delete($tableName, array $identifier)
     {
         $this->connect();
+        
         $criteria = array();
+        
         foreach (array_keys($identifier) as $id) {
             $criteria[] = $this->quoteIdentifier($id) . ' = ?';
         }
 
-        $query = 'DELETE FROM '
-                . $this->quoteIdentifier($tableName)
-                . ' WHERE ' . implode(' AND ', $criteria);
+        $query = 'DELETE FROM ' . $this->quoteIdentifier($tableName)
+               . ' WHERE ' . implode(' AND ', $criteria);
 
-        return $this->exec($query, array_values($identifier));
+        return $this->executeUpdate($query, array_values($identifier));
     }
 
     /**
@@ -386,6 +393,7 @@ class Connection
     public function close()
     {
         unset($this->_conn);
+        
         $this->_isConnected = false;
     }
 
@@ -397,7 +405,8 @@ class Connection
     public function setTransactionIsolation($level)
     {
         $this->_transactionIsolationLevel = $level;
-        return $this->exec($this->_platform->getSetTransactionIsolationSql($level));
+        
+        return $this->executeUpdate($this->_platform->getSetTransactionIsolationSql($level));
     }
 
     /**
@@ -422,11 +431,13 @@ class Connection
     public function update($tableName, array $data, array $identifier)
     {
         $this->connect();
+        
         if (empty($data)) {
             return false;
         }
 
         $set = array();
+        
         foreach ($data as $columnName => $value) {
             $set[] = $this->quoteIdentifier($columnName) . ' = ?';
         }
@@ -434,11 +445,11 @@ class Connection
         $params = array_merge(array_values($data), array_values($identifier));
 
         $sql  = 'UPDATE ' . $this->quoteIdentifier($tableName)
-                . ' SET ' . implode(', ', $set)
-                . ' WHERE ' . implode(' = ? AND ', array_keys($identifier))
-                . ' = ?';
+              . ' SET ' . implode(', ', $set)
+              . ' WHERE ' . implode(' = ? AND ', array_keys($identifier))
+              . ' = ?';
 
-        return $this->exec($sql, $params);
+        return $this->executeUpdate($sql, $params);
     }
 
     /**
@@ -452,6 +463,7 @@ class Connection
     public function insert($tableName, array $data)
     {
         $this->connect();
+        
         if (empty($data)) {
             return false;
         }
@@ -459,17 +471,17 @@ class Connection
         // column names are specified as array keys
         $cols = array();
         $a = array();
+        
         foreach ($data as $columnName => $value) {
             $cols[] = $this->quoteIdentifier($columnName);
             $a[] = '?';
         }
 
         $query = 'INSERT INTO ' . $this->quoteIdentifier($tableName)
-        . ' (' . implode(', ', $cols) . ') '
-        . 'VALUES (';
-        $query .= implode(', ', $a) . ')';
+               . ' (' . implode(', ', $cols) . ')'
+               . ' VALUES (' . implode(', ', $a) . ')';
 
-        return $this->exec($query, array_values($data));
+        return $this->executeUpdate($query, array_values($data));
     }
 
     /**
@@ -479,7 +491,7 @@ class Connection
      */
     public function setCharset($charset)
     {
-        $this->exec($this->_platform->getSetCharsetSql($charset));
+        $this->executeUpdate($this->_platform->getSetCharsetSql($charset));
     }
 
     /**
@@ -493,8 +505,6 @@ class Connection
      * problems than they solve.
      *
      * @param string $str           identifier name to be quoted
-     * @param bool $checkOption     check the 'quote_identifier' option
-     *
      * @return string               quoted identifier string
      */
     public function quoteIdentifier($str)
@@ -548,6 +558,7 @@ class Connection
     public function prepare($statement)
     {
         $this->connect();
+        
         return $this->_conn->prepare($statement);
     }
 
@@ -565,6 +576,7 @@ class Connection
         if ($limit > 0 || $offset > 0) {
             $query = $this->_platform->modifyLimitQuery($query, $limit, $offset);
         }
+        
         return $this->execute($query);
     }
 
@@ -573,7 +585,6 @@ class Connection
      *
      * @param string $query     sql query
      * @param array $params     query parameters
-     *
      * @return PDOStatement
      */
     public function execute($query, array $params = array())
@@ -590,6 +601,7 @@ class Connection
         } else {
             $stmt = $this->_conn->query($query);
         }
+        
         $this->_queryCount++;
         
         return $stmt;
@@ -601,9 +613,8 @@ class Connection
      * @param string $query     sql query
      * @param array $params     query parameters
      * @return integer
-     * @todo Rename to executeUpdate().
      */
-    public function exec($query, array $params = array())
+    public function executeUpdate($query, array $params = array())
     {
         $this->connect();
 
@@ -618,6 +629,7 @@ class Connection
         } else {
             $result = $this->_conn->exec($query);
         }
+        
         $this->_queryCount++;
         
         return $result;
@@ -651,6 +663,7 @@ class Connection
     public function errorCode()
     {
         $this->connect();
+        
         return $this->_conn->errorCode();
     }
 
@@ -662,6 +675,7 @@ class Connection
     public function errorInfo()
     {
         $this->connect();
+        
         return $this->_conn->errorInfo();
     }
 
@@ -678,6 +692,7 @@ class Connection
     public function lastInsertId($seqName = null)
     {
         $this->connect();
+        
         return $this->_conn->lastInsertId($seqName);
     }
 
@@ -692,10 +707,13 @@ class Connection
     public function beginTransaction()
     {
         $this->connect();
+        
         if ($this->_transactionNestingLevel == 0) {
             $this->_conn->beginTransaction();
         }
+        
         ++$this->_transactionNestingLevel;
+        
         return true;
     }
 
@@ -717,6 +735,7 @@ class Connection
         if ($this->_transactionNestingLevel == 1) {
             $this->_conn->commit();
         }
+        
         --$this->_transactionNestingLevel;
 
         return true;
@@ -761,6 +780,7 @@ class Connection
     public function getWrappedConnection()
     {
         $this->connect();
+        
         return $this->_conn;
     }
 
@@ -775,6 +795,7 @@ class Connection
         if ( ! $this->_schemaManager) {
             $this->_schemaManager = $this->_driver->getSchemaManager($this);
         }
+        
         return $this->_schemaManager;
     }
 }

lib/Doctrine/DBAL/Schema/AbstractSchemaManager.php

@@ -964,7 +964,7 @@ abstract class AbstractSchemaManager
     protected function _execSql($sql)
     {
         foreach ((array) $sql as $query) {
-            $this->_conn->exec($query);
+            $this->_conn->executeUpdate($query);
         }
     }
 }
\ No newline at end of file

lib/Doctrine/DBAL/Types/Type.php

@@ -114,6 +114,7 @@ abstract class Type
      * Factory method to create type instances.
      * Type instances are implemented as flyweights.
      *
+     * @static
      * @param string $name The name of the type (as returned by getName()).
      * @return Doctrine\DBAL\Types\Type
      */
@@ -123,37 +124,57 @@ abstract class Type
             if ( ! isset(self::$_typesMap[$name])) {
                 throw DoctrineException::updateMe("Unknown type: $name");
             }
+            
             self::$_typeObjects[$name] = new self::$_typesMap[$name]();
         }
+        
         return self::$_typeObjects[$name];
     }
     
     /**
      * Adds a custom type to the type map.
      *
+     * @static
      * @param string $name Name of the type. This should correspond to what
      *                           getName() returns.
      * @param string $className The class name of the custom type.
+     * @throws DoctrineException
      */
-    public static function addCustomType($name, $className)
+    public static function addType($name, $className)
     {
         if (isset(self::$_typesMap[$name])) {
             throw DoctrineException::typeExists($name);
         }
+        
         self::$_typesMap[$name] = $className;
     }
     
+    /**
+     * Checks if exists support for a type.
+     *
+     * @static
+     * @param string $name Name of the type
+     * @return boolean TRUE if type is supported; FALSE otherwise
+     */
+    public static function hasType($name)
+    {
+        return isset(self::$_typesMap[$name]);
+    }
+    
     /**
      * Overrides an already defined type to use a different implementation.
      *
+     * @static
      * @param string $name
      * @param string $className
+     * @throws DoctrineException
      */
     public static function overrideType($name, $className)
     {
         if ( ! isset(self::$_typesMap[$name])) {
             throw DoctrineException::typeNotFound($name);
         }
+        
         self::$_typesMap[$name] = $className;
     }
 }
\ No newline at end of file

lib/Doctrine/ORM/Persisters/AbstractCollectionPersister.php

@@ -67,7 +67,7 @@ abstract class AbstractCollectionPersister
             return; // ignore inverse side
         }
         $sql = $this->_getDeleteSql($coll);
-        $this->_conn->exec($sql, $this->_getDeleteSqlParameters($coll));
+        $this->_conn->executeUpdate($sql, $this->_getDeleteSqlParameters($coll));
     }
 
     /**
@@ -106,7 +106,7 @@ abstract class AbstractCollectionPersister
         $deleteDiff = $coll->getDeleteDiff();
         $sql = $this->_getDeleteRowSql($coll);
         foreach ($deleteDiff as $element) {
-            $this->_conn->exec($sql, $this->_getDeleteRowSqlParameters($coll, $element));
+            $this->_conn->executeUpdate($sql, $this->_getDeleteRowSqlParameters($coll, $element));
         }
     }
     
@@ -118,7 +118,7 @@ abstract class AbstractCollectionPersister
         $insertDiff = $coll->getInsertDiff();
         $sql = $this->_getInsertRowSql($coll);
         foreach ($insertDiff as $element) {
-            $this->_conn->exec($sql, $this->_getInsertRowSqlParameters($coll, $element));
+            $this->_conn->executeUpdate($sql, $this->_getInsertRowSqlParameters($coll, $element));
         }
     }
 

lib/Doctrine/ORM/Persisters/StandardEntityPersister.php

@@ -238,7 +238,7 @@ class StandardEntityPersister
                 . ' WHERE ' . implode(' = ? AND ', array_keys($where))
                 . ' = ?';
 
-        $result = $this->_conn->exec($sql, $params);
+        $result = $this->_conn->executeUpdate($sql, $params);
 
         if ($isVersioned && ! $result) {
             throw \Doctrine\ORM\OptimisticLockException::optimisticLockFailed();

lib/Doctrine/ORM/Query/Exec/MultiTableDeleteExecutor.php

@@ -112,18 +112,18 @@ class MultiTableDeleteExecutor extends AbstractSqlExecutor
         $numDeleted = 0;
         
         // Create temporary id table
-        $conn->exec($this->_createTempTableSql);
+        $conn->executeUpdate($this->_createTempTableSql);
         
         // Insert identifiers
-        $numDeleted = $conn->exec($this->_insertSql, $params);
+        $numDeleted = $conn->executeUpdate($this->_insertSql, $params);
 
         // Execute DELETE statements
         foreach ($this->_sqlStatements as $sql) {
-            $conn->exec($sql);
+            $conn->executeUpdate($sql);
         }
         
         // Drop temporary table
-        $conn->exec($this->_dropTempTableSql);
+        $conn->executeUpdate($this->_dropTempTableSql);
         
         return $numDeleted;
     }

lib/Doctrine/ORM/Query/Exec/MultiTableUpdateExecutor.php

@@ -144,18 +144,18 @@ class MultiTableUpdateExecutor extends AbstractSqlExecutor
         $numUpdated = 0;
 
         // Create temporary id table
-        $conn->exec($this->_createTempTableSql);
+        $conn->executeUpdate($this->_createTempTableSql);
 
         // Insert identifiers. Parameters from the update clause are cut off.
-        $numUpdated = $conn->exec($this->_insertSql, array_slice($params, $this->_numParametersInUpdateClause));
+        $numUpdated = $conn->executeUpdate($this->_insertSql, array_slice($params, $this->_numParametersInUpdateClause));
 
         // Execute UPDATE statements
         for ($i=0, $count=count($this->_sqlStatements); $i<$count; ++$i) {
-            $conn->exec($this->_sqlStatements[$i], $this->_sqlParameters[$i]);
+            $conn->executeUpdate($this->_sqlStatements[$i], $this->_sqlParameters[$i]);
         }
 
         // Drop temporary table
-        $conn->exec($this->_dropTempTableSql);
+        $conn->executeUpdate($this->_dropTempTableSql);
 
         return $numUpdated;
     }

lib/Doctrine/ORM/Query/Exec/SingleTableDeleteUpdateExecutor.php

@@ -47,6 +47,6 @@ class SingleTableDeleteUpdateExecutor extends AbstractSqlExecutor
     
     public function execute(\Doctrine\DBAL\Connection $conn, array $params)
     {
-        return $conn->exec($this->_sqlStatements, $params);
+        return $conn->executeUpdate($this->_sqlStatements, $params);
     }
 }
\ No newline at end of file

tests/Doctrine/Tests/OrmFunctionalTestCase.php

@@ -69,32 +69,32 @@ class OrmFunctionalTestCase extends OrmTestCase
     {
         $conn = $this->sharedFixture['conn'];
         if (isset($this->_usedModelSets['cms'])) {
-            $conn->exec('DELETE FROM cms_users_groups');
-            $conn->exec('DELETE FROM cms_groups');
-            $conn->exec('DELETE FROM cms_addresses');
-            $conn->exec('DELETE FROM cms_phonenumbers');
-            $conn->exec('DELETE FROM cms_articles');
-            $conn->exec('DELETE FROM cms_users');
+            $conn->executeUpdate('DELETE FROM cms_users_groups');
+            $conn->executeUpdate('DELETE FROM cms_groups');
+            $conn->executeUpdate('DELETE FROM cms_addresses');
+            $conn->executeUpdate('DELETE FROM cms_phonenumbers');
+            $conn->executeUpdate('DELETE FROM cms_articles');
+            $conn->executeUpdate('DELETE FROM cms_users');
         }
         if (isset($this->_usedModelSets['ecommerce'])) {
-            $conn->exec('DELETE FROM ecommerce_carts_products');
-            $conn->exec('DELETE FROM ecommerce_products_categories');
-            $conn->exec('DELETE FROM ecommerce_products_related');
-            $conn->exec('DELETE FROM ecommerce_carts');
-            $conn->exec('DELETE FROM ecommerce_customers');
-            $conn->exec('DELETE FROM ecommerce_features');
-            $conn->exec('DELETE FROM ecommerce_products');
-            $conn->exec('DELETE FROM ecommerce_shippings');
-            $conn->exec('DELETE FROM ecommerce_categories');
+            $conn->executeUpdate('DELETE FROM ecommerce_carts_products');
+            $conn->executeUpdate('DELETE FROM ecommerce_products_categories');
+            $conn->executeUpdate('DELETE FROM ecommerce_products_related');
+            $conn->executeUpdate('DELETE FROM ecommerce_carts');
+            $conn->executeUpdate('DELETE FROM ecommerce_customers');
+            $conn->executeUpdate('DELETE FROM ecommerce_features');
+            $conn->executeUpdate('DELETE FROM ecommerce_products');
+            $conn->executeUpdate('DELETE FROM ecommerce_shippings');
+            $conn->executeUpdate('DELETE FROM ecommerce_categories');
         }
         if (isset($this->_usedModelSets['company'])) {
-            $conn->exec('DELETE FROM company_persons_friends');
-            $conn->exec('DELETE FROM company_managers');
-            $conn->exec('DELETE FROM company_employees');
-            $conn->exec('DELETE FROM company_persons');
+            $conn->executeUpdate('DELETE FROM company_persons_friends');
+            $conn->executeUpdate('DELETE FROM company_managers');
+            $conn->executeUpdate('DELETE FROM company_employees');
+            $conn->executeUpdate('DELETE FROM company_persons');
         }
         if (isset($this->_usedModelSets['generic'])) {
-            $conn->exec('DELETE FROM date_time_model');
+            $conn->executeUpdate('DELETE FROM date_time_model');
         }
         $this->_em->clear();
     }