add description field to panel_domains and mail_virtual table, API parameter 'description' for Domains.add()/Domains.update() and Email.add()/Emails.update(); fixes #910

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

install/froxlor.sql

@@ -71,6 +71,7 @@ CREATE TABLE `mail_virtual` (
   `customerid` int(11) NOT NULL default '0',
   `popaccountid` int(11) NOT NULL default '0',
   `iscatchall` tinyint(1) unsigned NOT NULL default '0',
+  `description` varchar(255) NOT NULL DEFAULT '',
   PRIMARY KEY  (`id`),
   KEY `email` (`email`)
 ) ENGINE=InnoDB CHARSET=utf8 COLLATE=utf8_general_ci;
@@ -275,6 +276,7 @@ CREATE TABLE `panel_domains` (
   `ssl_enabled` tinyint(1) DEFAULT '1',
   `ssl_honorcipherorder` tinyint(1) DEFAULT '0',
   `ssl_sessiontickets` tinyint(1) DEFAULT '1',
+  `description` varchar(255) NOT NULL DEFAULT '',
   PRIMARY KEY  (`id`),
   KEY `customerid` (`customerid`),
   KEY `parentdomain` (`parentdomainid`),
@@ -710,7 +712,7 @@ opcache.interned_strings_buffer'),
 	('panel', 'customer_hide_options', ''),
 	('panel', 'is_configured', '0'),
 	('panel', 'version', '0.10.24'),
-	('panel', 'db_version', '202102200');
+	('panel', 'db_version', '202103030');
 
 
 DROP TABLE IF EXISTS `panel_tasks`;

install/updates/froxlor/0.10/update_0.10.inc.php

@@ -734,3 +734,13 @@ if (\Froxlor\Froxlor::isDatabaseVersion('202101200')) {
 
 	\Froxlor\Froxlor::updateToDbVersion('202102200');
 }
+
+if (\Froxlor\Froxlor::isDatabaseVersion('202102200')) {
+
+	showUpdateStep("Add new description fields to mail and domain table", true);
+	Database::query("ALTER TABLE panel_domains ADD `description` varchar(255) NOT NULL DEFAULT '' AFTER `ssl_sessiontickets`;");
+	Database::query("ALTER TABLE mail_virtual ADD `description` varchar(255) NOT NULL DEFAULT '' AFTER `iscatchall`");
+	lastStepStatus(0);
+
+	\Froxlor\Froxlor::updateToDbVersion('202103030');
+}

lib/Froxlor/Api/Commands/Domains.php

@@ -288,6 +288,8 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 	 *        	optional list of allowed/used ssl/tls ciphers, see system.ssl_cipher_list setting, only used/required if $override_tls is true, default empty or system.ssl_cipher_list setting if $override_tls is true
 	 * @param string $tlsv13_cipher_list
 	 *        	optional list of allowed/used tls-1.3 specific ciphers, see system.tlsv13_cipher_list setting, only used/required if $override_tls is true, default empty or system.tlsv13_cipher_list setting if $override_tls is true
+	 * @param string $description
+	 *        	optional custom description (currently not used/shown in the frontend), default empty
 	 *        	
 	 * @access admin
 	 * @throws \Exception
@@ -354,6 +356,7 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 						$tlsv13_cipher_list = $this->getParam('tlsv13_cipher_list', true, Settings::Get('system.tlsv13_cipher_list'));
 					}
 				}
+				$description = $this->getParam('description', true, '');
 
 				// validation
 				$p_domain = strtolower($p_domain);
@@ -728,7 +731,8 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 						'tlsv13_cipher_list' => $tlsv13_cipher_list,
 						'sslenabled' => $sslenabled,
 						'honorcipherorder' => $honorcipherorder,
