cylab-be/php-vbox-api

A PHP library to drive VirtualBox

1.8.4 2024-11-01 11:29 UTC

Requires

• ext-soap: *

Requires (Dev)

• insolita/unused-scanner: ^2.1
• phpseclib/phpseclib: ^2.0
• phpstan/phpstan: ^1.8
• phpunit/phpunit: ^8.2
• slevomat/coding-standard: ^6.0
• squizlabs/php_codesniffer: ^3.5
• vlucas/phpdotenv: ^3.3

MIT

• Thibault Debatty

README

A PHP library to drive VirtualBox. The API allows you to do stuff like:

$vbox = new VBox($username, $password);

// a single .ova may contain multiple machines
$vms = $vbox->import("/path/to/image.ova");
$vm = $vms[0];

$vm->setMemorySize(512); // MB
$vm->setCPUCount(2);

$adapter = $vm->getNetworkAdapter(0);
$adapter->setAttachmentType(NetworkAdapter::ATTACHEMENT_BRIDGED);
$adapter->setBridgedInterface("eno1");

$vm->up();

This library is actually a wrapper for the SOAP webservice of VirtualBox. You can find a copy of the complete SOAP webservice documentation in the documentation directory.

Installation

The library itself is best installed using composer:

composer require cylab-be/php-vbox-api

VirtualBox Web Service

You of course have to download and install VirtualBox.

In VirtualBox, each virtual machine is a separate user process. So it is usually best to create a dedicated user for running your VM's :

sudo adduser vbox

Then add this new user to the vbox group so it will be allowed to run virtual machines :

sudo adduser vbox vbox

Finally, you have to activate the VirtualBox Web Service.

Therefore, you have to create the file /etc/default/virtualbox and indicate which user should be used to run your machines:

VBOXWEB_USER=vbox

You can now start the VirtualBox Web Service:

sudo service vboxweb-service restart

Usage

Connecting to VirtualBox

$vbox = new VBox("vbox", "passord-of-vbox-user");

List all machines

$vms = $vbox->allVMs();
foreach ($vms as $vm) {
  echo $vm->getName() . "\n";
  echo $vm->getUUID() . "\n";
}

Modify a VM

$vm = $vbox->findVM("name or UUID");

// do a clean shutdown
$vm->halt();
$vm->setMemory(2048);
$vm->setCPUCount(4);
$vm->up();

// do a hard shutdown
$vm->kill();

// destroy the VM
$vm->destroy();

Take a screenshot

$vm->up();
sleep(5);
$img = $vm->takeScreenshot();
file_put_contents('/path/to/screenshot.png', $img);