mirror of
https://github.com/postfixadmin/postfixadmin.git
synced 2026-11-20 23:43:26 +03:00
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.
315 lines
11 KiB
Markdown
315 lines
11 KiB
Markdown
# 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()`
|