From f4b35998e8e953498cc62b49586decafe1362326 Mon Sep 17 00:00:00 2001
From: Fabian Schmengler <fs@integer-net.de>
Date: Wed, 2 Nov 2022 19:04:57 +0100
Subject: [PATCH] Magento: document new options additional_shared{files,dirs}

---
 docs/recipe/magento2.md | 134 +++++++++++++++++-----------------------
 recipe/magento2.php     |   9 ++-
 2 files changed, 65 insertions(+), 78 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index 3554336ff..8d43689f8 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -56,7 +56,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#L22)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L23)
 
 By default setup:static-content:deploy uses `en_US`.
 To change that, put `set('static_content_locales', 'en_US de_DE');`
@@ -68,7 +68,7 @@ in you deployer script.
 
 
 ### magento_themes
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L39)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L40)
 
 You can also set the themes to run against. By default it'll deploy
 all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
@@ -92,14 +92,14 @@ set('magento_themes', [
 
 
 ### static_deploy_options
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L44)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L45)
 
 Static content deployment options, e.g. '--no-parent'
 
 
 
 ### split_static_deployment
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L47)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L48)
 
 Deploy frontend and adminhtml together as default
 
@@ -109,7 +109,7 @@ false
 
 
 ### static_content_locales_backend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L50)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L51)
 
 Use the default languages for the backend as default
 
@@ -119,7 +119,7 @@ Use the default languages for the backend as default
 
 
 ### magento_themes_backend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L54)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L55)
 
 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)
@@ -130,7 +130,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#L60)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L61)
 
 Also set the number of conccurent jobs to run. The default is 1
 Update using: `set('static_content_jobs', '1');`
@@ -141,7 +141,7 @@ Update using: `set('static_content_jobs', '1');`
 
 
 ### content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L62)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L63)
 
 
 
@@ -151,7 +151,7 @@ return time();
 
 
 ### magento_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L67)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L68)
 
 Magento directory relative to repository root. Use "." (default) if it is not located in a subdirectory
 
@@ -161,7 +161,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#L70)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L71)
 
 Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recipe/deploy/shared.php`.
 
@@ -176,7 +176,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#L74)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L75)
 
 Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
 
@@ -201,7 +201,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#L88)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L89)
 
 Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
 
@@ -219,7 +219,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#L95)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L96)
 
 Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `recipe/deploy/clear_paths.php`.
 
@@ -237,8 +237,22 @@ Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `re
 ```
 
 
+### additional_shared_files
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L106)
+
+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#L108)
+
+Array of shared directories that will be added to the default shared_dirs without overriding
+
+
+
 ### bin/magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L104)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L113)
 
 
 
@@ -248,20 +262,20 @@ 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#L106)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L115)
 
 
 
 ```php title="Default value"
 // detect version
