+
+ Information on how to create operations
+ Information on how to create operations
+ Information on how to create operations
+
+
+
+
+
+ To create an operation use the %command_make% artisan command:
+
+
+
+ %artisan% %command_make% some_name
+
+
+
+ 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,
+
+
+
+ 2025_04_02_121627_some_name.php
+
+
+
+
+
+ The question will not be asked when calling a console command passing the --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:
+
+
+
+
+
+
diff --git a/docs/topics/customize-stub.topic b/docs/topics/customize-stub.topic
new file mode 100644
index 00000000..6e41e198
--- /dev/null
+++ b/docs/topics/customize-stub.topic
@@ -0,0 +1,34 @@
+
+
+
+
+ Adding data from certain tables when executing the `php artisan schema:dump` console command
+ Adding data from certain tables when executing the `php artisan schema:dump` console command
+ Adding data from certain tables when executing the `php artisan schema:dump` console command
+
+
+
+
+ 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:
+
+
+
+ %artisan% schema:dump
+
+
+
+ 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.
+
+
+
+ composer require dragon-code/laravel-data-dumper --dev
+
+
diff --git a/docs/topics/events.topic b/docs/topics/events.topic
new file mode 100644
index 00000000..d810b47d
--- /dev/null
+++ b/docs/topics/events.topic
@@ -0,0 +1,43 @@
+
+
+
+
+ Information on how to roll back operations
+ Information on how to roll back operations
+ Information on how to roll back operations
+
+
+
+
+ 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:
+
+
+
+ %artisan% %command_rollback%
+
+
+
+ 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:
+
+
+
+ %artisan% %command_rollback% --step=5
+
+
+
+ The %command_reset% command will roll back all of your application's operations:
+
+
+
+ %artisan% %command_reset%
+
+
+
+ For example:
+
+
+
+
+
+
+ The
+ %command_refresh% command will roll back all of your operations and then execute the operations command.
+ This command effectively re-creates your entire database:
+
+
+
+ %artisan% %command_refresh%
+
+
+
+ You may roll back and re-run a limited number of operations by providing the step option to the
+ %command_refresh% command.
+ For example, the following command will roll back and re-run the last five operations:
+
+
+
+ %artisan% %command_refresh% --step=5
+
+
+
+
+
+ The
+ %command_fresh% command will drop all operation records from the operation table and then execute the operations command:
+
+
+
+ %artisan% %command_fresh%
+
+
+
diff --git a/docs/topics/running-operations.topic b/docs/topics/running-operations.topic
new file mode 100644
index 00000000..d3904972
--- /dev/null
+++ b/docs/topics/running-operations.topic
@@ -0,0 +1,266 @@
+
+
+
+
+ Information on how to invoke operations during a deployment
+ Information on how to invoke operations during a deployment
+ Information on how to invoke operations during a deployment
+
+
+
+
+
+
+ To run all of your outstanding operations, execute the %command_run% artisan command:
+
+
+
+ %artisan% %command_run%
+
+
+
+ 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.
+
+
+
+ %artisan% %command_run% --isolated
+
+
+
+
+
+ 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:
+
+
+
+ %artisan% %command_run% --before
+
+
+
+ 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.
+
+
+
+ If you call the %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.
+
+
+
+
+
+ Some commands cannot be executed in production without confirmation.
+ These include all commands except %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:
+
+
+
+ %artisan% %command_install% --force
+
+
+
+
+
+ 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.
+
+
+
+ When using the 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.
+
+
+
+
+
+ By default, the operation will run in all environments.
+
+
+
+ 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.
+
+
+
+ We remind you that in this case the
+ queuing system must work in your application.
+
+
+
+
+
+ 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:
+
+
+
+ %artisan% %command_run% --path="foo/2022_10_14_000002_test2"
+
+
+
+ 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.
+
+
+
diff --git a/docs/topics/snippets_composer.topic b/docs/topics/snippets_composer.topic
new file mode 100644
index 00000000..809718b8
--- /dev/null
+++ b/docs/topics/snippets_composer.topic
@@ -0,0 +1,19 @@
+
+
+
+
+ Guide for upgrading to version 6.x from 5.x
+ Guide for upgrading to version 6.x from 5.x
+ Guide for upgrading to version 6.x from 5.x
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ If you used inheritance of actions from other actions, then you will need to process these files manually.
+
+
+
+ For your convenience, we have created an operations:upgrade console command:
+
+
+
+ composer remove dragon-code/laravel-actions
+ composer require dragon-code/laravel-deploy-operations:^6.0
+
+ %artisan% operations:upgrade
+ %artisan% migrate
+
+
+
+ It will do the following:
+
+
+
+ Changing the old namespace of “actions” to a new one
+ Moves files to a new location
+ Updates the configuration file
+ Rename the stub file (if published)
+
+
+
+ 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:
+
+
+
+ {
+ "require": {
+ "dragon-code/laravel-deploy-operations": "^6.0"
+ }
+ }
+
+
+
+
+
+
+
+ The namespace has been changed from DragonCode\LaravelActions to
+ DragonCode\LaravelDeployOperations.
+
+
+ You need to replace it in all actions of your application, as well as when using
+ .
+
+
+
+ You should replace 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.
+
+
+
+
+ use DragonCode\LaravelActions\Events\ActionEnded;
+ use DragonCode\LaravelDeployOperations\Enums\MethodEnum;
+
+ /** @var ActionEnded */
+ $event->method; // is string
+
+
+
+
+
+ use DragonCode\LaravelDeployOperations\Enums\MethodEnum;
+ use DragonCode\LaravelDeployOperations\Events\DeployOperationEnded;
+
+ /** @var DeployOperationEnded */
+ $event->method; // is MethodEnum
+
+
+
+
+
+
+ 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.
+
+
+
+ %artisan% vendor:publish --provider="DragonCode\LaravelDeployOperations\ServiceProvider"
+
+
+
+
+
+ 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:
+
+
+
+ // Old
+ class Names
+ {
+ public const ACTIONS = 'actions';
+ public const FRESH = 'actions:fresh';
+ // ...
+ }
+
+
+ // New
+ class Names
+ {
+ public const Fresh = 'operations:fresh';
+ public const Operations = 'operations';
+ // ...
+ }
+
+
+
+
+ File storage directory changed to /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.
+
+
+
+
+ The $async property has been removed from the base class.
+ You can use the previously available isAsync method instead.
+
+
+
+ If you published a stub file, then you also need to rename it from 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:
+
+
+
+ %artisan% vendor:publish --tag=stubs --provider="DragonCode\LaravelDeployOperations\ServiceProvider"
+
+
+
diff --git a/docs/topics/upgrade-7.topic b/docs/topics/upgrade-7.topic
new file mode 100644
index 00000000..471f37e9
--- /dev/null
+++ b/docs/topics/upgrade-7.topic
@@ -0,0 +1,287 @@
+
+
+