Embedly Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ee/embedly-bundle:dev-master
   

   Add the bundle to config/bundles.php:

   EE\Bundle\EmbedlyBundle\EEEmbedlyBundle::class => ['all' => true],
   

2. Configuration: Add Embedly API key to .env:

   EMBEDLY_API_KEY=your_api_key_here
   

   Publish the default config (optional):

   php bin/console config:dump-reference EEEmbedlyBundle
   

3. First Use Case: Fetch a URL's embed data in a controller:

   use Symfony\Component\HttpFoundation\Response;
   
   class EmbedController extends AbstractController
   {
       public function embed(Embedly $embedly): Response
       {
           $url = 'https://example.com';
           $embed = $embedly->embed($url);
   
           return $this->json($embed);
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Injection: Inject Embedly service directly into controllers, services, or twig extensions:

   public function __construct(private Embedly $embedly) {}
   

2. Twig Integration: Pass embed data to templates:

   {% for media in embedly.embed(url).media %}
       <img src="{{ media.url }}" alt="{{ media.title }}">
   {% endfor %}
   

3. Batch Processing: Fetch multiple URLs efficiently:

   $urls = ['url1', 'url2', 'url3'];
   $results = $embedly->batch($urls);
   

4. Custom Endpoints: Use specific Embedly endpoints (e.g., oembed, images):

   $oembed = $embedly->oembed('https://youtube.com/watch?v=abc123');
   

Integration Tips

• Caching: Cache responses to reduce API calls:

  $cacheKey = 'embedly_' . md5($url);
  if (!$embed = $cache->get($cacheKey)) {
      $embed = $embedly->embed($url);
      $cache->set($cacheKey, $embed, 3600); // Cache for 1 hour
  }
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $embed = $embedly->embed($invalidUrl);
  } catch (\Embed\Exceptions\EmbedException $e) {
      $this->addFlash('error', 'Embed failed: ' . $e->getMessage());
  }
  

• Async Processing: Use Symfony Messenger for background embed generation:

  $message = new GenerateEmbedMessage($url);
  $this->messageBus->dispatch($message);
  

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Hardcoding keys in config files violates security best practices. Always use .env.
   • Rotate keys periodically and clear caches after changes.

2. Rate Limits:

   • Embedly has strict rate limits (e.g., 10,000 requests/month for free tier). Monitor usage via Embedly Dashboard.
   • Implement exponential backoff for retries:

     $embedly->setRetryOptions(['max_retries' => 3, 'delay' => 1000]);
     

3. URL Validation:

   • Embedly may reject malformed URLs. Sanitize inputs:

     $url = filter_var($rawUrl, FILTER_VALIDATE_URL);
     if (!$url) throw new \InvalidArgumentException('Invalid URL');
     

4. Bundle Maturity:

   • Low stars/dependents suggest limited community support. Test thoroughly in staging.
   • Check for updates manually (no auto-updates for dev-master).

Debugging

• Enable Debug Mode:

  $embedly->setDebug(true); // Logs API requests/responses
  

• Common Errors:
  • EmbedException: Invalid API key or URL. Verify .env and input.
  • ConnectionException: Network issues. Check proxy/firewall settings.

Extension Points

1. Custom Responses: Override default response handling by extending the service:

   class CustomEmbedly extends Embedly
   {
       public function embed($url)
       {
           $response = parent::embed($url);
           return $this->transformResponse($response);
       }
   }
   

   Register as a service in config/services.yaml:

   services:
       App\Service\CustomEmbedly:
           decorates: 'embedly'
           arguments: ['@embedly.inner']
   

2. Event Listeners: Hook into the bundle’s lifecycle (if exposed) to log or modify requests/responses.

3. Configuration Overrides: Extend the default config in config/packages/ee_embedly.yaml:

   ee_embedly:
       api_key: '%env(EMBEDLY_API_KEY)%'
       default_endpoint: 'oembed' # Override default 'embed'