{"id":18772889,"url":"https://github.com/protonemedia/laravel-task-runner","last_synced_at":"2025-04-07T17:09:32.722Z","repository":{"id":159666657,"uuid":"634773133","full_name":"protonemedia/laravel-task-runner","owner":"protonemedia","description":"A package to write Shell scripts like Blade Components and run them locally or on a remote server","archived":false,"fork":false,"pushed_at":"2024-03-25T06:28:14.000Z","size":53,"stargazers_count":118,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-12T22:33:54.413Z","etag":null,"topics":["laravel","laravel-blade","laravel-package","symfony-process"],"latest_commit_sha":null,"homepage":"https://protone.media/en/blog/introducing-laravel-task-runner-write-scripts-like-blade-components-and-run-them-anywhere","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/protonemedia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-05-01T06:33:39.000Z","updated_at":"2024-04-15T04:06:11.539Z","dependencies_parsed_at":"2024-03-12T12:47:53.105Z","dependency_job_id":"b713d543-3b15-4612-8444-773b6e9ab29a","html_url":"https://github.com/protonemedia/laravel-task-runner","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protonemedia%2Flaravel-task-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protonemedia%2Flaravel-task-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protonemedia%2Flaravel-task-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protonemedia%2Flaravel-task-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/protonemedia","download_url":"https://codeload.github.com/protonemedia/laravel-task-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","laravel-blade","laravel-package","symfony-process"],"created_at":"2024-11-07T19:31:31.945Z","updated_at":"2025-04-07T17:09:32.700Z","avatar_url":"https://github.com/protonemedia.png","language":"PHP","funding_links":["https://github.com/sponsors/pascalbaljet"],"categories":[],"sub_categories":[],"readme":"# Laravel Task Runner\n\nA 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.\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/protonemedia/laravel-task-runner.svg?style=flat-square)](https://packagist.org/packages/protonemedia/laravel-task-runner)\n[![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)\n[![Total Downloads](https://img.shields.io/packagist/dt/protonemedia/laravel-task-runner.svg?style=flat-square)](https://packagist.org/packages/protonemedia/laravel-task-runner)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/protonemedia/laravel-task-runner)\n\n## Sponsor Us\n\n[\u003cimg src=\"https://inertiaui.com/visit-card.jpg\" /\u003e](https://inertiaui.com/inertia-table?utm_source=github\u0026utm_campaign=laravel-task-runner)\n\n❤️ 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\u0026utm_campaign=laravel-task-runner). Keeping track of issues and pull requests takes time, but we're happy to help!\n\n## Installation\n\nThis package requires Laravel 11 and PHP 8.2 or higher. You can install the package via composer:\n\n```bash\ncomposer require protonemedia/laravel-task-runner\n```\n\nOptionally, you can publish the config file with:\n\n```bash\nphp artisan vendor:publish --provider=\"ProtoneMedia\\LaravelTaskRunner\\ServiceProvider\"\n```\n\n## Basic usage\n\nYou may use the Artisan `make:task` command to create a `Task` class:\n\n```bash\nphp artisan make:task ComposerGlobalUpdate\n```\n\nThis will generate two files: `app/Tasks/ComposerGlobalUpdate.php` and `resources/views/tasks/composer-global-update.blade.php`.\n\nOnce you've added your script to the Blade template, you may run it on your local machine by calling the `dispatch()` method:\n\n```php\nComposerGlobalUpdate::dispatch();\n```\n\nAlternatively, if you don't want a separate Blade template, you may use the `--class` option (or `-c`):\n\n```bash\nphp artisan make:task ComposerGlobalUpdate -c\n```\n\nThis allows you to specify the script inline:\n\n```php\nclass ComposerGlobalUpdate extends Task\n{\n    public function render(): string\n    {\n        return 'composer global update';\n    }\n}\n```\n\n## Task output\n\nThe `dispatch()` method returns an instance of `ProcessOutput`, which can return the output and exit code:\n\n```php\n$output = ComposerGlobalUpdate::dispatch();\n\n$output-\u003egetBuffer();\n$output-\u003egetExitCode();\n\n$output-\u003egetLines();    // returns the buffer as an array\n$output-\u003eisSuccessful();    // returns true when the exit code is 0\n$output-\u003eisTimeout();    // returns true on a timeout\n```\n\nTo interact with the underlying `ProcessResult`, you may call the `getIlluminateResult()` method:\n\n```php\n$output-\u003egetIlluminateResult();\n```\n\n## Script variables\n\nJust like Blade Components, the public properties and methods of the Task class are available in the template:\n\n```php\nclass GetFile extends Task\n{\n    public function __construct(public string $path)\n    {\n    }\n\n    public function options()\n    {\n        return '-n';\n    }\n}\n```\n\nBlade template:\n\n```blade\ncat {{ $options() }} {{ $path }}\n```\n\nYou can create a new instance of the Task using the static `make()` method:\n\n```php\nGetFile::make('/etc/hosts')-\u003edispatch();\n```\n\n## Task options\n\nYou may specify a timeout. By default, the timeout is based on the `task-runner.default_timeout` config value.\n\n```php\nclass ComposerGlobalUpdate extends Task\n{\n    protected int $timeout = 60;\n}\n```\n\n## Run in background\n\nYou may run a task in the background:\n\n```php\nComposerGlobalUpdate::inBackground()-\u003edispatch();\n```\n\nIt 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.\n\n```php\nComposerGlobalUpdate::inBackground()\n    -\u003ewriteOutputTo(storage_path('script.output'))\n    -\u003edispatch();\n```\n\n## Run tasks on a remote server\n\nIn the `task-runner` configuration file, you may specify one or more remote servers:\n\n```php\nreturn [\n    'connections' =\u003e [\n        // 'production' =\u003e [\n        //     'host' =\u003e '',\n        //     'port' =\u003e '',\n        //     'username' =\u003e '',\n        //     'private_key' =\u003e '',\n        //     'private_key_path' =\u003e '',\n        //     'passphrase' =\u003e '',\n        //     'script_path' =\u003e '',\n        // ],\n    ],\n];\n```\n\nNow you may call the `onConnection()` method before calling other methods:\n\n```php\nComposerGlobalUpdate::onConnection('production')-\u003edispatch();\n\nComposerGlobalUpdate::onConnection('production')-\u003einBackground()-\u003edispatch();\n```\n\n## Task test assertions\n\nYou may call the `fake()` method to prevent tasks from running and make assertions after acting:\n\n```php\nuse ProtoneMedia\\LaravelTaskRunner\\Facades\\TaskRunner;\n\n/** @test */\npublic function it_updates_composer_globally()\n{\n    TaskRunner::fake();\n\n    $this-\u003epost('/api/composer/global-update');\n\n    TaskRunner::assertDispatched(ComposerGlobalUpdate::class);\n}\n```\n\nYou may also use a callback to investigate the Task further:\n\n```php\nTaskRunner::assertDispatched(function (ComposerGlobalUpdate $task) {\n    return $task-\u003efoo === 'bar';\n});\n```\n\nIf you type-hint the Task with `PendingTask`, you may verify the configuration:\n\n```php\nuse ProtoneMedia\\LaravelTaskRunner\\PendingTask;\n\nTaskRunner::assertDispatched(ComposerGlobalUpdate::class, function (PendingTask $task) {\n    return $task-\u003eshouldRunInBackground();\n});\n\nTaskRunner::assertDispatched(ComposerGlobalUpdate::class, function (PendingTask $task) {\n    return $task-\u003eshouldRunOnConnection('production');\n});\n```\n\nTo fake just some of the tasks, you may call the `fake()` method with a class or array of classes:\n\n```php\nTaskRunner::fake(ComposerGlobalUpdate::class);\nTaskRunner::fake([ComposerGlobalUpdate::class]);\n```\n\nAlternatively, you may fake everything except a specific task:\n\n```php\nTaskRunner::fake()-\u003edontFake(ComposerGlobalUpdate::class);\n```\n\nYou may also supply a fake Task output:\n\n```php\nTaskRunner::fake([\n    ComposerGlobalUpdate::class =\u003e 'Updating dependencies'\n]);\n```\n\nOr use the `ProcessOutput` class to set the exit code as well:\n\n```php\nuse ProtoneMedia\\LaravelTaskRunner\\ProcessOutput;\n\nTaskRunner::fake([\n    ComposerGlobalUpdate::class =\u003e ProcessOutput::make('Updating dependencies')-\u003esetExitCode(1);\n]);\n```\n\nWhen you specify the Task output, you may also prevent unlisted Tasks from running:\n\n```php\nTaskRunner::preventStrayTasks();\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Other Laravel packages\n\n* [`Inertia Table`](https://inertiaui.com/inertia-table?utm_source=github\u0026utm_campaign=laravel-task-runner): The Ultimate Table for Inertia.js with built-in Query Builder.\n* [`Laravel Blade On Demand`](https://github.com/protonemedia/laravel-blade-on-demand): Laravel package to compile Blade templates in memory.\n* [`Laravel Cross Eloquent Search`](https://github.com/protonemedia/laravel-cross-eloquent-search): Laravel package to search through multiple Eloquent models.\n* [`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.\n* [`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.\n* [`Laravel MinIO Testing Tools`](https://github.com/protonemedia/laravel-minio-testing-tools): Run your tests against a MinIO S3 server.\n* [`Laravel Mixins`](https://github.com/protonemedia/laravel-mixins): A collection of Laravel goodies.\n* [`Laravel Paddle`](https://github.com/protonemedia/laravel-paddle): Paddle.com API integration for Laravel with support for webhooks/events.\n* [`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.\n* [`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.\n\n## Security\n\nIf you discover any security related issues, please email pascal@protone.media instead of using the issue tracker.\n\n## Credits\n\n* [Pascal Baljet](https://github.com/protonemedia)\n* [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotonemedia%2Flaravel-task-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotonemedia%2Flaravel-task-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotonemedia%2Flaravel-task-runner/lists"}