Files
Rodrigo Cortés Cano 748e3ea121 Refactor account TOTP action rendering and status queries (#1198)
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.
2026-11-18 13:05:39 +00:00

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 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

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

  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()