Download the PHP package chamber-orchestra/view-bundle without Composer

ChamberOrchestra View Bundle

A Symfony bundle that provides a typed view layer for JSON API responses. Define response shapes as PHP classes, return them from controllers, and let the bundle handle serialization automatically — no manual JsonResponse construction needed.

Built for Symfony 8.0 and PHP 8.5+, the bundle eliminates boilerplate in REST API controllers by introducing view models with automatic property binding, collection mapping, and production-ready cache warming.

Key Features

• Typed view models — define JSON response structures as PHP classes with typed properties
• Automatic property binding — BindView maps domain object properties to view properties via reflection
• Collection mapping — IterableView transforms arrays and iterables with typed element views
• Null stripping — null values are automatically excluded from serialized JSON output
• Build-time cache warming — pre-computed metadata and property mappings eliminate reflection overhead in production
• Build-versioned caching — cache files are tied to container.build_id for zero-downtime deployments
• Doctrine proxy support — transparent lazy-load initialization before property access

Requirements

• PHP 8.5+
• Symfony 8.0 components (http-kernel, serializer, property-access, dependency-injection, config, framework-bundle)
• doctrine/common ^3.5

Installation

Enable the bundle in config/bundles.php:

Quick Start

Define a view model that maps properties from a domain object:

Return the view from a controller — the bundle converts it to a JsonResponse automatically:

ViewSubscriber converts any ViewInterface result into a JsonResponse. Non-view results pass through unchanged.

View Types

BindView Property Binding

BindView uses BindUtils to synchronize properties between source objects and view instances. It handles:

• Built-in PHP types and custom objects
• ViewInterface subclasses (auto-constructed)
• IterableView properties with #[Type(ViewClass::class)] attribute for typed collections
• Skips union types and incompatible type pairs

Architecture

Request/Response Flow

1. SetVersionSubscriber (priority 256) — injects the DI-managed BindUtils instance into BindView via BindView::setBindUtils()
2. Controller returns a ViewInterface object
3. ViewSubscriber — detects ViewInterface results, wraps non-ResponseViewInterface in DataView, serializes to JSON via ViewNormalizer

View Auto-Discovery

Views implementing ViewInterface are automatically tagged with chamber_orchestra.view via #[AutoconfigureTag]. The ViewPass compiler pass collects these classes and passes them to cache warmers for pre-computation.

Performance Optimizations

The bundle includes a two-phase optimization strategy for production environments:

Phase 1: Runtime Metadata Caching

• ViewMetadataFactory caches property metadata in memory
• Direct property access eliminates repeated reflection calls
• 30-50% faster normalization on repeated calls

Phase 2: Build-Time Cache Warming

• ViewMetadataCacheWarmer pre-computes view property metadata at build time
• BindUtilsCacheWarmer pre-computes property mappings (uses #[BindsFrom] for targeted source classes, falls back to N² pairs)
• Generated opcache-optimized PHP files stored in kernel.share_dir
• Cache files are versioned with container.build_id for safe deployments
• 60-80% reduction in reflection overhead on production requests
• Automatic fallback to reflection when warmed cache is unavailable

Cache Configuration

BindUtils is registered as a DI service with $buildId, $debug, and $shareDir constructor arguments. When APP_DEBUG=false, property accessor caching is enabled with a 24-hour lifetime. SetVersionSubscriber injects the configured instance into BindView on each request.

Warm the cache in production:

This generates build-versioned files in the shared cache directory:

• View property metadata (nullability, defaults, types)
• View-to-view property mappings for BindUtils

Benchmarks

PHPBench benchmarks are included to measure serialization performance and cache impact:

Benchmark classes: BindUtilsBench, CacheWarmupBench, NormalizationBench.

Development

License

MIT