Laravel Hetzner Robot SDK

A premium, feature-rich PHP SDK and Laravel integration for the Hetzner Robot Web Service API, featuring rate-limit handling, automatic retries, and concurrent batch operations.

Features

100% Endpoint Coverage: Complete implementation of all 14 Robot webservice sections (servers, IPs, subnets, resets, failover, Wake-on-LAN, boot options, reverse DNS, traffic, SSH keys, order products, Storage Boxes, firewalls, and vSwitches).
Basic Authentication: Fully automated Basic Auth headers configuration.
Form Urlencoded Requests: Parameters transfer mapped automatically using application/x-www-form-urlencoded.
Fail-Safe Retries & Backoff: Robust exponential backoff and rate-limit parsing handling RATE_LIMIT_EXCEEDED errors automatically.
Concurrently Pooled Processing: Execute calls asynchronously or concurrently in batches.
Type-Safe DTOs: Automated data hydration into standard PHP DTO structures.
Custom Exceptions: Specialized mapping of API status codes (ValidationException, RateLimitException, AuthenticationException, etc.).

Installation

Install the package via Composer:

composer require ghostcompiler/laravel-hetzner-robot

Publish the configuration file:

php artisan vendor:publish --provider="Vendor\HetznerRobot\Providers\HetznerRobotServiceProvider" --tag="config"

Add your Hetzner Robot API Web Service credentials to your .env file:

HETZNER_ROBOT_USERNAME=your_web_service_username_here
HETZNER_ROBOT_PASSWORD=your_web_service_password_here
HETZNER_ROBOT_BASE_URL=https://robot-ws.your-server.de
HETZNER_ROBOT_TIMEOUT=30
HETZNER_ROBOT_RETRIES=3
HETZNER_ROBOT_LOGGING_ENABLED=true

Usage Examples

Servers

Listing and Finding Servers

use Vendor\HetznerRobot\Facades\HetznerRobot;

// List all servers
$servers = HetznerRobot::servers()->all();

foreach ($servers as $server) {
    echo $server->serverName . ': ' . $server->serverIp . "\n";
}

// Find a server by number
$server = HetznerRobot::servers()->find(321);
echo "DC: " . $server->dc;

Updating and Cancelling a Server

// Rename a server
$server = HetznerRobot::servers()->update(321, [
    'server_name' => 'production-web-01'
]);

// Cancel a server
$cancellation = HetznerRobot::servers()->createCancellation(321, [
    'cancellation_reason' => 'no_longer_needed'
]);
echo "Cancellation status: " . $cancellation->cancellationDate;

IP & Subnet Management

// List all IP addresses
$ips = HetznerRobot::ips()->all();

// Update reverse DNS (PTR)
$rdns = HetznerRobot::rdns()->create('123.123.123.123', 'your-domain.com');

// Enable MAC address for IP
$mac = HetznerRobot::ips()->updateMac('123.123.123.123', '00:11:22:33:44:55');

Boot Configurations (Rescue, Linux, Windows, VNC)

// Enable rescue system for server
$rescue = HetznerRobot::boots()->enableRescue(321, [
    'os' => 'linux',
    'arch' => 64
]);

echo "Temp password: " . $rescue->password;

Storage Box

// List storage boxes
$boxes = HetznerRobot::storageBoxes()->all();

// Create snapshot
$snapshot = HetznerRobot::storageBoxes()->createSnapshot($boxId);

// Get snapshot plan
$plan = HetznerRobot::storageBoxes()->getSnapshotPlan($boxId);

// Create sub-account
$sub = HetznerRobot::storageBoxes()->createSubAccount($boxId, [
    'homedirectory' => 'backup_sub'
]);

Firewall Configuration

// Find firewall for server
$firewall = HetznerRobot::firewalls()->find(321);

// Create or update firewall rules
HetznerRobot::firewalls()->create(321, [
    'status' => 'active',
    'filter_ipv6' => false,
    'whitelist_hos' => true,
    'rules' => [
        'input' => [
            [
                'name' => 'Allow HTTP',
                'ip_version' => 'ipv4',
                'dst_port' => '80',
                'action' => 'accept'
            ]
        ]
    ]
]);

vSwitches

// List vswitches
$vswitches = HetznerRobot::vswitches()->all();

// Create vswitch
$vswitch = HetznerRobot::vswitches()->create([
    'name' => 'vswitch-prod',
    'vlan' => 4000
]);

// Add servers to vswitch
HetznerRobot::vswitches()->addServers($vswitch->id, [321, 421]);

Asynchronous Requests

