README

A comprehensive PHP client for The Movie Database (TMDB) API built with modern PHP practices and full test coverage.

Author: Łukasz Zychal

⚖️ TMDB License Compliance

This client is designed to help you comply with TMDB API Terms of Service. When using this client, you must:

✅ Include TMDB Attribution - Display "This product uses the TMDB API but is not endorsed or certified by TMDB"
✅ Use Official TMDB Logo - Include the TMDB logo when displaying data
✅ Respect Rate Limits - This client includes built-in rate limiting
✅ Handle Errors Properly - Use the provided exception handling

See TMDB_LICENSE_COMPLIANCE.md for detailed requirements and examples.

Features

🎬 Complete TMDB API Coverage - Movies, TV Shows, People, Search, Configuration, Genres
🚀 Modern PHP - Built for PHP 8.1+ with strict types and PSR compliance
🛡️ Type Safety - Full type declarations and static analysis support
🧪 Comprehensive Testing - Unit, integration, and contract tests
📊 CI/CD Pipeline - Automated testing, code quality, and security scanning
📚 Well Documented - Complete API documentation and examples
🔧 PSR Standards - PSR-4 autoloading, PSR-3 logging, PSR-7 HTTP messages
⚡ Guzzle Integration - Built on top of Guzzle HTTP client
🎯 Exception Handling - Specific exceptions for different error types

Installation

Install via Composer:

composer require lukaszzychal/tmdb-client-php

Configuration

1. Get TMDB API Key

Visit themoviedb.org
Create an account or log in
Request an API key
Copy your API key

2. Configure API Key

Option A: Using .env file (Recommended)

# Copy the example environment file
cp .env.example .env

# Edit .env and replace 'your-tmdb-api-key-here' with your actual API key
nano .env

Option B: Environment Variable

export TMDB_API_KEY="your-actual-api-key"

Quick Start

<?php

use LukaszZychal\TMDB\Client\TMDBClient;
use LukaszZychal\TMDB\Utils\LicenseCompliance;

// Load API key from .env file or environment variable
$apiKey = $_ENV['TMDB_API_KEY'] ?? getenv('TMDB_API_KEY');

// Initialize the client
$client = new TMDBClient($apiKey);

// Get popular movies
$popularMovies = $client->movies()->getPopular();
$movies = json_decode($popularMovies->getBody()->getContents(), true);

// Display movies with TMDB attribution (REQUIRED for compliance)
foreach ($movies['results'] as $movie) {
    echo "<h3>{$movie['title']}</h3>";
    echo "<p>{$movie['overview']}</p>";
    
    // MANDATORY: Include TMDB attribution
    echo LicenseCompliance::generateHtmlAttribution();
}

// Get movie details
$movieDetails = $client->movies()->getDetails(550); // Fight Club
$movie = json_decode($movieDetails->getBody()->getContents(), true);

// Search for movies
$searchResults = $client->search()->movies('Inception');
$results = json_decode($searchResults->getBody()->getContents(), true);

📋 License Compliance Helper

<?php
use LukaszZychal\TMDB\Utils\LicenseCompliance;

// Generate attribution HTML
$attribution = LicenseCompliance::generateHtmlAttribution();

// Validate your HTML content
$validation = LicenseCompliance::validateHtmlAttribution($yourHtmlContent);

// Check compliance status
$compliance = LicenseCompliance::checkCompliance([
    'requests_per_day' => 500,
    'has_attribution' => true,
    'has_logo' => true
]);

if (!$compliance['is_compliant']) {
    echo "Issues: " . implode(', ', $compliance['issues']);
}

API Documentation

Movies

$movies = $client->movies();

// Get movie details
$movie = $movies->getDetails($movieId, ['language' => 'en-US']);

// Get popular movies
$popular = $movies->getPopular(['page' => 1]);

// Get now playing movies
$nowPlaying = $movies->getNowPlaying(['page' => 1, 'region' => 'US']);

// Get upcoming movies
$upcoming = $movies->getUpcoming(['page' => 1]);

// Get top rated movies
$topRated = $movies->getTopRated(['page' => 1]);

// Get movie credits
$credits = $movies->getCredits($movieId);

// Get movie reviews
$reviews = $movies->getReviews($movieId, ['page' => 1]);

// Get movie videos
$videos = $movies->getVideos($movieId, ['language' => 'en-US']);

// Get movie images
$images = $movies->getImages($movieId, ['language' => 'en-US']);

// Get similar movies
$similar = $movies->getSimilar($movieId, ['page' => 1]);

// Get recommendations
$recommendations = $movies->getRecommendations($movieId, ['page' => 1]);

TV Shows

$tv = $client->tv();

// Get TV show details
$show = $tv->getDetails($tvId, ['language' => 'en-US']);

// Get popular TV shows
$popular = $tv->getPopular(['page' => 1]);

// Get TV shows airing today
$airingToday = $tv->getAiringToday(['page' => 1]);

// Get TV shows on the air
$onTheAir = $tv->getOnTheAir(['page' => 1]);

// Get top rated TV shows
$topRated = $tv->getTopRated(['page' => 1]);

// Get season details
$season = $tv->getSeasonDetails($tvId, $seasonNumber);

// Get episode details
$episode = $tv->getEpisodeDetails($tvId, $seasonNumber, $episodeNumber);

People

$people = $client->people();

// Get person details
$person = $people->getDetails($personId, ['language' => 'en-US']);

// Get popular people
$popular = $people->getPopular(['page' => 1]);

// Get person movie credits
$movieCredits = $people->getMovieCredits($personId);

// Get person TV credits
$tvCredits = $people->getTVCredits($personId);

