Assetic Bundle Laravel Package

Getting Started

This repo is a fork of the long-deprecated symfony/assetic-bundle. It is a drop-in for Symfony 2.x-era projects, not a modern asset pipeline. Before anything else, open its composer.json and check the require block against your Symfony version and the bundle's namespace (Sanpi\... vs. the original Symfony\Bundle\AsseticBundle\...); the day-to-day API is identical to the original bundle, so the upstream AsseticBundle docs and the Assetic docs are your real reference.

Minimal setup:

1. composer require sanpi/assetic-bundle (and make sure the original symfony/assetic-bundle isn't also installed — they conflict).
2. Register the bundle in app/AppKernel.php (verify the class name from vendor/).
3. Enable and configure in app/config/config.yml:

assetic:
    debug:          "%kernel.debug%"
    use_controller: false      # true only in dev
    bundles:        [ AppBundle ]
    filters:
        cssrewrite: ~
        lessphp:    ~
        uglifyjs2:  { bin: /usr/local/bin/uglifyjs }

4. Use it in Twig and dump:

{% stylesheets 'bundles/app/css/*.css' filter='cssrewrite' output='css/app.css' %}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

php app/console assetic:dump --env=prod --no-debug

First use case: take a bundle's Resources/public/css and js trees, concatenate them into a single versioned output in web/, and run cssrewrite so relative url(...) references survive the move.

Implementation Patterns

In-template tags with conditional filters. The ? prefix means "apply only when debug is off," which is how most projects keep dev readable and prod minified in one template:

{% javascripts '@AppBundle/Resources/public/js/*.js' filter='?uglifyjs2' output='js/app.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

Named assets in config (preferred once more than one template consumes the same bundle):

assetic:
    assets:
        app_css:
            inputs:  ['bundles/app/css/*.css']
            filters: ['cssrewrite']
            output:  'css/app.css'

Then reference it as {{ asset('app_css') }} (and inside {% stylesheets '@app_css' %}), which keeps templates free of glob strings and makes the asset list greppable.

Filter chaining. Multiple filters are comma-separated and execute left to right: filter='less, cssrewrite, ?uglifycss'. Order matters — rewrite URLs after compilation, minify last.

Dev vs. prod serving.

• Dev: assetic.use_controller: true with the bundle's _assetic route serves compiled files on demand (no dump step; slower).
• Prod: use_controller: false, and dump as a deploy step: assetic:dump --env=prod --no-debug. Add --watch locally for incremental rebuilds.

Custom filters. Implement Assetic\Filter\FilterInterface, register the class as a service tagged assetic.filter with an alias, then use the alias in Twig/config like any built-in filter. This is the main extension point — it's how you wrap a project-specific preprocessor (e.g., a PostCSS or image-optimizer binary).

Deploy integration. Treat assetic:dump like cache:clear: run it after code sync and before cache warmup, with --env=prod --no-debug. Combine with output= filenames (e.g., hashed or version-suffixed) so you can set long Cache-Control headers on web/css and web/js.

Gotchas and Tips

• cssrewrite + @Bundle paths is the #1 footgun. The filter rewrites url(...) relative to the output location, so @AppBundle/Resources/public/css/app.css with url(../img/x.png) often produces broken paths. Stick to bundles/app/... web-relative paths, or verify the generated CSS byte-for-byte before shipping.
• Debug mode silently disables ? filters. Your local template output (individual <link> tags, unminified) differs from prod (single file, minified). Always eyeball the result of assetic:dump --env=prod — not just the dev page.
• Stale Assetic cache. Assets are cached under the kernel cache dir with filemtime checks; changing a filter binary or config doesn't always invalidate it. When output "doesn't change," clear app/cache/{dev,prod} and re-dump — then re-check.
• FilterException usually means a missing binary. lessc, uglifyjs, sass, java (for YUI) must be on PATH or configured via bin:. The exception body contains the process stderr; read it.
• use_controller: true is dev-only. It's slow, adds a route, and known to interact badly with ? debug filters. Never leave it on in prod.
• Bundle scanning cost. assetic.bundles controls which bundles are scanned for Resources/public; listing only your bundles avoids scanning vendor assets (some of which ship broken CSS that assetic:dump will choke on).
• Composer conflicts. The original bundle pins symfony/symfony to 2.x and conflicts with symfony/assetic-bundle; this fork won't work on Symfony 4+. If you're inheriting it, pin the exact commit and put a migration plan in writing.
• Zero stars / zero dependents is a signal. There's no community buffer if it breaks. For anything greenfield use Webpack Encore (Symfony 4–6.x) or AssetMapper (6.3+); for legacy projects, isolate the dependency and keep assetic:dump in your deploy scripts so the failure mode is obvious and repeatable.