Laravel Task Runner

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 the Process feature in Laravel 10.

Sponsor this package

❤️ 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 consider sponsoring the maintenance and development. Keeping track of issues and pull requests takes time, but we're happy to help!

Laravel Splade

Did you hear about Laravel Splade? 🤩

It's the magic of Inertia.js with the simplicity of Blade. Splade provides a super easy way to build Single Page Applications using Blade templates. Besides that magic SPA-feeling, it comes with more than ten components to sparkle your app and make it interactive, all without ever leaving Blade.

Want to see this package in action?

Check out Eddy Server Management, our open-source solution for Server Provisioning and Zero-Downtime PHP Deployment!

Installation

This package requires Laravel 10 and PHP 8.1 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"

Basic usage

You may use the Artisan make:task command to create a Task class:

php artisan make:task ComposerGlobalUpdate

This will generate two files: app/Tasks/ComposerGlobalUpdate.php and resources/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 the dispatch() 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 ComposerGlobalUpdate extends Task
{
    public function render(): string
    {
        return 'composer global update';
    }
}

Task output

The dispatch() method returns an instance of ProcessOutput, 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 underlying ProcessResult, you may call the getIlluminateResult() method:

$output->getIlluminateResult();

Script variables

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

class GetFile extends Task
{
    public function __construct(public string $path)
    {
    }

    public function options()
    {
        return '-n';
    }
}

Blade template:

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

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

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

Task options

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

class ComposerGlobalUpdate extends Task
{
    protected int $timeout = 60;
}

Run in background

You may run a task in the background:

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

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

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

Run tasks on a remote server

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

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

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

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

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

Task test assertions

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

use ProtoneMedia\LaravelTaskRunner\Facades\TaskRunner;

/** @test */
public function it_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 with PendingTask, you may verify the configuration:

use ProtoneMedia\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 the fake() 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 the ProcessOutput class to set the exit code as well:

use ProtoneMedia\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();

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Other Laravel packages

• Laravel Analytics Event Tracking: Laravel package to easily send events to Google Analytics.
• 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 Dusk Fakes: Persistent Fakes for Laravel Dusk (Bus, Mail, Notifications, Queue).
• 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 Eloquent Where Not: This Laravel package allows you to flip/invert an Eloquent scope, or really any query constraint.
• Laravel Form Components: Blade components to rapidly build forms with Tailwind CSS Custom Forms and Bootstrap 4. Supports validation, model binding, default values, translations, includes default vendor styling and fully customizable!
• Laravel MinIO Testing Tools: This package provides a trait to 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 Splade: Splade provides a super easy way to build Single Page Applications using Blade templates. Besides that magic SPA-feeling, it comes with more than ten components to sparkle your app and make it interactive, all without ever leaving Blade.
• 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 WebDAV: WebDAV driver for Laravel's Filesystem.
• Laravel XSS Protection Middleware: Laravel Middleware to protect your app against Cross-site scripting (XSS). It sanitizes request input by utilising the Laravel Security package, and it can sanatize Blade echo statements as well.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Pascal Baljet
• All Contributors

License

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