// Get person combined credits
$combinedCredits = $people->getCombinedCredits($personId);

Search

$search = $client->search();

// Search movies
$movies = $search->movies('Inception', ['year' => 2010]);

// Search TV shows
$tvShows = $search->tv('Breaking Bad', ['first_air_date_year' => 2008]);

// Search people
$people = $search->people('Leonardo DiCaprio');

// Multi search (movies, TV shows, people)
$multi = $search->multi('Marvel');

Configuration & Genres

// Get API configuration
$config = $client->configuration()->getDetails();

// Get movie genres
$movieGenres = $client->genres()->getMovieList(['language' => 'en-US']);

// Get TV genres
$tvGenres = $client->genres()->getTVList(['language' => 'en-US']);

Configuration

You can customize the HTTP client behavior:

use Psr\Log\LoggerInterface;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Create a logger
$logger = new Logger('tmdb');
$logger->pushHandler(new StreamHandler('tmdb.log', Logger::INFO));

// Initialize client with custom configuration
$client = new TMDBClient(
    'your-api-key',
    [
        'timeout' => 60,
        'connect_timeout' => 15,
        'headers' => [
            'User-Agent' => 'MyApp/1.0'
        ]
    ],
    $logger
);

Error Handling

The client provides specific exceptions for different error scenarios:

use LukaszZychal\TMDB\Exception\AuthenticationException;
use LukaszZychal\TMDB\Exception\NotFoundException;
use LukaszZychal\TMDB\Exception\RateLimitException;
use LukaszZychal\TMDB\Exception\TMDBException;

try {
    $movie = $client->movies()->getDetails(999999999);
} catch (AuthenticationException $e) {
    // Invalid API key
    echo "Authentication failed: " . $e->getMessage();
} catch (NotFoundException $e) {
    // Resource not found
    echo "Movie not found: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Rate limit exceeded
    echo "Rate limit exceeded: " . $e->getMessage();
} catch (TMDBException $e) {
    // Other TMDB API errors
    echo "API Error: " . $e->getMessage();
}

Testing

Running Tests

# Run all tests (includes contract tests - needs real API key)
composer test

# Run core tests only (Unit + Integration - no API key needed)
composer test-core

# Run specific test suites
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Integration
vendor/bin/phpunit --testsuite=Contract

# Run with coverage
composer test-coverage

Contract Tests

Contract tests verify the real TMDB API behavior. To run them:

Get a TMDB API key from themoviedb.org
Configure your API key using one of these methods:

Option A: Using .env file (Recommended)
```
cp .env.example .env
# Edit .env and add your API key
```
Option B: Environment variable
```
export TMDB_API_KEY=your-api-key-here
```
Run contract tests:
```
vendor/bin/phpunit --testsuite=Contract
```

Note: Contract tests are rate-limited and should be run sparingly. They're automatically scheduled to run daily in the CI/CD pipeline.

Code Quality

This package maintains high code quality standards using multiple static analysis tools:

# Core quality check (recommended for daily use)
composer quality-core    # Style + Type Safety + Advanced Analysis

# Quick style check only
composer quality-check

# Full quality check (includes contract tests - needs real API key)
composer quality

# Individual tools
composer php-cs-fixer    # Code style check
composer phpstan         # Static type analysis
composer psalm          # Advanced type analysis

# Auto-fix style issues
composer php-cs-fixer-fix

# Run core tests (Unit + Integration - no API key needed)
composer test-core

Quality Tools Used:

PHP CS Fixer: Code style and formatting
PHPStan: Static type analysis (Level 8)
Psalm: Advanced type analysis and security detection
PHPUnit: Unit, Integration, and Contract testing

For detailed information about all quality commands, see Quality Commands Reference.

Automated Maintenance

This project includes automated maintenance features to ensure reliability and security:

🔄 Dependabot Integration

Monthly dependency updates for Composer packages and GitHub Actions
Automatic pull requests for minor and patch updates
Grouped updates to reduce noise
Manual review required for major version updates

🧪 Monthly Contract Testing

Automated monthly tests against the real TMDB API
Runs on the 1st day of every month at 2:00 AM UTC
Validates API compatibility and integration health
Detailed test reports with failure notifications
Can be triggered manually via GitHub Actions

📊 CI/CD Pipeline

Daily lightweight contract tests for quick API health checks
Comprehensive testing on every push and pull request
Multi-PHP version support (8.1, 8.2, 8.3, 8.4)
Security scanning with Trivy vulnerability detection
Code quality checks with PHP CS Fixer, PHPStan, and Psalm

Examples

Basic Usage

See examples/basic-usage.php for a complete working example.

License Compliance

See examples/license-compliance-example.php for detailed TMDB license compliance examples including:

HTML attribution generation
CSS styling
JSON-LD structured data
Validation and compliance checking

Run examples:

php examples/basic-usage.php
php examples/license-compliance-example.php

Requirements

PHP 8.1 or higher
Composer
Guzzle HTTP Client 7.8+

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

lukaszzychal / tmdb-client-php

Maintainers

Details

README

⚖️ TMDB License Compliance

Features

Installation

Configuration

1. Get TMDB API Key

2. Configure API Key

Quick Start

📋 License Compliance Helper

API Documentation

Movies

TV Shows

People

Search

Configuration & Genres

Configuration

Error Handling

Testing

Running Tests

Contract Tests

Code Quality

Quality Tools Used:

Automated Maintenance

🔄 Dependabot Integration

🧪 Monthly Contract Testing

📊 CI/CD Pipeline

Examples

Basic Usage

License Compliance

Requirements

Contributing

License

Links

Changelog