Triagem Bundle Laravel Package

Getting Started

• Know what this is before you install it. novosga/triage-bundle is a Symfony bundle (part of the NovoSGA queue/attendance platform), not a Laravel package. It ships a DI extension, a configuration tree, and domain services for triage/priority handling of appointments and tickets against service units. There is no service provider, no facade, and no package discovery.
• Requirements: v2.3.0 moves to Symfony 7.4 LTS, so expect PHP 8.2+ and Symfony ^7.4 components (http-kernel, dependency-injection, config). If you are still on Symfony 6.x/7.1 or PHP 8.1, stay on 2.2.x.
• Two realistic integration routes:
  1. Run it where it belongs — inside a Symfony app/microservice (or the NovoSGA core) and expose triage decisions to Laravel over HTTP/queue. Cleanest.
  2. Consume the domain layer only — pull in the appointment/triage services as plain PHP objects and skip TriageBundle::class + the DI extension entirely.
• Where to look first: the bundle's DependencyInjection/Configuration.php (this is where the new appointment max delay setting lives), the scheduled-appointment scheduling service, and the service-unit entity/model carrying the timezone property.
• First use case: schedule an appointment for a service unit, then evaluate it against the configured max delay to decide whether it is still within its triage window. The two headline changes in 2.3.0 — unit-timezone parsing and max-delay config — are exactly the two knobs this flow depends on.

Implementation Patterns

• Config-first for SLA. Register the bundle config (novosga_triage: root, key name to confirm from the config tree) and treat the max delay as an injected scalar — never hardcode it. In Laravel, mirror it in config/triage.php and bind it as a singleton so the domain services receive the same value the Symfony app would.
• Unit timezone is now authoritative. Since 2.3.0 the scheduled appointment datetime is parsed using the service unit's timezone, not the process/app default. Pattern: always pass the unit into the scheduling path, never call a bare new \DateTimeImmutable($string). Set date_default_timezone_set() correctly anyway so fallbacks are predictable.
• Adapter over inheritance. Wrap the bundle's scheduling/triage services in a thin application-level service (AppointmentScheduler, TriagePolicy) that converts your Eloquent models to the bundle's inputs and back. Keeps Symfony types out of your controllers and makes the bundle swappable.
• Bind interfaces, not classes. The bundle exposes repository-ish contracts via DI. In a Laravel ServiceProvider, bind() those contracts to Eloquent-backed implementations; in Symfony, alias them or decorate the existing services.
• SLA breach as a queued check. Drive max-delay evaluation from a scheduled job (->everyFiveMinutes()) that loads open appointments, asks the triage service whether they exceeded the window, and dispatches notifications. Keeps the bundle stateless and cheap.
• Test the policy, not the framework. The bundle's own suite moved to PHPUnit 11 with PHPStan 2 — if you extend its test case or reuse its fixtures, align your phpunit.xml schema. Inject a fixed clock (Psr\Clock/Carbon::setTestNow()) so timezone and delay assertions are deterministic.
• Pin deliberately: "novosga/triage-bundle": "^2.3" — do not float to *, since the Symfony major/minor floor moved.

Gotchas and Tips

• Timezone fix changes behaviour, silently. Appointments previously parsed with the server default timezone may now land at a different instant. Audit existing scheduled rows before/after upgrade; if the server TZ and unit TZ differ, historical datetimes are effectively shifted. Backfill or freeze is a decision you must make explicitly.
• Three timezones in play — PHP default, app config (APP_TIMEZONE in Laravel), and the per-unit timezone. Log all three when debugging an off-by-hours appointment; the 2.3.0 fix only guarantees the unit one is used for parsing, not for storage or display.
• Max delay defaults are the trap. Check what an unset value means (unlimited? zero? a fixed fallback?) and whether it applies retroactively to already-scheduled appointments or only at creation time. Validate the config at boot rather than discovering 0 in production.
• Symfony 7.4 deprecation cleanup is a breaking surface. The "symfony 7.4 deprecations" PR removes/renames things; anything you subclassed, decorated, or type-hinted from 7.1 internals needs re-checking. If you pair this with novosga/core, version-lock both — mismatched Symfony constraints are the most likely install failure.
• Dev-tool bumps are not runtime bumps, but PHPStan 2 and PHPCS 4 will flood your CI if you reuse the bundle's config. Run the bundle's static analysis in isolation, or point it at vendor/novosga/... only.
• Laravel friction points: the Symfony config tree is not config/*.php, so php artisan config:cache will not cover it — resolve the bundle's settings at container-build time. There is also no Illuminate event bridge; use Symfony's dispatcher or your own events.
• Extension points that survive upgrades: the configuration tree (add your own keys via a wrapping extension), service decoration/aliasing, and the clock/timezone seams. Avoid overriding concrete scheduling classes — those were touched in this release.
• Debugging tip: when triage decisions look wrong, dump the resolved unit timezone and the resolved max delay side by side first. In every recent issue class for this bundle, one of those two was the culprit.