[TUTORIAL] Proxmox PHP SDK: A thin PHP wrapper with full API coverage

[jefersonflus]

Hello everyone,

I’d like to share an open-source project that may be useful for those integrating Proxmox VE with PHP-based systems.

Proxmox PHP SDK is a lightweight and pragmatic PHP library that acts as a thin wrapper around the official Proxmox VE REST API. The goal is not to abstract or simplify Proxmox concepts, but to provide a clean, predictable way to interact with the API from PHP.

Project repository:
https://github.com/jefersonflus/Proxmox-PHP-SDK

---

Design goals​

• One-to-one mapping between API endpoints and PHP methods
• No opinionated workflows or hidden logic
• Clear separation by API domain (Nodes, Cluster, Storage, Access, etc.)
• Centralized HTTP handling and authentication

Authentication supports both username/password and API Tokens.

---

API coverage and validation​

A key focus of this project is staying fully aligned with the official API.

The SDK automatically validates its implementation against the official apidoc.js provided by Proxmox.

Current status:

• 646 official endpoints
• 646 implemented
• 0 missing endpoints
• 0 mismatches

This validation runs in CI, so API changes are detected early rather than at runtime.

---

Testing and maintenance​

• PHP contract tests covering API behavior
• 131 tests executed, all passing
• CI pipeline with linting, tests, and API validation
• Semantic Versioning (current release: v1.0.0)

---

Intended use cases​

• Custom dashboards or control panels
• PHP-based automation and backend services
• Integration with billing systems or internal tooling

The SDK is not intended to replace configuration management or orchestration tools like Terraform or Ansible. It focuses strictly on being a reliable PHP interface to the Proxmox API.

---

Feedback welcome​

This is a community-driven project, and feedback from Proxmox users is very welcome — whether it’s about API coverage, design decisions, or edge cases.

If useful, I can also share more details about how the API validation and contract tests are implemented.

Thank you for your time.