Hetzner Laravel

⚡️ Hetzner Laravel is a supercharged community-maintained Laravel SDK that allows you to interact with the Hetzner Cloud API. Inspired by Nuno Maduro's excellent OpenAI PHP client.

Features

🚀 Modern Architecture: Clean, organized, and maintainable code structure
🧪 Testing Ready: Includes ClientFake for easy testing and mocking
📊 Meta Information: Access rate limits and request details
🛡️ Type Safe: Full type safety with PHP 8.2+
🎯 Resource Based: Clean, organized API resources
🔧 Laravel Integration: Seamless Laravel service provider and facade
🌐 Complete API Coverage: All Hetzner Cloud API endpoints implemented

Installation

You can install the package via composer:

composer require boci/hetzner-laravel

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Boci\HetznerLaravel\HetznerLaravelServiceProvider" --tag="config"

Add your Hetzner API token to your .env file:

HETZNER_TOKEN=your-hetzner-api-token-here

Usage

Basic Usage

use Boci\HetznerLaravel\Client;

$client = Client::factory()
    ->withApiKey('your-api-token')
    ->make();

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

$server = $response->server();
$action = $response->action();
$rootPassword = $response->rootPassword();

echo "Server ID: " . $server->id();
echo "Server Name: " . $server->name();
echo "Status: " . $server->status();
echo "Root Password: " . $rootPassword;

Using the Facade

use Boci\HetznerLaravel\Facades\HetznerLaravel;

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

foreach ($servers->servers() as $server) {
    echo "Server: " . $server->name() . " - " . $server->status() . "\n";
}

// Get server details
$server = HetznerLaravel::servers()->retrieve('12345');
echo "Server IP: " . $server->server()->publicNet()['ipv4']['ip'];

// Delete a server
$action = HetznerLaravel::servers()->delete('12345');
echo "Delete action status: " . $action->action()->status();

Working with Images

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List available images
$images = HetznerLaravel::images()->list();

foreach ($images->images() as $image) {
    echo "Image: " . $image->name() . " - " . $image->osFlavor() . "\n";
}

// Get specific image details
$image = HetznerLaravel::images()->retrieve('12345');
echo "Image size: " . $image->image()->imageSize() . " GB";

Working with Locations

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List available locations
$locations = HetznerLaravel::locations()->list();

foreach ($locations->locations() as $location) {
    echo "Location: " . $location->name() . " - " . $location->city() . ", " . $location->country() . "\n";
}

Working with Server Types

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List available server types
$serverTypes = HetznerLaravel::serverTypes()->list();

foreach ($serverTypes->serverTypes() as $serverType) {
    echo "Server Type: " . $serverType->name() . " - " . $serverType->cores() . " cores, " . $serverType->memory() . " GB RAM\n";
}

Working with Networks

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List all networks
$networks = HetznerLaravel::networks()->list();

foreach ($networks->networks() as $network) {
    echo "Network: " . $network->name() . " - " . $network->ipRange() . "\n";
}

// Create a new network
$response = HetznerLaravel::networks()->create([
    'name' => 'my-network',
    'ip_range' => '10.0.0.0/16',
]);

$network = $response->network();
echo "Created network: " . $network->name();

Working with Load Balancers

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List all load balancers
$loadBalancers = HetznerLaravel::loadBalancers()->list();

foreach ($loadBalancers->loadBalancers() as $lb) {
    echo "Load Balancer: " . $lb->name() . " - " . $lb->loadBalancerType()->name() . "\n";
}

// Create a load balancer
$response = HetznerLaravel::loadBalancers()->create([
    'name' => 'my-lb',
    'load_balancer_type' => 'lb11',
    'location' => 'nbg1',
]);

$loadBalancer = $response->loadBalancer();
echo "Created load balancer: " . $loadBalancer->name();

Working with DNS

use Boci\HetznerLaravel\Facades\HetznerLaravel;

// List DNS zones
$zones = HetznerLaravel::dnsZones()->list();

foreach ($zones->zones() as $zone) {
    echo "Zone: " . $zone->name() . " - " . $zone->status() . "\n";
}

// Create a DNS zone
$response = HetznerLaravel::dnsZones()->create([
    'name' => 'example.com',
    'mode' => 'primary',
    'ttl' => 3600,
]);

$zone = $response->zone();
echo "Created zone: " . $zone->name();

// List DNS records for a zone
$rrsets = HetznerLaravel::dnsZones()->rrsets()->list('example.com');

foreach ($rrsets->rrsets() as $rrset) {
    echo "Record: " . $rrset->name() . " " . $rrset->type() . " " . $rrset->ttl() . "\n";
}

// Create a DNS record
$response = HetznerLaravel::dnsZones()->rrsets()->create('example.com', [
    'name' => 'www',
    'type' => 'A',
    'ttl' => 3600,
    'records' => [
        [
            'value' => '192.168.1.1',
            'comment' => 'Web server',
        ],
    ],
]);

