Reports Bundle Laravel Package

Technical Evaluation

Architecture fit. novosga/reports-bundle is a Symfony bundle, not a Laravel package. It ships no ServiceProvider, no publishable config, no facade, and its bootstrap path assumes a Symfony Kernel, DI container, and event dispatcher. It is also domain-coupled: Unidade is a NovoSGA concept (an organizational service unit), and Envelope here refers to the mail/message abstraction the bundle populates when emitting reports. That means the package cannot be dropped into a Laravel application as-is — it is consumable only as (a) a component inside a Symfony/NovoSGA service we operate alongside Laravel, or (b) a source of report-generation logic we adapt behind our own boundary. Assessed as a Laravel dependency, fit is poor; assessed as a PHP/Symfony service dependency, fit is good.

Integration feasibility. High if scoped as a sidecar service exposing report endpoints; low as an in-process library. The substantive change in v2.3.0 is correct and valuable: report envelopes now carry the unit's timezone (feat: Unidade timezone → fix: pass unit timezone to Envelope instance). For any multi-region deployment this fixes a real class of defect — reports and their delivery timestamps rendered in server-local time rather than the unit's local time. The remaining items are housekeeping: Symfony 7.1 → 7.4 LTS and dev-tool majors (PHPStan 2, PHPUnit 11, PHPCS 4), plus deprecation cleanup.

Technical risk. Moderate, concentrated in three places:

1. Symfony floor lift. 7.4 is an LTS with a long security runway, which is a net positive, but the upgrade removes 7.1-era deprecated APIs. Any host app or sibling bundle pinned below 7.4 will now conflict at the Composer level. This is a minor version bump that is effectively mandatory-upgrade for the transitive graph.
2. Dev-tool majors are not runtime-neutral for us. PHPStan 2 and PHPUnit 11 raise the bar for any fork, patch, or in-house extension we maintain; CI will go red on code that previously passed.
3. Feature-then-fix in the same release. PR #8 introduced unit timezone, PR #9 corrected its propagation to Envelope. Shipping both together is fine for consumers, but it signals the initial PR lacked a test asserting the envelope actually received the timezone — worth confirming a regression test exists now, since a silent timezone bug is exactly the kind that surfaces as wrong data in a customer-facing report rather than an exception.

Key questions.

• Do we consume this in-process anywhere, or only via a NovoSGA service we call over HTTP? This determines whether the Symfony floor matters to us.
• What is the package's declared PHP floor and symfony/* constraint range in composer.json for v2.3.0?
• Is there a test (unit or fixture-based) that pins Envelope timezone propagation across a DST boundary, not just a fixed offset?
• Does the unit timezone change the stored timestamp semantics, or only the rendered one? If stored, this is a data-migration question, not a display question.
• Who besides the single named maintainer has merge rights? Bus factor appears to be 1.

Integration Approach

Stack fit. PHP 8.2+ with Symfony 7.4. Laravel 11/12 already runs Symfony 7.x components transitively, so component-level version alignment is plausible — but alignment of symfony/* is not the same as bootstrapping a bundle. Do not plan on composer require inside a Laravel app and expecting it to register.

Migration path. Treat v2.2.3 → v2.3.0 as a minor bump with a hard transitive floor. The public API surface appears unchanged (no removals listed), so the practical migration is: bump the constraint, resolve the Symfony 7.4 floor across the graph, fix deprecation warnings surfaced by the new PHPStan rules, then verify report output. If we are on 7.1–7.3 anywhere in the same graph, that upgrade is the real work item, not this bundle.

Compatibility. Two gates: (1) the host application must be able to move to Symfony 7.4 without dragging an incompatible sibling bundle; (2) our static-analysis and test tooling must tolerate PHPStan 2 / PHPUnit 11, or we isolate the package's CI from ours. The timezone feature also implies configuration surface — every Unidade now needs a valid timezone identifier, so check what the fallback is for units with none set.

Sequencing.

1. Inventory where the bundle is actually reached (direct dependency, sidecar image, or not at all). If not at all, stop here.
2. Bump in a branch; run composer why-not against the Symfony 7.4 constraint to size the blast radius.
3. Validate timezone behaviour with fixtures: a unit in a DST-observing zone, a report generated near the transition, and a fixed-offset zone as control. Assert on both rendered report output and envelope metadata.
4. Confirm no stored-timestamp semantics changed; if they did, gate the release behind a data backfill plan.
5. Roll to staging, then production behind the existing report path, with a comparison of pre/post output for one representative unit.

Operational Impact

Maintenance. Upstream is active and disciplined about chore work — LTS upgrade and deprecation cleanup landed promptly, which is a good signal for a small project. The offsetting concern is concentration: one maintainer authored every PR in this release. We should assume we may need to patch or fork, and budget accordingly. Dev-tool majors increase our cost to keep a fork green.

Support. Symfony 7.4 LTS gives a multi-year security runway, which materially de-risks the dependency for the next planning horizon. That is the strongest argument for taking this release rather than deferring.

Scaling. The change is configuration-driven per unit, not per request — negligible runtime cost, no new I/O, no new external dependency. It scales fine; the scaling question is organizational (how many unit timezones must be curated and kept correct), not technical.

Failure modes.

• Wrong-timezone reports: unit with unset or invalid timezone silently falls back to server default — same symptom as the bug being fixed, but harder to spot because the feature appears present.
• Envelope misdelivery metadata: if timezone reaches the envelope but downstream consumers assumed UTC, timestamps shift by hours with no error.
• Composer resolution failure: hard blocker on upgrade, discovered late if the Symfony floor isn't checked first.
• CI breakage from tool majors: blocks our own patches, not production.
• DST edge cases: reports spanning a transition are the least-tested path and the most confusing when wrong.

Ramp-up. Low for a team already running Symfony/NovoSGA; a Laravel-only team will spend real time learning bundle conventions, the NovoSGA Unidade domain, and the envelope abstraction — likely more time than the feature is worth unless they are already operating the service. Recommend the owning team be whoever runs the NovoSGA deployment, not the Laravel application team.