-						'sessiontickets' => $sessiontickets
+						'sessiontickets' => $sessiontickets,
+						'description' => $description
 					);
 
 					$ins_stmt = Database::prepare("
@@ -780,7 +784,8 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 						`tlsv13_cipher_list` = :tlsv13_cipher_list,
 						`ssl_enabled` = :sslenabled,
 						`ssl_honorcipherorder` = :honorcipherorder,
-						`ssl_sessiontickets`= :sessiontickets
+						`ssl_sessiontickets` = :sessiontickets,
+						`description` = :description
 					");
 					Database::pexecute($ins_stmt, $ins_data, true, true);
 					$domainid = Database::lastInsertId();
@@ -932,6 +937,8 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 	 *        	optional whether to honor the (server) cipher order for this domain. default 0 (false), requires SSL
 	 * @param bool $sessiontickets
 	 *        	optional whether to enable or disable TLS sessiontickets (RFC 5077) for this domain. default 1 (true), requires SSL
+	 * @param string $description
+	 *        	optional custom description (currently not used/shown in the frontend), default empty
 	 *        	
 	 * @access admin
 	 * @throws \Exception
@@ -1027,6 +1034,7 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 				$ssl_cipher_list = $result['ssl_cipher_list'];
 				$tlsv13_cipher_list = $result['tlsv13_cipher_list'];
 			}
