CLI Signals

What are Signals?

Signals are software interrupts delivered to a process by the operating system. They notify processes of various events, from user-initiated interruptions (like pressing Ctrl+C) to system events (like terminal disconnection).

SignalTrait adds the ability to perform certain actions before the signal is consumed, as well as the capability to protect certain pieces of code from signal interruption. This protection mechanism guarantees the proper execution of critical command operations by ensuring they complete atomically without being interrupted by incoming signals.

Using the SignalTrait

The SignalTrait provides a comprehensive signal handling system for CLI commands. To use it, simply add the trait to your command class and register signals in your command’s run() method:

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class SampleCommand extends BaseCommand
{
    public function run(array $params): int
    {
        // Register basic termination signals
        $this->registerSignals();

        // Main processing loop
        while ($this->isRunning()) {
            // Do work here
            $this->processItem();

            sleep(3);
        }

        CLI::write('Command terminated gracefully', 'green');

        return EXIT_SUCCESS;
    }
}

This registers three termination signals that will set the $running state to false when received.

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class SampleCommand extends BaseCommand
{
    public function run(array $params): int
    {
        // Register signals with custom handlers
        $this->registerSignals(
            [SIGTERM, SIGINT, SIGUSR1, SIGUSR2],
            [
                SIGTERM => 'onGracefulShutdown',
                SIGINT  => 'onInterrupt',
                SIGUSR1 => 'onToggleDebug',
                SIGUSR2 => 'onStatusReport',
            ],
        );

        while ($this->isRunning()) {
            // Call custom method
            $this->doWork();
            sleep(1);
        }

        return EXIT_SUCCESS;
    }

    protected function onGracefulShutdown(int $signal): void
    {
        CLI::write('Received SIGTERM - shutting down gracefully...', 'yellow');
    }

    protected function onInterrupt(int $signal): void
    {
        CLI::write('Received SIGINT - stopping!', 'red');
    }

    protected function onToggleDebug(int $signal): void
    {
        // Custom debug mode
        $this->debugMode = ! $this->debugMode;
        CLI::write('Debug mode: ' . ($this->debugMode ? 'ON' : 'OFF'), 'blue');
    }

    protected function onStatusReport(int $signal): void
    {
        $state = $this->getProcessState();
        CLI::write('Status: ' . json_encode($state, JSON_PRETTY_PRINT), 'cyan');
    }
}

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class SampleCommand extends BaseCommand
{
    public function run(array $params): int
    {
        // Register signals without explicit mappings
        $this->registerSignals([SIGTERM, SIGINT, SIGHUP, SIGUSR1]);

        while ($this->isRunning()) {
            $this->doWork();
            sleep(1);
        }

        return EXIT_SUCCESS;
    }

    /**
     * Generic handler for all unmapped signals
     */
    protected function onInterruption(int $signal): void
    {
        $signalName = $this->getSignalName($signal);
        CLI::write("Received {$signalName} - handling generically", 'yellow');

        switch ($signal) {
            case SIGTERM:
                CLI::write('Graceful shutdown requested', 'green');
                break;

            case SIGINT:
                CLI::write('Immediate shutdown requested', 'red');
                break;

            case SIGHUP:
                CLI::write('Configuration reload requested', 'blue');
                break;

            case SIGUSR1:
                CLI::write('User signal 1 received', 'cyan');
                break;

            default:
                CLI::write('Unknown signal received', 'light_gray');
                break;
        }
    }
}

Critical Sections

Some operations should never be interrupted (database transactions, file operations). Use withSignalsBlocked() to create atomic operations:

<?php

use CodeIgniter\CLI\CLI;

class SampleCommand extends \BaseCommand
{
    // ...
    private function processOrder(array $orderData): void
    {
        // Critical section - no interruptions allowed
        $result = $this->withSignalsBlocked(function () use ($orderData) {
            CLI::write('Starting critical transaction - signals blocked', 'yellow');

            // Start database transaction
            $this->db->transStart();

            try {
                // Create order record
                $orderId = $this->createOrder($orderData);

                // Update inventory
                $this->updateInventory($orderData['items']);

                // Process payment
                $this->processPayment($orderId, $orderData['payment']);

                // Commit transaction
                $this->db->transCommit();

                CLI::write('Transaction completed successfully', 'green');

                return $orderId;
            } catch (\Exception $e) {
                // Rollback on error
                $this->db->transRollback();

                throw $e;
            }
        });

        CLI::write('Critical section complete - signals restored', 'cyan');
        CLI::write("Order {$result} processed successfully", 'green');
    }
}

During critical sections, ALL signals (including Ctrl+Z) are blocked to prevent data corruption.

Pause and Resume

The SignalTrait supports proper Unix job control with custom handlers:

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;
use CodeIgniter\I18n\Time;

