Merge branch '3.4'

* 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

Author: weaverryan

assetic/asset_management.rst

@@ -552,10 +552,11 @@ 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 provides various cache busting implementations via the
+    :ref:`version <reference-framework-assets-version>`,
+    :ref:`version_format <reference-assets-version-format>`, and
+    :ref:`json_manifest_path <reference-assets-json-manifest-path>`
+    configuration options.
 
 .. _assetic-dumping:
 

components/workflow.rst

@@ -44,8 +44,8 @@ these statuses are called **places**. You can define the workflow like this::
     use Symfony\Component\Workflow\Workflow;
     use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
 
-    $definition = new DefinitionBuilder()
-        ->addPlaces(['draft', 'review', 'rejected', 'published'])
+    $definition = new DefinitionBuilder();
+    $definition->addPlaces(['draft', 'review', 'rejected', 'published'])
         // Transitions are defined with a unique name, an origin place and a destination place
         ->addTransition(new Transition('to_review', 'draft', 'review'))
         ->addTransition(new Transition('publish', 'review', 'published'))

frontend.rst

@@ -6,6 +6,8 @@ working with CSS and JavaScript a joy. You can use it, use something else, or ju
 create static CSS and JS files in your ``web/`` directory and include them in your
 templates.
 
+.. _frontend-webpack-encore:
+
 Webpack Encore
 --------------
 
@@ -56,6 +58,13 @@ Guides
 * :doc:`jQuery and Legacy Applications </frontend/encore/legacy-apps>`
 * :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
 * :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
+* :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
+* :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
+
+Troubleshooting
+...............
+
+* :doc:`FAQ & Common Issues </frontend/encore/faq>`
 
 Full API
 ........

frontend/custom_version_strategy.rst

@@ -10,11 +10,17 @@ applications by adding a version identifier to the URL of the static assets
 identifier is also modified to force the browser to download it again instead of
 reusing the cached asset.
 
-Symfony supports asset versioning thanks to the :ref:`version <reference-framework-assets-version>`
-and :ref:`version_format <reference-assets-version-format>` configuration
-options. If your application requires a more advanced versioning, such as
-generating the version dynamically based on some external information, you can
-create your own version strategy.
+If your application requires advanced versioning, such as generating the
+version dynamically based on some external information, you can create your
+own version strategy.
+
+.. note::
+
+    Symfony provides various cache busting implementations via the
+    :ref:`version <reference-framework-assets-version>`,
+    :ref:`version_format <reference-assets-version-format>`, and
+    :ref:`json_manifest_path <reference-assets-json-manifest-path>`
+    configuration options.
 
 Creating your Own Asset Version Strategy
 ----------------------------------------

frontend/encore/advanced-config.rst

@@ -0,0 +1,44 @@
+Advanced Webpack Config
+=======================
+
+Quite simply, Encore generates the Webpack configuration that's used in your
+``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
+`configuration options`_, because many can be easily added on your own.
+
+For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
+modify the config after fetching the it from Encore:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+
+    var Encore = require('@symfony/webpack-encore');
+
+    // ... all Encore config here
+
+    // fetch the config, then modify it!
+    var config = Encore.getWebpackConfig();
+    config.watchOptions = { poll: true, ignored: /node_modules/ };
+
+    // other examples: add an alias or extension
+    // config.resolve.alias.local = path.resolve(__dirname, './resources/src');
+    // config.resolve.extensions.push('json');
+
+    // export the final config
+    module.exports = config;
+
+But be careful not to accidentally override any config from Encore:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    // GOOD - this modifies the config.resolve.extensions array
+    config.resolve.extensions.push('json');
+
+    // BAD - this replaces any extensions added by Encore
+    // config.resolve.extensions = ['json'];
+
+.. _`configuration options`: https://webpack.js.org/configuration/
+.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions

frontend/encore/custom-loaders-plugins.rst

