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>

actions/admin/settings/120.system.php

@@ -79,6 +79,14 @@ return array(
 					'save_method' => 'storeSettingHostname',
 					'plausibility_check_method' => 'checkHostname',
 					),
+				'api_enabled' => array(
+					'label' => $lng['serversettings']['enable_api'],
+					'settinggroup' => 'api',
+					'varname' => 'enabled',
+					'type' => 'bool',
+					'default' => false,
+					'save_method' => 'storeSettingField',
+				),
 				'system_validatedomain' => array(
 					'label' => $lng['serversettings']['validate_domain'],
 					'settinggroup' => 'system',

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,6 +36,23 @@ 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();
@@ -80,16 +102,36 @@ class CustomerBackups extends ApiCommand implements ResourceEntity
 		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();
@@ -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

@@ -104,7 +104,8 @@ 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
@@ -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
@@ -288,9 +332,51 @@ 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()
@@ -441,7 +527,8 @@ 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

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()
+	{}
+
+
+}

lng/english.lng.php

@@ -2143,3 +2143,5 @@ $lng['apikeys']['allowed_from'] = 'Allowed from';
 $lng['apikeys']['allowed_from_help'] = 'Comma separated list of ip addresses. Default empty.';
 $lng['apikeys']['valid_until'] = 'Valid until';
 $lng['apikeys']['valid_until_help'] = 'Date until valid, format YYYY-MM-DD';
+$lng['serversettings']['enable_api']['title'] = 'Enable external API usage';
+$lng['serversettings']['enable_api']['description'] = 'In order to use the froxlor API you need to activate this option. For more detailed information see <a href="https://api.froxlor.org/" target="_new">https://api.froxlor.org/</a>';

lng/german.lng.php

@@ -1791,3 +1791,5 @@ $lng['apikeys']['allowed_from'] = 'Erlaube Zugriff von';
 $lng['apikeys']['allowed_from_help'] = 'Komma getrennte Liste von IPs. Standard ist leer.';
 $lng['apikeys']['valid_until'] = 'Gültig bis';
 $lng['apikeys']['valid_until_help'] = 'Datum Gültigkeitsende, Format JJJJ-MM-TT';
+$lng['serversettings']['enable_api']['title'] = 'Aktiviere externe API Nutzung';
+$lng['serversettings']['enable_api']['description'] = 'Um die froxlor API nutzen zu können, muss diese Option aktiviert sein. Für detaillierte Informationen siehe <a href="https://api.froxlor.org/" target="_new">https://api.froxlor.org/</a>';

tests/bootstrap.php

@@ -13,7 +13,8 @@ $userdata_content = "<?php
 \$sql_root[0]['user'] = 'root';
 \$sql_root[0]['password'] = '$rpwd';
 \$sql_root[0]['host'] = 'localhost';
-\$sql_root[0]['caption'] = 'Test default';" . PHP_EOL;
+\$sql_root[0]['caption'] = 'Test default';
+\$sql['debug'] = true;" . PHP_EOL;
 
 $userdata = dirname(__DIR__) . '/lib/userdata.inc.php';