Monitor Bundle Laravel Package

Getting Started

novosga/monitor-bundle is a Symfony bundle from the Novo SGA queue-management ecosystem — not a Laravel package. It ships monitoring for service units (queue units) and, as of v2.3.0, propagates a unit's timezone onto every Envelope instance it creates. Treat the assessment below as "how to consume a Symfony bundle from a Laravel codebase," because that is the real day-to-day problem.

Requirements after v2.3.0

• PHP 8.2+ (Symfony 7.4 LTS enforces this).
• Symfony 7.4 components — the previous release tracked 7.1. If you are on Laravel 10 with PHP 8.1, this release is not installable; you need Laravel 11/12 on PHP 8.2+.

Install

composer require novosga/monitor-bundle:^2.3

Where to look first

1. src/*Bundle.php — the bundle class, to see what it registers.
2. src/DependencyInjection/Configuration.php — the actual config tree; this is your contract.
3. src/Resources/config/ — routing and service definitions. Check for a route prefix before mounting anything.
4. The Envelope class touched in PR #3 — that is the object carrying the unit timezone and the only behavioral change in this release.
5. composer.json — confirm the Symfony constraint and the PHP floor before you plan anything.

First use case Register one unit with a non-UTC timezone, hit the monitoring endpoint, and confirm timestamps render in the unit's local time rather than app.timezone. That single test exercises the bundle's routing, DI wiring, and the v2.3.0 fix end to end. If it passes, the rest of the integration is plumbing.

Implementation Patterns

Pick an integration shape before writing code. There are three viable ones:

1. Sub-kernel mount (full fidelity). Boot a minimal Symfony HttpKernel with only this bundle registered, and forward from a Laravel route:

   Route::get('/monitor/{path?}', fn (Request $r) => app(SymfonyBridge::class)->handle($r))
       ->where('path', '.*')->middleware(['auth']);
   

   Keeps the bundle's routing, Twig views, and config intact. Costs you a second container and a second cache directory.

2. Service-first extraction (recommended for most Laravel apps). Register the bundle's domain services in a Laravel service provider and call them directly, skipping Symfony routing and Twig entirely. You rebuild the presentation layer in Blade/Inertia. Less magic, easier to test, no parallel kernel.

3. Sidecar. Run the bundle as its own Symfony app and have Laravel proxy to it. Worth it only if you already operate Symfony services.

Config as code. Mirror the bundle's config tree into config/monitor.php and hydrate the Symfony container from it in one place. Do not scatter env() calls into the bridge — you will lose the ability to cache config in production.

Let the timezone come from the unit, not the app. After v2.3.0 the correct pattern is: the unit owns its timezone, the Envelope carries it, and consumers read it off the envelope. Do not re-derive local time from config('app.timezone') in your own listeners — that is exactly the class of bug PR #3 fixed, and re-deriving re-introduces it.

Test the envelope contract explicitly. Add a test that constructs a unit in America/Sao_Paulo (or your real tz), dispatches through the bundle, and asserts the envelope's timezone stamp. This is the one assertion that will catch regressions on future Symfony bumps.

Align tooling if you fork or contribute. The release moved the dev stack to PHPStan 2, PHPUnit 11, and PHPCS 4. If you maintain a fork or a patch set, upgrade those in lockstep or your CI will diverge from upstream's.

Gotchas and Tips

• No Laravel auto-discovery. There is no extra.laravel.providers entry. You must register the bridge manually; php artisan package:discover will do nothing for you here.
• The Symfony 7.4 bump is the real breaking change. It raises the PHP floor to 8.2 and pulls in APIs that removed several 6.x/7.0 deprecations. If you subclassed or decorated bundle services, re-run your test suite and check method signatures — a passing install does not mean a passing runtime.
• Deprecation cleanup (#6) can shift service signatures. The PR is billed as chore work, but "fix Symfony 7.4 deprecations" usually means constructor arguments or return types moved. Diff Resources/config/services.php between 2.2.0 and 2.3.0 rather than trusting the changelog.
• Remove any timezone workaround you wrote. If you were patching timestamps post-hoc to compensate for the pre-2.3.0 behavior, delete it now or you will double-apply the offset.
• Keep storage in UTC. The v2.3.0 change is about the envelope's display/metadata timezone. Verify your persistence layer still writes UTC; a bundle upgrade should never silently rewrite stored timestamps.
• Clear both caches. Symfony's container cache and Twig cache live outside Laravel's bootstrap/cache. Wire them into your deploy script, especially after a config change to unit timezones.
• Route prefix collisions. If you mount the bundle inside a Laravel app, check its route prefix against your web middleware group — CSRF and session middleware applied to a monitoring endpoint that expects its own auth will produce confusing 419s.
• Envelopes are immutable. Use stamps, don't mutate. If you need extra metadata on the envelope, add a stamp in a listener rather than reaching into the envelope object.
• Extend by decoration, not by editing vendor. Symfony's decorates: attribute maps cleanly onto Laravel's container; use it for any behavioral tweak so the next minor bump stays mergeable.
• The Dependabot bump (setup-php) is CI-only. It has zero runtime impact — ignore it when reasoning about upgrade risk.