Twig Extensions Reference minor brush-up

Author: mpdude

.platform.app.yaml

@@ -56,5 +56,5 @@ hooks:
       # Platform.sh currently sets PIP_USER=1.
       export PIP_USER=
       pip install pip==9.0.1 wheel==0.29.0
-      pip install -r requirements.txt
+      pip install -r _build/.requirements.txt
       make -C _build html

requirements.txt renamed to _build/.requirements.txt

@@ -5,8 +5,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set BUILDDIR=.
+set ALLSPHINXOPTS=-c %BUILDDIR% -d %BUILDDIR%/doctrees %SPHINXOPTS% ..
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

_build/make.bat

@@ -332,3 +332,5 @@
 /deployment/tools /deployment
 /install/bundles /setup/bundles
 /form /forms
+/testing/simulating_authentication /testing/http_authentication
+/components/dependency_injection/autowiring /service_container/autowiring

_build/redirection_map

@@ -163,8 +163,9 @@ In this case you can specify that the ``coffee`` filter is applied to all
                     name="coffee"
                     bin="/usr/bin/coffee"
                     node="/usr/bin/node"
-                    apply_to="\.coffee$" />
-                    <assetic:node-paths>/usr/lib/node_modules/</assetic:node-path>
+                    apply-to="\.coffee$">
+                    <assetic:node-path>/usr/lib/node_modules/</assetic:node-path>
+                </assetic:filter>
             </assetic:config>
         </container>
 
@@ -174,10 +175,10 @@ In this case you can specify that the ``coffee`` filter is applied to all
         $container->loadFromExtension('assetic', array(
             'filters' => array(
                 'coffee' => array(
-                    'bin'      => '/usr/bin/coffee',
-                    'node'     => '/usr/bin/node',
+                    'bin'        => '/usr/bin/coffee',
+                    'node'       => '/usr/bin/node',
                     'node_paths' => array('/usr/lib/node_modules/'),
-                    'apply_to' => '\.coffee$',
+                    'apply_to'   => '\.coffee$',
                 ),
             ),
         ));

_images/quick_tour/web_debug_toolbar.png

@@ -411,7 +411,7 @@ configuration under the ``assetic`` section. Read more in the
                     ),
                 ),
             ),
-        );
+        ));
 
 After you have defined the named assets, you can reference them in your templates
 with the ``@named_asset`` notation:

_images/security/anonymous_wdt.png

@@ -113,7 +113,7 @@ to ``true``:
                 <assetic:filter
                     name="jpegoptim"
                     bin="path/to/jpegoptim"
-                    strip_all="true" />
+                    strip-all="true" />
             </assetic:config>
         </container>
 
@@ -217,7 +217,7 @@ following configuration:
                     name="jpegoptim"
                     bin="path/to/jpegoptim" />
                 <assetic:twig>
-                    <assetic:twig_function
+                    <assetic:function
                         name="jpegoptim" />
                 </assetic:twig>
             </assetic:config>
@@ -234,7 +234,6 @@ following configuration:
             ),
             'twig' => array(
                 'functions' => array('jpegoptim'),
-                ),
             ),
         ));
 
@@ -277,7 +276,7 @@ file:
                     name="jpegoptim"
                     bin="path/to/jpegoptim" />
                 <assetic:twig>
-                    <assetic:twig_function
+                    <assetic:function
                         name="jpegoptim"
                         output="images/*.jpg" />
                 </assetic:twig>
@@ -296,7 +295,7 @@ file:
             'twig' => array(
                 'functions' => array(
                     'jpegoptim' => array(
-                        output => 'images/*.jpg'
+                        'output' => 'images/*.jpg',
                     ),
                 ),
             ),
@@ -308,4 +307,4 @@ file:
     `LiipImagineBundle`_ community bundle.
 
 .. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html
-.. _`LiipImagineBundle`: http://knpbundles.com/liip/LiipImagineBundle
+.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle

_images/security/symfony_loggedin_wdt.png

@@ -99,7 +99,7 @@ First, configure a new ``scssphp`` Assetic filter:
                 http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
 
             <assetic:config>
-                <filter name="scssphp" formatter="Leafo\ScssPhp\Formatter\Compressed" />
+                <assetic:filter name="scssphp" formatter="Leafo\ScssPhp\Formatter\Compressed" />
                 <!-- ... -->
             </assetic:config>
         </container>
@@ -172,7 +172,7 @@ First, configure a new ``jsqueeze`` Assetic filter as follows:
                 http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
 
             <assetic:config>
-                <filter name="jsqueeze" />
+                <assetic:filter name="jsqueeze" />
                 <!-- ... -->
             </assetic:config>
         </container>

assetic/apply_to_option.rst

@@ -170,11 +170,11 @@ can configure its location using the ``node`` key:
 
         // app/config/config.php
         $container->loadFromExtension('assetic', array(
-            'node' => '/usr/bin/nodejs',
+            'node'      => '/usr/bin/nodejs',
             'uglifyjs2' => array(
-                    // the path to the uglifyjs executable
-                    'bin' => '/usr/local/bin/uglifyjs',
-                ),
+                // the path to the uglifyjs executable
+                'bin' => '/usr/local/bin/uglifyjs',
+            ),
         ));
 
 Minify your Assets

assetic/asset_management.rst

@@ -38,9 +38,9 @@ stylesheets:
             # java: '/usr/bin/java'
             filters:
                 yui_css:
-                    jar: '%kernel.root_dir%/Resources/java/yuicompressor.jar'
+                    jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar'
                 yui_js:
-                    jar: '%kernel.root_dir%/Resources/java/yuicompressor.jar'
+                    jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar'
 
     .. code-block:: xml
 
@@ -57,10 +57,10 @@ stylesheets:
             <assetic:config>
                 <assetic:filter
                     name="yui_css"
-                    jar="%kernel.root_dir%/Resources/java/yuicompressor.jar" />
+                    jar="%kernel.project_dir%/app/Resources/java/yuicompressor.jar" />
                 <assetic:filter
                     name="yui_js"
-                    jar="%kernel.root_dir%/Resources/java/yuicompressor.jar" />
+                    jar="%kernel.project_dir%/app/Resources/java/yuicompressor.jar" />
             </assetic:config>
         </container>
 
@@ -71,10 +71,10 @@ stylesheets:
             // 'java' => '/usr/bin/java',
             'filters' => array(
                 'yui_css' => array(
-                    'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
+                    'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar',
                 ),
                 'yui_js' => array(
-                    'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
+                    'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar',
                 ),
             ),
         ));

assetic/jpeg_optimize.rst

@@ -153,6 +153,31 @@ whereas they cannot access the container parameters:
 The only notable disadvantage of using constants for this kind of configuration
 values is that you cannot redefine them easily in your tests.
 
+Parameter Naming
+----------------
+
+.. best-practice::
+
+    The name of your configuration parameters should be as short as possible and
+    should include a common prefix for the entire application.
+
+Using ``app.`` as the prefix of your parameters is a common practice to avoid
+collisions with Symfony and third-party bundles/libraries parameters. Then, use
+just one or two words to describe the purpose of the parameter:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    parameters:
+        # don't do this: 'dir' is too generic and it doesn't convey any meaning
+        app.dir: '...'
+        # do this: short but easy to understand names
+        app.contents_dir: '...'
+        # it's OK to use dots, underscores, dashes or nothing, but always
+        # be consistent and use the same format for all the parameters
+        app.dir.contents: '...'
+        app.contents-dir: '...'
+
 Semantic Configuration: Don't Do It
 -----------------------------------
 

assetic/php.rst

@@ -335,7 +335,7 @@ To enable the security voter in the application, define a new service:
     # app/config/services.yml
     services:
         # ...
-        post_voter:
+        app.post_voter:
             class:      AppBundle\Security\PostVoter
             arguments: ['@security.access.decision_manager']
             public:     false

assetic/uglifyjs.rst

@@ -154,7 +154,7 @@ of the most common elements of a bundle:
     Houses configuration, including routing configuration (e.g. ``routing.yml``).
 
 ``Resources/views/``
-    Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
+    Holds templates organized by controller name (e.g. ``Random/index.html.twig``).
 
 ``Resources/public/``
     Contains web assets (images, stylesheets, etc) and is copied or symbolically
