[Twig] [Twig Reference] Errors with asset_version function

[Sarah-eit]

Description

When using the asset_version function in a Twig template, errors occur if the path argument is not provided, which seems inconsistent with the documentation. Below are the details and the tests I performed.

Symfony version: 6.4.2

My configuration

framework:
    # ...
    assets:
        version: 'v1.0'
        packages:
            foo_package:
                base_path: /avatars
                version: 'v2.0'

Documentation reference

The documentation indicates that the asset_version function can be used as follows:

https://symfony.com/doc/6.4/reference/twig_reference.html#asset-version

asset_version

{{ asset_version(packageName = null) }}

packageName (optional)
    type: string | null default: null 

Tests performed

Test 1

{{ asset_version() }}

Result:

An exception has been thrown during the rendering of a template ("Too few arguments to function Symfony\Bridge\Twig\Extension\AssetExtension::getAssetVersion(), 0 passed in /var/www/skeleton/var/cache/dev/twig/b2/b215f70aff88988858d66fb176c34a10.php on line 222 and at least 1 expected").

Test 2

{{ asset_version(packageName = 'foo_package') }}

Result:

Value for argument "path" is required for function "asset_version".

Test 3

The image avatar.png is located in the public/avatars/ directory.

{{ asset_version(path = 'avatar.png', packageName = 'foo_package') }}

Expected Result: v2.0

Actual Result: v2.0

Investigation in Symfony code

While inspecting the Symfony codebase, I found the following:

AssetExtension.php (Symfony 6.4)

https://github.com/symfony/symfony/blob/6.4/src/Symfony/Bridge/Twig/Extension/AssetExtension.php

<?php

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <[email protected]>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Symfony\Bridge\Twig\Extension;

use Symfony\Component\Asset\Packages;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

/**
 * Twig extension for the Symfony Asset component.
 *
 * @author Fabien Potencier <[email protected]>
 */
final class AssetExtension extends AbstractExtension
{
    private Packages $packages;

    public function __construct(Packages $packages)
    {
        $this->packages = $packages;
    }

    public function getFunctions(): array
    {
        return [
            new TwigFunction('asset', $this->getAssetUrl(...)),
            new TwigFunction('asset_version', $this->getAssetVersion(...)),
        ];
    }

    /**
     * Returns the public url/path of an asset.
     *
     * If the package used to generate the path is an instance of
     * UrlPackage, you will always get a URL and not a path.
     */
    public function getAssetUrl(string $path, ?string $packageName = null): string
    {
        return $this->packages->getUrl($path, $packageName);
    }

    /**
     * Returns the version of an asset.
     */
    public function getAssetVersion(string $path, ?string $packageName = null): string
    {
        return $this->packages->getVersion($path, $packageName);
    }
}

The path parameter appears to be required in the getAssetVersion method. However, this requirement is not mentioned in the documentation.

Questions

Is this an issue with the documentation?
Should it explicitly state that the path parameter is mandatory?

Thank you in advance for your help!

[xabbuh]

Yes, this is a mistake in the documentation. The path argument must be documented similarly to how it is done for the asset() function above.

[Sarah-eit]

Thank you 👍
I'm going to make a fix.