The Proxmox VE API from PHP

By developers, for developers.

Built by Corsinvest, official Proxmox partner.

# the latest version is on Packagist
composer require corsinvest/cv4pve-api-php

Why

An application that manages Proxmox VE (a customer portal, a scheduled job, a monitoring or billing tool) has to speak its REST API: tickets and tokens, paths, parameters, JSON, tasks that end later. Written by hand it is a layer of HTTP code to build and to keep up with every Proxmox VE release.

cv4pve-api-php is that layer, generated from the API itself. The calls follow the tree of the API, so the Proxmox VE API viewer is also the reference of the client, and the comment of each method carries the same descriptions.

use Corsinvest\ProxmoxVE\Api\PveClient;

$client = new PveClient('pve01', 8006);
$client->setApiToken('automation@pve!app=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');

// GET /nodes/{node}/qemu/{vmid}/status/current
$result = $client->getNodes()->get('pve01')->getQemu()->get(100)->getStatus()->getCurrent()->vmStatus();

echo $result->isSuccessStatusCode()
    ? "VM {$result->getResponse()->data->vmid} is {$result->getResponse()->data->status}"
    : "{$result->getStatusCode()} {$result->getReasonPhrase()}";

From endpoint to methodPaths become getters and get(...), the methods of an endpoint become PHP methods, parameters become arguments.

In your application, API only

The client runs where PHP runs (a web application, a command line script, a scheduled job, a container) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes and no SSH is needed. What an application can do is what its API token or user is allowed to do: give it a token with just the privileges it needs, see Permissions.

Where it fits

The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. This library is the PHP way into the same API the tools of the suite use. If a ready tool already does the job, use the tool: cv4pve-cli calls the API from any shell, cv4pve-autosnap takes snapshots with retention. The same client exists for .NET with cv4pve-api-dotnet, for Java with cv4pve-api-java and for PowerShell with cv4pve-api-powershell.

What it does for you

The whole API

A method for every endpoint and HTTP method, generated from the Proxmox VE API schema, placed where the API has it: the path of an endpoint is the path in the code.

One Result for every call

The HTTP outcome and the Proxmox VE data together, read as objects or as arrays. A failed call does not throw.

API token or password

Connect with an API token or a user and password, with two-factor authentication, certificate validation and timeout.

Tasks

Start a backup, a clone or a migration, wait for its task to finish and read whether it succeeded.

Raw calls

GET, POST, PUT and DELETE on any path with an array of parameters: for the calls with many options and for endpoints newer than the library.

No dependency

PHP with the curl extension. No other package, no framework, no HTTP library to configure.

Part of the cv4pve suite →

Write your first call

Add the package with Composer, connect to any node, read your VMs.

Made by Corsinvest,
official Proxmox partner

Get startedProfessional support