Repository files navigation

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 aftersome database changes or feature updates.

This package is for you if...

• you regularly need toupdate specific data after you deployed new code
• you often execute jobs justonly one single time after a deployment
• you sometimesforget to execute that one specific job and stuff gets crazy
• your code getscluttered with jobs, that are not being used anymore
• your co-workers always need to be reminded toexecute that one job after some database changes
• you often seed or process datain a migration file (which is a big no-no!)

Require this package with composer:

composer require timokoerber/laravel-one-time-operations

Create the required table in your database:

php artisan migrate

Now you're all set!

Create new operation file:

php artisan operations:make<operation_name>

Create file without any attributes:

php artisan operations:make<operation_name> -e|--essential

Use command alias to create operation file:

php artisan make:operation<operation_name>

Process all new operation files:

php artisan operations:process

Force synchronous execution:

php artisan operations:process --sync

Force asynchronous execution:

php artisan operations:process --async

Test mode (don't flag operations as processed):

php artisan operations:process --test

Run command isolated:

php artisan operations:process --isolated

Force a specific queue for the job:

php artisan operations:process --queue=<name>

Only process operations with a specific tag:

php artisan operations:process --tag=<tagname>

Re-run one specific operation:

php artisan operations:process<operation_name>

Show all operations:

php artisan operations:show

Show pending operations:

php artisan operations:show pending

Show processed operations:

php artisan operations:show processed

Show disposed operations:

php artisan operations:show disposed

Use multiple filters to show operations:

php artisan operations:show pending processed disposed

TheOne-Time Operations work exactly likeLaravel Migrations.Just process the operationsafter your code was deployed and the migrations were migrated.You can make it part of your deployment script like this:

... - php artisan migrate - php artisan operations:process...

By default, the following elements will be created in your project:

• the tableoperations in your database
• the directoryoperations in your project root directory

If you want to use a different settings just publish and edit the config file:

php artisan vendor:publish --provider="TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider"

This will create the fileconfig/one-time-operations.php with the following content.

// config/one-time-operation.phpreturn ['directory' =>'operations','table' =>'operations',];

Make changes as you like.

To create a new operation file execute the following command:

php artisan operations:make AwesomeOperation

This will create a file likeoperations/XXXX_XX_XX_XXXXXX_awesome_operation.php with the following content.

<?php// operations/XXXX_XX_XX_XXXXXX_awesome_operation.phpuseTimoKoerber\LaravelOneTimeOperations\OneTimeOperation;returnnewclassextends OneTimeOperation{/**     * Determine if the operation is being processed asynchronously.     */protectedbool$async =true;/**     * The queue that the job will be dispatched to.     */protectedstring$queue ='default';/**     * A tag name, that this operation can be filtered by.     */protected ?string$tag =null;/**     * Process the operation.     */publicfunctionprocess():void    {//    }};

Provide your code in theprocess() method, for example:

// operations/XXXX_XX_XX_XXXXXX_awesome_operation.phppublicfunctionprocess():void{    User::where('active',1)->update(['status' =>'awesome'])// make active users awesome}

By default, the operation is being processedasynchronously (based on your configuration) by dispatching the jobOneTimeOperationProcessJob.By default, the operation is being dispatched to thedefault queue of your project. Change the$queue as you wish.

You can also execute the code synchronously by setting the$async flag tofalse.(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!).

If you don't need all the available attributes for your operation, you can create acleaner operation file with the--essential or-e option:

php artisan operations:make AwesomeOperation --essentialphp artisan operations:make AwesomeOperation -e

You can provide a custom class layout in/stubs/one-time-operation.stub, which will be used to create a new operation file.

Use the following call to process all new operation files.

php artisan operations:process

Your code will be executed, and you will find all the processed operations in theoperations table:

After that, this operation will not be processed anymore.

For each operation aOneTimeOperationProcessJob is being dispatched,either withdispatch() oderdispatchSync() based on the$async attribute in the operation file.

By providing the--sync or--async option with theoperations:process command, you can force a synchronously/asynchronously execution and ignore the attribute:

php artisan operations:process --async  // forcedispatch()php artisan operations:process --sync   // forcedispatchSync()

Hint! Ifoperation:process is part of your deployment process, it isnot recommended to process the operations synchronously,since an error in your operation could make your whole deployment fail.

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.

php artisan operations:process --queue=redis  // force redis queue

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).

php artisan operations:process --isolated

You can provide the$tag attribute in your operation file:

<?php// operations/XXXX_XX_XX_XXXXXX_awesome_operation.phpprotected ?string$tag ="awesome";};

That way you can filter operations with this specific tag when processing the operations:

php artisan operations:process --tag=awesome  // run only operations with"awesome" tag

This is quite usefull if, for example, you want to process some of your operations before and some after the migrations:

 - php artisan operations:process --tag=before-migrations  - php artisan migrate - php artisan operations:process

You can also provide multiple tags:

php artisan operations:process --tag=awesome --tag=foobar // run only operations with"awesome" or"foobar" tag

Hint!operations:process (without tags) still processesall operations, even if they have a tag.

If something went wrong (or if you just feel like it), you can process an operation again by providing thename of the operation as parameter inoperations:process.

php artisan operations:process XXXX_XX_XX_XXXXXX_awesome_operation

You might want to test your code a couple of times before flagging the operation as "processed". Provide the--test flag to run the command again and again.

php artisan operations:process --test

So you don't have to check the database or the directory for the existing operations,you can show a list withoperations:show.Filter the list with the available filterspending,processed anddisposed.

• pending - Operations, that have not been processed yet
• processed - Operations, that have been processed
• disposed - Operations, that have been processed and the files were already deleted

php artisan operations:show pending           // show only pending operationsphp artisan operations:show pending disposed  // show only pending and disposed operations

The whole idea of this package is, that you can dispose the operations once they were executed, so your project won't be cluttered with files and code, you won't be using anymore.

So you just need todelete the files from your repository

The deleted operations will be shown asDISPOSED when you calloperations:show, so you still have a history on all the processed operations.

composer test

Copyright © Timo Körber |www.timokoerber.com

"One-Time Operations for Laravel" is open-sourced software licensed under theMIT license.