Introduction

The database connection manager is an excelent tool that can help you to manage database connections for your application / website.
This component will store the connection details and conveniently initialize a pdo object to handle queries.
This tool offers also full support for the PtcQueryBuilder component, if specified as an option when adding a connection.

Main Features:

Handles multiple database connections
Full PDO support to handle queries
Can be used with the PtcQueryBuilder class
Uses the PtcDebug class to log connections

Getting Started

To start managing your database connections with the component, we can use the PtcDb::add( ) method to add a connection:

require_once( 'PtcDb.php' );
// adding a connection, this will be the default connection
PtcDb::add( array
(
    'user'  =>  'some user',
    'pass'  =>  'some pass',
    'db'    =>  'some database',
) );

We just added a new connection to the connection manager.

Note: If the parameter "$name" is not specified, the class will automatically use the default connection.

Connection Options

All possible connection options that can be passed to the PtcDb::add( ) method, are stored in the PtcDb::$_connectionOptions property:

$_connectionOptions = array
(
    'name'              =>  'default' , // the connection name
    'driver'                =>  'mysql' , // the driver for the pdo object
    'user'              =>  'root' , // the database username
    'pass'              =>  '' , // the username password
    'host'              =>  'localhost' , // the database host
    'db'                =>  'database' , // the database name
    'charset'               =>  'utf8' , // the database charset
    'query_builder'     =>  false , // use the query builder component
    'query_builder_class'   =>  'PtcQueryBuilder' , // the name of qurey builder class
    'pdo_attributes'        =>  array // attributes for the pdo object
    ( 
        PDO::ATTR_ERRMODE               =>  PDO::ERRMODE_WARNING ,
        PDO::ATTR_DEFAULT_FETCH_MODE    =>  PDO::FETCH_OBJ
    )
);

The following sections will describe these options in details:

name

This option sets the connection name.

Default value: default (string)

Note: The name of the connection should be passed with the "$name" argument to the PtcDb::add( ) method directly.

driver

This is the driver that the pdo object will use, currently only mysql is supported.

Default value: mysql (string)

user

This option sets the database username.

Default value: root (string)

pass

This option sets the username password.

Default value: default (string)

host

This option sets the databse host.

Default value: localhost (string)

db

This option sets the database name.

Default value: database (string)

charset

This option sets the charset for the database connection.

Default value: utf8 (string)

query_builder

This option adds query builder support to the connection manager, keep in mind that the PtcQueryBuilder component needs to be present.

See Using the Query Builder for a detailed explanation on using the Query Builder.

Default value: false (bool)

query_builder_class

This option sets the name of the query builder component, usefull if the component has been extended or is under a namespace.

Note: This option will only work with the query_builder option set to true.

Default value: PtcQueryBuilder (string)

pdo_attributes

This option sets attributes to the pdo object.
These are the default attributes that are been set when the PtcDb::add( ) method is called:

array
( 
    PDO::ATTR_ERRMODE                   =>  PDO::ERRMODE_WARNING ,
    PDO::ATTR_DEFAULT_FETCH_MODE        =>  PDO::FETCH_OBJ
);

Using Pdo with the Connection Manager

To use the Pdo object to handle queries with the default connection is very simple, here is and example that speaks for it self:

// calling Pdo object with the default connection
$query = PtcDb::prepare( 'SELECT * FROM some table' );
$query->execute( );
var_dump( $query->fetchAll( ) );

To use another connection you can use the PtcDb::getPdo( ) method:

// getting the pdo object
$pdo_object = PtcDb::getPdo( 'your connection name' );
// running queries with Pdo
$query = $pdo_object->prepare( 'SELECT * FROM some table' );
$query->execute( );
var_dump( $query->fetchAll( ) );

Using the Query Builder

To start using the PtcQueryBuilder component with the database connection manager we need to specify it when we are adding a connection.
Here is a practical example:

// including the Query Builder component
require_once( 'PtcQueryBuilder.php' ); 
// adding another database connection with the query builder class support
PtcDb::add( array
(
    'user'          =>  'some user' ,
    'pass'          =>  'some pass' ,
    'db'            =>  'some database' ,
    'query_builder' =>  true    // initialize the query builder
) );

To call methods from the PtcQueryBuilder is just like using the Pdo, here is an example using the default connection:

PtcDb::table( 'test_table' )->select( 'some_column as test' )->run( );

To retrieve the query builder object from another connection, the method PtcDb::getQB( ) can be used:

// getting the query builder object
$qb = PtcDb::getQB( 'your connection name' );
// running a query
$result = $qb->table( 'test_table' )
        ->select( 'some_column as test' )
        ->run( );

Refer to the Query Builder Component (PtcQueryBuilder) user manual for detailed usage.

Getting Connection Details

To retrieve the options from a previously configured connection with the PtcDb::add( ) method, we can use the PtcDb::getConnection( ) method:

// returns an array with the connection options
$conn_details = PtcDb::getConnection( 'your connection name' );
var_dump( $conn_details );

Note: If the parameter $name is not specified, all configured connections will be returned.

Table of Contents