README

Laravel wrapper for the NZBGet PHP SDK.

Requirements

PHP 8.3+
Laravel 11.0+ or 12.0+

Installation

composer require martincamen/laravel-nzbget

The package will auto-register its service provider.

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="NZBGet\NZBGetServiceProvider"

Add the following environment variables to your .env file:

NZBGET_HOST=localhost
NZBGET_PORT=6789
NZBGET_USERNAME=your-username
NZBGET_PASSWORD=your-password
NZBGET_USE_HTTPS=false
NZBGET_TIMEOUT=30

Usage

use NZBGet\Facades\NZBGet;

// Program actions
$version = NZBGet::program()->version(); // Returns "21.1"
NZBGet::program()->reload();             // Reload configuration
NZBGet::program()->shutdown();           // Shutdown server

// Status actions
$status = NZBGet::status()->get();                             // Returns Status DTO
echo $status->remainingSizeMB;                                 // Get remaining download size
echo $status->downloadPaused;                                  // Check if downloads paused
echo $status->isDownloading();                                 // Check if actively downloading
NZBGet::status()->serverVolumes();                             // Returns ServerVolumeCollection
NZBGet::status()->resetServerVolume(1, ServerCounter::Custom); // Reset server volume counter

// Download actions
NZBGet::download()->pause();              // Pause all downloads
NZBGet::download()->resume();             // Resume all downloads
NZBGet::download()->pausePost();          // Pause post-processing
NZBGet::download()->resumePost();         // Resume post-processing
NZBGet::download()->pauseScan();          // Pause scanning
NZBGet::download()->resumeScan();         // Resume scanning
NZBGet::download()->rate(5000);           // Set speed limit to 5000 KB/s
NZBGet::download()->scheduleResume(3600); // Resume in 1 hour (3600 seconds)

// Queue actions
$queue = NZBGet::queue()->listGroups();      // Returns QueueGroupCollection
NZBGet::queue()->pause([1, 2, 3]);           // Pause specific items
NZBGet::queue()->resume([1, 2, 3]);          // Resume specific items
NZBGet::queue()->delete([1, 2, 3]);          // Delete specific items
NZBGet::queue()->setPriority([1], 100);      // Set priority
NZBGet::queue()->setCategory([1], 'movies'); // Set category
NZBGet::queue()->moveTop([1, 2]);            // Move to top of queue
NZBGet::queue()->moveBottom([1, 2]);         // Move to bottom of queue

// History actions
$history = NZBGet::history()->get();                   // Returns HistoryItemCollection
$hidden = NZBGet::history()->get(includeHidden: true); // Returns HistoryItemCollection with hidden items
NZBGet::history()->hide([1, 2, 3]);                    // Hide items (soft delete)
NZBGet::history()->delete([1, 2]);                     // Permanently delete
NZBGet::history()->returnToQueue([1]);                 // Return to download queue
NZBGet::history()->redownload([1]);                    // Redownload item
NZBGet::history()->markGood([1, 2]);                   // Mark as good
NZBGet::history()->markBad([1, 2]);                    // Mark as bad

Dependency Injection

use NZBGet\NZBGet;

class MyController
{
    public function __construct(private NZBGet $nzbget) {}

    public function index()
    {
        $history = $this->nzbget->history()->get();

        return view('history', ['items' => $history]);
    }
}

Working with Collections

The SDK returns typed DTOs and collections:

use NZBGet\Facades\NZBGet;

// 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(HistoryItem $item) => $item->category === 'movies');

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

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

Using Enums

The SDK provides typed enums for commands and modes:

use NZBGet\Facades\NZBGet;
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\Facades\NZBGet;
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 / laravel-nzbget

Maintainers

Details