Filter Hooks for Customising Gated Content Output on WordPress

Introduction

For WordPress developers, extending plugin functionality without directly modifying core files is a cornerstone of maintainable and upgrade-safe development. Filter hooks are your primary tool for this, allowing you to intercept and modify data before it's used or displayed. When it comes to content gating, customising the user experience is paramount, and filter hooks offer the flexibility to tailor every aspect of the output.

Gatekeeper Pro, a robust WordPress plugin for restricting access to content, is built with developer extensibility in mind. It exposes a comprehensive set of filter hooks, enabling you to integrate gated content seamlessly into unique workflows, adjust display logic, and refine user interactions. This guide delves into practical applications of these filter hooks, empowering you to finely tune your gated content output.

Understanding WordPress Filter Hooks

In the WordPress ecosystem, hooks are mechanisms that allow you to "hook into" the WordPress core, themes, or plugins at specific points during execution. There are two main types: action hooks and filter hooks.

• Action Hooks: These allow you to inject custom code at specific points, performing an action without necessarily altering the data being processed. Think of them as "do something here" triggers.

• Filter Hooks: These allow you to modify data before it's processed or displayed. A filter takes a value, modifies it, and then returns the modified value. They are designed for "change this value" operations.

Filter hooks are identifiable by functions like apply_filters() in the plugin's codebase. When you add a filter, you're essentially providing a callback function that WordPress will execute whenever that specific apply_filters() call is encountered, passing the data through your function for modification.

Gatekeeper Pro's Extensibility Model

Gatekeeper Pro provides a secure and flexible way to protect downloads, videos, and page content, managing access through an intuitive request and approval workflow. Beyond its out-of-the-box features, the plugin offers a rich developer API, including numerous filter hooks, to ensure it can be adapted to virtually any custom requirement.

Whether you're building a client portal with unique branding, a training platform requiring dynamic access link parameters, or a lead generation system with custom form fields, Gatekeeper Pro's filters allow you to control the content output. This includes everything from the appearance of the access request form and the content of email notifications to the data displayed in resource cards and the messages users see.

Key Filter Hooks for Gated Content Customisation

Let's explore some practical examples of how filter hooks can be used to customise the output of your gated content with Gatekeeper Pro. For each example, we'll outline the hook's purpose, provide a code snippet, and discuss a real-world scenario.

1. Customising the Locked Content HTML Output

When content is locked, Gatekeeper Pro renders a default HTML wrapper containing the lock overlay, teaser content, and request button. The gatekeeper_pro_locked_content_html filter lets you modify or completely replace this locked-state HTML for a specific post or globally.

Purpose: To alter the HTML block displayed when content is gated and the visitor does not have a valid access token.

Parameters: $html (string - the default locked HTML), $post_id (int - the ID of the current post).

Example: Adding a custom call-to-action above the locked content.

<?php
add_filter( 'gatekeeper_pro_locked_content_html', 'saucecode_custom_locked_output', 10, 2 );

function saucecode_custom_locked_output( $html, $post_id ) {
    // Only apply to a specific post or post type if needed
    // if ( 'post' === get_post_type( $post_id ) ) {
    //     return '<div class="my-custom-message">Unlock this premium article!</div>' . $html;
    // }

    // Or replace the entire output globally
    $custom_message = '<div class="my-custom-gated-wrapper">';
    $custom_message .= '<h3>Access this exclusive resource now!</h3>';
    $custom_message .= '<p>Please submit your details below to gain immediate access to this valuable content.</p>';
    $custom_message .= $html; // Include the original locked content HTML
    $custom_message .= '</div>';

    return $custom_message;
}
?>

Real-world Application: For a B2B marketing site, you might want to display a more persuasive, branded message or integrate a specific lead magnet description directly above the access request form on certain whitepaper pages.

2. Customising the Unlocked Content HTML Output

Once a visitor presents a valid access token, Gatekeeper Pro renders the unlocked version of the gated content. The gatekeeper_pro_unlocked_content_html filter lets you modify or augment this unlocked HTML — for example, to inject a personalised welcome message or append related resource links.

Purpose: To alter the HTML block displayed after a visitor has gained access via a valid token.

Parameters: $html (string - the default unlocked HTML), $post_id (int - the ID of the resource post), $token (array - the validated token data including user_email, expires_at, etc.).

