Triage Bundle Laravel Package

Getting Started

novosga/triage-bundle is a Symfony bundle, not a Laravel package — it comes from the Novo SGA queue-management ecosystem and models triage/risk-classification of scheduled appointments. Treat it as a library you either consume inside a Symfony service (if your Laravel app talks to Novo SGA) or wrap behind a thin adapter in your Laravel domain layer; you will not get php artisan vendor:publish or Eloquent models out of it.

Minimal path:

1. composer require novosga/triage-bundle:^2.3 — note v2.3.0 requires Symfony 7.4 LTS components and therefore PHP 8.2+. Check composer why-not symfony/framework-bundle 7.4 before committing; Laravel 11/12 pin Symfony components below 7.4 in some patch lines and the constraint will resolve to a conflict rather than an error you can read easily.
2. Read DependencyInjection/Configuration.php first — that is the authoritative list of config keys (units, timezone, and the new appointment max-delay option). Everything else in the docs is downstream of it.
3. Register the bundle's DI extension in a Symfony kernel, or, for Laravel, bind the bundle's services manually in a service provider (constructor args are almost all interface-typed, so $this->app->bind(...) works without reflection hacks).
4. First use case: given a Unit, a ScheduledAppointment and a risk/priority input, resolve the triage result and confirm the appointment is inside the allowed scheduling window.

If you only need the triage rules and not the Doctrine mapping, you can pull the service classes alone and skip the bundle registration entirely.

Implementation Patterns

Configuration over code. The bundle is config-tree driven (Symfony TreeBuilder), not attribute driven. Wire environment-specific values through your Laravel config/ files into the container at boot rather than editing bundle YAML — it keeps the DI graph identical between test and prod.

Per-unit timezone as a first-class input. Units carry their own timezone, and since v2.3.0 appointment datetimes are parsed in the unit's timezone rather than the application default. Model this explicitly: resolve the Unit before parsing any datetime, and pass a DateTimeZone rather than relying on date_default_timezone_set(). For multi-tenant Laravel apps this maps cleanly onto a per-tenant timezone column.

Appointment max delay as a guard, not a validator. The new max-delay config (v2.3.0) belongs in your scheduling/booking path, early — resolve the limit from config once per request and short-circuit before persisting an appointment. Decide deliberately whether an over-limit appointment throws or is silently dropped; the bundle's behaviour is config-dependent, so assert on it in a test rather than assuming.

Adapter boundary. Expose a single TriageService-style class in your app that takes primitives (unit id, datetime, priority) and returns a DTO. This insulates your controllers from the bundle's value objects, which are not designed for serialization to JSON and will leak Doctrine proxies if you return them directly from an API resource.

Doctrine/ORM interop. Entities are Doctrine-mapped. If the rest of your Laravel app is Eloquent, either run a second EntityManager for these tables or hydrate the bundle's inputs from your Eloquent models and never persist through Doctrine. Mixing both on the same table is where most integration time gets lost.

Testing. With the dev-tool upgrade (PHPUnit 11, PHPStan 2, PHPCS 4), PHPUnit 11 deprecates docblock @dataProvider in favour of the #[DataProvider] attribute — write your wrapper tests that way now so a future bump doesn't break them.

Gotchas and Tips

• Timezone behaviour changed in v2.3.0. Datetimes previously parsed against the application/default timezone are now parsed against the unit's timezone. For any stored or cached scheduling data created before the upgrade, computed offsets can shift by hours. Backfill or re-derive unit timezones before deploying, and add a regression test with two units in different zones.
• DST is the real test case. A unit timezone fix that passes in UTC will still bite on spring-forward/fall-back boundaries. Test a 02:30 local appointment on a DST transition day.
• Symfony 7.4 requirement is the main upgrade risk. Laravel 11/12 do not always ship 7.4-pinned Symfony components. Resolve constraints in a scratch branch first; if you cannot bump, stay on 2.2.x until your Laravel line catches up.
• Deprecation cleanup is not a no-op. The "Symfony 7.4 deprecations" commit touches signatures; if you subclass or decorate bundle services, re-check your overrides against the new parent signatures.
• Max-delay defaults are the classic footgun. Verify whether the unset value means "unlimited" or "zero allowed", and whether the unit is minutes or days. Pin it explicitly in config even if the default suits you, so a future release cannot change the meaning silently.
• No vendor:publish. Bundle configuration lives in Symfony config (YAML/XML/PHP) or the container. In Laravel, keep a config/triage.php and translate it into container parameters in a provider — do not fight the bundle's expectation of a config tree.
• Extension points are the Unit/ScheduledAppointment entity fields and the priority/risk resolution services. Prefer composing a decorator over your own service to subclassing bundle classes; there is no formal extension interface, so subclassing is more brittle across minor releases.
• Debugging: when triage output looks wrong, check unit timezone resolution first, then config resolution order (env var vs config file vs default). Both are silent-failure paths — no exception, just a plausible wrong answer.