@@ -0,0 +1,64 @@
+Adding Custom Loaders & Plugins
+===============================
+
+Adding Custom Loaders
+---------------------
+
+Encore already comes with a variety of different loaders out of the box,
+but if there is a specific loader that you want to use that is not currently supported, you
+can add your own loader through the ``addLoader`` function.
+The ``addLoader`` takes any valid webpack rules config.
+
+If, for example, you want to add the `handlebars-loader`_, call ``addLoader`` with
+your loader config
+
+.. code-block:: javascript
+
+    Encore
+        // ...
+        .addLoader({ test: /\.handlebars$/, loader: 'handlebars-loader' })
+    ;
+
+Since the loader config accepts any valid Webpack rules object, you can pass any
+additional information your need for the loader
+
+.. code-block:: javascript
+
+    Encore
+        // ...
+        .addLoader({
+            test: /\.handlebars$/,
+            loader: 'handlebars-loader',
+            options: {
+                helperDirs: [
+                    __dirname + '/helpers1',
+                    __dirname + '/helpers2',
+                ],
+                partialDirs: [
+                    path.join(__dirname, 'templates', 'partials')
+                ]
+            }
+        })
+    ;
+
+Adding Custom Plugins
+---------------------
+
+Encore uses a variety of different `plugins`_ internally. But, you can add your own
+via the ``addPlugin()`` method. For example, if you use `Moment.js`_, you might want
+to use the `IgnorePlugin`_ (see `moment/moment#2373`_):
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        + .addPlugin(new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/))
+    ;
+
+.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader
+.. _`plugins`: https://webpack.js.org/plugins/
+.. _`Moment.js`: https://momentjs.com/
+.. _`IgnorePlugin`: https://webpack.js.org/plugins/ignore-plugin/
+.. _`moment/moment#2373`: https://github.com/moment/moment/issues/2373

frontend/encore/faq.rst

@@ -0,0 +1,80 @@
+FAQ and Common Issues
+=====================
+
+My App Lives under a Subdirectory
+---------------------------------
+
+If your app does not live at the root of your web server (i.e. it lives under a subdirectory,
+like ``/myAppSubdir``), you just need to configure that when calling ``Encore.setPublicPrefix()``:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        .setOutputPath('web/build/')
+
+        - .setPublicPath('/build')
+        + // this is your *true* public path
+        + .setPublicPath('/myAppSubdir/build')
+
+        + // this is now needed so that your manifest.json keys are still `build/foo.js`
+        + // i.e. you won't need to change anything in your Symfony app
+        + .setManifestKeyPrefix('build')
+    ;
+
+If you're :ref:`processing your assets through manifest.json <load-manifest-files>`,
+you're done! The ``manifest.json`` file will now include the subdirectory in the
+final paths:
+
+.. code-block:: json
+
+    {
+        "build/app.js": "/myAppSubdir/build/app.123abc.js",
+        "build/dashboard.css": "/myAppSubdir/build/dashboard.a4bf2d.css"
+    }
+
+"jQuery is not defined" or "$ is not defined"
+---------------------------------------------
+
+This error happens when your code (or some library that you are using) expects ``$``
+or ``jQuery`` to be a global variable. But, when you use Webpack and ``require('jquery')``,
+no global variables are set.
+
+The fix depends on if the error is happening in your code or inside some third-party
+code that you're using. See :doc:`/frontend/encore/legacy-apps` for the fix.
+
+Uncaught ReferenceError: webpackJsonp is not defined
+----------------------------------------------------
+
+If you get this error, it's probably because you've just added a :doc:`shared entry </frontend/encore/shared-entry>`
+but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the
+information about the :ref:`script tags <encore-shared-entry-script>` in that section.
+
+This dependency was not found: some-module in ./path/to/file.js
+---------------------------------------------------------------
+
+Usually, after you install a package via yarn, you can require / import it to use
+it. For example, after running ``yarn add respond.js``, you try to require that module:
+
+.. code-block:: javascript
+
+    require('respond.js');
+
+But, instead of working, you see an error:
+
+    This dependency was not found:
+
+    * respond.js in ./app/Resources/assets/js/app.js
+
+Typically, a package will "advertise" its "main" file by adding a ``main`` key to
+its ``package.json``. But sometimes, old libraries won't have this. Instead, you'll
+need to specifically require the file you need. In this case, the file you should
+use is located at ``node_modules/respond.js/dest/respond.src.js``. You can require
+this via:
+
+.. code-block:: javascript
+
+    // require a non-minified file whenever possible
+    require('respond.js/dest/respond.src.js');

