Reports Bundle Laravel Package

Getting Started

novosga/reports-bundle is a Symfony bundle for Novo SGA reporting, not a Laravel-native package. In v2.3.0 the main day-to-day change is that report envelopes now receive the timezone configured on the Unidade (unit), rather than relying on a default timezone.

Minimal steps:

1. Confirm your application meets the new Symfony constraint. v2.3.0 upgrades from Symfony 7.1 to Symfony 7.4 LTS, so older Symfony 6.x/7.0/7.1 applications should stay on v2.2.3 unless they upgrade Symfony first.
2. Install with Composer: composer require novosga/reports-bundle:^2.3.
3. Register the bundle in a Symfony application (config/bundles.php) and import/configure its services as documented by the bundle. There is no Laravel service provider or php artisan vendor:publish workflow.
4. Look first at the bundle’s README, src/, report templates, and any Envelope/Unidade related classes. Those are the key integration points for the v2.3.0 timezone change.
5. First use case: generate a report for a unit and verify that the resulting Envelope uses the unit’s timezone. Test with a non-default timezone and a DST boundary.

For Laravel developers, treat this as a Symfony package you may call from a Symfony service, a standalone reporting service, or an internal API — not as a package you would normally drop directly into a Laravel app.

Implementation Patterns

• Unit-scoped report generation: Pass the Unidade/unit context into the report service, then let the bundle construct the Envelope. In v2.3.0 you should not manually set the envelope timezone from app config if the unit already has one.
• Timezone as domain data: Store valid IANA timezones on Unidade (e.g. America/Sao_Paulo). Use the unit timezone consistently for report headers, generated timestamps, and scheduled report windows.
• Scheduled reports: Wrap report generation in a Symfony console command or message handler. For Laravel integrations, trigger that command/API from a Laravel job rather than trying to boot the Symfony bundle inside Laravel.
• Template customization: Prefer overriding report templates through the bundle’s documented override path instead of editing vendor files. Keep custom templates in your app and reference them through configuration.
• Upgrade workflow: After upgrading to v2.3.0, run composer update, clear the Symfony cache, run your test suite, and review deprecation logs. The release includes Symfony 7.4 deprecation fixes, but your app may still surface its own deprecations.
• Testing pattern: Add a regression test that creates a unit with a non-UTC timezone, generates an envelope, and asserts the envelope timezone matches the unit. This directly covers the v2.3.0 feature/fix.

Gotchas and Tips

• Not a Laravel package: There is no Laravel facade, config publish, or Eloquent integration. If you are in Laravel, plan for a Symfony sidecar/service or an API boundary.
• Symfony version constraint: v2.3.0 targets Symfony 7.4 LTS. If your app is on Symfony 7.1 or earlier, Composer may block the upgrade. Pin v2.2.3 until the Symfony upgrade is complete.
• Timezone validity: The new behavior passes the unit timezone into Envelope. An empty, null, or invalid Unidade timezone can still cause errors or fallback behavior. Validate timezone values at write time and handle missing timezones explicitly.
• DST edge cases: Test reports around daylight-saving transitions, especially if report date ranges are computed from local unit time.
• No explicit breaking changes: The v2.3.0 notes are a feature, a fix, and dependency/tooling upgrades. The practical risk is the Symfony 7.4 requirement and deprecation fallout, not a documented API break.
• Dev tooling is not runtime: PHPStan 2, PHPUnit 11, and PHPCS 4 upgrades affect development only. Do not infer production requirements from those bumps.
• Debugging: Use Symfony’s container debug commands and profiler to confirm the report service receives the expected unit. Clear cache after upgrading, and check deprecation logs for Symfony 7.4 issues.
• Extension points: Prefer decorating the report/envelope service or overriding templates over forking the bundle. Keep the unit-to-timezone mapping in your domain layer so future bundle changes do not require scattered fixes.