# Handler Classes - Developer Guide This document explains how Handler classes work in PostfixAdmin, and how to create new ones. ## Overview Handler classes extend `PFAHandler` and provide a standardised way to manage database entities. Once a Handler is created, it automatically works with: - `list.php` - list/search view - `edit.php` - create/edit form - `delete.php` - deletion - `editactive.php` - toggle active status - CLI via `postfixadmin-cli` Existing examples: `DkimHandler`, `FetchmailHandler`, `MailboxHandler`, `AliasHandler`, `DomainHandler`, `AdminHandler`. ## Creating a Handler ### 1. File and Class Naming The class name must match the URL parameter: `list.php?table=foo` loads `FooHandler` from `model/FooHandler.php`. Note that only the first letter is capitalised: - `table=dkim` -> `DkimHandler` - `table=aliasdomain` -> `AliasdomainHandler` The class autoloader scans `model/` via the `classmap` in `composer.json`. ### 2. Required Properties ```php class FooHandler extends PFAHandler { protected string $db_table = 'foo'; // database table name protected string $id_field = 'id'; // primary key column protected string $label_field = 'name'; // column used as display label protected ?string $domain_field = 'domain'; // column containing domain (or '' if none) protected string $order_by = 'name'; // ORDER BY clause } ``` If the table has no domain column, set `$domain_field = ''` and override `no_domain_field()`: ```php protected function no_domain_field() { // Prevent the default die() - handle domain filtering yourself $this->allowed_domains = []; } ``` ### 3. Non-admin user access If the Handler should be accessible to non-admin users (via `users/`), set `$user_field` to the column that identifies the owning user: ```php protected ?string $user_field = 'username'; ``` Also add `user_hardcoded_field` to `webformConfig()` (see below). If `$user_field` is empty and a user (non-admin) tries to access the Handler, the default `no_user_field()` will call `die()`. ### 4. Field Definitions - initStruct() The `initStruct()` method is used to define the fields that will be rendered in the list / edit forms. Generally these will map onto database fields, but you can create virtual fields if necessary. ```php protected function initStruct() { $this->struct = [ 'id' => self::pacol($allow_editing, $display_in_form, $display_in_list, $type, $PALANG_label, $PALANG_desc, $default, $options, $multiopt), // other fields here... ]; } ``` #### pacol() parameters | Parameter | Type | Description | |---------------------|------|------------------------------------------------------------------------------------------------------------------------| | `$allow_editing` | int | 1 = editable, 0 = read-only | | `$display_in_form` | int | 1 = show in edit form, 0 = hide | | `$display_in_list` | int | 1 = show in list view, 0 = hide | | `$type` | string | Field type (see below) | | `$PALANG_label` | string | Language key for the field label | | `$PALANG_desc` | string | Language key for the help/description text | | `$default` | mixed | Default value | | `$options` | array | Options for `enum`/`list` types | | `$not_in_db` | int | 1 - not in db, 0 - in db. (LEGACY: named array for additional options to this function) | | `$dont_write_to_db` | int | Do not write field into DB | | `$select` | string | Custom SQL expression replacing the column name in SELECT, see e.g. AdminHandler's domain_count definition for example | | `$extrafrom` | string | SQL fragment added after FROM (for JOINs) | | `$linkto` | string | Make the value a link (`%s` replaced with ID) | **Field types:** | Type | Description | |------|-------------| | `text` | Text input | | `mail` | Email address (treated as text unless handler adds `_validate_*`) | | `pass` | Password (hashed via `pacrypt()` before storage) | | `b64p` | Base64-encoded password | | `num` | Numeric | | `bool` | Boolean (converted to database-specific boolean) | | `enum` | Dropdown from `$options` array | | `list` | Multi-select list | | `txta` | Textarea | | `txtl` | Text, displayed as list in list view | | `ts` | Timestamp (auto-formatted per locale) | | `vnum` | Virtual numeric (not stored in DB) | | `vtxt` | Virtual text (not stored in DB) | | `quot` | Quota display | | `totp` | Read-only TOTP action in account edit forms; the handler returns a boolean and the template renders it | This list covers the most common types. Additional types may exist in `PFAHandler` and individual Handler classes — check the source for the full set. ### 5. Messages - initMsg() This allows you to override the default messages PostfixAdmin will use when various errors occur, replace PALANG_key with an actual key from a language file, e.g alias_domain_already_exists ```php protected function initMsg() { $this->msg['error_already_exists'] = 'PALANG_key'; $this->msg['error_does_not_exist'] = 'PALANG_key'; $this->msg['confirm_delete'] = 'PALANG_key'; if ($this->new) { $this->msg['logname'] = 'create_foo'; $this->msg['store_error'] = 'PALANG_error_key'; $this->msg['successmessage'] = 'PALANG_success_key'; } else { $this->msg['logname'] = 'edit_foo'; $this->msg['store_error'] = 'PALANG_error_key'; $this->msg['successmessage'] = 'PALANG_success_key'; } } ``` ### 6. Form/List Configuration - webformConfig() Controls how `list.php` and `edit.php` render the Handler: ```php public function webformConfig() { return array( 'formtitle_create' => 'PALANG_create_title', 'formtitle_edit' => 'PALANG_edit_title', 'create_button' => 'PALANG_create_button', 'required_role' => 'admin', // 'admin' or 'global-admin' 'listview' => 'list.php?table=foo', // redirect target after edit 'early_init' => 0, // 1 = call init() before set() 'user_hardcoded_field' => 'username', // required if users can access ); } ``` The `user_hardcoded_field` must be set (non-empty) for `list.php` / `edit.php` / `delete.php` to allow user-mode access. It names the field that identifies the owning user, but note that the web entry points only check that this key is non-empty — they do not automatically set the field value. User scoping for SELECT queries is handled by `PFAHandler::$user_field`, and write enforcement must be done in the Handler itself (e.g. via `_validate_*` or `preSave()`). ### 7. Auto-increment IDs If your table uses auto-increment for the primary key: ```php protected function validate_new_id() { if ($this->id != '') { $this->errormsg[$this->id_field] = 'auto_increment value, you must pass an empty string!'; return false; } return true; } ``` ### 8. Field Validation Create methods named `_validate_FIELDNAME()` for custom validation: ```php protected function _validate_ip(string $field, string $value): bool { if (!filter_var($value, FILTER_VALIDATE_IP)) { $this->errormsg[$field] = Config::Lang('invalid_ip'); return false; } return true; } ``` These are called automatically by `PFAHandler::set()` when processing input. `TotpexceptionHandler::set()` additionally requires `password_current` for the acting account on every creation or edit. The generic editor submits this as `value[password_current]`. The password is not persisted, and a later `set()` call requires confirmation again. `TotpPf::addException()` shares the same password check while retaining its existing signature and persistence/hooks. Mailbox users do not select a target: the handler always uses their acting username, even when a different target is submitted. ### 9. Hooks: preSave() and postSave() Override these to add logic before/after database writes: ```php protected function preSave(): bool { // Modify $this->values before save // Return false to abort return true; } protected function postSave(): bool { // Run after a successful save (e.g. hook scripts) return true; } ``` ### 10. Custom delete() Override to add permission checks or post-delete actions: ```php public function delete() { if (!$this->view()) { $this->errormsg[] = Config::Lang($this->msg['error_does_not_exist']); return false; } // Custom permission checks using $this->result db_delete($this->db_table, $this->id_field, $this->id); db_log($this->domain, 'delete_foo', $this->id); $this->infomsg[] = Config::Lang_f('pDelete_delete_success', $this->result['label']); return true; } ``` ### 11. Post-processing Results Override `read_from_db_postprocess()` to filter or modify results after they are read from the database: ```php protected function read_from_db_postprocess($db_result) { // Filter, modify, or augment results return $db_result; } ``` This is preferred over overriding `read_from_db()` directly. ## Key Internal Variables | Variable | Description | |----------|-------------| | `$this->id` | Current item ID (set by `init()`) | | `$this->new` | 1 = create mode, 0 = edit mode | | `$this->values` | Validated values (set by `set()`) | | `$this->result` | Current item data (set by `view()`) | | `$this->is_admin` | 1 = admin/superadmin, 0 = user | | `$this->is_superadmin` | 1 = global admin, 0 = regular admin or user | | `$this->admin_username` | Admin username (empty for users) | | `$this->username` | Username (set in user mode) | | `$this->allowed_domains` | Domains this admin can manage | | `$this->domain` | Domain of current item | | `$this->struct` | Field structure definitions | ## Menu Integration Add URL mappings to `configs/menu.conf`: ```ini # admin menu url_foo = list.php?table=foo url_foo_new = edit.php?table=foo # user menu (note the ../ prefix for accessing public/ from public/users/) url_user_foo = ../list.php?table=foo ``` Then reference them in templates using `{#url_foo#}`. ## Lifecycle 1. `list.php`/`edit.php` instantiates the Handler: `new FooHandler($new, $username, $is_admin)` 2. Constructor calls `initStruct()`, `initMsg()`, sets up `$allowed_domains` 3. For edit: `init($id)` loads the item, `set($values)` validates input, `save()` writes to DB 4. `save()` calls `preSave()`, does the INSERT/UPDATE, then calls `postSave()` 5. For list: `getList($condition)` calls `build_select_query()` -> `read_from_db()` -> `read_from_db_postprocess()`