$rrset = $response->rrset();
echo "Created record: " . $rrset->name() . " " . $rrset->type();

// Export zone file
$exportResponse = HetznerLaravel::dnsZones()->export('example.com');
echo "Zone file: " . $exportResponse->zoneFile();

// Change zone nameservers
$actionResponse = HetznerLaravel::dnsZones()->actions()->changeNameservers('example.com', [
    'nameservers' => ['ns1.example.com', 'ns2.example.com'],
]);
echo "Action status: " . $actionResponse->action()->status();

Meta Information

Access rate limits and request details:

$response = $client->servers()->list();
$meta = $response->meta();

echo "Request ID: " . $meta->requestId;
echo "Rate Limit: " . $meta->rateLimitLimit;
echo "Remaining: " . $meta->rateLimitRemaining;
echo "Reset Time: " . $meta->rateLimitReset;

Testing

The package provides a fake implementation for testing:

use Boci\HetznerLaravel\Testing\ClientFake;
use Boci\HetznerLaravel\Responses\Servers\CreateResponse;

$client = new ClientFake([
    CreateResponse::fake([
        'name' => 'test-server',
        'server_type' => 'cpx11',
    ]),
]);

$response = $client->servers()->create([
    'name' => 'test-server',
    'server_type' => 'cpx11',
    'image' => 'ubuntu-24.04',
    'location' => 'nbg1',
]);

expect($response->server()->name())->toBe('test-server');

// Assert that requests were sent
$client->assertSent(\Boci\HetznerLaravel\Resources\Servers::class, function (string $method, array $parameters): bool {
    return $method === 'create' && $parameters['name'] === 'test-server';
});

Testing with Exceptions

use Boci\HetznerLaravel\Testing\ClientFake;
use Boci\HetznerLaravel\Exceptions\ErrorException;

$client = new ClientFake([
    new ErrorException([
        'message' => 'Server not found',
        'code' => 'server_not_found',
    ], 404)
]);

// This will throw the ErrorException
$client->servers()->retrieve('non-existent');

Advanced Usage

Custom HTTP Client

use Boci\HetznerLaravel\Client;
use GuzzleHttp\Client as GuzzleClient;

$client = Client::factory()
    ->withApiKey('your-api-token')
    ->withHttpClient(new GuzzleClient([
        'timeout' => 60,
        'verify' => false, // Only for development
    ]))
    ->make();

Dependency Injection

use Boci\HetznerLaravel\Client;

class ServerController
{
    public function __construct(
        private Client $hetznerClient
    ) {}

    public function createServer()
    {
        $response = $this->hetznerClient->servers()->create([
            'name' => 'my-server',
            'server_type' => 'cpx11',
            'image' => 'ubuntu-24.04',
            'location' => 'nbg1',
        ]);

        return response()->json($response->toArray());
    }
}

API Resources

The package is organized into resources that correspond to Hetzner Cloud API endpoints:

Actions: Get multiple actions, get an action
Billing: Get all prices
Certificates: List, create, get, update, delete certificates
DNS Zones: List, create, get, update, delete DNS zones + actions + RRSets
Firewalls: List, create, get, update, delete firewalls + actions
Floating IPs: List, create, get, update, delete floating IPs + actions
Images: List, get, update, delete images + actions
ISOs: List, get ISOs
Load Balancers: List, create, get, update, delete load balancers + actions
Load Balancer Types: List, get load balancer types
Locations: List, get locations
Networks: List, create, get, update, delete networks + actions
Placement Groups: List, create, get, update, delete placement groups
Primary IPs: List, create, get, update, delete primary IPs + actions
Servers: List, create, get, update, delete servers + actions
Server Types: List, get server types
SSH Keys: List, create, get, update, delete SSH keys
Volumes: List, create, get, update, delete volumes + actions

Error Handling

The package provides custom exceptions for better error handling:

use Boci\HetznerLaravel\Exceptions\ErrorException;
use Boci\HetznerLaravel\Exceptions\TransporterException;

try {
    $response = $client->servers()->create($parameters);
} catch (ErrorException $e) {
    // Handle API errors
    echo "API Error: " . $e->getMessage();
    echo "Error Code: " . $e->getCode();
} catch (TransporterException $e) {
    // Handle network/transport errors
    echo "Network Error: " . $e->getMessage();
}

Documentation

For more information about the Hetzner Cloud API, please refer to the following resources:

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email amar8eka@gmail.com instead of using the issue tracker.

Credits

License

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

Quick Reference

🚀 Actions

list() - Get multiple actions
retrieve(string $actionId) - Get an action

🔐 Security

Certificates

list() - List certificates
create(array $parameters) - Create a certificate
retrieve(string $certificateId) - Get a certificate
update(string $certificateId, array $parameters) - Update a certificate
delete(string $certificateId) - Delete a certificate

SSH Keys

