Primordyx Framework Documentation

ConnectionManager
in package

Class ConnectionManager

Centralizes database handles for the Primordyx framework using connection management. Connections must be configured manually via createHandle() in your bootstrap.php. Cached for reuse within the same request lifecycle.

Manual Configuration Example:

ConnectionManager::createHandle('default',
    'mysql:host=localhost;dbname=myapp;charset=utf8mb4',
    'app_user',
    'secure_password_123',
    [PDO::ATTR_TIMEOUT => 30]
);

Usage Examples:

  $db = ConnectionManager::getHandle();           // default connection
  $db = ConnectionManager::getHandle('reporting'); // named connection
  ConnectionManager::forget('reporting');         // close specific connection
  ConnectionManager::reconnect('default');       // force reconnection
Tags
since
1.0.0

Table of Contents

Properties

$configs  : array<string, array<string|int, mixed>>
$handles  : array<string, PDO>

Methods

createHandle()  : PDO
Create and configure a database connection handle.
forget()  : void
Close and remove a connection from the handles.
forgetAll()  : void
Close all connections and clear the handles.
getConnectionNames()  : array<string|int, string>
Get all available connection names.
getHandle()  : PDO
Get a PDO handle for database operations.
hasConnection()  : bool
Check if a connection exists in the handles.
reconnect()  : PDO
Force reconnection by destroying and recreating a connection.
registerConfig()  : void
Register a database configuration for lazy loading.
createAndStoreHandle()  : PDO
Create PDO connection, set attributes, and store in handles array.

Properties

$configs

protected static array<string, array<string|int, mixed>> $configs = []

Stored connection configurations

Methods

createHandle()

Create and configure a database connection handle.

public static createHandle(string $handleName, string $dsn, string $username, string $password[, array<string|int, mixed> $options = [] ]) : PDO

This method allows you to configure database connections programmatically. Useful for CLI scripts, testing, or dynamic configuration scenarios.

Parameters
$handleName : string

Connection handle name

$dsn : string

PDO Data Source Name

$username : string

Database username

$password : string

Database password

$options : array<string|int, mixed> = []

PDO options array

Tags
throws
PDOException

If database connection fails

example 
// Create default connection
ConnectionManager::createHandle('default',
    'mysql:host=localhost;dbname=myapp;charset=utf8mb4',
    'app_user',
    'secure_password',
    [PDO::ATTR_TIMEOUT => 30]
);
example 
// Create admin connection for elevated operations
ConnectionManager::createHandle('admin',
    'mysql:host=localhost;dbname=mysql;charset=utf8mb4',
    'root',
    'root_password'
);
Return values
PDO —

The configured PDO connection

forget()

Close and remove a connection from the handles.

public static forget([string $handleName = 'default' ]) : void

This method properly closes a database connection and removes it from the internal handles pool. Useful for long-running processes or when you need to force a fresh connection (e.g., after configuration changes).

Parameters
$handleName : string = 'default'

The name of the connection handle to close

Tags
example 
// Close the default connection
ConnectionManager::forget();
example 
// Close a specific named connection
ConnectionManager::forget('reporting');

forgetAll()

Close all connections and clear the handles.

public static forgetAll() : void

getConnectionNames()

Get all available connection names.

public static getConnectionNames() : array<string|int, string>
Return values
array<string|int, string> —

Array of connection handle names

getHandle()

Get a PDO handle for database operations.

public static getHandle([string $handleName = 'default' ]) : PDO

This method implements connection caching - if a connection for the specified handle name already exists, it returns the cached instance. If not found in handles, it attempts to create one from stored configuration.

Parameters
$handleName : string = 'default'

Connection handle name

Tags
throws
PDOException

If database connection fails

throws
RuntimeException

If connection not found and no configuration available

example 
// Get default database connection
$db = ConnectionManager::getHandle();
example 
// Get named connection for reporting database
$reportDb = ConnectionManager::getHandle('reporting');
Return values
PDO —

Configured PDO database handle

hasConnection()

Check if a connection exists in the handles.

public static hasConnection([string $handleName = 'default' ]) : bool
Parameters
$handleName : string = 'default'

Connection handle name

Return values
bool —

True if connection exists

reconnect()

Force reconnection by destroying and recreating a connection.

public static reconnect([string $handleName = 'default' ]) : PDO

This method removes the existing connection from the handles pool and immediately recreates it using the stored configuration. Useful when you suspect a connection has gone stale or want to refresh connection settings.

Parameters
$handleName : string = 'default'

Connection handle name

Tags
throws
RuntimeException

If no stored configuration exists for the handle

example 
// Force reconnect to default database
$db = ConnectionManager::reconnect();
example 
// Force reconnect to admin database
$adminDb = ConnectionManager::reconnect('admin');
Return values
PDO —

The new PDO connection

registerConfig()

Register a database configuration for lazy loading.

public static registerConfig(string $handleName, string $dsn, string $username, string $password[, array<string|int, mixed> $options = [] ]) : void

Connection will be created on first use via getHandle()

Parameters
$handleName : string

Connection handle name

$dsn : string

PDO Data Source Name

$username : string

Database username

$password : string

Database password

$options : array<string|int, mixed> = []

PDO options array

createAndStoreHandle()

Create PDO connection, set attributes, and store in handles array.

private static createAndStoreHandle(string $handleName) : PDO
Parameters
$handleName : string

Connection handle name

Tags
throws
PDOException

If database connection fails

Return values
PDO —

$handle


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results