Docs

Appearance

Formatrica - Public API Documentation ​

Version: 1.0.5 Last Updated: 2026-03-04

This document describes all public APIs, hooks, filters, and integration points available in Formatrica.

Scope note This API reference documents the WordPress plugin hook API (do_action / apply_filters) for formatrica. The Joomla component (com_formatrica) does not use WordPress hooks. It uses Joomla event dispatching with onFormatrica... event names (for example onFormatricaBeforeSubmission, onFormatricaAfterSubmission, and integration payload filters).

Table of Contents ​

  1. Actions (Hooks)
  2. Filters

Actions (Hooks) ​

Form Submission Lifecycle ​

formatrica_before_submission ​

Fires before a form submission is processed.

php
do_action(
    'formatrica_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('formatrica_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);

formatrica_after_submission ​

Fires after a submission is successfully processed.

php
do_action(
    'formatrica_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('formatrica_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);

formatrica_submission_failed ​

Fires when submission fails validation or processing.

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

Example:

php
add_action('formatrica_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 ​

formatrica_integration_dispatch ​

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

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

Example - Custom CRM Integration:

php
add_action('formatrica_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);

formatrica_wp_post_created ​

Fires after WordPress post is created from submission.

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

Email Hooks ​

formatrica_before_email_send ​

Fires before email is sent (allows cancellation).

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

Filters ​

Form Processing Filters ​

formatrica_sanitize_value ​

Filter individual field value during sanitization.

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

Example - Custom Sanitization:

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

formatrica_validate_field ​

Filter field validation errors.

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

Example - Custom Validation:

php
add_filter('formatrica_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 ​

formatrica_email_message ​

Modify email content before sending.

php
apply_filters(
    'formatrica_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('formatrica_email_message', function($message, $form, $submission) {
    // Add custom footer
    $message['html'] .= '<p><small>Submitted via Formatrica</small></p>';
    return $message;
}, 10, 3);

formatrica_wp_post_args ​

Modify WordPress post arguments before creation.

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

Example:

php
add_filter('formatrica_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 ​

formatrica_render_field ​

Modify field HTML before rendering.

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

Example - Add Custom Class:

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

Support & Contributing ​

Last Updated: March 4, 2026 Plugin Version: 1.0.5