Skip to main content
NativePHP Desktop provides a powerful API for spawning and managing child processes, allowing you to run background tasks, execute system commands, and manage long-running processes.

​
Starting Processes

​
PHP Processes

Run a PHP script as a child process: 
use Native\Desktop\Facades\ChildProcess;

$process = ChildProcess::php(
    cmd: 'worker.php',
    alias: 'background-worker'
);
With custom environment variables: 
$process = ChildProcess::php(
    cmd: 'worker.php',
    alias: 'background-worker',
    env: [
        'WORKER_TYPE' => 'email',
        'QUEUE_NAME' => 'emails'
    ]
);

​
Artisan Commands

Run Laravel Artisan commands: 
$process = ChildProcess::artisan(
    cmd: 'queue:work',
    alias: 'queue-worker'
);
With arguments: 
$process = ChildProcess::artisan(
    cmd: ['queue:work', '--queue=high', '--tries=3'],
    alias: 'queue-worker'
);

​
Node.js Processes

Run Node.js scripts: 
$process = ChildProcess::node(
    cmd: 'server.js',
    alias: 'node-server',
    env: ['PORT' => '3000']
);

​
System Commands

Execute any system command: 
$process = ChildProcess::start(
    cmd: ['ffmpeg', '-i', 'input.mp4', 'output.mp4'],
    alias: 'video-converter',
    cwd: storage_path('app/videos')
);

​
Process Management

​
Getting Process Information

Retrieve a process by its alias: 
$process = ChildProcess::get('queue-worker');

if ($process) {
    $pid = $process->pid;
    $alias = $process->alias;
    $cmd = $process->cmd;
}
Get all running processes: 
$processes = ChildProcess::all();

foreach ($processes as $alias => $process) {
    echo "{$alias}: PID {$process->pid}\n";
}

​
Stopping Processes

Stop a specific process: 
ChildProcess::stop('queue-worker');
Or stop from the process instance: 
$process = ChildProcess::get('queue-worker');
$process->stop();

​
Restarting Processes

Restart a process with its original configuration: 
$process = ChildProcess::restart('queue-worker');

​
Persistent Processes

Mark a process as persistent so it automatically restarts if it crashes: 
$process = ChildProcess::artisan(
    cmd: 'queue:work',
    alias: 'queue-worker',
    persistent: true
);
Persistent processes will automatically restart if they exit unexpectedly, making them ideal for queue workers and other critical background tasks.

​
Process Communication

Send messages to a running process: 
$process = ChildProcess::get('background-worker');
$process->message('process-item-123');

​
PHP Configuration

Customize PHP ini settings for PHP processes: 
$process = ChildProcess::php(
    cmd: 'memory-intensive-task.php',
    alias: 'heavy-worker',
    iniSettings: [
        'memory_limit' => '512M',
        'max_execution_time' => '300'
    ]
);

​
Working Directory

Set the working directory for a process: 
$process = ChildProcess::start(
    cmd: ['npm', 'run', 'build'],
    alias: 'npm-build',
    cwd: base_path('resources/frontend')
);

​
Practical Examples

use Native\Desktop\Facades\ChildProcess;

class QueueManager
{
    public function startWorker($queue = 'default')
    {
        $alias = "queue-worker-{$queue}";
        
        // Check if already running
        if (ChildProcess::get($alias)) {
            return;
        }

        ChildProcess::artisan(
            cmd: ['queue:work', "--queue={$queue}"],
            alias: $alias,
            persistent: true,
            iniSettings: [
                'memory_limit' => '256M'
            ]
        );
    }

    public function stopWorker($queue = 'default')
    {
        ChildProcess::stop("queue-worker-{$queue}");
    }

    public function restartWorker($queue = 'default')
    {
        ChildProcess::restart("queue-worker-{$queue}");
    }

    public function getAllWorkers()
    {
        $all = ChildProcess::all();
        
        return array_filter($all, function ($alias) {
            return str_starts_with($alias, 'queue-worker-');
        }, ARRAY_FILTER_USE_KEY);
    }
}

​
Process Properties

Each process instance has the following properties:
  • pid - Process ID
  • alias - Unique identifier for the process
  • cmd - Command array that was executed
  • cwd - Working directory
  • env - Environment variables
  • persistent - Whether the process auto-restarts
  • iniSettings - PHP ini settings (PHP processes only)

​
Best Practices

1
Use Descriptive Aliases
2
Give your processes clear, descriptive aliases that make them easy to identify and manage.
3
Monitor Process Health
4
Regularly check if critical processes are running and restart them if needed.
5
Clean Up Processes
6
Stop processes when they’re no longer needed to free up system resources.
7
Handle Process Failures
8
Implement error handling and logging to track when processes fail or exit unexpectedly.
Be careful with persistent processes. If a process fails repeatedly, it will continue to restart, which could impact system performance.

Build docs developers (and LLMs) love

Get started for freeTalk to us