From 232cee9d5ff0b1e450862f6064ba323af966052d Mon Sep 17 00:00:00 2001 From: Christian Boltz Date: Sun, 6 May 2012 20:01:32 +0000 Subject: [PATCH] PFAHandler: - make PFAHandler an "abstract class" - add functions that must be implemented by every *Handler class as abstract functions: - abstract protected function initStruct(); - abstract protected function initMsg(); - abstract public function webformConfig(); - abstract protected function validate_new_id(); - lots of additional comments AdminHandler, AliasdomainHandler, DomainHandler, MailboxHandler: - remove comments that are now in PFAHandler git-svn-id: https://svn.code.sf.net/p/postfixadmin/code/trunk@1385 a1433add-5e2c-0410-b055-b7f2511e0802 --- model/AdminHandler.php | 17 ------- model/AliasdomainHandler.php | 6 --- model/DomainHandler.php | 14 ------ model/MailboxHandler.php | 6 --- model/PFAHandler.php | 87 ++++++++++++++++++++++++++++++++---- 5 files changed, 79 insertions(+), 51 deletions(-) diff --git a/model/AdminHandler.php b/model/AdminHandler.php index a8fb5d64..c37edf10 100644 --- a/model/AdminHandler.php +++ b/model/AdminHandler.php @@ -26,17 +26,6 @@ class AdminHandler extends PFAHandler { # TODO: shorter PALANG labels ;-) # TODO: hardcode 'default' to Config::read in pacol()? - # values for the "type" column: - # text one line of text - # pass password (will be encrypted with pacrypt()) - # num number - # txtl text "list" - array of one line texts - # vnum "virtual" number, coming from JOINs etc. - # bool boolean (converted to 0/1, additional column _$field with yes/no) - # ts timestamp (created/modified) - # enum list of options, must be given in column "options" as array - # list like enum, but allow multiple selections - # NOTE: There are dependencies between domains and domain_count # NOTE: If you disable "display in list" for domain_count, the SQL query for domains might break. # NOTE: (Disabling both shouldn't be a problem.) @@ -84,9 +73,6 @@ class AdminHandler extends PFAHandler { ); } - # messages used in various functions. - # always list the key to hand over to Lang::read - # the only exception is 'logname' which uses the key for db_log protected function initMsg() { $this->msg['error_already_exists'] = 'pAdminCreate_admin_username_text_error2'; # TODO: better error message $this->msg['error_does_not_exist'] = 'pAdminEdit_admin_result_error'; # TODO: better error message @@ -99,9 +85,6 @@ class AdminHandler extends PFAHandler { } } - /* - * Configuration for the web interface - */ public function webformConfig() { if ($this->new) { $successmsg = 'pAdminCreate_admin_result_success'; diff --git a/model/AliasdomainHandler.php b/model/AliasdomainHandler.php index d7d8257f..72942d3f 100644 --- a/model/AliasdomainHandler.php +++ b/model/AliasdomainHandler.php @@ -63,9 +63,6 @@ class AliasdomainHandler extends PFAHandler { return $success; } - # messages used in various functions. - # always list the key to hand over to Lang::read - # the only exception is 'logname' which uses the key for db_log protected function initMsg() { $this->msg['error_already_exists'] = 'pCreate_alias_domain_error2'; # TODO: better error message $this->msg['error_does_not_exist'] = 'pCreate_alias_domain_error2'; # TODO: better error message @@ -78,9 +75,6 @@ class AliasdomainHandler extends PFAHandler { } } - /* - * Configuration for the web interface - */ public function webformConfig() { return array( # $PALANG labels diff --git a/model/DomainHandler.php b/model/DomainHandler.php index 81d7cbbc..557dae4a 100644 --- a/model/DomainHandler.php +++ b/model/DomainHandler.php @@ -31,14 +31,6 @@ class DomainHandler extends PFAHandler { $quota = boolconf('quota') ? 1 : 0; # TOOD: use a function or write a Config::intbool function $dom_q = boolconf('domain_quota') ? 1 : 0; # TOOD: use a function or write a Config::intbool function - # values for the "type" column: - # text one line of text - # num number - # vnum "virtual" number, coming from JOINs etc. - # bool boolean (converted to 0/1, additional column _$field with yes/no) - # ts timestamp (created/modified) - # enum list of options, must be given in column "options" as array - # NOTE: There are dependencies between alias_count, mailbox_count and total_quota. # NOTE: If you disable "display in list" for one of them, the SQL query for the others might break. # NOTE: (Disabling all of them shouldn't be a problem.) @@ -78,9 +70,6 @@ class DomainHandler extends PFAHandler { ); } - # messages used in various functions. - # always list the key to hand over to Lang::read - # the only exception is 'logname' which uses the key for db_log protected function initMsg() { $this->msg['error_already_exists'] = 'pAdminCreate_domain_domain_text_error'; $this->msg['error_does_not_exist'] = 'domain_does_not_exist'; @@ -93,9 +82,6 @@ class DomainHandler extends PFAHandler { } } - /* - * Configuration for the web interface - */ public function webformConfig() { return array( # $PALANG labels diff --git a/model/MailboxHandler.php b/model/MailboxHandler.php index 5c18b63c..6364a629 100644 --- a/model/MailboxHandler.php +++ b/model/MailboxHandler.php @@ -40,9 +40,6 @@ class MailboxHandler extends PFAHandler { ); } - # messages used in various functions. - # always list the key to hand over to Lang::read - # the only exception is 'logname' which uses the key for db_log protected function initMsg() { $this->msg['error_already_exists'] = 'pCreate_mailbox_username_text_error2'; $this->msg['error_does_not_exist'] = 'pCreate_mailbox_username_text_error1'; @@ -55,9 +52,6 @@ class MailboxHandler extends PFAHandler { } } - /* - * Configuration for the web interface - */ public function webformConfig() { if ($this->new) { # the webform will display a local_part field + domain dropdown on $new $this->struct['username']['display_in_form'] = 0; diff --git a/model/PFAHandler.php b/model/PFAHandler.php index 42fab7e6..3eaf24dd 100644 --- a/model/PFAHandler.php +++ b/model/PFAHandler.php @@ -1,5 +1,5 @@ new = 1; @@ -97,10 +98,55 @@ class PFAHandler { $this->initMsg(); } + /** + * ensure a lazy programmer can't give access to all items accidently + * + * to intentionally disable the check if $this->domain_field is empty, override this function + */ protected function no_domain_field() { if ($this->admin_username != "") die('Attemp to restrict domains without setting $this->domain_field!'); } + /** + * init $this->struct (an array of pacol() results) + * see pacol() in functions.inc.php for all available parameters + * + * available values for the "type" column: + * text one line of text + * pass password (will be encrypted with pacrypt()) + * num number + * txtl text "list" - array of one line texts + * vnum "virtual" number, coming from JOINs etc. + * bool boolean (converted to 0/1, additional column _$field with yes/no) + * ts timestamp (created/modified) + * enum list of options, must be given in column "options" as array + * list like enum, but allow multiple selections + * You can use custom types, but you'll have to add handling for them in *Handler and the smarty templates + * + */ + abstract protected function initStruct(); + + /** + * init $this->msg[] with messages used in various functions. + * + * always list the key to hand over to Lang::read + * the only exception is 'logname' which uses the key for db_log + * + * The values can depend on $this->new + * TODO: use separate keys edit_* and new_* and choose the needed message at runtime + */ + abstract protected function initMsg(); + + /** + * returns an array with some labels and settings for the web interface + * can also change $this->struct to something that makes the web interface better + * (for example, it can make local_part and domain editable as separate fields + * so that users can choose the domain from a dropdown) + * + * @return array + */ + abstract public function webformConfig(); + /** * initialize with $id and check if it is valid * @param string $id @@ -130,7 +176,13 @@ class PFAHandler { } } - + /** + * on $new, check if the ID is valid (for example, check if it is a valid mail address syntax-wise) + * called by init() + * @return boolean true/false + * must also set $this->errormsg[$this->id_field] if ID is invalid + */ + abstract protected function validate_new_id(); /** * set and verify values @@ -184,6 +236,7 @@ class PFAHandler { } # validate based on field name (_field_$fieldname) + # TODO: rename to _validate_$key ? $func="_field_".$key; if (method_exists($this, $func) ) { if (!$this->{$func}($key, $values[$key])) $valid = false; @@ -194,7 +247,7 @@ class PFAHandler { } } } elseif ($this->new) { # new, field not set in input data - $this->errormsg[] = "field $key is missing"; + $this->errormsg[] = "field $key is missing"; # TODO: make translateable # TODO: use $this->errormsg[$key] ? # echo "MISSING / not set: $key\n"; } else { # edit, field unchanged # echo "skipped / not set: $key\n"; @@ -221,8 +274,11 @@ class PFAHandler { /** * store $this->values in the database + * + * converts values based on $this->struct[*][type] (boolean, password encryption) + * * calls $this->storemore() where additional things can be done - * @return bool - true if all values are valid, otherwise false + * @return bool - true if all values were stored in the database, otherwise false * error messages (if any) are stored in $this->errormsg */ public function store() { @@ -275,7 +331,14 @@ class PFAHandler { /** * read_from_db + * + * reads all fields specified in $this->struct from the database + * and auto-converts them to database-independent values based on the field type (see $colformat) + * + * calls $this->read_from_db_postprocess() to postprocess the result + * * @param array or string - condition (an array will be AND'ed using db_where_clause, a string will be directly used) + * (if you use a string, make sure it is correctly escaped!) * @param integer limit - maximum number of rows to return * @param integer offset - number of first row to return * @return array - rows (as associative array, with the ID as key) @@ -295,7 +358,9 @@ class PFAHandler { } $colformat = array( + # 'ts' fields are always returned as $formatted_date, and the raw value as _$field 'ts' => "$formatted_date AS ###KEY###, ###KEY### AS _###KEY###", + # 'bool' fields are always returned as 0/1, additonally _$field contains yes/no (already translated) 'bool' => "CASE ###KEY### WHEN '" . db_get_boolean(true) . "' THEN '1' WHEN '" . db_get_boolean(false) . "' THEN '0' END as ###KEY###," . "CASE ###KEY### WHEN '" . db_get_boolean(true) . "' THEN '$yes' WHEN '" . db_get_boolean(false) . "' THEN '$no' END as _###KEY###", ); @@ -328,6 +393,8 @@ class PFAHandler { } if ($this->domain_field != "") { + # TODO: wrap where clause in (...) to avoid problems if OR is used? + # TODO: Note: this would need a change in db_where_clause not to include the WHERE keyword in the result $where .= " AND " . db_in_clause($this->domain_field, $this->allowed_domains); } @@ -352,6 +419,10 @@ class PFAHandler { return $db_result; } + /** + * allows to postprocess the database result + * called by read_from_db() + */ protected function read_from_db_postprocess($db_result) { return $db_result; } @@ -359,8 +430,8 @@ class PFAHandler { /** * get the values of an item - * @param array or string $condition - * @return bool - true if at least one item was found + * @param boolean (optional) - if false, $this->errormsg[] will not be filled in case of errors + * @return bool - true if item was found * The data is stored in $this->return (as associative array of column => value) * error messages (if any) are stored in $this->errormsg */ @@ -378,7 +449,7 @@ class PFAHandler { /** * get a list of one or more items with all values - * @param array or string $condition + * @param array or string $condition - see read_from_db for details * @param integer limit - maximum number of rows to return * @param integer offset - number of first row to return * @return bool - true if at least one item was found