From 99267c3693ad452d508eb059270a0f05bfd785f7 Mon Sep 17 00:00:00 2001
From: Tom Scott-Malden <tom@skywire.co.uk>
Date: Fri, 10 Mar 2023 17:36:42 +0000
Subject: [PATCH] DD#0000: feat: Updated docs

---
 docs/recipe/magento2.md | 130 ++++++++++++++++++++++++----------------
 1 file changed, 79 insertions(+), 51 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index db112eb35..8a6357853 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -115,7 +115,7 @@ The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe.
 
 ## Configuration
 ### static_content_locales
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L23)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L25)
 
 By default setup:static-content:deploy uses `en_US`.
 To change that, simply put `set('static_content_locales', 'en_US de_DE');`
@@ -127,7 +127,7 @@ in you deployer script.
 
 
 ### magento_themes
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L40)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L42)
 
 You can also set the themes to run against. By default it'll deploy
 all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
@@ -151,14 +151,14 @@ set('magento_themes', [
 
 
 ### static_deploy_options
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L45)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L47)
 
 Static content deployment options, e.g. '--no-parent'
 
 
 
 ### split_static_deployment
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L48)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L50)
 
 Deploy frontend and adminhtml together as default
 
@@ -168,7 +168,7 @@ false
 
 
 ### static_content_locales_backend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L51)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L53)
 
 Use the default languages for the backend as default
 
@@ -178,7 +178,7 @@ Use the default languages for the backend as default
 
 
 ### magento_themes_backend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L55)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L57)
 
 backend themes to deploy. Only used if split_static_deployment=true
 This setting supports the same options/structure as [magento_themes](/docs/recipe/magento2.md#magento_themes)
@@ -189,7 +189,7 @@ This setting supports the same options/structure as [magento_themes](/docs/recip
 
 
 ### static_content_jobs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L61)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L63)
 
 Also set the number of conccurent jobs to run. The default is 1
 Update using: `set('static_content_jobs', '1');`
@@ -200,7 +200,7 @@ Update using: `set('static_content_jobs', '1');`
 
 
 ### content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L63)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L65)
 
 
 
@@ -210,7 +210,7 @@ return time();
 
 
 ### magento_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L68)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L70)
 
 Magento directory relative to repository root. Use "." (default) if it is not located in a subdirectory
 
@@ -220,7 +220,7 @@ Magento directory relative to repository root. Use "." (default) if it is not lo
 
 
 ### shared_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L71)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L73)
 
 Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recipe/deploy/shared.php`.
 
@@ -235,7 +235,7 @@ Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recip
 
 
 ### shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L75)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L77)
 
 Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
 
@@ -261,7 +261,7 @@ Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/
 
 
 ### writable_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L90)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L92)
 
 Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
 
@@ -279,7 +279,7 @@ Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `r
 
 
 ### clear_paths
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L97)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L99)
 
 Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `recipe/deploy/clear_paths.php`.
 
@@ -298,7 +298,7 @@ Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `re
 
 
 ### bin/magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L106)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L108)
 
 
 
@@ -308,7 +308,7 @@ Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `re
 
 
 ### magento_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L108)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L110)
 
 
 
@@ -321,7 +321,7 @@ return $matches[0] ?? '2.0';
 
 
 ### config_import_needed
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L115)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L117)
 
 
 :::info Autogenerated
@@ -332,7 +332,7 @@ The value of this configuration is autogenerated on access.
 
 
 ### database_upgrade_needed
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L129)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L131)
 
 
 :::info Autogenerated
@@ -343,7 +343,7 @@ The value of this configuration is autogenerated on access.
 
 
 ### enable_zerodowntime
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L144)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L146)
 
 Deploy without setting maintenance mode if possible
 
