New in Symfony 2.6: Smarter assets:install command

Contributed by
Roy Van Ginneken
in #11312.

The assets:install command is one of the trickiest things for Symfony newcomers. This command is used to install the web assets (CSS, JavaScript, images) for the production application. When executed without options, the command copies into web/ all the files found in the Resources/public/ directories of your application and bundles.

Although developers usually execute the command without any option, most of the time it's better to execute it with the --symlink option. This makes a symbolic link of your assets instead of actually copying their files. This means that any change in the content of the web assets will have immediate effect in the application.

The problem is that the --symlink option will throw an InvalidArgumentException if your system doesn't support symbolic links. That's why, starting from Symfony 2.6, the behavior of the assets:install command will be smarter. Now, when your system doesn't support symbolic links or if there is any other problem, the command will silently fall back to make a hard copy of the assets and it will inform you about this:

# make a hard copy of the assets in web/
$ php app/console assets:install

# if possible, make absolute symlinks in web/ if not, make a hard copy
$ php app/console assets:install --symlink

# if possible, make relative symlinks in web/ if not, make a hard copy
$ php app/console assets:install --symlink --relative

In short, starting from Symfony 2.6, the best practice is to always pass the --symlink option to the assets:install command.

This improvement was originally proposed by Ryan Weaver in the issue #11297 and it's part of the Symfony DX initiative. We'd like to thank the help provided by Andre Rømcke, from the eZ Publish community, Bruno Škvorc and Pascal Borreli.


@Javier: I don't think this description is accurate. The command still does not create symlinks unless you actually use the --symlink option. All that was changed is that, when you prefer symlinks via the option, it will now fall back to hard copies when symlinks do not work. This way people can use the symlink option even when symlinks might not be available and still reach the goal of having resources installed.
I understood the same as Tobias said but then read again and found out that --symlinks still has to be passed. In short, the command is smarter by only falling back to hardcopy if symlinking failed.

Why didn't you put --symlink automatic then ? And in another hand add the --hardcopy option.
@Tobias, thanks for reporting this error. I've just updated the blog post to reflect the new behavior with more precision. My mistake has been to follow the original description of the Ryan's issue instead of the actual code of the change. I will be more careful in future blog posts :)
@Arnaud, you are right and the content of the post has been updated since it was first published.

Regarding why is this behavior not enabled by default, I guess it has to do with the "backwards compatibility" policy. We cannot change this behavior in Symfony 2.x versions. That's why I've added a new proposal to the list of BC-breaks for Symfony 3:
To make the default be symlink (so you don't have to pass the --symlink argument), modify your composer.json file and add this under the "extra" key:
"symfony-assets-install": "symlink"
@Javier There is a typo in the examples. Remove the trailing 's' to --symlinkS ;)
@Pierre-Charles it's fixed now. Thanks for reporting this error!

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.