add some more function-doc; add setting to enable/disable api in system-settings; added last three api-command classes (empty so far)

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

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

@@ -0,0 +1,36 @@
+<?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
+ *
+ */
+class Cronjobs extends ApiCommand implements ResourceEntity
+{
+	public function add()
+	{}
+
+	public function get()
+	{}
+
+	public function update()
+	{}
+
+	public function listing()
+	{}
+
+	public function delete()
+	{}
+
+
+}

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

@@ -18,6 +18,11 @@
 class CustomerBackups extends ApiCommand implements ResourceEntity
 {
 
+	/**
+	 * check whether backup is enabled systemwide and if accessable for customer (hide_options)
+	 *
+	 * @throws Exception
+	 */
 	private function validateAccess()
 	{
 		if (Settings::Get('system.backupenabled') != 1) {
@@ -31,38 +36,55 @@ class CustomerBackups extends ApiCommand implements ResourceEntity
 		}
 	}
 
+	/**
+	 * add a new customer backup job
+	 *
+	 * @param string $path
+	 *        	path to store the backup to
+	 * @param bool $backup_dbs
+	 *        	optional whether to backup databases, default is 0 (false)
+	 * @param bool $backup_mail
+	 *        	optional whether to backup mail-data, default is 0 (false)
+	 * @param bool $backup_web
+	 *        	optional whether to backup web-data, default is 0 (false)
+	 * @param int $customerid
+	 *        	required when called as admin, not needed when called as customer
+	 *
+	 * @access admin, customer
+	 * @return array
+	 */
 	public function add()
 	{
 		$this->validateAccess();
-		
+
 		// required parameter
 		$path = $this->getParam('path');
-		
+
 		// parameter
 		$backup_dbs = $this->getParam('backup_dbs', true, 0);
 		$backup_mail = $this->getParam('backup_mail', true, 0);
 		$backup_web = $this->getParam('backup_web', true, 0);
-		
+
 		// get customer data
 		$customer = $this->getCustomerData();
-		
+
 		// validation
 		$path = makeCorrectDir(validate($path, 'path', '', '', array(), true));
 		$userpath = $path;
 		$path = makeCorrectDir($customer['documentroot'] . '/' . $path);
-		
+
 		if ($backup_dbs != '1') {
 			$backup_dbs = '0';
 		}
-		
+
 		if ($backup_mail != '1') {
 			$backup_mail = '0';
 		}
-		
+
 		if ($backup_web != '1') {
 			$backup_web = '0';
 		}
-		
+
 		$task_data = array(
 			'customerid' => $customer['customerid'],
 			'uid' => $customer['guid'],
@@ -75,27 +97,47 @@ class CustomerBackups extends ApiCommand implements ResourceEntity
 		);
 		// schedule backup job
 		inserttask('20', $task_data);
-		
+
 		$this->logger()->logAction($this->isAdmin() ? ADM_ACTION : USR_ACTION, LOG_NOTICE, "[API] added customer-backup job for '" . $customer['loginname'] . "'. Target directory: " . $userpath);
 		return $this->response(200, "successfull", $task_data);
 	}
 
+	/**
+	 * You cannot get a planned backup.
+	 * Try CustomerBackups.listing()
+	 */
 	public function get()
 	{
 		throw new Exception('You cannot get a planned backup. Try CustomerBackups.listing()', 303);
 	}
 
+	/**
+	 * You cannot update a planned backup.
+	 * You need to delete it and re-add it.
+	 */
 	public function update()
 	{
 		throw new Exception('You cannot update a planned backup. You need to delete it and re-add it.', 303);
 	}
 
+	/**
+	 * list all planned backup-jobs, if called from an admin, list all planned backup-jobs of all customers you are allowed to view, or specify id or loginname for one specific customer
+	 *
+	 * @param int $customerid
+	 *        	optional, admin-only, select backup-jobs of a specific customer by id
+	 * @param string $loginname
+	 *        	optional, admin-only, select backup-jobs of a specific customer by loginname
+	 *
+	 * @access admin, customer
+	 * @throws Exception
+	 * @return array count|list
+	 */
 	public function listing()
 	{
 		$this->validateAccess();
-		
+
 		$customer_ids = $this->getAllowedCustomerIds('extras.backup');
-		
+
 		// check whether there is a backup-job for this customer
 		$sel_stmt = Database::prepare("SELECT * FROM `" . TABLE_PANEL_TASKS . "` WHERE `type` = '20'");
 		Database::pexecute($sel_stmt);
@@ -113,6 +155,20 @@ class CustomerBackups extends ApiCommand implements ResourceEntity
 		));
 	}
 
