Screen Bundle Laravel Package

Getting Started

• Install with composer require os2display/screen-bundle:^1.1. This is a Symfony bundle, not a Laravel package, so there is no service provider or config publish step you can lean on. In a Laravel codebase you either run it inside a Symfony kernel/container (e.g. a sidecar service or a symfony/* micro-kernel) or lift the domain services and Doctrine mappings into your app manually.
• First place to look: Resources/config/ for service definitions and DependencyInjection/ for the extension class. Then read the Channel, Screen, and Slide entity mappings under Entity/ — the data model is the package.
• First use case to validate your wiring: create a Channel, attach a couple of Slides, give the channel a schedule window, and ask the scheduling service which slides are currently active. If that returns the right set, your entities, migrations, and container wiring are all sound.
• Run bin/console doctrine:migrations:migrate (or port the schema into a Laravel migration) before touching any service — most "it returns nothing" reports are missing tables, not broken code.

Implementation Patterns

• Model the hierarchy explicitly. Screen → Channel → Slide with schedules hanging off channels. Treat the entities as the contract; build your application layer (controllers, jobs, API resources) around them rather than duplicating the scheduling logic.
• Delegate scheduling to the bundle's service, never re-implement it. The 1.1.7 release fixes a bug in channel scheduling, which is exactly the kind of logic you do not want to fork. Inject the scheduling service via constructor injection and let it decide what is active at a given time.
• Time-window queries: pass an explicit DateTimeInterface when you need deterministic results (tests, cron jobs, previews). Schedule evaluation against "now" is convenient in a controller but painful to test.
• Preview/dry-run endpoint: a small controller that accepts a channel ID and a timestamp and returns the resolved slide list is the highest-value thing you can build on top of this bundle. It doubles as your integration test harness.
• Screen payload shaping: because the bundle deals in entities, add an API Resource / serializer layer so your player clients don't get Doctrine proxies and lazy-loaded collections in JSON. Eager-load channel→slide relations in the repository query.
• Integration tip: if you are consuming this from a Laravel app, wrap the container-managed services in thin adapter classes and bind them as singletons in a service provider. That keeps the Symfony/Doctrine types out of your controllers and makes the dependency swappable.
• Caching: schedule resolution per channel per time bucket is a natural cache target. Key on channel_id + rounded hour and invalidate on channel/slide writes.

Gotchas and Tips

• 1.1.7 is a patch, not a feature release. It fixes channel scheduling (PR #14). No breaking changes, no new config, no deprecations — upgrading from 1.1.x is low risk. Pin ^1.1.7 rather than a looser constraint so you actually receive the fix.
• Audit your workarounds. If you previously compensated for mis-scheduled channels with manual overrides, timezone hacks, or filtering slides in your own controller, remove them and re-run your preview endpoint against the fixed behaviour. Leaving them in will silently double-correct.
• Symfony/Doctrine version coupling. The bundle assumes a specific Symfony major and Doctrine ORM version. In a Laravel project pulling in doctrine/orm and symfony/*, expect dependency resolution friction — check composer.json of the bundle before upgrading your own framework.
• Doctrine cache is the usual suspect. After changing entity mappings or config, clear the metadata cache (doctrine:cache:clear-metadata) and any Laravel config cache. Stale proxies produce errors that look like mapping bugs.
• Timezone handling is the most common scheduling defect. Store schedules in UTC, convert at the edge. Verify the 1.1.7 fix behaves correctly for channels whose windows span midnight or cross a DST boundary.
• Extension points: override templates under Resources/views by placing files at the conventional bundle override path, and decorate services rather than editing vendor code. For entity changes, prefer Doctrine listeners/subscribers so you can re-vendor the bundle safely.
• Debugging: if a channel returns no slides, check in this order — (1) tables migrated, (2) channel/slide published flags, (3) schedule window values stored in UTC, (4) whether the container is actually resolving the bundle's service or a stale cached one.