Skip to content

About

PHP client for the HestiaCP API: users, web domains, mail, databases and backups

Topics

Resources

Stars

9 stars

Watchers

2 watching

Forks

Repository files navigation

HestiaCP PHP API logo

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.

Latest Stable Version Total Downloads PHP 8.3 or later Tests Coverage License


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 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.

Requirements

  • 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.

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, 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.
Mail 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 null lets 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.

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, ...), or the host isn't HestiaCP
}

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

Documentation

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.

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.

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.

About

PHP client for the HestiaCP API: users, web domains, mail, databases and backups

Topics

Resources

Stars

9 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages