Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/timokoerber/laravel-one-time-operations
Run operations once after deployment - just like you do it with migrations!
https://github.com/timokoerber/laravel-one-time-operations
cicd deployment dispatch jobs laravel laravel-framework migrations operations
Last synced: 3 days ago
JSON representation
Run operations once after deployment - just like you do it with migrations!
- Host: GitHub
- URL: https://github.com/timokoerber/laravel-one-time-operations
- Owner: TimoKoerber
- License: mit
- Created: 2023-03-10T18:23:54.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-23T13:32:26.000Z (29 days ago)
- Last Synced: 2024-12-05T04:03:47.669Z (17 days ago)
- Topics: cicd, deployment, dispatch, jobs, laravel, laravel-framework, migrations, operations
- Language: PHP
- Homepage:
- Size: 78.1 KB
- Stars: 527
- Watchers: 4
- Forks: 32
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# One-Time Operations for Laravel
Run operations once after deployment - just like you do it with migrations!
-----
**Take your CI/CD to the next Level with One-Time Operations for Laravel**! 🚀
Create specific classes for a one-time usage, that can be executed automatically after each deployment.
Same as migrations they get processed once and then never again. Perfect for seeding or updating some data instantly after
some database changes or feature updates.
This package is for you if...
- you regularly need to **update specific data** after you deployed new code
- you often execute jobs just **only one single time** after a deployment
- you sometimes **forget to execute** that one specific job and stuff gets crazy
- your code gets **cluttered with jobs**, that are not being used anymore
- your co-workers always need to be reminded to **execute that one job** after some database changes
- you often seed or process data **in a migration file** (which is a big no-no!)
## Installation
Require this package with composer:
```shell
composer require timokoerber/laravel-one-time-operations
```
Create the required table in your database:
```shell
php artisan migrate
```
Now you're all set!
## Commands
### Create operation files
Create new operation file:
```shell
php artisan operations:make
```
Create file without any attributes:
```shell
php artisan operations:make -e|--essential
```
Use command alias to create operation file:
```shell
php artisan make:operation
```
### Process operations
Process all new operation files:
```shell
php artisan operations:process
```
Force synchronous execution:
```shell
php artisan operations:process --sync
```
Force asynchronous execution:
```shell
php artisan operations:process --async
```
Test mode (don't flag operations as processed):
```shell
php artisan operations:process --test
```
Run command isolated:
```shell
php artisan operations:process --isolated
```
Force a specific queue for the job:
```shell
php artisan operations:process --queue=
```
Only process operations with a specific tag:
```shell
php artisan operations:process --tag=
```
Re-run one specific operation:
```shell
php artisan operations:process
```
### Show operations
Show all operations:
```shell
php artisan operations:show
```
Show pending operations:
```shell
php artisan operations:show pending
```
Show processed operations:
```shell
php artisan operations:show processed
```
Show disposed operations:
```shell
php artisan operations:show disposed
```
Use multiple filters to show operations:
```shell
php artisan operations:show pending processed disposed
```
## Tutorials
### CI/CD & Deployment-Process
The *One-Time Operations* work exactly like [Laravel Migrations](https://laravel.com/docs/9.x/migrations).
Just process the operations *after your code was deployed and the migrations were migrated*.
You can make it part of your deployment script like this:
```shell
...
- php artisan migrate
- php artisan operations:process
...
```
### Edit config
By default, the following elements will be created in your project:
- the table `operations` in your database
- the directory `operations` in your project root directory
If you want to use a different settings just publish and edit the config file:
```shell
php artisan vendor:publish --provider="TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider"
```
This will create the file `config/one-time-operations.php` with the following content.
```php
// config/one-time-operation.php
return [
'directory' => 'operations',
'table' => 'operations',
];
```
Make changes as you like.
### Create One-Time Operation files
To create a new operation file execute the following command:
```shell
php artisan operations:make AwesomeOperation
```
This will create a file like `operations/XXXX_XX_XX_XXXXXX_awesome_operation.php` with the following content.
```php
update(['status' => 'awesome']) // make active users awesome
}
```
By default, the operation is being processed ***asynchronously*** (based on your configuration) by dispatching the job `OneTimeOperationProcessJob`.
By default, the operation is being dispatched to the `default` queue of your project. Change the `$queue` as you wish.
You can also execute the code synchronously by setting the `$async` flag to `false`.
_(this is only recommended for small operations, since the processing of these operations should be part of the deployment process)_
**Hint:** If you use synchronous processing, the `$queue` attribute will be ignored (duh!).
### Create a cleaner operation file
If you don't need all the available attributes for your operation, you can create a *cleaner* operation file with the `--essential` or `-e` option:
```shell
php artisan operations:make AwesomeOperation --essential
php artisan operations:make AwesomeOperation -e
```
### Custom operation file
You can provide a custom class layout in `/stubs/one-time-operation.stub`, which will be used to create a new operation file.
### Processing the operations
Use the following call to process all new operation files.
```shell
php artisan operations:process
```
Your code will be executed, and you will find all the processed operations in the `operations` table:
| id | name | dispatched | processed_at |
|-----|-------------------------------------|------------|---------------------|
| 1 | XXXX_XX_XX_XXXXXX_awesome_operation | async | 2015-10-21 07:28:00 |
After that, this operation will not be processed anymore.
### Dispatching Jobs synchronously or asynchronously
For each operation a `OneTimeOperationProcessJob` is being dispatched,
either with `dispatch()` oder `dispatchSync()` based on the `$async` attribute in the operation file.
By providing the `--sync` or `--async` option with the `operations:process` command, you can force a synchronously/asynchronously execution and ignore the attribute:
```shell
php artisan operations:process --async // force dispatch()
php artisan operations:process --sync // force dispatchSync()
```
**Hint!** If `operation:process` is part of your deployment process, it is **not recommended** to process the operations synchronously,
since an error in your operation could make your whole deployment fail.
### Force different queue for all operations
You can provide the `--queue` option in the artisan call. The given queue will be used for all operations, ignoring the `$queue` attribute in the class.
```shell
php artisan operations:process --queue=redis // force redis queue
```
### Run commands isolated on Multi-Server Architecture
If you work with a Multi-Server Architecture you can use `--isolated` option to make sure to only run one instance of the command ([Laravel Isolatable Commands](https://laravel.com/docs/10.x/artisan#isolatable-commands)).
```shell
php artisan operations:process --isolated
```
### Run only operations with a given tag
You can provide the `$tag` attribute in your operation file:
```php