Repository files navigation

A package to write Shell scripts like Blade Components and run them locally or on a remote server. Support for running tasks in the background and test assertions. Built upon theProcess feature in Laravel.

❤️ We proudly support the community by developing Laravel packages and giving them away for free. If this package saves you time or if you're relying on it professionally, please considersponsoring the maintenance and development and check out our latest premium package:Inertia Table. Keeping track of issues and pull requests takes time, but we're happy to help!

This package requires Laravel 11 and PHP 8.2 or higher. You can install the package via composer:

composer require protonemedia/laravel-task-runner

Optionally, you can publish the config file with:

php artisan vendor:publish --provider="ProtoneMedia\LaravelTaskRunner\ServiceProvider"

You may use the Artisanmake:task command to create aTask class:

php artisan make:task ComposerGlobalUpdate

This will generate two files:app/Tasks/ComposerGlobalUpdate.php andresources/views/tasks/composer-global-update.blade.php.

Once you've added your script to the Blade template, you may run it on your local machine by calling thedispatch() method:

ComposerGlobalUpdate::dispatch();

Alternatively, if you don't want a separate Blade template, you may use the--class option (or-c):

php artisan make:task ComposerGlobalUpdate -c

This allows you to specify the script inline:

class ComposerGlobalUpdateextends Task{publicfunctionrender():string    {return'composer global update';    }}

Thedispatch() method returns an instance ofProcessOutput, which can return the output and exit code:

$output = ComposerGlobalUpdate::dispatch();$output->getBuffer();$output->getExitCode();$output->getLines();// returns the buffer as an array$output->isSuccessful();// returns true when the exit code is 0$output->isTimeout();// returns true on a timeout

To interact with the underlyingProcessResult, you may call thegetIlluminateResult() method:

$output->getIlluminateResult();

Just like Blade Components, the public properties and methods of the Task class are available in the template:

class GetFileextends Task{publicfunction__construct(publicstring$path)    {    }publicfunctionoptions()    {return'-n';    }}

Blade template:

cat{{ $options()}}{{$path}}

You can create a new instance of the Task using the staticmake() method:

GetFile::make('/etc/hosts')->dispatch();

You may specify a timeout. By default, the timeout is based on thetask-runner.default_timeout config value.

class ComposerGlobalUpdateextends Task{protectedint$timeout =60;}

You may run a task in the background:

ComposerGlobalUpdate::inBackground()->dispatch();

It allows you to write the output to a file, as thedispatch() method won't return anything when the Task is still running in the background.

ComposerGlobalUpdate::inBackground()    ->writeOutputTo(storage_path('script.output'))    ->dispatch();

In thetask-runner configuration file, you may specify one or more remote servers:

return ['connections' => [// 'production' => [//     'host' => '',//     'port' => '',//     'username' => '',//     'private_key' => '',//     'private_key_path' => '',//     'passphrase' => '',//     'script_path' => '',// ],    ],];

Now you may call theonConnection() method before calling other methods:

ComposerGlobalUpdate::onConnection('production')->dispatch();ComposerGlobalUpdate::onConnection('production')->inBackground()->dispatch();

You may call thefake() method to prevent tasks from running and make assertions after acting:

useProtoneMedia\LaravelTaskRunner\Facades\TaskRunner;/** @test */publicfunctionit_updates_composer_globally(){    TaskRunner::fake();$this->post('/api/composer/global-update');    TaskRunner::assertDispatched(ComposerGlobalUpdate::class);}

You may also use a callback to investigate the Task further:

TaskRunner::assertDispatched(function (ComposerGlobalUpdate$task) {return$task->foo ==='bar';});

If you type-hint the Task withPendingTask, you may verify the configuration:

useProtoneMedia\LaravelTaskRunner\PendingTask;TaskRunner::assertDispatched(ComposerGlobalUpdate::class,function (PendingTask$task) {return$task->shouldRunInBackground();});TaskRunner::assertDispatched(ComposerGlobalUpdate::class,function (PendingTask$task) {return$task->shouldRunOnConnection('production');});

To fake just some of the tasks, you may call thefake() method with a class or array of classes:

TaskRunner::fake(ComposerGlobalUpdate::class);TaskRunner::fake([ComposerGlobalUpdate::class]);

Alternatively, you may fake everything except a specific task:

TaskRunner::fake()->dontFake(ComposerGlobalUpdate::class);

You may also supply a fake Task output:

TaskRunner::fake([    ComposerGlobalUpdate::class =>'Updating dependencies']);

Or use theProcessOutput class to set the exit code as well:

useProtoneMedia\LaravelTaskRunner\ProcessOutput;TaskRunner::fake([    ComposerGlobalUpdate::class => ProcessOutput::make('Updating dependencies')->setExitCode(1);]);

When you specify the Task output, you may also prevent unlisted Tasks from running:

TaskRunner::preventStrayTasks();

Please seeCHANGELOG for more information what has changed recently.

Please seeCONTRIBUTING for details.

• Inertia Table: The Ultimate Table for Inertia.js with built-in Query Builder.
• Laravel Blade On Demand: Laravel package to compile Blade templates in memory.
• Laravel Cross Eloquent Search: Laravel package to search through multiple Eloquent models.
• Laravel Eloquent Scope as Select: Stop duplicating your Eloquent query scopes and constraints in PHP. This package lets you re-use your query scopes and constraints by adding them as a subquery.
• Laravel FFMpeg: This package provides an integration with FFmpeg for Laravel. The storage of the files is handled by Laravel's Filesystem.
• Laravel MinIO Testing Tools: Run your tests against a MinIO S3 server.
• Laravel Mixins: A collection of Laravel goodies.
• Laravel Paddle: Paddle.com API integration for Laravel with support for webhooks/events.
• Laravel Verify New Email: This package adds support for verifying new email addresses: when a user updates its email address, it won't replace the old one until the new one is verified.
• Laravel XSS Protection: Laravel Middleware to protect your app against Cross-site scripting (XSS). It sanitizes request input, and it can sanatize Blade echo statements.

If you discover any security related issues, please emailpascal@protone.media instead of using the issue tracker.

• Pascal Baljet
• All Contributors

The MIT License (MIT). Please seeLicense File for more information.