EZSCALE/virtfusion-whmcs-module
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

feat: auto-create custom fields, add try/catch coverage, PHPDoc, and Pint formatting
All checks were successful
Publish Release / release (push) Successful in 10s
Details

Browse Source 
- Auto-create 'Initial Operating System' and 'Initial SSH Key' custom fields
  via Database::ensureCustomFields() on module load, eliminating the manual
  modify.sql step
- Delete modify.sql (no longer needed)
- Add try/catch blocks around every DB operation and API call across all PHP
  files per CLAUDE.md error handling rules
- Add comprehensive PHPDoc to all classes, methods, and properties
- Set up Laravel Pint (laravel/pint) with Laravel-style preset for consistent
  code formatting across the codebase
- Add git pre-commit hook (hooks/pre-commit) that runs Pint on staged PHP
  files, auto-installed via Composer post-install/post-update scripts
- Simplify README installation to a single copy-paste command

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Prophet731
2026-03-19 15:03:17 -05:00
parent 1ab2ef42a5
commit d253bd44e6
22 changed files with 2384 additions and 1474 deletions
Download Patch File Download Diff File Expand all files Collapse all files

643
modules/servers/VirtFusionDirect/lib/ModuleFunctions.php
View File

@@ -2,6 +2,12 @@
namespace WHMCS\Module\Server\VirtFusionDirect;
/**
* Extends Module to handle the WHMCS service lifecycle for VirtFusion servers.
*
* Responsibilities include: provisioning (create, suspend, unsuspend, terminate),
* package changes, usage updates, client area rendering, and admin tab fields.
*/
class ModuleFunctions extends Module
{
public function __construct()
@@ -10,13 +16,13 @@ class ModuleFunctions extends Module
}
/**
* Provision a new VirtFusion server for a WHMCS service.
*
* CREATE SERVER
*
* Before creating a server, we check to see if a user exists in VirtFusion that matches
* the WHMCS user. If it matches, We move on to create the server, if not, we attempt to
* create a user to assign to the new server.
* Ensures a matching VirtFusion user exists (creating one if needed), then creates
* the server and triggers the OS build via ConfigureService::initServerBuild().
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function createAccount($params)
{
@@ -33,9 +39,9 @@ class ModuleFunctions extends Module
* If no VirtFusionDirect control server exists, cancel the create account action.
*/
$server = $params['serverid'] ?: false;
$cp = $this->getCP($server, !$server);
$cp = $this->getCP($server, ! $server);
if (!$cp) {
if (! $cp) {
return 'No Control server found. Please ensure a VirtFusion server is configured in WHMCS.';
}
@@ -62,16 +68,16 @@ class ModuleFunctions extends Module
*/
$user = Database::getUser($params['userid']);
if (!$user) {
if (! $user) {
return 'WHMCS user not found for ID ' . (int) $params['userid'];
}
$request = $this->initCurl($cp['token']);
$userData = [
"name" => $user->firstname . ' ' . $user->lastname,
"email" => $user->email,
"extRelationId" => $user->id,
'name' => $user->firstname . ' ' . $user->lastname,
'email' => $user->email,
'extRelationId' => $user->id,
];
// Enable self-service billing if configured
@@ -100,7 +106,6 @@ class ModuleFunctions extends Module
/**
* A user is available. We can now attempt to create a server.
*/
$configOptionDefaultNaming = [
'ipv4' => 'IPv4',
'packageId' => 'Package',
@@ -122,10 +127,10 @@ class ModuleFunctions extends Module
}
$options = [
"packageId" => (int) $params['configoption2'],
"userId" => $data->data->id,
"hypervisorId" => (int) $params['configoption1'],
"ipv4" => (int) $params['configoption3'],
'packageId' => (int) $params['configoption2'],
'userId' => $data->data->id,
'hypervisorId' => (int) $params['configoption1'],
'ipv4' => (int) $params['configoption3'],
];
if (array_key_exists('configoptions', $params)) {
@@ -159,7 +164,7 @@ class ModuleFunctions extends Module
$this->updateWhmcsServiceParamsOnServerObject($params['serviceid'], $data);
// If the server is created successfully, we can initialize the server build.
$cs = new ConfigureService();
$cs = new ConfigureService;
$vfUserId = isset($data->data->owner->id) ? (int) $data->data->owner->id : null;
$cs->initServerBuild($data->data->id, $params, $vfUserId);
@@ -171,328 +176,440 @@ class ModuleFunctions extends Module
if (isset($data->msg)) {
return $data->msg;
}
return 'Server creation failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
}
/**
* Allows changing of the package of a server
* Change the VirtFusion package assigned to a server and apply resource modifications.
*
* @param $params
* @return string
* Updates the package via the API, then individually adjusts memory, CPU, and bandwidth
* if those configurable options are present.
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function changePackage($params)
{
$service = Database::getSystemService($params['serviceid']);
try {
$service = Database::getSystemService($params['serviceid']);
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (!$whmcsService) return 'WHMCS service record not found.';
$cp = $this->getCP($whmcsService->server);
if (!$cp) return 'No control server found.';
$request = $this->initCurl($cp['token']);
$data = $request->put($cp['url'] . '/servers/' . (int) $service->server_id . '/package/' . (int) $params['configoption2']);
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 204:
break;
case 404:
return 'The server or package was not found in VirtFusion (HTTP 404).';
case 423:
if (isset($data->msg)) {
return $data->msg;
}
return 'The server is currently locked. Please try again later.';
default:
return 'Update package request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
// Apply individual resource modifications from configurable options
if (isset($params['configoptions']) && is_array($params['configoptions'])) {
$configOptionDefaultNaming = [
'memory' => 'Memory',
'cpuCores' => 'CPU Cores',
'traffic' => 'Bandwidth',
];
$configOptionCustomNaming = [];
if (file_exists(ROOTDIR . '/modules/servers/VirtFusionDirect/config/ConfigOptionMapping.php')) {
$configOptionCustomNaming = require ROOTDIR . '/modules/servers/VirtFusionDirect/config/ConfigOptionMapping.php';
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (! $whmcsService) {
return 'WHMCS service record not found.';
}
foreach ($configOptionDefaultNaming as $resource => $optionName) {
$currentOption = array_key_exists($resource, $configOptionCustomNaming) ? $configOptionCustomNaming[$resource] : $optionName;
if (isset($params['configoptions'][$currentOption]) && is_numeric($params['configoptions'][$currentOption])) {
$value = (int) $params['configoptions'][$currentOption];
if ($resource === 'memory' && $value < 1024) {
$value = $value * 1024;
$cp = $this->getCP($whmcsService->server);
if (! $cp) {
return 'No control server found.';
}
$request = $this->initCurl($cp['token']);
$data = $request->put($cp['url'] . '/servers/' . (int) $service->server_id . '/package/' . (int) $params['configoption2']);
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 204:
break;
case 404:
return 'The server or package was not found in VirtFusion (HTTP 404).';
case 423:
if (isset($data->msg)) {
return $data->msg;
}
return 'The server is currently locked. Please try again later.';
default:
return 'Update package request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
// Apply individual resource modifications from configurable options
if (isset($params['configoptions']) && is_array($params['configoptions'])) {
$configOptionDefaultNaming = [
'memory' => 'Memory',
'cpuCores' => 'CPU Cores',
'traffic' => 'Bandwidth',
];
$configOptionCustomNaming = [];
if (file_exists(ROOTDIR . '/modules/servers/VirtFusionDirect/config/ConfigOptionMapping.php')) {
$configOptionCustomNaming = require ROOTDIR . '/modules/servers/VirtFusionDirect/config/ConfigOptionMapping.php';
}
foreach ($configOptionDefaultNaming as $resource => $optionName) {
$currentOption = array_key_exists($resource, $configOptionCustomNaming) ? $configOptionCustomNaming[$resource] : $optionName;
if (isset($params['configoptions'][$currentOption]) && is_numeric($params['configoptions'][$currentOption])) {
$value = (int) $params['configoptions'][$currentOption];
if ($resource === 'memory' && $value < 1024) {
$value = $value * 1024;
}
$this->modifyResource($params['serviceid'], $resource, $value);
}
$this->modifyResource($params['serviceid'], $resource, $value);
}
}
return 'success';
}
return 'success';
return 'Service not found in module database.';
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
return 'Service not found in module database.';
}
/**
* Delete a VirtFusion server, applying the default 5-minute grace period before destruction.
*
* TERMINATE SERVER
*
* When requesting to terminate a server in VirtFusion, we leave it set to
* the default 5-minute delay allowing to un-terminate in VirtFusion if the
* request was done in error.
* On success, removes the service record from the module database and clears WHMCS service fields.
* If VirtFusion reports the server is already gone (404 + "server not found"), treats it as success.
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function terminateAccount($params)
{
$service = Database::getSystemService($params['serviceid']);
try {
$service = Database::getSystemService($params['serviceid']);
if ($service) {
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (!$whmcsService) return 'WHMCS service record not found.';
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (! $whmcsService) {
return 'WHMCS service record not found.';
}
$cp = $this->getCP($whmcsService->server);
if (!$cp) return 'No control server found.';
$cp = $this->getCP($whmcsService->server);
if (! $cp) {
return 'No control server found.';
}
$request = $this->initCurl($cp['token']);
$data = $request->delete($cp['url'] . '/servers/' . (int) $service->server_id);
$data = json_decode($data);
$request = $this->initCurl($cp['token']);
$data = $request->delete($cp['url'] . '/servers/' . (int) $service->server_id);
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
switch ($request->getRequestInfo('http_code')) {
case 204:
Database::deleteSystemService($params['serviceid']);
$this->updateWhmcsServiceParamsOnDestroy($params['serviceid']);
return 'success';
case 204:
Database::deleteSystemService($params['serviceid']);
$this->updateWhmcsServiceParamsOnDestroy($params['serviceid']);
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
return 'success';
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
} else {
return 'VirtFusion returned 404: ' . $data->msg;
}
} else {
return 'VirtFusion returned 404: ' . $data->msg;
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
} else {
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
default:
return 'Termination request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
default:
return 'Termination request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
return 'Service not found in module database. Has termination already been run?';
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
return 'Service not found in module database. Has termination already been run?';
}
/**
* Suspend a VirtFusion server, queuing the action if another operation is in progress.
*
* SUSPEND SERVER
*
* When requesting to suspend a server in VirtFusion it may be delayed if another action
* is being processed. This function will return success if the server is either suspended
* now or has been queued for suspension.
* Returns 'success' whether the server is suspended immediately or queued for suspension.
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function suspendAccount($params)
{
$service = Database::getSystemService($params['serviceid']);
try {
$service = Database::getSystemService($params['serviceid']);
if ($service) {
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (!$whmcsService) return 'WHMCS service record not found.';
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (! $whmcsService) {
return 'WHMCS service record not found.';
}
$cp = $this->getCP($whmcsService->server);
if (!$cp) return 'No control server found.';
$cp = $this->getCP($whmcsService->server);
if (! $cp) {
return 'No control server found.';
}
$request = $this->initCurl($cp['token']);
$data = $request->post($cp['url'] . '/servers/' . (int) $service->server_id . '/suspend');
$data = json_decode($data);
$request = $this->initCurl($cp['token']);
$data = $request->post($cp['url'] . '/servers/' . (int) $service->server_id . '/suspend');
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
switch ($request->getRequestInfo('http_code')) {
case 204:
return 'success';
case 204:
return 'success';
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
} else {
return 'VirtFusion returned 404: ' . $data->msg;
}
} else {
return 'VirtFusion returned 404: ' . $data->msg;
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
} else {
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
case 423:
if (isset($data->msg)) {
return $data->msg;
}
return 'The server is currently locked. Please try again later.';
default:
return 'Suspend request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
return 'Service not found in module database.';
}
function updateServerObject($params)
{
$service = Database::getSystemService($params['serviceid']);
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (!$whmcsService) return 'WHMCS service record not found.';
$cp = $this->getCP($whmcsService->server);
if (!$cp) return 'No control server found.';
$request = $this->initCurl($cp['token']);
$data = $request->get($cp['url'] . '/servers/' . (int) $service->server_id);
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 200:
Database::updateSystemServiceServerObject($params['serviceid'], $data);
$this->updateWhmcsServiceParamsOnServerObject($params['serviceid'], $data);
return 'success';
default:
return 'Request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
return 'Service not found in module database.';
}
public function unsuspendAccount($params)
{
$service = Database::getSystemService($params['serviceid']);
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (!$whmcsService) return 'WHMCS service record not found.';
$cp = $this->getCP($whmcsService->server);
if (!$cp) return 'No control server found.';
$request = $this->initCurl($cp['token']);
$data = $request->post($cp['url'] . '/servers/' . (int) $service->server_id . '/unsuspend');
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 204:
return 'success';
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
} else {
return 'VirtFusion returned 404: ' . $data->msg;
case 423:
if (isset($data->msg)) {
return $data->msg;
}
} else {
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
case 423:
if (isset($data->msg)) {
return $data->msg;
}
return 'The server is currently locked. Please try again later.';
default:
return 'Unsuspend request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
return 'The server is currently locked. Please try again later.';
default:
return 'Suspend request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
}
return 'Service not found in module database.';
}
public function adminServicesTabFields($params)
{
$serverId = '';
$serverObject = '';
return 'Service not found in module database.';
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
$service = Database::getSystemService($params['serviceid']);
$systemUrl = Database::getSystemUrl();
if ($service) {
$serverId = $service->server_id;
$serverObject = $service->server_object;
}
$fields = [
'Server ID' => AdminHTML::serverId($serverId),
'Server Info' => AdminHTML::serverInfo($systemUrl, $params['serviceid']),
'Server Object' => AdminHTML::serverObject($serverObject),
];
if ($params['status'] != 'Terminated') {
$fields['Options'] = AdminHTML::options($systemUrl, $params['serviceid']);
}
return $fields;
}
public function adminServicesTabFieldsSave($params)
{
if (!isset($_POST['modulefields'][0]) || $_POST['modulefields'][0] === '') {
Database::deleteSystemService($params['serviceid']);
} else {
$serverId = (int) $_POST['modulefields'][0];
if ($serverId > 0) {
Database::updateSystemServiceServerId($params['serviceid'], $serverId);
}
return $e->getMessage();
}
}
/**
* Validate server creation parameters via dry run.
* Refresh the cached server object by fetching fresh data from the VirtFusion API.
*
* @param array $params WHMCS service params
* @return string 'success' or error message
* Updates both the module database record and the WHMCS service fields (IP, username, etc.).
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function updateServerObject($params)
{
try {
$service = Database::getSystemService($params['serviceid']);
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (! $whmcsService) {
return 'WHMCS service record not found.';
}
$cp = $this->getCP($whmcsService->server);
if (! $cp) {
return 'No control server found.';
}
$request = $this->initCurl($cp['token']);
$data = $request->get($cp['url'] . '/servers/' . (int) $service->server_id);
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 200:
Database::updateSystemServiceServerObject($params['serviceid'], $data);
$this->updateWhmcsServiceParamsOnServerObject($params['serviceid'], $data);
return 'success';
default:
return 'Request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
return 'Service not found in module database.';
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
}
/**
* Unsuspend a VirtFusion server, queuing the action if another operation is in progress.
*
* Returns 'success' whether the server is unsuspended immediately or queued for unsuspension.
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function unsuspendAccount($params)
{
try {
$service = Database::getSystemService($params['serviceid']);
if ($service) {
$whmcsService = Database::getWhmcsService($params['serviceid']);
if (! $whmcsService) {
return 'WHMCS service record not found.';
}
$cp = $this->getCP($whmcsService->server);
if (! $cp) {
return 'No control server found.';
}
$request = $this->initCurl($cp['token']);
$data = $request->post($cp['url'] . '/servers/' . (int) $service->server_id . '/unsuspend');
$data = json_decode($data);
Log::insert(__FUNCTION__, $request->getRequestInfo(), $data);
switch ($request->getRequestInfo('http_code')) {
case 204:
return 'success';
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
Database::deleteSystemService($params['serviceid']);
return 'success';
} else {
return 'VirtFusion returned 404: ' . $data->msg;
}
} else {
return 'VirtFusion returned 404 without details. The API may be unavailable.';
}
case 423:
if (isset($data->msg)) {
return $data->msg;
}
return 'The server is currently locked. Please try again later.';
default:
return 'Unsuspend request failed. VirtFusion API returned HTTP ' . $request->getRequestInfo('http_code');
}
}
return 'Service not found in module database.';
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
}
/**
* Generate the admin Services tab custom fields for a VirtFusion service.
*
* Returns fields for Server ID (editable), Server Info, Server Object (JSON viewer),
* and Options (action buttons), omitting Options for terminated services.
*
* @param array $params WHMCS service parameters
* @return array Associative array of field label => HTML content
*/
public function adminServicesTabFields($params)
{
try {
$serverId = '';
$serverObject = '';
$service = Database::getSystemService($params['serviceid']);
$systemUrl = Database::getSystemUrl();
if ($service) {
$serverId = $service->server_id;
$serverObject = $service->server_object;
}
$fields = [
'Server ID' => AdminHTML::serverId($serverId),
'Server Info' => AdminHTML::serverInfo($systemUrl, $params['serviceid']),
'Server Object' => AdminHTML::serverObject($serverObject),
];
if ($params['status'] != 'Terminated') {
$fields['Options'] = AdminHTML::options($systemUrl, $params['serviceid']);
}
return $fields;
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
return [];
}
}
/**
* Save the admin Services tab custom fields for a VirtFusion service.
*
* Deletes the module database record if the Server ID field is cleared,
* or updates it with the new integer server ID if a value is provided.
*
* @param array $params WHMCS service parameters
* @return void
*/
public function adminServicesTabFieldsSave($params)
{
try {
if (! isset($_POST['modulefields'][0]) || $_POST['modulefields'][0] === '') {
Database::deleteSystemService($params['serviceid']);
} else {
$serverId = (int) $_POST['modulefields'][0];
if ($serverId > 0) {
Database::updateSystemServiceServerId($params['serviceid'], $serverId);
}
}
} catch (\Exception $e) {
Log::insert(__FUNCTION__, $params, $e->getMessage());
}
}
/**
* Perform a dry-run server creation to validate the current product configuration.
*
* Used by the WHMCS "Test Connection" button to confirm that the package, hypervisor,
* and IP settings are accepted by the VirtFusion API without creating a server.
*
* @param array $params WHMCS service parameters
* @return string 'success' or an error message
*/
public function validateServerConfig($params)
{
try {
$server = $params['serverid'] ?: false;
$cp = $this->getCP($server, !$server);
$cp = $this->getCP($server, ! $server);
if (!$cp) {
if (! $cp) {
return 'No Control server found.';
}
$options = [
"packageId" => (int) $params['configoption2'],
"hypervisorId" => (int) $params['configoption1'],
"ipv4" => (int) $params['configoption3'],
'packageId' => (int) $params['configoption2'],
'hypervisorId' => (int) $params['configoption1'],
'ipv4' => (int) $params['configoption3'],
];
// We need a userId for dry run - use the service owner
@@ -517,6 +634,16 @@ class ModuleFunctions extends Module
}
}
/**
* Render the client area overview tab for a VirtFusion service.
*
* Returns the template name and variables (system URL, service status, hostname,
* self-service mode) needed by the Smarty overview template. Falls back to an
* error template on any exception.
*
* @param array $params WHMCS service parameters
* @return array Template name and variables for WHMCS to render
*/
public function clientArea($params)
{
$serverHostname = null;