eliashaeussler/cpanel-requests

Small PHP library enabling requests to cPanel instances

3.1.1 2024-01-16 19:13 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• ext-json: *
• guzzlehttp/guzzle: ^7.0
• guzzlehttp/psr7: ^2.0
• monolog/monolog: ^3.0
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0 || ^2.0
• symfony/console: ^6.0 || ^7.0
• symfony/filesystem: ^6.0 || ^7.0
• symfony/finder: ^6.0 || ^7.0

Requires (Dev)

• armin/editorconfig-cli: ^1.8 || ^2.0
• donatj/mock-webserver: ^2.4
• eliashaeussler/php-cs-fixer-config: ^2.0
• eliashaeussler/phpstan-config: ^2.0
• eliashaeussler/rector-config: ^2.0
• ergebnis/composer-normalize: ^2.28
• phpstan/extension-installer: ^1.2
• phpstan/phpstan-phpunit: ^1.1
• phpunit/phpunit: ^10.3
• spomky-labs/otphp: ^11.1
• thecodingmachine/safe: ^2.0

Suggests

• spomky-labs/otphp: Used for authentication via HTTP session (^11.1)

GPL-3.0-or-later

• Elias Häußler

README

📦 Packagist | :floppy_disk: Repository | :bug: Issue tracker

A simple PHP project to make API requests on your cPanel installation. This allows you to call modules inside the installation and interact with them to add, show or list data such as domains, e-mail accounts, databases and so on.

The project makes use of UAPI. Therefore, it is required to have a cPanel installation with at least version 42 running.

🔥 Installation

composer require eliashaeussler/cpanel-requests

⚠️ If you want to use two-factor authentication together with the HTTP session authorization method, you must manually require the spomky-labs/otphp package (>= 11.1).

⚡Usage

Authorization

The following authorization methods are currently available:

Type	Implementation class
Authorization via API token (recommended)	Application\Authorization\TokenAuthorization
Authorization via HTTP session	Application\Authorization\HttpAuthorization

💡 You can also provide your own implementation for authorization at your cPanel instance. For this, you have to implement the interface Application\Authorization\AuthorizationInterface.

Create a new CPanel instance

Once you have selected an authentication method, you can create a new Application\CPanel instance:

use EliasHaeussler\CpanelRequests\Application;

/** @var Application\Authorization\AuthorizationInterface $authorization */
$cPanel = new Application\CPanel($authorization, 'example.com', 2083);

Perform API requests

Now you're able to make API requests:

use EliasHaeussler\CpanelRequests\Application;

/** @var Application\CPanel $cPanel */
$response = $cPanel->api('<module>', '<function>', ['optional' => 'parameters']);
if ($response->isValid()) {
    // Do anything...
    // Response data can be fetched using $response->getData()
}

Note that currently only GET requests are supported.

Visit the official documentation to get an overview about available API modules and functions.

🐝 Example

use EliasHaeussler\CpanelRequests\Application;
use EliasHaeussler\CpanelRequests\Http;

$authorization = new Application\Authorization\TokenAuthorization(
    username: 'bob',
    token: '9CKU401OH5WVDGSAVXN3UMLT8BJ5IY',
);
$cPanel = new Application\CPanel(
    authorization: $authorization,
    host: 'cpanel.bobs.site',
    port: 2083,
    protocol: Http\Protocol::Https,
);

// Fetch domains from cPanel API
$response = $cPanel->api(
    module: 'DomainInfo',
    function: 'list_domains',
);

if (!$response->isValid()) {
    throw new \RuntimeException('Got invalid response from cPanel application.');
}

$domains = $response->getData()->data;
echo 'Bob\'s main domain is: ' . $domains->main_domain;

🗑️ Cleanup

The project provides a console application that can be used to execute several cleanup commands from the command line.

# General usage
vendor/bin/cpanel-requests

# Remove expired request cookie files (default lifetime: 1 hour)
vendor/bin/cpanel-requests cleanup:cookies
vendor/bin/cpanel-requests cleanup:cookies --lifetime 1800

# Remove log files
vendor/bin/cpanel-requests cleanup:logs

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).