Getting Started

Minimal Steps

Installation:

composer require braunstetter/assets-push-bundle

Add to config/bundles.php:

return [
    // ...
    Braunstetter\AssetsPushBundle\AssetsPushBundle::class => ['all' => true],
];

First Use Case: In a Twig template (e.g., templates/base.html.twig), register assets:

{% css '/path/to/file.css' %}
{% js '/path/to/script.js' %}

Then, in your layout or base template, render them in <head>:

{% block pushedJs %}
    {% for js in assets()['js'] %}
        <script src="{{ asset(js) }}"></script>
    {% endfor %}
{% endblock %}

Where to Look First

Twig Tags: Focus on {% css %} and {% js %} tags for asset registration.
assets() Function: Use this in your base template to render collected assets.
Configuration: Check config/packages/braunstetter_assets_push.yaml (if auto-generated) for customization.

Implementation Patterns

Workflows

Component-Based Asset Management:
- Register assets in reusable Twig components (e.g., components/breadcrumb.html.twig):
```
{% css 'bundles/app/css/breadcrumb.css' %}
{% js 'bundles/app/js/breadcrumb.js' %}
```
- Render them in the parent template via assets().

Dynamic Asset Loading:

Use assets() in controllers to conditionally push assets:

return $this->render('page.html.twig', [
    'extra_css' => ['/dynamic.css'],
    'extra_js' => ['/dynamic.js'],
]);

Pass arrays to Twig and loop in templates:

{% for css in extra_css %}
    {% css css %}
{% endfor %}

Base Template Integration:

Extend pushedJs and pushedCss blocks in child templates:

{% block pushedJs %}
    {{ parent() }}
    <script src="{{ asset('/child.js') }}"></script>
{% endblock %}

Integration Tips

Asset Versioning: Append ?v={{ env('APP_VERSION') }} to paths to bust caches:
```
{% css '/file.css?v=' ~ env('APP_VERSION') %}
```

Conditional Loading: Use Twig’s if to load assets only when needed:

{% if is_feature_enabled('analytics') %}
    {% js '/analytics.js' %}
{% endif %}

Symfony UX Integration: Combine with Stimulus for dynamic asset loading:
```
{% js '/stimulus.js' %}
{% js '/controllers/app_controller.js' %}
```

Gotchas and Tips

Pitfalls

Double Registration:

Assets pushed in both parent and child templates will appear twice. Use {% block %} to extend instead of re-pushing:

{% block pushedJs %}
    {{ parent() }}  {# Renders parent assets first #}
    <script src="{{ asset('/child.js') }}"></script>
{% endblock %}

Asset Path Resolution:
- Paths are relative to public/ by default. Use absolute paths (e.g., bundles/app/css/file.css) or asset() helper:
```
{% css asset('css/file.css') %}
```
Twig Cache Invalidation:
- Clear Twig cache after adding new asset tags:
```
php bin/console cache:clear --env=prod
```

Debugging

Inspect Collected Assets: Dump assets() in a template to verify registration:
```
{{ dump(assets()) }}
```
Check for Typos: Ensure {% css %} and {% js %} tags are closed properly (no trailing spaces or line breaks).

Extension Points

Custom Asset Types: Override the bundle’s AssetCollector service to support additional types (e.g., {% font %}):

# config/services.yaml
Braunstetter\AssetsPushBundle\AssetCollector:
    arguments:
        $supportedTypes: ['css', 'js', 'font']

Pre/Post-Processing: Extend the AssetCollector to modify paths or add attributes:

// src/EventSubscriber/AssetsSubscriber.php
public function onKernelRequest(GetResponseEvent $event)
{
    $assets = $event->getRequest()->attributes->get('assets', []);
    $assets['js'] = array_map(fn($path) => $path . '?defer', $assets['js']);
    $event->getRequest()->attributes->set('assets', $assets);
}

Environment-Specific Assets: Use Twig’s {% if app.environment == 'dev' %} to conditionally push assets:
```
{% if app.environment == 'dev' %}
    {% css '/dev-toolbar.css' %}
{% endif %}
```

Configuration Quirks

Disable for Specific Templates: Set assets_push_enabled: false in Twig’s context:
```
{% set _context.get('assets_push_enabled') = false %}
```
Custom Block Names: Override default block names (pushedJs, pushedCss) in config/packages/braunstetter_assets_push.yaml:
```
assets_push:
    js_block: 'custom_js'
    css_block: 'custom_css'
```

Assets Push Bundle Laravel Package