README

A PHP SDK for the Jellyseerr/Overseerr REST API.

Important

This project is still being developed and breaking changes might occur even between patch versions.

The aim is to follow semantic versioning as soon as possible.

Ecosystem

Requirements

• PHP 8.3+

Installation

composer require martincamen/jellyseerr-php

Quick Start

use MartinCamen\Jellyseerr\JellySeerr;

$jellyseerr = JellySeerr::create(
    host: 'localhost',
    port: 5055,
    apiKey: 'your-api-key',
    useHttps: false,
);

// Get all media requests
$requests = $jellyseerr->requests()->all();

// Search for movies and series
$results = $jellyseerr->search()->search('Breaking Bad');

// Get movie details by TMDB ID
$movie = $jellyseerr->movies()->find(27205);

// Get system status
$status = $jellyseerr->system()->status();

Usage

Requests

Manage media requests (approve, decline, create, etc.):

use MartinCamen\Jellyseerr\Data\Options\RequestOptions;
use MartinCamen\Jellyseerr\Data\Responses\MediaRequest;
use MartinCamen\Jellyseerr\Data\Responses\RequestPage;

// Get all requests (paginated)
/** @var RequestPage $requests */
$requests = $jellyseerr->requests()->all();

foreach ($requests as $request) {
    echo $request->id;
    echo $request->status->value;
    echo $request->requestedBy?->displayName;
}

// Get requests with filtering
$options = RequestOptions::make()
    ->withFilter('pending')
    ->withTake(50);
$requests = $jellyseerr->requests()->all($options);

// Get a specific request
/** @var MediaRequest $request */
$request = $jellyseerr->requests()->find(1);

// Get request counts by status
$counts = $jellyseerr->requests()->count();
echo "Pending: {$counts->pending}";
echo "Approved: {$counts->approved}";
echo "Total: {$counts->total}";

// Create a movie request
$request = $jellyseerr->requests()->movie(tmdbId: 27205);

// Create a series request (all seasons)
$request = $jellyseerr->requests()->series(tmdbId: 1396);

// Create a series request (specific seasons)
$request = $jellyseerr->requests()->series(tmdbId: 1396, seasons: [1, 2, 3]);

// Create a 4K request
$request = $jellyseerr->requests()->movie(tmdbId: 27205, is4k: true);

// Approve a pending request
$request = $jellyseerr->requests()->approve(1);

// Decline a pending request
$request = $jellyseerr->requests()->decline(1);

// Retry a failed request
$request = $jellyseerr->requests()->retry(1);

// Delete a request
$jellyseerr->requests()->delete(1);

Movies

Get movie details and related content:

use MartinCamen\Jellyseerr\Data\Responses\MovieDetails;
use MartinCamen\Jellyseerr\Data\Responses\SearchPage;

// Get movie details by TMDB ID
/** @var MovieDetails $movie */
$movie = $jellyseerr->movies()->find(27205);

echo $movie->title;
echo $movie->overview;
echo $movie->releaseDate;
echo $movie->status;

// Get movie recommendations
/** @var SearchPage $recommendations */
$recommendations = $jellyseerr->movies()->recommendations(27205);

foreach ($recommendations as $result) {
    echo $result->title;
    echo $result->mediaType;
}

// Get similar movies
$similar = $jellyseerr->movies()->similar(27205);

Series

Get series details and related content:

use MartinCamen\Jellyseerr\Data\Responses\SeriesDetails;
use MartinCamen\Jellyseerr\Data\Responses\SearchPage;

// Get series details by TMDB ID
/** @var SeriesDetails $series */
$series = $jellyseerr->series()->find(1396);

echo $series->name;
echo $series->overview;
echo $series->firstAirDate;
echo $series->status;
echo $series->numberOfSeasons;

// Get series recommendations
/** @var SearchPage $recommendations */
$recommendations = $jellyseerr->series()->recommendations(1396);

// Get similar series
$similar = $jellyseerr->series()->similar(1396);

// Get season details
$season = $jellyseerr->series()->season(tmdbId: 1396, seasonId: 1);

Search

Search and discover content:

use MartinCamen\Jellyseerr\Data\Responses\SearchPage;

// Search for movies and series
/** @var SearchPage $results */
$results = $jellyseerr->search()->search('Inception');

foreach ($results as $result) {
    echo $result->title;
    echo $result->mediaType; // 'movie' or 'tv'
    echo $result->id; // TMDB ID
}

// Paginated search
$page2 = $jellyseerr->search()->search('Inception', page: 2);

// Discover movies
$movies = $jellyseerr->search()->discoverMovies();

// Discover series
$series = $jellyseerr->search()->discoverSeries();

// Get trending content
$trending = $jellyseerr->search()->trending();

// Get upcoming movies
$upcoming = $jellyseerr->search()->upcoming();

Users

Manage users and their requests:

use MartinCamen\Jellyseerr\Data\Responses\User;
use MartinCamen\Jellyseerr\Data\Responses\UserPage;

// Get all users (paginated)
/** @var UserPage $users */
$users = $jellyseerr->users()->all();

foreach ($users as $user) {
    echo $user->id;
    echo $user->displayName;
    echo $user->email;
}