frontend/encore/legacy-apps.rst

@@ -1,6 +1,21 @@
 jQuery and Legacy Applications
 ==============================
 
+Inside Webpack, when you require a module, it does *not* (usually) set a global variable.
+Instead, it just returns a value:
+
+.. code-block:: javascript
+
+    // this loads jquery, but does *not* set a global $ or jQuery variable
+    const $ = require('jquery');
+
+In practice, this will cause problems with some outside libraries that *rely* on
+jQuery to be global. It will be a problem if some of *your* JavaScript isn't being
+processed through Webpack (e.g. you have some JavaScript in your templates).
+
+Using Libraries that Expect jQuery to be Global
+-----------------------------------------------
+
 Some legacy JavaScript applications use programming practices that don't play
 well with the new practices promoted by Webpack. The most common of these
 problems is using code (e.g. jQuery plugins) that assume that jQuery is already
@@ -27,7 +42,7 @@ So, when working with legacy applications, you may need to add the following to
     +     .autoProvidejQuery()
     ;
 
-Internally, this ``autoProvidejQuery()`` method uses the ``autoProvideVariables()``
+Internally, this ``autoProvidejQuery()`` method calls the ``autoProvideVariables()``
 method from Encore. In practice, it's equivalent to doing:
 
 .. code-block:: javascript
@@ -38,16 +53,33 @@ method from Encore. In practice, it's equivalent to doing:
         .autoProvideVariables({
             $: 'jquery',
             jQuery: 'jquery'
+            'window.jQuery': 'jquery',
         })
         // ...
     ;
 
+Accessing jQuery from outside of Webpack JavaScript Files
+---------------------------------------------------------
+
 If you also need to provide access to ``$`` and ``jQuery`` variables outside of
-JavaScript files processed by Webpack, you must create the global variables
-yourself in some file loaded before the legacy JavaScript code. For example, you
-can define a ``common.js`` file processed by Webpack and loaded in every page
-with the following content:
+JavaScript files processed by Webpack (e.g. JavaScript that still lives in your
+templates), you need to manually set these as global variables in some JavaScript
+file that is loaded before your legacy code.
+
+For example, you could define a ``common.js`` file that's processed by Webpack and
+loaded on every page with the following content:
 
 .. code-block:: javascript
 
-    window.$ = window.jQuery = require('jquery');
+    // require jQuery normally
+    const $ = require('jquery');
+
+    // create global $ and jQuery variables
+    global.$ = global.jQuery = $;
+
+.. tip::
+
+    The ``global`` variable is a special way of setting things in the ``window``
+    variable. In a web context, using ``global`` and ``window`` are equivalent,
+    except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
+    In other words, use ``global``.

frontend/encore/postcss.rst

@@ -18,6 +18,8 @@ Next, create a ``postcss.config.js`` file at the root of your project:
         plugins: {
             // include whatever plugins you want
             // but make sure you install these via yarn or npm!
+
+            // add browserslist config to package.json (see below)
             autoprefixer: {}
         }
     }
@@ -35,6 +37,29 @@ Then, Enable the loader in Encore!
 
 That's it! The ``postcss-loader`` will now be used for all CSS, Sass, etc files.
 
+Adding browserslist to package.json
+-----------------------------------
+
+The ``autoprefixer`` (and many other tools) need to know what browsers you want to
+support. The best-practice is to configure this directly in your ``package.json``
+(so that all the tools can read this):
+
+.. code-block:: diff
+
+    {
+    +     "browserslist": [ "last 2 versions", "ios >= 8" ]
+    }
+
+See `browserslist`_ for more details on the syntax.
+
+.. note::
+
+    Encore uses `babel-preset-env`_, which *also* needs to know which browsers you
+    want to support. But this does *not* read the ``browserslist`` config key. You
+    must configure the browsers separately via :doc:`configureBabel() </frontend/encore/babel>`.
+
 .. _`PostCSS`: http://postcss.org/
 .. _`autoprefixing`: https://github.com/postcss/autoprefixer
 .. _`linting`: https://stylelint.io/
+.. _`browserslist`: https://github.com/ai/browserslist
+.. _`babel-preset-env`: https://github.com/babel/babel-preset-env