Example: Adding a personalised greeting and expiry notice to unlocked content.

<?php
add_filter( 'gatekeeper_pro_unlocked_content_html', 'saucecode_custom_unlocked_output', 10, 3 );

function saucecode_custom_unlocked_output( $html, $post_id, $token ) {
    // Add a personalised greeting using the token's email address
    $greeting = '<div class="my-unlocked-greeting">';
    $greeting .= '<p>Welcome back, ' . esc_html( $token['user_email'] ) . '!</p>';

    // Show expiry notice if the token has an expiry date
    if ( ! empty( $token['expires_at'] ) ) {
        $greeting .= '<p class="my-expiry-notice">Your access expires on '
            . esc_html( wp_date( get_option( 'date_format' ), strtotime( $token['expires_at'] ) ) )
            . '.</p>';
    }
    $greeting .= '</div>';

    return $greeting . $html;
}
?>

Real-world Application: A client portal can display a personalised welcome message and token expiry countdown after access is granted, improving the user experience and reducing support queries about access duration.

3. Overriding Email Template File Paths

Gatekeeper Pro sends five email notifications: admin notification, request received, approved, disapproved, and expiry warning. Templates live in the plugin's templates/emails/ directory and can be overridden by placing files in your theme at gatekeeper-pro/emails/. For programmatic control, the gatekeeper_pro_email_template filter lets you swap the template file path — useful when you need conditional logic to choose different templates.

Purpose: To change which PHP template file is used to render a specific email type.

Parameters: $template_file (string - the resolved file path to the template), $template (string - the template name, e.g., 'approved', 'request-received', 'admin-notification', 'disapproved', 'expiry-warning').

Example: Using a different approval email template for a specific post type.

<?php
add_filter( 'gatekeeper_pro_email_template', 'saucecode_custom_email_template_path', 10, 2 );

