lots of phpdoc; fix Customers::update()

Signed-off-by: Michael Kaufmann (d00p) <d00p@froxlor.org>

lib/classes/api/abstract.ApiCommand.php

@@ -1,20 +1,76 @@
 <?php
 
+/**
+ * This file is part of the Froxlor project.
+ * Copyright (c) 2010 the Froxlor Team (see authors).
+ *
+ * For the full copyright and license information, please view the COPYING
+ * file that was distributed with this source code. You can also view the
+ * COPYING file online at http://files.froxlor.org/misc/COPYING.txt
+ *
+ * @copyright  (c) the authors
+ * @author     Froxlor team <team@froxlor.org> (2010-)
+ * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
+ * @package    API
+ * @since      0.10.0
+ *
+ */
 abstract class ApiCommand
 {
 
+	/**
+	 * debug flag
+	 *
+	 * @var boolean
+	 */
 	private $debug = true;
 
+	/**
+	 * is admin flag
+	 *
+	 * @var boolean
+	 */
 	private $is_admin = false;
 
+	/**
+	 * internal user data array
+	 *
+	 * @var array
+	 */
 	private $user_data = null;
 
+	/**
+	 * logger interface
+	 *
+	 * @var FroxlorLogger
+	 */
 	private $logger = null;
 
+	/**
+	 * mail interface
+	 *
+	 * @var PHPMailer
+	 */
 	private $mail = null;
 
+	/**
+	 * array of parameters passed to the command
+	 *
+	 * @var array
+	 */
 	private $cmd_params = null;
 
+	/**
+	 *
+	 * @param array $header
+	 *        	optional, passed via API
+	 * @param array $params
+	 *        	optional, array of parameters (var=>value) for the command
+	 * @param array $userinfo
+	 *        	optional, passed via WebInterface (instead of $header)
+	 *        	
+	 * @throws Exception
+	 */
 	public function __construct($header = null, $params = null, $userinfo = null)
 	{
 		global $lng;
@@ -38,6 +94,10 @@ abstract class ApiCommand
 		}
 	}
 
+	/**
+	 * initialize global $lng variable to have
+	 * localized strings available for the ApiCommands
+	 */
 	private function initLang()
 	{
 		global $lng;
@@ -77,6 +137,9 @@ abstract class ApiCommand
 		include_once makeSecurePath(FROXLOR_INSTALL_DIR . '/lng/lng_references.php');
 	}
 
