README

Dashboards and reports for Symfony applications: figures contributed by any bundle, charts drawn without a script, reports exported, scheduled and delivered.

phil/reporting-bundle gathers what an application measures in one place. Any bundle, or the application itself, contributes a figure — orders taken, a renewal rate — as a MetricSource, and a series — visits by day, sales by category — as a SeriesSource. The configuration places them on dashboards; Twig components show a dashboard, a metric or a chart on any page, and an EasyAdmin back office shows a dashboard as one of its pages when EasyAdmin is installed.

The charts are HTML, CSS and SVG, never a script. An SVG image is drawn on the server by phil/svg-chart, with a title, a description that reads every value, and the table of its values beside it; bars of HTML and CSS are a table themselves; a table alone is a third rendering. A metric shows its value written in the reader's locale, and its change from the period before.

A report is a service with columns and rows, read row by row: exported to CSV, TSV or JSON, streamed as a download, written from the command line, or scheduled with Symfony Scheduler and delivered by Mailer or Notifier from a Messenger worker. A message carries an identifier only: the job, with its recipients and parameters, and the exported file wait in stores readable by their owner — the claim check.

It relies on the library phil/svg-chart to draw the images; Symfony UX, Messenger, Scheduler, Mailer, Notifier, Console and EasyAdmin are each used when they are installed.

Status

Part	State
`MetricSource`, `SeriesSource`: the data-source port, found by key	Implemented and tested
`Period`, `Metric`, `Series`, `SeriesSet`, with limits; `PeriodPreset`, counted in the configured time zone	Implemented and tested
Dashboards in the configuration, restricted to a role when one is named	Implemented and tested
`PhilReporting:Dashboard`, `:LiveDashboard`, `:Metric`, `:Chart` components	Implemented and tested
SVG, HTML and table renderings; a stylesheet on the tokens of PHIL UX, no inline style	Implemented and tested
`ReportDefinition`, `ReportFormat` (CSV, TSV, JSON), formula cells neutralised, rows bounded	Implemented and tested
`ReportQueue`, `RunReport`, the job and export stores of the claim check	Implemented and tested
The `phil_reporting` schedule of Symfony Scheduler	Implemented and tested
The `mail` and `notification` deliveries	Implemented and tested
`ReportResponses` downloads, `phil:reporting:export`, the EasyAdmin page	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements, enabling the bundle, the stylesheet.
Configuration	Every key of `phil_reporting`.
Sources	Contributing metrics and series, periods and limits.
Dashboards	The components, the renderings, their accessibility, EasyAdmin.
Reports	Definitions, formats, downloads, the command, schedules, deliveries and the claim check.
Extension points	What an application may replace or add, and when it is stable.
Testing	The bundle's tests, and testing code that uses it.
Reference	Every public type, with its role.

Quick start

use Phil\ReportingBundle\Application\Contract\MetricSource;
use Phil\ReportingBundle\Domain\ValueObject\Metric;
use Phil\ReportingBundle\Domain\ValueObject\Period;

final readonly class OrdersTaken implements MetricSource
{
    public function __construct(private OrderRepository $orders) {}

    public static function key(): string { return 'orders'; }

    public function title(): string { return 'Orders'; }

    public function metric(Period $period): Metric
    {
        return new Metric($this->orders->countBetween($period->start, $period->end));
    }
}

# config/packages/phil_reporting.yaml
phil_reporting:
    timezone: America/Toronto
    dashboards:
        sales:
            title: Sales
            periods: [last_30_days, this_month, last_month]
            widgets:
                - { metric: orders, compare: true }

<twig:PhilReporting:LiveDashboard name="sales" />

Requirements

PHP 8.5 or later, with intl, json, mbstring and sodium; Symfony 8.2.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

phil / reporting-bundle

Package info

Security

Statistics