A modern PHP client for the HestiaCP API.
Manage users, web domains, mail, databases and backups on a HestiaCP server from your PHP code.
- 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 withRawCommandandRawListCommand, or write your own. - Tested against a real server: besides the unit tests on PHP 8.3 to 8.5, every module method was tested against a live HestiaCP 1.10.9 server, with all three login methods.
- PHP 8.3 or later
- HestiaCP with the API enabled, and the IP address of the calling machine allowed in the server settings
- HestiaCP 1.6 or later for access keys. The library is tested on HestiaCP 1.10.9; an older version may lack some scripts or arguments, which HestiaCP reports as a failed command (a
ProcessException).
Where HestiaCP 1.10.9 behaves unexpectedly, the docs say so, for example in packages and DNSSEC.
composer require neto737/hestiacp-apiuse 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.
| Module | Get it with | What it covers |
|---|---|---|
| Users | getModuleUser() |
List, show, add and delete users. Change passwords, contact emails, packages, names, shells, languages and roles, suspend and unsuspend, list usage stats, back up all users. |
| Web domains | getModuleWeb($user) |
Add, delete, suspend and unsuspend domains. Change the IP address. Aliases, redirects, HTTP authentication, SSL certificates, Let's Encrypt, templates, proxy and FTP accounts. |
getModuleMail($user) |
Mail domains and accounts, passwords, quotas, suspending, aliases, forwarding, autoreplies, catch-all addresses, antispam and antivirus, DKIM keys and DNS records, SSL certificates. | |
| Databases | getModuleDatabase($user) |
Create, list and delete databases. Change passwords, suspend and unsuspend. |
| Backups | getModuleBackup($user) |
Create, list and delete backups. List, update and delete backup exclusions. |
| Packages | getModulePackage() |
List, show, add, copy, rename and delete 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. |
Every module follows the same rules:
- Modules that take a username work on that user's objects. Their methods don't take the username again.
- Methods that change something return
true, or throw an exception (see Error handling). Methods that read (list*(),detail(),stats()) return an array. - The arrays are HestiaCP's JSON as it is. Field names are uppercase, and every field value is a string, numbers included (
'TTL' => '14400'). Flags are'yes'or'no', so check$domain['SUSPENDED'] === 'yes', not=== true. - An optional argument left as
nulllets HestiaCP use its own default. Parameter names are stable, so you can use named arguments, for example$db->add('wp', 'wp', $password, charset: 'LATIN1').
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.
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, ...), or the host isn't HestiaCP
}All exception types and exit codes are listed in Error handling.
- 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 · DNS · Databases · Backups · Cron jobs · Packages
- Sending commands directly: using the command classes, and writing your own
Upgrading from v1? Read UPGRADING.md. All changes are listed in CHANGELOG.md.
Bug reports and pull requests are welcome. To run the checks:
composer install
composer check # coding style, static analysis and testsEach 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.
A separate suite runs against a real HestiaCP server, to catch what a mock can't: composer test:live. It needs HESTIACP_HOST and HESTIACP_ACCESS_KEY (an admin access key, ACCESS_KEY:SECRET_KEY), and optionally HESTIACP_HASH and HESTIACP_PASSWORD to test the legacy endpoint, and HESTIACP_VERIFY (a CA bundle path, or 0). Each test class creates a user and deletes it afterwards, so use a test server, not a production one. The suite covers every module method except Users::backup(), which backs up every user on the server, and Let's Encrypt, which needs a domain that resolves to the server; both were tested by hand against HestiaCP 1.10.9.
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.
If this library saves you time, you can support its development via Liberapay, PayPal or crypto:
BTC: bc1q89ntljt5lk7g9z68f5cjs83qfm2xme7g4hkur7
ETH: 0xeef9220639F14E7A0FD825AAAd0574e5a8aD7A4B
LTC: ltc1q508qfkd09vyya6c5zkfx4r248pf3ezj9ngjdr2
Released under the MIT License.