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

Method	Description
`version()`	Get the NZBGet version
`shutdown()`	Shutdown the NZBGet server
`reload()`	Reload the configuration

StatusActions

Method	Description
`get()`	Get current server status
`serverVolumes()`	Get server volume statistics
`resetServerVolume(int $serverId, ServerCounter $counter)`	Reset server volume counter

DownloadActions

Method	Description
`pause()`	Pause all downloads
`resume()`	Resume all downloads
`pausePost()`	Pause post-processing
`resumePost()`	Resume post-processing
`pauseScan()`	Pause directory scanning
`resumeScan()`	Resume directory scanning
`rate(int $limitKbPerSecond)`	Set speed limit (Limit disabled by default (`0`))
`scheduleResume(int $secondsToWait)`	Schedule automatic resume

QueueActions

Method	Description
`listGroups(int $logEntries = 0)`	List all queue groups
`pause(array $ids)`	Pause specific items
`resume(array $ids)`	Resume specific items
`delete(array $ids)`	Delete specific items
`setPriority(array $ids, int $priority)`	Set priority
`setCategory(array $ids, string $category)`	Set category
`setName(array $ids, string $name)`	Rename items
`moveTop(array $ids)`	Move to top of queue
`moveBottom(array $ids)`	Move to bottom of queue

HistoryActions

Method	Description
`get(bool $includeHidden = false)`	Get history items
`hide(array $ids)`	Hide items (soft delete)
`delete(array $ids)`	Permanently delete items
`returnToQueue(array $ids)`	Return items to queue
`process(array $ids)`	Re-run post-processing
`redownload(array $ids)`	Redownload items
`setName(array $ids, string $name)`	Rename items
`setDupeKey(array $ids, string $key)`	Set duplicate key
`setDupeScore(array $ids, int $score)`	Set duplicate score
`setDupeMode(array $ids, DupeMode $mode)`	Set duplicate mode
`markBad(array $ids)`	Mark as bad
`markGood(array $ids)`	Mark as good
`markSuccess(array $ids)`	Mark as success

License

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

martincamen / nzbget-php

Maintainers

Details