// Get all users with pagination
$users = $jellyseerr->users()->all(['take' => 50, 'skip' => 0]);

// Get a specific user
/** @var User $user */
$user = $jellyseerr->users()->find(1);

// Get the currently authenticated user
$me = $jellyseerr->users()->me();

// Get a user's requests
$requests = $jellyseerr->users()->requests(userId: 1);

// Get a user's watchlist
$watchlist = $jellyseerr->users()->watchlist(userId: 1);

System

Get system status and settings:

use MartinCamen\Jellyseerr\Data\Responses\SystemSummary;

// Get system status
/** @var SystemSummary $status */
$status = $jellyseerr->system()->status();

echo $status->version;
echo $status->commitTag;

// Get appdata path information
$appdata = $jellyseerr->system()->appdata();

// Get public settings (no auth required)
$settings = $jellyseerr->system()->publicSettings();

Request Options

The SDK provides typed request option classes:

use MartinCamen\Jellyseerr\Data\Options\RequestOptions;

// Create options with fluent builder
$options = RequestOptions::make()
    ->withFilter('pending')      // all, pending, approved, processing, available
    ->withSort('added')          // added, modified
    ->withRequestedBy(1)         // filter by user ID
    ->withTake(50)               // page size
    ->withSkip(0);               // offset

$requests = $jellyseerr->requests()->all($options);

// Or pass array directly
$requests = $jellyseerr->requests()->all([
    'filter' => 'pending',
    'take'   => 50,
]);

Error Handling

The SDK throws specific exceptions for different error types:

use MartinCamen\ArrCore\Exceptions\AuthenticationException;
use MartinCamen\ArrCore\Exceptions\ConnectionException;
use MartinCamen\ArrCore\Exceptions\NotFoundException;
use MartinCamen\ArrCore\Exceptions\ValidationException;

try {
    $movie = $jellyseerr->movies()->find(999999999);
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (NotFoundException $e) {
    // Movie not found
} catch (ConnectionException $e) {
    // Could not connect to server
} catch (ValidationException $e) {
    // Validation error
    print_r($e->getErrors());
}

Testing

The SDK provides testing utilities for easy mocking:

use PHPUnit\Framework\Attributes\Test;
use MartinCamen\Jellyseerr\Testing\Factories\MovieDetailsFactory;
use MartinCamen\Jellyseerr\Testing\Factories\RequestFactory;
use MartinCamen\Jellyseerr\Testing\Factories\SearchResultFactory;
use MartinCamen\Jellyseerr\Testing\JellyseerrFake;

class MyTest extends TestCase
{
    #[Test]
    public function itDisplaysRequests(): void
    {
        $fake = new JellyseerrFake();

        $requests = $fake->requests()->all();

        $this->assertNotEmpty($requests);
        $fake->assertCalled('requests');
    }

    #[Test]
    public function itSearchesForMovies(): void
    {
        $fake = new JellyseerrFake();

        $results = $fake->search()->search('Inception');

        $fake->assertCalled('search');
    }
}

Using Factories

use MartinCamen\Jellyseerr\Testing\Factories\MovieDetailsFactory;
use MartinCamen\Jellyseerr\Testing\Factories\RequestFactory;
use MartinCamen\Jellyseerr\Testing\Factories\SearchResultFactory;
use MartinCamen\Jellyseerr\Testing\Factories\SeriesDetailsFactory;
use MartinCamen\Jellyseerr\Testing\Factories\SystemStatusFactory;
use MartinCamen\Jellyseerr\Testing\Factories\UserFactory;

// Create movie details data
$movie = MovieDetailsFactory::make(27205);
$movie = MovieDetailsFactory::make(27205, [
    'title'       => 'Inception',
    'releaseDate' => '2010-07-16',
]);

// Create series details data
$series = SeriesDetailsFactory::make(1396);
$series = SeriesDetailsFactory::make(1396, [
    'name'            => 'Breaking Bad',
    'numberOfSeasons' => 5,
]);

// Create request data
$request = RequestFactory::make(1);
$requests = RequestFactory::makeMany(5);

// Create search result data
$results = SearchResultFactory::makeMany(10);
$movies = SearchResultFactory::makeMovies(5);
$series = SearchResultFactory::makeSeries(5);

// Create user data
$user = UserFactory::make(1);

// Create system status data
$status = SystemStatusFactory::make();
$status = SystemStatusFactory::make([
    'version'   => '2.0.0',
    'commitTag' => 'abc123',
]);

Architecture

The SDK follows a layered architecture:

JellySeerr (Public SDK)
  ↓
Action Classes (RequestActions, MovieActions, etc.)
  ↓
Endpoint Classes (RequestEndpoint, MediaEndpoint, etc.)
  ↓
HTTP Client

• JellySeerr: The public entry point returning action classes
• Action Classes: Type-safe methods for each domain (requests()->all(), movies()->find(1))
• Endpoint Classes: Low-level API calls using Jellyseerr's native terminology
• Response Types: Typed DTOs from the SDK (MovieDetails, RequestPage, etc.)

License

The MIT License (MIT). Please see License File for more information.