Merge branch '3.3' into 3.4

* 3.3:
  incorrect session short description
  Use of Setters and Getters
  Small mistype edits
  Changed text how to get button label
  Small misspelling fixes
  Small typo fix
  Edited to show more ways, to get crawler form
  Adding FAQ about deploy and git
  Fix (sense) typo in ACL documentation
  [Encore] Updating for new sass options ability
  fixing links in table
  fixing bad link
  Adding Assetic versus Encore document

Author: weaverryan

components/dom_crawler.rst

@@ -396,10 +396,19 @@ given text. This method is especially useful because you can use it to return
 a :class:`Symfony\\Component\\DomCrawler\\Form` object that represents the
 form that the button lives in::
 
-    $form = $crawler->selectButton('validate')->form();
+    // button example: <button id="my-super-button" type="submit">My super button</button>
+    
+    // you can get button by its label
+    $form = $crawler->selectButton('My super button')->form();
+    
+    // or by button id (#my-super-button) if the button doesn't have a label
+    $form = $crawler->selectButton('my-super-button')->form();
+    
+    // or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
+    $crawler->filter('.form-vertical')->form();
 
     // or "fill" the form fields with data
-    $form = $crawler->selectButton('validate')->form(array(
+    $form = $crawler->selectButton('my-super-button')->form(array(
         'name' => 'Ryan',
     ));
 

controller.rst

@@ -453,8 +453,8 @@ Managing the Session
 --------------------
 
 Symfony provides a nice session object that you can use to store information
-about the user between requests. By default, Symfony stores the attributes in a
-cookie by using native PHP sessions.
+about the user between requests. By default, Symfony stores the token in a
+cookie and writes the attributes to a file by using native PHP sessions.
 
 .. versionadded:: 3.3
     The ability to request a ``Session`` instance in controllers was introduced

controller/upload_file.rst

@@ -239,7 +239,7 @@ logic to a separate service::
         {
             $fileName = md5(uniqid()).'.'.$file->guessExtension();
 
-            $file->move($this->targetDir, $fileName);
+            $file->move($this->getTargetDir(), $fileName);
 
             return $fileName;
         }

frontend.rst

@@ -62,18 +62,28 @@ Guides
 * :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
 * :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
 
-Troubleshooting
-...............
+Issues & Questions
+..................
 
 * :doc:`FAQ & Common Issues </frontend/encore/faq>`
+* :doc:`/frontend/encore/versus-assetic`
 
 Full API
 ........
 
 * `Full API`_: https://github.com/symfony/webpack-encore/blob/master/index.js
 
+Assetic
+-------
+
+Assetic is a pure PHP library that helps to process & optimize your assets (similar
+to Encore). Even though we recommend using Encore, Assetic still works great. For
+a comparison, see :doc:`/frontend/encore/versus-assetic`.
+
+For more about Assetic, see :doc:`/assetic`.
+
 Other Front-End Articles
-........................
+------------------------
 
 .. toctree::
     :hidden:

frontend/encore/bootstrap.rst

@@ -41,7 +41,7 @@ this, you can use the ``resolve_url_loader`` option:
 
     // webpack.config.js
     Encore
-    +     .enableSassLoader({
+    +     .enableSassLoader(function(sassOptions) {}, {
     +         resolve_url_loader: false
     +     })
     ;

frontend/encore/css-preprocessors.rst

@@ -22,7 +22,21 @@ And enable it in ``webpack.config.js``:
         .enableSassLoader()
     ;
 
-That's it! All files ending in ``.sass`` or ``.scss`` will be pre-processed.
+That's it! All files ending in ``.sass`` or ``.scss`` will be pre-processed. You
+can also pass options to ``sass-loader``:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+        .enableSassLoader(function(sassOptions) {
+            // https://github.com/sass/node-sass#options
+            // options.includePaths = [...]
+        });
+    ;
 
 Using LESS
 ----------

frontend/encore/faq.rst

@@ -1,6 +1,57 @@
 FAQ and Common Issues
 =====================
 
+How do I deploy my Encore Assets?
+---------------------------------
+
+There are two important things to remember when deploying your assets.
+
+**1) Run ``encore production``**
+
+Optimize your assets for production by running:
+
+.. code-block:: terminal
+
+    $ ./node_modules/.bin/encore production
+
+That will minify your assets and make other performance optimizations. Yay!
+
+But, what server should you run this command on? That depends on how you deploy.
+For example, you could execute this locally (or on a build server), and use rsync
+or something else to transfer the built files to your server. Or, you could put your
+files on your production server first (e.g. via a git pull) and then run this command
+on production (ideally, before traffic hits your code). In this case, you'll need
+to install Node.js on your production server.
+
+**2) Only Deploy the Built Assets**
+
+The *only* files that need to be deployed to your production servers are the
+final, built assets (e.g. the ``web/build`` directory). You do *not* need to install
+Node.js, deploy ``webpack.config.js``, the ``node_modules`` directory or even your source
+asset files, **unless** you plan on running ``encore production`` on your production
+machine. Once your assets are built, these are the *only* thing that need to live
+on the production server.
+
+Do I need to Install Node.js on my Production Server?
+-----------------------------------------------------
+
+No, unless you plan to build your production assets on your production server,
+which is not recommended. See `How do I deploy my Encore Assets?`_.
+
+What Files Should I commit to git? And which should I Ignore?
+-------------------------------------------------------------
+
+You should commit all of your files to git, except for the ``node_modules/`` directory
+and the built files. Your ``.gitignore`` file should include:
+
+.. code-block:: text
+
+    /node_modules/
+    # whatever path you're passing to Encore.setOutputPath()
+    /web/build
+
+You *should* commit all of your source asset files, ``package.json`` and ``yarn.lock``.
+
 My App Lives under a Subdirectory
 ---------------------------------
 

frontend/encore/versus-assetic.rst

@@ -0,0 +1,56 @@
+Encore Versus Assetic?
+======================
+
+Symfony originally shipped with support for :doc:`Assetic </assetic>`: a
+pure PHP library capable of processing, combining and minifying CSS and JavaScript
+files. And while Encore is now the recommended way or processing your assets, Assetic
+still works well.
+
+So what are the differences between Assetic and Encore?
+
++--------------------------+-------------------------------+-------------------------+
+|                          | Assetic                       | Encore                  +
++--------------------------+-------------------------------+-------------------------+
+| Language                 | Pure PHP, relies on other     | Node.js                 |
+|                          | language tools for some tasks |                         |
++--------------------------+-------------------------------+-------------------------+
+| Combine assets?          | Yes                           | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Minify assets?           | Yes (when configured)         | Yes (out-of-the-box)    |
++--------------------------+-------------------------------+-------------------------+
+| Process Sass/Less?       | Yes                           | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Loads JS Modules? [1]_   | No                            | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Load CSS Deps in JS? [1] | No                            | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| React, Vue.js support?   | No [2]_                       | Yes                     |
++--------------------------+-------------------------------+-------------------------+
+| Support                  | Not actively maintained       | Actively maintained     |
++--------------------------+-------------------------------+-------------------------+
+
+.. [1] JavaScript modules allow you to organize your JavaScript into small files
+       called modules and import them:
+
+       .. code-block:: javascript
+
+           // require third-party modules
+           var $ = require('jquery');
+
+           // require your own CoolComponent.js modules
+           var coolComponent = require('./components/CoolComponent');
+
+       Encore (via Webpack) parses these automatically and creates a JavaScript
+       file that contains all needed dependencies. You can even require CSS or
+       images.
+
+.. [2] Assetic has outdated support for React.js only. Encore ships with modern
+       support for React.js, Vue.js, Typescript, etc.
+
+Should I Upgrade from Assetic to Encore
+---------------------------------------
+
+If you already have Assetic working in an application, and haven't needed any of
+the features that Encore offers over Assetic, continuting to use Assetic is fine.
+If you *do* start to need more features, then you might have a business case for
+changing to Encore.

security/acl_advanced.rst

@@ -190,7 +190,7 @@ this request to an implementation of
 This allows you to replace the way access decisions are reached without actually
 modifying the ACL class itself.
 
-The ``PermissionGrantingStrategy`` first checks all your object-scope ACEs. If none
+The ``PermissionGrantingStrategy`` first checks all your object-scope ACEs. If one
 is applicable, the class-scope ACEs will be checked. If none is applicable,
 then the process will be repeated with the ACEs of the parent ACL. If no
 parent ACL exists, an exception will be thrown.