Panel Bundle Laravel Package

Getting Started

The first thing to internalise: novosga/panel-bundle is a Symfony bundle, not a Laravel package. There is no service provider to register, no vendor:publish, no Blade views, no config/panel.php. "Getting started" means standing up a separate NovoSGA panel process and integrating with it over an HTTP boundary. Plan for that before you plan a single line of Laravel code.

Minimal path, in order:

1. Read composer.json on the v2.3.0 tag before anything else. Note the php constraint and the symfony/* + novosga/core-bundle pins — this is the go/no-go check for your environment, and it tells you what else the panel expects to sit next to.
2. Stand it up in its own Composer root (or the official NovoSGA Docker image) pointed at a NovoSGA database. Do not try to nest it inside your Laravel composer.json.
3. Let NovoSGA core own the schema. Run the core migrations first, then the panel's. A half-migrated database produces template and repository errors that look like panel bugs but are ordering problems.
4. Log in as an attendant, pull a ticket, call it. That's your smoke test — it proves auth, schema, and routing are all sane.
5. Back in Laravel, build the seam. A single NovosgaClient class (base URI, timeout, retry, typed DTOs) behind an interface, faked in tests. Your first use case is: issue a ticket from Laravel, confirm it appears in the panel queue, then call it from the panel and confirm Laravel can read the state back.

Where to look first when something is wrong: the panel's var/log/dev.log and the Symfony profiler. Never storage/logs/laravel.log — the panel does not write there.

Implementation Patterns

Sidecar service, always. Run the panel as its own container/process with its own composer.json and its own lifecycle. Your Laravel app talks to it over HTTP; it does not share a process, an autoloader, or a database connection. This one decision eliminates the entire class of Symfony/Laravel dependency-conflict problems and lets each app upgrade independently.

Wrap every call in a client. A NovosgaClient bound to an interface, configured from config/services.php, with timeout + retry + a fake()-able test double. Controllers and jobs never touch Http:: against the panel directly. When the panel's minor version changes something, you fix one class.

Auth bridging — pick one, document it.

• Shared-cookie SSO: put both apps behind the same parent domain and a reverse proxy, set framework.session.cookie_domain in the panel to the parent domain, and make sure X-Forwarded-Proto/X-Forwarded-Host are trusted on both sides.
• Header forwarding: terminate auth in Laravel, forward an authenticated identity header from the proxy, and have the panel trust it. Either way, do not duplicate the user table. NovoSGA has its own usuario records and expects them. Sync attendants into NovoSGA from a Laravel listener on user create/update, or from a scheduled job — one direction only, Laravel as the source of truth for identity.

Read-model sync for reporting. If you need queue state inside Laravel (dashboards, notifications, SLA timers), poll the panel on a schedule into local tables. Do not join across to the NovoSGA schema from Eloquent, and do not point a second Laravel DB connection at it. Keeping your migrations independent of the bundle's schema is what makes upgrades boring.

Theming and UI changes go through Twig overrides. Panel customisation is Symfony-native: override Twig templates and adjust bundle config under config/packages/. Keep every override in a small, documented, version-pinned overlay directory so a v2.3.x bump doesn't silently break the panel at 9am.

Compose your dev environment. A docker-compose.yml with the panel, its database, and a seeded attendant account belongs in your repo. Every Laravel dev should be able to run the integration locally without reading NovoSGA docs.

Lifecycle events are the supported extension seam. If you need to react to ticket/attendance events inside the panel's world, use Symfony event listeners registered in the panel root — not monkey-patching services.

Gotchas and Tips

• v2.3.0 has no release notes. The release body is a bare changelog link. Treat it as "probably minor, unverified". Read the commit diff before upgrading: constructor/service-definition changes, config keys, Doctrine migrations, and especially the Twig/template layer — panel bundles are almost always customised at the view layer, and that's where minor bumps break silently with a blank page and no exception in your Laravel logs.
• Pin the exact tag. 2.3.0, not ^2.3. Given the silent release notes, an unattended composer update in the panel root is an unplanned production change.
• Composer collisions are the classic afternoon-loser. Laravel and the bundle pin overlapping symfony/* components. Separate Composer roots make this impossible; a merged composer.json makes it inevitable.
• Schema ownership confusion. The panel expects the NovoSGA core schema to exist and be migrated. It is not self-bootstrapping. If you see odd repository/template errors on a fresh environment, check migration order before you debug the panel.
• Cross-app auth fails silently. When login "just doesn't stick", check framework.session.cookie_domain, cookie SameSite (panel and Laravel must agree, and SameSite=None requires Secure), and the proxy's forwarded headers. Debug the session config before you debug the auth code — it's almost never the auth code.
• Logs live with the panel. var/log/dev.log in the panel root, plus the Symfony profiler. A blank panel page is nearly always a Twig render exception recorded there.
• Supported extension points: Twig template overrides, bundle config under config/packages/, and Symfony event listeners. Anything beyond those is reaching into internals and will break on a minor bump — budget for it or avoid it.
• Upgrade routine, on a branch: diff v2.2.x → v2.3.0 → re-check the symfony/* and core-bundle pins → run the panel's own login/pull-ticket flow → bump the pin. Never on main on a Friday.
• Fake the client in tests. Since the panel is a network dependency, your Laravel test suite must never require it to be running. Interface + fake keeps CI fast and honest.