1. <?php
  2. /**
  3.  * File containing the ezcDbInstance class.
  4.  *
  5.  * @package Database
  6.  * @version 1.4
  7.  * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved.
  8.  * @license http://ez.no/licenses/new_bsd New BSD License
  9.  */
 10.  
 11. /**
 12.  * Holds database instances for global access throughout an application.
 13.  *
 14.  * It is common for many application to use only one or very few database connections.
 15.  * This class holds a single database connection name or a list of databases
 16.  * identified by a handle. The database connections can be retrieved from anywhere
 17.  * within your code through the static methods.
 18.  * This eliminates the need to pass the connection handle around.
 19.  *
 20.  * Typical usage example:
 21.  * <code>
 22.  * $db = ezcDbFactory::create( $dbparams );
 23.  * ezcDbInstance::set( $db );
 24.  *
 25.  * // ...
 26.  *
 27.  * $db = ezcDbInstance::get();
 28.  * </code>
 29.  *
 30.  * More complex example, with two connections, having identifiers (for convenience):
 31.  * <code>
 32.  * $mydb = ezcDbFactory::create( $mysql_dbparams );
 33.  * $pgdb = ezcDbFactory::create( $pgsql_dbparams );
 34.  *
 35.  * ezcDbInstance::set( $mydb, 'my' );
 36.  * ezcDbInstance::set( $pgdb, 'pg' );
 37.  * ezcDbInstance::chooseDefault( 'my' );
 38.  *
 39.  * // ...
 40.  *
 41.  * $mydb = ezcDbInstance::get( 'my' ); // returns the mysql instance
 42.  * $pgdb = ezcDbInstance::get( 'pg' ); // returns the pgsql instance
 43.  * $mydb = ezcDbInstance::get();  // returns the mysql instance which is default
 44.  * </code>
 45.  *
 46.  * @package Database
 47.  * @version 1.4
 48.  * @mainclass
 49.  */
 50. class ezcDbInstance
 51. {
 52.     /**
 53.      * Identifier of the instance that will be returned
 54.      * when you call get() without arguments.
 55.      *
 56.      * @see ezcDbInstance::get()
 57.      * @var string 
 58.      */
 59.     static private $DefaultInstanceIdentifier = false;
 60.  
 61.     /**
 62.      * Holds the database instances.
 63.      *
 64.      * Example:
 65.      * <code>
 66.      * array( 'mysql1' => [object],
 67.      *        'mysql2' => [object],
 68.      *        'oracle' => [object] )
 69.      * </code>
 70.      *
 71.      * @var array(string=>ezcDbHandler) 
 72.      */
 73.     static private $Instances = array();
 74.  
 75.     /**
 76.      * Returns the database instance $identifier.
 77.      *
 78.      * If $identifier is ommited the default database instance
 79.      * specified by chooseDefault() is returned.
 80.      *
 81.      * @throws ezcDbHandlerNotFoundException if the specified instance is not found.
 82.      * @param string $identifier 
 83.      * @return ezcDbHandler 
 84.      */
 85.     public static function get( $identifier = false )
 86.     {
 87.         if ( $identifier === false && self::$DefaultInstanceIdentifier )
 88.         {
 89.             $identifier = self::$DefaultInstanceIdentifier;
 90.         }
 91.  
 92.         if ( !isset( self::$Instances[$identifier] ) )
 93.         {
 94.             // The DatabaseInstanceFetchConfig callback should return an
 95.             // ezcDbHandler object which will then be set as instance.
 96.             $ret = ezcBaseInit::fetchConfig( 'ezcInitDatabaseInstance', $identifier );
 97.             if ( $ret === null )
 98.             {
 99.                 throw new ezcDbHandlerNotFoundException( $identifier );
100.             }
101.             else
102.             {
103.                 self::set( $ret, $identifier );
104.             }
105.         }
106.  
107.         return self::$Instances[$identifier];
108.     }
109.  
110.     /**
111.      * Returns the identifiers of the registered database instances.
112.      *
113.      * @return array(string) 
114.      */
115.     public static function getIdentifiers()
116.     {
117.         return array_keys( self::$Instances );
118.     }
119.  
120.     /**
121.      * Adds the database handler $db to the list of known instances.
122.      *
123.      * If $identifier is specified the database instance can be
124.      * retrieved later using the same identifier.
125.      *
126.      * @param ezcDbHandler $db 
127.      * @param string $identifier the identifier of the database handler
128.      * @return void 
129.      */
130.     public static function set( ezcDbHandler $db, $identifier = false )
131.     {
132.         self::$Instances[$identifier] = $db;
133.     }
134.  
135.     /**
136.      * Sets the database $identifier as default database instance.
137.      *
138.      * To retrieve the default database instance
139.      * call get() with no parameters..
140.      *
141.      * @see ezcDbInstance::get().
142.      * @param string $identifier 
143.      * @return void 
144.      */
145.     public static function chooseDefault( $identifier )
146.     {
147.         self::$DefaultInstanceIdentifier = $identifier;
148.     }
149.  
150.     /**
151.      * Resets the default instance holder.
152.      *
153.      * @return void 
154.      */
155.     public static function resetDefault()
156.     {
157.         self::$DefaultInstanceIdentifier = false;
158.     }
159.  
160.     /**
161.      * Resets this object to its initial state.
162.      *
163.      * The list of instances will be emptied and
164.      * {@link resetDefault()} will be called.
165.      *
166.      * @return void 
167.      */
168.     public static function reset()
169.     {
170.         self::$Instances = array();
171.         self::resetDefault();
172.     }
173. }
174.  
175. ?>