nomadicsoft/simplecloud-php

PHP API client for SimpleCloud.ru VPS hosting (v3 API)

dev-master 2026-04-12 02:55 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

MIT

• NomadicSoft

• api
• vps
• cloud
• hosting
• simplecloud

README

A clean PHP API client for SimpleCloud.ru VPS hosting (v3 API).

Requirements

• PHP 8.1+
• Guzzle HTTP 7.x

Installation

composer require nomadicsoft/simplecloud-php

Quick Start

use CloudCompute\SimpleCloud\SimpleCloud;

$client = new SimpleCloud('your-api-token');

// List all VPS
$result = $client->vps->list();
foreach ($result['vps'] as $server) {
    echo $server['name'] . ' — ' . $server['status'] . PHP_EOL;
}

// Create a VPS
$vps = $client->vps->create(
    size: '1',
    image: 221,
    region: 'ixcellerate',
    paymentPeriod: '1m',
    name: 'my-server',
);

// Wait for it to become active
$vps = $client->vps->waitForStatus($vps['vps']['id'], 'active', maxSeconds: 120);
echo $vps['vps']['networks']['v4'][0]['ip_address'];

Configuration

$client = new SimpleCloud('your-token', [
    'timeout' => 60,
    'guzzle' => [
        // Any additional Guzzle client options
    ],
]);

Error Handling

The client throws typed exceptions for API errors:

use CloudCompute\SimpleCloud\Exceptions\AuthenticationException;
use CloudCompute\SimpleCloud\Exceptions\NotFoundException;
use CloudCompute\SimpleCloud\Exceptions\ValidationException;
use CloudCompute\SimpleCloud\Exceptions\SimpleCloudException;

try {
    $client->vps->get(999999);
} catch (AuthenticationException $e) {
    // 401 — invalid or expired token
} catch (NotFoundException $e) {
    // 404 — resource not found
} catch (ValidationException $e) {
    // 422 — invalid parameters
} catch (SimpleCloudException $e) {
    // Any other API error
    echo $e->getHttpStatusCode();
    echo $e->getErrorBody();
}

Resources

All resources are accessed as properties on the main SimpleCloud client instance. They are lazy-initialized on first access.

Account

$client->account->getInfo();                  // GET /account
$client->account->update([...]);              // POST /account
$client->account->getDetails();               // GET /account/details
$client->account->updateDetails([...]);       // POST /account/details
$client->account->getContacts();              // GET /account/contacts
$client->account->updateContacts([...]);      // POST /account/contacts
$client->account->getAuthLog($page, $perPage); // GET /account/authLog

Auth

$client->auth->login($login, $password);      // POST /auth/login

Finance

$client->finance->getLog(['since' => '...', 'till' => '...', 'direction' => 'incoming']);
$client->finance->getPaymentMethods();
$client->finance->recharge('AC', 1500.0, rebillingOn: false);

Notifications

$client->notifications->list($page, $perPage);
$client->notifications->list(announces: true);  // Announcements only

Subaccounts

$client->subaccounts->isEnabled();
$client->subaccounts->setEnabled(true);
$client->subaccounts->list($page, $perPage);
$client->subaccounts->get($id);
$client->subaccounts->create([...]);
$client->subaccounts->update($id, [...]);
$client->subaccounts->delete($id);
$client->subaccounts->getSessionKey($id);

Projects

$client->projects->list($page, $perPage);
$client->projects->get($id);
$client->projects->create([...]);
$client->projects->update($id, [...]);
$client->projects->delete($id);

Actions

$client->actions->list($page, $perPage);      // GET /actions
$client->actions->get($actionId);              // GET /actions/$id

Domains

$client->domains->list($page, $perPage);
$client->domains->get($domainId);
$client->domains->create('example.com', '1.2.3.4');
$client->domains->delete($domainId);

Domain Records

$client->domainRecords->list($domainId, $page, $perPage);
$client->domainRecords->get($domainId, $recordId);
$client->domainRecords->create($domainId, [
    'type' => 'A',
    'name' => 'sub',
    'data' => '1.2.3.4',
]);
$client->domainRecords->update($domainId, $recordId, ['name' => 'new-name']);
$client->domainRecords->delete($domainId, $recordId);

Reverse DNS

$client->reverseDns->list();
$client->reverseDns->get($recordId);
$client->reverseDns->update($recordId, 'new.domain.com.');
$client->reverseDns->reset($recordId);          // Reset to default
$client->reverseDns->createIpv6($vpsId);         // Create IPv6 reverse zone
$client->reverseDns->deleteIpv6($recordV6Id);    // Delete IPv6 reverse zone

VPS

CRUD

$client->vps->list($page, $perPage);
$client->vps->get($vpsId);
$client->vps->create(
    size: '1',
    image: 221,
    region: 'ixcellerate',
    paymentPeriod: '1m',   // '1h' or '1m'
    name: 'my-server',
    password: '',           // Auto-generated if empty
    mbit200: false,         // 200 Mbit/s upgrade
);
$client->vps->update($vpsId, [
    'size' => '2',
    'payment_period' => '1h',
    'mbit200' => true,
]);
$client->vps->delete($vpsId);

Actions

All actions use POST /vps/$id/actions with a type parameter:

$client->vps->reboot($vpsId);
$client->vps->reboot($vpsId, rescue: true);    // Rescue mode
$client->vps->powerCycle($vpsId);
$client->vps->shutdown($vpsId);
$client->vps->powerOff($vpsId);
$client->vps->powerOn($vpsId);
$client->vps->passwordReset($vpsId);
$client->vps->resize($vpsId, '2');              // New plan ID
$client->vps->rebuild($vpsId, 221);             // New image ID
$client->vps->rename($vpsId, 'new-name');
$client->vps->restore($vpsId, $backupImageId);
$client->vps->snapshot($vpsId, 'my-snapshot');

Action History, Backups, Statistics

$client->vps->getActions($vpsId, $page, $perPage);
$client->vps->getAction($vpsId, $actionId);

$client->vps->getBackups($vpsId, $page, $perPage);

// Statistics: type = CPU|RAM|disk|traffic (null = all), period = 1h|6h|12h|1d|7d|1m
$client->vps->getStatistics($vpsId);
$client->vps->getStatistics($vpsId, type: 'CPU', period: '1d');

Polling

$vps = $client->vps->waitForStatus(
    vpsId: $id,
    expectedStatus: 'active',
    maxSeconds: 120,
    intervalSeconds: 5,
);

Images

$client->images->list($page, $perPage);              // All images
$client->images->listDistributions($page, $perPage);  // OS distributions
$client->images->listApplications($page, $perPage);   // Application images
$client->images->get(7555620);                         // By ID
$client->images->get('ubuntu-14-04-x64');              // By slug

SSH Keys

$client->sshKeys->list($page, $perPage);
$client->sshKeys->get(512190);                          // By ID
$client->sshKeys->get('3b:16:bf:e4:...');               // By fingerprint
$client->sshKeys->create('My Key', 'ssh-rsa AAAA...');
$client->sshKeys->update(512190, 'Renamed Key');
$client->sshKeys->delete(512190);

Sizes (Plans)

$client->sizes->list();

Regions

$client->regions->list();

Pagination

List endpoints support pagination with page and perPage parameters. Responses include links.pages and meta.total:

$result = $client->vps->list(page: 2, perPage: 10);

$servers = $result['vps'];
$total = $result['meta']['total'];
$nextPage = $result['links']['pages']['next'] ?? null;

License

MIT