How to Modify Token Behaviour With WordPress Filters for Gated Content

Introduction

For WordPress developers working with gated content, the ability to customise how access tokens behave is paramount. While plugins like Gatekeeper Pro offer robust out-of-the-box solutions for restricting content, real-world applications often demand bespoke adjustments to token expiry, admin approval windows, or email template logic.

This article dives into the practical application of WordPress filters, providing a step-by-step tutorial on how to modify token behaviour within a gated content setup. We'll explore how to leverage these developer hooks to integrate content restriction seamlessly into your custom workflows, ensuring your access control is as flexible as your project requires.

Understanding Token Behaviour in Gated Content

In a gated content system, tokens are the digital keys that grant approved users access to restricted resources. When a visitor submits an access request and it's approved, Gatekeeper Pro generates a cryptographically signed token. This token is then sent to the user, allowing them to view or download the protected content.

Gatekeeper Pro offers flexible token management, including two primary unlock modes: per-item tokens, which grant access to a single specific resource, and sitewide tokens, which unlock all gated content. Crucially, tokens can have a configurable Time-To-Live (TTL), defining their expiry, Understanding these core behaviours is the first step towards effectively modifying them.

The Power of WordPress Filters for Customisation

WordPress filters are a cornerstone of its extensibility, allowing developers to modify data before it's used or displayed. Unlike action hooks, which execute code at specific points, filters enable you to intercept and alter variables or values. This mechanism is ideal for fine-tuning the behaviour of plugins like Gatekeeper Pro without directly editing their core files, ensuring your customisations are update-safe.

By attaching your custom functions to these filter hooks, you gain precise control over various aspects of the plugin's operation. This non-destructive approach means you can tailor token behaviour to specific content types or external conditions, making your gated content solution truly unique and robust.

Identifying Key Token-Related Filters in Gatekeeper Pro

Gatekeeper Pro is designed with developer extensibility in mind, providing a suite of action and filter hooks. To modify token behaviour, we'll focus on filters that allow us to interact with a token's lifecycle and properties. While specific filter names can vary, typically they follow a pattern that indicates their purpose.

The following examples use the real filter hooks exposed by Gatekeeper Pro. We'll cover adjusting the user-facing token TTL, the admin approval link TTL, and email template file paths.

Filter 1: Modifying Token Expiry (TTL)

The gatekeeper_pro_token_ttl filter lets you adjust the number of hours a user-facing access token remains valid. The filter receives the default TTL, the post ID, and the full request data array — enabling conditional expiry based on requester email domain, content type, or any other criteria.

<?php
/**
 * Customise Gatekeeper Pro token TTL based on requester or content.
 *
 * @param int   $ttl_hours The default TTL in hours.
 * @param int   $post_id   The ID of the locked post.
 * @param array $request   The full access request data array.
 * @return int The modified TTL in hours.
 */
function my_custom_token_ttl( $ttl_hours, $post_id, $request ) {
    // Example 1: Unlimited access for 'premium_client' email domains.
    $email = $request['user_email'] ?? '';
    if ( str_contains( $email, '@premiumclient.com' ) ) {
        return 0; // 0 means unlimited access in Gatekeeper Pro.
    }

    // Example 2: Shorter TTL for specific content categories.
    $terms = get_the_terms( $post_id, 'category' );
    if ( $terms && ! is_wp_error( $terms ) ) {
        foreach ( $terms as $term ) {
            if ( $term->slug === 'free-trial-content' ) {
                return 24; // Token expires in 24 hours for trial content.
            }
        }
    }

    // Return the original TTL if no custom logic applies.
    return $ttl_hours;
}
add_filter( 'gatekeeper_pro_token_ttl', 'my_custom_token_ttl', 10, 3 );
?>

In this example, we're hypothetically checking the requester's email domain to grant unlimited access to "premium clients." We also demonstrate adjusting the TTL for content within a specific category, such as "free-trial-content," setting it to 24 hours. The arguments passed to the filter — $post_id and the full $request array (containing user_email, user_company, post_type, etc.) — are crucial for implementing conditional logic.

