Skip to content

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':
    1. configured email_reply_to
    2. first valid email value found by scanning field_meta (the implicit "reply to whoever submitted the form" fallback)
    3. context['submission_email']
    4. null
  • email_kind === 'submitter_confirmation':
    • configured submitter_email.reply_to_email only
    • 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)

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.

EventVendor
onNxFormsFilterWebhookPayloadGeneric webhook + standalone
onNxFormsFilterMailchimpPayloadMailchimp
onNxFormsFilterHubspotPayloadHubSpot
onNxFormsFilterSalesforcePayloadSalesforce
onNxFormsFilterBrevoPayloadBrevo

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, content or modal.
  • 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.