Embera Laravel Package

Getting Started

1. Install via Composer: composer require mpratt/embera.
2. Initialize the client in your application (typically in a service provider or controller):

   $embera = new \Embera\Embera(['discover' => true]);
   

3. Fetch embed data for a URL:

   $response = $embera->getUrlEmbedData('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
   

4. Render embed HTML:

   echo $response->html; // Outputs the embed <iframe> or <blockquote>
   

Start with basic usage and enable discover (auto-detect oEmbed endpoints) for maximum compatibility. Use the getDefaultConfig() method to inspect available options.

Implementation Patterns

• Blade Integration: Wrap in a @component or helper function (e.g., oembed('https://...')) for clean view usage:

  {!! oembed($videoUrl) !!}
  

• Caching Strategy: Use Laravel’s cache driver for persistent embed data to avoid repeated API calls:

  $cacheKey = 'embera_' . md5($url);
  $embed = Cache::remember($cacheKey, now()->addDay(), fn() => $embera->getUrlEmbedData($url));
  

• Responsive Embeds: Enable responsive config option to automatically wrap <iframe> in responsive containers (div AspectRatio).
• Offline Mode: Set discover to false and pre-register providers (e.g., Youtube, Vimeo) for reliable local rendering without network dependency.
• Provider-Specific Tweaks: Customize per-provider via config (e.g., disable YouTube cookies by appending ?cc_load_policy=1&iv_load_policy=3 to 参数).

Gotchas and Tips

• HTML Sanitization: Always sanitize $response->html before output in Blade using {!! !!} only after confirming trust (oEmbed responses can include arbitrary HTML/script—use HTMLPurifier or similar in production).
• Discovery Failures: Set discover => false and explicitly define providers if fetching from known domains (e.g., YouTube, Twitter) to avoid DNS lookups and improve performance.
• Error Handling: Check $response->status (e.g., 200, 404) before rendering; fallback gracefully for invalid URLs.
• Caching Gotcha: Embed codes may change (e.g., new oEmbed specs, provider policy updates); vary cache key by version (e.g., include library version or provider-specific hash).
• Extensibility: Extend \Embera\Http\Provider to add custom oEmbed endpoints or override response parsing for services not natively supported.