| <?php |
| /** |
| * File containing the ezcDbInstance class. |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| * @package Database |
| * @version //autogentag// |
| * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0 |
| */ |
| |
| /** |
| * Holds database instances for global access throughout an application. |
| * |
| * It is common for many application to use only one or very few database connections. |
| * This class holds a single database connection name or a list of databases |
| * identified by a handle. The database connections can be retrieved from anywhere |
| * within your code through the static methods. |
| * This eliminates the need to pass the connection handle around. |
| * |
| * Typical usage example: |
| * <code> |
| * $db = ezcDbFactory::create( $dbparams ); |
| * ezcDbInstance::set( $db ); |
| * |
| * // ... |
| * |
| * $db = ezcDbInstance::get(); |
| * </code> |
| * |
| * More complex example, with two connections, having identifiers (for convenience): |
| * <code> |
| * $mydb = ezcDbFactory::create( $mysql_dbparams ); |
| * $pgdb = ezcDbFactory::create( $pgsql_dbparams ); |
| * |
| * ezcDbInstance::set( $mydb, 'my' ); |
| * ezcDbInstance::set( $pgdb, 'pg' ); |
| * ezcDbInstance::chooseDefault( 'my' ); |
| * |
| * // ... |
| * |
| * $mydb = ezcDbInstance::get( 'my' ); // returns the mysql instance |
| * $pgdb = ezcDbInstance::get( 'pg' ); // returns the pgsql instance |
| * $mydb = ezcDbInstance::get(); // returns the mysql instance which is default |
| * </code> |
| * |
| * @package Database |
| * @version //autogentag// |
| * @mainclass |
| */ |
| class ezcDbInstance |
| { |
| /** |
| * Identifier of the instance that will be returned |
| * when you call get() without arguments. |
| * |
| * @see ezcDbInstance::get() |
| * @var string |
| */ |
| static private $DefaultInstanceIdentifier = false; |
| |
| /** |
| * Holds the database instances. |
| * |
| * Example: |
| * <code> |
| * array( 'mysql1' => [object], |
| * 'mysql2' => [object], |
| * 'oracle' => [object] ) |
| * </code> |
| * |
| * @var array(string=>ezcDbHandler) |
| */ |
| static private $Instances = array(); |
| |
| /** |
| * Returns the database instance $identifier. |
| * |
| * If $identifier is ommited the default database instance |
| * specified by chooseDefault() is returned. |
| * |
| * @throws ezcDbHandlerNotFoundException if the specified instance is not found. |
| * @param string $identifier |
| * @return ezcDbHandler |
| */ |
| public static function get( $identifier = false ) |
| { |
| if ( $identifier === false && self::$DefaultInstanceIdentifier ) |
| { |
| $identifier = self::$DefaultInstanceIdentifier; |
| } |
| |
| if ( !isset( self::$Instances[$identifier] ) ) |
| { |
| // The DatabaseInstanceFetchConfig callback should return an |
| // ezcDbHandler object which will then be set as instance. |
| $ret = ezcBaseInit::fetchConfig( 'ezcInitDatabaseInstance', $identifier ); |
| if ( $ret === null ) |
| { |
| throw new ezcDbHandlerNotFoundException( $identifier ); |
| } |
| else |
| { |
| self::set( $ret, $identifier ); |
| } |
| } |
| |
| return self::$Instances[$identifier]; |
| } |
| |
| /** |
| * Returns the identifiers of the registered database instances. |
| * |
| * @return array(string) |
| */ |
| public static function getIdentifiers() |
| { |
| return array_keys( self::$Instances ); |
| } |
| |
| /** |
| * Adds the database handler $db to the list of known instances. |
| * |
| * If $identifier is specified the database instance can be |
| * retrieved later using the same identifier. |
| * |
| * @param ezcDbHandler $db |
| * @param string $identifier the identifier of the database handler |
| * @return void |
| */ |
| public static function set( ezcDbHandler $db, $identifier = false ) |
| { |
| self::$Instances[$identifier] = $db; |
| } |
| |
| /** |
| * Sets the database $identifier as default database instance. |
| * |
| * To retrieve the default database instance |
| * call get() with no parameters.. |
| * |
| * @see ezcDbInstance::get(). |
| * @param string $identifier |
| * @return void |
| */ |
| public static function chooseDefault( $identifier ) |
| { |
| self::$DefaultInstanceIdentifier = $identifier; |
| } |
| |
| /** |
| * Resets the default instance holder. |
| * |
| * @return void |
| */ |
| public static function resetDefault() |
| { |
| self::$DefaultInstanceIdentifier = false; |
| } |
| |
| /** |
| * Resets this object to its initial state. |
| * |
| * The list of instances will be emptied and |
| * {@link resetDefault()} will be called. |
| * |
| * @return void |
| */ |
| public static function reset() |
| { |
| self::$Instances = array(); |
| self::resetDefault(); |
| } |
| } |
| |
| ?> |