From 9fd089997cbc62445b691b0c2d6cea485d9aae2f Mon Sep 17 00:00:00 2001
From: Mathieu De Keyzer <me@theus.be>
Date: Wed, 3 Jul 2024 11:24:25 +0200
Subject: [PATCH] refactor(elasticms): archives in cache storage (#939)

Co-authored-by: David mattei <d.mattei89@gmail.com>
---
 dev/client-helper-bundle/routing.md | 16 +++++++++++++++-
 dev/client-helper-bundle/twig.md    |  8 ++++----
 upgrade.md                          | 11 +++++++++++
 3 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/dev/client-helper-bundle/routing.md b/dev/client-helper-bundle/routing.md
index 24d9dcf..7254cc3 100644
--- a/dev/client-helper-bundle/routing.md
+++ b/dev/client-helper-bundle/routing.md
@@ -73,7 +73,7 @@ And in the redirect_favicon.json.twig template:
 
 ````twig
 {% apply spaceless %}
-      {% set assetPath = emsch_assets_version('240c99f842c118a733f14420bf40e320bdb500b9') %}
+      {% do emsch_assets_version('240c99f842c118a733f14420bf40e320bdb500b9') %}
       {{ {'url': asset('static/favicon-96x96.png', 'emsch'), 'status': 301 }|json_encode|raw }}
 {% endapply %}
 ````
@@ -338,3 +338,17 @@ Return HTTP codes:
 > With all other server APIs, listeners to `kernel.terminate` are still executed, but the response is not sent to 
 > the client until they are all completed.
 
+## Route to assets in archive
+
+With this controller you can specify routes to files in zip archives.
+
+If the route is not immutable (does not contain the archive hash) you must specify the maxAge argument (by default it's set to one week).
+
+```yaml
+emsch_demo_asset_in_archive:
+  config:
+    path: '/assets_in_archive/{path}'
+    requirements: { path: .* }
+    defaults: { hash: 253b903b1fb3ac30975ae9844a0352a65cdcfa3d, maxAge: 3600 }
+    controller: 'EMS\CommonBundle\Controller\FileController::assetInArchive'
+```
diff --git a/dev/client-helper-bundle/twig.md b/dev/client-helper-bundle/twig.md
index feadada..c79fcf2 100644
--- a/dev/client-helper-bundle/twig.md
+++ b/dev/client-helper-bundle/twig.md
@@ -23,12 +23,12 @@ Example base template.
 
 ## emsch_assets_version
 
-This is similar to [emsch_assets](#emsch_assets) but using the hash as version strategy for the assets. No need to add an alias rule in the Vhost file.
+This function specify the hash of the archive containing the assets of the website (JS, CSS, ...)
+
+The second argument should be set to `null` as that argument has been deprecated in 5.19.x.
 
-This function will unzip the file (hash) in /public/{saveDir}/**hash** (if not exists).
-The default value of the saveDir is **bundles**.
 ```twig
-{{- emsch_assets_version('hash', 'saveDir') -}}
+{%- do emsch_assets_version('hash', null) -%}
 ```
 
 This function can be called only one time per Twig rendering. Otherwise, an error will be thrown.
diff --git a/upgrade.md b/upgrade.md
index 2152a7d..b57cc56 100644
--- a/upgrade.md
+++ b/upgrade.md
@@ -20,6 +20,17 @@
   * In case of warning or error in the `emsco:xliff:update` command the report file is no more available locally. The report is upladed in the admin's storages. The directly get a link to the report you need to specify a `--base-url` option.
 
     Example ```emsco:xliff:update /tmp/pages-nl-to-de.xlf --base-url=https://my-admin.my-project.tld```
+* You should not specify a folder where to expand website assets in the `emsch_assets_version` twig function, in this case the function returns `null`.
+  * By default, if you specify `null` (e.g. `{% do emsch_assets_version(include('@EMSCH/template/asset_hash.twig'), null) %}`) as second arguments, the `emsch` assets will have a an url like `/bundle/253b903b1fb3ac30975ae9844a0352a65cdcfa3d/site.css` which urls will be resolved by the route `EMS\CommonBundle\Controller\FileController::assetInArchive`
+  * It's also possible the defined you own route for assets in archive, if the route is not immutable (does not contain the archive hash) you must specify the `maxAge` argument (by default it's set to one week): 
+```yaml
+emsch_demo_asset_in_archive:
+  config:
+    path: '/assets_in_archive/{path}'
+    requirements: { path: .* }
+    defaults: { hash: 253b903b1fb3ac30975ae9844a0352a65cdcfa3d, maxAge: 3600 }
+    controller: 'EMS\CommonBundle\Controller\FileController::assetInArchive'
+```
 
 ## version 5.17.x