Filter 2: Adjusting the Admin Approval Token TTL

When an access request is submitted, Gatekeeper Pro sends an email to admins containing one-click "Approve" and "Disapprove" links. These links are secured with HMAC-signed tokens that have their own configurable time-to-live. The gatekeeper_pro_admin_token_ttl filter lets you adjust this window — useful if your team needs more time to review requests before the approval links expire.

<?php
/**
 * Extend the admin approval link TTL from the default 72 hours.
 *
 * @param int $ttl The default TTL in seconds (72 * HOUR_IN_SECONDS).
 * @return int The modified TTL in seconds.
 */
function my_custom_admin_token_ttl( $ttl ) {
    // Example 1: Give admins a full week to act on approval links.
    return 7 * DAY_IN_SECONDS;
}
add_filter( 'gatekeeper_pro_admin_token_ttl', 'my_custom_admin_token_ttl' );
?>

The default admin token TTL is 72 hours (3 days). This filter receives the value in seconds (not hours like the user-facing token TTL). In the example above, we extend it to 7 days — useful for agencies where requests may sit in an inbox over a long weekend. Note: reducing this value too aggressively could frustrate admins who receive approval emails but find the links already expired.

Filter 3: Overriding Email Template File Paths

When tokens are issued, Gatekeeper Pro sends approval emails using PHP template files from the plugin's templates/emails/ directory (which can be overridden in your theme at gatekeeper-pro/emails/). The gatekeeper_pro_email_template filter lets you programmatically swap which template file is used — useful when you need conditional logic to choose different templates based on content type or requester data.

<?php
/**
 * Swap the email template file path based on content type.
 *
 * @param string $template_file The resolved file path to the template.
 * @param string $template      The template name (e.g., 'approved', 'disapproved',
 *                               'request-received', 'admin-notification', 'expiry-warning').
 * @return string Modified file path.
 */
function my_custom_email_template( $template_file, $template ) {
    // Example 1: 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;
        }
    }

    // Example 2: Use a different admin notification for high-value content.
    if ( 'admin-notification' === $template ) {
        $custom = get_stylesheet_directory() . '/gatekeeper-pro/emails/admin-notification-vip.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }

    return $template_file;
}
add_filter( 'gatekeeper_pro_email_template', 'my_custom_email_template', 10, 2 );
?>

The filter receives the resolved file path and the template name. Template names correspond to the five email types: 'admin-notification', 'request-received', 'approved', 'disapproved', and 'expiry-warning'. The plugin first checks your theme for overrides at gatekeeper-pro/emails/{template}.php, then falls back to the plugin's own templates/emails/ directory. This filter runs after that resolution, giving you the final say over which file is loaded.

Step-by-Step Tutorial: Implementing Custom Token Behaviour

Step 1: Set Up Your Development Environment

Before writing any code, ensure you have a local or staging WordPress environment. Install and activate the Gatekeeper Pro plugin. You'll need a way to add custom PHP code, ideally through a child theme's functions.php file or a custom plugin. Using a custom plugin is generally recommended for site-specific functionality, as it separates your customisations from theme updates.

Ensure you have access to your site's file system or a code editor that can interact with it. Basic knowledge of PHP and WordPress hooks is assumed.

Step 2: Create a Custom Plugin (Recommended)

To keep your customisations organised and update-safe, create a simple custom plugin. This involves creating a new folder in your wp-content/plugins/ directory, for example, my-custom-gkp-extensions. Inside this folder, create a PHP file (e.g., my-custom-gkp-extensions.php) and add the standard plugin header.

<?php
/**
 * Plugin Name: My Custom Gatekeeper Pro Extensions
 * Description: Customisations for Gatekeeper Pro token behaviour.
 * Version: 1.0.0
 * Author: Custom Developer
 */

// Your custom filter functions will go here.
?>

