Report Bundle Laravel Package

Getting Started

Treat this as legacy-only. sylius/report-bundle is an archived, read-only subtree split of the Sylius monorepo, so a Laravel developer's realistic "day one" is either (a) maintaining an existing Sylius install that already has it, or (b) reading it for one hour to steal its domain model before building a Laravel-native equivalent. Do not composer require it into a Laravel app: it is a Symfony bundle and assumes a Sylius kernel, Doctrine, Twig, and the admin grid stack.

If you are on a legacy Sylius install that already depends on it:

1. Confirm it is in composer.json and in the bundle registration (config/bundles.php on Symfony Flex, AppKernel::registerBundles() on older versions). Only register it if it is already a locked dependency — never add it fresh.
2. Import the bundle's admin routing inside your admin routing file (typically @SyliusReportBundle/Resources/config/routing.yml).
3. Verify the report table (sylius_report-style entity) exists via your migrations or Doctrine schema tool; the bundle does not ship a Laravel migration.
4. Clear the container cache (bin/console cache:clear) after touching registration or service tags.

Where to look first, in order:

• Model/Report — the actual contract. A report is a named row holding a data fetcher string alias, a renderer string alias, and some serialized configuration.
• DataFetcher/ and Renderer/ — the only two extension points you will realistically touch. This is where the bundle's value lives.
• DependencyInjection/ — find the compiler pass that collects tagged fetchers/renderers. That tag name is the real public API; read it rather than guessing.
• Resources/config/ — service wiring plus any shipped fetchers/renderers.
• Resources/views/ and Resources/translations/ — what you override for presentation.

First use case: reproduce a trivial sales or registration report end-to-end. Create a report record (admin UI, fixture, or data migration), point it at a shipped fetcher and renderer, and confirm the admin list and report view render without template errors. That one loop teaches the entire bundle: fetcher produces data, renderer consumes it, the entity binds them by string alias.

Implementation Patterns

The core loop is: resolve report by code → resolve fetcher by alias → fetch data → resolve renderer by alias → render. Everything else in the bundle is plumbing around that sentence.

Custom data fetcher:

• Implement DataFetcherInterface (check the vendored copy for the exact signature; broadly it receives the Report and returns something the renderer can consume).
• Constructor-inject repositories and query builders. Never pull from the container inside the fetcher — the Sylius container will happily let you, and it will bite you during tests and cache warmup.
• Return a deliberately dumb shape: an array of rows plus totals. Query objects and ORM entities leak behavior into the renderer and make it untestable.
• Register the service with the bundle's fetcher tag (read the compiler pass for the exact string) and a stable alias. That alias is what you store on the report record.

Custom renderer:

• Implement RendererInterface, inject Twig, render a template you own.
• Keep it stateless: no queries, no aggregation, no business logic. If it needs derived values, compute them in the fetcher.
• Register with the renderer tag and alias, then reference that alias from the report record.

Seeding reports without the admin UI:

• A report is just configuration: code, name, dataFetcher alias, renderer alias, and serialized options. Seed them in a fixture or data migration when the admin screens are unreliable.
• Always set a stable code so you can load reports by code from your own controllers, console commands, or exporters.

Reusing reports outside the admin:

• Load the report by code from the repository, then resolve the fetcher and renderer by alias from the tagged service collection. Do not assume the report is only reachable via the admin route — the same fetch/render pipeline is usable from a console command or a scheduled job.
• If you need exports (CSV, XLSX) the bundle does not give you, add a renderer implementation that writes to a stream instead of a Twig template. This is the cleanest extension point.

If your real goal is a Laravel-native reporting module, mine this codebase for the vocabulary rather than the code: report definition, data source, filters, permissions, renderer, exporter, scheduler. Then implement it against Laravel primitives — queued generation for heavy queries, cached output keyed by report code plus filter hash, Eloquent/query builder fetchers behind an interface, Blade/API resources for renderers, and explicit policy classes for row-level access.

Gotchas and Tips

• Framework mismatch is the blocker, not the code. The bundle will not boot outside a Sylius kernel. Any "just install it in Laravel" plan ends in embedding Symfony components or running a second Symfony service — neither is worth it for an archived package with 6 stars and zero dependents.
• Archived means no patch path. The repo is a read-only split of Sylius/Sylius; issues and PRs filed here go nowhere. Any bug you hit is your bug. Plan an exit, not a fork.
• Tag names are not a public API. The compiler pass tag strings are internal to the monorepo. Read them from DependencyInjection/ in your vendored copy and pin your version; do not copy tag strings from blog posts or older docs.
• Report data is not a snapshot. These are live ORM queries. Two runs can produce different numbers, and totals may not reconcile with the rows you render if the underlying data changes mid-request. If users compare reports, capture the run timestamp and consider materializing results.
• Query timeouts and memory on export. Large reports will time out or exhaust memory on the web request. Use queued generation and cached outputs even in the legacy install; the bundle does not do this for you.
• String aliases bite silently. A typo in the fetcher or renderer alias on a report record produces a container lookup failure, not a validation error. Validate aliases when seeding reports and assert them in a test.
• Serialized options are schema-less. Report configuration is stored as a blob; changes to your fetcher's options will not migrate existing report rows. Guard with defaults in the fetcher and treat missing keys as configuration errors you surface explicitly.
• Template overrides win over bundle views by path convention (Sylius/Symfony override resolution). When an admin report view breaks, check your app's override directory before the bundle's Resources/views/.
• Extension points that actually exist: the fetcher tag, the renderer tag, and the bundle's controller/service wiring. Almost everything else is internal — fight the framework here and you will lose the next upgrade.
• Debugging order when a report renders blank: verify the alias resolves in the container (debug the tagged service list), then call the fetcher directly from a console command, then call the renderer with canned data, then look at the Twig template. Isolate the stage rather than debugging the whole pipeline at once.
• For the Laravel product, the honest call: do not adopt. Read Model/Report, the fetcher interface, and the renderer interface, then rebuild the ~200 lines of pattern you actually want. You will get queueing, caching, caching invalidation, and Laravel auth policies — none of which this bundle has — for less effort than isolating a dead Symfony subtree.