use GuzzleHttp\Promise\PromiseInterface;

// Return a Guzzle Promise immediately
$promise = HetznerRobot::servers()->async()->all();

// Resolve promise when ready
$servers = $promise->wait();

Batch Concurrent Operations

// Execute multiple queries concurrently
$results = HetznerRobot::batch([
    fn () => HetznerRobot::servers()->find(321),
    fn () => HetznerRobot::servers()->find(421),
    fn () => HetznerRobot::storageBoxes()->find(123456),
]);

$server1 = $results[0];
$server2 = $results[1];
$storageBox = $results[2];

Exception Handling

All exceptions inherit from Vendor\HetznerRobot\Exceptions\HetznerException.

use Vendor\HetznerRobot\Exceptions\AuthenticationException;
use Vendor\HetznerRobot\Exceptions\ValidationException;
use Vendor\HetznerRobot\Exceptions\RateLimitException;
use Vendor\HetznerRobot\Exceptions\HetznerException;

try {
    HetznerRobot::servers()->update(321, []);
} catch (AuthenticationException $e) {
    // 401 Unauthorized
} catch (ValidationException $e) {
    // 400 Bad Request / INVALID_INPUT
    $missingFields = $e->getMissingFields();
    $invalidFields = $e->getInvalidFields();
} catch (RateLimitException $e) {
    // 403 Rate Limit Exceeded
    $maxRequest = $e->getMaxRequest();
} catch (HetznerException $e) {
    // Base exception handler
}

Static Analysis & Linting

Run PHPStan static analysis:

vendor/bin/phpstan analyse

Run Psalm static analysis:

vendor/bin/psalm

Format code with Pint:

vendor/bin/pint

Development Environment

Built using ServBay

Mac M4 Tested
macOS Apple Silicon
Powered by ServBay

<?php namespace Vendor\HetznerRobot\DTOs; class OrderProduct { public string $id; public string $name; public array $description = []; public string $traffic; public array $dist = []; public array $lang = []; public array $location = []; public array $prices = []; public array $orderableAddons = []; public array $arch = []; public string $cpu = ''; public int $cpuBenchmark = 0; public int $memorySize = 0; public int $hddSize = 0; public string $hddText = ''; public int $hddCount = 0; public string $datacenter = ''; public string $networkSpeed = ''; public float $price = 0.0; public float $priceHourly = 0.0; public float $priceSetup = 0.0; public float $priceVat = 0.0; public float $priceHourlyVat = 0.0; public float $priceSetupVat = 0.0; public bool $fixedPrice = false; public int $nextReduce = 0; public string $nextReduceDate = ''; public static function fromArray(array $data): self { $product = new self; $product->id = (string) ($data['id'] ?? ''); $product->name = (string) ($data['name'] ?? ''); $product->description = (array) ($data['description'] ?? []); $product->traffic = (string) ($data['traffic'] ?? ''); $product->dist = (array) ($data['dist'] ?? []); $product->lang = (array) ($data['lang'] ?? []); $product->location = (array) ($data['location'] ?? []); $product->prices = (array) ($data['prices'] ?? []); $product->orderableAddons = (array) ($data['orderable_addons'] ?? []); $product->arch = (array) ($data['arch'] ?? []); $product->cpu = (string) ($data['cpu'] ?? ''); $product->cpuBenchmark = (int) ($data['cpu_benchmark'] ?? 0); $product->memorySize = (int) ($data['memory_size'] ?? 0); $product->hddSize = (int) ($data['hdd_size'] ?? 0); $product->hddText = (string) ($data['hdd_text'] ?? ''); $product->hddCount = (int) ($data['hdd_count'] ?? 0); $product->datacenter = (string) ($data['datacenter'] ?? ''); $product->networkSpeed = (string) ($data['network_speed'] ?? ''); $product->price = (float) ($data['price'] ?? 0.0); $product->priceHourly = (float) ($data['price_hourly'] ?? 0.0); $product->priceSetup = (float) ($data['price_setup'] ?? 0.0); $product->priceVat = (float) ($data['price_vat'] ?? 0.0); $product->priceHourlyVat = (float) ($data['price_hourly_vat'] ?? 0.0); $product->priceSetupVat = (float) ($data['price_setup_vat'] ?? 0.0); $product->fixedPrice = (bool) ($data['fixed_price'] ?? false); $product->nextReduce = (int) ($data['next_reduce'] ?? 0); $product->nextReduceDate = (string) ($data['next_reduce_date'] ?? ''); return $product; } }

Laravel Hetzner Robot