list() - List SSH keys
create(array $parameters) - Create an SSH key
retrieve(string $sshKeyId) - Get an SSH key
update(string $sshKeyId, array $parameters) - Update an SSH key
delete(string $sshKeyId) - Delete an SSH key

🌐 DNS Zones

list() - List DNS zones
create(array $parameters) - Create a DNS zone
retrieve(string $zoneIdOrName) - Get a DNS zone
update(string $zoneIdOrName, array $parameters) - Update a DNS zone
delete(string $zoneIdOrName) - Delete a DNS zone
export(string $zoneIdOrName) - Export zone file
import(array $parameters) - Import zone file
actions() - Access zone actions
rrsets() - Access DNS records

📍 Locations

list() - List locations
retrieve(string $locationId) - Get a location

🔥 Firewalls

list() - List firewalls
create(array $parameters) - Create a firewall
retrieve(string $firewallId) - Get a firewall
update(string $firewallId, array $parameters) - Update a firewall
delete(string $firewallId) - Delete a firewall
actions() - Access firewall actions

🌐 Floating IPs

list() - List floating IPs
create(array $parameters) - Create a floating IP
retrieve(string $floatingIpId) - Get a floating IP
update(string $floatingIpId, array $parameters) - Update a floating IP
delete(string $floatingIpId) - Delete a floating IP
actions() - Access floating IP actions

🖥️ Servers

list() - List servers
create(array $parameters) - Create a server
retrieve(string $serverId) - Get a server
update(string $serverId, array $parameters) - Update a server
delete(string $serverId) - Delete a server
metrics(string $serverId, array $parameters) - Get server metrics
actions() - Access server actions

🖼️ Images

list() - List images
retrieve(string $imageId) - Get an image
update(string $imageId, array $parameters) - Update an image
delete(string $imageId) - Delete an image
actions() - Access image actions

💿 ISOs

list() - List ISOs
retrieve(string $isoId) - Get an ISO

📦 Placement Groups

list() - List placement groups
create(array $parameters) - Create a placement group
retrieve(string $placementGroupId) - Get a placement group
update(string $placementGroupId, array $parameters) - Update a placement group
delete(string $placementGroupId) - Delete a placement group

🔗 Primary IPs

list() - List primary IPs
create(array $parameters) - Create a primary IP
retrieve(string $primaryIpId) - Get a primary IP
update(string $primaryIpId, array $parameters) - Update a primary IP
delete(string $primaryIpId) - Delete a primary IP
actions() - Access primary IP actions

⚙️ Server Types

list() - List server types
retrieve(string $serverTypeId) - Get a server type

⚖️ Load Balancers

list() - List load balancers
create(array $parameters) - Create a load balancer
retrieve(string $loadBalancerId) - Get a load balancer
update(string $loadBalancerId, array $parameters) - Update a load balancer
delete(string $loadBalancerId) - Delete a load balancer
metrics(string $loadBalancerId, array $parameters) - Get load balancer metrics
actions() - Access load balancer actions

⚖️ Load Balancer Types

list() - List load balancer types
retrieve(string $loadBalancerTypeId) - Get a load balancer type

🌐 Networks

list() - List networks
create(array $parameters) - Create a network
retrieve(string $networkId) - Get a network
update(string $networkId, array $parameters) - Update a network
delete(string $networkId) - Delete a network
actions() - Access network actions

💰 Billing

listPricing() - Get all prices

💾 Volumes

list() - List volumes
create(array $parameters) - Create a volume
retrieve(string $volumeId) - Get a volume
update(string $volumeId, array $parameters) - Update a volume
delete(string $volumeId) - Delete a volume
actions() - Access volume actions

This package provides complete coverage of the Hetzner Cloud API, ensuring you can manage all your cloud resources programmatically with ease.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
config		config
src		src
tests		tests
.gitignore		.gitignore
.styleci.yml		.styleci.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
composer.json		composer.json
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml		phpunit.xml

License

amar8eka/hetzner-laravel

Folders and files

Latest commit

History

Repository files navigation

Hetzner Laravel

Features

Installation

Configuration

Usage

Basic Usage

Using the Facade

Working with Images

Working with Locations

Working with Server Types

Working with Networks

Working with Load Balancers

Working with DNS

Meta Information

Testing

Testing with Exceptions

Advanced Usage

Custom HTTP Client

Dependency Injection

API Resources

Error Handling

Documentation

Contributing

Security

Credits

License

Quick Reference

🚀 Actions

🔐 Security

Certificates

SSH Keys

🌐 DNS Zones

📍 Locations

🔥 Firewalls

🌐 Floating IPs

🖥️ Servers

🖼️ Images

💿 ISOs

📦 Placement Groups

🔗 Primary IPs

⚙️ Server Types

⚖️ Load Balancers

⚖️ Load Balancer Types

🌐 Networks

💰 Billing

💾 Volumes

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages