Propel API
Class

Propel

class Propel

Propel's main resource pool and initialization & configuration class.

This static class is used to handle Propel initialization and to maintain all of the
open database connections and instantiated database maps.

Constants

VERSION

The Propel version.
DEFAULT_NAME

A constant for <code>default</code>.
LOG_EMERG

A constant defining 'System is unusuable' logging level
LOG_ALERT

A constant defining 'Immediate action required' logging level
LOG_CRIT

A constant defining 'Critical conditions' logging level
LOG_ERR

A constant defining 'Error conditions' logging level
LOG_WARNING

A constant defining 'Warning conditions' logging level
LOG_NOTICE

A constant defining 'Normal but significant' logging level
LOG_INFO

A constant defining 'Informational' logging level
LOG_DEBUG

A constant defining 'Debug-level messages' logging level
CLASS_PDO

The class name for a PDO object.
CLASS_PROPEL_PDO

The class name for a PropelPDO object.
CLASS_DEBUG_PDO

The class name for a DebugPDO object.
CONNECTION_READ

Constant used to request a READ connection (applies to replication).
CONNECTION_WRITE

Constant used to request a WRITE connection (applies to replication).

Methods

static  initialize()

Initializes Propel
static  configure(string $configFile)

Configure Propel a PHP (array) config file.
static  init(string $c)

Initialization of Propel a PHP (array) configuration file.
static bool isInit()

Determine whether Propel has already been initialized.
static  setConfiguration(mixed $c)

Sets the configuration for Propel and all dependencies.
static mixed getConfiguration(int $type = PropelConfiguration::TYPE_ARRAY)

Get the configuration for this component.
static  setLogger(object $logger)

Override the configured logger.
static bool hasLogger()

Returns true if a logger, for example PEAR::Log, has been configured, otherwise false.
static object logger()

Get the configured logger.
static bool log(string $message, string $level = self::LOG_DEBUG)

Logs a message If a logger has been configured, the logger will be used, otherwrise the logging message will be discarded without any further action
static DatabaseMap getDatabaseMap(string $name = null)

Returns the database map information.
static  setDatabaseMap(string $name, DatabaseMap $map)

Sets the database map object to use for specified datasource.
static  setForceMasterConnection(boolean $bit)

For replication, set whether to always force the use of a master connection.
static boolean getForceMasterConnection()

For replication, whether to always force the use of a master connection.
static  setConnection(string $name, PropelPDO $con, string $mode = Propel::CONNECTION_WRITE)

Sets a Connection for specified datasource name.
static PDO getConnection(string $name = null, string $mode = Propel::CONNECTION_WRITE)

Gets an already-opened PDO connection or opens a new one for passed-in db name.
static PDO getMasterConnection(string $name)

Gets an already-opened write PDO connection or opens a new one for passed-in db name.
static PDO getSlaveConnection(string $name)

Gets an already-opened read PDO connection or opens a new one for passed-in db name.
static PDO initConnection(array $conparams, string $name, string $defaultClass = Propel::CLASS_PROPEL_PDO)

Opens a new PDO connection for passed-in db name.
static DBAdapter getDB(string $name = null)

Returns database adapter for a specific datasource.
static  setDB(string $name, DBAdapter $adapter)

Sets a database adapter for specified datasource.
static string getDefaultDB()

Returns the name of the default database.
static  close()

Closes any associated resource handles.
static boolean autoload(string $className)

Autoload function for loading propel dependencies.
static  initBaseDir()

Initialize the base directory for the autoloader.
static string importClass($path)

Include once a file specified in DOT notation and return unqualified classname.
static  setDatabaseMapClass(string $name)

Set your own class-name for Database-Mapping.
static boolean disableInstancePooling()

Disable instance pooling.
static boolean enableInstancePooling()

Enable instance pooling (enabled by default).
static boolean isInstancePoolingEnabled()

the instance pooling behaviour.

Details

at line 263
static public initialize()

Initializes Propel

Exceptions

PropelException Any exceptions caught during processing will be rethrown wrapped into a PropelException.

at line 290
static public configure(string $configFile)

Configure Propel a PHP (array) config file.

Parameters

string $configFile Path (absolute or relative to include_path) to config file.

Exceptions

PropelException If configuration file cannot be opened. (E_WARNING probably will also be raised by PHP)

at line 326
static public init(string $c)

Initialization of Propel a PHP (array) configuration file.

Parameters

string $c The Propel configuration file path.

Exceptions

PropelException Any exceptions caught during processing will be rethrown wrapped into a PropelException.

at line 337
static public bool isInit()

Determine whether Propel has already been initialized.

Return Value

bool True if Propel is already initialized.

at line 347
static public setConfiguration(mixed $c)

Sets the configuration for Propel and all dependencies.

Parameters

mixed $c The Configuration (array or PropelConfiguration)

at line 368
static public mixed getConfiguration(int $type = PropelConfiguration::TYPE_ARRAY)

Get the configuration for this component.

Parameters

int $type - PropelConfiguration::TYPE_ARRAY: return the configuration as an array (for backward compatibility this is the default) - PropelConfiguration::TYPE_ARRAY_FLAT: return the configuration as a flat array ($config['name.space.item']) - PropelConfiguration::TYPE_OBJECT: return the configuration as a PropelConfiguration instance

Return Value

mixed The Configuration (array or PropelConfiguration)

at line 385
static public setLogger(object $logger)

Override the configured logger.

This is primarily for things like unit tests / debugging where
you want to change the logger without altering the configuration file.

You can use any logger class that implements the propel.logger.BasicLogger
interface. This interface is based on PEAR::Log, so you can also simply pass
a PEAR::Log object to this method.

Parameters

object $logger The new logger to use. ([PEAR] Log or BasicLogger)

at line 396
static public bool hasLogger()

Returns true if a logger, for example PEAR::Log, has been configured, otherwise false.

Return Value

bool True if Propel uses logging

at line 406
static public object logger()

Get the configured logger.

Return Value

object Configured log class ([PEAR] Log or BasicLogger).

at line 421
static public bool log(string $message, string $level = self::LOG_DEBUG)

Logs a message If a logger has been configured, the logger will be used, otherwrise the logging message will be discarded without any further action

Parameters

string $message The message that will be logged.
string $level The logging level.

Return Value

bool True if the message was logged successfully or no logger was used.

at line 459
static public DatabaseMap getDatabaseMap(string $name = null)

Returns the database map information.

Name relates to the name
of the connection pool to associate with the map.

The database maps are "registered" by the generated map builder classes.

Parameters

string $name The name of the database corresponding to the DatabaseMap to retrieve.

Return Value

DatabaseMap The named <code>DatabaseMap</code>.

Exceptions

PropelException - if database map is null or propel was not initialized properly.

at line 482
static public setDatabaseMap(string $name, DatabaseMap $map)

Sets the database map object to use for specified datasource.

Parameters

string $name The datasource name.
DatabaseMap $map The database map object to use for specified datasource.

at line 495
static public setForceMasterConnection(boolean $bit)

For replication, set whether to always force the use of a master connection.

Parameters

boolean $bit True or False

at line 505
static public boolean getForceMasterConnection()

For replication, whether to always force the use of a master connection.

Return Value

boolean

at line 517
static public setConnection(string $name, PropelPDO $con, string $mode = Propel::CONNECTION_WRITE)

Sets a Connection for specified datasource name.

Parameters

string $name The datasource name for the connection being set.
PropelPDO $con The PDO connection.
string $mode Whether this is a READ or WRITE connection (Propel::CONNECTION_READ, Propel::CONNECTION_WRITE)

at line 539
static public PDO getConnection(string $name = null, string $mode = Propel::CONNECTION_WRITE)

Gets an already-opened PDO connection or opens a new one for passed-in db name.

Parameters

string $name The datasource name that is used to look up the DSN from the runtime configuation file.
string $mode The connection mode (this applies to replication systems).

Return Value

PDO A database connection

Exceptions

PropelException - if connection cannot be configured or initialized.

at line 566
static public PDO getMasterConnection(string $name)

Gets an already-opened write PDO connection or opens a new one for passed-in db name.

Parameters

string $name The datasource name that is used to look up the DSN from the runtime configuation file. Empty name not allowed.

Return Value

PDO A database connection

Exceptions

PropelException - if connection cannot be configured or initialized.

at line 592
static public PDO getSlaveConnection(string $name)

Gets an already-opened read PDO connection or opens a new one for passed-in db name.

Parameters

string $name The datasource name that is used to look up the DSN from the runtime configuation file. Empty name not allowed.

Return Value

PDO A database connection

Exceptions

PropelException - if connection cannot be configured or initialized.

at line 639
static public PDO initConnection(array $conparams, string $name, string $defaultClass = Propel::CLASS_PROPEL_PDO)

Opens a new PDO connection for passed-in db name.

Parameters

array $conparams Connection paramters.
string $name Datasource name.
string $defaultClass The PDO subclass to instantiate if there is no explicit classname specified in the connection params (default is Propel::CLASS_PROPEL_PDO)

Return Value

PDO A database connection of the given class (PDO, PropelPDO, SlavePDO or user-defined)

Exceptions

PropelException - if lower-level exception caught when trying to connect.

at line 744
static public DBAdapter getDB(string $name = null)

Returns database adapter for a specific datasource.

Parameters

string $name The datasource name.

Return Value

DBAdapter The corresponding database adapter.

Exceptions

PropelException If unable to find DBdapter for specified db.

at line 768
static public setDB(string $name, DBAdapter $adapter)

Sets a database adapter for specified datasource.

Parameters

string $name The datasource name.
DBAdapter $adapter The DBAdapter implementation to use.

at line 781
static public string getDefaultDB()

Returns the name of the default database.

Return Value

string Name of the default DB

at line 796
static public close()

Closes any associated resource handles.

This method frees any database connection handles that have been
opened by the getConnection() method.

at line 811
static public boolean autoload(string $className)

Autoload function for loading propel dependencies.

Parameters

string $className The class name needing loading.

Return Value

boolean TRUE if the class was loaded, false otherwise.

at line 825
static public initBaseDir()

Initialize the base directory for the autoloader.

Avoids a call to dirname(__FILE__) each time self::autoload() is called.
FIXME put in the constructor if the Propel class ever becomes a singleton

at line 842
static public string importClass($path)

Include once a file specified in DOT notation and return unqualified classname.

Typically, Propel uses autoload is used to load classes and expects that all classes
referenced within Propel are included in Propel's autoload map. This method is only
called when a specific non-Propel classname was specified -- for example, the
classname of a validator in the schema.xml. This method will attempt to include that
class via autoload and then relative to a location on the include_path.

Parameters

$path

Return Value

string unqualified classname

at line 876
static public setDatabaseMapClass(string $name)

Set your own class-name for Database-Mapping.

Then
you can change the whole TableMap-Model, but keep its
functionality for Criteria.

Parameters

string $name The name of the class.

at line 887
static public boolean disableInstancePooling()

Disable instance pooling.

Return Value

boolean true if the method changed the instance pooling state, false if it was already disabled

at line 902
static public boolean enableInstancePooling()

Enable instance pooling (enabled by default).

Return Value

boolean true if the method changed the instance pooling state, false if it was already enabled

at line 916
static public boolean isInstancePoolingEnabled()

the instance pooling behaviour.

True by default.

Return Value

boolean Whether the pooling is enabled or not.