class DatabaseConnectionResolver extends ConnectionResolver implements CachedConnectionResolver

Database connection resolver for the testing environment.

Testbench needs stable bare connections across its setup, transaction, and assertion helpers. The resolver therefore retains each borrowed wrapper alongside its bare connection and explicitly discards both at teardown. Concurrent database tests enable pool.testing_enabled to use coroutine-owned connections.

Constants

DEFAULT_CONNECTION_CONTEXT_KEY

Context key for per-coroutine default connection override.

Shared with DatabaseManager::usingConnection() to ensure all access paths respect the override.

Properties

protected string|null $default

The config-derived default connection name, captured at construction.

from  ConnectionResolver
protected PoolManager $poolManager from  ConnectionResolver
protected ConnectionLease|PooledConnection> $nonCoroutineConnections

Pooled wrappers retained by non-coroutine task execution.

from  ConnectionResolver
static protected Connection> $connections

Connections for testing environment.

static protected Connection> $pooledConnections

Borrowed pooled wrappers that own the cached bare connections.

static protected int|null $containerId

The object ID of the container when connections were cached.

static protected bool $rebindingRegistered

Whether the dispatcher rebinding hook has been registered.

Methods

__construct(Container $container)

Create a new connection resolver instance.

connection(UnitEnum|string|null $name = null)

Get a database connection instance.

Connection|null
getHeldConnection(UnitEnum|string|null $name = null)

Get the connection owned by the active testing mode without borrowing one.

bool
hasApplicableTransaction(UnitEnum|string|null $name = null)

Check the retained testing connection before coroutine-owned connections.

string
connectionDateFormat(UnitEnum|string|null $name = null)

Get the query grammar date format of a connection without holding one.

static void
releaseIdleConnections()

Return idle physical sessions owned by the current execution.

void
releaseConnections()

Release connections retained by non-coroutine task execution.

void
discardConnections()

Discard connections retained by non-coroutine task execution.

string|null
getDefaultConnection()

Get the default connection name.

void
setDefaultConnection(string|null $name)

Set the default connection name for the current execution context.

string
connectionName(UnitEnum|string|null $name)

Get the connection name a request resolves to: the given name, or the current default.

string
getContextKey(string $name)

Get the context key for storing a connection.

string
getLeaseContextKey(string $name)

Get the context key for the current logical connection's lease.

void
discardFailedConnection(ConnectionLease|PooledConnection $owner, Throwable $exception)

Discard a failed connection owner while preserving cancellation precedence.

void
terminateConnections(Closure $terminate)

Detach and terminate retained non-coroutine connections.

static void
resetCachedConnections()

Reset all cached connections to clean state for another setup phase.

static void
flushCachedConnections()

Discard all cached connections and clear resolver lifecycle state.

static void
registerDispatcherRebinding(Container $container)

Register a rebinding hook for the event dispatcher.

Connection|null
getResolvedConnection(string $name)

Get an already resolved connection from the cache.

array
getRetainedConnections()

Get the connections shared across the test's setup, requests and assertions.

string
connectionCacheKey(string $name, DatabasePool|null $pool = null)

Resolve the cache key that owns the pooled wrapper.

void
flush(string $name)

Flush a cached connection.

static void
discardCachedConnection(string $cacheKey)

Discard one cached connection and its owning pooled wrapper.

bool
restoreInMemoryPdoIfPooled(UnitEnum|string|null $name, PDO $pdo)

Restore a pooled in-memory database, returning false when pooling is disabled.

bool
poolEnabled(ConnectionName $name)

Determine whether this test uses coroutine-owned pooled connections.

static void
discardCachedConnections()

Discard every cached pooled wrapper.

Details

in ConnectionResolver at line 55
__construct(Container $container)

Create a new connection resolver instance.

Parameters

Container $container

at line 248
Connection connection(UnitEnum|string|null $name = null)

Get a database connection instance.

Borrows connections through the pool manager and retains their owning wrappers until terminal test teardown.

Parameters

UnitEnum|string|null $name

Return Value

Connection

at line 161
Connection|null getHeldConnection(UnitEnum|string|null $name = null)

Get the connection owned by the active testing mode without borrowing one.

Parameters

UnitEnum|string|null $name

Return Value

Connection|null

at line 183
bool hasApplicableTransaction(UnitEnum|string|null $name = null)

Check the retained testing connection before coroutine-owned connections.

Parameters

UnitEnum|string|null $name

Return Value

bool

in ConnectionResolver at line 216
string connectionDateFormat(UnitEnum|string|null $name = null)

Get the query grammar date format of a connection without holding one.

