README

⚡️ 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.

boci/hetzner-laravel

包简介

关键字：

README 文档