Actions

This page documents all PHP actions fired by Unblock.

Actions allow you to execute code at specific points in the plugin lifecycle.

Summary

Action	Description
unblock/loaded	Plugin loaded, before services registered
unblock/init	Plugin fully initialized
unblock/form/processed	Form submission passed validation, before email
unblock/form/spam_detected	Form submission detected as spam

loaded

Fired when the UnBlock plugin file has been loaded, before services are registered and initialized.

Parameters

None.

Usage

add_action( 'unblock/loaded', function() {

    // Plugin is loaded but not fully initialized.
    // Use this for very early setup.

} );

Example: Early Configuration

add_action( 'unblock/loaded', function() {

    // Define constants before plugin initializes.
    if ( ! defined( 'MY_UNBLOCK_DEBUG' ) ) {
        define( 'MY_UNBLOCK_DEBUG', true );
    }

} );

init

Fired after the plugin's helpers, services, and hooks have been registered. This is the recommended hook for most integrations.

Parameters

None.

Usage

add_action( 'unblock/init', function() {

    // Plugin is fully initialized.
    // Safe to interact with all plugin features.

} );

Example: Initialize Custom Integration

add_action( 'unblock/init', function() {

    // Register custom functionality after UnBlock is ready.
    if ( class_exists( 'My_Custom_Integration' ) ) {
        My_Custom_Integration::instance()->init();
    }

} );

Example: Conditional Feature Loading

add_action( 'unblock/init', function() {

    // Load additional features based on environment.
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {

        add_filter( 'unblock/data/providers', function( $providers ) {

            $providers['debug'] = [
                'class' => My_Debug_Provider::class,
            ];

            return $providers;

        } );

    }

} );

form/processed

Fires after a form submission passes all validation (honeypot, timestamp, rate limit, sanitization, attachments) and before the email is sent.

do_action( 'unblock/form/processed', Context $context );

Parameter	Type	Description
$context	\Unblock\Form\Context	Form context with sanitized fields, attachments, referer, client IP, and form ID

Example: Save Form Entry

add_action( 'unblock/form/processed', function( $context ) {

    wp_insert_post( [
        'post_type'    => 'form_entry',
        'post_title'   => 'Submission from ' . $context->referer(),
        'post_content' => wp_json_encode( $context->fields() ),
        'post_status'  => 'private',
    ] );

} );

Example: Forward to HelpScout

This example forwards form submissions to HelpScout as conversations, using the topic field as a tag. If the API call fails, the error is reported back to the user.

add_action( 'unblock/form/processed', function( $context ) {

    $fields = $context->fields();
    $email  = $fields['email'] ?? '';
    $name   = $fields['name'] ?? '';
    $topic  = $fields['topic'] ?? 'other';

    if ( ! $email ) {
        $context->add_error(
            'submission_failed',
            __( 'Failed to send the form. Please try again later.', 'my-theme' )
        );
        return;
    }

    $token = my_get_helpscout_token(); // Your OAuth2 token helper.
    $parts = explode( ' ', $name, 2 );

    $response = wp_remote_post( 'https://api.helpscout.net/v2/conversations', [
        'headers' => [
            'Authorization' => 'Bearer ' . $token,
            'Content-Type'  => 'application/json',
        ],
        'body' => wp_json_encode( [
            'subject'   => sprintf( '[%s] Message from %s', ucfirst( $topic ), $name ),
            'customer'  => [
                'email'     => $email,
                'firstName' => $parts[0] ?? '',
                'lastName'  => $parts[1] ?? '',
            ],
            'mailboxId' => MY_HELPSCOUT_MAILBOX_ID,
            'type'      => 'email',
            'status'    => 'active',
            'threads'   => [
                [
                    'type'     => 'customer',
                    'customer' => [ 'email' => $email ],
                    'text'     => $fields['message'] ?? '',
                ],
            ],
            'tags' => [ $topic ],
        ] ),
    ] );

    $status = wp_remote_retrieve_response_code( $response );

    if ( is_wp_error( $response ) || 201 !== $status ) {
        $context->add_error(
            'submission_failed',
            __( 'Failed to send the form. Please try again later.', 'my-theme' )
        );
    }

} );

// Disable the default email — HelpScout handles it.
add_filter( 'unblock/form/send_email', '__return_false' );

Error handling

Call $context->add_error( $code, $message ) to signal a failure. The error code determines the HTTP status (429 for rate_limited, 400 for anything else), and the message is returned to the client in the JSON response.

form/spam_detected

Fires when a form submission is detected as spam via honeypot or timestamp checks.

do_action( 'unblock/form/spam_detected', Context $context );

Parameter	Type	Description
$context	\Unblock\Form\Context	Form context with error details

Example: Log Spam Attempts

add_action( 'unblock/form/spam_detected', function( $context ) {

    error_log( 'Spam detected from IP: ' . $context->client_ip() );

} );

Next steps

• Data filters — providers, meta, and expression extensions
• Debug Logging — diagnose expression and query errors