PHPackages                             protonemedia/laravel-task-runner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. protonemedia/laravel-task-runner

ActiveLibrary[Utility & Helpers](/categories/utility)

protonemedia/laravel-task-runner
================================

Write Shell scripts like Blade Components and run them locally or on a remote server

1.7.0(2mo ago)1325.5k↓50%7[1 PRs](https://github.com/protonemedia/laravel-task-runner/pulls)1MITPHPPHP ^8.2|^8.3|^8.4|^8.5CI passing

Since May 1Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/protonemedia/laravel-task-runner)[ Packagist](https://packagist.org/packages/protonemedia/laravel-task-runner)[ Docs](https://github.com/protonemedia/laravel-task-runner)[ RSS](/packages/protonemedia-laravel-task-runner/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (9)Versions (14)Used By (1)

Laravel Task Runner
===================

[](#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](https://laravel.com/docs/10.x/processes) in Laravel.

[![Latest Version on Packagist](https://camo.githubusercontent.com/424260d5aa0822e65bd6a33224ffd6918fc8714e20ccec5d56ff2bf86447ab19/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70726f746f6e656d656469612f6c61726176656c2d7461736b2d72756e6e65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/protonemedia/laravel-task-runner)[![run-tests](https://github.com/protonemedia/laravel-task-runner/actions/workflows/run-tests.yml/badge.svg)](https://github.com/protonemedia/laravel-task-runner/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/0ad037d347cc97c7d881998ad57bca39ec5f896a0a1b4433e0697d6269b2a6f5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f70726f746f6e656d656469612f6c61726176656c2d7461736b2d72756e6e65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/protonemedia/laravel-task-runner)[![Buy us a tree](https://camo.githubusercontent.com/130148911f548b001b2ac68a32c0a06559977ca60ada3bf480c72ae4ea093175/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54726565776172652d2546302539462538432542332d6c69676874677265656e)](https://plant.treeware.earth/protonemedia/laravel-task-runner)

Sponsor Us
----------

[](#sponsor-us)

[![](https://camo.githubusercontent.com/b5348f68e9a1a6ff90432d75a6692be1d604b3320ce1fcabd4b1ef29668053c4/68747470733a2f2f696e657274696175692e636f6d2f76697369742d636172642e6a7067)](https://inertiaui.com/inertia-table?utm_source=github&utm_campaign=laravel-task-runner)

❤️ 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](https://github.com/sponsors/pascalbaljet) and check out our latest premium package: [Inertia Table](https://inertiaui.com/inertia-table?utm_source=github&utm_campaign=laravel-task-runner). Keeping track of issues and pull requests takes time, but we're happy to help!

Installation
------------

[](#installation)

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"
```

Basic usage
-----------

[](#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
-----------

[](#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
----------------

[](#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
------------

[](#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
-----------------

[](#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
----------------------------

[](#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' => '',
        //     'private_key_path' => '',
        //     '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
--------------------

[](#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
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Other Laravel packages
----------------------

[](#other-laravel-packages)

- [Inertia Modal](https://inertiaui.com/inertia-modal/docs/introduction): With Inertia Modal, you can easily open any route in a Modal or Slideover without having to change anything about your existing routes or controllers.

- [`Inertia Table`](https://inertiaui.com/inertia-table?utm_source=github&utm_campaign=laravel-task-runner): The Ultimate Table for Inertia.js with built-in Query Builder.
- [`Laravel Blade On Demand`](https://github.com/protonemedia/laravel-blade-on-demand): Laravel package to compile Blade templates in memory.
- [`Laravel Cross Eloquent Search`](https://github.com/protonemedia/laravel-cross-eloquent-search): Laravel package to search through multiple Eloquent models.
- [`Laravel Eloquent Scope as Select`](https://github.com/protonemedia/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`](https://github.com/protonemedia/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`](https://github.com/protonemedia/laravel-minio-testing-tools): Run your tests against a MinIO S3 server.
- [`Laravel Mixins`](https://github.com/protonemedia/laravel-mixins): A collection of Laravel goodies.
- [`Laravel Paddle`](https://github.com/protonemedia/laravel-paddle): Paddle.com API integration for Laravel with support for webhooks/events.
- [`Laravel Verify New Email`](https://github.com/protonemedia/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`](https://github.com/protonemedia/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.

Security
--------

[](#security)

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

Credits
-------

[](#credits)

- [Pascal Baljet](https://github.com/protonemedia)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance91

Actively maintained with recent releases

Popularity37

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 59.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~113 days

Recently: every ~178 days

Total

10

Last Release

80d ago

PHP version history (5 changes)1.0.0PHP ^8.1|^8.2

1.3.0PHP ^8.1|^8.2|^8.3

1.4.0PHP ^8.2|^8.3

1.5.0PHP ^8.2|^8.3|^8.4

1.7.0PHP ^8.2|^8.3|^8.4|^8.5

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8403149?v=4)[Pascal Baljet](/maintainers/pascalbaljet)[@pascalbaljet](https://github.com/pascalbaljet)

---

Top Contributors

[![pascalbaljet](https://avatars.githubusercontent.com/u/8403149?v=4)](https://github.com/pascalbaljet "pascalbaljet (42 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (17 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (11 commits)")[![ruchit288](https://avatars.githubusercontent.com/u/28095255?v=4)](https://github.com/ruchit288 "ruchit288 (1 commits)")

---

Tags

laravellaravel-bladelaravel-packagesymfony-processlaravelprotonemedialaravel-task-runner

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/protonemedia-laravel-task-runner/health.svg)

```
[![Health](https://phpackages.com/badges/protonemedia-laravel-task-runner/health.svg)](https://phpackages.com/packages/protonemedia-laravel-task-runner)
```

###  Alternatives

[spatie/laravel-data

Create unified resources and data transfer objects

1.7k28.9M626](/packages/spatie-laravel-data)[worksome/exchange

Check Exchange Rates for any currency in Laravel.

123544.7k](/packages/worksome-exchange)[spatie/laravel-screenshot

Take screenshots of web pages in Laravel apps

7615.9k2](/packages/spatie-laravel-screenshot)[ralphjsmit/livewire-urls

Get the previous and current url in Livewire.

82270.3k4](/packages/ralphjsmit-livewire-urls)[marcelweidum/filament-expiration-notice

Customize the livewire expiration notice

9169.0k4](/packages/marcelweidum-filament-expiration-notice)[hydrat/filament-table-layout-toggle

Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts.

6292.3k1](/packages/hydrat-filament-table-layout-toggle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)