As discussed in #1068. Adds `DOCUMENTS/CUSTOM_FIELDS.md`, a start-to-finish walkthrough for adding a custom field to a built-in entity using the `*_struct_hook` callbacks, no core patching required.
9.4 KiB
Custom Fields with *_struct_hook
This is a walkthrough for adding your own field to one of PostfixAdmin's
built-in entities (domains, mailboxes, aliases, admins, and so on) without
patching any PostfixAdmin code. It uses the *_struct_hook config callbacks,
which let you add, change, or remove fields on a Handler's $struct at runtime.
The handy part is that the Handler builds both its SQL and its edit form
straight from $struct, so a field you bolt on through the hook gets full add,
edit, and list support in the web UI without any extra work. It also gets picked
up automatically by postfixadmin-cli, so the same field is manageable from the
command line, not just the browser.
The worked example below adds a per-domain x_backend_host field and then wires
it into Postfix (transport_maps) and Dovecot (proxy). The end result is a
front-end PostfixAdmin box that routes each domain to whichever downstream
server actually holds its mailboxes. The same recipe works for any custom
field, so if you only care about the UI part, jump to
Just the field and stop there.
How the hook works
When a Handler is constructed it reads a config key named after its primary
database table plus _struct_hook. If that key names a real function, the
Handler runs $struct through it (see model/PFAHandler.php):
$struct_hook = Config::read($this->db_table . '_struct_hook');
if (!empty($struct_hook) && is_string($struct_hook) && $struct_hook != 'NO' && function_exists($struct_hook)) {
$this->struct = $struct_hook($this->struct);
}
There's one hook per Handler. The config keys all live (empty by default) in
config.inc.php:
| Config key | Entity / table |
|---|---|
admin_struct_hook |
admins |
domain_struct_hook |
domains |
alias_struct_hook |
aliases |
mailbox_struct_hook |
mailboxes |
alias_domain_struct_hook |
alias domains |
fetchmail_struct_hook |
fetchmail |
dkim_struct_hook |
DKIM keys |
dkim_signing_struct_hook |
DKIM signing |
Your hook is just a function that takes $struct and returns it back, modified.
Don't forget to return it.
Two things to know before you start
- The hook doesn't touch the database. Adding a field to
$structtells PostfixAdmin how to handle the column, but it won't create it for you. You add the column yourself withALTER TABLE. - Prefix your custom columns with
x_so they don't collide with anything a future PostfixAdmin release might add. That's why the example below usesx_backend_hostrather than a barebackend_host, and the samex_rule applies to any custom$PALANGstrings you add (see Step 2). The full naming policy is in Naming policy for custom fields and tables at the end of this page.
Step 1: add the database column
ALTER TABLE domain ADD COLUMN x_backend_host VARCHAR(255) NULL DEFAULT 'backend1.example.com';
Step 2: surface the field with a hook
Put this in config.local.php rather than config.inc.php, so an upgrade
won't wipe it out. Point the config key at a function and define that function.
The tidiest way to build the column definition is PFAHandler::pacol(), since
that's how the core defines its own fields. Using PHP 8's named arguments keeps
it readable, so you're not left counting positional parameters:
$CONF['domain_struct_hook'] = 'domain_struct_hook';
function domain_struct_hook($struct) {
$struct['x_backend_host'] = PFAHandler::pacol(
allow_editing: 1,
display_in_form: 1,
display_in_list: 1,
type: 'text',
PALANG_label: 'x_backend_host', // a $PALANG key, not literal text
PALANG_desc: 'x_backend_host_desc', // ditto
default: 'backend1.example.com',
);
return $struct;
}
PALANG_label and PALANG_desc are language keys, not the visible text.
PostfixAdmin looks them up in $PALANG (the interface-strings array), so define
your own strings with a language hook, again prefixing the keys with x_:
$CONF['language_hook'] = 'my_language_hook';
function my_language_hook($PALANG, $language) {
// Set the strings for every language. Add `case "de":` etc. before the
// default if you want translations. Just make sure the keys exist in
// every branch (including default) so they're never missing.
$PALANG['x_backend_host'] = 'Backend Host';
$PALANG['x_backend_host_desc'] = 'Downstream mail server that hosts this domain';
return $PALANG;
}
(If you'd rather not bother with $PALANG, passing literal text as the label
still renders (PostfixAdmin shows the key as-is when it isn't found), but the
language hook is the clean, translatable way and keeps you consistent with core.)
The full pacol() parameter list (allow_editing, display_in_form,
display_in_list, type, PALANG_label, PALANG_desc, default, options, and the
rest) is over in HANDLER_CLASSES.md.
The same trick works for tweaking or hiding existing fields, for example
$struct['transport']['display_in_form'] = 0;.
And that's the whole UI part. The create/edit form now shows a Backend Host box and writes whatever you type back to the column.
Heads up on the list view: the edit form updates itself from
$structautomatically, but if you're using the virtual list templates and want the new column to show up in the list too, you may also have to add it to the matching list template. There's a note about this above the*_struct_hookblock inconfig.inc.php.
Just the field (minimal recipe)
If all you wanted was a custom column in the UI, Steps 1 and 2 are the whole job. Everything past here is specific to the front-end mail-routing case.
Step 3: route Postfix mail to the backend
Point transport_maps at a query that turns the stored hostname into a Postfix
transport on the fly:
# /etc/postfix/mysql/transport_domains.cf
query = SELECT CONCAT('smtp:[', x_backend_host, ']:25') FROM domain WHERE domain='%s' AND active=1
The square brackets tell Postfix to skip the MX lookup and hand the mail straight to that host.
Step 4: proxy Dovecot logins to the same backend
Reuse the exact same hostname as Dovecot's proxy target in your passdb and
userdb SQL. Now an IMAP or POP login that lands on the front end gets proxied
to the backend that actually owns the mailbox:
# dovecot-sql.conf.ext
password_query = \
SELECT m.username AS user, m.password, 'y' AS proxy, d.x_backend_host AS host \
FROM mailbox m JOIN domain d ON m.domain = d.domain \
WHERE m.username = '%{user}' AND m.active = 1 AND d.active = 1
Why a separate column instead of transport?
Fair question, since PostfixAdmin already ships a transport column and you can
absolutely drive Postfix routing from it. The reason this example uses a
separate x_backend_host is that the same value gets reused as Dovecot's proxy
host, and transport stores a full smtp:[host]:port string that Dovecot
can't swallow as-is. Keeping a plain hostname in its own column means both
Postfix and Dovecot read it directly, with no string-slicing on the Dovecot
side. If you only need the Postfix routing and don't care about Dovecot, then
reusing transport (maybe with a bit of SQL CONCAT/SUBSTRING to reshape it)
works just as well.
Naming policy for custom fields and tables
Custom fields and tables must be named so they never collide with fields, tables, or indexes a future PostfixAdmin version might add.
Extra fields in existing tables:
- Use a field name starting with
x_. - If you add indexes, prefix them
x_too (ortablename_x_on PostgreSQL). - Avoid unique indexes and foreign keys where you can, since they make schema changes harder.
Extra tables:
- Use a table name starting with
x_. - Inside that table, name fields and indexes however you like.
- Consider including
created,modified, andactivecolumns (most PostfixAdmin tables have them). - Unique keys inside your own tables are fine.
- On PostgreSQL, index and unique-key names must start with
x_(better:x_tablename_). - Avoid foreign keys to PostfixAdmin's default tables where possible.
A note for MySQL/MariaDB users: the x_ prefix on index and key names is
mainly a PostgreSQL requirement. PostgreSQL keeps those names unique per schema
(database-wide), so a custom index there could clash with a core one.
MySQL/MariaDB scope index names per table, so inside your own x_ table any
index name is fine. (Indexes you add to an existing PostfixAdmin table are
still best x_-prefixed on any database, since you're sharing that table's
namespace.) The column- and table-name x_ rules apply everywhere regardless.
This is the policy from PostfixAdmin's custom-fields wiki page, reproduced here so it lives in the repo.
The short version
*_struct_hooklets you add, change, or drop Handler fields from config alone. No core edits, no fork.- Add the DB column yourself. The hook only handles it, it doesn't create it.
- Prefix your custom columns (and any custom
$PALANGkeys) withx_, per the naming policy. - Define field labels/descriptions as
$PALANGstrings via$CONF['language_hook'], rather than hardcoding text. - One plain-hostname column can feed both Postfix
transport_mapsand Dovecot proxying, which is exactly what you want for a front-end/back-end mail setup.