@@ -181,4 +181,4 @@ Learn more
 
     bundles/*
 
-_`third-party bundles`: http://knpbundles.com
+_`third-party bundles`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

assetic/yuicompressor.rst

@@ -81,8 +81,8 @@ bundle configuration would look like:
 
         <!-- app/config/config.xml -->
         <?xml version="1.0" ?>
-
         <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:acme-social="http://example.org/schema/dic/acme_social"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
@@ -218,18 +218,64 @@ This class can now be used in your ``load()`` method to merge configurations and
 force validation (e.g. if an additional option was passed, an exception will be
 thrown)::
 
+    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
+
     public function load(array $configs, ContainerBuilder $container)
     {
         $configuration = new Configuration();
 
         $config = $this->processConfiguration($configuration, $configs);
-        // ...
+        
+        // you now have these 2 config keys
+        // $config['twitter']['client_id'] and $config['twitter']['client_secret']
     }
 
 The ``processConfiguration()`` method uses the configuration tree you've defined
 in the ``Configuration`` class to validate, normalize and merge all the
 configuration arrays together.
 
+Now, you can use the ``$config`` variable to modify a service provided by your bundle.
+For example, imagine your bundle has the following example config:
+
+.. code-block:: xml
+
+    <!-- src/Acme/SocialBundle/Resources/config/services.xml -->
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <container xmlns="http://symfony.com/schema/dic/services"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://symfony.com/schema/dic/services
+            http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+        <services>
+            <service id="acme.social.twitter_client" class="Acme\SocialBundle\TwitterClient">
+                <argument></argument> <!-- will be filled in with client_id dynamically -->
+                <argument></argument> <!-- will be filled in with client_secret dynamically -->
+            </service>
+        </services>
+    </container>
+
+In your extension, you can load this and dynamically set its arguments::
+
+    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
+    // ...
+
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+    use Symfony\Component\Config\FileLocator;
+
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        $loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
+        $loader->load('services.xml');
+
+        $configuration = new Configuration();
+        $config = $this->processConfiguration($configuration, $configs);
+
+        $def = $container->getDefinition('acme.social.twitter_client');
+        $def->replaceArgument(0, $config['twitter']['client_id']);
+        $def->replaceArgument(1, $config['twitter']['client_secret']);
+    }
+
+
 .. tip::
 
     Instead of calling ``processConfiguration()`` in your extension each time you
@@ -253,9 +299,7 @@ configuration arrays together.
         }
 
     This class uses the ``getConfiguration()`` method to get the Configuration
-    instance. You should override it if your Configuration class is not called
-    ``Configuration`` or if it is not placed in the same namespace as the
-    extension.
+    instance.
 
 .. sidebar:: Processing the Configuration yourself
 

best_practices/configuration.rst

@@ -93,8 +93,9 @@ The same goes for routing files and some other resources.
 
     The overriding of resources only works when you refer to resources with
     the ``@FOSUserBundle/Resources/config/routing/security.xml`` method.
-    If you refer to resources without using the ``@BundleName`` shortcut, they
-    can't be overridden in this way.
+    You need to use the ``@BundleName`` shortcut when referring to resources
+    so they can be successfully overridden (except templates, which are
+    overridden in a different way, as explained in :doc:`/templating/overriding`).
 
 .. caution::
 

best_practices/security.rst

@@ -26,8 +26,7 @@ the bundle on the `Packagist.org`_ site.
 
 .. tip::
 
-    Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
-    archive of Symfony Bundles.
+    Looking for bundles? Try searching for `symfony-bundle topic on GitHub`_.
 
 2) Install the Bundle via Composer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -49,7 +48,7 @@ version, include it as the second argument of the `composer require`_ command:
 B) Enable the Bundle
 --------------------
 
-At this point, the bundle is installed in your Symfony project (in
+At this point, the bundle is installed in your Symfony project (e.g. 
 ``vendor/friendsofsymfony/``) and the autoloader recognizes its classes.
 The only thing you need to do now is register the bundle in ``AppKernel``::
 
@@ -119,14 +118,14 @@ of the bundle's configuration:
 
 The output will look like this:
 
-.. code-block:: text
+.. code-block:: yaml
 
     assetic:
         debug:                '%kernel.debug%'
         use_controller:
             enabled:              '%kernel.debug%'
             profiler:             false
-        read_from:            '%kernel.root_dir%/../web'
+        read_from:            '%kernel.project_dir%/web'
         write_to:             '%assetic.read_from%'
         java:                 /usr/bin/java
         node:                 /usr/local/bin/node
@@ -157,5 +156,5 @@ what to do next. Have fun!
 .. _their documentation: https://getcomposer.org/doc/00-intro.md
 .. _Packagist.org:       https://packagist.org
 .. _FOSUserBundle:       https://github.com/FriendsOfSymfony/FOSUserBundle
-.. _KnpBundles.com:      http://knpbundles.com/
 .. _`composer require`:  https://getcomposer.org/doc/03-cli.md#require
+.. _`symfony-bundle topic on GitHub`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories