README

PHP library for the Hetzner Robot Webservice (dedicated servers, Storage Box, ordering, etc.). HTTP uses PHP’s curl extension only (no PECL http, no Guzzle, no stream wrappers).

Authentication is HTTP Basic Auth (Robot “web service user” + password). POST and PUT parameters are sent as application/x-www-form-urlencoded, as required by the official API.

Architecture diagram

Requirements

PHP 8.1+ (including current 8.5+ releases).
Extensions: curl, json

Installation

composer require ghostcompiler/hetzner-robot

Or add a path repository for local development:

{
  "repositories": [{ "type": "path", "url": "../hetzner-robot" }],
  "require": { "ghostcompiler/hetzner-robot": "*" }
}

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use Ghostcompiler\HetznerRobot\HetznerRobotClient;
use Ghostcompiler\HetznerRobot\ApiException;

$user = getenv('HETZNER_ROBOT_USER') ?: '';
$pass = getenv('HETZNER_ROBOT_PASSWORD') ?: '';
$client = new HetznerRobotClient($user, $pass);

try {
    $data = $client->servers->listServers();
    // JSON array of { "server": { ... } } entries, or see official docs for each endpoint
} catch (ApiException $e) {
    echo $e->getMessage(), ' (HTTP ', $e->getHttpStatus(), ")\n";
    if ($e->getApiErrorCode()) {
        echo 'API code: ', $e->getApiErrorCode(), "\n";
    }
}

Optional base URL

$client = new HetznerRobotClient($user, $pass, 'https://robot-ws.your-server.de');

Form bodies (POST / PUT)

Pass PHP arrays; they are encoded as form fields. For repeated fields such as ip[] in POST /traffic, pass a list (sequential array):

$client->traffic->queryTraffic([
    'type' => 'month',
    'from' => '2024-01-01',
    'to' => '2024-01-31',
    'ip' => ['203.0.113.1', '203.0.113.2'],
]);

DELETE with a body

Some endpoints (for example DELETE /vswitch/{id} and DELETE /vswitch/{id}/server) require form fields on DELETE. Use the corresponding client methods; the transport sends the body when provided.

Testing (PHPUnit)

composer install
composer test

Integration tests (real API) are excluded by default. To run them:

export HETZNER_ROBOT_USER='your-webservice-user'
export HETZNER_ROBOT_PASSWORD='your-password'
./vendor/bin/phpunit --group integration

Interactive demo (browser)

The demo/ folder is a single-page explorer (JavaScript fetch + copy):

Enter Web service user and password (optional Save in browser → localStorage).
Expand a resource client and run any public method; array parameters use JSON in the UI (decoded to PHP arrays for form/query use).
Responses are JSON; Copy response uses the Clipboard API on secure contexts, with a fallback otherwise.

Security: use locally only; do not expose demo/ on a public server.

composer install
php -S 127.0.0.1:8080 -t demo

Open http://127.0.0.1:8080.

Method labels and paths in the demo come from demo/includes/method_summaries.json. Regenerate after changing client methods:

php tools/generate_method_summaries.php

How requests are built

flowchart LR
  app[Your_code]
  facade[HetznerRobotClient]
  sub[Resource_clients]
  curl[CurlTransport]
  api[robot_ws_your_server_de]
  app --> facade
  facade --> sub
  sub --> curl
  curl -->|"HTTPS_BasicAuth_form_or_query"| api

Official documentation

Robot Webservice (EN)

This project mirrors the layout and patterns of the Hetzner Cloud PHP SDK (HetznerClient, cURL-only transport), adapted for Robot’s Basic Auth and form-encoded writes.

ghostcompiler / hetzner-robot

Maintainers

Package info

Statistics

Security