{"id":13620362,"url":"https://github.com/ash-jc-allen/laravel-executor","last_synced_at":"2025-04-05T11:10:50.855Z","repository":{"id":41144598,"uuid":"237113840","full_name":"ash-jc-allen/laravel-executor","owner":"ash-jc-allen","description":"Configurable code that can be run when installing and updating your web app.","archived":false,"fork":false,"pushed_at":"2021-08-31T17:46:41.000Z","size":79,"stargazers_count":255,"open_issues_count":0,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T10:09:03.802Z","etag":null,"topics":["hacktoberfest","laravel"],"latest_commit_sha":null,"homepage":"","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/ash-jc-allen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"ash-jc-allen"}},"created_at":"2020-01-30T01:00:13.000Z","updated_at":"2025-03-27T01:12:34.000Z","dependencies_parsed_at":"2022-07-18T08:13:47.248Z","dependency_job_id":null,"html_url":"https://github.com/ash-jc-allen/laravel-executor","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Flaravel-executor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Flaravel-executor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Flaravel-executor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Flaravel-executor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ash-jc-allen","download_url":"https://codeload.github.com/ash-jc-allen/laravel-executor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"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":["hacktoberfest","laravel"],"created_at":"2024-08-01T21:00:55.011Z","updated_at":"2025-04-05T11:10:50.814Z","avatar_url":"https://github.com/ash-jc-allen.png","language":"PHP","funding_links":["https://github.com/sponsors/ash-jc-allen"],"categories":["PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://ashallendesign.co.uk/images/custom/laravel-executor-logo.png\" width=\"500\"\u003e\n\u003c/p\u003e \n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/laravel-executor\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ashallendesign/laravel-executor.svg?style=flat-square\" alt=\"Latest Version on Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.com/ash-jc-allen/laravel-executor\"\u003e\u003cimg src=\"https://img.shields.io/travis/ash-jc-allen/laravel-executor/master.svg?style=flat-square\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/laravel-executor\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/ashallendesign/laravel-executor.svg?style=flat-square\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/laravel-executor\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/ashallendesign/laravel-executor?style=flat-square\" alt=\"PHP from Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/ash-jc-allen/laravel-executor/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/ash-jc-allen/laravel-executor?style=flat-square\" alt=\"GitHub license\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n    - [Requirements](#requirements)\n    - [Install the Package](#install-the-package)\n- [Usage](#usage)\n    - [Creating an Executor](#creating-an-executor)\n        - [Creating a New Executor](#creating-a-new-executor)\n        - [Creating an Executor with a Command](#creating-an-executor-with-a-command)\n    - [Updating an Executor](#updating-an-executor)\n        - [Adding an Artisan Command](#adding-an-artisan-command)\n        - [Adding a Command](#adding-a-command)\n        - [Adding a Closure](#adding-a-closure)\n        - [Adding Desktop Notifications](#adding-desktop-notifications)\n        - [Pinging a URL](#pinging-a-url)\n    - [Running the Executors](#running-the-executors)\n        - [Running via the Console](#running-via-the-console)\n        - [Running Manually](#running-manually)\n- [Examples](#examples)\n- [Security](#security)\n- [Contribution](#contribution)\n- [Credits](#credits)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Overview\n\nA Laravel package that simplifies running code and commands when installing or updating your web app.\n\n## Installation\n\n### Requirements\nThe package has been developed and tested to work with the following minimum requirements:\n\n- PHP 7.2\n- Laravel 6\n\n### Install the Package\nYou can install the package via Composer:\n\n```bash\ncomposer require ashallendesign/laravel-executor\n```\n\n## Usage\n### Creating an Executor\n#### Creating a New Executor\nTo create a new Executor, you can use the following command:\n\n```bash\nphp artisan make:executor YourExecutorNameHere\n```\n\nThe above command would create an Executor named ``` YourExecutorNameHere ``` that can be found in the ``` app/Executor ```\nfolder.\n\n#### Creating an Executor with a Command\nGenerally, Executors are expected to be run within a console. So, when creating a new Executor, if you intend for it to\nbe run in the console, you can use the following command:\n\n```bash\nphp artisan make:executor YourExecutorNameHere -c\n```\n\nThe command above will create the exact same boilerplate for your new Executor as the command in [Creating a New Executor](#creating-a-new-executor).\nHowever, it will create a new command in your ``` app/Commands ``` folder named ``` RunYourExecutorNameHereExecutor ```.\nThis means that you won't need a new command manually to run your executor.\n\nLearn more in [Running via the Console](#running-via-the-console) to find out how to run the Executor inside the commands.\n\n### Updating an Executor\n#### Adding an Artisan Command\nTo run an Artisan command via your Executor class, you can add the ``` runArtisan() ``` method to your Executor's ``` run() ```\nmethod. For example, the code below shows how you could set the Executor to run the built-in Laravel ``` php artisan cache:clear ```\ncommand:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003erunArtisan('cache:clear');\n    }\n}\n```\n\nIn some cases, you may want to run a command that requires your input. For example, you might have a command that\ncreates a new user in the database and need you to input some details. In this case, you can pass ``` true ``` as the second\nparameter to the ``` -\u003erunArtisan() ``` method to specify that it is an interactive command.\n\nTo determine the process timeout for the command, you can also pass a time in seconds as the third parameter to the\n``` -\u003erunArtisan() ``` method.\n\n#### Adding a Command\nTo run a command (that can't be run with Artisan) via your Executor class, you can add the ``` runExternal() ``` method to your Executor's ``` run() ```\nmethod. For example, the code below shows how you could set the Executor to run the built-in Composer ``` composer install ```\ncommand:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003erunExternal('composer install');\n    }\n}\n```\n\nIn some cases, you may want to run a command that requires your input. For example, you might have a command that\ncreates a new user in the database and need you to input some details. In this case, you can pass ``` true ``` as the second\nparameter to the ``` -\u003erunExternal() ``` method to specify that it is an interactive command.\n\nTo determine the process timeout for the command, you can also pass a time in seconds as the third parameter to the\n``` -\u003erunExternal() ``` method.\n\n\n#### Adding a Closure\nSometimes you might want to run some code that doesn't necessarily fit into an existing command. In this case, you can add a closure\nto your Executor instead. The example below shows how to pass a simple closure to your Executor class:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003erunClosure(function () {\n            return 'I am running inside a closure.';\n        });\n    }\n}\n```\n\n#### Adding Desktop Notifications\n\nIf you are running your Executor via the console, you may want to display desktop notifications between some steps. To display\na desktop notification you can use either ``` -\u003esimpleDesktopNotification() ``` or ``` -\u003edesktopNotification() ```.\n\nBy using ``` -\u003esimpleDesktopNotification() ``` you can pass just a title and body that should be displayed. The example below\nshows how to create a simple desktop notification:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003esimpleDesktopNotification('Notification title', 'Notification body');\n    }\n}\n```\n\nIf you want to customise your notification, you can use ``` -\u003edesktopNotification() ``` and pass a ``` Joli\\JoliNotif\\Notification ```\nobject as the parameter. For more information on building these types of notifications, check out the [``` Joli\\JoliNotif ```\ndocumentation here](https://github.com/jolicode/JoliNotif).\n\nYou can also add the ``` -\u003ecompleteNotification() ``` to your Executor so that a desktop notification can be displayed\nonce all the code inside the class has been run.\n\n#### Pinging a URL\n\nIf you're using your Executor for updating your application on a live server, you might want to ping a URL when it's finished.\nThis could be useful for sending a webhook to alert you that the scripts have run successfully. To ping a URL, you can simply\nuse the ``` -\u003eping() ``` method.\n\nThe example below shows how to ping a website:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003eping('https://ashallendesign.co.uk/executor-webhook-route');\n    }\n}\n```\n\nIf you want to send headers in your ``` ping() ```, you can pass them as a second parameter. This can be useful for if you\nwant to add a signature to your webhook requests to assert that they've been sent from an authorised sender.\n\nThe example below shows how to ping a website with headers:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003eping('https://ashallendesign.co.uk/executor-webhook-route', [\n            'X-Webhook-Signature' =\u003e 'secret-signature-to-go-here'\n        ]);\n    }\n}\n```\n\n### Running the Executors\n#### Running via the Console\nAs mentioned above, Executors are mainly intended for being run from within the console. This makes them ideal for adding\nto deploy scripts; such as the ones that can be found one Laravel Forge and Runcloud.\n\nIf you created a command at the same time as the Executor class by using the command above found in [Creating an Executor with a Command](#creating-an-executor-with-a-command),\nyour command will already have been given a signature. The signature is created by converting the Executor's classname into kebab case.\nFor example, an Executor with the name ``` AppInstall ``` will be given the command signature of ``` executor:app-install ```.\n\nThe example below shows how a command (that has been unaltered) can be run the ``` AppInstall ``` Executor:\n\n```bash\nphp artisan executor:app-install\n```\n\nNote: To register the command with your Laravel application, you will want to add the command class name to the ``` $commands``` array in your\n``` app/Console/Kernel.php ``` file.\n\n#### Running manually\nThere may be times when you want to run an Executor class outside of the command line. To do this, you simply need to call\nthe ``` -\u003erun() ``` method on your class. The example below shows how to manually run an Executor named ``` AppInstall ```:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse App\\Executor\\AppInstall;\n\nclass Controller\n{\n    public function index()\n    {\n        (new AppInstall())-\u003erun();\n    }\n}\n```\n\n## Examples\nThe example below shows how to create an Executor class that can be run after pulling a new branch of project down from\na remote repository:\n\n```php\n\u003c?php\n\nnamespace App\\Executor;\n\nuse AshAllenDesign\\LaravelExecutor\\Classes\\Executor;\n\nclass AppUpdate extends Executor\n{\n    public function run(): Executor\n    {\n        return $this-\u003esimpleDesktopNotification('Starting Executor', 'Starting the AppUpdate Executor.')\n                    -\u003erunExternal('composer install')\n                    -\u003erunArtisan('migrate')\n                    -\u003erunArtisan('cache:clear')\n                    -\u003ecompleteNotification();\n    }\n}\n```\n\nAssuming that the above Executor class is still using the default command signature, each time the branch is pulled down,\nthe following command could be run: ``` php artisan executor:app-update ```.\n\nThe image below shows how a simple Executor command could be run. It's only executing ``` composer du -o ``` but demonstrates\nhow Laravel Executor can provide feedback with real-time output and desktop notifications.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://ashallendesign.co.uk/images/custom/executor-desktop-notification.gif\"\u003e\n\u003c/p\u003e\n\n## Security\n\nIf you find any security related issues, please contact me directly at [mail@ashallendesign.co.uk](mailto:mail@ashallendesign.co.uk) to report it.\n\n## Contribution\n\nIf you wish to make any changes or improvements to the package, feel free to make a pull request.\n\nNote: A contribution guide will be added soon.\n\n## Credits\n\n- [Ash Allen](https://ashallendesign.co.uk)\n- [Ahmad Masabni](https://github.com/masabni)\n- [Jess Pickup](https://jesspickup.co.uk) (Logo)\n- [All Contributors](https://github.com/ash-jc-allen/laravel-executor/graphs/contributors)\n\n## Changelog\n\nCheck the [CHANGELOG](CHANGELOG.md) to get more information about the latest changes.\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%2Fash-jc-allen%2Flaravel-executor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fash-jc-allen%2Flaravel-executor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fash-jc-allen%2Flaravel-executor/lists"}