Activate this new plugin from your WordPress admin dashboard under the 'Plugins' menu. All your custom code for Gatekeeper Pro token modifications will reside within this plugin file.

Step 3: Implement Custom Token Expiry (TTL)

Let's implement the first example: modifying the token TTL. Copy the my_custom_token_ttl function and the add_filter call from Filter 1 into your custom plugin file. For testing, create an access request for a post and observe the token expiry.

To test the "premium client" logic, you'd need to simulate an access request with an email containing '@premiumclient.com'. After approval, check the token details in the Gatekeeper Pro admin area or the user's email to confirm the TTL has been set to unlimited (or 0 hours). For the "free-trial-content" category, assign a post to that category and request access to verify the 24-hour expiry.

Step 4: Adjust the Admin Approval Link TTL

Next, add the my_custom_admin_token_ttl function from Filter 2 into your custom plugin file. To test, submit a new access request and check the approval link in the admin notification email. The HMAC-signed URL contains a timestamp — after your configured TTL elapses, clicking the link should return an "expired" error. You can temporarily set a very short TTL (e.g., 60 seconds) to verify the expiry logic works, then set it to your production value.

Step 5: Override Email Template Paths

Finally, add the my_custom_email_template function from Filter 3 into your custom plugin file. Create the custom template files in your child theme's gatekeeper-pro/emails/ directory (e.g., approved-resource.php). Copy an existing template from the plugin's templates/emails/ directory as a starting point, then customise its markup.

To test, approve an access request and check the resulting email. If your filter matched, you'll see the content from your custom template. Use error_log() within your filter function to verify which template name and file path are being resolved, confirming the filter is firing correctly.

Best Practices for Using Filters

• Use a Child Theme or Custom Plugin: Always place your custom code in a child theme's functions.php or, preferably, a dedicated custom plugin. This prevents your modifications from being overwritten during theme or plugin updates.

• Prefix Your Functions: Use a unique prefix for your custom function names (e.g., my_custom_) to avoid naming collisions with other plugins or themes.

• Add Comments: Document your code thoroughly. Explain what each filter does, why it's there, and any assumptions made. This makes your code easier to understand and maintain for yourself and others.

• Test Thoroughly: After applying any filter, rigorously test the affected functionality across various scenarios. Check different access request types, content types, and boundary conditions to ensure your changes behave as expected.

• Understand Filter Priority: The third argument in add_filter() is priority (default is 10). If multiple functions hook into the same filter, a lower number runs earlier. Adjust this if your filter needs to run before or after another.

• Validate Inputs: Always validate and sanitise any data retrieved from external sources before using it in your filter logic.

Real-World Applications

Modifying token behaviour with filters opens up a myriad of possibilities for complex gated content scenarios:

• Tiered Access Levels: Use the gatekeeper_pro_token_ttl filter to grant longer or unlimited access to premium members (based on email domain or company) while offering limited 24-hour trials to prospects.

• Promotional Campaigns: Dynamically set token expiry to match campaign durations — short windows for flash sales, longer access for evergreen resources.

• Client Portals: Return 0 from the TTL filter for trusted client email domains, providing permanent access to all their project documentation.

• Distributed Teams: Extend the admin approval link TTL with gatekeeper_pro_admin_token_ttl to accommodate teams across time zones where requests may not be reviewed for several days.

• Branded Email Communications: Use the gatekeeper_pro_email_template filter to serve different approval email designs for different post types or client tiers, ensuring every touchpoint matches your brand.

Conclusion

WordPress filters provide a powerful and elegant solution for developers to extend and customise the core functionality of plugins like Gatekeeper Pro. By understanding and utilising filters for token behaviour, you can create a highly tailored and flexible gated content system that perfectly aligns with your project's unique requirements.

Whether it's adjusting user-facing token expiry, extending admin approval windows, or swapping email templates conditionally, these developer hooks empower you to build sophisticated access control workflows. Embracing this extensibility ensures your content gating solution is robust, future-proof, and seamlessly integrated into your WordPress ecosystem.