Quite often, when working with operations, it becomes necessary to run one or another console command, and each time you have to write the following code:
To create an operation use the %command_make% artisan command:
The new operation's file will be placed in your
%directory% directory in the base path of your app.
Each operation file name contains a timestamp, which allows Laravel to determine the order of the operations. For example,
--quiet parameter.
When calling the %command_run% console command without passing a name in the name parameter,
you will be asked for a name for the file.
You can enter your own or simply press Enter to continue.
In this case, automatic file name generation will be applied
If you do not specify the name attribute,
then the file name will be generated automatically according to the rule:
The name for the file will be automatically obtained from the currently active git repository branch at the root of the project.
If the branch name cannot be determined, the word “auto” will be used.
You can use nested paths to create operations:
All of these commands will create a file called %directory%/foo/bar/Y_m_d_His_qwe_rty.php.
For example:
By default, the new operation class will contain the __invoke method,
but you can easily replace it with public up name.
Note that the __invoke method has been added as a single call.
This means that when the operation is running, it will be called, but not when it is rolled back.
You should also pay attention to the fact that if there is an __invoke method in the class,
the down method will not be called.
You can also use the dependency injection with __invoke, up and
down methods:
You may publish the stub used by the make:operation command and/or
Laravel Idea plugin for
JetBrains PhpStorm if you want to modify it.
This will create the file stubs/deploy-operation.stub, which you can modify to suit you.
As you build your application, you may accumulate more and more migrations over time.
This can lead to your
database/migrations directory becoming bloated with potentially hundreds of migrations.
If you would like, you may "squash" your migrations into a single SQL file.
To get started, execute the schema:dump command:
You can read more about the operation of this console command in the Laravel documentation.
Here we mention this console command because operations tend to save the execution state in order to prevent re-runs where this is not explicitly allowed.
But if you run sequentially the console commands %artisan% schema:dump and
%artisan% migrate:fresh, you will see that all actions will be called again.
This is due to the fact that the dump mechanism saves the contents of just one table - migrations.
To solve this problem, there is a Database Data Dumper project that allows you to specify a list of tables required for export to a dump.
In addition to those that you can easily specify in its configuration file,
we recommend that you also specify the
operations database table from this project in order to save the state of the operations when performing a clean deployment of the database from a dump.
You can also handle events when executing operations:
If there are no operation files to execute, the NoPendingDeployOperations event will be sent.
In other cases, the DeployOperationStarted event will be sent before processing starts,
and the DeployOperationEnded event will be sent after processing.
For example:
It is also possible to subscribe to events manually:
You can also override the success and failed methods,
which are called on success or failure processing.
Call the %artisan% %command_run% command.
The log file will contain one success record.
Call the %artisan% %command_run% command.
The log file will contain one failed record.
The methods will work in the same way in conjunction with the __invoke magic method.
The only difference is that in this case the down method will not be executed.
To get the latest version of
If necessary, you can publish the configuration file by calling the console command:
Now you can
| PHP | Laravel | Package | Documentation | Status |
| ^8.2 | 11, 12, 13 | ^7.0 | ||
| ^8.2 | 10, 11, 12 | ^6.0 | Documentation | |
| ^8.2 | 10, 11 | ^5.0 | Documentation | |
| ^8.0 | 7, 8, 9, 10, 11 | ^4.0 | Documentation | |
| ^8.0 | 7, 8, 9 | ^3.0 | Documentation | |
| ^7.3, ^8.0 | 6, 7, 8, 9 | ^2.0 | --- | |
| ^7.3, ^8.0 | 6, 7, 8 | ^1.0 | --- |
To quickly call operations from other code, you can use the OperationHelper helper function.
This will execute any operations not performed earlier:
For example,
This will execute all previously unexecuted operations in the specified folder:
For example,
For example,
If you are using
JetBrains PhpStorm
with the
Laravel Idea plugin installed,
you can use the operation function to autocomplete.
The %command_status% command displays the execution status of operations.
In it you can see which operations were executed and which were not:
For example,
To roll back the latest operation, you may use the %command_rollback% command.
This command rolls back the last "batch" of operations, which may include multiple operation files:
You may roll back a limited number of operations by providing the
step option to the rollback command.
For example, the following command will roll back the last five operations:
For example:
The
%command_fresh% command will drop all operation records from the operation table and then execute the operations command:
To run all of your outstanding operations, execute the %command_run% artisan command:
The order in which operations are called is checked by file name in alphabetical order, without taking into account directory names:
If you are deploying your application across multiple servers and running operations as part of your deployment process,
you likely do not want two servers attempting to run the database at the same time.
To avoid this, you may use the isolated option when invoking the
%command_run% command.
Sometimes it becomes necessary to launch operations separately, for example, to notify about the successful deployment of a project.
There is a before option for this when calling operations:
When you call the %command_run% command with the before parameter,
the script will only perform operations for which the needBefore method is true.
For backwards compatibility, the needBefore method returns true by default,
but operations will only be executed if the option is explicitly passed.
For example, you need to call operations when deploying an application. Some operations should be run after the operations are deployed, and others after the application is fully launched.
To run, you need to pass the before parameter.
For example, when using
Deployer it would look like this:
Thus, when %command_run% is called, all operations whose
before parameter is true will be executed,
and after that, the remaining tasks will be executed.
%command_run% command without the before parameter,
then all tasks will be executed regardless of the value of the
needBefore method inside the operation class.
%command_status% and %command_run%.
Some operations are destructive, which means they may cause you to lose data.
In order to protect you from running these commands against your production database,
you will be prompted for confirmation before the commands are executed.
To force the commands to run without a prompt, use the --force flag:
In some cases, you need to call the code every time you deploy the application. For example, to call reindexing.
To do this, override the shouldOnce method in the operation file:
If the value is shouldOnce is false,
the up method will be called every time the %command_run% command called.
In this case, information about it will not be written to the
%table% table and, therefore, the
down method will not be called when the rollback command is called.
before parameter to run command,
it is recommended to override the value of the needBefore method to false,
otherwise this operation will be executed twice.
In some cases, it becomes necessary to execute an operation in a specific environment.
For example production.
For this you can override the shouldRun method:
You can also specify multiple environment names:
You can work with exceptions in the same way:
In some cases, it becomes necessary to undo previously performed operations in the database. For example, when code execution throws an error. To do this, the code must be wrapped in a transaction.
By setting the withinTransactions to true parameter,
you will ensure that your code is wrapped in a transaction without having to manually call the
DB::transaction() method.
This will reduce the time it takes to create the operation.
The number of code execution attempts in case of transaction errors is set in the settings file.
By default, the number of attempts is %transactions_attempts%.
In some cases, it becomes necessary to execute operations in an asynchronous manner without delaying the deployment process.
To do this, you need to override the shouldBeAsync method in the operation class:
In this case, the operation file that defines this parameter will run asynchronously using the
DragonCode\LaravelDeployOperations\Jobs\OperationJob job.
The name of the connection and queue can be changed through the settings.
Operations can also be invoked when Laravel migrations are completed (php artisan migrate).
The Laravel event system is used for this purpose.
To do this, add a withOperation public method to your migration file that
will return the name of the file or folder to call.
For example:
Now, once the migration is done, Laravel will send a MigrationEnded event, catching which the
%artisan% %command_run% console command will be called passing this parameter.
The same thing will happen if you invoke the following console command:
This method works with all three migration methods: up, down and
__invoke.
When the %artisan% migrate console command is called,
the operation will call the up or __invoke method.
When the %artisan% migrate:rollback console command is called,
the operation will call the down method if it exists in the operation file.
If you are using JetBrains PhpStorm with the Laravel Idea plugin installed, then autocomplete will be available to you:
To avoid entering file names manually, you can use the operation helper function.
All it does is to suggest IDE paths to operation files with recursive search.
Then you need to update the dependencies:
dragon-code/contracts) support was endedFor your convenience, we have created an upgrade console command:
It will do the following:
up method with __invoke if the class does not have a
down method
snake_case to camelCaseDeploy Actions for Laravel now requires PHP 8.0.2 or greater.
You should update the following dependency in your application's composer.json file:
Publish the config file and migrate the settings from the config/database.php file to
config/actions.php.
actions folder in the project root,
or update the actions.path option in the configuration file.
DragonCode\LaravelActions\Support\Actionable with
DragonCode\LaravelActions\Action.
Replace named calls to your application's classes with anonymous ones.
For example:
down method, then you can replace the up method with
__invoke.
%artisan% migrate command to make changes to the action repository table.
Make sure all overridden properties are typed:
| New Name | Old Name |
| protected bool $once | protected $once |
| protected bool $transactions | protected $transactions |
| protected int $transactionAttempts | protected $transaction_attempts |
| protected string\|array\|null $environment | protected $environment |
| protected string\|array\|null $exceptEnvironment | protected $except_environment |
| protected bool $before | protected $before |
Before:
After:
For your convenience, we have created an `upgrade` console command:
It will do the following:
You should update the following dependency in your application's composer.json file:
Replace:
with:
| New Name | Old Name |
| %artisan% make:action | %artisan% make:migration:action |
| %artisan% actions | %artisan% migrate:actions |
| %artisan% actions:install | %artisan% migrate:actions:install |
| %artisan% actions:fresh | %artisan% migrate:actions:fresh |
| %artisan% actions:refresh | %artisan% migrate:actions:refresh |
| %artisan% actions:reset | %artisan% migrate:actions:reset |
| %artisan% actions:rollback | %artisan% migrate:actions:rollback |
| %artisan% actions:status | %artisan% migrate:actions:status |
| %artisan% actions:upgrade | %artisan% migrate:actions:upgrade |
DragonCode\LaravelActions\Constants\Names::MIGRATE
with DragonCode\LaravelActions\Constants\Names::ACTIONS
The new table name is `actions`.
You can also specify any name in the application settings file.
If you are using Laravel 10, then you need to install the dependency:
You should update the following dependencies in your application's composer.json file:
For your convenience, we have created an operations:upgrade console command:
It will do the following:
Please note that the script allows you to automate most of the actions, but may not complete them completely. Therefore, you will need to manually check the result of the upgrade by checking this guide.
You should change the package name in the composer.json file from
dragon-code/laravel-actions to
dragon-code/laravel-deploy-operations, and also change its version to ^6.0:
The namespace has been changed from DragonCode\LaravelActions to
DragonCode\LaravelDeployOperations.
DragonCode\LaravelActions\Action namespace with
DragonCode\LaravelDeployOperations\Operation.
| New Name | Old Name |
| make:operation | make:action |
| operations | actions |
| operations:fresh | actions:fresh |
| operations:install | actions:install |
| operations:refresh | actions:refresh |
| operations:reset | actions:reset |
| operations:rollback | actions:rollback |
| operations:status | actions:status |
| operations:stub | actions:stub |
| operations:upgrade | actions:upgrade |
| New Name | Old Name |
| DeployOperationStarted | ActionStarted |
| DeployOperationEnded | ActionEnded |
| DeployOperationFailed | ActionFailed |
| NoPendingDeployOperations | NoPendingActions |
Don't forget to also change the namespace from DragonCode\LaravelActions\Events to
DragonCode\LaravelDeployOperations\Events.
The type of the method property for events has been changed.
We recommend that you delete the old configuration file
config/actions.php and publish a new one.
This way you will see the changes made to it.
If you use package constant references, you must also rename them.
The old name was in UPPER_CASE, the new one was in PascalCase.
For example:
/operations from /actions.
The following properties have been removed:
$transactions$transactionAttempts
Instead, you can use the hasTransactions and transactionAttempts methods.
The enabledTransactions method has been renamed to hasTransactions.
$async property has been removed from the base class.
You can use the previously available isAsync method instead.
stubs/action.stub to
stubs/deploy-operation.stub and make changes to its structure.
The %artisan% operations:stub console command has been removed. Use another command instead:
You should update the following dependencies in your application's composer.json file:
php artisan operations:upgrade console command.
It does not exist now.
php artisan operations:refresh console command.
It does not exist now.
php artisan operations:reset console command.
It does not exist now.
A strict typification has been added to all the project files.
The DragonCode\LaravelDeployOperations\Helpers\ConfigHelper class has been removed and
DragonCode\LaravelDeployOperations\Data\Config\ConfigData, which is a Data object, is now used instead.
For example,
This tidied up the handling of settings and options.
If you used a direct reference to the Helpers/Config and
Values/Options classes, update your code.
The following properties and methods have been removed from the
DragonCode\LaravelDeployOperations\Operation
class: