Download the PHP package toppy/symfony-async-twig-bundle without Composer

Async Twig Bundle

Read-Only Repository This is a read-only subtree split from the main repository. Please submit issues and pull requests to toppynl/symfony-astro.

Symfony integration bundle for the async Twig rendering stack. This is Layer 3 of the Toppy architecture, providing the bridge between Symfony's service container, request handling, and the framework-agnostic async rendering packages. The bundle auto-configures view models, sets up profiler integration, and provides request-aware context factories for the islands architecture.

Installation

The bundle is auto-registered via Symfony Flex. If not using Flex, add it manually:

Requirements

• PHP 8.4+
• Symfony 6.4, 7.0, or 8.0
• toppy/async-view-model (required)
• toppy/twig-view-model (required)
• toppy/twig-streaming (optional, for streaming features)
• toppy/twig-prerender (optional, for prerender modifiers)

Quick Start

With zero configuration, the bundle enables core view model functionality:

Create a view model:

Use it in templates:

Architecture

Key Classes

Compiler Passes

Service Configuration

The bundle auto-configures services via tags:

View models are collected into a ServiceLocator for lazy loading, and the ViewModelManager uses this locator to resolve view models on demand.

Configuration

Bundle Configuration

View Model Registration

View models are automatically discovered and registered when they implement AsyncViewModel:

For view models with dependencies on other view models, implement WithDependencies:

The ViewModelDependencyValidationPass detects circular dependencies at container compile time, failing the build rather than causing runtime errors.

Usage

In Controllers

Return a StreamedResponse with the streaming template renderer:

For non-streaming responses, use standard Twig rendering - view models still resolve in parallel:

In Templates

The view() function retrieves resolved view model data:

Context from Symfony Request

The ContextFactory creates contexts from the current Symfony request:

The ContextResolver is request-scoped and implements ResetInterface for FrankenPHP worker mode:

Profiler Integration

When profiler.enabled is true, the bundle registers data collectors for the Symfony Web Profiler:

Web Debug Toolbar

The toolbar shows:

• Number of resolved view models
• Total resolution time
• Parallel efficiency percentage

Profiler Panels

ViewModels Panel (toppy.view_model):

• List of all resolved view models
• Resolution status (success, error, cached, stale)
• Timing information (start, duration)
• Dependencies between view models

Streaming Panel (toppy.streaming):

• Unified timeline of all events
• Template enter/leave events
• Block enter/leave events
• View model resolution events
• HTTP request events (if HttpClientProfiler is available)
• Key markers (First Template, All Data Ready, Response Complete)

HTTP Client Panel (toppy.http_client):

• Outgoing HTTP requests made during view model resolution
• Status codes, timing, URLs

The profilers implement LateDataCollectorInterface because StreamedResponse callbacks execute after kernel.response. Data is collected at kernel.terminate.

Streaming Response with Debug Toolbar

The StreamedResponseWebDebugToolbarListener injects the web debug toolbar into streamed responses by appending the toolbar JS after the stream completes. This preserves streaming benefits while maintaining debugging capabilities.

Cache Layer

Enable stale-while-revalidate caching for view models:

View models can define cache behavior:

Cache Invalidation

When invalidation.enabled is true, an endpoint is available at /_cache/invalidate:

OpenTelemetry Integration

When open-telemetry/api is installed and a TracerInterface is available, the OpenTelemetryCompilerPass automatically decorates the profiler to emit spans for view model resolution.

Early Hints Providers

Implement EarlyHintsProviderInterface to add resources to HTTP 103 Early Hints:

The bundle includes ImportMapEarlyHintsProvider for Symfony AssetMapper integration.

Integration

This bundle sits at the top of the dependency graph:

The bundle consolidates service definitions from all packages:

• async-view-model: ViewModelManager, profiler interfaces, context abstractions
• twig-view-model: ViewExtension, ViewModelRuntime
• twig-streaming: SlotRegistry, StreamingTemplateRenderer, EarlyHints
• twig-prerender: PrerenderExtension, ContextEncryptor

Testing

Key test areas:

• Configuration validation (Tests/DependencyInjection/ConfigurationTest.php)
• Profiler data collection (Tests/Unit/Profiler/)
• Cache implementation (Tests/Unit/Cache/)
• Controller responses (Tests/Unit/Controller/)

License

Proprietary - see the main repository for license details.