Youtube Bundle Laravel Package

Getting Started

Know what you're installing first. This is a Symfony bundle that plugs a YouTube slide type into an existing OS2Display digital-signage installation. It is not a Laravel package, and there is no Laravel integration path — if you're on Laravel you are looking at this to lift ideas, not to composer require it. The realistic audience is a developer maintaining an OS2Display stack who needs editors to publish YouTube videos to screens.

Minimal steps, in order:

1. Confirm you have a working OS2Display install. The bundle only makes sense inside the OS2Display admin + screen player. Verify the Symfony version your OS2Display line runs on and check the bundle's composer.json require block before anything else; a 2019 bundle will not install on Symfony 5/6.
2. Pin to 2.0.1. The 2.0.1 release was a Composer package-name correction, so treat it as the first installable 2.0 and avoid 2.0.0. If any composer.json, CI config, or Dockerfile in your estate was scaffolded against 2.0.0, grep for the old name.
3. Register the bundle in AppKernel.php (older Symfony) or config/bundles.php (Flex). Verify the exact bundle class name from the repo — the docs don't spell it out.
4. Provision a YouTube Data API v3 key if you plan to use the search path: Google Cloud console → enable YouTube Data API v3 → create an API key → restrict it. Put it in your own parameters file, not the admin UI.
5. Create a test YouTube slide on a scratch channel with a known-good public video, and confirm render on a real player device.

Look first at three files inside the bundle, not the README:

• Resources/config/ — service wiring and any config key the bundle reads (this is where the API key is expected).
• Resources/views/ — the Twig template that renders the iframe. This is your primary extension seam.
• Form/ — the editor-facing form; this tells you which playback options (autoplay, mute, controls) and which selection mode (URL vs search) are actually wired.

Those three files constitute the whole contract. The release notes and description are the only docs you get.

Implementation Patterns

Slide type composition. Create one YouTube slide per pinned video, and keep these slides on a dedicated channel. That lets editors reorder or reschedule YouTube content without disturbing the other slide types on the same channel, and it makes the slide-type dependency obvious during incident review.

Template override over vendor edits. The bundle ships a Twig template; copy it into your app's template namespace at the same relative path and override there. This is where you control iframe allow attributes, sizing, loading="lazy", and — importantly — whether you point at youtube.com or youtube-nocookie.com. Editing vendor/ loses the change on every composer install.

Config as code, not as admin toggles. Keep the API key and playback defaults (autoplay, mute, controls) in your parameters/config layer so dev, staging, and prod are reproducible. Admin-UI-configured settings become environment drift within a month, and you cannot diff them.

Scheduling is at the channel/screen level, not per-slide. Use OS2Display's existing scheduler to time the YouTube slide, but hold the slide duration against the video length. If the slide's assigned duration is shorter than the video, the sign cuts the video off mid-playback — this is the single most common support ticket for signage video slides.

URL over search, whenever possible. A known-URL slide costs zero API quota and cannot fail because a key expired. Reserve search-based selection for editorial workflows where the video genuinely changes, and cache the results — do not hit the search endpoint every time the screen polls.

Extending. The bundle is thin. If you need playlists, custom thumbnails, or an analytics beacon, add a new slide type that reuses the same Twig template rather than forking this one. You get your feature, and you keep the archived dependency frozen at a version that still installs.

Network allowlisting. Before go-live, add youtube.com, www.youtube-nocookie.com, i.ytimg.com, and s.ytimg.com to the kiosk/player network allowlist. Embedded YouTube fails silently to a black rectangle when these are blocked, so treat the allowlist as a deployment prerequisite, not a troubleshooting step.

Gotchas and Tips

The package is archived (last release 2019). No fixes, no security patches, no support. Assign a maintenance owner and assume you will replace this eventually. That does not make it unusable — it makes it frozen.

Symfony version is the hard gate. Built for an older OS2Display line. Confirm composer.json require accepts your Symfony version before you invest time in configuration; it almost certainly will not run on Symfony 5+ without work you don't want to do on an archived bundle.

Autoplay requires mute. Browser policy allows autoplay only when the video is muted. If you set autoplay=true without mute=true, the screen shows a paused player that nobody will click. Set both, always, for signage.

YouTube Data API v3 search is 100 units per call against a default 10,000/day quota. Fine for a handful of editors, catastrophic if anything loops on the search endpoint. Cache it; don't let a screen-player poll trigger search.

Not every URL-selectable video is embeddable. Video owners can disable embedding, and the admin UI will happily accept a URL that later renders as an error card on the sign. Test the exact video on the exact player device before go-live — not in a desktop browser, since the player's CSP and headers differ.

CSP and X-Frame-Options fail closed and quietly. If the OS2Display screen player sets a restrictive frame-src or X-Frame-Options, the iframe blanks with nothing in the PHP logs. Allow https://www.youtube.com and https://www.youtube-nocookie.com in the player's policy. Prefer youtube-nocookie.com for privacy posture and for regions that treat YouTube embedding as tracking.

Debugging order for "black rectangle on the sign": did the Twig template render at all? → is the iframe src correct and HTTPS? → is that video embeddable on this device? → is the network allowlist in place? → is CSP blocking it? Do not start in the admin UI; it will show a slide that "looks fine" while the player renders nothing.

2.0.0 is a packaging defect, not a version to work around. If dependency resolution behaves oddly, confirm the resolved package name matches 2.0.1's corrected value. Don't spend time debugging 2.0.0.

If you're on Laravel: you are not the audience for this package. The equivalent (a Blade partial with an embed URL parser, a form field for the URL, and the autoplay+mute defaults) is roughly a day of work and you control the maintenance. Reading this bundle is worth ten minutes for the embed and playback-option decisions; installing it is not.