Admin Bundle Laravel Package

Getting Started

os2display/admin-bundle is the administration UI for the os2display digital-signage platform. Release 2.2.1 merges PR #25, adding screen administration — CRUD screens for managing the display endpoints that show content. If you are coming from Laravel, read the next section before running composer require: this is a Symfony bundle, not a Laravel package.

First places to look after pulling 2.2.1:

1. composer.json — confirm the PHP/Symfony version constraints and the bundle's dependencies.
2. src/Resources/config/ — routing, services, and DI wiring. This is where the new screen-admin routes and services land.
3. The controller and form type added/changed by PR #25 — that is the canonical pattern for every other admin resource (slides, media, channels).
4. src/Resources/views/ — Twig templates for the admin screens, including the new screen list/form.
5. Migrations or Doctrine mapping changes, if the screen entity gained fields.

Minimal path to a working screen admin (inside a Symfony host application):

composer require os2display/admin-bundle:2.2.1

// config/bundles.php
return [
    // ...
    Os2Display\AdminBundle\Os2DisplayAdminBundle::class => ['all' => true],
];

Then import the bundle routing, ensure the Doctrine connection and any required migrations are applied, create an admin user, and open the admin route (commonly /admin). The first end-to-end use case is: log in → open Screens → create a screen → assign it to a channel/playlist → verify it appears in the screen list. That exercises the new feature and the auth/permission layer at once.

Implementation Patterns

Treat the screen admin as the reference implementation. The bundled screen list + form + persist flow is the template for any custom admin resource you add. Copy the structure (Controller → FormType → Entity → Twig template → route entry) rather than inventing a new one; it keeps you compatible with upstream changes in later 2.x releases.

Integrating with a Laravel application. Do not try to mount this bundle inside Laravel. The realistic patterns are:

• Run os2display (Symfony) as a separate service and expose the admin on a subdomain, fronted by the same reverse proxy as your Laravel app.
• Share authentication via a common identity provider (OIDC/SAML) so admins move between the Laravel app and the signage admin without a second login.
• Sync data your Laravel app owns (e.g. content metadata, user/tenant mapping) into the signage database or through its API, and link out to the admin screens rather than reimplementing them.

Screen lifecycle workflow. Model screens as long-lived registered devices. The admin CRUD covers create/edit/delete; the day-to-day workflow is registration → assignment to a channel → content publishing → status monitoring. Keep the screen identifier stable and referenced from your own system if you need cross-system reporting.

Extending without forking. Prefer overriding Twig templates via the standard bundle override path and decorating services over patching vendor code. If you need extra fields on the screen form, extend the form type through a form extension rather than editing the bundle's form class.

Version pinning. Pin to 2.2.* and review the changelog on each bump. Because 2.2.1 adds a feature in a patch release, treat patch bumps as potentially schema- or route-affecting and run them through staging first.

Gotchas and Tips

• This is not a Laravel package. There is no service provider, no config/admin.php, no Artisan commands, no Blade, no Eloquent. It uses Symfony DI, Twig, Doctrine, and Symfony routing/security. Any Laravel-side integration is at the HTTP/SSO boundary, not in-process.
• Semantic versioning is loose. 2.2.1 is a patch version that ships a new feature (screen admin). Do not assume patch releases are behaviour-neutral; read the PR diff before upgrading.
• Check for migrations and route changes. New admin screens usually mean new routes and often new or altered Doctrine mappings. Run doctrine:schema:validate / migrations and clear the Symfony cache after upgrading.
• Permissions. New admin sections are a frequent source of "403 for non-super-admin" bugs. Verify the screen-admin routes are covered by your role configuration and that the menu entry is gated by the same voter/role check as the controller.
• Asset pipeline mismatch. The bundle may expect a Symfony Encore/Webpack build. If your host app uses Vite or a different pipeline, admin JS/CSS can silently fail to load — check the browser console and the rendered <script> tags first when the screen list looks broken.
• Caching. After enabling the bundle or upgrading, clear the Symfony cache (bin/console cache:clear). Stale container caches produce confusing "service not found" or "route not found" errors on new features.
• Debugging. Use the Symfony profiler for the screen-admin request: it shows the resolved controller, form validation errors, and Doctrine queries in one place. For 500s on save, check form validation and entity mapping before the controller.
• Upgrade hygiene. Snapshot the admin database before applying 2.2.1 in staging; a screen-admin feature may touch the screen table, and rollback is far cheaper than a partial migration.