Themoviedb Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require ghanem/themoviedb
   php artisan migrate
   php artisan vendor:publish --provider="Ghanem\Themoviedb\ThemoviedbServiceProvider" --tag="config"
   

2. Configure API Key

   • Register at The Movie Database to obtain an API key.
   • Add to .env:

     THEMOVIEDB_KEY=your_api_key_here
     THEMOVIEDB_NUM_OF_RECORDS=20  # Optional: Default is 100
     

3. First Use Case Seed top-rated movies via CLI:

   php artisan themoviedb:seed top_rated_movies
   

   Verify data via the /movies endpoint (default route).

Implementation Patterns

Workflows

1. Seeding Data

   • One-Time Seeds: Use the CLI command for initial setup:

     php artisan themoviedb:seed [type]  # e.g., top_rated_movies, popular_movies
     

   • Scheduled Seeds: Integrate with Laravel’s task scheduling (e.g., app/Console/Kernel.php):

     $schedule->command('themoviedb:seed top_rated_movies')->daily();
     

     Ensure cron runs php artisan schedule:run (e.g., * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1).

2. Queue-Based Processing Enable async processing in .env:

   THEMOVIEDB_ENABLE_QUEUE=true
   

   • Requires a queue worker (e.g., php artisan queue:work).

3. API Integration

   • Fetch movies programmatically via the service class:

     use Ghanem\Themoviedb\Facades\Themoviedb;
     
     $movies = Themoviedb::getMovies('top_rated');
     

   • Customize routes/middleware via config/themoviedb.php:

     'prefix' => 'api/v1',
     'middleware' => ['throttle:60'],
     

4. Data Validation

   • Extend the Movie model or use API responses directly:

     $response = Themoviedb::callApi('movie/popular');
     $movies = collect($response['results'])->map(fn($item) => [
         'title' => $item['title'],
         'vote_average' => $item['vote_average'],
     ]);
     

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • The Movie Database API has rate limits. Monitor usage if seeding frequently.
   • Fix: Implement retries with exponential backoff (e.g., using GuzzleHttp\Exception\RequestException).

2. Queue Configuration

   • If THEMOVIEDB_ENABLE_QUEUE=true, ensure:
     • A queue driver is configured in .env (e.g., QUEUE_CONNECTION=database).
     • The failed_jobs table exists (run php artisan queue:failed-table if missing).
   • Debug: Check queue jobs with php artisan queue:work --once --verbose.

3. Migration Conflicts

   • The package’s migrations may conflict with existing movies/genres tables.
   • Fix: Review database/migrations/ for duplicates or customize the seeder to append data.

4. Deprecated Endpoints

   • The package uses endpoints like top_rated_movies, but TMDb’s API may change.
   • Tip: Validate endpoints against TMDb’s API docs periodically.

Debugging

• API Errors: Log raw responses to debug:

  try {
      $response = Themoviedb::callApi('movie/popular');
  } catch (\Exception $e) {
      \Log::error('TMDb API Error:', ['response' => $response->getBody(), 'error' => $e->getMessage()]);
  }
  

• Seeder Issues: Check for duplicate entries by adding a unique constraint to the movies table’s tmdb_id column.

Extension Points

1. Custom Seeders Override the seeder logic in app/Providers/ThemoviedbServiceProvider.php:

   public function boot()
   {
       $this->app->extend('themoviedb.seeder', function ($seeder) {
           return new CustomSeeder($seeder->getClient());
       });
   }
   

2. Additional Fields Extend the Movie model to include TMDb-specific fields:

   // app/Models/Movie.php
   protected $casts = [
       'release_date' => 'date',
       'vote_average' => 'float',
   ];
   

3. Webhooks for Updates Use TMDb’s Change Log API to sync updates:

   $changes = Themoviedb::callApi('changelog/movies');
   // Process $changes['results'] to update your DB.
   

4. Testing Mock the API client in tests:

   $mock = Mockery::mock('overload:Ghanem\Themoviedb\Themoviedb');
   $mock->shouldReceive('callApi')->andReturn(['results' => []]);