+			$description = $this->getParam('description', true, $result['description']);
 
 			// count subdomain usage of source-domain
 			$subdomains_stmt = Database::prepare("
@@ -1589,6 +1597,7 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 			$update_data['sslenabled'] = $sslenabled;
 			$update_data['honorcipherorder'] = $honorcipherorder;
 			$update_data['sessiontickets'] = $sessiontickets;
+			$update_data['description'] = $description;
 			$update_data['id'] = $id;
 
 			$update_stmt = Database::prepare("
@@ -1634,7 +1643,8 @@ class Domains extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEn
 				`tlsv13_cipher_list` = :tlsv13_cipher_list,
 				`ssl_enabled` = :sslenabled,
 				`ssl_honorcipherorder` = :honorcipherorder,
-				`ssl_sessiontickets` = :sessiontickets
+				`ssl_sessiontickets` = :sessiontickets,
+				`description` = :description
 				WHERE `id` = :id
 			");
 			Database::pexecute($update_stmt, $update_data, true, true);

lib/Froxlor/Api/Commands/Emails.php

@@ -35,6 +35,8 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 	 *        	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)
+	 * @param string $description
+	 *        	optional custom description (currently not used/shown in the frontend), default empty
 	 *        	
 	 * @access admin, customer
 	 * @throws \Exception
@@ -54,6 +56,7 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 
 			// parameters
 			$iscatchall = $this->getBoolParam('iscatchall', true, 0);
+			$description = $this->getParam('description', true, '');
 
 			// validation
 			if (substr($domain, 0, 4) != 'xn--') {
@@ -121,14 +124,16 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 				`email` = :email,
 				`email_full` = :email_full,
 				`iscatchall` = :iscatchall,
-				`domainid` = :domainid
+				`domainid` = :domainid,
+				`description` = :description
 			");
 			$params = array(
 				"cid" => $customer['customerid'],
 				"email" => $email,
 				"email_full" => $email_full,
 				"iscatchall" => $iscatchall,
-				"domainid" => $domain_check['id']
+				"domainid" => $domain_check['id'],
+				"description" => $description
 			);
 			Database::pexecute($stmt, $params, true, true);
 
@@ -167,7 +172,7 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 		$customer_ids = $this->getAllowedCustomerIds('email');
 		$params['idea'] = ($id <= 0 ? $emailaddr : $id);
 
-		$result_stmt = Database::prepare("SELECT v.`id`, v.`email`, v.`email_full`, v.`iscatchall`, v.`destination`, v.`customerid`, v.`popaccountid`, v.`domainid`, u.`quota`
+		$result_stmt = Database::prepare("SELECT v.`id`, v.`email`, v.`email_full`, v.`iscatchall`, v.`destination`, v.`customerid`, v.`popaccountid`, v.`domainid`, v.`description`, u.`quota`
 			FROM `" . TABLE_MAIL_VIRTUAL . "` v
 			LEFT JOIN `" . TABLE_MAIL_USERS . "` u ON v.`popaccountid` = u.`id`
 			WHERE v.`customerid` IN (" . implode(", ", $customer_ids) . ")
@@ -195,6 +200,8 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 	 *        	optional, required when called as admin (if $customerid is not specified)
 	 * @param boolean $iscatchall
 	 *        	optional
+	 * @param string $description
+	 *        	optional custom description (currently not used/shown in the frontend), default empty
 	 *        	
 	 * @access admin, customer
 	 * @throws \Exception
@@ -227,6 +234,7 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 
 		// parameters
 		$iscatchall = $this->getBoolParam('iscatchall', true, $result['iscatchall']);
+		$description = $this->getParam('description', true, $result['description']);
 
 		// get needed customer info to reduce the email-address-counter by one
 		$customer = $this->getCustomerData();
@@ -256,12 +264,13 @@ class Emails extends \Froxlor\Api\ApiCommand implements \Froxlor\Api\ResourceEnt
 
 		$stmt = Database::prepare("
 			UPDATE `" . TABLE_MAIL_VIRTUAL . "`
-			SET `email` = :email , `iscatchall` = :caflag
+			SET `email` = :email , `iscatchall` = :caflag, `description` = :description
 			WHERE `customerid`= :cid AND `id`= :id
 		");
 		$params = array(
 			"email" => $email,
 			"caflag" => $iscatchall,
+			"description" => $description,
 			"cid" => $customer['customerid'],
 			"id" => $id
 		);

lib/Froxlor/Froxlor.php

@@ -10,7 +10,7 @@ final class Froxlor
 	const VERSION = '0.10.24';
 
 	// Database version (YYYYMMDDC where C is a daily counter)
-	const DBVERSION = '202102200';
+	const DBVERSION = '202103030';
 
 	// Distribution branding-tag (used for Debian etc.)
 	const BRANDING = '';

tests/Domains/DomainsTest.php

@@ -32,13 +32,15 @@ class DomainsTest extends TestCase
 			'ssl_protocols' => array(
 				'TLSv1.2',
 				'TLSv1.3'
-			)
+			),
+			'description' => 'awesome domain'
 		];
 		$json_result = Domains::getLocal($admin_userdata, $data)->add();
 		$result = json_decode($json_result, true)['data'];
 		$this->assertEquals($customer_userdata['documentroot'] . 'test.local/', $result['documentroot']);
 		$this->assertTrue(in_array('TLSv1.3', explode(",", $result['ssl_protocols'])));
 		$this->assertEquals('0', $result['isemaildomain']);
+		$this->assertEquals('awesome domain', $result['description']);
 	}
 
 	/**
@@ -207,7 +209,8 @@ class DomainsTest extends TestCase
 			'domainname' => 'test.local',
 			'email_only' => 1,
 			'override_tls' => 0,
-			'documentroot' => 'web'
+			'documentroot' => 'web',
+			'description' => 'changed desc'
 		];
 		$json_result = Domains::getLocal($admin_userdata, $data)->update();
 		$result = json_decode($json_result, true)['data'];
@@ -215,6 +218,7 @@ class DomainsTest extends TestCase
 		$this->assertFalse(in_array('TLSv1.3', explode(",", $result['ssl_protocols'])));
 		$this->assertEquals('test.local', $result['domain']);
 		$this->assertEquals($customer_userdata['documentroot'] . 'web/', $result['documentroot']);
+		$this->assertEquals('changed desc', $result['description']);
 	}
 
 	/**

tests/Emails/EmailsTest.php

@@ -36,12 +36,14 @@ class MailsTest extends TestCase
 
 		$data = [
 			'email_part' => 'info',
-			'domain' => 'test2.local'
+			'domain' => 'test2.local',
+			'description' => 'awesome email'
 		];
 		$json_result = Emails::getLocal($customer_userdata, $data)->add();
 		$result = json_decode($json_result, true)['data'];
 		$this->assertEquals("info@test2.local", $result['email_full']);
 		$this->assertEquals(0, $result['iscatchall']);
+		$this->assertEquals('awesome email', $result['description']);
 
 		// reset setting
 		Settings::Set('panel.customer_hide_options', '', true);
@@ -87,11 +89,13 @@ class MailsTest extends TestCase
 
 		$data = [
 			'emailaddr' => 'catchall@test2.local',
-			'iscatchall' => 1
+			'iscatchall' => 1,
+			'description' => 'now with catchall'
 		];
 		$json_result = Emails::getLocal($customer_userdata, $data)->update();
 		$result = json_decode($json_result, true)['data'];
 		$this->assertEquals(1, $result['iscatchall']);
+		$this->assertEquals('now with catchall', $result['description']);
 	}
 
 	public function testCustomerEmailForwardersAdd()