README

A PHP SDK for the NZBGet JSON-RPC API.

Requirements

• PHP 8.2+

Installation

composer require martincamen/nzbget-php

Usage

use NZBGet\NZBGet;

$nzbget = new NZBGet(
    host: 'localhost',
    port: 6789,
    username: 'admin',
    password: 'secret',
    useHttps: false,
    timeout: 30,
);

$version = $nzbget->program()->version();
$history = $nzbget->history()->get();

Working with Collections

The SDK returns typed DTOs and collections:

// Get history as a typed collection
$history = $nzbget->history()->get();

// Iterate with typed items
foreach ($history as $item) {
    echo $item->nzbName;  // string
    echo $item->status;   // string
    echo $item->health;   // int
    echo $item->dupeMode; // DupeMode enum
}

// Collection methods
$first = $history->first();     // ?HistoryItem
$last = $history->last();       // ?HistoryItem
$found = $history->find(123);   // ?HistoryItem by ID
$count = $history->count();     // int
$isEmpty = $history->isEmpty(); // bool

// Filter items
$movies = $history->filter(fn($item) => $item->category === 'movies');

// Map collection
$names = $history->map(fn($item) => $item->nzbName);

// Convert to array
$array = $history->toArray();

Using Enums

The SDK provides typed enums for commands and modes:

use NZBGet\Data\Enums\DupeMode;
use NZBGet\Data\Enums\ServerCounter;

// Set duplicate mode with enum
$nzbget->history()->setDupeMode([1, 2], DupeMode::Force);

// Available DupeMode values
DupeMode::Score; // 'SCORE'
DupeMode::All;   // 'ALL'
DupeMode::Force; // 'FORCE'

// Reset server volume counter with enum
$nzbget->status()->resetServerVolume(1, ServerCounter::Custom);

// Available ServerCounter values
ServerCounter::Custom; // Reset custom counter only
ServerCounter::All;    // Reset all counters

Error Handling

The SDK throws specific exceptions for different error types:

use NZBGet\Exceptions\AuthenticationException;
use NZBGet\Exceptions\ConnectionException;
use NZBGet\Exceptions\JsonRpcException;

try {
    $version = $nzbget->program()->version();
} catch (AuthenticationException $e) {
    // Invalid username or password
} catch (ConnectionException $e) {
    // Could not connect to the server
} catch (JsonRpcException $e) {
    // JSON-RPC error from NZBGet
    echo $e->rpcCode;    // Error code
    echo $e->getMessage(); // Error message
}

Testing

The SDK provides testing utilities for easy mocking:

use NZBGet\Testing\NZBGetFake;
use NZBGet\Testing\Factories\HistoryItemFactory;
use NZBGet\Testing\Factories\QueueGroupFactory;
use NZBGet\Testing\Factories\StatusFactory;
use PHPUnit\Framework\Attributes\Test;

class MyTest extends TestCase
{
    #[Test]
    public function itDisplaysHistory(): void
    {
        // Create a fake NZBGet instance
        $fake = new NZBGetFake([
            'history' => HistoryItemFactory::new()->count(5)->makeArray(),
            'status'  => StatusFactory::new()->makeArray(),
            'version' => '21.1',
        ]);

        // Use it in your code
        $history = $fake->history()->get();

        // Assert calls were made
        $fake->assertCalled('history');
        $fake->assertCalledWith('history', [false]);
        $fake->assertNotCalled('shutdown');
        $fake->assertCalledTimes('history', 1);
    }

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

        $fake->history()->hide([1, 2, 3]);

        $fake->assertCalledWith('editqueue', ['HistoryDelete', 0, '', [1, 2, 3]]);
    }
}

Using Factories

use NZBGet\Testing\Factories\HistoryItemFactory;
use NZBGet\Testing\Factories\QueueGroupFactory;

// Create a single item
$item = HistoryItemFactory::new()->make();

// Create multiple items
$collection = HistoryItemFactory::new()->count(5)->make();

// Create with custom attributes
$item = HistoryItemFactory::new()
    ->withAttributes([
        'NZBID'    => 123,
        'Category' => 'movies',
        'Status'.  => 'SUCCESS/ALL',
    ])
    ->make();

// Get raw array data (for API mocking)
$data = HistoryItemFactory::new()->count(3)->makeArray();

Available Actions

ProgramActions

StatusActions

DownloadActions

QueueActions

HistoryActions

License

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