Tmdb Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require bogdanfinn/tmdb-bundle
   

2. Enable the Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       bogdanfinn\tmdbBundle\tmdbBundle::class => ['all' => true],
   ];
   

3. Configure API Key Add to config/packages/tmdb.yaml:

   tmdb:
       api_key: "%env(TMDB_API_KEY)%"  # Store in .env
       use_models: true
   

4. First Use Case Fetch a TV show in a controller:

   use bogdanfinn\tmdbBundle\Client\TvShowClient;
   
   public function show(TvShowClient $tvShowClient)
   {
       $show = $tvShowClient->getShow(1397); // Stranger Things ID
       return $this->json($show);
   }
   

Implementation Patterns

Core Workflows

1. Service Injection Use dependency injection for all clients:

   public function __construct(
       private TvShowClient $tvShowClient,
       private MovieClient $movieClient,
       private EpisodeClient $episodeClient
   ) {}
   

2. Model vs. JSON

   • Set use_models: true for typed objects (e.g., Movie, TvShow).
   • Set false for raw JSON responses (useful for custom parsing).

3. Pagination Handling Use getPopular() or search() methods with pagination:

   $popularMovies = $movieClient->getPopular(1, 20); // Page 1, 20 items
   

4. Async Processing Queue API calls for heavy operations (e.g., fetching all episodes):

   $this->dispatch(new FetchEpisodesJob($tvShowClient, $showId));
   

Integration Tips

• Caching Responses Cache API responses with Symfony’s cache system:

  $cache = $this->get('cache.app');
  $key = "tmdb_show_{$showId}";
  if (!$cache->has($key)) {
      $show = $tvShowClient->getShow($showId);
      $cache->set($key, $show, 3600); // Cache for 1 hour
  }
  

• Error Handling Wrap API calls in try-catch:

  try {
      $show = $tvShowClient->getShow($showId);
  } catch (\Exception $e) {
      $this->addFlash('error', 'Failed to fetch show: ' . $e->getMessage());
      return $this->redirectToRoute('home');
  }
  

• Custom Endpoints Extend the bundle’s Client classes for unsupported endpoints:

  class CustomClient extends AbstractClient {
      public function getCustomEndpoint($endpoint, array $params = []) {
          return $this->request('GET', $endpoint, $params);
      }
  }
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Never hardcode API keys. Use .env and Symfony’s %env().
   • Rate limits apply (40 requests/10 seconds). Cache aggressively.

2. Model vs. JSON Mismatch

   • If use_models: true is set but models are missing, verify the Model namespace (bogdanfinn\tmdbBundle\Model) is autoloaded.

3. Deprecated Methods

   • The bundle is "work in progress." Check the GitHub issues for breaking changes.

4. Symfony Version Compatibility

   • Tested for Symfony 4/5. May require adjustments for older versions.

Debugging

• Enable Debug Mode Add to config/packages/dev/tmdb.yaml:

  tmdb:
      debug: true  # Logs API requests/responses
  

• Validate API Responses Use var_dump() or dd() to inspect raw JSON when models behave unexpectedly:

  $rawResponse = $tvShowClient->getShow($showId, ['use_models' => false]);
  

Extension Points

1. Custom Models Override bundle models in src/Model/:

   namespace App\Model;
   use bogdanfinn\tmdbBundle\Model\Movie as BaseMovie;
   
   class Movie extends BaseMovie {
       public function getCustomField() { ... }
   }
   

   Update config.yml to point to your models:

   tmdb:
       model_namespace: App\Model
   

2. Event Listeners Subscribe to API events (e.g., tmdb.response):

   // src/EventListener/TmdbListener.php
   public function onTmdbResponse(GetResponseEvent $event) {
       $response = $event->getResponse();
       // Modify response data
   }
   

3. Testing Mock the Client interface for unit tests:

   $mockClient = $this->createMock(TvShowClient::class);
   $mockClient->method('getShow')->willReturn(new TvShow());
   $this->container->set(TvShowClient::class, $mockClient);