WordPress Hooks & Actions

One of WPfaker's most important design decisions is that it uses the standard WordPress API for every operation it performs. When WPfaker creates a post, it calls wp_insert_post(). When it creates a taxonomy term, it calls wp_insert_term(). When it creates a user, it calls wp_insert_user(). When it assigns a featured image, it calls set_post_thumbnail(). When it assigns taxonomy terms to a post, it calls wp_set_object_terms(). There are no shortcuts, no direct database inserts, and no bypasses of the WordPress hook system.

This means that every action, filter, and hook that WordPress and your plugins have registered fires exactly as it would if a human user had created the content manually through the admin interface. If your theme runs code when a new post is published, that code runs when WPfaker publishes a generated post. If a plugin sends a notification when a new user is created, that notification fires when WPfaker generates a user. If a custom plugin validates taxonomy terms before they are saved, that validation runs on WPfaker-generated terms. The generated content passes through the exact same pipeline as real content.

This is not a minor technical detail — it is the foundation of what makes WPfaker useful for testing. If WPfaker bypassed hooks and wrote directly to the database, you would be testing with data that never triggered your theme's save_post handlers, never ran through your SEO plugin's metadata generation, never activated your caching plugin's invalidation logic, and never fired your custom plugin's business rules. The test data would look correct in the database but would be missing all the side effects that real content creation produces. By going through the standard WordPress API, WPfaker ensures that your generated content is indistinguishable from manually created content at every level of the system.

TIP

This hook-compatible behavior means WPfaker is not just a data seeder — it is a full content lifecycle simulator. Use it to test not only how your theme displays content, but how your entire WordPress stack responds to content creation, modification, and deletion events.

Post Creation Hooks

When WPfaker generates a post, it calls wp_insert_post() with a complete post data array including title, content, excerpt, status, author, and date. This single function call triggers a cascade of WordPress core actions and filters that your theme and plugins can hook into.

The most important hooks fired during post creation include:

wp_insert_post fires immediately after the post is saved to the database. This is the most commonly used hook for post-creation side effects. SEO plugins use it to generate meta tags, caching plugins use it to warm or invalidate caches, and custom plugins use it to trigger workflows, send notifications, or update related data. Every post WPfaker generates fires this hook with the full post object and a boolean indicating whether it is an update or a new insertion.

save_post and save_post_{post_type} fire after wp_insert_post and provide a convenient way to hook into saves for specific post types. If you have a handler registered for save_post_property that calculates a computed field based on other meta values, that handler runs on every WPfaker-generated property post.

transition_post_status fires when a post's status changes. Since WPfaker creates posts with the status you configure (publish, draft, pending, or private), this hook fires with the appropriate status transition — typically from "new" to your selected status. Plugins that trigger actions on publication (like social media auto-posting or email notifications) will fire on WPfaker-generated posts just as they would on manually published posts.

wp_after_insert_post fires after all post meta and terms have been saved, making it the safest hook for operations that depend on the complete post state. This is a relatively modern hook (WordPress 5.6+) and is increasingly preferred over save_post for complex operations.

Post Meta Hooks

After creating the post, WPfaker populates custom fields by calling update_post_meta() for each field. Every meta update fires the update_post_meta and updated_post_meta actions, as well as the update_postmeta filter. If your plugin watches for changes to specific meta keys — for example, recalculating a price index when a _price meta field changes — those watchers trigger on WPfaker-generated meta values.

For field plugins like ACF, the meta updates go through ACF's own save functions where available, which means ACF-specific hooks like acf/save_post also fire. The same applies to JetEngine, Meta Box AIO, and other supported field plugins — WPfaker respects each plugin's save mechanism to ensure plugin-specific hooks are triggered.

Featured Image Hooks

When WPfaker assigns a featured image to a post using set_post_thumbnail(), WordPress fires the updated_post_meta action for the _thumbnail_id meta key. Plugins that generate responsive image markup, create Open Graph tags from featured images, or trigger CDN uploads when a thumbnail is set will all activate on WPfaker-generated posts.

Taxonomy Assignment Hooks

When WPfaker assigns taxonomy terms to a post using wp_set_object_terms(), WordPress fires set_object_terms with the post ID, term IDs, taxonomy slug, and the operation type (append or replace). Plugins that maintain denormalized term counts, rebuild navigation menus based on assigned categories, or trigger content classification workflows will all fire correctly.

Taxonomy Term Hooks

When WPfaker creates taxonomy terms, it calls wp_insert_term() with the term name, taxonomy, and optional arguments like slug, description, and parent term. This fires the standard WordPress hooks:

created_term and create_{taxonomy} fire immediately after a new term is saved. If you have a handler that assigns default meta values to new categories, generates a term image, or logs term creation events, those handlers run on every WPfaker-generated term.

edited_term_taxonomy fires after the term-taxonomy relationship is established. Plugins that maintain custom term ordering, rebuild taxonomy caches, or synchronize terms across multisite installations hook into this event.

When WPfaker assigns custom meta to terms using update_term_meta(), the update_term_meta and updated_term_meta actions fire for each meta key, just as they would for manually created term meta.

User Creation Hooks

When WPfaker generates users, it calls wp_insert_user() with a complete user data array including login, email, password, display name, role, and biographical information. This fires:

user_register fires immediately after a new user is created. This is the primary hook for user creation side effects. Membership plugins use it to set up subscriptions, notification plugins use it to send welcome emails, and CRM integrations use it to create customer records. Every user WPfaker generates triggers this hook.

set_user_role fires when the user's role is assigned. Plugins that grant capabilities based on role, restrict content access, or trigger onboarding workflows based on the assigned role will all activate correctly.

When WPfaker sets custom user meta using update_user_meta(), the update_user_meta and updated_user_meta actions fire for each meta key.

INFO

WPfaker generates users with safe, non-deliverable email addresses using the @example.com domain (RFC 2606). This means that even though user creation hooks fire — including any email notification hooks — the notifications will not reach real inboxes. However, if your site uses a transactional email service that charges per send, be aware that WPfaker-generated users may still trigger email dispatch attempts.

Media & Image Hooks

When WPfaker downloads images from providers like LoremFlickr, Unsplash, or Picsum and imports them into the media library, it uses the standard WordPress attachment workflow:

wp_insert_attachment fires when the image file is registered as an attachment post in the database. Plugins that process new uploads — like image optimization services (ShortPixel, Imagify, Smush), watermarking plugins, or CDN upload handlers — will activate on WPfaker-imported images just as they would on manually uploaded files.

wp_generate_attachment_metadata fires when WordPress creates the thumbnail and intermediate image sizes defined by your theme and settings. This is a filter that lets plugins modify or extend the generated metadata. Image optimization plugins commonly hook here to compress the generated thumbnails.

add_attachment fires after the attachment is fully saved, making it the hook where post-upload processing typically occurs.

The images are stored in the standard wp-content/uploads directory structure, organized by year and month, and are fully visible in the Media Library. WordPress generates all registered image sizes (thumbnails, medium, large, and any custom sizes your theme defines) just as it would for a manual upload.

Deletion Hooks

When you delete generated content through WPfaker's History interface or the REST API, WPfaker uses the standard WordPress deletion functions:

wp_delete_post() fires before_delete_post and deleted_post for each post being removed. Plugins that clean up related data, remove cached pages, or log deletion events will trigger correctly. WPfaker passes $force_delete = true to bypass the trash and permanently delete posts, which also fires the delete_post action.

wp_delete_term() fires pre_delete_term and delete_{taxonomy} for each term. Plugins that maintain term relationship caches or synchronize taxonomies across systems will react to WPfaker deletions.

wp_delete_user() fires delete_user and deleted_user for each user. Membership plugins, CRM integrations, and audit logging systems will all register the user removal.

wp_delete_attachment() fires when related media is removed (controlled by the "Delete Related Media" option). Image optimization plugins that maintain external records of processed images will receive the deletion event and can clean up their own data.

WPfaker Custom Hooks

In addition to triggering all standard WordPress hooks, WPfaker provides its own action hooks and filter hooks that developers can use to extend or modify the plugin's behavior. These hooks power WPfaker's addon system, which allows third-party WordPress plugins to register custom field adapters, AI providers, and generation logic.

Actions

wpfaker_loaded — Fires when WPfaker is fully loaded and all contracts and services are available. This is the entry point for addons — any addon plugin must wait for this action before registering adapters or providers. Receives the WPfaker version string as its only parameter.

add_action('wpfaker_loaded', function (string $version) {
    // WPfaker is ready — register your extensions here
});

wpfaker_register_adapters — Fires inside the wpfaker_loaded lifecycle, signaling that it is time to register custom field plugin adapters via AdapterFactory::register().

add_action('wpfaker_register_adapters', function () {
    \WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);
});

wpfaker_register_ai_providers — Fires inside the wpfaker_loaded lifecycle, signaling that it is time to register custom AI providers via AiProviderFactory::register(). Custom providers automatically appear in the Settings AI provider dropdown.

add_action('wpfaker_register_ai_providers', function () {
    \WPFaker\Services\AiProviderFactory::register('my_ai', MyAiProvider::class, 'My AI Service');
});

wpfaker_activate — Fires when the WPfaker plugin is activated.

wpfaker_deactivate — Fires when the WPfaker plugin is deactivated. Receives a boolean indicating whether the user chose to delete all WPfaker data on deactivation.

wpfaker_after_generate_item — Fires after each post is generated. Receives the content type ('post'), the generated post ID, the current index, the total count, and the generation options array. This hook fires only for post generation, not for terms or users.

add_action('wpfaker_after_generate_item', function (string $type, int $id, int $index, int $total, array $options) {
    // React to each generated item — e.g. log progress
}, 10, 5);

wpfaker_after_generate — Fires after an entire batch of posts has been generated. Receives the content type ('post'), an array of all generated post IDs, and the generation options array. This hook fires only for post generation, not for terms or users.

add_action('wpfaker_after_generate', function (string $type, array $ids, array $options) {
    // React to completed batch — e.g. trigger reindex
}, 10, 3);

wpfaker_template_cpt_linked — Fires when a template's cross-CPT relationship field links to a target post type's template. Receives the template ID, the source post type, the target CPT slug, and the target template ID. WPfaker uses this internally to unlink sibling templates (other templates for the same post type that previously linked to the same target), ensuring only one template per post type holds a given cross-CPT link.

add_action('wpfaker_template_cpt_linked', function (int $templateId, string $postType, string $targetCpt, int $targetTemplateId) {
    // React to a template linking to a target CPT's template
}, 10, 4);

Filters

wpfaker_post_data — Modify the post data array before it is passed to wp_insert_post(). Receives the post data array, the post type slug, the current index, the total count, and the generation options array.

add_filter('wpfaker_post_data', function (array $postData, string $postType, int $index, int $total, array $options) {
    if ($postType === 'product') {
        $postData['post_status'] = 'draft';
    }
    return $postData;
}, 10, 5);

wpfaker_field_value — Modify a generated field value before it is saved to the database. Receives the generated value, the field config array, the post type slug, and the post ID.

add_filter('wpfaker_field_value', function ($value, array $config, string $postType, int $postId) {
    if ($config['name'] === 'price') {
        return round($value, 2);
    }
    return $value;
}, 10, 4);

wpfaker_adapter_priority — Change the order in which field plugin adapters are resolved. Receives an array of adapter keys sorted by priority.

add_filter('wpfaker_adapter_priority', function (array $priority) {
    // Make your adapter resolve first
    array_unshift($priority, 'my_plugin');
    return $priority;
});

wpfaker_field_name_detection_enabled — Controls whether WPfaker's automatic field name detection runs. Return false to disable pattern matching and AI detection entirely, forcing all fields to use default type-based generation. This can be useful in testing scenarios where you want predictable output without smart detection.

// Disable field name detection
add_filter('wpfaker_field_name_detection_enabled', '__return_false');

wpfaker_template_adapter_info — Modify the adapter information returned with template listings. Receives an associative array keyed by post type slug, where each entry contains fields (array of field names), taxonomies (array of taxonomy slugs), and adapters (array of adapter names). Addons use this filter to inject additional fields or adapter metadata into the template editor's field list.

add_filter('wpfaker_template_adapter_info', function (array $adapterInfo) {
    // Add custom fields for a post type
    if (isset($adapterInfo['product'])) {
        $adapterInfo['product']['fields'][] = 'my_custom_field';
        $adapterInfo['product']['adapters'][] = 'my_plugin';
    }
    return $adapterInfo;
});

wpfaker_generate_sub_tabs — Register additional sub-tabs in the generation interface. Addons use this filter to add their own generation panels alongside the built-in Posts, Taxonomies, Users, and Comments tabs. Return an array of tab definitions, each with an id and label key.

add_filter('wpfaker_generate_sub_tabs', function (array $tabs) {
    $tabs[] = [
        'id'    => 'my-addon',
        'label' => 'My Addon',
    ];
    return $tabs;
});

INFO

For a complete guide on building addons that use these hooks — including the full interface contracts for field adapters and AI providers — see the Addon Development guide.

Practical Implications

Understanding that WPfaker fires all WordPress hooks has several practical implications for your testing workflow.

Testing Plugin Integrations

If you are developing a plugin that reacts to content creation events — for example, a plugin that auto-generates PDF invoices when a "booking" post is published — you can use WPfaker to generate fifty booking posts in one batch and verify that fifty PDF invoices are created. You do not need to manually create each booking post to test the integration.

Performance Profiling

Because WPfaker triggers all hooks, generating a batch of posts exercises the same code paths as manual content creation. If your save_post handlers are slow, you will notice that WPfaker generation is slow too. This makes WPfaker generation time a useful proxy for measuring how your hook handlers perform under load. If generating 50 posts takes three minutes but image downloads only account for thirty seconds, the remaining time is spent in your hooks — and that is valuable profiling information.

Cache Warming and Invalidation

Caching plugins that invalidate or warm caches on content changes will react to WPfaker-generated content. If you are testing a caching strategy, generating a batch of posts with WPfaker exercises the cache invalidation logic in a way that manual testing with one or two posts cannot. You can verify that your cache handles bulk content creation gracefully without memory exhaustion or excessive purge operations.

SEO and Metadata Generation

SEO plugins like Yoast SEO, Rank Math, or The SEO Framework that generate meta descriptions, Open Graph tags, or schema markup on post save will process WPfaker-generated posts. This lets you verify that your SEO configuration produces correct output across a variety of content structures, including posts with different title lengths, content lengths, featured image states, and taxonomy assignments.

Email and Notification Testing

Plugins that send emails or notifications on content events will fire on WPfaker-generated content. While WPfaker uses safe @example.com email addresses for generated users, notification plugins that email administrators or content managers about new posts will still attempt to send. If you are generating large batches and your site has aggressive notification settings, you may want to temporarily disable notification plugins or use a mail-trapping service like Mailpit during generation.

WARNING

Because all hooks fire during generation, be mindful of plugins that perform expensive operations on save_post or wp_insert_post. If you have a plugin that calls an external API for every new post, generating 100 posts will trigger 100 API calls. Consider temporarily disabling such plugins during bulk generation if the hook behavior is not part of what you are testing.