NXP Docs

Appearance

NXP Easy Forms - Public API Documentation ​

Version: 1.0.0 Last Updated: 2025-01-23

This document describes all public APIs, hooks, filters, and integration points available in NXP Easy Forms.

Scope note This API reference documents the WordPress plugin hook API (do_action / apply_filters) for nxp-easy-forms. The Joomla component (com_nxpeasyforms) does not use WordPress hooks. It uses Joomla event dispatching with onNxpEasyForms... event names (for example onNxpEasyFormsBeforeSubmission, onNxpEasyFormsAfterSubmission, and integration payload filters).

Table of Contents ​

  1. Actions (Hooks)
  2. Filters
  3. Public PHP Classes
  4. REST API Endpoints
  5. JavaScript API
  6. Integration Queue API
  7. Database Schema

Actions (Hooks) ​

Form Submission Lifecycle ​

nxp_easy_forms_before_submission ​

Fires before a form submission is processed.

php
do_action(
    'nxp_easy_forms_before_submission',
    int $form_id,
    array $form,
    array $request_data,
    array $context
);

Parameters:

  • $form_id (int) - Form ID
  • $form (array) - Form configuration (includes fields, settings, title, etc.)
  • $request_data (array) - Raw POST data
  • $context (array) - Submission context (IP, user agent, etc.)

Example:

php
add_action('nxp_easy_forms_before_submission', function($form_id, $form, $data, $context) {
    // Log submission attempt
    error_log("Form {$form_id} ({$form['title']}) submission from IP: {$context['ip_address']}");
}, 10, 4);

nxp_easy_forms_after_submission ​

Fires after a submission is successfully processed.

php
do_action(
    'nxp_easy_forms_after_submission',
    int $form_id,
    array $sanitised,
    array $result,
    array $form,
    array $context
);

Parameters:

  • $form_id (int) - Form ID
  • $sanitised (array) - Sanitized submission data (field values)
  • $result (array) - Processing result with keys:
    • success (bool) - Whether submission succeeded
    • message (string) - Success/error message
    • data (array) - Contains submission_id (int|null) and fields (array)
    • email (array) - Email delivery result
  • $form (array) - Form configuration
  • $context (array) - Submission context (IP, user agent, etc.)

Example:

php
add_action('nxp_easy_forms_after_submission', function($form_id, $sanitised, $result, $form, $context) {
    // Access submission ID (null if storage disabled)
    $submission_id = $result['data']['submission_id'] ?? null;

    // Custom notification for specific form
    if ($form_id === 5) {
        wp_mail('admin@example.com', 'VIP Form Submitted', print_r($sanitised, true));
    }

    // Log to custom table
    if ($submission_id) {
        global $wpdb;
        $wpdb->insert('wp_my_custom_log', [
            'form_id' => $form_id,
            'submission_id' => $submission_id,
            'data' => json_encode($sanitised),
            'logged_at' => current_time('mysql'),
        ]);
    }
}, 10, 5);

nxp_easy_forms_submission_failed ​

Fires when submission fails validation or processing.

php
do_action(
    'nxp_easy_forms_submission_failed',
    int $form_id,
    string $error_message,
    array $context
);

Example:

php
add_action('nxp_easy_forms_submission_failed', function($form_id, $error, $context) {
    // Track failed submissions
    update_option("form_{$form_id}_failure_count", get_option("form_{$form_id}_failure_count", 0) + 1);
}, 10, 3);

Integration Hooks ​

nxp_easy_forms_integration_dispatch ​

Fires when a custom integration is triggered (not handled by core).

php
do_action(
    'nxp_easy_forms_integration_dispatch',
    string $integration_id,
    array $settings,
    array $form,
    array $payload,
    array $context,
    array $field_meta
);

Example - Custom CRM Integration:

php
add_action('nxp_easy_forms_integration_dispatch', function($id, $settings, $form, $payload, $context, $meta) {
    if ($id !== 'my_custom_crm') {
        return;
    }

    // Send to custom CRM
    wp_remote_post('https://mycrm.com/api/leads', [
        'body' => json_encode($payload),
        'headers' => ['Authorization' => 'Bearer ' . $settings['api_key']],
    ]);
}, 10, 6);

nxp_easy_forms_wp_post_created ​

Fires after WordPress post is created from submission.

php
do_action(
    'nxp_easy_forms_wp_post_created',
    int $post_id,
    array $form,
    array $payload
);

Email Hooks ​

nxp_easy_forms_before_email_send ​

Fires before email is sent (allows cancellation).

php
do_action(
    'nxp_easy_forms_before_email_send',
    array $message,
    array $form
);

Filters ​

Form Processing Filters ​

nxp_easy_forms_sanitize_value ​

Filter individual field value during sanitization.

php
apply_filters(
    'nxp_easy_forms_sanitize_value',
    mixed $sanitised_value,
    mixed $raw_value,
    array $field_config
);

Example - Custom Sanitization:

php
add_filter('nxp_easy_forms_sanitize_value', function($sanitised, $raw, $field) {
    // Custom phone number format
    if ($field['type'] === 'tel') {
        return preg_replace('/[^0-9]/', '', $sanitised);
    }
    return $sanitised;
}, 10, 3);

nxp_easy_forms_validate_field ​

Filter field validation errors.

php
apply_filters(
    'nxp_easy_forms_validate_field',
    ?string $error,
    mixed $value,
    array $field_config
);

Example - Custom Validation:

php
add_filter('nxp_easy_forms_validate_field', function($error, $value, $field) {
    if ($field['name'] === 'company_email' && !str_ends_with($value, '@company.com')) {
        return 'Must use company email address';
    }
    return $error;
}, 10, 3);

Email Filters ​

nxp_easy_forms_email_message ​

Modify email content before sending.

php
apply_filters(
    'nxp_easy_forms_email_message',
    array $message,
    array $form,
    array $submission
);

Message Array Structure:

php
[
    'to' => 'recipient@example.com',
    'subject' => 'Form Submission',
    'html' => '<html>...</html>',
    'text' => 'Plain text version',
    'from_name' => 'Site Name',
    'from_email' => 'noreply@site.com',
    'reply_to' => 'user@example.com', // Optional
]

Example:

php
add_filter('nxp_easy_forms_email_message', function($message, $form, $submission) {
    // Add custom footer
    $message['html'] .= '<p><small>Submitted via NXP Easy Forms</small></p>';
    return $message;
}, 10, 3);

nxp_easy_forms_wp_post_args ​

Modify WordPress post arguments before creation.

php
apply_filters(
    'nxp_easy_forms_wp_post_args',
    array $postarr,
    array $form,
    array $payload,
    array $settings,
    array $context
);

Example:

php
add_filter('nxp_easy_forms_wp_post_args', function($postarr, $form) {
    // Force specific category
    if ($form['id'] === 10) {
        $postarr['post_category'] = [5, 12];
    }
    return $postarr;
}, 10, 2);

Form Display Filters ​

nxp_easy_forms_render_field ​

Modify field HTML before rendering.

php
apply_filters(
    'nxp_easy_forms_render_field',
    string $html,
    array $field,
    string $form_id_attr
);

Example - Add Custom Class:

php
add_filter('nxp_easy_forms_render_field', function($html, $field) {
    if ($field['type'] === 'email') {
        $html = str_replace('<input', '<input class="custom-email-field"', $html);
    }
    return $html;
}, 10, 2);

Public PHP Classes ​

Submission_Service ​

Namespace: NXP_Easy_Forms\Submission\Submission_Service

Public Methods:

handle() ​

Process form submission.

php
public function handle(
    int $form_id,
    array $request_data,
    array $context = [],
    array $files = []
): array

Returns: ['success' => bool, 'message' => string, 'data' => array]

Throws: Submission_Exception

Form_Repository ​

Namespace: NXP_Easy_Forms\Forms\Form_Repository

Public Methods:

get(int $form_id): ?array ​

Retrieve form by ID.

php
$form_repo = new \NXP_Easy_Forms\Forms\Form_Repository();
$form = $form_repo->get(5);

if ($form) {
    echo $form['title'];
}

get_all(): array ​

Get all forms (excludes trashed).

create(array $data): int ​

Create new form, returns form ID.

update(int $form_id, array $data): bool ​

Update existing form.

delete(int $form_id): bool ​

Soft-delete form (sets active = 0).

Integration_Queue ​

Namespace: NXP_Easy_Forms\Submission\Integration_Queue

Public Methods:

should_queue(string $integration_id): bool ​

Check if integration runs async.

php
$queue = new \NXP_Easy_Forms\Submission\Integration_Queue();
if ($queue->should_queue('zapier')) {
    // Will be queued
}

get_stats(): array ​

Get queue statistics.

php
$stats = $queue->get_stats();
// Returns:
[
    'total_jobs' => 5,
    'pending' => 3,
    'retrying' => 2,
    'oldest_timestamp' => 1234567890,
]

clear_queue(): void ​

Clear all queued jobs (debugging only).

REST API Endpoints ​

Base URL: /wp-json/nxp-easy-forms/v1/

Authentication: WordPress nonce (X-WP-Nonce header)

POST /submissions ​

Submit a form.

Request:

json
{
  "form_id": 5,
  "fields": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "_nxp_nonce": "abc123..."
}

Response (200):

json
{
  "success": true,
  "message": "Thank you for your submission!",
  "data": {
    "submission_id": 123,
    "redirect_url": null
  }
}

Response (400) - Validation Error:

json
{
  "success": false,
  "message": "Validation failed",
  "data": {
    "errors": {
      "email": "Please enter a valid email address"
    }
  }
}

GET /forms/{id}/builder ​

Get form builder data (admin only).

Response:

json
{
  "form": {
    "id": 5,
    "title": "Contact Form",
    "active": 1
  },
  "config": {
    "fields": [...],
    "options": {...}
  }
}

POST /forms/{id}/builder ​

Save form builder data (admin only).

Request:

json
{
  "title": "Updated Form",
  "config": {
    "fields": [...],
    "options": {...}
  }
}

GET /forms/{id}/test-email ​

Send test email (admin only).

Query Params:

  • recipient: Email address
  • provider: Delivery method (wordpress, sendgrid, mailgun, etc.)

Response:

json
{
  "success": true,
  "sent": true,
  "provider": "mailgun"
}

JavaScript API ​

Global Object: window.nxpEasyForms ​

Available on frontend pages with forms.

Properties ​

javascript
window.nxpEasyForms = {
  restUrl: '/wp-json/nxp-easy-forms/v1/',
  nonce: 'abc123...',
  ajaxUrl: '/wp-admin/admin-ajax.php',
  i18n: {
    // Translated strings
    required: 'This field is required',
    invalidEmail: 'Please enter a valid email',
    // ...
  }
}

Form Instance Methods ​

javascript
// Get form instance
const form = document.querySelector('[data-nxp-form-id="5"]');
const formInstance = form.nxpFormInstance;

// Reset form
formInstance.reset();

// Get field value
const email = formInstance.getFieldValue('email');

// Set field value
formInstance.setFieldValue('email', 'new@example.com');

// Validate programmatically
const isValid = formInstance.validate();

// Submit programmatically
formInstance.submit();

Integration Queue API ​

Cron Hook ​

Hook Name: nxp_easy_forms_process_integration_queueSchedule: Every minute Function: Processes 10 queued jobs per run

Manually Trigger Queue Processing ​

php
// Via WP-CLI
wp cron event run nxp_easy_forms_process_integration_queue

// Via PHP
do_action('nxp_easy_forms_process_integration_queue');

Queue Data Structure ​

Stored in wp_options table as nxp_easy_forms_integration_queue.

php
[
  [
    'id' => 'uuid-string',
    'integration_id' => 'zapier',
    'settings' => [...],
    'form' => [...],
    'payload' => [...],
    'context' => [...],
    'field_meta' => [...],
    'timestamp' => 1234567890,
    'attempts' => 0,
    'last_error' => null,
  ],
  // ... more jobs
]

Database Schema ​

Table: wp_nxp_easy_forms_forms ​

sql
CREATE TABLE wp_nxp_easy_forms_forms (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  title varchar(255) NOT NULL DEFAULT '',
  config longtext NOT NULL,
  active tinyint(1) NOT NULL DEFAULT 1,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY active (active),
  KEY created_at (created_at)
);

Columns:

  • id: Form ID
  • title: Form title
  • config: JSON-encoded form configuration (fields + options)
  • active: 1 = active, 0 = trashed
  • created_at: Creation timestamp
  • updated_at: Last modification timestamp

Table: wp_nxp_easy_forms_submissions ​

sql
CREATE TABLE wp_nxp_easy_forms_submissions (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  form_id bigint(20) unsigned NOT NULL,
  payload longtext NOT NULL,
  ip_address varchar(45) DEFAULT NULL,
  user_agent text DEFAULT NULL,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY form_id (form_id),
  KEY created_at (created_at),
  KEY ip_address (ip_address)
);

Columns:

  • id: Submission ID
  • form_id: Related form ID
  • payload: JSON-encoded submission data
  • ip_address: Submitter IP (nullable if anonymization enabled)
  • user_agent: Browser user agent
  • created_at: Submission timestamp

Schema Version Management ​

Option Key: nxp_easy_forms_db_versionCurrent Version: 1

Accessing Schema Manager ​

php
$schema_manager = new \NXP_Easy_Forms\Setup\Schema_Manager();

// Check version
$current = $schema_manager->get_current_version(); // 1
$installed = $schema_manager->get_installed_version(); // 1

// Check if upgrade needed
if ($schema_manager->needs_upgrade()) {
    $schema_manager->run_migrations();
}

Examples ​

Example 1: Log All Submissions to Custom Table ​

php
add_action('nxp_easy_forms_after_submission', function($form_id, $sanitised, $result, $form, $context) {
    global $wpdb;

    $submission_id = $result['data']['submission_id'] ?? null;
    if (!$submission_id) {
        return; // Storage disabled, nothing to log
    }

    $wpdb->insert('wp_my_custom_log', [
        'form_id' => $form_id,
        'submission_id' => $submission_id,
        'data' => json_encode($sanitised),
        'logged_at' => current_time('mysql'),
    ]);
}, 10, 5);

Example 2: Custom Integration Dispatcher ​

php
// Register custom integration
add_action('nxp_easy_forms_integration_dispatch', function($id, $settings, $form, $payload) {
    if ($id !== 'my_crm') {
        return;
    }

    $api_key = $settings['api_key'] ?? '';
    if (empty($api_key)) {
        error_log('My CRM: API key missing');
        return;
    }

    wp_remote_post('https://mycrm.com/api/contacts', [
        'headers' => [
            'Authorization' => 'Bearer ' . $api_key,
            'Content-Type' => 'application/json',
        ],
        'body' => wp_json_encode([
            'name' => $payload['name'] ?? '',
            'email' => $payload['email'] ?? '',
            'source' => 'NXP Easy Forms',
        ]),
        'timeout' => 15,
    ]);
}, 10, 4);

Example 3: Modify Email Based on Form Field ​

php
add_filter('nxp_easy_forms_email_message', function($message, $form, $submission) {
    // Change recipient based on department selection
    if (!empty($submission['department'])) {
        $recipients = [
            'sales' => 'sales@company.com',
            'support' => 'support@company.com',
            'billing' => 'billing@company.com',
        ];

        $dept = $submission['department'];
        if (isset($recipients[$dept])) {
            $message['to'] = $recipients[$dept];
        }
    }

    return $message;
}, 10, 3);

Support & Contributing ​

Last Updated: January 23, 2025 Plugin Version: 1.0.0