+	/**
+	 * delete a planned backup-jobs by id, if called from an admin you need to specify the customerid/loginname
+	 *
+	 * @param int $backup_job_entry
+	 *        	id of backup job
+	 * @param int $customerid
+	 *        	optional, required when called as admin (if $loginname is not specified)
+	 * @param string $loginname
+	 *        	optional, required when called as admin (if $customerid is not specified)
+	 *
+	 * @access admin, customer
+	 * @throws Exception
+	 * @return bool
+	 */
 	public function delete()
 	{
 		// get planned backups

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

@@ -0,0 +1,36 @@
+<?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
+ *
+ */
+class HostingPlans extends ApiCommand implements ResourceEntity
+{
+	public function add()
+	{}
+
+	public function get()
+	{}
+
+	public function update()
+	{}
+
+	public function listing()
+	{}
+
+	public function delete()
+	{}
+
+
+}

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

@@ -29,29 +29,29 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	{
 		if ($this->isAdmin()) {
 			$this->logger()->logAction(ADM_ACTION, LOG_NOTICE, "[API] list php-configs");
-			
+
 			$result = Database::query("
 				SELECT c.*, fd.description as fpmdesc
 				FROM `" . TABLE_PANEL_PHPCONFIGS . "` c
 				LEFT JOIN `" . TABLE_PANEL_FPMDAEMONS . "` fd ON fd.id = c.fpmsettingid
 				ORDER BY c.description ASC
 			");
-			
+
 			$phpconfigs = array();
 			while ($row = $result->fetch(PDO::FETCH_ASSOC)) {
 				$query_params = array(
 					'id' => $row['id']
 				);
-				
+
 				$query = "SELECT * FROM `" . TABLE_PANEL_DOMAINS . "`
 					WHERE `phpsettingid` = :id
 					AND `parentdomainid` = '0'";
-				
+
 				if ((int) $this->getUserDetail('domains_see_all') == 0) {
 					$query .= " AND `adminid` = :adminid";
 					$query_params['adminid'] = $this->getUserDetail('adminid');
 				}
-				
+
 				if ((int) Settings::Get('panel.phpconfigs_hidestdsubdomain') == 1) {
 					$ssdids_res = Database::query("
 					SELECT DISTINCT `standardsubdomain` FROM `" . TABLE_PANEL_CUSTOMERS . "`
@@ -64,35 +64,35 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 						$query .= " AND `id` NOT IN (" . implode(', ', $ssdids) . ")";
 					}
 				}
-				
+
 				$domains = array();
 				$domainresult_stmt = Database::prepare($query);
 				Database::pexecute($domainresult_stmt, $query_params, true, true);
-				
+
 				if (Database::num_rows() > 0) {
 					while ($row2 = $domainresult_stmt->fetch(PDO::FETCH_ASSOC)) {
 						$domains[] = $row2['domain'];
 					}
 				}
-				
+
 				// check whether we use that config as froxor-vhost config
 				if (Settings::Get('system.mod_fcgid_defaultini_ownvhost') == $row['id'] || Settings::Get('phpfpm.vhost_defaultini') == $row['id']) {
 					$domains[] = Settings::Get('system.hostname');
 				}
-				
+
 				if (empty($domains)) {
 					$domains[] = $this->lng['admin']['phpsettings']['notused'];
 				}
-				
+
 				// check whether this is our default config
 				if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini') == $row['id']) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.defaultini') == $row['id'])) {
 					$row['is_default'] = true;
 				}
-				
+
 				$row['domains'] = $domains;
 				$phpconfigs[] = $row;
 			}
-			
+
 			return $this->response(200, "successfull", array(
 				'count' => count($phpconfigs),
 				'list' => $phpconfigs
@@ -103,9 +103,10 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 
 	/**
 	 * return a php-setting entry by id
-	 * 
-	 * @param int $id php-settings-id
-	 * 
+	 *
+	 * @param int $id
+	 *        	php-settings-id
+	 *        	
 	 * @access admin
 	 * @throws Exception
 	 * @return array
@@ -114,7 +115,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	{
 		if ($this->isAdmin()) {
 			$id = $this->getParam('id');
-			
+
 			$result_stmt = Database::prepare("
 				SELECT * FROM `" . TABLE_PANEL_PHPCONFIGS . "` WHERE `id` = :id
 			");
@@ -132,6 +133,49 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	/**
 	 * add new php-settings entry
 	 *
+	 * @param string $description
+	 *        	description of the php-config
+	 * @param string $phpsettings
+	 *        	the actual ini-settings
+	 * @param string $binary
+	 *        	optional the binary to php-cgi if FCGID is used
+	 * @param string $file_extensions
+	 *        	optional allowed php-file-extensions if FCGID is used, default is 'php'
+	 * @param int $mod_fcgid_starter
+	 *        	optional number of fcgid-starters if FCGID is used, default is -1
+	 * @param int $mod_fcgid_maxrequests
+	 *        	optional number of fcgid-maxrequests if FCGID is used, default is -1
+	 * @param string $mod_fcgid_umask
+	 *        	optional umask if FCGID is used, default is '022'
+	 * @param int $fpmconfig
+	 *        	optional id of the fpm-daemon-config if FPM is used
+	 * @param bool $phpfpm_enable_slowlog
+	 *        	optional whether to write a slowlog or not if FPM is used, default is 0 (false)
+	 * @param string $phpfpm_reqtermtimeout
+	 *        	optional request terminate timeout if FPM is used, default is '60s'
+	 * @param string $phpfpm_reqslowtimeout
+	 *        	optional request slowlog timeout if FPM is used, default is '5s'
+	 * @param bool $phpfpm_pass_authorizationheader
+	 *        	optional whether to pass authorization header to webserver if FPM is used, default is 0 (false)
+	 * @param bool $override_fpmconfig
+	 *        	optional whether to override fpm-daemon-config value for the following settings if FPM is used, default is 0 (false)
+	 * @param string $pm
+	 *        	optional process-manager to use if FPM is used (allowed values are 'static', 'dynamic' and 'ondemand'), default is fpm-daemon-value
+	 * @param int $max_children
+	 *        	optional number of max children if FPM is used, default is the fpm-daemon-value
+	 * @param int $start_server
+	 *        	optional number of servers to start if FPM is used, default is fpm-daemon-value
+	 * @param int $min_spare_servers
+	 *        	optional number of minimum spare servers if FPM is used, default is fpm-daemon-value
+	 * @param int $max_spare_servers
+	 *        	optional number of maximum spare servers if FPM is used, default is fpm-daemon-value
+	 * @param int $max_requests
+	 *        	optional number of maximum requests if FPM is used, default is fpm-daemon-value
+	 * @param int $idle_timeout
+	 *        	optional number of seconds for idle-timeout if FPM is used, default is fpm-daemon-value
+	 * @param string $limit_extensions
+	 *        	optional limitation of php-file-extensions if FPM is used, default is fpm-daemon-value
+	 *        	
 	 * @access admin
 	 * @throws Exception
 	 * @return array
@@ -139,18 +183,18 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	public function add()
 	{
 		if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) {
-			
+
 			// required parameter
 			$description = $this->getParam('description');
 			$phpsettings = $this->getParam('phpsettings');
-			
+
 			if (Settings::Get('system.mod_fcgid') == 1) {
 				$binary = $this->getParam('binary');
 				$fpm_config_id = 1;
 			} elseif (Settings::Get('phpfpm.enabled') == 1) {
 				$fpm_config_id = intval($this->getParam('fpmconfig'));
 			}
-			
+
 			// parameters
 			$file_extensions = $this->getParam('file_extensions', true, 'php');
 			$mod_fcgid_starter = $this->getParam('mod_fcgid_starter', true, - 1);
@@ -160,7 +204,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 			$fpm_reqtermtimeout = $this->getParam('phpfpm_reqtermtimeout', true, "60s");
 			$fpm_reqslowtimeout = $this->getParam('phpfpm_reqslowtimeout', true, "5s");
 			$fpm_pass_authorizationheader = $this->getParam('phpfpm_pass_authorizationheader', true, 0);
-			
+
 			$override_fpmconfig = $this->getParam('override_fpmconfig', true, 0);
 			$def_fpmconfig = $this->apiCall('FpmDaemons.get', array(
 				'id' => $fpm_config_id
@@ -218,11 +262,11 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 				$mod_fcgid_maxrequests = 0;
 				$mod_fcgid_umask = "022";
 			}
-			
+
 			if (strlen($description) == 0 || strlen($description) > 50) {
 				standard_error('descriptioninvalid', '', true);
 			}
-			
+
 			$ins_stmt = Database::prepare("
 				INSERT INTO `" . TABLE_PANEL_PHPCONFIGS . "` SET
 				`description` = :desc,
@@ -272,7 +316,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 			);
 			Database::pexecute($ins_stmt, $ins_data, true, true);
 			$ins_data['id'] = Database::lastInsertId();
-			
+
 			inserttask('1');
 			$this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting with description '" . $description . "' has been created by '" . $this->getUserDetail('loginname') . "'");
 
@@ -288,22 +332,64 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	 * update a php-setting entry by given id
 	 *
 	 * @param int $id
+	 * @param string $description
+	 *        	description of the php-config
+	 * @param string $phpsettings
+	 *        	the actual ini-settings
+	 * @param string $binary
+	 *        	optional the binary to php-cgi if FCGID is used
+	 * @param string $file_extensions
+	 *        	optional allowed php-file-extensions if FCGID is used, default is 'php'
+	 * @param int $mod_fcgid_starter
+	 *        	optional number of fcgid-starters if FCGID is used, default is -1
+	 * @param int $mod_fcgid_maxrequests
+	 *        	optional number of fcgid-maxrequests if FCGID is used, default is -1
+	 * @param string $mod_fcgid_umask
+	 *        	optional umask if FCGID is used, default is '022'
+	 * @param int $fpmconfig
+	 *        	optional id of the fpm-daemon-config if FPM is used
+	 * @param bool $phpfpm_enable_slowlog
+	 *        	optional whether to write a slowlog or not if FPM is used, default is 0 (false)
+	 * @param string $phpfpm_reqtermtimeout
+	 *        	optional request terminate timeout if FPM is used, default is '60s'
+	 * @param string $phpfpm_reqslowtimeout
+	 *        	optional request slowlog timeout if FPM is used, default is '5s'
+	 * @param bool $phpfpm_pass_authorizationheader
+	 *        	optional whether to pass authorization header to webserver if FPM is used, default is 0 (false)
+	 * @param bool $override_fpmconfig
+	 *        	optional whether to override fpm-daemon-config value for the following settings if FPM is used, default is 0 (false)
+	 * @param string $pm
+	 *        	optional process-manager to use if FPM is used (allowed values are 'static', 'dynamic' and 'ondemand'), default is fpm-daemon-value
+	 * @param int $max_children
+	 *        	optional number of max children if FPM is used, default is the fpm-daemon-value
+	 * @param int $start_server
+	 *        	optional number of servers to start if FPM is used, default is fpm-daemon-value
+	 * @param int $min_spare_servers
+	 *        	optional number of minimum spare servers if FPM is used, default is fpm-daemon-value
+	 * @param int $max_spare_servers
+	 *        	optional number of maximum spare servers if FPM is used, default is fpm-daemon-value
+	 * @param int $max_requests
+	 *        	optional number of maximum requests if FPM is used, default is fpm-daemon-value
+	 * @param int $idle_timeout
+	 *        	optional number of seconds for idle-timeout if FPM is used, default is fpm-daemon-value
+	 * @param string $limit_extensions
+	 *        	optional limitation of php-file-extensions if FPM is used, default is fpm-daemon-value
 	 *
 	 * @access admin
-	 * @throws Exception::
+	 * @throws Exception
 	 * @return array
 	 */
 	public function update()
 	{
 		if ($this->isAdmin() && $this->getUserDetail('change_serversettings') == 1) {
-			
+
 			// required parameter
 			$id = $this->getParam('id');
 
 			$result = $this->apiCall('PhpSettings.get', array(
 				'id' => $id
 			));
-			
+
 			// parameters
 			$description = $this->getParam('description', true, $result['description']);
 			$phpsettings = $this->getParam('phpsettings', true, $result['phpsettings']);
@@ -371,11 +457,11 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 				$mod_fcgid_maxrequests = 0;
 				$mod_fcgid_umask = "022";
 			}
-			
+
 			if (strlen($description) == 0 || strlen($description) > 50) {
 				standard_error('descriptioninvalid', '', true);
 			}
-			
+
 			$upd_stmt = Database::prepare("
 				UPDATE `" . TABLE_PANEL_PHPCONFIGS . "` SET
 				`description` = :desc,
@@ -426,7 +512,7 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 				'id' => $id
 			);
 			Database::pexecute($upd_stmt, $upd_data, true, true);
-			
+
 			inserttask('1');
 			$this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting with description '" . $description . "' has been updated by '" . $this->getUserDetail('loginname') . "'");
 
@@ -441,8 +527,9 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 	/**
 	 * delete a php-setting entry by id
 	 *
-	 * @param int $id php-settings-id
-	 *
+	 * @param int $id
+	 *        	php-settings-id
+	 *        	
 	 * @access admin
 	 * @throws Exception
 	 * @return array
@@ -455,15 +542,15 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 			$result = $this->apiCall('PhpSettings.get', array(
 				'id' => $id
 			));
-			
+
 			if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini_ownvhost') == $id) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.vhost_defaultini') == $id)) {
 				standard_error('cannotdeletehostnamephpconfig', '', true);
 			}
-			
+
 			if ((Settings::Get('system.mod_fcgid') == '1' && Settings::Get('system.mod_fcgid_defaultini') == $id) || (Settings::Get('phpfpm.enabled') == '1' && Settings::Get('phpfpm.defaultini') == $id)) {
 				standard_error('cannotdeletedefaultphpconfig', '', true);
 			}
-			
+
 			// set php-config to default for all domains using the
 			// config that is to be deleted
 			$upd_stmt = Database::prepare("
@@ -473,14 +560,14 @@ class PhpSettings extends ApiCommand implements ResourceEntity
 			Database::pexecute($upd_stmt, array(
 				'id' => $id
 			), true, true);
-			
+
 			$del_stmt = Database::prepare("
 				DELETE FROM `" . TABLE_PANEL_PHPCONFIGS . "` WHERE `id` = :id
 			");
 			Database::pexecute($del_stmt, array(
 				'id' => $id
 			), true, true);
-			
+
 			inserttask('1');
 			$this->logger()->logAction(ADM_ACTION, LOG_INFO, "[API] php setting '" . $result['description'] . "' has been deleted by '" . $this->getUserDetail('loginname') . "'");
 			return $this->response(200, "successfull", $result);

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

@@ -0,0 +1,36 @@
+<?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
+ *
+ */
+class Traffic extends ApiCommand implements ResourceEntity
+{
+	public function add()
+	{}
+
+	public function get()
+	{}
+
+	public function update()
+	{}
+
+	public function listing()
+	{}
+
+	public function delete()
+	{}
+
+
+}