Vexim Web Plugin Pdns Laravel Package

Getting Started

This is not a Laravel/Composer package — it is a PHP plugin for Vexim, the web UI for virtual mail domains, and it wires Vexim's domain lifecycle into a PowerDNS database backend. There is no service provider, no config/ publishing, and no facade. Plan to deploy it as files in your Vexim tree, not via composer require.

Minimal steps:

1. Confirm the PowerDNS backend is SQL-based (MySQL/MariaDB or PostgreSQL) using the standard domains / records schema. The plugin reads and writes those tables directly; it does not talk to the PowerDNS HTTP API or pdnsutil.
2. Copy the plugin into Vexim's plugin directory and enable it from Vexim's plugin configuration (per the repo README). Vexim's plugin loader discovers it by directory name.
3. Give Vexim DB credentials access to the PowerDNS database — same database or cross-database grants, depending on your setup.
4. Where to look first: the plugin's entry file (hook registration), then the zone/record-writing code. That is where parent-zone resolution and default record creation live, and it is the code you will touch most.
5. First use case: create a mail domain in Vexim and confirm that (a) a PowerDNS zone appears in domains, (b) the expected MX/SPF/A records appear in records, and (c) dig MX yourdomain.tld @your-ns returns them. This end-to-end check is the fastest way to validate credentials, schema assumptions, and caching.

Implementation Patterns

• Hook into Vexim's domain create/update/delete events. The plugin's job is to keep the PowerDNS zone in sync with Vexim's domain table. Treat Vexim as the source of truth for which domains exist, and PowerDNS as the source of truth for DNS content.
• Parent-zone-first resolution (new in v1.2.1). When creating records for a child domain (e.g. mail.example.com), the plugin now checks whether an authoritative parent zone (example.com) already exists and writes the record into that zone instead of creating a conflicting child zone. If you relied on the old behavior of always creating a separate zone per Vexim domain, audit your existing zones before upgrading.
• Template your default record sets. Most deployments want a predictable bundle on domain creation: A/AAAA for the mail host, MX, SPF/TXT, and a DKIM placeholder. Centralize this in one function so you can extend it without hunting through hook callbacks.
• Wrap writes in a transaction where the driver supports it, and roll back the PowerDNS changes if the Vexim domain insert fails. A half-created domain with a live zone is the most common operational mess this plugin can produce.
• Idempotency matters. Re-running domain creation (retries, imports, bulk provisioning scripts) should not duplicate records rows. The PowerDNS records table has no universal unique constraint across versions, so guard with an existence check before insert.
• Integrating from a Laravel app: treat this as an external system. Either (a) use a second Eloquent connection pointed at the PowerDNS database and mirror the plugin's logic in a job/command, or (b) shell out to a provisioning script. Do not expect to composer require this and call it from a controller — wrapping it is more work than reimplementing the two or three queries you actually need.
• Verify through the resolver, not the database. After every change, test with dig against the actual authoritative nameserver. Passing DB assertions with a stale PowerDNS cache is a classic false positive.

Gotchas and Tips

• No Laravel packaging. No config file, no .env keys, no migrations, no Artisan commands. Configuration is Vexim-side. Budget time for a thin wrapper if you need it inside a Laravel app.
• Upgrade note for v1.2.1: this is a targeted bug fix for authoritative parent zones on child-domain records. It is not a breaking change, but it does change which zone a record lands in. If you have child domains whose records were previously written to auto-created child zones, reconcile or delete those orphan zones after upgrading, or you will serve stale/duplicate answers.
• Direct DB writes require care with PowerDNS semantics. Zone names in domains.name are stored without a trailing dot; record names in records.name are stored with one (and @-style roots must be expanded). Getting this wrong produces zones that look fine in the DB but never resolve.
• PowerDNS caches aggressively. After manual fixes, run pdns_control purge (or restart) before concluding the plugin is broken. Debug the cache before debugging the code.
• Credential scope. Grant only SELECT/INSERT/UPDATE/DELETE on the PowerDNS database — not DDL. The plugin should never be in a position to alter the schema.
• DNSSEC is out of scope. If you enable DNSSEC on zones, the plugin's record changes can invalidate signatures. Either keep signed zones out of the plugin's reach or add a re-sign step to your provisioning flow.
• Debugging path: Vexim's PHP error log → the PowerDNS DB rows → dig against the authoritative NS → PowerDNS log. In that order; most reported "plugin bugs" are permission or caching issues.
• Extension points are limited to the Vexim hook surface. For custom record templates, extra validation, or non-standard schemas, fork or add a wrapper rather than patching in place — this plugin has no plugin-of-a-plugin mechanism and future upstream changes will conflict with local edits.
• Pin your version. Given the small maintainer surface, track the exact tag you deployed in your runbook so the next release note (like this one) can be evaluated against a known state.