function saucecode_custom_email_template_path( $template_file, $template ) {
    // Use a completely custom approval email for the 'resource' post type
    if ( 'approved' === $template ) {
        $custom = get_stylesheet_directory() . '/gatekeeper-pro/emails/approved-resource.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }
    return $template_file;
}
?>

Real-world Application: An agency managing client portals might want to include dynamic client-specific links or contact information in approval emails, ensuring tailored communication without creating multiple static templates.

4. Modifying Access Request Form Fields Configuration

The native access request form includes two always-visible fields (name and email) plus four configurable fields: phone, location, company, and message. Each configurable field has visible, required, and label properties that administrators control from the settings screen. The gatekeeper_pro_form_fields filter lets you programmatically override these properties — for example, to force certain fields visible on specific pages or change labels dynamically.

Purpose: To modify the visibility, required status, or labels of the native form's configurable fields.

Parameters: $fields (array - keyed by field name with visible, required, and label sub-keys), $post_id (int - the ID of the current post).

Example: Making the company and phone fields required on a specific post type.

<?php
add_filter( 'gatekeeper_pro_form_fields', 'saucecode_require_company_phone', 10, 2 );

function saucecode_require_company_phone( $fields, $post_id ) {
    // Force company and phone fields to be visible and required on 'resource' post type
    if ( 'resource' === get_post_type( $post_id ) ) {
        $fields['company']['visible']  = true;
        $fields['company']['required'] = true;
        $fields['company']['label']    = 'Organisation';

        $fields['phone']['visible']  = true;
        $fields['phone']['required'] = true;
    }

    // Change the message field label globally
    if ( isset( $fields['message'] ) ) {
        $fields['message']['label'] = 'Why do you need access?';
    }

    return $fields;
}
?>

Real-world Application: A B2B lead generation site can force the company field to be visible and required on whitepaper and case-study pages, gathering qualifying data without affecting the simpler form shown on blog posts.

5. Dynamically Adjusting Token Lifetime (TTL)

When an access request is approved, Gatekeeper Pro generates a time-limited token. The default TTL is configured in the plugin settings (and can be overridden per post). The gatekeeper_pro_token_ttl filter lets you programmatically adjust the token lifetime in hours before the token is generated — useful for granting longer access to premium customers or shorter windows for time-sensitive content.

Purpose: To dynamically change the token expiry duration based on content type, requester data, or any other condition.

Parameters: $ttl_hours (int - the TTL in hours; 0 or null means unlimited), $post_id (int - the ID of the resource post), $request (array - the full access request data including user_email, user_company, etc.).

Example: Granting longer access for specific email domains.

<?php
add_filter( 'gatekeeper_pro_token_ttl', 'saucecode_custom_token_ttl', 10, 3 );

function saucecode_custom_token_ttl( $ttl_hours, $post_id, $request ) {
    // Grant 30-day access for partner email domains
    $email = $request['user_email'] ?? '';
    if ( str_ends_with( $email, '@partnerdomain.com' ) ) {
        return 720; // 30 days in hours
    }

    // Shorter 24-hour window for time-sensitive press releases
    if ( 'press_release' === get_post_type( $post_id ) ) {
        return 24;
    }

    return $ttl_hours; // Keep the default for everything else
}
?>

Real-world Application: A media company can grant 30-day access to partner journalists while keeping short 24-hour windows for embargoed press releases, all controlled programmatically through a single filter.

6. Controlling Which Post Types Support Gating

By default, Gatekeeper Pro enables gating on post types selected in the plugin settings. The gatekeeper_pro_enabled_post_types filter lets you programmatically add or remove post types from gating support — useful when registering custom post types that should always be gatable regardless of settings, or when you need conditional logic.

Purpose: To dynamically control which WordPress post types have content gating available.

Parameters: $post_types (array - list of post type slugs that currently have gating enabled).

Example: Ensuring a custom post type is always gatable.

<?php
add_filter( 'gatekeeper_pro_enabled_post_types', 'saucecode_always_gate_resources' );

function saucecode_always_gate_resources( $post_types ) {
    // Ensure our custom 'resource' post type is always gatable
    if ( ! in_array( 'resource', $post_types, true ) ) {
        $post_types[] = 'resource';
    }

    // Also enable gating for a 'toolkit' post type
    if ( ! in_array( 'toolkit', $post_types, true ) ) {
        $post_types[] = 'toolkit';
    }

    return $post_types;
}
?>

Real-world Application: When building a site with custom post types for resources, toolkits, or training modules, this filter ensures gating is always available on those types — even if an administrator hasn't manually enabled them in the plugin settings.

Implementing Customisations Safely and Effectively

When working with filter hooks, follow these best practices to ensure your customisations are robust and maintainable:

• Use a Child Theme or Custom Plugin: Never modify plugin files directly. Place your filter functions in your theme's functions.php (if using a child theme) or, preferably, within a custom plugin. This ensures your changes are not lost during updates.

• Prefix Your Functions: Always prefix your custom function names (e.g., saucecode_custom_gated_output) to avoid naming conflicts with other themes or plugins.

• Understand Parameters and Return Values: Carefully read the documentation for each filter to know what parameters it expects and what type of data it should return. Returning incorrect data types can lead to unexpected errors.

• Prioritise Filters: The third argument in add_filter() is the priority. Lower numbers execute earlier. If multiple filters target the same hook, priority determines the order of execution.

• Conditional Logic: Use conditional tags (e.g., is_singular(), get_post_type()) within your filter functions to apply changes only to specific posts, pages, or content types, preventing unintended sitewide effects.

Real-World Scenarios and Advanced Integrations

Leveraging Gatekeeper Pro's filter hooks opens doors to sophisticated integrations:

• Dynamic Content Based on User Data: Modify gated content output or form fields based on data retrieved from an external CRM or user profile, delivering a highly personalised experience.

• A/B Testing Content Gate Variations: Use filters to dynamically change the HTML of the content gate or request form for different user segments, allowing you to A/B test conversion rates.

• Facilitating Marketing Automation Workflows: While Gatekeeper Pro handles access requests internally, filters can be used to augment the data before it's saved, making it suitable for export and use in marketing automation platforms, or to modify success messages to prompt users to engage with other marketing funnels.

Conclusion

Filter hooks are an indispensable part of the WordPress developer's toolkit, and Gatekeeper Pro embraces this extensibility. By understanding and utilising the plugin's filter hooks, you gain granular control over every aspect of your gated content output. This empowers you to create highly customised, branded, and workflow-specific solutions that seamlessly integrate with your WordPress site, ensuring a polished and effective content gating strategy.