class SampleCommand extends BaseCommand
{
    public function run(array $params): int
    {
        // Register pause/resume signals with custom handlers
        $this->registerSignals(
            [SIGTERM, SIGINT, SIGTSTP, SIGCONT],
            [
                SIGTSTP => 'onPause',
                SIGCONT => 'onResume',
            ],
        );

        while ($this->isRunning()) {
            $this->processWork();
            sleep(2);
        }

        return EXIT_SUCCESS;
    }

    protected function onPause(int $signal): void
    {
        CLI::write('Pausing - saving current date...', 'yellow');

        // Save current timestamp
        $state = [
            'timestamp' => Time::now()->getTimestamp(),
        ];

        file_put_contents(WRITEPATH . 'app_state.json', json_encode($state));

        CLI::write('State saved. Process will now suspend.', 'green');
    }

    protected function onResume(int $signal): void
    {
        CLI::write('Resuming - restoring...', 'green');

        $file = WRITEPATH . 'app_state.json';

        // Restore saved state
        if (file_exists($file)) {
            $state = json_decode(file_get_contents($file), true);
            $date  = Time::createFromTimestamp($state['timestamp'])->format('Y-m-d H:i:s');

            CLI::write('Restored from ' . $date, 'cyan');
        }

        CLI::write('Resuming normal operation...', 'green');
    }
}

# RECOMMENDED: Use shell job control
php spark my:command
# Press Ctrl+Z to suspend
fg  # Resume - maintains terminal control

# PROBLEMATIC: Manual signal sending
php spark my:command &
kill -TSTP $PID   # Suspend
kill -CONT $PID   # Resume - may lose terminal control

Triggering Signals

# Get the process ID
php spark long:running:command &
echo $!  # Shows PID, e.g., 12345

# Send different signals
kill -TERM 12345   # Graceful shutdown
kill -INT 12345    # Interrupt (same as Ctrl+C)
kill -HUP 12345    # Hangup
kill -USR1 12345   # User-defined signal 1
kill -USR2 12345   # User-defined signal 2

# Pause and resume
kill -TSTP 12345   # Suspend (same as Ctrl+Z)
kill -CONT 12345   # Resume (same as fg)

php spark long:command     # Run in foreground
# Press Ctrl+Z to suspend
bg                         # Move to background
fg                         # Bring back to foreground
jobs                       # List suspended jobs

Debugging Signals

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class SampleCommand extends BaseCommand
{
    // ...

    protected function debugProcessState(): void
    {
        $state = $this->getProcessState();

        CLI::write('=== PROCESS DEBUG INFO ===', 'yellow');
        CLI::write('PID: ' . $state['pid'], 'cyan');
        CLI::write('Running: ' . ($state['running'] ? 'YES' : 'NO'), 'cyan');
        CLI::write('PCNTL Available: ' . ($state['pcntl_available'] ? 'YES' : 'NO'), 'cyan');
        CLI::write('Signals Registered: ' . $state['registered_signals'], 'cyan');
        CLI::write('Signal Names: ' . implode(', ', $state['registered_signals_names']), 'cyan');
        CLI::write('Explicit Mappings: ' . $state['explicit_mappings'], 'cyan');
        CLI::write('Signals Blocked: ' . ($state['signals_blocked'] ? 'YES' : 'NO'), 'cyan');
        CLI::write('Memory Usage: ' . $state['memory_usage_mb'] . ' MB', 'cyan');
        CLI::write('Peak Memory: ' . $state['memory_peak_mb'] . ' MB', 'cyan');

        // POSIX info (if available)
        if (isset($state['session_id'])) {
            CLI::write('Session ID: ' . $state['session_id'], 'cyan');
            CLI::write('Process Group: ' . $state['process_group'], 'cyan');
            CLI::write('Has Terminal: ' . ($state['has_controlling_terminal'] ? 'YES' : 'NO'), 'cyan');
        }

        CLI::write('========================', 'yellow');
    }
}

Class Reference

trait CodeIgniter\CLI\SignalTrait

registerSignals($signals = [SIGTERM, SIGINT, SIGHUP, SIGQUIT], $methodMap = [])

Parameters:

• $signals (array) – List of signals to handle

• $methodMap (array) – Optional signal-to-method mapping

Return type:

void

Register signal handlers with optional custom method mapping.

<?php

// Basic signal registration
$this->registerSignals();

// Register specific signals
$this->registerSignals([SIGTERM, SIGINT]);

// Register signals with custom method mapping
$this->registerSignals(
    [SIGTERM, SIGINT, SIGUSR1],
    [
        SIGTERM => 'handleGracefulShutdown',
        SIGUSR1 => 'handleReload',
    ],
);

Note

Requires the PCNTL extension. On Windows, signal handling is automatically disabled.

isRunning()

Returns:

true if the process should continue running, false if not

Return type:

bool

Check if the process should continue running (not terminated).

<?php

use CodeIgniter\CLI\CLI;

// Main application loop
while ($this->isRunning()) {
    // Process work items
    $this->processNextItem();

    // Small delay to prevent CPU spinning
    usleep(100000); // 0.1 seconds
}

CLI::write('Process terminated gracefully.');

shouldTerminate()

Returns:

true if termination has been requested, false if not

Return type:

bool

Check if termination has been requested (opposite of isRunning()).

<?php

use CodeIgniter\CLI\CLI;

// Check for termination before expensive operations
if ($this->shouldTerminate()) {
    CLI::write('Termination requested, skipping file processing.');

    return;
}

// Process large file
foreach ($largeDataSet as $item) {
    // Check periodically during long operations
    if ($this->shouldTerminate()) {
        CLI::write('Termination requested during processing.');
        break;
    }

    $this->processItem($item);
}

requestTermination()

Return type:

void

Manually request process termination.

<?php

use CodeIgniter\CLI\CLI;

// Request termination based on conditions
if ($errorCount > $this->maxErrors) {
    CLI::write("Too many errors ({$errorCount}), requesting termination.", 'red');
    $this->requestTermination();

    return;
}

resetState()

Return type:

void

Reset all states - useful for testing or restart scenarios.

withSignalsBlocked($operation)

Parameters:

• $operation (callable) – The critical operation to execute without interruption

Returns:

The result of the operation

Return type:

mixed

Execute a critical operation with ALL signals blocked to prevent ANY interruption.

Note

This blocks ALL interruptible signals including termination signals (SIGTERM, SIGINT), pause/resume signals (SIGTSTP, SIGCONT), and custom signals (SIGUSR1, SIGUSR2). Only SIGKILL (unblockable) can still terminate the process.

areSignalsBlocked()

Returns:

true if signals are currently blocked, false if not

Return type:

bool

Check if signals are currently blocked.

mapSignal($signal, $method)

Parameters:

• $signal (int) – Signal constant

• $method (string) – Method name to call for this signal

Return type:

void

Add or update signal-to-method mapping at runtime.

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;
use CodeIgniter\CLI\SignalTrait;

class SampleCommand extends BaseCommand
{
    use SignalTrait;
    public function run(array $params): int
    {
        // Register signals first
        $this->registerSignals([SIGTERM, SIGINT, SIGUSR1, SIGUSR2]);

        // Map signals to specific methods at runtime
        $this->mapSignal(SIGUSR1, 'handleReload');
        $this->mapSignal(SIGUSR2, 'handleStatusDump');
    }

    // Custom signal handlers
    public function handleReload(int $signal): void
    {
        CLI::write('Received reload signal, reloading configuration...');
        $this->reloadConfig();
    }

    public function handleStatusDump(int $signal): void
    {
        CLI::write('=== Process Status ===');
        $this->printStatus($this->getProcessState());
    }
}

getSignalName($signal)

Parameters:

• $signal (int) – Signal constant

Returns:

Human-readable signal name

Return type:

string

Get human-readable name for a signal constant.

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;
use CodeIgniter\CLI\SignalTrait;

class SampleCommand extends BaseCommand
{
    use SignalTrait;

    public function run(array $params): int
    {
        // ...
    }

    // Log signal information
    public function onInterruption(int $signal): void
    {
        $signalName = $this->getSignalName($signal);
        CLI::write("Received signal: {$signalName} ({$signal})", 'yellow');
    }
}

hasSignals()

Returns:

true if any signals are registered, false if not

Return type:

bool

Check if any signals are registered.

getSignals()

Returns:

Array of registered signal constants

Return type:

array

Get array of registered signal constants.

getProcessState()

Returns:

Comprehensive process state information

Return type:

array

Get comprehensive process state information including process ID, memory usage, signal handling status, and terminal control information.

<?php

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;
use CodeIgniter\CLI\SignalTrait;

class SampleCommand extends BaseCommand
{
    use SignalTrait;

    public function run(array $params): int
    {
        // ...
    }

    // Debug process state
    public function debugProcessState(): void
    {
        $state = $this->getProcessState();

        CLI::write('=== Process Debug Information ===');
        CLI::write("PID: {$state['pid']}");
        CLI::write('Running: ' . ($state['running'] ? 'Yes' : 'No'));
        CLI::write("Memory Usage: {$state['memory_usage_mb']} MB");
        CLI::write("Peak Memory: {$state['memory_peak_mb']} MB");
        CLI::write('Registered Signals: ' . implode(', ', $state['registered_signals_names']));
        CLI::write('Signals Blocked: ' . ($state['signals_blocked'] ? 'Yes' : 'No'));
    }
}

unregisterSignals()

Return type:

void

Unregister all signals and clean up resources.

Note

This removes all signal handling behavior for all previously registered signals.