README

What is it for? | What are the requirements? | How to install it? | How to use it? | How to contribute?

Framework-agnostic Hetzner Cloud API SDK with typed models and safe token obfuscation.

What is it for?

A fully async PHP SDK for the Hetzner Cloud API. All methods return GuzzleHttp\Promise\PromiseInterface, allowing non-blocking usage. Features include:

Typed readonly models with factory methods
Bearer token obfuscation in logs and exceptions
Automatic retry on connection failures and Retry-After responses
PSR-3 logger and PSR-16 cache integration

Supported Resources

Servers — list, get, create, delete, power on/off, rebuild
Firewalls — list, get, create, delete, set rules, apply/remove resources
SSH Keys — list, get, create, delete
Actions — get

What are the requirements?

PHP 8.4 or above
ext-json

How to install it?

composer require poor-plebs/hetzner-cloud-sdk

How to use it?

use PoorPlebs\HetznerCloudSdk\HetznerCloudClient;

$client = new HetznerCloudClient(
    apiToken: 'your-hetzner-api-token',
    cache: $yourPsr16Cache,
);

// List servers
$response = $client->servers()->list()->wait();
foreach ($response->result as $server) {
    echo $server->name . ' — ' . $server->status . PHP_EOL;
}

// Get a single server
$response = $client->servers()->get(123)->wait();
echo $response->result->publicNet->ipv4->ip;

// Create a server
$response = $client->servers()->create([
    'name' => 'my-server',
    'server_type' => 'cx22',
    'image' => 'ubuntu-24.04',
    'location' => 'fsn1',
])->wait();

// Power off a server
$client->servers()->powerOff(123)->wait();

// List firewalls
$response = $client->firewalls()->list()->wait();

// Create an SSH key
$response = $client->sshKeys()->create(
    name: 'deploy-key',
    publicKey: 'ssh-rsa AAAA...',
)->wait();

// Set a PSR-3 logger
$client->setLogger($yourPsr3Logger);

How to contribute?

poor-plebs/hetzner-cloud-sdk follows semantic versioning. Read more on semver.org.

Create issues to report problems or requests. Fork and create pull requests to propose solutions and ideas.

Development Setup

This project uses modern PHP tooling with strict quality standards:

Testing: Pest PHP v4 with parallel execution
Static Analysis: PHPStan at level max with strict and deprecation rules
Code Style: PHP-CS-Fixer (PSR-12)
Coverage Requirements: Minimum 80% code coverage and 80% type coverage

Available Commands

composer test          # Run tests (parallel, no coverage)
composer coverage      # Run tests with coverage (min 80%)
composer type-coverage # Check type coverage (min 80%)
composer static        # Run PHPStan analysis
composer cs            # Check code style
composer csf           # Fix code style
composer ci            # Run full CI pipeline

If local PHP/Composer are unavailable, use Docker via bin/dc <composer-args...>.

poor-plebs / hetzner-cloud-sdk

Maintainers

Package info

Statistics

Security