Api Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install via Composer

   composer require php-tmdb/api
   

2. Publish Config (Optional but Recommended)

   php artisan vendor:publish --provider="Tmdb\TmdbServiceProvider" --tag="config"
   

   Edit config/tmdb.php to include your API key and preferred HTTP client (e.g., GuzzleHttp\Client).

3. First Use Case: Fetch a Movie

   use Tmdb\Tmdb;
   
   $tmdb = new Tmdb(config('tmdb.api_key'));
   $movie = $tmdb->getMovie(550); // Fetch *Fight Club*
   dd($movie->title, $movie->overview, $movie->poster_path);
   

4. Key Configuration

   • Set tmdb.api_key in .env or config/tmdb.php.
   • Override default HTTP client (e.g., tmdb.client = GuzzleHttp\Client).

Implementation Patterns

Core Workflows

1. Resource-Specific Queries

• Movies: $tmdb->getMovie($id), $tmdb->getMoviesNowPlaying()
• TV Shows: $tmdb->getTvShow($id), $tmdb->getTvShowsOnTheAir()
• People: $tmdb->getPerson($id), $tmdb->getPersonCredits($id)
• Search: $tmdb->searchMovie($query), $tmdb->searchMulti($query)

Example: Fetch Trending Movies

$trending = $tmdb->getTrending('movie', ['time_window' => 'day']);
foreach ($trending->results as $movie) {
    echo $movie->title . " (" . $movie->release_date->format('Y') . ")\n";
}

2. Pagination & Query Parameters

Use getMovies() with query params:

$popularMovies = $tmdb->getMovies('popular', [
    'page' => 2,
    'region' => 'US',
    'sort_by' => 'vote_average.desc'
]);

3. Image Handling

Access images via poster_path, backdrop_path, etc., and construct URLs:

$posterUrl = $tmdb->imageUrl($movie->poster_path, 'w500');
// Outputs: https://image.tmdb.org/t/p/w500/abc123.jpg

4. Laravel Integration

Service Provider Binding (Optional) Bind the client in AppServiceProvider:

$this->app->singleton(Tmdb::class, function ($app) {
    return new Tmdb(config('tmdb.api_key'), $app->make('http.client'));
});

Now inject Tmdb into controllers/services:

public function showMovie(Tmdb $tmdb, $id) {
    $movie = $tmdb->getMovie($id);
    return view('movie', compact('movie'));
}

5. Caching Responses

Cache API responses for 24 hours (adjust as needed):

$movie = Cache::remember("tmdb_movie_{$id}", now()->addHours(24), function () use ($tmdb, $id) {
    return $tmdb->getMovie($id);
});

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never commit config/tmdb.php or .env to version control.
   • Use Laravel’s .env for sensitive keys.

2. Rate Limiting

   • TMDb enforces rate limits. Handle 429 Too Many Requests gracefully:

     try {
         $tmdb->getMovie($id);
     } catch (\Tmdb\Exceptions\RateLimitException $e) {
         // Retry after delay or notify admin
     }
     

3. Deprecated Endpoints

   • The package was last updated in 2022. Verify endpoints (e.g., getMovieChanges()) exist in TMDb’s API docs.
   • Example: getMovieVideos() may require manual path construction if the wrapper is outdated.

4. Image Paths

   • poster_path/backdrop_path can be null. Always check:

     $posterUrl = $movie->poster_path ? $tmdb->imageUrl($movie->poster_path) : null;
     

Debugging

• Enable Guzzle Debugging Add to config/tmdb.php:

  'options' => [
      'debug' => env('TMDB_DEBUG', false),
  ],
  

  Check logs for raw API responses during issues.

• Validate Responses Use dd($tmdb->getMovie($id)->toArray()) to inspect raw data structure.

Extension Points

1. Custom HTTP Client Extend the client for middleware (e.g., logging, retry logic):

   $client = new \GuzzleHttp\Client([
       'timeout' => 10,
       'headers' => ['User-Agent' => 'MyApp/1.0'],
   ]);
   $tmdb = new Tmdb($apiKey, $client);
   

2. Add New Endpoints If missing, extend the Tmdb class or create a decorator:

   class ExtendedTmdb extends Tmdb {
       public function getCustomEndpoint($path, $params = []) {
           return $this->request('get', $path, $params);
       }
   }
   

3. Laravel Eloquent Models Sync TMDb data with local models:

   // Example: Sync movie metadata to a `Movie` model
   $tmdbMovie = $tmdb->getMovie($id);
   Movie::updateOrCreate(
       ['tmdb_id' => $id],
       [
           'title' => $tmdbMovie->title,
           'overview' => $tmdbMovie->overview,
           'poster_path' => $tmdbMovie->poster_path,
       ]
   );
   

Performance Tips

• Batch Requests Use searchMulti() for combined searches (movies, TV, people):

  $results = $tmdb->searchMulti('Inception', ['page' => 1]);
  

• Lazy-Load Images Defer image URL generation until needed (e.g., in Blade views):

  @if($movie->poster_path)
      <img src="{{ $tmdb->imageUrl($movie->poster_path, 'w300') }}">
  @endif