Download the PHP package chuckbartowski/proxmox-sdk without Composer

Framework-agnostic core — usable from any PHP project, script, or worker — with an optional bundle for first-class Symfony integration. Authenticated with API tokens or ticket/cookie credentials, typed exceptions, async task helpers, and a comment-free, strictly typed codebase (PHP 8.2+, declare(strict_types=1) everywhere).

Table of Contents

• Features
• Requirements
• Installation
• Quick Start (plain PHP)
• Symfony Integration (optional)
• Architecture
• Authentication
• Asynchronous Tasks (UPID)
• API Reference
  • Nodes
  • QEMU virtual machines
  • LXC containers
  • Cluster
  • Storage
  • Backups
  • Network
  • Access control
• Responses
• Error Handling
• Testing
• Security Notes
• WHMCS module
• License

Features

• Wide API coverage: nodes, QEMU VMs, LXC containers, cluster, storage, backup jobs, vzdump, networking, users/tokens/ACLs.
• Both auth modes: API tokens (recommended, stateless) and ticket/cookie login with automatic re-login on expiry and CSRF handling for write requests.
• Task-aware: Proxmox returns a UPID for every asynchronous operation — the SDK detects them ($response->upid()) and can block until completion (waitForTask()), failing loudly when the task itself failed.
• QEMU and LXC share one polished interface: identical lifecycle methods (start, stop, clone, migrate, snapshots, resize…) implemented once, specialized where the APIs differ.
• Framework-agnostic: one plain facade (Proxmox) you can instantiate anywhere; the only hard dependency is symfony/http-client, a standalone component that works in any PHP project.
• A single normalized response object (ApiResponse) that unwraps Proxmox's data envelope and flattens field-level validation errors.
• Typed exception hierarchy under one marker interface, so you can catch narrowly or broadly.
• Nothing is sealed off: the client's get/post/put/delete accept any path, so an endpoint not wrapped by a module is one call away.
• Optional Symfony bundle with semantic configuration and autowirable services.
• Fully unit-tested against MockHttpClient (no network required).

Requirements

Installation

The package is published on Packagist:

Quick Start (plain PHP)

No framework required — build the client and go:

Client constructor signature:

Symfony Integration (optional)

Register the bundle:

Then create config/packages/proxmox_sdk.yaml:

Configuration reference

The Proxmox facade is then autowirable in controllers, services, commands, and message handlers. The bundle reuses your application's http_client service when available and falls back to a native client otherwise.

Architecture

Design decisions:

• Facade + lazy modules: Proxmox instantiates each module on first use and caches it.
• Modules always validate: every module method calls ensureSuccess() internally and throws ApiException on failure. To inspect a failed response without an exception, drop down to the client level.
• One guest abstraction: AbstractGuestApi implements the shared VM/container lifecycle; QemuApi adds what only VMs have (hard reset, guest agent, VNC proxy).
• Ticket state is self-healing: on a 401/403 with ticket auth, the client discards the ticket, re-logs once, and retries the request transparently.

Authentication

Two modes, checked in order:

1. API token (recommended) — stateless, no CSRF, survives restarts. Create one in Datacenter » Permissions » API Tokens (or via this SDK):

Configure with tokenId: 'automation@pve!sdk' + the secret shown once at creation. Grant the token its own permissions when privsep is enabled — a common pitfall: a privilege-separated token has no permissions until you add ACLs for it.

2. Ticket (username/password) — the SDK logs in against /access/ticket, stores the ticket and CSRF token in memory, sends PVEAuthCookie on every call and CSRFPreventionToken on writes, and re-logs automatically when the ticket expires (~2 hours).

Missing credentials throw an AuthenticationException immediately, before any network request.

Asynchronous Tasks (UPID)

Most mutating operations (start, clone, migrate, vzdump, destroy…) return immediately with a task identifier (UPID:node:…) while the work continues server-side:

waitForTask() polls the task status until it stops, returns the final status on success (OK or warnings), and throws an ApiException carrying the real exitstatus when the task failed — so a failed clone never masquerades as a success. taskLog() fetches the task output for diagnostics.

API Reference

Every method returns an Error Handling).

Nodes

$proxmox->nodes()

QEMU virtual machines

$proxmox->qemu() — full VM lifecycle on /nodes/{node}/qemu.

LXC containers

$proxmox->lxc() — the same lifecycle interface as QEMU (minus VM-only operations) on /nodes/{node}/lxc.

Cluster

$proxmox->cluster() — version(), status(), resources(?type) (filter: vm, storage, node, sdn), tasks(), nextId(), options() / setOptions(), haResources(), and resource pools: pools(), pool(poolId), createPool(poolId, ?comment), updatePool(poolId, fields) (add/remove vms/storage members, delete => 1 to remove), deletePool(poolId).

nextId() + create() is the standard provisioning pattern shown in the Quick Start.

Storage

$proxmox->storage() — cluster-wide definitions (list, create, update, remove) and per-node views: nodeStorages(node), status(node, storage), content(node, storage, ?contentType), deleteVolume(...), and downloadUrl(node, storage, url, filename) to pull ISOs/templates straight from a URL (returns a UPID).

Backups

$proxmox->backups() — scheduled job management on /cluster/backup (jobs, createJob, updateJob, deleteJob) and on-demand dumps: run(node, options) (POST /nodes/{node}/vzdump) and defaults(node).

Network

$proxmox->network() — node network interfaces: list, find, create(node, iface, type, options) (types: bridge, bond, vlan, …), update, remove, plus apply(node) to activate pending changes and revert(node) to discard them. Proxmox stages network changes — nothing is live until apply().

Access control

$proxmox->access() — users (users, createUser, updateUser, deleteUser), API tokens (tokens, createToken, deleteToken), groups, roles(), and ACLs: acl(), updateAcl(path, roles, options) (add ['delete' => 1] to revoke), permissions(?path, ?userid).

Responses

All calls return an immutable ApiResponse; the Proxmox data envelope is already unwrapped:

Error Handling

All SDK exceptions implement ProxmoxSdkExceptionInterface, so a single catch covers everything:

To inspect a failed response without exceptions, use the client directly — client-level methods return the response as-is:

Testing

The suite runs entirely offline against MockHttpClient:

To test your own services, inject a ProxmoxClient built with a mock:

Security Notes

• Secrets (tokenSecret, password) are passed with #[\SensitiveParameter], so they never appear in stack traces.
• Prefer API tokens with privilege separation (privsep => 1) and grant them only the ACLs they need (PVEVMAdmin on /vms, not Administrator on /).
• A fresh Proxmox VE ships with a self-signed certificate. Rather than disabling verify_ssl, install a proper certificate (ACME is built into Proxmox) — keep verify_ssl: false strictly for lab environments.
• Keep credentials in .env.local or your secret vault — never commit them.
• remove() on guests (especially with purge: true), deleteVolume() and rollbackSnapshot() are irreversible — gate destructive calls behind confirmation flows in your application.

WHMCS module

A ready-to-use WHMCS provisioning module ships in whmcs/modules/servers/proxmoxsdk/. It provisions VPS by cloning a template through this SDK — clone + wait + start on create, suspend/resume, terminate (stop + purge), and reboot.

Install

1. composer require chuckbartowski/proxmox-sdk in your WHMCS root.
2. Copy the proxmoxsdk folder into <whmcs>/modules/servers/.
3. Add a server with Type: Proxmox VE (SDK), the PVE hostname, the token id (user@realm!name) as username, and the token secret in the Access Hash field.
4. Set the config options: Node, Template VMID, and VMID base (the new VMID is base + service id, so it is deterministic and collision-free).

License

MIT