+	/**
+	 * initialize mail interface so an API wide mail-object is available
+	 */
 	private function initMail()
 	{
 		/**
@@ -108,6 +171,18 @@ abstract class ApiCommand
 		}
 	}
 
+	/**
+	 * returns an instance of the wanted ApiCommand (e.g.
+	 * Customers, Domains, etc);
+	 * this is used widely in the WebInterface
+	 *
+	 * @param array $userinfo
+	 *        	array of user-data
+	 * @param array $params
+	 *        	array of parameters for the command
+	 *        	
+	 * @return ApiCommand
+	 */
 	public static function getLocal($userinfo = null, $params = null)
 	{
 		return new static(null, $params, $userinfo);
@@ -276,6 +351,15 @@ abstract class ApiCommand
 		return $this->mail;
 	}
 
+	/**
+	 * return api-compatible response in JSON format and send corresponding http-header
+	 *
+	 * @param int $status
+	 * @param string $status_message
+	 * @param mixed $data
+	 *
+	 * @return string json-encoded response message
+	 */
 	protected function response($status, $status_message, $data = null)
 	{
 		header("HTTP/1.1 " . $status);
@@ -288,6 +372,15 @@ abstract class ApiCommand
 		return $json_response;
 	}
 
+	/**
+	 * read user data from database by api-request-header fields
+	 *
+	 * @param array $header
+	 *        	api-request header
+	 *        	
+	 * @throws Exception
+	 * @return boolean
+	 */
 	private function readUserData($header = null)
 	{
 		$sel_stmt = Database::prepare("SELECT * FROM `api_keys` WHERE `apikey` = :ak AND `secret` = :as");

lib/classes/api/api_includes.inc.php

@@ -1,4 +1,20 @@
 <?php
+
+/**
+ * This file is part of the Froxlor project.
+ * Copyright (c) 2010 the Froxlor Team (see authors).
+ *
+ * For the full copyright and license information, please view the COPYING
+ * file that was distributed with this source code. You can also view the
+ * COPYING file online at http://files.froxlor.org/misc/COPYING.txt
+ *
+ * @copyright  (c) the authors
+ * @author     Froxlor team <team@froxlor.org> (2010-)
+ * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
+ * @package    API
+ * @since      0.10.0
+ *
+ */
 if (! defined('FROXLOR_INSTALL_DIR')) {
 	define('FROXLOR_INSTALL_DIR', dirname(dirname(dirname(__DIR__))));
 	require_once FROXLOR_INSTALL_DIR . '/lib/tables.inc.php';

lib/classes/api/commands/class.Admins.php

@@ -11,7 +11,8 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class Admins extends ApiCommand implements ResourceEntity

lib/classes/api/commands/class.Customers.php

@@ -11,7 +11,8 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class Customers extends ApiCommand implements ResourceEntity
@@ -724,7 +725,32 @@ class Customers extends ApiCommand implements ResourceEntity
 			if (Settings::Get('ticket.enabled') != '1') {
 				$tickets = - 1;
 			}
-			
+
+			$diskspace = $diskspace * 1024;
+			$traffic = $traffic * 1024 * 1024;
+
+			if (((($this->getUserDetail('diskspace_used') + $diskspace - $result['diskspace']) > $this->getUserDetail('diskspace')) && ($this->getUserDetail('diskspace') / 1024) != '-1')
+				|| ((($this->getUserDetail('mysqls_used') + $mysqls - $result['mysqls']) > $this->getUserDetail('mysqls')) && $this->getUserDetail('mysqls') != '-1')
+				|| ((($this->getUserDetail('emails_used') + $emails - $result['emails']) > $this->getUserDetail('emails')) && $this->getUserDetail('emails') != '-1')
+				|| ((($this->getUserDetail('email_accounts_used') + $email_accounts - $result['email_accounts']) > $this->getUserDetail('email_accounts')) && $this->getUserDetail('email_accounts') != '-1')
+				|| ((($this->getUserDetail('email_forwarders_used') + $email_forwarders - $result['email_forwarders']) > $this->getUserDetail('email_forwarders')) && $this->getUserDetail('email_forwarders') != '-1')
+				|| ((($this->getUserDetail('email_quota_used') + $email_quota - $result['email_quota']) > $this->getUserDetail('email_quota')) && $this->getUserDetail('email_quota') != '-1' && Settings::Get('system.mail_quota_enabled') == '1')
+				|| ((($this->getUserDetail('ftps_used') + $ftps - $result['ftps']) > $this->getUserDetail('ftps')) && $this->getUserDetail('ftps') != '-1')
+				|| ((($this->getUserDetail('tickets_used') + $tickets - $result['tickets']) > $this->getUserDetail('tickets')) && $this->getUserDetail('tickets') != '-1')
+				|| ((($this->getUserDetail('subdomains_used') + $subdomains - $result['subdomains']) > $this->getUserDetail('subdomains')) && $this->getUserDetail('subdomains') != '-1')
+				|| (($diskspace / 1024) == '-1' && ($this->getUserDetail('diskspace') / 1024) != '-1')
+				|| ($mysqls == '-1' && $this->getUserDetail('mysqls') != '-1')
+				|| ($emails == '-1' && $this->getUserDetail('emails') != '-1')
+				|| ($email_accounts == '-1' && $this->getUserDetail('email_accounts') != '-1')
+				|| ($email_forwarders == '-1' && $this->getUserDetail('email_forwarders') != '-1')
+				|| ($email_quota == '-1' && $this->getUserDetail('email_quota') != '-1' && Settings::Get('system.mail_quota_enabled') == '1')
+				|| ($ftps == '-1' && $this->getUserDetail('ftps') != '-1')
+				|| ($tickets == '-1' && $this->getUserDetail('tickets') != '-1')
+				|| ($subdomains == '-1' && $this->getUserDetail('subdomains') != '-1')
+			) {
+				standard_error('youcantallocatemorethanyouhave', '', true);
+			}
+
 			// Either $name and $firstname or the $company must be inserted
 			if ($name == '' && $company == '') {
 				standard_error(array(

lib/classes/api/commands/class.Domains.php

@@ -11,7 +11,8 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class Domains extends ApiCommand implements ResourceEntity
@@ -759,14 +760,22 @@ class Domains extends ApiCommand implements ResourceEntity
 		if ($this->isAdmin() && $this->getUserDetail('change_serversettings')) {
 			
 			// parameters
-			$id = $this->getParam('id');
+			$id = $this->getParam('id', true, 0);
-			
+			$dn_optional = ($id <= 0 ? false : true);
+			$domainname = $this->getParam('domainname', $dn_optional, '');
+
+			if ($id <= 0 && empty($domainname)) {
+				throw new Exception("Either 'id' or 'domainname' parameter must be given", 406);
+			}
+
 			// get requested domain
 			$json_result = Domains::getLocal($this->getUserData(), array(
 				'id' => $id,
+				'domainname' => $domainname,
 				'no_std_subdomain' => true
 			))->get();
 			$result = json_decode($json_result, true)['data'];
+			$id = $result['id'];
 			
 			// optional parameters
 			$p_domain = $this->getParam('domain', true, $result['domain']);

lib/classes/api/commands/class.FpmDaemons.php

@@ -11,14 +11,15 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class FpmDaemons extends ApiCommand implements ResourceEntity
 {
 
 	/**
-	 * lists all php-config entries
+	 * lists all fpm-daemon entries
 	 *
 	 * @return array count|list
 	 */
@@ -66,6 +67,13 @@ class FpmDaemons extends ApiCommand implements ResourceEntity
 		throw new Exception("Not allowed to execute given command.", 403);
 	}
 
+	/**
+	 * return a fpm-daemon entry by id
+	 *
+	 * @param int $id fpm-daemon-id
+	 *
+	 * @return array
+	 */
 	public function get()
 	{
 		if ($this->isAdmin()) {
@@ -238,6 +246,14 @@ class FpmDaemons extends ApiCommand implements ResourceEntity
 		throw new Exception("Not allowed to execute given command.", 403);
 	}
 
+	/**
+	 * delete a fpm-daemon entry by id
+	 *
+	 * @param int $id fpm-daemon-id
+	 *
+	 * @throws Exception
+	 * @return array
+	 */
 	public function delete()
 	{
 		if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) {

lib/classes/api/commands/class.Froxlor.php

@@ -11,12 +11,19 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class Froxlor extends ApiCommand
 {
 
+	/**
+	 * checks whether there is a newer version of froxlor available
+	 * 
+	 * @throws Exception
+	 * @return string
+	 */
 	public function checkUpdate()
 	{
 		global $version, $branding;

lib/classes/api/commands/class.IpsAndPorts.php

@@ -11,7 +11,8 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class IpsAndPorts extends ApiCommand implements ResourceEntity

lib/classes/api/commands/class.PhpSettings.php

@@ -11,7 +11,8 @@
  * @copyright  (c) the authors
  * @author     Froxlor team <team@froxlor.org> (2010-)
  * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
- * @package    Panel
+ * @package    API
+ * @since      0.10.0
  *
  */
 class PhpSettings extends ApiCommand implements ResourceEntity
@@ -100,6 +101,13 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 		throw new Exception("Not allowed to execute given command.", 403);
 	}
 
+	/**
+	 * return a php-config entry by id
+	 * 
+	 * @param int $id php-settings-id
+	 * 
+	 * @return array
+	 */
 	public function get()
 	{
 		if ($this->isAdmin()) {
@@ -320,6 +328,14 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 		throw new Exception("Not allowed to execute given command.", 403);
 	}
 
+	/**
+	 * delete a php-config entry by id
+	 *
+	 * @param int $id php-config-id
+	 *
+	 * @throws Exception
+	 * @return array
+	 */
 	public function delete()
 	{
 		if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) {

lib/classes/api/interface.ResourceEntity.php

@@ -1,5 +1,20 @@
 <?php
 
+/**
+ * This file is part of the Froxlor project.
+ * Copyright (c) 2010 the Froxlor Team (see authors).
+ *
+ * For the full copyright and license information, please view the COPYING
+ * file that was distributed with this source code. You can also view the
+ * COPYING file online at http://files.froxlor.org/misc/COPYING.txt
+ *
+ * @copyright  (c) the authors
+ * @author     Froxlor team <team@froxlor.org> (2010-)
+ * @license    GPLv2 http://files.froxlor.org/misc/COPYING.txt
+ * @package    API
+ * @since      0.10.0
+ *
+ */
 interface ResourceEntity
 {