Vimeo Bundle Laravel Package

Getting Started

First, know what you're installing. Os2DisplayVimeoBundle is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/vimeo.php, no php artisan vendor:publish. It is a slide-type extension for the OS2 Display digital-signage platform and expects os2display/core-style slide-type interfaces, Twig, and a Symfony DI container.

Minimal steps:

composer require os2display/vimeo-bundle

Then, in a Symfony/os2display app, register the bundle in config/bundles.php:

return [
    Os2Display\VimeoBundle\Os2DisplayVimeoBundle::class => ['all' => true],
];

Where to look first, in this order:

1. DependencyInjection/Os2DisplayVimeoBundleExtension.php — what config keys actually exist and what they default to.
2. Resources/config/services.* — the service IDs, which are your real extension points (and where the rename will bite you).
3. The slide-type class itself (implements the os2display slide-type interface) — getType(), getTemplate(), getIcon() tell you the whole contract in ~60 lines.
4. Resources/views/ — the Twig template that renders the player. This is what you will actually override 90% of the time.

First use case: an editor adds a Vimeo slide in the admin UI by pasting a video URL/ID; the slide stores the Vimeo reference; the screen renders an embedded player through the bundle's template. Get that path working end-to-end on a test screen before touching config.

If you are genuinely forced to use this from Laravel, don't try to shoehorn the bundle in. Pull the pieces: instantiate the Vimeo API client yourself, treat the slide-type class as a plain value/renderer object, and re-implement the thin template. You lose the DI wiring and gain nothing by fighting it.

Implementation Patterns

Configure, then tag. The bundle's slide type only becomes available once the service is tagged/collected by os2display's slide-type registry. Read the extension class for the config tree, set values in config/packages/os2_display_vimeo.yaml (Vimeo client credentials, embed parameters such as autoplay, muted, loop, dnt, background), then clear the container cache.

Render via the shipped template. Don't rebuild the embed markup. Pass the slide's data into the bundle template and let it handle parameter serialisation — that is the only place the Vimeo query-string logic exists and it is easy to get subtly wrong by hand.

Override the template, not the class. Put your own version at the bundle-namespaced override path in your app's templates/ and the container will prefer it. This is the supported way to change player attributes, wrappers, sizing classes, or to add tracking.

Decorate the slide type to extend behaviour. If you need extra fields (poster fallback, a per-slide aspect ratio), decorate the service rather than editing vendor code:

services:
    App\Slides\VimeoSlideType:
        decorates: os2display.vimeo.slide_type

That survives the next release; a fork does not.

Test the rendered output, not the Vimeo API. Assert the template produces the expected iframe/player markup with a fixed slide payload. Mock the API client; you do not want network calls in CI and Vimeo rate limits will make the suite flaky.

Keep a migration note for the rename. Every reference to the old bundle class name, namespace, or service ID belongs in a single grep-able list, because 2.0.0 invalidated all of them at once.

Gotchas and Tips

2.0.0 is a rename-only release, and that means it is breaking. There is no functionality change, which makes it more dangerous — it will slip through review. Update at minimum:

• composer.json — the package name and the version constraint (^2.0).
• The bundle class name in bundles.php (Os2DisplayVimeoBundle, previously whatever casing/prefix you had).
• Every use statement referencing the old namespace.
• Service IDs in your own services.yaml — the os2display.vimeo.*-style IDs may have moved.
• Template references (@Os2DisplayVimeo/...) and translation domains.
• Any instanceof checks or extends against bundle classes in your app code.

"Class not found" immediately after upgrading is almost always stale config/container cache or an out-of-date autoloader:

composer dump-autoload
bin/console cache:clear

In production, run the config cache warm-up as part of deploy; a cached container built against the old bundle name will keep silently working until the next restart, then fail hard.

Autoplay will not work with sound. Browser policy blocks it. muted + background=1 is the only reliable combination for unattended signage. If a screen shows a black box, check these two embed params before assuming the player is broken.

Vimeo privacy settings override your code. Domain-level embed restrictions and "where can this be embedded" settings on the video will refuse to play on your signage host, no matter what the bundle emits. Confirm the video's privacy/domain allowlist when a player renders but shows an error frame. Unlisted links behave differently from authenticated/token access — decide which model you are on early.

No Laravel conveniences exist. No auto-discovery, no facade, no config file in config/. Anything you'd normally do with php artisan vendor:publish here requires copying templates/paths by hand, and any environment-based configuration must be injected through the Symfony config layer.

The clean extension points are: template override, service decoration, and config. Anything that requires editing the bundle source means you should re-check whether a decorator or a config key you overlooked would have done the job.

Pin your constraint and read the changelog before minor bumps. If a single-line release like this one can be a full major version, the project takes semantic versioning seriously — take the hint and read the diff rather than assuming composer update is safe.