Appearance
Developer Events Reference
NXForms dispatches Joomla events at key points, so your plugins can observe and change its behaviour without changing NXForms. Every event listed here is part of the public contract; events that aren't listed are internal and may change without notice. Events marked Requires: NXForms Pro fire only when NXForms Pro is installed and enabled.
How to listen
Use a Joomla plugin that implements Joomla\Event\SubscriberInterface and registers its listeners through getSubscribedEvents(). The plugin must be installed and enabled for Joomla to call these listeners. Example skeleton:
php
<?php
declare(strict_types=1);
namespace MyVendor\Plugin\System\NxformsHooks\Extension;
defined('_JEXEC') or die;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\Event;
use Joomla\Event\SubscriberInterface;
final class NxformsHooks extends CMSPlugin implements SubscriberInterface
{
public static function getSubscribedEvents(): array
{
return [
'onNxFormsBeforeEmailSent' => 'prefixSubject',
'onNxFormsAfterSubmission' => 'recordSubmission',
];
}
public function prefixSubject(Event $event): void
{
$message = $event['message'];
$message['subject'] = '[Form] ' . $message['subject'];
$event['message'] = $message;
}
public function recordSubmission(Event $event): void
{
// Informational: observe only the data needed for your integration.
}
}Event types
- Filter: listener can mutate the payload. Read the value via
$event['key'], mutate locally, write back via$event['key'] = $newValue. The component re-reads the event immediately after dispatch and uses the mutated value. - Informational: listener observes only. Mutations are ignored (or undefined behaviour). Use these for audit logging, metrics, outbound notifications.
Stability guarantees
- Event names are stable across minor releases.
- Payload keys may be added in minor releases. Listeners must not assume the payload is the exact set of keys documented today.
- Existing payload keys, types, and semantics are stable across minor releases. Breaking changes are reserved for major versions and called out in the changelog.
- Filter events specify exactly which keys the component reads back after dispatch; mutating other keys is a no-op.
Submission lifecycle (site-side)
Events fired while a submission is processed, in this order.
onNxFormsBeforeSubmission
Type: Informational
Fires: after the token, honeypot and minimum-time checks pass, and after onNxFormsFilterSubmissionRequest. Payload:
php
[
'formId' => int, // form being submitted
'form' => array<string,mixed>, // full form definition
'request' => array<string,mixed>, // raw incoming request data
'context' => array<string,mixed>, // ip_address, user_agent, files, ...
]Use cases: audit logging, request-counting, early metrics.
onNxFormsFilterSubmissionRequest
Type: Filter
Fires: before validation, after the token check.
Payload:
php
[
'value' => array<string,mixed>, // mutable: the request data
'formId' => int,
'form' => array<string,mixed>,
'context' => array<string,mixed>,
]Read back: $event['value'] (the mutated request data).
Use cases: rewrite incoming values before validation (translate field aliases, normalize phone numbers, drop legacy keys).
onNxFormsFilterMinSubmissionTime
Type: Filter (numeric)
Fires: when NXForms works out the minimum time between showing the form and accepting it, which keeps bots out.
Payload:
php
[
'value' => int, // mutable: minimum seconds (default 2)
'formId' => int,
'context' => array<string,mixed>,
]Read back: $event['value'] (the new threshold in seconds).
onNxFormsFilterRecaptchaScore
Type: Filter (numeric)
Fires: after Google returns the reCAPTCHA v3 score.
Payload:
php
[
'value' => float, // mutable: minimum acceptable score 0.0–1.0
'formId' => int,
]Use cases: lower the threshold for low-risk forms or raise it for high-spam pages.
onNxFormsFilterMaxUploadSize
Type: Filter (numeric)
Fires: for each uploaded file being checked.
Payload:
php
[
'value' => int, // mutable: max bytes
'field' => array<string,mixed>, // the field config
]onNxFormsFilterAllowedFileTypes
Type: Filter (array)
Fires: for each uploaded file being checked.
Payload:
php
[
'value' => array<string,string>, // mutable: list of allowed MIME types
'field' => array<string,mixed>,
]Note: the validator strips dangerous MIME types (executable, script) from the result regardless of what the listener returns. A warning is logged when a listener tries to allow a forbidden type.
onNxFormsFilterMaxImageDimension
Type: Filter (numeric)
Fires: for each uploaded image (image/* MIME types).
Payload:
php
[
'value' => int, // mutable: max width OR height in pixels (default 4096)
'field' => array<string,mixed>,
]onNxFormsFilterSanitizedSubmission
Type: Filter
Fires: after field validation and sanitisation, before the entry is stored.
Payload:
php
[
'value' => array<string,mixed>, // mutable: sanitised submission values
'formId' => int,
'form' => array<string,mixed>,
'context' => array<string,mixed>,
'field_meta' => array<int,array<string,mixed>>,
]Use cases: post-validation enrichment (geo-resolve IP into city, hash a value, etc.).
onNxFormsBeforeIntegrationDispatch (1.3+)
Type: Informational
Requires: NXForms Pro.
Fires: once per enabled integration, before it is sent or queued. Also fires once for the standalone webhook (integrationId = 'webhook') when enabled.
Payload:
php
[
'integrationId' => string, // 'webhook' | 'make' | 'mailchimp' | 'hubspot' | 'salesforce' | 'brevo' | ...
'settings' => array<string,mixed>,
'form' => array<string,mixed>,
'payload' => array<string,mixed>,
'context' => array<string,mixed>,
'field_meta' => array<int,array<string,mixed>>,
'mode' => string, // 'queued' | 'sync'
]Use cases: count outbound dispatch attempts, gate per-tenant throttling, observe before any side effect.
onNxFormsAfterIntegrationDispatch (1.3+)
Type: Informational
Requires: NXForms Pro.
Fires: on two paths, with the same payload:
- Sync path: after an integration that is sent right away returns or fails (joomla_article, user_registration, user_login, salesforce).
- Queued path: after each attempt of a queued integration: success, a failure that will be retried, or the final failure.
Payload:
php
[
'integrationId' => string,
'settings' => array<string,mixed>,
'form' => array<string,mixed>,
'payload' => array<string,mixed>,
'context' => array<string,mixed>,
'field_meta' => array<int,array<string,mixed>>,
'mode' => string, // 'sync' | 'queued'
'result' => string, // 'dispatched' | 'failed' | 'failed_will_retry' | 'requeued'
'error' => ?string, // exception message when result != 'dispatched'
]Result values:
dispatched: dispatcher returned without throwing.failed: terminal failure, queue ran out of retry attempts and dropped the job. Only fires on the queued path.failed_will_retry: transient failure, queue rescheduled the job with backoff. Only fires on the queued path.requeued: sync attempt threw, dispatcher catch-block enqueued for later retry. Only fires on the sync path.
Use cases: per-integration success/failure metrics, alerting on terminal failures, audit logging.
Not fired for: integrations without a registered dispatcher. Those emit the legacy onNxFormsIntegrationDispatch instead (see below).
onNxFormsIntegrationDispatch (legacy)
Type: Informational
Requires: NXForms Pro.
Fires: only when no dispatcher is registered for the integration id. Before 1.3 this was the only way to observe integration dispatch; it is kept for backwards compatibility.
Payload:
php
[
'integrationId' => string,
'settings' => array<string,mixed>,
'form' => array<string,mixed>,
'payload' => array<string,mixed>,
'context' => array<string,mixed>,
'field_meta' => array<int,array<string,mixed>>,
]For new code: use onNxFormsBeforeIntegrationDispatch instead.
onNxFormsBeforeEmailSent (1.3+)
Type: Filter
Fires: after the message is composed and before it is delivered, for both the notification to the site owner and the confirmation to the visitor; use email_kind to tell them apart.
Payload:
php
[
'form' => array<string,mixed>,
'submission' => array<string,mixed>,
'context' => array<string,mixed>,
'message' => array{
recipients:array<string>, subject:string, html:string,
text:string, from_name:string, from_email:string
}, // mutable
'reply_to' => ?string, // mutable; v1 string-only — see below
'email_kind' => 'notification' | 'submitter_confirmation',
]Read back: $event['message'] and $event['reply_to'].
Use cases: BCC injection, transactional template rerouting, per-tenant header tweaks, recipient overrides. Listeners that should only act on owner-facing notification mail (e.g. BCC the support team on every notification, but not on confirmation copies sent to the visitor) MUST branch on email_kind === 'notification' to avoid also intercepting the submitter-confirmation flow.
Not fired when: notifications are switched off for the form (send_email is false), or, for the confirmation, when it is switched off or the visitor's address is missing or invalid.
Reply-to resolution differs per kind:
email_kind === 'notification':- configured
email_reply_to - first valid email value found by scanning
field_meta(the implicit "reply to whoever submitted the form" fallback) context['submission_email']null
- configured
email_kind === 'submitter_confirmation':- configured
submitter_email.reply_to_emailonly - never field-scans, never falls back to the submitter's own email (that would loop replies back to the visitor — wrong semantic for a confirmation message)
- configured
reply_to is a bare email address or null.
onNxFormsAfterEmailSent (1.3+)
Type: Informational
Fires: after delivery, for both the notification and the visitor confirmation; use email_kind to tell them apart.
Payload:
php
[
'form' => array<string,mixed>,
'submission' => array<string,mixed>,
'context' => array<string,mixed>,
'message' => array<string,mixed>, // post-mutation, what was actually delivered
'reply_to' => ?string,
'result' => array{sent:bool, error?:?string},
'email_kind' => 'notification' | 'submitter_confirmation',
]Use cases: audit log of every email sent, metrics on send failures, retry counters. Same email_kind branching rule as the before event: listeners that audit only one direction of mail should filter on the discriminator.
onNxFormsAfterSubmission
Type: Informational
Fires: once when the form is sent, at the end of processing. For a form that takes payments, it fires when the form is sent, while the payment is still pending, and once more after the payment is confirmed. A listener that throws is logged and does not undo the stored entry. Payload:
php
[
'formId' => int,
'sanitised' => array<string,mixed>, // legacy values; may contain credentials
'sanitised_redacted' => array<string,mixed>, // use for logging and external consumers
'result' => array<string,mixed>, // success/uuid/message/etc
'form' => array<string,mixed>,
'context' => array<string,mixed>,
]Per-integration payload filters
These let plugins rewrite the JSON body of a specific outbound integration before it's serialised and sent. All have the same shape and behave identically; only the event name varies per service. They fire with NXForms Pro.
| Event | Vendor |
|---|---|
onNxFormsFilterWebhookPayload | Generic webhook + standalone |
onNxFormsFilterMailchimpPayload | Mailchimp |
onNxFormsFilterHubspotPayload | HubSpot |
onNxFormsFilterSalesforcePayload | Salesforce |
onNxFormsFilterBrevoPayload | Brevo |
Type: Filter
Payload:
php
[
'payload' => array<string,mixed>, // mutable: the JSON body
'form' => array<string,mixed>,
'submission' => array<string,mixed>,
'context' => array<string,mixed>,
'field_meta' => array<int,array<string,mixed>>,
]Read back: $event['payload'].
Use cases: per-vendor body customisation (extra Mailchimp tags from a custom field, HubSpot association mappings, Salesforce record-type overrides).
onNxFormsWebhookFailed
Type: Informational
Requires: NXForms Pro.
Fires: when the general webhook fails with a connection or HTTP error.
Payload:
php
[
'endpoint' => string, // REDACTED, webhook secrets are stripped
'integration' => string, // 'webhook'
'error' => string, // REDACTED message
'context' => array<string,mixed>,
'form' => array<string,mixed>,
'payload' => array<string,mixed>,
]Note: endpoint and error are redacted before this event fires: secrets are removed and the address is reduced to its host and a hash.
User events
onNxFormsUserRegistered
Type: Informational
Requires: NXForms Pro.
Fires: after the User Registration action creates a user.
Payload: Joomla-style positional [$userId, $data].
onNxFormsUserLoggedIn
Type: Informational
Requires: NXForms Pro.
Fires: after a successful login through the User Login action.
Payload: Joomla-style positional [$payload] containing the login result.
Form-builder lifecycle (admin-side)
onNxFormsFilterDuplicateTitle
Type: Filter (string)
Fires: when an administrator duplicates a form, to work out the copy's title.
Payload:
php
[
'value' => string, // mutable: candidate title
'original' => array<string,mixed>, // the source form being duplicated
]Read back: $event['value'].
Default: appends (Copy) (or localised equivalent) to the original title; listener can replace with any string.
onNxFormsBeforeFormSave (1.3+)
Type: Filter
Fires: before a form is saved, from the builder or Joomla's form save.
Payload:
php
[
'formId' => int, // 0 if creating a new form
'data' => array<string,mixed>, // mutable: the about-to-be-saved data
'wasNew' => bool, // true when formId === 0
]Read back: $event['data'].
Use cases: force tags, inject audit metadata, normalize schema before persistence.
Cannot: veto the save. For veto semantics use Joomla's existing onContentBeforeSave event with setError().
onNxFormsAfterFormSave (1.3+)
Type: Informational
Fires: after a form is saved successfully. Not fired when the save fails.
Payload:
php
[
'formId' => int, // the persisted id (always > 0)
'data' => array<string,mixed>, // post-save data shape
'wasNew' => bool,
]Deleting entries
onNxFormsAfterSubmissionsDelete
Type: Informational
Fires: after entries and their uploaded files are deleted, once per batch of up to 500 entries.
Payload: the typed event Joomla\Component\Nxforms\Administrator\Event\Addon\AfterSubmissionsDeleteEvent. getDeleted() returns the deleted entries, each with read-only id, uuid and formId. It carries no answers, IP addresses or tokens. A listener that fails is logged; the deletion still stands.
Rendering
onNxFormsBeforeFormRender
Type: Filter
Fires: once each time a form is shown, after NXForms has checked that the form is available.
Payload: the typed event Joomla\Component\Nxforms\Administrator\Event\Addon\BeforeFormRenderEvent.
getForm()returns the form;getPlacement()says where it is shown:view,module,contentormodal.setInitialValues()fills in field values on the server, through the normal field rendering.replaceOutput()replaces the whole form with your own HTML, which you must escape yourself.
A paused form stays paused: this event can't show it.
Versioning
This document tracks the public event contract for NXForms 2.0. An (1.3+) marker records when an event first appeared in the 1.x line; it does not describe a separate edition or a current feature gate. Events without a version marker predate this reference.