@@ -352,8 +352,18 @@ true
 ```
 
 
+### use_redis_cache_id
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L149)
+
+deploy with auto updating cache index_prefix
+
+```php title="Default value"
+false
+```
+
+
 ### artifact_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L330)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L335)
 
 The file the artifact is saved to
 
@@ -363,7 +373,7 @@ The file the artifact is saved to
 
 
 ### artifact_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L333)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L338)
 
 The directory the artifact is saved in
 
@@ -373,7 +383,7 @@ The directory the artifact is saved in
 
 
 ### artifact_excludes_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L337)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L342)
 
 Points to a file with a list of files to exclude from packaging.
 The format is as with the `tar --exclude-from=[file]` option
@@ -384,7 +394,7 @@ The format is as with the `tar --exclude-from=[file]` option
 
 
 ### build_from_repo
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L340)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L345)
 
 If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory
 
@@ -394,7 +404,7 @@ false
 
 
 ### repository
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L343)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L348)
 
 Overrides [repository](/docs/recipe/common.md#repository) from `recipe/common.php`.
 
@@ -406,7 +416,7 @@ null
 
 
 ### artifact_path
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L346)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L351)
 
 The relative path to the artifact file. If the directory does not exist, it will be created
 
@@ -419,7 +429,7 @@ return get('artifact_dir') . '/' . get('artifact_file');
 
 
 ### bin/tar
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L354)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L359)
 
 The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings
 :::info Autogenerated
@@ -430,14 +440,14 @@ The value of this configuration is autogenerated on access.
 
 
 ### additional_shared_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L426)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L431)
 
 Array of shared files that will be added to the default shared_files without overriding
 
 
 
 ### additional_shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L428)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L433)
 
 Array of shared directories that will be added to the default shared_dirs without overriding
 
@@ -447,7 +457,7 @@ Array of shared directories that will be added to the default shared_dirs withou
 ## Tasks
 
 ### magento:compile
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L154)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L159)
 
 Compiles magento di.
 
@@ -459,7 +469,7 @@ e.g.
 
 
 ### magento:deploy:assets
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L180)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L185)
 
 Deploys assets.
 
@@ -486,7 +496,7 @@ in `app/etc/config.php`, e.g.:
 
 
 ### magento:deploy:assets:adminhtml
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L196)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L201)
 
 Deploys assets for backend only.
 
@@ -494,7 +504,7 @@ Deploys assets for backend only.
 
 
 ### magento:deploy:assets:frontend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L201)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L206)
 
 Deploys assets for frontend only.
 
@@ -502,7 +512,7 @@ Deploys assets for frontend only.
 
 
 ### magento:sync:content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L249)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L254)
 
 Syncs content version.
 
@@ -510,7 +520,7 @@ Syncs content version.
 
 
 ### magento:maintenance:enable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L259)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L264)
 
 Enables maintenance mode.
 
@@ -518,7 +528,7 @@ Enables maintenance mode.
 
 
 ### magento:maintenance:disable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L265)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L270)
 
 Disables maintenance mode.
 
@@ -526,7 +536,7 @@ Disables maintenance mode.
 
 
 ### magento:maintenance:enable-if-needed
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L271)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L276)
 
 Set maintenance mode if needed.
 
@@ -534,7 +544,7 @@ Set maintenance mode if needed.
 
 
 ### magento:config:import
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L278)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L283)
 
 Config Import.
 
@@ -542,7 +552,7 @@ Config Import.
 
 
 ### magento:upgrade:db
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L287)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L292)
 
 Upgrades magento database.
 
@@ -550,7 +560,7 @@ Upgrades magento database.
 
 
 ### magento:cache:flush
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L296)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L301)
 
 Flushes Magento Cache.
 
@@ -558,7 +568,7 @@ Flushes Magento Cache.
 
 
 ### deploy:magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L301)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L306)
 
 Magento2 deployment operations.
 
@@ -575,7 +585,7 @@ This task is group task which contains next tasks:
 
 
 ### magento:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L311)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L316)
 
 Magento2 build operations.
 
@@ -588,7 +598,7 @@ This task is group task which contains next tasks:
 
 
 ### deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L317)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L322)
 
 Deploys your project.
 
@@ -604,7 +614,7 @@ This task is group task which contains next tasks:
 
 
 ### artifact:package
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L365)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L370)
 
 Packages all relevant files in an artifact.
 
@@ -612,7 +622,7 @@ Packages all relevant files in an artifact.
 
 
 ### artifact:upload
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L375)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L380)
 
 Uploads artifact in release folder for extraction.
 
@@ -620,7 +630,7 @@ Uploads artifact in release folder for extraction.
 
 
 ### artifact:extract
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L380)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L385)
 
 Extracts artifact in release path.
 
@@ -628,7 +638,7 @@ Extracts artifact in release path.
 
 
 ### build:remove-generated
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L386)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L391)
 
 Clears generated files prior to building.
 
@@ -636,7 +646,7 @@ Clears generated files prior to building.
 
 
 ### build:prepare
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L391)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L396)
 
 Prepare local artifact build.
 
@@ -644,7 +654,7 @@ Prepare local artifact build.
 
 
 ### artifact:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L416)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L421)
 
 Builds an artifact.
 
@@ -661,15 +671,33 @@ This task is group task which contains next tasks:
 
 
 ### deploy:additional-shared
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L432)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L437)
 
 Adds additional files and dirs to the list of shared files and dirs.
 
 
 
 
+### magento:set_cache_prefix
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L448)
+
+Update cache id_prefix.
+
+Update cache id_prefix on deploy so that you are compiling against a fresh cache
+Reference Issue: https://github.com/davidalger/capistrano-magento2/issues/151
+use set('use_redis_cache_id') in your deployer script to enable
+
+
+### magento:cleanup_cache_prefix
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L476)
+
+Cleanup cache id_prefix env files.
+
+After successful deployment, move the tmp_env.php file to env.php ready for next deployment
+
+
 ### artifact:prepare
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L439)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L489)
 
 Prepares an artifact on the target server.
 
@@ -689,7 +717,7 @@ This task is group task which contains next tasks:
 
 
 ### artifact:finish
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L452)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L502)
 
 Executes the tasks after artifact is released.
 
@@ -704,7 +732,7 @@ This task is group task which contains next tasks:
 
 
 ### artifact:deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L460)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L510)
 
 Actually releases the artifact deployment.