As suggested by @cboltz in #1188 (comment) and #1188 (comment), move TOTP action HTML out of both AdminHandler and MailboxHandler into a shared Smarty partial.
11 KiB
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 viewedit.php- create/edit formdelete.php- deletioneditactive.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->DkimHandlertable=aliasdomain->AliasdomainHandler
The class autoloader scans model/ via the classmap in composer.json.
2. Required Properties
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():
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:
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.
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
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:
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:
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:
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:
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:
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:
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:
# 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
list.php/edit.phpinstantiates the Handler:new FooHandler($new, $username, $is_admin)- Constructor calls
initStruct(),initMsg(), sets up$allowed_domains - For edit:
init($id)loads the item,set($values)validates input,save()writes to DB save()callspreSave(), does the INSERT/UPDATE, then callspostSave()- For list:
getList($condition)callsbuild_select_query()->read_from_db()->read_from_db_postprocess()