README

HestiaCP PHP API

A modern PHP client for the HestiaCP API.
Manage users, web domains, mail, databases and backups on a HestiaCP server from your PHP code.

Features

Every HestiaCP login method: access keys (HestiaCP 1.6+), legacy API keys, and admin username and password.
Ready-made modules for users, web domains, mail, DNS, databases, backups, cron jobs and packages.
Errors as exceptions: each failure is a typed exception that carries HestiaCP's exit code, so you can tell "already exists" apart from "bad credentials".
TLS verification on by default, with an option for self-signed certificates.
Plain PHP arrays as results. The only dependency is Guzzle.
Lower-level access: send any of the bundled command classes directly, run any v-* script by name with RawCommand and RawListCommand, or write your own.
Tested on PHP 8.2 to 8.5 and checked against HestiaCP 1.10.

Requirements

PHP 8.2 or later
HestiaCP with the API enabled, and the IP address of the calling machine allowed in the server settings

Installation

composer require neto737/hestiacp-api

Quick start

use neto737\HestiaCP\Client;

// Access key (HestiaCP 1.6+), written as ACCESS_KEY:SECRET_KEY
$client = Client::simpleFactory('https://panel.example.com', 'ACCESS_KEY:SECRET_KEY');

// Check that the credentials work
$client->testAuthorization(); // bool

// List all users
$users = $client->getModuleUser()->list(); // ['admin' => ['NAME' => '...', 'CONTACT' => '...', ...], ...]

// Add a web domain for the admin user and give it a Let's Encrypt certificate
$web = $client->getModuleWeb('admin');
$web->addDomain('example.com');
$web->addDomainLetsEncrypt('example.com', 'www.example.com');

// Create a mailbox
$mail = $client->getModuleMail('admin');
$mail->addDomain('example.com');
$mail->addAccount('example.com', 'info', 'S3cure-Pa$$word');

Note

TLS certificates are verified by default. If your panel still uses the self-signed certificate created at install, see TLS certificates.

Modules

Module	Get it with	What it covers
Users	`getModuleUser()`	List, show, add and delete users. Change passwords, contact emails and packages, suspend and unsuspend, list usage stats, back up all users.
Web domains	`getModuleWeb($user)`	Add, delete, suspend and unsuspend domains. Aliases, SSL certificates, Let's Encrypt, templates, proxy and FTP accounts.
Mail	`getModuleMail($user)`	Mail domains and accounts, passwords, suspending, aliases, forwarding, autoreplies, DKIM keys and DNS records.
Databases	`getModuleDatabase($user)`	Create, list and delete databases. Change passwords, suspend and unsuspend.
Backups	`getModuleBackup($user)`	Create, list and delete backups. List and delete backup exclusions.
Packages	`getModulePackage()`	List and show hosting packages.
Cron jobs	`getModuleCron($user)`	List, add, change, suspend, unsuspend and delete cron jobs.
DNS	`getModuleDns($user)`	DNS domains and records: add, change, suspend, unsuspend and delete. TTL, SOA, templates and DNSSEC.

Need a command that isn't wrapped in a module? See Sending commands directly, or run any script by name when no command class exists for it.

Error handling

use neto737\HestiaCP\Command\ResponseCode;
use neto737\HestiaCP\Exceptions\AuthorizationException;
use neto737\HestiaCP\Exceptions\ClientException;
use neto737\HestiaCP\Exceptions\ProcessException;

try {
	$client->getModuleUser()->add('jane', 'S3cure-Pa$$word', 'jane@example.com');
} catch (AuthorizationException $e) {
	// wrong credentials, or not allowed to run the command
} catch (ProcessException $e) {
	if ($e->getCode() === ResponseCode::E_EXISTS) {
		// the user already exists
	}
} catch (ClientException $e) {
	// connection problem: timeout, DNS, TLS, ...
}

All exception types and exit codes are listed in Error handling.

Documentation

Authentication and client setup: access keys, legacy API keys, passwords, hostname rules, TLS and timeouts
Error handling: exception types and HestiaCP exit codes
Modules: Users · Web domains · Mail · Databases · Backups
Sending commands directly: using the command classes, and writing your own

Upgrading from v1? Read UPGRADING.md. All changes are listed in CHANGELOG.md.

Contributing

Bug reports and pull requests are welcome. To run the checks:

composer install
composer check    # coding style, static analysis and tests

Each check can also run on its own: composer test (PHPUnit), composer analyse (PHPStan) and composer cs (PHP-CS-Fixer). composer cs-fix fixes the coding style. The code uses tabs for indentation and LF line endings.

The tests use Guzzle's mock handler, so they don't need a HestiaCP server.

Credits

This library started as a fork of ProfiCloS/vestacp-api by PROFI CLOUD SERVICES s.r.o., a client for VestaCP, and was adapted and extended for HestiaCP.

This is a community project. It is not affiliated with or endorsed by the HestiaCP project. The Hestia logo used in this project's logo is copyright hestiacp.com and is included unmodified.

Support the project ❤️

If this library saves you time, you can support its development via Liberapay, PayPal or crypto:

BTC: bc1q89ntljt5lk7g9z68f5cjs83qfm2xme7g4hkur7
ETH: 0xeef9220639F14E7A0FD825AAAd0574e5a8aD7A4B
LTC: ltc1q508qfkd09vyya6c5zkfx4r248pf3ezj9ngjdr2

License

Released under the MIT License.

neto737 / hestiacp-api

Package info

Security

Fund package maintenance!

Statistics