diff --git a/_build/redirection_map b/_build/redirection_map index 980c5ea32ff..5734d9ea14f 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -355,6 +355,13 @@ /event_dispatcher/class_extension /event_dispatcher /form /forms /form/use_virtual_forms /form/inherit_data_option +/frontend/assetic/apply_to_option /frontend/assetic +/frontend/assetic/asset_management /frontend/assetic +/frontend/assetic/jpeg_optimize /frontend/assetic +/frontend/assetic/php /frontend/assetic +/frontend/assetic/uglifyjs /frontend/assetic +/frontend/assetic/yuicompressor /frontend/assetic +/reference/configuration/assetic /frontend/assetic /security/target_path /security /service_container/third_party /service_container /templating/templating_service /templates diff --git a/assetic/_standard_edition_warning.rst.inc b/assetic/_standard_edition_warning.rst.inc deleted file mode 100644 index 2a111cd2291..00000000000 --- a/assetic/_standard_edition_warning.rst.inc +++ /dev/null @@ -1,5 +0,0 @@ -.. caution:: - - Starting from Symfony 2.8, Assetic is no longer included by default in the - Symfony Standard Edition. Refer to :doc:`this article ` - to learn how to install and enable Assetic in your Symfony application. diff --git a/best_practices/web-assets.rst b/best_practices/web-assets.rst index 2aeee469f0a..271a1fa3eeb 100644 --- a/best_practices/web-assets.rst +++ b/best_practices/web-assets.rst @@ -29,7 +29,6 @@ features. Next: :doc:`/best_practices/tests` -.. _`official Assetic documentation`: https://github.com/kriswallsmith/assetic .. _`Webpack Encore`: https://github.com/symfony/webpack-encore .. _`Webpack`: https://webpack.js.org/ .. _`official Webpack Encore documentation`: https://symfony.com/doc/current/frontend.html diff --git a/frontend/assetic.rst b/frontend/assetic.rst index 59f8d06ecba..76434529920 100644 --- a/frontend/assetic.rst +++ b/frontend/assetic.rst @@ -1,10 +1,8 @@ Assetic ======= -.. include:: /assetic/_standard_edition_warning.rst.inc +.. caution:: -.. toctree:: - :maxdepth: 1 - :glob: - - assetic/* + Using Assetic to manage web assets in Symfony applications is no longer + recommended. Instead, use :doc:`Webpack Encore `, which bridges + Symfony apps with modern JavaScript-based tools to manage web assets. diff --git a/frontend/assetic/apply_to_option.rst b/frontend/assetic/apply_to_option.rst deleted file mode 100644 index a144f08172f..00000000000 --- a/frontend/assetic/apply_to_option.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. index:: - single: Assetic; Apply filters - -How to Apply an Assetic Filter to a specific File Extension -=========================================================== - -.. include:: /assetic/_standard_edition_warning.rst.inc - -Assetic filters can be applied to individual files, groups of files or even, -as you'll see here, files that have a specific extension. To show you how -to handle each option, suppose that you want to use Assetic's CoffeeScript -filter, which compiles CoffeeScript files into JavaScript. - -The main configuration is just the paths to ``coffee``, ``node`` and ``node_modules``. -An example configuration might look like this: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - coffee: - bin: /usr/bin/coffee - node: /usr/bin/node - node_paths: [/usr/lib/node_modules/] - - .. code-block:: xml - - - - - - - - /usr/lib/node_modules/ - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'coffee' => array( - 'bin' => '/usr/bin/coffee', - 'node' => '/usr/bin/node', - 'node_paths' => array('/usr/lib/node_modules/'), - ), - ), - )); - -Filter a single File --------------------- - -You can now serve up a single CoffeeScript file as JavaScript from within your -templates: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/example.coffee' filter='coffee' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/example.coffee'), - array('coffee') - ) as $url): ?> - - - -This is all that's needed to compile this CoffeeScript file and serve it -as the compiled JavaScript. - -Filter multiple Files ---------------------- - -You can also combine multiple CoffeeScript files into a single output file: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/example.coffee' - '@AppBundle/Resources/public/js/another.coffee' - filter='coffee' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array( - '@AppBundle/Resources/public/js/example.coffee', - '@AppBundle/Resources/public/js/another.coffee', - ), - array('coffee') - ) as $url): ?> - - - -Both files will now be served up as a single file compiled into regular JavaScript. - -.. _assetic-apply-to: - -Filtering Based on a File Extension ------------------------------------ - -One of the great advantages of using Assetic is reducing the number of asset -files to lower HTTP requests. In order to make full use of this, it would -be good to combine *all* your JavaScript and CoffeeScript files together -since they will ultimately all be served as JavaScript. Unfortunately just -adding the JavaScript files to the files to be combined as above will not -work as the regular JavaScript files will not survive the CoffeeScript compilation. - -This problem can be avoided by using the ``apply_to`` option, which allows you -to specify which filter should always be applied to particular file extensions. -In this case you can specify that the ``coffee`` filter is applied to all -``.coffee`` files: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - coffee: - bin: /usr/bin/coffee - node: /usr/bin/node - node_paths: [/usr/lib/node_modules/] - apply_to: '\.coffee$' - - .. code-block:: xml - - - - - - - - /usr/lib/node_modules/ - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'coffee' => array( - 'bin' => '/usr/bin/coffee', - 'node' => '/usr/bin/node', - 'node_paths' => array('/usr/lib/node_modules/'), - 'apply_to' => '\.coffee$', - ), - ), - )); - -With this option, you no longer need to specify the ``coffee`` filter in the -template. You can also list regular JavaScript files, all of which will be -combined and rendered as a single JavaScript file (with only the ``.coffee`` -files being run through the CoffeeScript filter): - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/example.coffee' - '@AppBundle/Resources/public/js/another.coffee' - '@AppBundle/Resources/public/js/regular.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array( - '@AppBundle/Resources/public/js/example.coffee', - '@AppBundle/Resources/public/js/another.coffee', - '@AppBundle/Resources/public/js/regular.js', - ) - ) as $url): ?> - - diff --git a/frontend/assetic/asset_management.rst b/frontend/assetic/asset_management.rst deleted file mode 100644 index 1226dd38c36..00000000000 --- a/frontend/assetic/asset_management.rst +++ /dev/null @@ -1,691 +0,0 @@ -.. index:: - single: Assetic; Introduction - -How to Use Assetic for Asset Management -======================================= - -Installing and Enabling Assetic -------------------------------- - -Starting from Symfony 2.8, Assetic is no longer included by default in the -Symfony Standard Edition. Before using any of its features, install the -AsseticBundle executing this console command in your project: - -.. code-block:: bash - - $ composer require symfony/assetic-bundle - -Then, enable the bundle in the ``AppKernel.php`` file of your Symfony application:: - - // app/AppKernel.php - - // ... - class AppKernel extends Kernel - { - // ... - - public function registerBundles() - { - $bundles = array( - // ... - new Symfony\Bundle\AsseticBundle\AsseticBundle(), - ); - - // ... - } - } - -Finally, add the following minimal configuration to enable Assetic support in -your application: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - debug: '%kernel.debug%' - use_controller: '%kernel.debug%' - filters: - cssrewrite: ~ - - # ... - - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'debug' => '%kernel.debug%', - 'use_controller' => '%kernel.debug%', - 'filters' => array( - 'cssrewrite' => null, - ), - // ... - )); - - // ... - -Introducing Assetic -------------------- - -Assetic combines two major ideas: :ref:`assets ` and -:ref:`filters `. The assets are files such as CSS, -JavaScript and image files. The filters are things that can be applied to -these files before they are served to the browser. This allows a separation -between the asset files stored in the application and the files actually presented -to the user. - -Without Assetic, you just serve the files that are stored in the application -directly: - -.. configuration-block:: - - .. code-block:: html+twig - - - - .. code-block:: php - - - -But *with* Assetic, you can manipulate these assets however you want (or -load them from anywhere) before serving them. This means you can: - -* Minify and combine all of your CSS and JS files - -* Run all (or just some) of your CSS or JS files through some sort of compiler, - such as LESS, SASS or CoffeeScript - -* Run image optimizations on your images - -.. _assetic-assets: - -Assets ------- - -Using Assetic provides many advantages over directly serving the files. -The files do not need to be stored where they are served from and can be -drawn from various sources such as from within a bundle. - -You can use Assetic to process :ref:`CSS stylesheets `, -:ref:`JavaScript files ` and -:ref:`images `. The philosophy -behind adding either is basically the same, but with a slightly different syntax. - -.. _assetic-including-javascript: - -Including JavaScript Files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To include JavaScript files, use the ``javascripts`` tag in any template: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*') - ) as $url): ?> - - - -.. note:: - - If your application templates use the default block names from the Symfony - Standard Edition, the ``javascripts`` tag will most commonly live in the - ``javascripts`` block: - - .. code-block:: html+twig - - {# ... #} - {% block javascripts %} - {% javascripts '@AppBundle/Resources/public/js/*' %} - - {% endjavascripts %} - {% endblock %} - {# ... #} - -.. tip:: - - You can also include CSS stylesheets: see :ref:`assetic-including-css`. - -In this example, all files in the ``Resources/public/js/`` directory of the -AppBundle will be loaded and served from a different location. The actual -rendered tag might simply look like: - -.. code-block:: html - - - -This is a key point: once you let Assetic handle your assets, the files are -served from a different location. This *will* cause problems with CSS files -that reference images by their relative path. See :ref:`assetic-cssrewrite`. - -.. _assetic-including-css: - -Including CSS Stylesheets -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To bring in CSS stylesheets, you can use the same technique explained above, -except with the ``stylesheets`` tag: - -.. configuration-block:: - - .. code-block:: html+twig - - {% stylesheets 'bundles/app/css/*' filter='cssrewrite' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('bundles/app/css/*'), - array('cssrewrite') - ) as $url): ?> - - - -.. note:: - - If your application templates use the default block names from the Symfony - Standard Edition, the ``stylesheets`` tag will most commonly live in the - ``stylesheets`` block: - - .. code-block:: html+twig - - {# ... #} - {% block stylesheets %} - {% stylesheets 'bundles/app/css/*' filter='cssrewrite' %} - - {% endstylesheets %} - {% endblock %} - {# ... #} - -But because Assetic changes the paths to your assets, this *will* break any -background images (or other paths) that uses relative paths, unless you use -the :ref:`cssrewrite ` filter. - -.. note:: - - Notice that in the original example that included JavaScript files, you - referred to the files using a path like ``@AppBundle/Resources/public/file.js``, - but that in this example, you referred to the CSS files using their actual, - publicly-accessible path: ``bundles/app/css``. You can use either, except - that there is a known issue that causes the ``cssrewrite`` filter to fail - when using the ``@AppBundle`` syntax for CSS stylesheets. - -.. _assetic-including-image: - -Including Images -~~~~~~~~~~~~~~~~ - -To include an image you can use the ``image`` tag. - -.. configuration-block:: - - .. code-block:: html+twig - - {% image '@AppBundle/Resources/public/images/example.jpg' %} - Example - {% endimage %} - - .. code-block:: html+php - - image( - array('@AppBundle/Resources/public/images/example.jpg') - ) as $url): ?> - Example - - -You can also use Assetic for image optimization. More information in -:doc:`/frontend/assetic/jpeg_optimize`. - -.. tip:: - - Instead of using Assetic to include images, you may consider using the - `LiipImagineBundle`_ community bundle, which allows to compress and - manipulate images (rotate, resize, watermark, etc.) before serving them. - -.. _assetic-cssrewrite: - -Fixing CSS Paths with the ``cssrewrite`` Filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since Assetic generates new URLs for your assets, any relative paths inside -your CSS files will break. To fix this, make sure to use the ``cssrewrite`` -filter with your ``stylesheets`` tag. This parses your CSS files and corrects -the paths internally to reflect the new location. - -You can see an example in the previous section. - -.. caution:: - - When using the ``cssrewrite`` filter, don't refer to your CSS files using - the ``@AppBundle`` syntax. See the note in the above section for details. - -Combining Assets -~~~~~~~~~~~~~~~~ - -One feature of Assetic is that it will combine many files into one. This helps -to reduce the number of HTTP requests, which is great for front-end performance. -It also allows you to maintain the files more easily by splitting them into -manageable parts. This can help with re-usability as you can easily split -project-specific files from those which can be used in other applications, -but still serve them as a single file: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts - '@AppBundle/Resources/public/js/*' - '@AcmeBarBundle/Resources/public/js/form.js' - '@AcmeBarBundle/Resources/public/js/calendar.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array( - '@AppBundle/Resources/public/js/*', - '@AcmeBarBundle/Resources/public/js/form.js', - '@AcmeBarBundle/Resources/public/js/calendar.js', - ) - ) as $url): ?> - - - -In the ``dev`` environment, each file is still served individually, so that -you can debug problems more easily. However, in the ``prod`` environment -(or more specifically, when the ``debug`` flag is ``false``), this will be -rendered as a single ``script`` tag, which contains the contents of all of -the JavaScript files. - -.. tip:: - - If you're new to Assetic and try to use your application in the ``prod`` - environment (by using the ``app.php`` controller), you'll likely see - that all of your CSS and JS breaks. Don't worry! This is on purpose. - For details on using Assetic in the ``prod`` environment, see :ref:`assetic-dumping`. - -And combining files doesn't only apply to *your* files. You can also use Assetic to -combine third party assets, such as jQuery, with your own into a single file: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts - '@AppBundle/Resources/public/js/thirdparty/jquery.js' - '@AppBundle/Resources/public/js/*' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array( - '@AppBundle/Resources/public/js/thirdparty/jquery.js', - '@AppBundle/Resources/public/js/*', - ) - ) as $url): ?> - - - -Using Named Assets -~~~~~~~~~~~~~~~~~~ - -AsseticBundle configuration directives allow you to define named asset sets. -You can do so by defining the input files, filters and output files in your -configuration under the ``assetic`` section. Read more in the -:doc:`assetic config reference `. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - assets: - jquery_and_ui: - inputs: - - '@AppBundle/Resources/public/js/thirdparty/jquery.js' - - '@AppBundle/Resources/public/js/thirdparty/jquery.ui.js' - - .. code-block:: xml - - - - - - - - @AppBundle/Resources/public/js/thirdparty/jquery.js - @AppBundle/Resources/public/js/thirdparty/jquery.ui.js - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'assets' => array( - 'jquery_and_ui' => array( - 'inputs' => array( - '@AppBundle/Resources/public/js/thirdparty/jquery.js', - '@AppBundle/Resources/public/js/thirdparty/jquery.ui.js', - ), - ), - ), - )); - -After you have defined the named assets, you can reference them in your templates -with the ``@named_asset`` notation: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts - '@jquery_and_ui' - '@AppBundle/Resources/public/js/*' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array( - '@jquery_and_ui', - '@AppBundle/Resources/public/js/*', - ) - ) as $url): ?> - - - -.. _assetic-filters: - -Filters -------- - -Once they're managed by Assetic, you can apply filters to your assets before -they are served. This includes filters that compress the output of your assets -for smaller file sizes (and better frontend optimization). Other filters -can compile CoffeeScript files to JavaScript and process SASS into CSS. -In fact, Assetic has a long list of available filters. - -Many of the filters do not do the work directly, but use existing third-party -libraries to do the heavy-lifting. This means that you'll often need to install -a third-party library to use a filter. The great advantage of using Assetic -to invoke these libraries (as opposed to using them directly) is that instead -of having to run them manually after you work on the files, Assetic will -take care of this for you and remove this step altogether from your development -and deployment processes. - -To use a filter, you first need to specify it in the Assetic configuration. -Adding a filter here doesn't mean it's being used - it just means that it's -available to use (you'll use the filter below). - -For example to use the UglifyJS JavaScript minifier the following configuration -should be defined: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - uglifyjs2: - bin: /usr/local/bin/uglifyjs - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'uglifyjs2' => array( - 'bin' => '/usr/local/bin/uglifyjs', - ), - ), - )); - -Now, to actually *use* the filter on a group of JavaScript files, add it -into your template: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' filter='uglifyjs2' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array('uglifyjs2') - ) as $url): ?> - - - -A more detailed guide about configuring and using Assetic filters as well as -details of Assetic's debug mode can be found in :doc:`/frontend/assetic/uglifyjs`. - -Controlling the URL Used ------------------------- - -If you wish to, you can control the URLs that Assetic produces. This is -done from the template and is relative to the public document root: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' output='js/compiled/main.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array(), - array('output' => 'js/compiled/main.js') - ) as $url): ?> - - - -.. note:: - - Symfony provides various cache busting implementations via the - :ref:`version `, - :ref:`version_format `, and - :ref:`json_manifest_path ` - configuration options. - -.. _assetic-dumping: - -Dumping Asset Files -------------------- - -In the ``dev`` environment, Assetic generates paths to CSS and JavaScript -files that don't physically exist on your computer. But they render nonetheless -because an internal Symfony controller opens the files and serves back the -content (after running any filters). - -This kind of dynamic serving of processed assets is great because it means -that you can immediately see the new state of any asset files you change. -It's also bad, because it can be quite slow. If you're using a lot of filters, -it might be downright frustrating. - -Fortunately, Assetic provides a way to dump your assets to real files, instead -of being generated dynamically. - -Dumping Asset Files in the ``prod`` Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the ``prod`` environment, your JS and CSS files are represented by a single -tag each. In other words, instead of seeing each JavaScript file you're including -in your source, you'll likely just see something like this: - -.. code-block:: html - - - -Moreover, that file does **not** actually exist, nor is it dynamically rendered -by Symfony (as the asset files are in the ``dev`` environment). This is on -purpose - letting Symfony generate these files dynamically in a production -environment is just too slow. - -.. _assetic-dump-prod: - -Instead, each time you use your application in the ``prod`` environment (and therefore, -each time you deploy), you should run the following command: - -.. code-block:: terminal - - $ php bin/console assetic:dump --env=prod --no-debug - -This will physically generate and write each file that you need (e.g. ``/js/abcd123.js``). -If you update any of your assets, you'll need to run this again to regenerate -the file. - -Dumping Asset Files in the ``dev`` Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, each asset path generated in the ``dev`` environment is handled -dynamically by Symfony. This has no disadvantage (you can see your changes -immediately), except that assets can load noticeably slow. If you feel like -your assets are loading too slowly, follow this guide. - -First, tell Symfony to stop trying to process these files dynamically. Make -the following change in your ``config_dev.yml`` file: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config_dev.yml - assetic: - use_controller: false - - .. code-block:: xml - - - - - - - - - .. code-block:: php - - // app/config/config_dev.php - $container->loadFromExtension('assetic', array( - 'use_controller' => false, - )); - -Next, since Symfony is no longer generating these assets for you, you'll -need to dump them manually. To do so, run the following command: - -.. code-block:: terminal - - $ php bin/console assetic:dump - -This physically writes all of the asset files you need for your ``dev`` -environment. The big disadvantage is that you need to run this each time -you update an asset. Fortunately, by using the ``assetic:watch`` command, -assets will be regenerated automatically *as they change*: - -.. code-block:: terminal - - $ php bin/console assetic:watch - -The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior -versions, you had to use the ``--watch`` option of the ``assetic:dump`` -command for the same behavior. - -Since running this command in the ``dev`` environment may generate a bunch -of files, it's usually a good idea to point your generated asset files to -some isolated directory (e.g. ``/js/compiled``), to keep things organized: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' output='js/compiled/main.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array(), - array('output' => 'js/compiled/main.js') - ) as $url): ?> - - - -.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle diff --git a/frontend/assetic/jpeg_optimize.rst b/frontend/assetic/jpeg_optimize.rst deleted file mode 100644 index 8e6871163d1..00000000000 --- a/frontend/assetic/jpeg_optimize.rst +++ /dev/null @@ -1,310 +0,0 @@ -.. index:: - single: Assetic; Image optimization - -How to Use Assetic for Image Optimization with Twig Functions -============================================================= - -.. include:: /assetic/_standard_edition_warning.rst.inc - -Among its many filters, Assetic has four filters which can be used for on-the-fly -image optimization. This allows you to get the benefits of smaller file sizes -without having to use an image editor to process each image. The results -are cached and can be dumped for production so there is no performance hit -for your end users. - -Using Jpegoptim ---------------- - -`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic, make -sure to have it already installed on your system and then, configure its location -using the ``bin`` option of the ``jpegoptim`` filter: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - )); - -It can now be used from a template: - -.. configuration-block:: - - .. code-block:: html+twig - - {% image '@AppBundle/Resources/public/images/example.jpg' - filter='jpegoptim' output='/images/example.jpg' %} - Example - {% endimage %} - - .. code-block:: html+php - - image( - array('@AppBundle/Resources/public/images/example.jpg'), - array('jpegoptim') - ) as $url): ?> - Example - - -Removing all EXIF Data -~~~~~~~~~~~~~~~~~~~~~~ - -By default, the ``jpegoptim`` filter removes some meta information stored -in the image. To remove all EXIF data and comments, set the ``strip_all`` option -to ``true``: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - strip_all: true - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - 'strip_all' => 'true', - ), - ), - )); - -Lowering Maximum Quality -~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the ``jpegoptim`` filter doesn't alter the quality level of the JPEG -image. Use the ``max`` option to configure the maximum quality setting (in a -scale of ``0`` to ``100``). The reduction in the image file size will of course -be at the expense of its quality: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - max: 70 - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - 'max' => '70', - ), - ), - )); - -Shorter Syntax: Twig Function ------------------------------ - -If you're using Twig, it's possible to achieve all of this with a shorter -syntax by enabling and using a special Twig function. Start by adding the -following configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - twig: - functions: - jpegoptim: ~ - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - 'twig' => array( - 'functions' => array('jpegoptim'), - ), - )); - -The Twig template can now be changed to the following: - -.. code-block:: html+twig - - Example - -You can also specify the output directory for images in the Assetic configuration -file: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - twig: - functions: - jpegoptim: { output: images/*.jpg } - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - 'twig' => array( - 'functions' => array( - 'jpegoptim' => array( - 'output' => 'images/*.jpg', - ), - ), - ), - )); - -.. tip:: - - For uploaded images, you can compress and manipulate them using the - `LiipImagineBundle`_ community bundle. - -.. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html -.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle diff --git a/frontend/assetic/php.rst b/frontend/assetic/php.rst deleted file mode 100644 index 8571b99b0c0..00000000000 --- a/frontend/assetic/php.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. index:: - single: Front-end; Assetic, Bootstrap - -Combining, Compiling and Minimizing Web Assets with PHP Libraries -================================================================= - -.. include:: /assetic/_standard_edition_warning.rst.inc - -The official Symfony Best Practices recommend to use Assetic to -:doc:`manage web assets `, unless you are -comfortable with JavaScript-based front-end tools. - -Even if those JavaScript-based solutions are the most suitable ones from a -technical point of view, using pure PHP alternative libraries can be useful in -some scenarios: - -* If you can't install or use ``npm`` and the other JavaScript solutions; -* If you prefer to limit the amount of different technologies used in your - applications; -* If you want to simplify application deployment. - -In this article, you'll learn how to combine and minimize CSS and JavaScript files -and how to compile Sass files using PHP-only libraries with Assetic. - -Installing the Third-Party Compression Libraries ------------------------------------------------- - -Assetic includes a lot of ready-to-use filters, but it doesn't include their -associated libraries. Therefore, before enabling the filters used in this article, -you must install two libraries. Open a command console, browse to your project -directory and execute the following commands: - -.. code-block:: terminal - - $ composer require leafo/scssphp - $ composer require patchwork/jsqueeze - - -Organizing your Web Asset Files -------------------------------- - -This example will include a setup using the Bootstrap CSS framework, jQuery, FontAwesome -and some regular CSS and JavaScript application files (called ``main.css`` and -``main.js``). The recommended directory structure for this set-up looks like this: - -.. code-block:: text - - web/assets/ - ├── css - │   ├── main.css - │   └── code-highlight.css - ├── js - │   ├── bootstrap.js - │   ├── jquery.js - │   └── main.js - └── scss - ├── bootstrap - │   ├── _alerts.scss - │   ├── ... - │   ├── _variables.scss - │   ├── _wells.scss - │   └── mixins - │   ├── _alerts.scss - │   ├── ... - │   └── _vendor-prefixes.scss - ├── bootstrap.scss - ├── font-awesome - │   ├── _animated.scss - │   ├── ... - │   └── _variables.scss - └── font-awesome.scss - -Combining and Minimizing CSS Files and Compiling SCSS Files ------------------------------------------------------------ - -First, configure a new ``scssphp`` Assetic filter: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - scssphp: - formatter: 'Leafo\ScssPhp\Formatter\Compressed' - # ... - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'scssphp' => array( - 'formatter' => 'Leafo\ScssPhp\Formatter\Compressed', - ), - // ... - ), - )); - -The value of the ``formatter`` option is the fully qualified class name of the -formatter used by the filter to produce the compiled CSS file. Using the -compressed formatter will minimize the resulting file, regardless of whether -the original files are regular CSS files or SCSS files. - -Next, update your Twig template to add the ``{% stylesheets %}`` tag defined -by Assetic: - -.. code-block:: html+twig - - {# app/Resources/views/base.html.twig #} - - - - - - {% stylesheets filter="scssphp" output="css/app.css" - "assets/scss/bootstrap.scss" - "assets/scss/font-awesome.scss" - "assets/css/*.css" - %} - - {% endstylesheets %} - -This simple configuration compiles, combines and minifies the SCSS files into a -regular CSS file that's put in ``web/css/app.css``. This is the only CSS file -which will be served to your visitors. - -Combining and Minimizing JavaScript Files ------------------------------------------ - -First, configure a new ``jsqueeze`` Assetic filter as follows: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jsqueeze: ~ - # ... - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jsqueeze' => null, - // ... - ), - )); - -Next, update the code of your Twig template to add the ``{% javascripts %}`` tag -defined by Assetic: - -.. code-block:: html+twig - - - - {% javascripts filter="?jsqueeze" output="js/app.js" - "assets/js/jquery.js" - "assets/js/bootstrap.js" - "assets/js/main.js" - %} - - {% endjavascripts %} - - - - -This simple configuration combines all the JavaScript files, minimizes the contents -and saves the output in the ``web/js/app.js`` file, which is the one that is -served to your visitors. - -The leading ``?`` character in the ``jsqueeze`` filter name tells Assetic to only -apply the filter when *not* in ``debug`` mode. In practice, this means that you'll -see unminified files while developing and minimized files in the ``prod`` environment. diff --git a/frontend/assetic/uglifyjs.rst b/frontend/assetic/uglifyjs.rst deleted file mode 100644 index 89b39fd7b4a..00000000000 --- a/frontend/assetic/uglifyjs.rst +++ /dev/null @@ -1,334 +0,0 @@ -.. index:: - single: Assetic; UglifyJS - -How to Minify CSS/JS Files (Using UglifyJS and UglifyCSS) -========================================================= - -.. include:: /assetic/_standard_edition_warning.rst.inc - -`UglifyJS`_ is a JavaScript parser/compressor/beautifier toolkit. It can be used -to combine and minify JavaScript assets so that they require less HTTP requests -and make your site load faster. `UglifyCSS`_ is a CSS compressor/beautifier -that is very similar to UglifyJS. - -In this article, the installation, configuration and usage of UglifyJS is -shown in detail. UglifyCSS works pretty much the same way and is only -talked about briefly. - -Install UglifyJS ----------------- - -UglifyJS is available as a `Node.js`_ module. First, you need to `install Node.js`_ -and then, decide the installation method: global or local. - -Global Installation -~~~~~~~~~~~~~~~~~~~ - -The global installation method makes all your projects use the very same UglifyJS -version, which simplifies its maintenance. Open your command console and execute -the following command (you may need to run it as a root user): - -.. code-block:: terminal - - $ npm install -g uglify-js - -Now you can execute the global ``uglifyjs`` command anywhere on your system: - -.. code-block:: terminal - - $ uglifyjs --help - -Local Installation -~~~~~~~~~~~~~~~~~~ - -It's also possible to install UglifyJS inside your project only, which is useful -when your project requires a specific UglifyJS version. To do this, install it -without the ``-g`` option and specify the path where to put the module: - -.. code-block:: terminal - - $ cd /path/to/your/symfony/project - $ npm install uglify-js --prefix app/Resources - -It is recommended that you install UglifyJS in your ``app/Resources`` folder and -add the ``node_modules`` folder to version control. Alternatively, you can create -an npm `package.json`_ file and specify your dependencies there. - -Now you can execute the ``uglifyjs`` command that lives in the ``node_modules`` -directory: - -.. code-block:: terminal - - $ "./app/Resources/node_modules/.bin/uglifyjs" --help - -Configure the ``uglifyjs2`` Filter ----------------------------------- - -Now we need to configure Symfony to use the ``uglifyjs2`` filter when processing -your JavaScripts: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - uglifyjs2: - # the path to the uglifyjs executable - bin: /usr/local/bin/uglifyjs - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'uglifyjs2' => array( - // the path to the uglifyjs executable - 'bin' => '/usr/local/bin/uglifyjs', - ), - ), - )); - -.. note:: - - The path where UglifyJS is installed may vary depending on your system. - To find out where npm stores the ``bin`` folder, execute the following command: - - .. code-block:: terminal - - $ npm bin -g - - It should output a folder on your system, inside which you should find - the UglifyJS executable. - - If you installed UglifyJS locally, you can find the ``bin`` folder inside - the ``node_modules`` folder. It's called ``.bin`` in this case. - -You now have access to the ``uglifyjs2`` filter in your application. - -Configure the ``node`` Binary ------------------------------ - -Assetic tries to find the node binary automatically. If it cannot be found, you -can configure its location using the ``node`` key: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - # the path to the node executable - node: /usr/bin/nodejs - filters: - uglifyjs2: - # the path to the uglifyjs executable - bin: /usr/local/bin/uglifyjs - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'node' => '/usr/bin/nodejs', - 'uglifyjs2' => array( - // the path to the uglifyjs executable - 'bin' => '/usr/local/bin/uglifyjs', - ), - )); - -Minify your Assets ------------------- - -In order to apply UglifyJS on your assets, add the ``filter`` option in the -asset tags of your templates to tell Assetic to use the ``uglifyjs2`` filter: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' filter='uglifyjs2' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array('uglifyj2s') - ) as $url): ?> - - - -.. note:: - - The above example assumes that you have a bundle called AppBundle and your - JavaScript files are in the ``Resources/public/js`` directory under your - bundle. However you can include your JavaScript files no matter where they are. - -With the addition of the ``uglifyjs2`` filter to the asset tags above, you -should now see minified JavaScripts coming over the wire much faster. - -Disable Minification in Debug Mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Minified JavaScripts are very difficult to read, let alone debug. Because of -this, Assetic lets you disable a certain filter when your application is in -debug (e.g. ``app_dev.php``) mode. You can do this by prefixing the filter name -in your template with a question mark: ``?``. This tells Assetic to only -apply this filter when debug mode is off (e.g. ``app.php``): - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' filter='?uglifyjs2' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array('?uglifyjs2') - ) as $url): ?> - - - -To try this out, switch to your ``prod`` environment (``app.php``). But before -you do, don't forget to :ref:`clear your cache ` -and :ref:`dump your assetic assets `. - -.. tip:: - - Instead of adding the filters to the asset tags, you can also configure which - filters to apply for each file in your application configuration file. - See :ref:`assetic-apply-to` for more details. - -Install, Configure and Use UglifyCSS ------------------------------------- - -The usage of UglifyCSS works the same way as UglifyJS. First, make sure -the node package is installed: - -.. code-block:: terminal - - # global installation - $ npm install -g uglifycss - - # local installation - $ cd /path/to/your/symfony/project - $ npm install uglifycss --prefix app/Resources - -Next, add the configuration for this filter: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - uglifycss: - bin: /usr/local/bin/uglifycss - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'uglifycss' => array( - 'bin' => '/usr/local/bin/uglifycss', - ), - ), - )); - -To use the filter for your CSS files, add the filter to the Assetic ``stylesheets`` -helper: - -.. configuration-block:: - - .. code-block:: html+twig - - {% stylesheets 'bundles/App/css/*' filter='uglifycss' filter='cssrewrite' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('bundles/App/css/*'), - array('uglifycss'), - array('cssrewrite') - ) as $url): ?> - - - -Just like with the ``uglifyjs2`` filter, if you prefix the filter name with -``?`` (i.e. ``?uglifycss``), the minification will only happen when you're -not in debug mode. - -.. _`UglifyJS`: https://github.com/mishoo/UglifyJS -.. _`UglifyCSS`: https://github.com/fmarcia/UglifyCSS -.. _`Node.js`: https://nodejs.org/ -.. _`install Node.js`: https://nodejs.org/ -.. _`package.json`: http://browsenpm.org/package.json diff --git a/frontend/assetic/yuicompressor.rst b/frontend/assetic/yuicompressor.rst deleted file mode 100644 index 65efa9b7142..00000000000 --- a/frontend/assetic/yuicompressor.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. index:: - single: Assetic; YUI Compressor - -How to Minify JavaScripts and Stylesheets with YUI Compressor -============================================================= - -.. caution:: - - The YUI Compressor is `no longer maintained by Yahoo`_. That's why you are - **strongly advised to avoid using YUI utilities** unless strictly necessary. - Read :doc:`/frontend/assetic/uglifyjs` for a modern and up-to-date alternative. - -.. include:: /assetic/_standard_edition_warning.rst.inc - -Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets -so they travel over the wire faster, the `YUI Compressor`_. Thanks to Assetic, -you can take advantage of this tool very easily. - -Download the YUI Compressor JAR -------------------------------- - -The YUI Compressor is written in Java and distributed as a JAR. `Download the JAR`_ -from the Yahoo! website and save it to ``app/Resources/java/yuicompressor.jar``. - -Configure the YUI Filters -------------------------- - -Now you need to configure two Assetic filters in your application, one for -minifying JavaScripts with the YUI Compressor and one for minifying -stylesheets: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - # java: '/usr/bin/java' - filters: - yui_css: - jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar' - yui_js: - jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar' - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - // 'java' => '/usr/bin/java', - 'filters' => array( - 'yui_css' => array( - 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar', - ), - 'yui_js' => array( - 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar', - ), - ), - )); - -.. note:: - - Windows users need to remember to update config to proper Java location. - In Windows7 x64 bit by default it's ``C:\Program Files (x86)\Java\jre6\bin\java.exe``. - -You now have access to two new Assetic filters in your application: -``yui_css`` and ``yui_js``. These will use the YUI Compressor to minify -stylesheets and JavaScripts, respectively. - -Minify your Assets ------------------- - -You have YUI Compressor configured now, but nothing is going to happen until -you apply one of these filters to an asset. Since your assets are a part of -the view layer, this work is done in your templates: - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' filter='yui_js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array('yui_js') - ) as $url): ?> - - - -.. note:: - - The above example assumes that you have a bundle called AppBundle and your - JavaScript files are in the ``Resources/public/js`` directory under your - bundle. This isn't important however - you can include your JavaScript - files no matter where they are. - -With the addition of the ``yui_js`` filter to the asset tags above, you should -now see minified JavaScripts coming over the wire much faster. The same process -can be repeated to minify your stylesheets. - -.. configuration-block:: - - .. code-block:: html+twig - - {% stylesheets '@AppBundle/Resources/public/css/*' filter='yui_css' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('@AppBundle/Resources/public/css/*'), - array('yui_css') - ) as $url): ?> - - - -Disable Minification in Debug Mode ----------------------------------- - -Minified JavaScripts and stylesheets are very difficult to read, let alone -debug. Because of this, Assetic lets you disable a certain filter when your -application is in debug mode. You can do this by prefixing the filter name -in your template with a question mark: ``?``. This tells Assetic to only -apply this filter when debug mode is off. - -.. configuration-block:: - - .. code-block:: html+twig - - {% javascripts '@AppBundle/Resources/public/js/*' filter='?yui_js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*'), - array('?yui_js') - ) as $url): ?> - - - -.. tip:: - - Instead of adding the filter to the asset tags, you can also globally - enable it by adding the ``apply_to`` attribute to the filter configuration, for - example in the ``yui_js`` filter ``apply_to: "\.js$"``. To only have the filter - applied in production, add this to the ``config_prod`` file rather than the - common config file. For details on applying filters by file extension, - see :ref:`assetic-apply-to`. - -.. _`YUI Compressor`: http://yui.github.io/yuicompressor/ -.. _`Download the JAR`: https://github.com/yui/yuicompressor/releases -.. _`no longer maintained by Yahoo`: http://yuiblog.com/blog/2013/01/24/yui-compressor-has-a-new-owner/ diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst index 7cce1bb2144..746d53d971a 100644 --- a/frontend/custom_version_strategy.rst +++ b/frontend/custom_version_strategy.rst @@ -165,7 +165,7 @@ the :ref:`version_strategy ` option: .. code-block:: yaml - # app/config/config.yml + # config/packages/framework.yaml framework: # ... assets: @@ -173,7 +173,7 @@ the :ref:`version_strategy ` option: .. code-block:: xml - + ` option: .. code-block:: php - // app/config/config.php + // config/packages/framework.php use App\Asset\VersionStrategy\GulpBusterVersionStrategy; $container->loadFromExtension('framework', array( diff --git a/frontend/encore/cdn.rst b/frontend/encore/cdn.rst index 90650f285ad..3f42b20b84f 100644 --- a/frontend/encore/cdn.rst +++ b/frontend/encore/cdn.rst @@ -11,7 +11,7 @@ it in Encore: // ... Encore - .setOutputPath('web/build/') + .setOutputPath('public/build/') // in dev mode, don't use the CDN .setPublicPath('/build'); // ... diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst index a34396ff4bf..02ddacd7929 100644 --- a/frontend/encore/faq.rst +++ b/frontend/encore/faq.rst @@ -26,7 +26,7 @@ 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 +final, built assets (e.g. the ``public/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 @@ -48,7 +48,7 @@ and the built files. Your ``.gitignore`` file should include: /node_modules/ # whatever path you're passing to Encore.setOutputPath() - /web/build + /public/build You *should* commit all of your source asset files, ``package.json`` and ``yarn.lock``. @@ -64,7 +64,7 @@ like ``/myAppSubdir``), you just need to configure that when calling ``Encore.se Encore // ... - .setOutputPath('web/build/') + .setOutputPath('public/build/') - .setPublicPath('/build') + // this is your *true* public path @@ -117,7 +117,7 @@ But, instead of working, you see an error: This dependency was not found: - * respond.js in ./app/Resources/assets/js/app.js + * respond.js in ./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 diff --git a/frontend/encore/postcss.rst b/frontend/encore/postcss.rst index ddc5dabefcf..46dde48090a 100644 --- a/frontend/encore/postcss.rst +++ b/frontend/encore/postcss.rst @@ -46,7 +46,7 @@ You can also pass options to the `postcss-loader`_ by passing a callback: // ... + .enablePostCssLoader((options) => { + options.config = { - + path: 'app/config/postcss.config.js' + + path: 'config/postcss.config.js' + }; + }) ; diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index 49f1f3b71c2..2e3e5eb7b2d 100644 --- a/frontend/encore/simple-example.rst +++ b/frontend/encore/simple-example.rst @@ -33,12 +33,12 @@ Inside, use Encore to help generate your Webpack configuration. Encore // the project directory where all compiled assets will be stored - .setOutputPath('web/build/') + .setOutputPath('public/build/') // the public path used by the web server to access the previous directory .setPublicPath('/build') - // will create web/build/app.js and web/build/app.css + // will create public/build/app.js and public/build/app.css .addEntry('app', './assets/js/app.js') // allow sass/scss files to be processed diff --git a/frontend/encore/versioning.rst b/frontend/encore/versioning.rst index 49d389f68de..9ba5442ef2c 100644 --- a/frontend/encore/versioning.rst +++ b/frontend/encore/versioning.rst @@ -40,11 +40,11 @@ created in your ``outputPath`` directory: In your app, you need to read this file to dynamically render the correct paths in your ``script`` and ``link`` tags. If you're using Symfony, just activate the -``json_manifest_file`` versioning strategy in ``config.yml``: +``json_manifest_file`` versioning strategy: .. code-block:: yaml - # app/config/config.yml + # config/packages/framework.yaml framework: # ... assets: diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst index ea954471978..70c3bfa4066 100644 --- a/quick_tour/the_view.rst +++ b/quick_tour/the_view.rst @@ -261,10 +261,6 @@ Symfony provides the ``asset()`` function to deal with them easily: The ``asset()`` function looks for the web assets inside the ``public/`` directory. -If you store them in another directory, read -:doc:`this article ` -to learn how to manage web assets. - Using the ``asset()`` function, your application is more portable. The reason is that you can move the application root directory anywhere under your web root directory without changing anything in your template's code. diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst deleted file mode 100644 index a30ba7ef450..00000000000 --- a/reference/configuration/assetic.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. index:: - pair: Assetic; Configuration reference - -AsseticBundle Configuration ("assetic") -======================================= - -.. caution:: - - Assetic is no longer recommended to manage web assets in Symfony - applications. Instead, use :doc:`Webpack Encore `, which bridges - Symfony applications with modern JavaScript tools used to manage web assets. diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 853f027050d..4fce390afd5 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -11,13 +11,6 @@ application there could be more tags available provided by third-party bundles: ======================================== ======================================================================== Tag Name Usage ======================================== ======================================================================== -`assetic.asset`_ Register an asset to the current asset manager -`assetic.factory_worker`_ Add a factory worker -`assetic.filter`_ Register a filter -`assetic.formula_loader`_ Add a formula loader to the current asset manager -`assetic.formula_resource`_ Adds a resource to the current asset manager -`assetic.templating.php`_ Remove this service if PHP templating is disabled -`assetic.templating.twig`_ Remove this service if Twig templating is disabled `auto_alias`_ Define aliases based on the value of container parameters `console.command`_ Add a command `controller.argument_value_resolver`_ Register a value resolver for controller arguments such as ``Request`` @@ -52,182 +45,6 @@ Tag Name Usage `validator.initializer`_ Register a service that initializes objects before validation ======================================== ======================================================================== -assetic.asset -------------- - -**Purpose**: Register an asset with the current asset manager - -assetic.factory_worker ----------------------- - -**Purpose**: Add a factory worker - -A Factory worker is a class implementing ``Assetic\Factory\Worker\WorkerInterface``. -Its ``process($asset)`` method is called for each asset after asset creation. -You can modify an asset or even return a new one. - -In order to add a new worker, first create a class:: - - use Assetic\Asset\AssetInterface; - use Assetic\Factory\Worker\WorkerInterface; - - class MyWorker implements WorkerInterface - { - public function process(AssetInterface $asset) - { - // ... change $asset or return a new one - } - - } - -And then register it as a tagged service: - -.. configuration-block:: - - .. code-block:: yaml - - services: - App\Assetic\CustomWorker: - tags: [assetic.factory_worker] - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - use App\Assetic\CustomWorker; - - $container - ->register(CustomWorker::class) - ->addTag('assetic.factory_worker') - ; - -assetic.filter --------------- - -**Purpose**: Register a filter - -AsseticBundle uses this tag to register common filters. You can also use -this tag to register your own filters. - -First, you need to create a filter:: - - use Assetic\Asset\AssetInterface; - use Assetic\Filter\FilterInterface; - - class MyFilter implements FilterInterface - { - public function filterLoad(AssetInterface $asset) - { - $asset->setContent('alert("yo");' . $asset->getContent()); - } - - public function filterDump(AssetInterface $asset) - { - // ... - } - } - -Second, define a service: - -.. configuration-block:: - - .. code-block:: yaml - - services: - App\Assetic\CustomFilter: - tags: - - { name: assetic.filter, alias: my_filter } - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - use App\Assetic\CustomFilter; - - $container - ->register(CustomFilter::class) - ->addTag('assetic.filter', array('alias' => 'my_filter')) - ; - -Finally, apply the filter: - -.. code-block:: twig - - {% javascripts - '@AcmeBaseBundle/Resources/public/js/global.js' - filter='my_filter' - %} - - {% endjavascripts %} - -You can also apply your filter via the ``assetic.filters.my_filter.apply_to`` -config option as it's described here: :doc:`/frontend/assetic/apply_to_option`. -In order to do that, you must define your filter service in a separate xml -config file and point to this file's path via the ``assetic.filters.my_filter.resource`` -configuration key. - -assetic.formula_loader ----------------------- - -**Purpose**: Add a formula loader to the current asset manager - -A Formula loader is a class implementing -``Assetic\\Factory\Loader\\FormulaLoaderInterface`` interface. This class -is responsible for loading assets from a particular kind of resources (for -instance, twig template). Assetic ships loaders for PHP and Twig templates. - -An ``alias`` attribute defines the name of the loader. - -assetic.formula_resource ------------------------- - -**Purpose**: Adds a resource to the current asset manager - -A resource is something formulae can be loaded from. For instance, Twig -templates are resources. - -assetic.templating.php ----------------------- - -**Purpose**: Remove this service if PHP templating is disabled - -The tagged service will be removed from the container if the -``framework.templating.engines`` config section does not contain php. - -assetic.templating.twig ------------------------ - -**Purpose**: Remove this service if Twig templating is disabled - -The tagged service will be removed from the container if -``framework.templating.engines`` config section does not contain ``twig``. - auto_alias ---------- diff --git a/reference/index.rst b/reference/index.rst index 8dcd0ae955e..4ddda83f1f4 100644 --- a/reference/index.rst +++ b/reference/index.rst @@ -7,7 +7,6 @@ Reference Documents configuration/framework configuration/doctrine configuration/security - configuration/assetic configuration/swiftmailer configuration/twig configuration/monolog diff --git a/reference/map.rst.inc b/reference/map.rst.inc index cfc67ca0832..76a4c26e554 100644 --- a/reference/map.rst.inc +++ b/reference/map.rst.inc @@ -8,7 +8,6 @@ * :doc:`framework ` * :doc:`doctrine ` * :doc:`security ` - * :doc:`assetic ` * :doc:`swiftmailer ` * :doc:`twig ` * :doc:`monolog `