Documentation v1.0.0

Overview

The Laravel Hetzner Cloud SDK provides a production-ready client interface for managing cloud servers, volumes, networks, firewalls, and load balancers. Compatible with PHP 8.2 through 8.5, and Laravel 11 through 13.

Installation

Install the package through Composer:

composer require ghostcompiler/laravel-hetzner-cloud

Publish the configuration assets:

php artisan vendor:publish --provider="Vendor\HetznerCloud\Providers\HetznerCloudServiceProvider" --tag="config"

Configuration

The published configuration file lives at config/hetzner-cloud.php. You can generate your API Token from the Hetzner Cloud Console under project Security settings.

return [
    'token' => env('HETZNER_CLOUD_TOKEN'),
    'base_url' => env('HETZNER_CLOUD_BASE_URL', 'https://api.hetzner.cloud/v1'),
    'timeout' => (int) env('HETZNER_CLOUD_TIMEOUT', 30),
    'retries' => (int) env('HETZNER_CLOUD_RETRIES', 3),
    'retry_backoff' => (int) env('HETZNER_CLOUD_RETRY_BACKOFF', 100),
    'logging' => [
        'enabled' => (bool) env('HETZNER_CLOUD_LOGGING_ENABLED', false),
        'channel' => env('HETZNER_CLOUD_LOGGING_CHANNEL'),
    ],
];

Service Provider

The service provider binds the singleton client and orchestrator to Laravel's service container.

use Vendor\HetznerCloud\Managers\HetznerManager;

$manager = app(HetznerManager::class);
$servers = $manager->servers()->all();

Facades

Interact with the SDK fluently using the Facade accessor.

use Vendor\HetznerCloud\Facades\Hetzner;

$server = Hetzner::servers()->find(123);

Servers

Manage VM instances, trigger power status controls, attach networks, and boot rescue environments.

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

// Create server
$response = Hetzner::servers()->create([
    'name' => 'web-01',
    'server_type' => 'cx22',
    'image' => 'ubuntu-24.04',
    'location' => 'fsn1',
]);

Volumes

Attach SSD block storage disks to servers.

$volumes = Hetzner::volumes()->all();
Hetzner::volumes()->attach($volumeId, $serverId);

Networks

Private IP infrastructure networks for server communication.

$networks = Hetzner::networks()->all();

Firewalls

Configure stateless inbound and outbound security rules.

Hetzner::firewalls()->apply($firewallId, $serverId);

Floating IPs

Allocate highly available IP addresses routing to servers dynamically.

Hetzner::floatingIps()->assign($ipId, $serverId);

Primary IPs

Provision static primary interface IPs.

Hetzner::primaryIps()->all();

Load Balancers

Traffic distribution proxies for targets cluster pools.

Hetzner::loadBalancers()->addTarget($lbId, ['type' => 'server', 'server' => ['id' => $serverId]]);

SSH Keys

Authentication credentials for VM deployments.

Hetzner::sshKeys()->create(['name' => 'key', 'public_key' => 'ssh-rsa...']);

Images

OS base distributions and backups snapshots.

$images = Hetzner::images()->all();

Certificates

TLS keys configuration storage.

Hetzner::certificates()->all();

Placement Groups

Server scheduling spread layout policies.

Hetzner::placementGroups()->create(['name' => 'grp', 'type' => 'spread']);

Locations

Read geographical server centers.

$locs = Hetzner::locations()->all();

Datacenters

Information on physical facilities.

$dcs = Hetzner::datacenters()->all();

ISOs

Optical disk installations catalog.

$isos = Hetzner::isos()->all();

Pricing

List product pricing rates.

$pricing = Hetzner::pricing()->all();

Actions

Lifecycle action history.

$actions = Hetzner::actions()->all();

Server Types

Available VM hardware configurations.

$types = Hetzner::serverTypes()->all();

Load Balancer Types

Capacity limits configurations for load balancers.

$lbTypes = Hetzner::loadBalancerTypes()->all();

Async Requests

Configure queries asynchronously to yield Guzzle Promises.

$promise = Hetzner::servers()->async()->all();
$servers = $promise->wait();

Batch Operations

Run calls concurrently in pooled execution tasks.

$results = Hetzner::batch([
    fn () => Hetzner::servers()->find(1),
    fn () => Hetzner::servers()->find(2),
]);

Retries & Rate Limits

Request pipeline is governed by automatic Guzzle middleware.

Exception Handling

HTTP error codes automatically map to specific PHP exception classes.

try {
    Hetzner::servers()->find(999);
} catch (\Vendor\HetznerCloud\Exceptions\NotFoundException $e) {
    // 404 Error
}

Helper Cheatsheet

Quick copy reference table for common helper methods.

FAQ