[WIP] Document "framework.assets.json_manifest_path" option #8004
Conversation
|
Looks like the automatic pull request builds are broken again. Can you provide the For example, the controller/argument_value_resolver.rst file contains invalid XML, specifically the line Importantly, this also causes build failure when building the Symfony documentation locally, as well! |
|
|
||
| The ``json_manifest_path`` option was introduced in Symfony 3.3. | ||
|
|
||
| The file path to a `manifest.json` file containing an associative array of asset |
There was a problem hiding this comment.
two ticks around manifest.json here.. and 2 lines below
|
|
||
| The file path to a `manifest.json` file containing an associative array of asset | ||
| names and their respective compiled names. A common cache-busting tecnique using | ||
| a `manifest.json` file works by writing out assets with a "hash" or "chunk hash" |
There was a problem hiding this comment.
I think we can remove or "chunk hash" - it may just confuse people - the important thing is that it's some hash in the filename
| The file path to a `manifest.json` file containing an associative array of asset | ||
| names and their respective compiled names. A common cache-busting tecnique using | ||
| a `manifest.json` file works by writing out assets with a "hash" or "chunk hash" | ||
| appendened to their file names. You can incorporate this into many workflows, |
There was a problem hiding this comment.
... file names (e.g.
main.ae433f1cb.css).
| names and their respective compiled names. A common cache-busting tecnique using | ||
| a `manifest.json` file works by writing out assets with a "hash" or "chunk hash" | ||
| appendened to their file names. You can incorporate this into many workflows, | ||
| including Webpack and Gulp using `gulp-rev`_ and `webpack-manifest-plugin`_, |
There was a problem hiding this comment.
swap the order of the links to match the order before :)
| framework: | ||
| assets: | ||
| # this manifest is applied to every asset (including packages) | ||
| json_manifest_path: "%kernel.root_dir%/../web/assets/manifest.json" |
There was a problem hiding this comment.
we can now use %kernel.project_dir%/web :)
|
|
||
| This parameter cannot be set at the same time as ``version`` or ``version_strategy``. | ||
| Additionally, parameter cannot be nullified at the package scope if a global manifest | ||
| file is specified. |
There was a problem hiding this comment.
Additionally, this option cannot be...
There was a problem hiding this comment.
Maybe add a new sentence (probably not in the note, but at the bottom somewhere):
If an asset's path is not found in the manifest file, the original - unmodified - path will be used.
|
@robfrawley Yea, the builds on platform.sh have been failing a bit more lately. Btw, we have invalid XML in Anyways, THANKS for this PR - you're saving me time personally :). Here are the failing build details: https://gist.github.com/weaverryan/cfd9db1da189bf6907a37c3fe436b106 Cheers! |
3b4dd0f to
74df78e
Compare
|
@weaverryan Thanks for the review; fixed all comments. As for the build failures, it looks like the invalid XML is causing the highlighting subroutine to fail while it parses the XML. The build error you linked above is the same one I get locally. Here is the same failure with some additional context: Again, this is caused by the invalid XML line @javiereguiluz No note added to https://symfony.com/doc/current/frontend/custom_version_strategy.html as the version strategy it describes is actually different from the |
74df78e to
b3c977e
Compare
|
There are a few other places in the documentation where asset versioning is briefly described, but these sections currently only mention the I've amended the documentation to include the new diff --git a/assetic/asset_management.rst b/assetic/asset_management.rst
index 4a78a7741..a1d58d468 100644
--- a/assetic/asset_management.rst
+++ b/assetic/asset_management.rst
@@ -552,10 +552,14 @@ done from the template and is relative to the public document root:
.. note::
- Symfony also contains a method for cache *busting*, where the final URL
- generated by Assetic contains a query parameter that can be incremented
- via configuration on each deployment. For more information, see the
- :ref:`reference-framework-assets-version` configuration option.
+ Symfony also contains a few internal methods for cache *busting*. The
+ :ref:`reference-framework-assets-version` configuration option appends
+ a query parameter to the asset path that can be incremented manually
+ on each deploy in your configuration. The
+ :ref:`json_manifest_path <reference-assets-json-manifest-path>`
+ configuration option uuses a ``manifest.json`` file, generally created
+ using a Webpack, Gulp, or other asset work flow, that maps assets to
+ their respective compiled names.
.. _assetic-dumping:
diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
index 86c8d5114..bebfbaabb 100644
--- a/reference/twig_reference.rst
+++ b/reference/twig_reference.rst
@@ -124,7 +124,10 @@ asset
Returns a public path to ``path``, which takes into account the base path
set for the package and the URL path. More information in
:ref:`templating-assets`. For asset versioning, see
-:ref:`reference-framework-assets-version`.
+:ref:`reference-framework-assets-version`,
+:ref:`reference-assets-json-manifest-path`, and
+:ref:`reference-assets-version-strategy
+.
assets_version
~~~~~~~~~~~~~~
diff --git a/templating.rst b/templating.rst
index 1a24325a0..7ccdc0b9c 100644
--- a/templating.rst
+++ b/templating.rst
@@ -774,10 +774,12 @@ should render with the subdirectory (e.g. ``/my_app/images/logo.png``). The
being used and generating the correct paths accordingly.
Additionally, if you use the ``asset()`` function, Symfony can automatically
-append a query string to your asset, in order to guarantee that updated static
-assets won't be loaded from cache after being deployed. For example, ``/images/logo.png`` might
-look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
-configuration option.
+implement cache busting strategies. The :ref:`reference-framework-assets-version`
+configuration option appends a query parameter to the asset path that can be
+incremented manually on each deploy in your configuration. The
+:ref:`json_manifest_path <reference-assets-json-manifest-path>` configuration
+option uses a ``manifest.json`` file, generally created using a Webpack, Gulp,
+or other asset work flow, that maps assets to their respective compiled names.
If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
as follows: |
b3c977e to
14c609b
Compare
|
Yes to the adding the diffs you posted, but let's shorten them - we should most say "there is versioning" and link. I just want to avoid duplicating explanations |
|
@weaverryan Just pushed a commit with the additional cache busting references tweaked to include the new |
8e1fa07 to
c8aa434
Compare
This PR was merged into the 3.3 branch. Discussion ---------- Remove/update lines causing build failures This pull request amends the invalid code blocks within the documentation to fix the build errors (both locally and on `platform.sh`). ~~Additionally, this normalizes the dependency installation and build calls executed by both `travis` and `platform.sh` so they both use the same environment to build the documentation. _This is important as currently, often one will fail while the other will succeed; this should not ever happen and they should both either fail or succeed._~~ See #8004 (comment) and #8004 (comment) for the origin story. ~~*Note: This should likely be applied to the `3.3` branch which is where the errors originate, will update the target branch once this is confirmed.*~~ Commits ------- 18ee5e2 fix invalid code lines and remove extra space
There was a problem hiding this comment.
@robfrawley I like this contribution a lot. And the note about the different cache busting options is useful too. Thanks!
| names and their respective compiled names. A common cache-busting technique using | ||
| a ``manifest.json`` file works by writing out assets with a "hash" appended to their | ||
| file names (e.g. ``main.ae433f1cb.css``). You can incorporate this into many work | ||
| flows, including Webpack and Gulp using `webpack-manifest-plugin`_ and `gulp-rev`_, |
There was a problem hiding this comment.
@weaverryan @javiereguiluz Does Symfony Encore support cache busting using a manifest.json file and hashed file names? If so, should we add a reference to it here?
There was a problem hiding this comment.
It does: added a note about that in combination with references for straight-webpack and gulp.
c8aa434 to
08d2af6
Compare
08d2af6 to
f7c7b56
Compare
|
Latest commit squashed three previous commits. The only change is the inclusion of information about using Webpack Encore to create manifest files; the prior text about using straight-webpack and gulp remains, as well. See the new tip box for the changes. |
|
Thank you @robfrawley. |
…tion (robfrawley) This PR was submitted for the master branch but it was merged into the 3.3 branch instead (closes #8004). Discussion ---------- [WIP] Document "framework.assets.json_manifest_path" option This pull request adds initial documentation for the newly introduced asset JSON manifest file path option: `framework.assets.json_manifest_path`. Resolves #7659. For reference on this new configuration option, see symfony/symfony#22046 and [symfony.com/blog/new-in-symfony-3-3-manifest-based-asset-versioning](https://symfony.com/blog/new-in-symfony-3-3-manifest-based-asset-versioning). Commits ------- 13a3070 document new framework.assets.json_manifest_path option
* 3.4: Fixes for #8084 thanks to Stof Tweaks thanks to Javier Use Twig's namespaced paths adding anotehr faq for old packages without a main script minor rewording [Encore] Adding more FAQs for #8072 [Encore] Documenting addPlugin - see #8070 Documenting (better) how to expose global variables - see #8071 [Encore] Adding docs about deploying to a subdirectory - see #8069 Adding docs about adding custom config - see #8067 Add missing link to handlebars-loader Add docs for custom loaders [#8004] some minor tweaks document new framework.assets.json_manifest_path option Minor reword Clearify setup of basic auth for test environment Update workflow.rst rearrange how workflow events are presented adding note about extracting CSS Adding note about browserslist config
This pull request adds initial documentation for the newly introduced asset JSON manifest file path option:
framework.assets.json_manifest_path. Resolves #7659.For reference on this new configuration option, see symfony/symfony#22046 and symfony.com/blog/new-in-symfony-3-3-manifest-based-asset-versioning.