SignalTrait
Signal Trait
Provides PCNTL signal handling capabilities for CLI commands. Requires the PCNTL extension (Unix only).
Table of Contents
Properties
- $isPcntlAvailable : bool|null
- Cached result of PCNTL extension availability.
- $isPosixAvailable : bool|null
- Cached result of POSIX extension availability.
- $registeredSignals : array<int, int>
- Array of registered signals.
- $running : bool
- Whether the process should continue running (false = termination requested).
- $signalMethodMap : array<int, string>
- Signal-to-method mapping.
- $signalsBlocked : bool
- Whether signals are currently blocked.
Methods
- blockSignals() : void
- Block ALL interruptible signals during critical sections.
-
getProcessState()
: array{pid: int, running: bool, pcntl_available: bool, registered_signals: int, registered_signals_names: array
- Get comprehensive process state information.
- getSignalName() : string
- Get human-readable signal name.
- getSignals() : array<int, int>
- Get list of registered signals.
- handleSignal() : void
- Handle incoming signals.
- hasSignals() : bool
- Check if signals are registered.
- isPcntlAvailable() : bool
- Check if PCNTL extension is available (cached).
- isPosixAvailable() : bool
- Check if POSIX extension is available (cached).
- isRunning() : bool
- Check if the process is currently running (not terminated).
- mapSignal() : void
- Add or update signal-to-method mapping at runtime.
- registerSignals() : void
- Register signal handlers.
- requestTermination() : void
- Request immediate termination.
- resetState() : void
- Reset all states (for testing or restart scenarios).
- shouldTerminate() : bool
- Check if command should terminate.
- signalsBlocked() : bool
- Check if signals are currently blocked.
- unblockSignals() : void
- Unblock previously blocked signals.
- unregisterSignals() : void
- Unregister all signals (cleanup).
- withSignalsBlocked() : TReturn
- Execute a callable with ALL signals blocked to prevent ANY interruption during critical operations.
- callCustomHandler() : void
- Call custom signal handler if one is mapped for this signal.
Properties
$isPcntlAvailable
Cached result of PCNTL extension availability.
private
static bool|null
$isPcntlAvailable
= null
$isPosixAvailable
Cached result of POSIX extension availability.
private
static bool|null
$isPosixAvailable
= null
$registeredSignals
Array of registered signals.
private
array<int, int>
$registeredSignals
= []
$running
Whether the process should continue running (false = termination requested).
private
bool
$running
= true
$signalMethodMap
Signal-to-method mapping.
private
array<int, string>
$signalMethodMap
= []
$signalsBlocked
Whether signals are currently blocked.
private
bool
$signalsBlocked
= false
Methods
blockSignals()
Block ALL interruptible signals during critical sections.
protected
blockSignals() : void
Only SIGKILL (unblockable) can terminate the process.
getProcessState()
Get comprehensive process state information.
protected
getProcessState() : array{pid: int, running: bool, pcntl_available: bool, registered_signals: int, registered_signals_names: array, signals_blocked: bool, explicit_mappings: int, memory_usage_mb: float, memory_peak_mb: float, session_id?: false|int, process_group?: false|int, has_controlling_terminal?: bool}
Return values
array{pid: int, running: bool, pcntl_available: bool, registered_signals: int, registered_signals_names: arraygetSignalName()
Get human-readable signal name.
protected
getSignalName(int $signal) : string
Parameters
- $signal : int
Return values
stringgetSignals()
Get list of registered signals.
protected
getSignals() : array<int, int>
Return values
array<int, int>handleSignal()
Handle incoming signals.
protected
handleSignal(int $signal) : void
Parameters
- $signal : int
hasSignals()
Check if signals are registered.
protected
hasSignals() : bool
Return values
boolisPcntlAvailable()
Check if PCNTL extension is available (cached).
protected
isPcntlAvailable() : bool
Return values
boolisPosixAvailable()
Check if POSIX extension is available (cached).
protected
isPosixAvailable() : bool
Return values
boolisRunning()
Check if the process is currently running (not terminated).
protected
isRunning() : bool
Return values
boolmapSignal()
Add or update signal-to-method mapping at runtime.
protected
mapSignal(int $signal, string $method) : void
Parameters
- $signal : int
- $method : string
registerSignals()
Register signal handlers.
protected
registerSignals([array<int, int> $signals = [] ][, array<int, string> $methodMap = [] ]) : void
Parameters
- $signals : array<int, int> = []
-
List of signals to handle
- $methodMap : array<int, string> = []
-
Optional signal-to-method mapping
requestTermination()
Request immediate termination.
protected
requestTermination() : void
resetState()
Reset all states (for testing or restart scenarios).
protected
resetState() : void
shouldTerminate()
Check if command should terminate.
protected
shouldTerminate() : bool
Return values
boolsignalsBlocked()
Check if signals are currently blocked.
protected
signalsBlocked() : bool
Return values
boolunblockSignals()
Unblock previously blocked signals.
protected
unblockSignals() : void
unregisterSignals()
Unregister all signals (cleanup).
protected
unregisterSignals() : void
withSignalsBlocked()
Execute a callable with ALL signals blocked to prevent ANY interruption during critical operations.
protected
withSignalsBlocked(callable(): TReturn $operation) : TReturn
This blocks ALL interruptible signals including:
- Termination signals (SIGTERM, SIGINT, etc.)
- Pause/resume signals (SIGTSTP, SIGCONT)
- Custom signals (SIGUSR1, SIGUSR2)
Only SIGKILL (unblockable) can still terminate the process. Use this for database transactions, file operations, or any critical atomic operations.
Parameters
- $operation : callable(): TReturn
Tags
Return values
TReturncallCustomHandler()
Call custom signal handler if one is mapped for this signal.
private
callCustomHandler(int $signal) : void
Falls back to generic onInterruption() method if no explicit mapping exists.
Parameters
- $signal : int