-$versionOutput = run('{{bin/php}} {{bin/magento}} --version');
+$versionOutput = run('{{bin/php}} {{release_or_current_path}}/{{bin/magento}} --version');
 preg_match('/(\d+\.?)+(-p\d+)?$/', $versionOutput, $matches);
 return $matches[0] ?? '2.0';
 ```
 
 
 ### maintenance_mode_status_active
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L113)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L122)
 
 
 
@@ -273,7 +287,7 @@ return strpos($maintenanceModeStatusOutput, MAINTENANCE_MODE_ACTIVE_OUTPUT_MSG)
 
 
 ### enable_zerodowntime
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L120)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L129)
 
 Deploy without setting maintenance mode if possible
 
@@ -283,7 +297,7 @@ true
 
 
 ### artifact_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L310)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L317)
 
 artifact deployment section
 settings section
@@ -294,7 +308,7 @@ settings section
 
 
 ### artifact_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L311)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L318)
 
 
 
@@ -304,7 +318,7 @@ settings section
 
 
 ### artifact_excludes_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L312)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L319)
 
 
 
@@ -314,7 +328,7 @@ settings section
 
 
 ### artifact_path
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L314)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L321)
 
 
 
@@ -327,7 +341,7 @@ return get('artifact_dir') . '/' . get('artifact_file');
 
 
 ### bin/tar
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L321)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L328)
 
 
 :::info Autogenerated
@@ -338,7 +352,7 @@ The value of this configuration is autogenerated on access.
 
 
 ### cacheToolPath
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L329)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L336)
 
 
 
@@ -351,7 +365,7 @@ return get('cacheTool', '{{current_path}}/bin/cachetool');
 ## Tasks
 
 ### magento:compile
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L124)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L133)
 
 Compiles magento di.
 
@@ -359,7 +373,7 @@ Tasks
 
 
 ### magento:deploy:assets
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L130)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L139)
 
 Deploys assets.
 
@@ -367,7 +381,7 @@ Deploys assets.
 
 
 ### magento:deploy:assets:adminhtml
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L144)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L153)
 
 Deploys assets for backend only.
 
@@ -375,7 +389,7 @@ Deploys assets for backend only.
 
 
 ### magento:deploy:assets:frontend
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L149)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L158)
 
 Deploys assets for frontend only.
 
@@ -383,7 +397,7 @@ Deploys assets for frontend only.
 
 
 ### magento:sync:content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L197)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L206)
 
 Syncs content version.
 
@@ -391,7 +405,7 @@ Syncs content version.
 
 
 ### magento:maintenance:enable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L207)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L216)
 
 Enables maintenance mode.
 
@@ -399,7 +413,7 @@ Enables maintenance mode.
 
 
 ### magento:maintenance:disable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L212)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L221)
 
 Disables maintenance mode.
 
@@ -407,7 +421,7 @@ Disables maintenance mode.
 
 
 ### magento:config:import
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L217)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L226)
 
 Config Import.
 
@@ -415,7 +429,7 @@ Config Import.
 
 
 ### magento:upgrade:db
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L252)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L261)
 
 Upgrades magento database.
 
@@ -423,7 +437,7 @@ Upgrades magento database.
 
 
 ### magento:cache:flush
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L279)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L288)
 
 Flushes Magento Cache.
 
@@ -431,7 +445,7 @@ Flushes Magento Cache.
 
 
 ### deploy:magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L284)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L293)
 
 Magento2 deployment operations.
 
@@ -446,7 +460,7 @@ This task is group task which contains next tasks:
 
 
 ### magento:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L292)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L301)
 
 Magento2 build operations.
 
@@ -459,7 +473,7 @@ This task is group task which contains next tasks:
 
 
 ### deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L298)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L307)
 
 Deploys your project.
 
@@ -475,7 +489,7 @@ This task is group task which contains next tasks:
 
 
 ### artifact:package
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L335)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L342)
 
 Packages all relevant files in an artifact.
 
@@ -483,7 +497,7 @@ tasks section
 
 
 ### artifact:upload
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L345)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L352)
 
 Uploads artifact in release folder for extraction.
 
@@ -491,7 +505,7 @@ Uploads artifact in release folder for extraction.
 
 
 ### artifact:extract
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L350)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L357)
 
 Extracts artifact in release path.
 
@@ -499,7 +513,7 @@ Extracts artifact in release path.
 
 
 ### build:prepare-env
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L356)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L363)
 
 Provides env.php for build.
 
@@ -507,49 +521,17 @@ Provides env.php for build.
 
 
 ### build:remove-generated
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L367)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L374)
 
 Clears generated files prior to building.
 
 
 
 
-### cache:clear:opcache
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L372)
-
-Clears the opcache, cache tool required.
-
-
-
-
-### artifact:build
+### build:prepare
 [Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L379)
 
-Builds an artifact.
-
-
-
-
-### artifact:prepare
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L396)
-
-Prepares an artifact on the target server.
-
-
-
-
-### artifact:finish
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L414)
-
-Executes the tasks after artifact is released.
-
-
-
-
-### artifact:deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L426)
-
-Actually releases the artifact deployment.
+Prepare local artifact build.
 
 
 
diff --git a/recipe/magento2.php b/recipe/magento2.php
index ba973131c..87bf362a7 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -102,8 +102,13 @@
     '{{magento_dir}}/var/view_preprocessed/*'
 ]);
 
-add('shared_files', get('additional_shared_files') ?? []);
-add('shared_dirs', get('additional_shared_dirs') ?? []);
+// Array of shared files that will be added to the default shared_files without overriding
+set('additional_shared_files', []);
+// Array of shared directories that will be added to the default shared_dirs without overriding
+set('additional_shared_dirs', []);
+
+add('shared_files', get('additional_shared_files'));
+add('shared_dirs', get('additional_shared_dirs'));
 
 set('bin/magento', '{{magento_dir}}/bin/magento');