Core concepts

You must now that any ProxmoxVE server has a web service that can be used to manage all Proxmox resources, it uses a REST like API. The base URI to the API is like: https://your.server:8006/api2/json/, of course if you have Proxmox listening on another port you would replace it in the URI. Read more at the Proxmox wiki.

ProxmoxVE API Client library

This PHP5 library will handle all HTTP requests that the Proxmox web service needs in order to create, fetch, modify and delete all kind of Proxmox resources.

Installation

Recomended installation is using Composer, if you do not have Composer what are you waiting?

In the root of your project execute the following:

$ composer require zzantares/proxmoxve ~3.0

Or add this to your composer.json file:

{
    "require": {
        "zzantares/proxmoxve": "~3.0"
    }
}

Then perform the installation:

$ composer install --no-dev

Basic usage

<?php

// Require the autoloader
require_once 'vendor/autoload.php';

// Use the library namespace
use ProxmoxVE\Proxmox;

// Create your credentials array
$credentials = [
    'hostname' => 'proxmox.server.com',  // Also can be an IP
    'username' => 'root',
    'password' => 'secret',
];

// realm and port defaults to 'pam' and '8006' but you can specify them like so
$credentials = [
    'hostname' => 'proxmox.server.com',
    'username' => 'root',
    'password' => 'secret',
    'realm' => 'pve',
    'port' => '9009',
];

// Then simply pass your credentials array when creating the API client object.
$proxmox = new Proxmox($credentials);

$allNodes = $proxmox->get('/nodes');

print_r($allNodes);

Sample output:

Array
(
    [data] => Array
        (
            [0] => Array
                (
                    [disk] => 2539465464
                    [cpu] => 0.031314446882002
                    [maxdisk] => 30805066770
                    [maxmem] => 175168446464
                    [node] => mynode1
                    [maxcpu] => 24
                    [level] => 
                    [uptime] => 139376
                    [id] => node/mynode1
                    [type] => node
                    [mem] => 20601992182
                )

        )

)

Available functions

On your proxmox client object you can use get(), create(), set() and delete() functions for all resources specified at PVE2 API Documentation, params are passed as the second parameter in an associative array.

Also any ProxmoxVE object has this functions that might be useful to you:

Set and get credentials

Some times your program will need to query multiple proxmox servers. You can use setCredentials() function to change the server that the library is talking to.

<?php
require_once 'vendor/autoload.php';

$serverA = ['hostname' => 'hostA', 'username' => 'userA', 'password' => 'passwdA'];
$proxmox = new ProxmoxVE\Proxmox($serverA);  // API object created only once

// Get nodes on server A
$proxmox->get('/nodes');

$serverB = ['hostname' => 'hostB', 'username' => 'userB', 'password' => 'passwdB'];
$proxmox->setCredentials($serverB);

// After that every communication is sent to the new server

$proxmox->get('/nodes');  // Get nodes on server B

// Also you can call getCredentials for whatever reason
$credentialsB = $proxmox->getCredentials();

echo 'Hostname: ' . $credentialsB->getHostname();  // Hostname: hostB

Using custom credentials object

Also is possible to create a ProxmoxVE instance passing a custom object that has all related data needed to connect to the Proxmox server:

<?php
// Once again require the autoloader
require_once 'vendor/autoload.php';

// Sample custom credentials class
class CustomCredentials
{
    public function __construct($host, $user, $pass)
    {
        $this->hostname = $host;
        $this->username = $user;
        $this->password = $pass;
    }
}

// Create ProxmoxVE instance by passing your custom credentials object
$credentials = new CustomCredentials('proxmox.server.com', 'root', 'secret');
$proxmox = new ProxmoxVE\Proxmox($credentials);

// Then you can use it, for example create a new user.

// Define params
$params = [
    'userid' => 'new_user@pve',  // Proxmox requires to specify the realm (see the docs)
    'comment' => 'Creating a new user',
    'password' => 'canyoukeepasecret?',
];

// Send request passing params
$result = $proxmox->create('/access/users', $params);

// If an error occurred the 'errors' key will exist in the response array
if (isset($result['errors'])) {
    error_log('Unable to create new proxmox user.');
    foreach ($result['errors'] as $title => $description) {
        error_log($title . ': ' . $description);
    }
} else {
    echo 'Successful user creation!';
}

Using a custom credentials object is useful when your application uses some ORM models with the connecting data inside them, so you can pass for example an Eloquent model that holds the credentials inside. The only thing your custom credentials object needs, is to have the required accesible properties:

hostname
username
password
realm (optional defaults to pam)
port (optional defaults to 8006)

If you feel using getters is better, the Proxmox API client object will search for the next getters if properties are not accesible:

getHostname()
getUsername()
getPassword()
getRealm() (optional defaults to pam)
getPort() (optional defaults to 8006)

If your custom object uses __get magic method to access properties you're covered too!.

<?php
require_once 'vendor/autoload.php';

// Example of custom credentials class
class CustomCredentials
{
    private $hostname;
    private $username;
    private $password;
    
    public function __construct($host, $user, $pass)
    {
        $this->hostname = $host;
        $this->username = $user;
        $this->password = $pass;
    }
    
    public function __get($property)
    {
        if (property_exists($this, $property)) return $this->$property;
    }
}

// Create an object of your custom credentials object
$customCredentials = new CustomCredentials('my.proxmox.tld', 'user', 'secret');

// Pass your custom credentials when creating the API client
$proxmox = new ProxmoxVE\Proxmox($customCredentials);

// At this point you can use the $proxmox normally

Why is this useful? Personally when dealing with Eloquent models I already have a Credentials object, so I want to use that object to login to a proxmox server.

Set and get response type

You must know that the proxmox webservice API can give you responses in json, extjs, html, text and secretely png for server graphics. You can specify the response format using setResponseType() function.

<?php
require_once 'vendor/autoload.php';

$serverCredentials = new ProxmoxVE\Credentials('host', 'user', 'passwd');

// You can specify format as 2nd argument when creating API client object.
$proxmox = new ProxmoxVE\Proxmox($serverCredentials, 'html');

// Ask for nodes, gives back a PHP string with HTML response
$proxmox->get('/nodes');

// Change response type to JSON
$proxmox->setResponseType('json');

// Now asking for nodes gives back JSON raw string
$proxmox->get('/nodes');

// If you want again return PHP arrays you can use the 'array' format.
$proxmox->setResponseType('array');

// Also you can call getResponseType for whatever reason you have
$responseType = $proxmox->getResponseType();  // array

This library can respond in 2 extra formats, array and pngb64. If no response format is specified when creating the API client object, array will be used by default, which will give you back a PHP array as response.

<?php
require_once 'vendor/autoload.php';

$serverCredentials = [
    'hostname' => 'server',
    'username' => 'some_user',
    'password' => 'secret.passwd',
];

// You can specify format as 2nd argument when creating API client object.
$proxmox = new ProxmoxVE\Proxmox($serverCredentials, 'png');

// Because querying '/nodes' does not return PNG this will give you errrors.
$proxmox->get('/nodes');

// Asking for a PNG resource will give you back binary data.
$binaryPNG = $proxmox->get('/nodes/mynode/rrd', ['ds' => 'cpu', 'timeframe' => 'day']);

// You can do this with the returned data
if ($resource = imagecreatefromstring($response)) {
    // We can save the image, or render to the browser, whatever you like
    imagepng($resource, 'sample.png');
    imagedestroy($resource);
}

// It is common to fetch images and then use base64 to display the image easily in a webpage
$proxmox->setResponseType('pngb64');  // Sample format: data:image/png;base64,iVBORw0KGgoAAAA...
$base64 = $proxmox->get('/nodes/mynode/rrd', ['ds' => 'cpu', 'timeframe' => 'day']);

// So we can do something like this
echo "<img src='{$base64}' \>";

// 'array' it is used as default response type when unrecognized or no format is specified.
$proxmox->setResponseType();  // sets response type to 'array'
$proxmox->setResponseType('McDonalds');  // Also sets response type to 'array'

FAQ

What resources or paths can I interact with and how?

In your proxmox server you can use the pvesh CLI Tool to manage all the pve resources, you can use this library in the exact same way you would use the pvesh tool. For instance you could run pvesh then, as the screen message should say, you can type help [path] [--verbose] to see how you could use a path and what params you should pass to it. Be sure to read about the pvesh CLI Tool at the Proxmox wiki.

How does the Proxmox API works?

Consult the ProxmoxVE API article at the Proxmox wiki.

I need more docs!

See the wiki for more detailed documentation. Or use the Proxmox forums support.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Core concepts

Core concepts

ProxmoxVE API Client library

Installation

Basic usage

Available functions

Set and get credentials

Using custom credentials object

Set and get response type

FAQ

Clone this wiki locally