Reports Bundle Laravel Package

Product Decisions This Supports

• Multi-region / multi-timezone reporting. v2.3.0 adds per-unit (Unidade) timezone handling, including passing the unit timezone through to the report Envelope and a follow-up fix for that propagation. For any roadmap item involving branches, stores, clinics, or service units spread across timezones, this release is what makes report timestamps and date-bucketing correct rather than silently server-local. This directly unblocks "regional operations dashboard" and "per-branch SLA/compliance reporting" style features without building custom timezone plumbing.
• Build vs. buy on the reporting layer. This bundle already owns report definition, envelope/dispatch, and rendering within the NovoSGA ecosystem. The timezone feature is a good example of the long-tail correctness work you would otherwise own: if you are evaluating building in-house reports, budget for exactly this class of fix (timezone, DST boundaries, per-tenant locale) and compare it against the cost of adopting this dependency.
• Platform modernization planning. The jump to Symfony 7.4 LTS plus symfony 7.4 deprecations cleanup is a scheduled-maintenance signal. It gives you a defensible version-support horizon and reduces the odds of being forced into an emergency framework upgrade mid-quarter. Use it to slot the dependency bump into a normal maintenance window rather than a scramble.
• Contributor velocity / sustainability. The dev-tool upgrade (PHPStan 2, PHPUnit 11, PHPCS 4) is not user-visible, but it is the leading indicator of whether this dependency will keep pace. Static analysis and test tooling at current majors is a reasonable proxy for "actively maintained, safe to depend on for another 12–18 months."
• Use cases this fits: queue/ticket management deployments already on NovoSGA that need branch-level reporting; internal operations tooling where report fidelity across locations matters more than pixel-perfect BI; teams that want reporting inside their existing PHP app rather than standing up a separate BI stack.
• What it does not decide for you: it is a Symfony bundle tied to the NovoSGA domain model (Unidade, Envelope), not a general-purpose Laravel reporting package. It does not answer "should we build a data warehouse" — it answers "should our branch-level reports be timezone-correct without custom code."

When to Consider This Package

Consider it when all of the following hold:

• You are running or integrating with NovoSGA (or a domain with a very similar unit/queue/service model). The value here is the domain integration, not a generic reporting API.
• You have users or units in more than one timezone, or you have a single timezone today but a roadmap that adds regions. The v2.3.0 change is the reason to move now; on a single-timezone deployment it is a correctness improvement with little visible benefit.
• You are on, or can get to, Symfony 7.x and are comfortable tracking an LTS cadence (7.4). This release assumes that baseline.
• You want reporting in-process in your PHP application, with the report envelope/dispatch lifecycle owned by the bundle, rather than exporting to an external BI tool.
• You value maintenance signals: recent tagged releases, modern static analysis and test tooling, an identifiable maintainer actively merging fixes (the Envelope timezone fix landed immediately after the feature, which is a good sign of responsiveness).

Look elsewhere when:

• You are on Laravel and expecting first-class Laravel idioms (service providers, Eloquent, Blade/Mail views, config/*.php publishing). This is a Symfony bundle; adopting it in Laravel means carrying Symfony components and adapting the domain model. The integration cost is real and should be scoped before you commit.
• You need a generic, framework-agnostic reporting engine with arbitrary data sources. The tight coupling to Unidade/Envelope becomes friction the moment your domain diverges.
• You need guaranteed long-term vendor support, SLAs, or a security response commitment. This is community-maintained; treat it as a dependency you own the risk on.
• Your reporting needs are heavy analytics (large fact tables, ad-hoc slicing, dashboards over millions of rows). This is operational reporting, not an analytics platform.
• You are timezone-naive and staying that way — the headline feature buys you nothing and you are taking on upgrade churn for no benefit.

Adoption criteria to verify before committing: confirm your Symfony version against the 7.4 requirement; confirm your Unidade-equivalent model maps cleanly or is extensible; run a spike that generates one report across a DST boundary in a non-UTC unit; and confirm you have an owner for the dependency bump each time Symfony ships a major.

How to Pitch It (Stakeholders)

For executives — one paragraph. This release closes a correctness gap in how our reports handle time. Until now, report timestamps were effectively tied to a single reference timezone; with v2.3.0 each operating unit carries its own timezone through to the report itself. Practically: a branch in São Paulo and a branch in Manaus now produce reports whose dates and times mean what they say, including across daylight-saving transitions. That removes a class of "the numbers don't match what the branch sees" incidents, and it is a prerequisite for any regional or per-branch performance reporting we put on the roadmap. The release also moves the underlying framework to a long-term-support version, which extends our support window and lowers the risk of a forced upgrade later.

For engineering — the substance. v2.3.0 is a minor release with no breaking changes: one feature (unit timezone threaded through the report Envelope), one immediate follow-up fix ensuring the timezone actually reaches the Envelope instance, a Symfony 7.1 → 7.4 LTS upgrade with deprecation cleanup, and dev-tooling bumps (PHPStan 2, PHPUnit 11, PHPCS 4). The work to schedule is the framework bump and its deprecation fallout, not the feature. Two things to validate in the upgrade: that our unit/Unidade configuration actually populates the new timezone field (otherwise the feature is inert and we get the old behavior silently), and that any downstream report consumers or stored report payloads are not assuming a single timezone. If we extend or override the Envelope, confirm the propagation fix covers our path. The dev-tooling upgrades mean our CI gates will likely tighten — expect some new static-analysis findings on first run and plan a small cleanup allowance.

The ask. Approve a scoped upgrade spike (one engineer, roughly a day): bump the dependency, set a non-UTC timezone on a test unit, generate a report spanning a DST change, and confirm the output. If it passes, fold it into the next maintenance window and add per-unit timezone configuration to the regional reporting initiative's acceptance criteria.