Hetzner Laravel Laravel Package

Technical Evaluation

Architecture fit boci/hetzner-laravel is a Laravel-native SDK: package auto-discovery, a published config file, credential wiring via env, and type-safe DTOs over Hetzner's REST APIs. It fits an architecture where the Laravel application is the control plane — provisioning app servers, managing DNS records during tenant onboarding, or scripting network/LB setup from an admin panel or queue worker. The value proposition is real but narrow: it replaces hand-rolled Http::withToken(...)->post('api.hetzner.cloud/v1/servers', ...) calls with typed request/response objects and centralized config.

Critically, this is a transport client, not an orchestrator. It carries no state, performs no drift detection, and provides no reconciliation semantics. A TPM should scope it as an adapter layer beneath a domain service you own (e.g. CloudProvisioner), never as the thing that decides what infrastructure should exist.

Integration feasibility Initial integration cost is low — composer require, one env var, one config publish. The real effort sits in three places:

• Token model. Hetzner Cloud API tokens are project-scoped and read/write; there is no fine-grained IAM. A leaked token is full control of that project. Treat token handling and rotation as a first-class design task, not a config detail.
• API surface boundaries. Hetzner Cloud (servers, networks, LBs) and Hetzner DNS are separate products with separate APIs and versioning. The description claims DNS coverage; confirm on the current tag that it targets the DNS API, not just Cloud.
• Testability. Verify the package routes through Laravel's HTTP client so Http::fake() works. If it constructs its own client, your test strategy and your ability to exercise failure paths degrade significantly.

Technical risk The adoption signal is weak and should be stated plainly to stakeholders: 91 stars, 0 dependents, single maintainer, and an aggregate score of ~20/100. Zero dependents means zero public evidence of production use — you would be an early adopter, not a follower. The reported last release of 2026-10-25 is a future date, which is either a metadata artifact or a signal that release/tag hygiene is unreliable; verify tags and changelog against the actual repository before pinning anything.

Bus factor is 1. Assume you may need to fork and maintain. Hetzner-specific lock-in is low (the API is Hetzner's regardless of client), but DTO/namespace coupling is real — mitigate with an internal interface.

Key questions for the maintainer / spike

1. Which Hetzner API versions are targeted, and how are breaking changes tracked?
2. Is HTTP transport built on Laravel's client (and therefore Http::fake()-able, middleware-aware, timeout-configurable)?
3. Are retries, backoff, and 429 handling implemented, or left to the caller?
4. Is pagination handled transparently for list endpoints?
5. Are async Actions (server create/rebuild) modeled, or only fire-and-forget?
6. What is the test coverage, and is there a CI matrix against supported Laravel/PHP versions?
7. Are DNS zone/rrset operations included, and against which DNS API version?
8. What is the maintainer's stated support window and deprecation policy?

Integration Approach

Stack fit Requires a modern PHP/Laravel baseline (verify the exact support matrix — likely PHP 8.2+, Laravel 10–12). Because it is a plain synchronous client, it composes cleanly with queue workers and jobs, which is how provisioning should run: HTTP request in, ProvisionServerJob dispatched, status polled with backoff.

Migration path There are three realistic entry points, in ascending order of effort:

1. From raw HTTP calls — the common case. Mechanical swap; highest immediate payoff from type safety and centralized config.
2. From console/Terraform-managed infra — do not migrate wholesale. Keep Terraform (or equivalent) as the source of truth for baseline infrastructure and use this package only for per-tenant or dynamic ephemeral resources. Mixing the two without a clear ownership boundary is the fastest route to drift.
3. From another Hetzner SDK — cheapest technically, but validate feature parity on the endpoints you actually use before switching.

Compatibility and abstraction Define an internal CloudProvider interface (createServer, deleteServer, upsertDnsRecord, listServers) and implement it with this package. That single step converts a bus-factor-1 dependency into a replaceable detail and bounds the blast radius of abandonment or a breaking upstream release. Pin exact versions, commit composer.lock, and mirror to a private fork if the package lands on a critical path.

Sequencing

1. Spike (2–3 days) — throwaway Hetzner project, exercise the endpoints on your roadmap, run the key questions above, confirm Http::fake() works.
2. Adapter + test harness — wrap behind your interface, establish a fake-based test suite covering 429/5xx/timeout paths.
3. Non-production pilot — pick the lowest-blast-radius real workload: a single DNS record or a scratch server in a dev project.
4. Production, feature-flagged — expand to servers/networks/LBs behind a config toggle with a manual fallback path documented.
5. Reconciliation job — scheduled job that diffs intended vs. actual state and alerts. Ship this before broad production rollout, not after.

Operational Impact

Maintenance Budget explicit ownership: roughly one day per quarter to review upstream releases and CVEs, plus contingency for a fork if the maintainer goes dormant. Assign a named code owner. Treat any upgrade as a change requiring the fake-based test suite to pass.

Support No commercial support and no SLA — issues are community-only. Your on-call absorbs all consequences. Escalation path is Hetzner's own support for API-side problems and the upstream repo (best-effort) for client-side bugs. Document that internal reality so nobody assumes vendor backing.

Scaling Hetzner Cloud imposes per-project rate limits (on the order of a few thousand requests/hour, with tighter per-endpoint limits). Two consequences matter at scale:

• Polling is the enemy. Naive "poll until running" loops burn quota fast when provisioning N servers concurrently. Use action-based polling with exponential backoff, and a global concurrency cap on provisioning jobs.
• Fan-out risk. Bulk operations (create 50 servers, upsert 500 DNS records) need a rate-limited queue, not a foreach. Design this into the adapter, not per-caller.

If the package does not implement retry/backoff itself, wrap it — do not rely on ad-hoc handling scattered across call sites.

Failure modes The dangerous cases are the partial ones, and a stateless SDK cannot protect you from them:

• Orphaned billable resources — request times out after Hetzner accepted it; you never get the ID; the server bills forever. Mitigation: deterministic naming convention + reconciliation sweep that deletes unlabeled/unexpected resources.
• Non-idempotent retries — a retried create yields duplicates. Mitigation: never blind-retry mutations; use name-as-idempotency-key and pre-flight lookups.
• DNS drift and duplicate rrsets — Hetzner DNS rejects duplicate records but partial multi-record updates leave zones inconsistent. Mitigation: declarative full-set upserts, not per-record appends.
• 429 / 5xx cascades — surfaces as flaky provisioning under load. Mitigation: backoff, circuit breaker, dead-letter queue.
• Token leakage — full project compromise, no scoping to limit it. Mitigation: never log the token, sanitize exception payloads (clients often embed request context), rotate on a schedule, use separate tokens per environment.

Ramp-up Low for engineers: any Laravel developer is productive in under a day, since the idioms (facade, config, DTOs) are familiar. The learning curve is Hetzner's API semantics, not the package — Actions, async state transitions, per-project rate limits, and the Cloud-vs-DNS split. Budget that as the real onboarding cost and put it in a short internal runbook rather than leaving it tribal.

TPM recommendation Adopt conditionally. It is a reasonable convenience layer with genuine type-safety benefits, but a 0-dependent, single-maintainer, low-score dependency does not belong on an unmediated critical path. Gate adoption on the spike answering the questions above — particularly HTTP-client testability, retry behavior, and DNS API coverage — and require the internal CloudProvider abstraction and reconciliation job as non-negotiable prerequisites to production use.