doc & small bugs

cwp7.php

@@ -17,6 +17,13 @@ if (!defined('WHMCS')) {
 	die('This file cannot be accessed directly');
 }
 
+/**
+ * Define CWP7 product metadata parameters. 
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/meta-data-params/
+ *
+ * @return array
+ */
 function cwp7_MetaData() {
     return array(
         'DisplayName' => 'CentOS Web Panel Provisioning',
@@ -29,6 +36,23 @@ function cwp7_MetaData() {
     );
 }
 
+/**
+ * Test connection to a CWP7 server with the given server parameters.
+ *
+ * Allows an admin user to verify that an API connection can be
+ * successfully made with the given configuration parameters for a
+ * server.
+ *
+ * When defined in a module, a test connection button will appear
+ * alongside the server type dropdown when adding or editing an
+ * existing server.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/module-parameters/
+ *
+ * @return array
+ */
 function cwp7_Testconnection($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->getServerType();
@@ -44,6 +68,13 @@ function cwp7_Testconnection($params) {
     );
 }
 
+/**
+ * Define CWP7 product configuration options. 
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/config-options/
+ *
+ * @return array
+ */
 function cwp7_ConfigOptions() {
     $whmcs = App::self();
     $serverGroupID = $whmcs->get_req_var('servergroup');
@@ -91,6 +122,22 @@ function cwp7_ConfigOptions() {
 	return $configOptions;
 }
 
+/**
+ * Provision a new account of a CWP7 server.
+ *
+ * Attempt to provision a new CWP7 account. This is
+ * called any time provisioning is requested inside of WHMCS. Depending upon the
+ * configuration, this can be any of:
+ * * When a new order is placed
+ * * When an invoice for a new order is paid
+ * * Upon manual request by an admin user
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ * 
+ * @return string 'success' or an error message
+ */
 function cwp7_CreateAccount($params) {
 	$username = strtolower(substr($params['clientsdetails']['firstname'],0,2) . substr($params['clientsdetails']['lastname'],0,3)) . $params['serviceid'];
 	$userdomain = $username . '.local';
@@ -134,6 +181,18 @@ function cwp7_CreateAccount($params) {
 	return 'success';
 }
 
+/**
+ * Removes a CWP7 account.
+ *
+ * Called when a termination is requested. This can be invoked automatically for
+ * overdue products if enabled, or requested manually by an admin user.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string 'success' or an error message
+ */
 function cwp7_TerminateAccount($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->deleteAccount(array('user' => $params['username'], 'email' => $params['clientsdetails']['email']));
@@ -143,6 +202,19 @@ function cwp7_TerminateAccount($params) {
 	return 'success';
 }
 
+/**
+ * Set a CWP7 account to status inactive.
+ *
+ * Called when a suspension is requested. This is invoked automatically by WHMCS
+ * when a product becomes overdue on payment or can be called manually by admin
+ * user.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string 'success' or an error message
+ */
 function cwp7_SuspendAccount($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->suspendAccount($params['username']);
@@ -152,6 +224,19 @@ function cwp7_SuspendAccount($params) {
 	return 'success';
 }
 
+/**
+ * Set a CWP7 account to status active.
+ *
+ * Called when an un-suspension is requested. This is invoked
+ * automatically upon payment of an overdue invoice for a product, or
+ * can be called manually by admin user.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string 'success' or an error message
+ */
 function cwp7_UnsuspendAccount($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->unsuspendAccount($params['username']);
@@ -161,6 +246,19 @@ function cwp7_UnsuspendAccount($params) {
 	return 'success';
 }
 
+/**
+ * Client area output logic handling.
+ *
+ * This function is used to define module specific client area output. It should
+ * return an array consisting of a template file and optional additional
+ * template variables to make available to that template.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/client-area-output/
+ *
+ * @return array
+ */
 function cwp7_ClientArea($params) {
 	$clientInfo = array('moduleclientarea' => '1');
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
@@ -231,6 +329,17 @@ function cwp7_ClientArea($params) {
     );
 }
 
+/**
+ * Perform single sign-on for a CWP7 account.
+ *
+ * When successful, returns a URL to which the user should be redirected.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/single-sign-on/
+ *
+ * @return array
+ */
 function cwp7_ServiceSingleSignOn($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->getLoginLink($params['username']);
@@ -249,6 +358,22 @@ function cwp7_ServiceSingleSignOn($params) {
 	}
 }
 
+/**
+ * Change the password for a CWP7 account.
+ *
+ * Called when a password change is requested. This can occur either due to a
+ * client requesting it via the client area or an admin requesting it from the
+ * admin side.
+ *
+ * This option is only available to client end users when the product is in an
+ * active status.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_ChangePassword($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->changePass(array('user' => $params['username'], 'password' => $params['password']));
@@ -258,6 +383,22 @@ function cwp7_ChangePassword($params) {
 	return 'success';
 }
 
+/**
+ * Upgrade or downgrade a CWP7 account by package.
+ *
+ * Called to apply any change in product assignment or parameters. It
+ * is called to provision upgrade or downgrade orders, as well as being
+ * able to be invoked manually by an admin user.
+ *
+ * This same function is called for upgrades and downgrades of both
+ * products and configurable options.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_ChangePackage($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->modifyAccount(array('user' => $params['username'], 'email' => $params['clientdetails']['email'], 'package' => $params['configoption1']));
@@ -267,6 +408,15 @@ function cwp7_ChangePackage($params) {
 	return 'success';
 }
 
+/**
+ * Usage Update
+ * 
+ * Important: Runs daily per server not per product
+ * Run Manually: /admin/reports.php?report=disk_usage_summary&action=updatestats
+ * @param array $params common module parameters
+ * 
+ * @see https://developers.whmcs.com/provisioning-modules/usage-update/
+ */
 function cwp7_UsageUpdate($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->getAllAccounts();
@@ -312,6 +462,17 @@ function cwp7_UsageUpdate($params) {
 	}
 }
 
+/**
+ * Additional actions a client user can invoke.
+ *
+ * Define additional actions a client user can perform for an instance of a
+ * product/service.
+ *
+ * Any actions you define here will be automatically displayed in the available
+ * list of actions within the client area.
+ *
+ * @return array
+ */
 function cwp7_ClientAreaCustomButtonArray ($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->getAccount($params['username']);
@@ -335,6 +496,16 @@ function cwp7_ClientAreaCustomButtonArray ($params) {
 	);
 }
 
+/**
+ * Additional actions a client user can invoke.
+ *
+ * Define additional actions a client user is allowed to perform for an instance of a
+ * product/service.
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ * 
+ * @return array
+ */
 function cwp7_ClientAreaAllowedFunctions() {
 	return array(
 		"Enable SSL" => "enableSSL",
@@ -353,6 +524,15 @@ function cwp7_ClientAreaAllowedFunctions() {
   	);
 }
 
+/**
+ * Opens a form to add a new domain.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_newDomain($params) {
 	return array(
         'breadcrumb' => array(
@@ -362,6 +542,15 @@ function cwp7_newDomain($params) {
     );
 }
 
+/**
+ * Adds a new domain to a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_addDomain($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -377,6 +566,15 @@ function cwp7_addDomain($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to add a new subdomain to a domain.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_newSubdomain($params) {
 	$cwp7 = new cwp7_Admin($params['serverhostname'], $params['serveraccesshash']);
 	$response = $cwp7->getAccount($params['username']);
@@ -408,6 +606,15 @@ function cwp7_newSubdomain($params) {
     );
 }
 
+/**
+ * Adds a new subdomain to domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_addSubdomain($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -435,6 +642,15 @@ function cwp7_addSubdomain($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to delete a domain from a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_delDomainConfirm($params) {
 	return array(
 		'templatefile' => 'cwp7_del_domain_confirm',
@@ -444,6 +660,15 @@ function cwp7_delDomainConfirm($params) {
     );
 }
 
+/**
+ * Removes a domain from a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_delDomain($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -487,6 +712,15 @@ function cwp7_delDomain($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to delete a subdomain from domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_delSubdomainConfirm($params) {
 	return array(
 		'templatefile' => 'cwp7_del_subdomain_confirm',
@@ -496,6 +730,15 @@ function cwp7_delSubdomainConfirm($params) {
     );
 }
 
+/**
+ * Removes a subdomain from a domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_delSubdomain($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -539,6 +782,15 @@ function cwp7_delSubdomain($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to enable SSL for a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_enableSSLConfirm($params) {
 	return array(
 		'templatefile' => 'cwp7_enable_SSL_confirm',
@@ -548,6 +800,15 @@ function cwp7_enableSSLConfirm($params) {
     );
 }
 
+/**
+ * Aktivate CWP7 AutoSSL for a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_enableSSL($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -562,6 +823,15 @@ function cwp7_enableSSL($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to renew a SSL certificate for a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_renewSSLConfirm($params) {
 	return array(
 		'templatefile' => 'cwp7_renew_SSL_confirm',
@@ -571,6 +841,15 @@ function cwp7_renewSSLConfirm($params) {
     );
 }
 
+/**
+ * Renews a SSL certificate for a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_renewSSL($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -585,6 +864,15 @@ function cwp7_renewSSL($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to set a DNS record for a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_setDNSConfirm($params) {
 	if(isset($_POST['s'])){
 		return array(
@@ -603,6 +891,15 @@ function cwp7_setDNSConfirm($params) {
     );
 }
 
+/**
+ * Update a DNS zone for a domain setting a new record for a domain or subdomain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string "success" or an error message
+ */
 function cwp7_setDNS($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -650,11 +947,12 @@ function cwp7_setDNS($params) {
 	$zoneIDcollection = Capsule::table('dns_manager2_zone')
 		->select('id')
 		->where('name', '=', $domainName)
+		->where('clientid', '=', $params['userid'])
 		->get();
 	$zoneIDobj = $zoneIDcollection[0];
 	$zoneID = $zoneIDobj->{'id'};
 	if(!isset($zoneID)) {
-		return 'Error: zone ID not found for domain ' . $domainName;
+		return 'Error: Zone for domain ' . $domainName . ' or not owned by client';
 	}
 	$dnsZone = localAPI('dnsmanager', array( 'dnsaction' => 'getZone', 'zone_id' => $zoneID));
     foreach($dnsZone['data']->records as $record) {
@@ -675,6 +973,15 @@ function cwp7_setDNS($params) {
 	return 'success';
 }
 
+/**
+ * Opens a form to inform about the DNS status of a subdomain or domain of a CWP7 account.
+ *
+ * @param array $params common module parameters
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return array template information
+ */
 function cwp7_infoDNS($params) {
 	if(!filter_var($_POST['d'], FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)){
 		return 'Error: invalid domain name';
@@ -689,14 +996,26 @@ function cwp7_infoDNS($params) {
     );
 }
 
-function cwp7CheckA($domain, $serverIP, $nameserverIP, $recurse = 0) {
+/**
+ * Ask nameservers for a IP adress of a given host.
+ *
+ * @param string $host hostname
+ * @param string $serverIP CWP7 server IP
+ * @param string $nameserverIP polled name server IP
+ * @param int $recurse optional -> used to follow CNAME responses
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return bool
+ */
+function cwp7CheckA($host, $serverIP, $nameserverIP, $recurse = 0) {
 	if($recurse > 3) {
 		return false;
 	}
 	$nameserver = array($nameserverIP);
 	$resolver = new Net_DNS2_Resolver(array('nameservers' => $nameserver));
     try {
-            $result = $resolver->query($domain, 'A');
+            $result = $resolver->query($host, 'A');
             
     } catch(Net_DNS2_Exception $e) {
 		logModuleCall(
@@ -707,19 +1026,31 @@ function cwp7CheckA($domain, $serverIP, $nameserverIP, $recurse = 0) {
 			$e->getMessage()
 		);
 	}
-	$domainA = $result->answer;
-	if($domainA[0]->type == 'CNAME') {
-		if(cwp7CheckA($domainA[0]->cname, $serverIP, $nameserverIP, $recurse++)) {
+	$hostA = $result->answer;
+	if($hostA[0]->type == 'CNAME') {
+		if(cwp7CheckA($hostA[0]->cname, $serverIP, $nameserverIP, $recurse++)) {
 			return true;
 		}
 	}
-	if($domainA[0]->type == 'A') {
-		if($domainA[0]->address == $serverIP){
+	if($hostA[0]->type == 'A') {
+		if($hostA[0]->address == $serverIP){
 			return true;
 		}
 	}
+	return false;
 }
 
+/**
+ * Ask nameservers for the authority of a domain.
+ *
+ * @param string $domain domain name
+ * @param string $nameserverIP polled name server IP
+ * @param string $nameserverName name of the own namesever
+ *
+ * @see https://developers.whmcs.com/provisioning-modules/supported-functions/
+ *
+ * @return string 'none' -> not registered, 'self' -> registered at own or the name of an other responsible nameserver
+ */
 function cwp7CheckSOA($domain, $nameserverIP, $nameserverName ) {
 	$nameserver = array($nameserverIP);
 	$resolver = new Net_DNS2_Resolver(array('nameservers' => $nameserver));