diff --git a/resources/views/docs/1/digging-deeper/child-process.md b/resources/views/docs/1/digging-deeper/child-process.md index 1c47e21a..8db38476 100644 --- a/resources/views/docs/1/digging-deeper/child-process.md +++ b/resources/views/docs/1/digging-deeper/child-process.md @@ -7,13 +7,22 @@ order: 700 Child Processes allow your application to spin up managed processes, forked from your app's main process. This is great for long-running processes that you want to interact with repeatedly during the life of your application. - + Child Processes can be managed from your application using a straightforward API. When your app quits, these processes get shut down gracefully. "Spawning" a Child Process is like running a command from the CLI. Any command you can run in the terminal can be a Child Process. +```php +ChildProcess::start( + cmd: 'tail -f storage/logs/laravel.log', + alias: 'tail' +); +``` + +Any process invoked using the ChildProcess facade will be non-blocking and keep running in the background. Even if the request that triggered it has finished. + **Bear in mind that your Child Process ("command line") arguments may need to differ depending on which platform your application is running on (Mac/Linux vs Windows).** @@ -26,10 +35,12 @@ application. --- ## Alternatives + Before deciding to use a Child Process, consider the alternatives available to you. You should pick the most appropriate for the problem you're trying to solve: ### Queues + The [queue runner](queues) is useful for very simply offloading _Laravel_ tasks to the background. Each task must be a Laravel queued [Job](https://laravel.com/docs/queues#creating-jobs). @@ -37,6 +48,7 @@ Any queued jobs that don't get processed before your app is quit, will get proce queue runner) starts again. ### Scheduler + The Laravel scheduler runs as normal (every minute) inside a NativePHP application. You can add [scheduled tasks](https://laravel.com/docs/scheduling) to your application just as you normally would, to have them run on a regular schedule. @@ -47,16 +59,18 @@ Any scheduled tasks that would have run while your application isn't running wil only be able to run while your application is running.** ### `shell_exec`, `proc_open` etc + PHP has good built-in support for running arbitrary programs in separate processes. For example: -- [`shell_exec`](https://www.php.net/manual/en/function.shell-exec.php) allows you to run commands and return their -output to your application. -- [`proc_open`](https://www.php.net/manual/en/function.proc-open.php) allows you to spin up a command with more control -over how its input and output streams are handled. +- [`shell_exec`](https://www.php.net/manual/en/function.shell-exec.php) allows you to run commands and return their + output to your application. +- [`proc_open`](https://www.php.net/manual/en/function.proc-open.php) allows you to spin up a command with more control + over how its input and output streams are handled. While these can be used in your NativePHP application, consider that they: -- May block the script that is executing them until the sub-process has finished. -- May become orphaned from your application, allowing them to continue running after your app has quit. + +- May block the script that is executing them until the sub-process has finished. +- May become orphaned from your application, allowing them to continue running after your app has quit. Runaway orphaned processes could negatively impact your user's system and can become tricky to manage without user intervention. You should be cautious about starting processes this way. @@ -64,6 +78,7 @@ intervention. You should be cautious about starting processes this way. --- ## Starting a Child Process + Each Child Process must have a unique alias. This is the name you will use to reference and interact with this process throughout your application. @@ -73,7 +88,7 @@ You may start a process using the `ChildProcess` facade: use Native\Laravel\Facades\ChildProcess; ChildProcess::start( - cmd: 'tail -n50 storage/logs/laravel.log', + cmd: 'tail -f storage/logs/laravel.log', alias: 'tail' ); ``` @@ -89,26 +104,28 @@ may fail for a number of reasons. [`ProcessSpawned` event](#codeprocessspawnedcode).** ### Current Working Directory + By default, the child process will use the working directory of your application as it's "current working directory" (`cwd`). However, you can explicitly change this if needed by passing a string path to the `$cwd` parameter of the `start` method: ```php ChildProcess::start( - cmd: ['tail', '-n50', 'logs/laravel.log'], + cmd: ['tail', '-f', 'logs/laravel.log'], alias: 'tail', cwd: storage_path() ); ``` ### Persistent Processes + You may mark a process as `persistent` to indicate that the runtime should make sure that once it has been started it is always running. This works similarly to tools like [`supervisord`](http://supervisord.org/), ensuring that the process gets booted up again in case it crashes. ```php ChildProcess::start( - cmd: ['tail', '-n50', 'logs/laravel.log'], + cmd: ['tail', '-f', 'logs/laravel.log'], alias: 'tail', persistent: true ); @@ -116,9 +133,26 @@ ChildProcess::start( **The only way to stop a persistent process is for your application to quit.** +### PHP scripts + +For your convenience, NativePHP provides a simple method to execute PHP scripts in the background using NativePHP's packaged PHP binary: + +```php +ChildProcess::php('path/to/script.php', alias: 'script'); +``` + +### Artisan commands + +NativePHP provides a similar method convenience for Artisan commands: + +```php +ChildProcess::artisan('smtp:serve', alias: 'smtp-server'); +``` + ## Getting running processes ### Getting a single process + You can use the `ChildProcess` facade's `get` method to get a running process with a given alias: ```php @@ -128,25 +162,68 @@ $tail = ChildProcess::get('tail'); This will return a `Native\Laravel\ChildProcess` instance. ### Getting all processes + You can use the `ChildProcess` facade's `all` method to get all running processes: ```php -$tail = ChildProcess::all(); +$processes = ChildProcess::all(); ``` This will return an array of `Native\Laravel\ChildProcess` instances. +## Stopping a Child Process + +Your child processes will shut down when your application exits. However, you may also choose to stop them manually or +provide this control to your user. + +If you have a `Native\Laravel\ChildProcess` instance, you may call the `stop` method on it: + +```php +$tail->stop(); +``` + +Alternatively, you may use the `ChildProcess` facade to stop a process via its alias: + +```php +ChildProcess::stop('tail'); +``` + +This will attempt to stop the process gracefully. The [`ProcessExited`](#codeprocessexitedcode) event will be +dispatched if the process exits. + +Note that [persistent processes](/docs/1/digging-deeper/child-process#persistent-processes) will restart even when you +stop them manually. The only way to stop a persistent process is by quitting the application. + +## Restarting a Child Process + +As a convenience, you may simply restart a Child Process using the `restart` method. This may be useful in cases where +the program has become unresponsive and you simply need to "reboot" it. + +If you have a `Native\Laravel\ChildProcess` instance, you may call the `restart` method on it: + +```php +$tail->stop(); +``` + +Alternatively, you may use the `ChildProcess` facade to restart a process via its alias: + +```php +ChildProcess::restart('tail'); +``` + ## Sending input + There are multiple ways to provide input to your Child Process: -- The environment. -- Arguments to the command. -- Its standard input stream (`STDIN`). -- A custom interface, e.g. a network socket. +- The environment. +- Arguments to the command. +- Its standard input stream (`STDIN`). +- A custom interface, e.g. a network socket. Which you use will depend on what the program is capable of handling. ### Environment + Child Processes will inherit the environment available to your application by default. If needed, you can provide extra environment variables when starting the process via the `$env` parameter of the `start` method: @@ -161,17 +238,19 @@ ChildProcess::start( ``` ### Command line arguments + You can pass arguments to the program via the `$cmd` parameter of the `start` method. This accepts a `string` or an `array`, whichever you prefer to use: ```php ChildProcess::start( - cmd: ['tail', '-n50', 'storage/logs/laravel.log'], + cmd: ['tail', '-f', 'storage/logs/laravel.log'], alias: 'tail' ); ``` ### Messaging a Child Process + You may send messages to a running child process's standard input stream (`STDIN`) using the `message` method: ```php @@ -187,98 +266,72 @@ ChildProcess::message('Hello, world!', 'tail'); The message format and how they are handled will be determined by the program you're running. ## Handling output + A Child Process may send output via any of the following interfaces: -- Its standard output stream (`STDOUT`). -- Its standard error stream (`STDERR`). -- A custom interface, e.g. a network socket. +- Its standard output stream (`STDOUT`). +- Its standard error stream (`STDERR`). +- A custom interface, e.g. a network socket. +- Broadcasting a Custom Event + +`STDOUT`, `STDERR` & [Custom Events](/docs/1/digging-deeper/broadcasting#custom-events) are dispatched using +Laravel's event system. + +You may listen to these events by registering a listener in your app service provider, or on the front end +using the [Native helper](/docs/1/digging-deeper/broadcasting#listening-with-javascript). + +Please see the [Events](#events) section for a full list of events. ### Listening for Output (`STDOUT`) + You may receive standard output for a process by registering an event listener for the [`MessageReceived`](#codemessagereceivedcode) event: -```php -use Illuminate\Support\Facades\Event; -use Native\Laravel\Events\ChildProcess\MessageReceived; - -Event::listen(MessageReceived::class, function (MessageReceived $event) { - if ($event->alias === 'tail') { - info($event->data); - } -}); -``` - ### Listening for Errors (`STDERR`) + You may receive standard errors for a process by registering an event listener for the [`ErrorReceived`](#codeerrorreceivedcode) event: -```php -use Illuminate\Support\Facades\Event; -use Native\Laravel\Events\ChildProcess\ErrorReceived; - -Event::listen(ErrorReceived::class, function (ErrorReceived $event) { - if ($event->alias === 'tail') { - info($event->data); - } -}); -``` - -## Stopping a Child Process -Your child processes will shut down when your application exits. However, you may also choose to stop them manually or -provide this control to your user. - -If you have a `Native\Laravel\ChildProcess` instance, you may call the `stop` method on it: - -```php -$tail->stop(); -``` - -Alternatively, you may use the `ChildProcess` facade to stop a process via its alias: - -```php -ChildProcess::stop('tail'); -``` - -This will attempt to stop the process gracefully. The [`ProcessExited`](#codeprocessexitedcode) event will be -dispatched if the process exits. +## Events -## Restarting a Child Process -As a convenience, you may simply restart a Child Process using the `restart` method. This may be useful in cases where -the program has become unresponsive and you simply need to "reboot" it. +NativePHP provides a simple way to listen for Child Process events. -If you have a `Native\Laravel\ChildProcess` instance, you may call the `restart` method on it: +All events get dispatched as regular Laravel events, so you may use your `AppServiceProvider` to register listeners. ```php -$tail->stop(); -``` +use Illuminate\Support\Facades\Event; +use Native\Laravel\Events\ChildProcess\MessageReceived; -Alternatively, you may use the `ChildProcess` facade to restart a process via its alias: +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Event::listen(MessageReceived::class, function(MessageReceived $event) { + if ($event->alias === 'tail') { + // + } + }); +} -```php -ChildProcess::restart('tail'); ``` -## Events - -NativePHP provides a simple way to listen for Child Process events. - -All events get dispatched as regular Laravel events, so you may use your `EventServiceProvider` to register listeners. +Sometimes you may want to listen and react to these events in real-time, which is why NativePHP also broadcasts all +Child Process events to the `nativephp` broadcast channel. Any events broadcasted this way also get dispatched over IPC, enabling you to react to them on the front-end without using websockets. -```php -protected $listen = [ - 'Native\Laravel\Events\ChildProcess\MessageReceived' => [ - 'App\Listeners\MainLoopEvent', - ], -]; +```js +Native.on("Native\\Laravel\\Events\\ChildProcess\\MessageReceived", (event) => { + if (event.alias === "tail") { + container.append(event.data); + } +}); ``` -Sometimes you may want to listen and react to these events in real-time, which is why NativePHP also broadcasts all -Child Process events to the `nativephp` broadcast channel. - To learn more about NativePHP's broadcasting capabilities, please refer to the [Broadcasting](/docs/digging-deeper/broadcasting) section. ### `ProcessSpawned` + This `Native\Laravel\Events\ChildProcess\ProcessSpawned` event will be dispatched when a Child Process has successfully been spawned. The payload of the event contains the `$alias` and the `$pid` of the process. @@ -286,15 +339,18 @@ been spawned. The payload of the event contains the `$alias` and the `$pid` of t process.** ### `ProcessExited` + This `Native\Laravel\Events\ChildProcess\ProcessExited` event will be dispatched when a Child Process exits. The payload of the event contains the `$alias` of the process and its exit `$code`. ### `MessageReceived` + This `Native\Laravel\Events\ChildProcess\MessageReceived` event will be dispatched when the Child Process emits some output via its standard output stream (`STDOUT`). The payload of the event contains the `$alias` of the process and the message `$data`. ### `ErrorReceived` + This `Native\Laravel\Events\ChildProcess\ErrorReceived` event will be dispatched when the Child Process emits an error via its standard error stream (`STDERR`). The payload of the event contains the `$alias` of the process and the error `$data`.