A connection the current coroutine holds answers for itself. Otherwise the pool's recorded driver format is used. A cold lookup resolves the connection as usual, then returns only its idle physical session; connections without session leases retain their normal ownership.

Parameters

UnitEnum|string|null $name

Return Value

string

in ConnectionResolver at line 259
static void releaseIdleConnections()

Return idle physical sessions owned by the current execution.

Return Value

void

in ConnectionResolver at line 273
void releaseConnections()

internal  
 

Release connections retained by non-coroutine task execution.

Return Value

void

in ConnectionResolver at line 287
void discardConnections()

internal  
 

Discard connections retained by non-coroutine task execution.

Return Value

void

in ConnectionResolver at line 303
string|null getDefaultConnection()

Get the default connection name.

Checks Context first for per-coroutine override (from setDefaultConnection() or DatabaseManager::usingConnection()), then falls back to the config-derived default captured at construction.

Return Value

string|null

in ConnectionResolver at line 315
void setDefaultConnection(string|null $name)

Set the default connection name for the current execution context.

Writes to coroutine Context so concurrent requests in the same Swoole worker are not affected. A null value clears the override and getDefaultConnection() falls back to the config-derived default.

Parameters

string|null $name

Return Value

void

in ConnectionResolver at line 327
protected string connectionName(UnitEnum|string|null $name)

Get the connection name a request resolves to: the given name, or the current default.

Parameters

UnitEnum|string|null $name

Return Value

string

in ConnectionResolver at line 339
protected string getContextKey(string $name)

Get the context key for storing a connection.

Parameters

string $name

Return Value

string

in ConnectionResolver at line 347
protected string getLeaseContextKey(string $name)

Get the context key for the current logical connection's lease.

Parameters

string $name

Return Value

string

in ConnectionResolver at line 355
protected void discardFailedConnection(ConnectionLease|PooledConnection $owner, Throwable $exception)

Discard a failed connection owner while preserving cancellation precedence.

Parameters

ConnectionLease|PooledConnection $owner
Throwable $exception

Return Value

void

in ConnectionResolver at line 371
protected void terminateConnections(Closure $terminate)

Detach and terminate retained non-coroutine connections.

Parameters

Closure $terminate

Return Value

void

at line 73
static void resetCachedConnections()

Reset all cached connections to clean state for another setup phase.

Called after Application is created to prevent test pollution (query logs, event listeners, transaction state, etc.) from leaking between tests.

When the container changes (new test with fresh Application), cached connections are flushed since they hold references to the old container's services. A rebinding hook is registered so Event::fake() automatically updates cached connections with the new dispatcher.

The cached connections are process-global, so runtime use can reset or discard a connection borrowed by another coroutine.

Return Value

void

at line 112
static void flushCachedConnections()

Discard all cached connections and clear resolver lifecycle state.

The cached connections are process-global, so runtime use can discard a connection borrowed by another coroutine.

Return Value

void

at line 126
static protected void registerDispatcherRebinding(Container $container)

Register a rebinding hook for the event dispatcher.

When Event::fake() swaps the dispatcher, this callback updates all cached connections to use the new (fake) dispatcher.

Parameters

Container $container

Return Value

void

at line 149
Connection|null getResolvedConnection(string $name)

Get an already resolved connection from the cache.

Parameters

string $name

Return Value

Connection|null

at line 175
array getRetainedConnections()

Get the connections shared across the test's setup, requests and assertions.

Return Value

array

at line 201
protected string connectionCacheKey(string $name, DatabasePool|null $pool = null)

Resolve the cache key that owns the pooled wrapper.

Parameters

string $name
DatabasePool|null $pool

Return Value

string

at line 221
void flush(string $name)

Flush a cached connection.

Discard the owning pooled wrapper before clearing the bare connection.

Parameters

string $name

Return Value

void

at line 231
static protected void discardCachedConnection(string $cacheKey)

Discard one cached connection and its owning pooled wrapper.

Parameters

string $cacheKey

Return Value

void

at line 317
bool restoreInMemoryPdoIfPooled(UnitEnum|string|null $name, PDO $pdo)

Restore a pooled in-memory database, returning false when pooling is disabled.

Replaces the database shared by this application's pool borrowers.

Parameters

UnitEnum|string|null $name
PDO $pdo

Return Value

bool

at line 341
protected bool poolEnabled(ConnectionName $name)

Determine whether this test uses coroutine-owned pooled connections.

Parameters

ConnectionName $name

Return Value

bool

at line 352
static protected void discardCachedConnections()

Discard every cached pooled wrapper.

Return Value

void