Replication

Coordinates read/write connection selection around replica lag.

When MySQL read replicas are enabled in config, the trait records a short cooldown after write events. During that cooldown reads continue using the write connection so application code does not immediately read stale replica state after creating, updating, deleting, restoring, or reordering a model.

• Full name: \PhalconKit\Mvc\Model\Traits\Replication

Properties

replicationLag

Replica lag window in milliseconds.

protected static ?int $replicationLag

A null value means replication behavior has not been initialized yet.

• This property is static.

replicationReadyAt

Unix timestamp in milliseconds after which replica reads may resume.

protected static ?int $replicationReadyAt

A null value means the replica is considered ready immediately.

• This property is static.

readWriteConnectionBehaviorEventsManager

Events manager that already received the read/write replication listeners.

protected ?\Phalcon\Contracts\Events\Manager $readWriteConnectionBehaviorEventsManager

Models can be initialized more than once in tests, long-running workers, or application code that refreshes feature options. Tracking the manager instance keeps listener attachment idempotent while still allowing a new manager to receive the listeners if the model swaps managers.

Methods

setConnectionService

Set the default connection service used by Phalcon for this model.

public setConnectionService(string $connectionService): void

Implemented by Phalcon's model base class.

• This method is abstract. Parameters:

setReadConnectionService

Set the read connection service used by Phalcon for this model.

public setReadConnectionService(string $connectionService): void

• This method is abstract. Parameters:

setWriteConnectionService

Set the write connection service used by Phalcon for this model.

public setWriteConnectionService(string $connectionService): void

• This method is abstract. Parameters:

getWriteConnectionService

Return the configured write connection service name.

public getWriteConnectionService(): string

• This method is abstract. Return Value:

DI service name for write operations.

getReadConnectionService

Return the configured read connection service name.

public getReadConnectionService(): string

• This method is abstract. Return Value:

DI service name for read operations.

getModelsManager

Return the model manager responsible for connection selection.

public getModelsManager(): \Phalcon\Mvc\Model\ManagerInterface

Phalcon's manager applies transaction and sticky-write state before resolving the configured read service.

• This method is abstract.

getReplicationLag

Return the configured replica lag window in milliseconds.

public static getReplicationLag(): int|null

• This method is static. Return Value:

Lag window, or null before replication initialization.

setReplicationLag

Set the replica lag window in milliseconds.

public static setReplicationLag(int|null $replicationLag = null): void

• This method is static. Parameters:

getReplicationReadyAt

Return the timestamp after which replica reads may resume.

public static getReplicationReadyAt(): int|null

• This method is static. Return Value:

Unix timestamp in milliseconds, or null when reads are not currently pinned to the write connection.

setReplicationReadyAt

Set the timestamp after which replica reads may resume.

public static setReplicationReadyAt(int|null $replicationReadyAt = null): void

• This method is static. Parameters:

initializeReplication

Initialize read/write connection services for replica-aware models.

public initializeReplication(array<array-key,mixed>|null $options = null): void

The trait reads database.drivers.readonly.enable from the config service. When enabled, it configures connection service names and attaches write-event listeners that temporarily pin reads to the write connection.

Parameters:

Throws:

When the config service cannot be resolved through the PhalconKit DI contract. - ServiceException

selectReadConnection

Select the connection used for model reads.

public selectReadConnection(): \Phalcon\Contracts\Db\Adapter\Adapter

During the replica-cooldown window, the write connection is returned directly. Otherwise selection is delegated to Phalcon's model manager so transactions and native sticky-write state still take precedence over the configured read service.

Return Value:

Read connection when replicas are ready; write connection while reads are pinned after a mutation.

Throws:

When the read or write connection service cannot be resolved through the PhalconKit DI contract. - ServiceException

addReadWriteConnectionBehavior

Attach lifecycle listeners that pin reads to the write connection.

public addReadWriteConnectionBehavior(): void

Each write-like event updates replicationReadyAt to now + lag. Native Phalcon requires a compatible events manager to attach these callbacks.

Throws:

When the model events manager is missing or does not implement Phalcon's events manager contract. - ServiceException

isReplicationReady

Determine whether reads may use a replica again.

public isReplicationReady(): bool

When the cooldown has expired, the ready timestamp is cleared so future calls remain ready until another write event updates it.

Return Value:

True when the replica cooldown is absent or expired.

nowMs

Return the current process time in milliseconds.

protected static nowMs(): int

This helper keeps replication timestamps integer-based and easy to compare without leaking floating-point microtime values into public replication state.

• This method is static. Return Value:

Unix timestamp in milliseconds.