Important

You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Dynamic Assets

You can change assets during an application life cycle, for instance when an administrator is configuring your website. In this case, the assets cache should be busted properly. Symfony does not manage this case out-of-the-box but the Asset Component can be easily enhanced to support this feature.

The following samples of code show how to add dynamic versioning for any asset package.

For example, let us assume that acme asset package should use the dynamic versioning.

  1. First, register the package. Use Resources/config/oro/app.yml in your bundle or config/config.yml:

    framework:
    assets:
        packages:
            acme:
                version: %assets_version%
                version_format: ~ # use the default format

  2. Set DynamicAssetVersionStrategy for this package.

     1 <?php
 2
 3 namespace Acme\Bundle\SomeBundle;
 4
 5 use Symfony\Component\DependencyInjection\ContainerBuilder;
 6 use Symfony\Component\HttpKernel\Bundle\Bundle;
 7
 8 use Oro\Bundle\UIBundle\DependencyInjection\Compiler\DynamicAssetVersionPass;
 9
10 class AcmeSomeBundle extends Bundle
11 {
12     /**
13      * {@inheritdoc}
14      */
15     public function build(ContainerBuilder $container)
16     {
17         parent::build($container);
18
19         $container->addCompilerPass(new DynamicAssetVersionPass('acme'));
20     }
21 }

    The configuration is finished.

  3. Update the package version when your assets are changed:

     1 <?php
 2
 3 namespace Acme\Bundle\SomeBundle\Controller;
 4
 5 use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 6
 7 class SomeController extends Controller
 8 {
 9     public function updateAction()
10     {
11         ...
12
13         /** @var Oro\Bundle\UIBundle\Asset\DynamicAssetVersionManager $assetVersionManager */
14         $assetVersionManager = $this->get('oro_ui.dynamic_asset_version_manager');
15         $assetVersionManager->updateAssetVersion('acme');
16
17         ...
18     }
19 }

The usage of your assets is the same as other assets, for example by the well-known asset() Twig function:

1{{ asset('test.js', 'acme') }}
2{# the result may be something like this: test.js?version=123-2 #}
3{# where #}
4{# '123' is the static asset version specified in %assets_version% parameter #}
5{# '2' is the dynamic asset version; this number is increased each time you call $assetVersionManager->updateAssetVersion('acme') #}

Keep in mind that the package name should be passed to the asset() function. This tells Symfony that the asset belongs to your package and that dynamic versioning strategy should be applied.