Embedly Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require embedly/embedly-php
   

   Add your Embedly API key to .env:

   EMBEDLY_API_KEY=your_api_key_here
   

2. Basic Usage

   use Embed\Embedly;
   
   $embedly = new Embedly(config('services.embedly.key'));
   $response = $embedly->oembed('https://example.com');
   dd($response->html); // Renders embeddable HTML
   

3. First Use Case Fetch and display embeds for URLs in a CMS or blog post:

   $url = request('url');
   $embed = (new Embedly(config('services.embedly.key')))->oembed($url);
   return view('embed.preview', ['embed' => $embed]);
   

Implementation Patterns

Common Workflows

1. Dynamic Embed Generation

   // In a Blade template
   @php
       $embed = (new \Embed\Embedly(config('services.embedly.key')))->oembed($post->url);
   @endphp
   {!! $embed->html !!}
   

2. Caching Responses Use Laravel's cache to avoid API rate limits:

   $cacheKey = 'embed_' . md5($url);
   $embed = cache()->remember($cacheKey, now()->addHours(1), function() use ($url) {
       return (new Embedly(config('services.embedly.key')))->oembed($url);
   });
   

3. Error Handling

   try {
       $embed = $embedly->oembed($url);
   } catch (\Embed\Exceptions\EmbedlyException $e) {
       return response()->view('embed.fallback', ['error' => $e->getMessage()]);
   }
   

4. Batch Processing For bulk embeds (e.g., importing posts):

   $urls = ['https://example.com/1', 'https://example.com/2'];
   $results = $embedly->batch($urls);
   

Integration Tips

• Laravel Service Provider Bind the client to the container for dependency injection:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(Embedly::class, function ($app) {
          return new Embedly(config('services.embedly.key'));
      });
  }
  

• API Key Management Store the key in config/services.php:

  'embedly' => [
      'key' => env('EMBEDLY_API_KEY'),
  ],
  

• Queueing Heavy Requests Offload embed generation to a queue job:

  // app/Jobs/GenerateEmbed.php
  public function handle()
  {
      $embed = (new Embedly(config('services.embedly.key')))->oembed($this->url);
      $this->post->update(['embed_html' => $embed->html]);
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limits Embedly enforces rate limits. Cache responses aggressively and handle 429 Too Many Requests errors:

   try {
       $embed = $embedly->oembed($url);
   } catch (\Embed\Exceptions\EmbedlyException $e) {
       if ($e->getCode() === 429) {
           sleep(1); // Backoff
           retry();
       }
   }
   

2. Unsupported URLs Not all URLs are embeddable. Validate responses:

   if (empty($embed->html)) {
       return response()->view('embed.fallback');
   }
   

3. HTTPS Requirements Embedly rejects HTTP URLs. Sanitize inputs:

   $url = Str::startsWith($url, 'http://') ? Str::replace('http://', 'https://', $url) : $url;
   

Debugging

• Enable Debug Mode

  $embedly = new Embedly(config('services.embedly.key'), ['debug' => true]);
  

  Logs HTTP requests/responses to storage/logs/embedly.log.

• Inspect Raw Responses Access the full API response:

  $response = $embedly->oembed($url);
  dd($response->raw); // Raw JSON from Embedly
  

Extension Points

1. Custom Endpoints Override the default API URL (e.g., for self-hosted Embedly):

   $embedly = new Embedly(config('services.embedly.key'), [
       'api_url' => 'https://your-custom-endpoint.com'
   ]);
   

2. Response Transformers Extend the Embed\OEmbed class to modify responses:

   class CustomOEmbed extends \Embed\OEmbed {
       public function getHtml() {
           $html = parent::getHtml();
           return str_replace('<iframe', '<iframe loading="lazy"', $html);
       }
   }
   

3. Proxying Requests Route Embedly traffic through a proxy (e.g., for IP whitelisting):

   $embedly = new Embedly(config('services.embedly.key'), [
       'http' => [
           'proxy' => 'tcp://proxy.example.com:8080',
           'timeout' => 10
       ]
   ]);
   

Configuration Quirks

• Default User Agent Embedly may block requests with non-standard user agents. Set a custom one:

  $embedly = new Embedly(config('services.embedly.key'), [
      'user_agent' => 'MyApp/1.0 (+https://myapp.com)'
  ]);
  

• SSL Verification Disable SSL verification only for testing (not production):

  $embedly = new Embedly(config('services.embedly.key'), [
      'verify_ssl' => false
  ]);