torann/embedder
Laravel package for embedding media from URLs via oEmbed services. It turns links to YouTube, Vimeo, Twitter and other supported providers into responsive embed HTML through a simple, configurable API.
The package gives you two related capabilities: emitting OpenGraph metadata for your pages and resolving embed links (oEmbed-style previews) for URLs. At 0.0.4 it is still pre-1.0, so treat the public API as unstable and pin the exact version in composer.json ("vendor/package": "0.0.4") rather than using a caret constraint.
Minimal setup:
composer require vendor/package and commit the lock file.php artisan vendor:publish --tag=... — check the README for the exact tag) so you can see which resolvers/providers are enabled and where timeouts are configured.<head>, above any hand-written <meta property="og:*"> tags you already have.view-source — not just in the DOM inspector, since some tag managers inject after load.Your first real use case is almost always the "shareable page": a public detail page (product, post, profile) that needs correct og:title/og:description/og:image when pasted into Slack or a social network. Get that working end-to-end before wiring up embeds.
Where to look first when something is off: the published config file, then the package's Blade view/component (it's the cheapest place to confirm what's actually being rendered), then the resolver/service class for embed generation.
Set OG values at the source, not in the view. Since 0.0.4 the package refuses to let OpenGraph values be overridden after they've been set. Model your data as "the page declares its OG values once" — via a model method, a dedicated data object, or a config array keyed by route — and let the package render from that single source. Trying to @section-style override tags in a child view is the pattern this release explicitly breaks; see Gotchas.
A per-model accessor is the cleanest fit for Laravel. Give shareable models a method returning title/description/image/type, and pass that to the package from the controller or a view composer. This keeps OG concerns out of Blade and makes the values testable:
// app/Models/Post.php
public function openGraph(): array
{
return [
'title' => $this->title,
'description' => Str::limit(strip_tags($this->body), 160),
'image' => $this->hero_image_url,
'type' => 'article',
];
}
Then assert on it in a feature test ($response->assertSee('og:title', false)) so a template refactor can't silently break sharing.
Fallbacks belong in one place. Decide the project-wide rule — e.g. missing image falls back to a default brand card — and implement it in your own wrapper rather than scattering ?? config('...') across views. When the package changes its fallback behaviour (likely before 1.0), you'll only have one place to fix.
Embed links: resolve, then cache. Embed resolution means an outbound HTTP call, which means latency, rate limits, and flakiness. Two patterns that hold up:
Fake the network in tests. Any embed test should use Http::fake() with recorded provider responses. This also pins you against upstream API drift and keeps CI offline-safe.
Keep rendering in a partial. Wrap the package output in your own Blade partial so you control the surrounding markup, escaping, and the "no OG data available" case. Swapping the package later then becomes a one-file change.
0.0.4 is a behaviour change, not just a bug fix. "Don't allow OpenGraph values overrides" means any code that previously set tags after the package set them — a child view overriding a layout, a middleware mutating values, a View::composer running late — will now silently keep the original values. Symptoms are nasty because nothing errors: pages just share the wrong title. After upgrading, grep for every place you touch OG values and consolidate to one declaration site, then verify a handful of representative pages with a share-preview debugger.
Clear cached embeds after upgrading. 0.0.4 fixes a bug in embed link retrieval, which means previously cached outputs may have been stored in the broken shape. Flush whatever cache keys/columns hold resolved embeds, or key your cache with the package version so upgrades self-invalidate.
Pre-1.0 semver. 0.0.x releases may break without a major bump, and patch-level changes like this one can still alter behaviour. Pin exactly, read every changelog, and cover your integration with a small number of feature tests asserting on rendered tags and on your stored embed data — those tests are what make an upgrade a five-minute job instead of an afternoon.
Outbound requests need guardrails. Set a connect/response timeout in the package config, and consider disabling resolvers for providers you don't actually use so an arbitrary user-submitted URL can't fan out to a dozen endpoints. Watch for SSRF if URLs come from users: you generally do not want to resolve localhost or private ranges.
Escaping. OG values frequently contain user-controlled text. Confirm the package's output is escaped (inspect the compiled Blade view) before you feed it raw titles or descriptions; og:description containing a stray " can break the attribute and corrupt every subsequent tag in the head.
Missing image dimensions. Many consumers ignore og:image without og:image:width/height. If the package doesn't emit them, add them yourself — this is a common cause of "the preview works on one platform but not another".
Extension points to note for later. The resolver list and the OG value provider are the two seams you'll most likely want to customise (adding a provider, changing fallbacks). Note in your team docs how to register a custom resolver, because that's the escape hatch that stops you forking the package — and at 0.0.x, forking is the outcome you want to avoid.
How can I help you explore Laravel packages today?