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

StatusActions

DownloadActions

QueueActions

HistoryActions

License

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