DEV Community: Webequipe

One Plugin, Every Client Stack: Building a Universal WordPress Webhook Adapter

Webequipe — Tue, 18 Aug 2026 09:08:39 +0000

A client asked me for something simple a while back: send a Telegram message every time someone fills out their contact form. Another client had a HubSpot connection that wasn't behaving, so we ended up routing everything through Zapier first, then into HubSpot from there — easier to debug that way anyway. A third wanted Slack pinged on WooCommerce events, different channels depending on whether it was a new order, a refund, or a cancellation.

Three clients, three completely different destinations, but the same underlying job every time: something happens on WordPress, and it needs to go somewhere else automatically. I was rebuilding this by hand often enough that it stopped making sense not to build it properly once.

Most plugins that do this kind of thing hard-code support for specific plugins — CF7 today, WPForms next month, LearnDash whenever someone asks enough times. You're always one release behind whatever your client happens to be running. I wanted something that didn't have that ceiling.

Dedicated adapters where the payload actually needs cleanup. Contact Form 7, WPForms, Fluent Forms, Ninja Forms, Formidable Forms, and WooCommerce each get their own adapter. These plugins pass messy native objects full of nonces, reCAPTCHA tokens, and internal metadata mixed in with the real submission data — without cleanup, the payload is basically unusable. Each adapter strips that noise and hands back clean, labeled fields.

A generic adapter for literally everything else. This is the part that actually solves the ceiling problem. Instead of writing a new adapter every time a client uses some plugin I've never heard of, there's one listener:

add_action( $hook_name, function() {
    $args    = func_get_args();           // catch all arguments
    $payload = $this->serialize( $args ); // normalize to array
    $this->dispatch( $payload );          // send to webhook
}, 10, PHP_INT_MAX ); // accept any number of arguments

PHP_INT_MAX as the accepted-argument count means it captures every argument a hook fires, no matter which plugin fires it. Point it at learndash_course_completed, a membership plugin's renewal hook, or something from a plugin that doesn't exist yet — it just works.

Raw hook arguments aren't that useful on their own, though. user_id = 42 doesn't tell you much by itself. So there's a serialization layer that flattens known WordPress types (WP_Post, WP_User, WP_Term, anything exposing get_data()) into safe common fields, and — the part I like most — attaches a companion expanded object for documented ID arguments. user_id gets a full userobject with email, login, and roles attached automatically. Undocumented integer arguments even get a best-effort resolve against posts/users/terms/orders, so an unlabeled hook argument usually still returns something usable instead of a bare number.

There's also a small data-only dictionary of known WordPress core hooks with pre-documented field names, purely for UI discoverability — no logic in it, just labels so the dropdown makes sense.

End result: the handful of plugins that genuinely need clean-payload treatment get it, and everything else — any LMS, any membership tool, any custom hook, anything built after this ships — is covered without writing new code for it.

It's free and live on WordPress.org if you want to see it in action.

The WordPress Excerpt Filter Isn't Universal — A Debugging Story

Webequipe — Mon, 17 Aug 2026 11:57:39 +0000

A support ticket landed recently that looked, on the surface, like a rendering bug: a plugin's search results were showing up as literal HTML tags on the page instead of a nicely formatted result card. <div class="entry-summary"> and friends, printed right there as visible text, as if the browser had simply given up on parsing the markup.

It turned out to be a much more interesting bug than "the HTML is broken." It's a compatibility gap that quietly affects any WordPress plugin that tries to inject rich HTML into a search result excerpt — and it's worth understanding if you've ever built a plugin that hooks into the_excerpt().

The setup

The plugin in question indexes PDF files and injects them into WordPress search results, alongside your regular posts and pages. When a PDF matches a search, it needs to show more than a plain title: a thumbnail preview, the file size, the page count, a highlighted snippet of matching text. None of that fits into what WordPress expects an excerpt to contain, which is, by convention, plain text.

So the plugin does what a lot of plugins do: it hooks get_the_excerpt, the_excerpt, the_content, and wp_trim_words, and on those hooks it builds up a chunk of HTML — a <div> or <span> wrapper with meta info, an <img> preview, <mark> tags around the matched keywords — and returns that HTML as the "excerpt." As long as the active theme calls WordPress's own the_excerpt()/get_the_excerpt() functions to render that region of the page, the browser receives real markup and renders it as intended.

The plugin's changelog showed real engineering effort here — explicit compatibility fixes for Astra, Divi, Avada, and Elementor, plus block-theme support via render_block. Each of those required understanding how that specific theme reaches into the post data to build its search result cards. That's the part that doesn't get talked about enough: "supports WordPress" and "supports every theme's excerpt rendering path" are not the same claim.

Where it broke

One popular multipurpose theme wasn't on that compatibility list, and a customer running it hit exactly the bug described above. Digging into the theme's helper functions turned up the reason, and it's not unique to this theme — it's a pattern worth watching for in general.

Many big, feature-rich WordPress themes don't just call the_excerpt() and trust WordPress's own excerpt pipeline. They ship their own excerpt generator — a theme-specific function that reads post_excerpt or post_content directly, truncates it to a target length, and outputs it. This is usually done for good reasons: consistent excerpt lengths across templates, custom "read more" behavior, support for excerpts on custom post types that don't behave well with the default logic.

The problem is that a custom excerpt generator like this typically assumes its input is plain text. So it does something like:

$raw = get_post_field( 'post_content', $post_id );
$trimmed = wp_trim_words( $raw, $length );
echo esc_html( $trimmed );

That esc_html() call is completely reasonable if the source is plain text. It's a defensive habit — never trust unescaped content into the page. But when the input already contains real HTML markup (because a plugin built it for exactly that purpose), esc_html() converts every < and > into < and >. The server sends valid entities, the browser dutifully renders them as literal text, and you get exactly the symptom from the support ticket: a page full of visible tag soup where a nicely formatted card should be.

Crucially, this bypasses the plugin entirely. The plugin's hooks on get_the_excerpt and the_excerpt never fire, because the theme isn't calling those WordPress functions — it has its own code path. All the careful Astra/Divi/Avada/Elementor compatibility work in the world doesn't help, because those fixes assume the theme is at least going through the standard filter chain somewhere.

The general lesson

If you're building a WordPress plugin that needs to output HTML through what is conventionally a plain-text field — excerpts are the classic example, but this also applies to things like post titles, meta descriptions, or any "summary" field a theme might touch — keep three things in mind:

The excerpt filter chain is a convention, not a contract. get_the_excerpt, the_excerpt, and wp_trim_words are the standard way WordPress themes render excerpts, and most themes use them. But nothing forces a theme to. Popular multipurpose and page-builder-adjacent themes especially tend to reimplement this logic for extra control, and when they do, your filters simply never run.

"It works in theme X" doesn't generalize. Compatibility with WordPress core's rendering pipeline isn't the same as compatibility with a given theme's rendering pipeline. If your plugin injects HTML into what's normally plain-text territory, budget for theme-specific escape hatches — a filter your users (or you) can hook to redirect a theme's custom excerpt function back to the_excerpt(), for example.

When something you expect to be markup shows up as literal tag text on the page, suspect double-escaping before you suspect a rendering bug. The moment you see <div class=...> printed as visible characters rather than parsed as an element, the underlying cause is almost always esc_html() (or an equivalent) being applied to a string that already contains real HTML — not malformed markup, not a browser quirk. Check the page source directly: if you see <div...> in the raw response, that confirms it immediately.

Why this matters beyond one plugin

This class of bug is a nice reminder that WordPress's plugin/theme ecosystem is held together by conventions that are easy to assume are guarantees. The the_excerpt() filter chain has been part of WordPress for well over a decade, and it's tempting to treat it as a stable, universal integration point. For the vast majority of themes, it is. But "vast majority" isn't "all," and the exceptions tend to be exactly the themes with the largest install bases — the ones that ship enough custom functionality to need their own take on something as basic as an excerpt.

If you maintain a plugin that hooks core content filters to inject rich output, it's worth explicitly testing against a handful of the biggest multipurpose themes, not just the block-theme defaults — and building in an extension point so users (or you, later) can patch the gap without waiting for a plugin update.

Have you run into a similar "my HTML got escaped because the theme has its own renderer" bug? I'd be curious to hear which theme did it to you — drop it in the comments.

Indexing Large PDFs Without Timing Out: Background Processing with WP-Cron

Webequipe — Fri, 31 Jul 2026 11:05:41 +0000

The first version of our indexing code did exactly what you'd expect: a PDF gets uploaded, a hook fires, we parse the whole file, we store the text. Simple, and it worked fine — right up until someone uploaded a 300-page scanned course catalog and the request just… never finished.

What we started with

add_action( 'add_attachment', 'webequipe_index_pdf_on_upload' );

function webequipe_index_pdf_on_upload( $attachment_id ) {
    $file = get_attached_file( $attachment_id );

    if ( pathinfo( $file, PATHINFO_EXTENSION ) !== 'pdf' ) {
        return;
    }

    $parser = new \Smalot\PdfParser\Parser();
    $pdf    = $parser->parseFile( $file );
    $text   = $pdf->getText(); // fine for a 5-page PDF, not for a 300-page one

    webequipe_store_pdf_text( $attachment_id, $text );
}

For a handful of pages this runs in under a second. For a large, text-heavy file it can easily blow past PHP's max_execution_time — 30 seconds by default, and often less on shared hosting. When that happens, the request just gets killed mid-parse. Worst part: this was firing synchronously on the upload request itself, so the admin uploading the file was the one sitting there watching it hang.

Bumping max_execution_time isn't a real fix. A lot of hosts don't let you override it at all, and even where you can, you're still tying up one PHP worker for the entire parse — which gets worse, not better, the moment two people upload large PDFs at the same time.

The actual fix: stop trying to do it all at once

Instead of parsing the whole file in one request, we split the work into small chunks and let WP-Cron pick them up one at a time in the background.

Step one — on upload, just queue it. Don't parse anything yet.

add_action( 'add_attachment', 'webequipe_queue_pdf_for_indexing' );

function webequipe_queue_pdf_for_indexing( $attachment_id ) {
    $file = get_attached_file( $attachment_id );

    if ( pathinfo( $file, PATHINFO_EXTENSION ) !== 'pdf' ) {
        return;
    }

    webequipe_set_status( $attachment_id, 'scheduled' );

    if ( ! wp_next_scheduled( 'webequipe_process_pdf_chunk', array( $attachment_id ) ) ) {
        wp_schedule_single_event( time() + 10, 'webequipe_process_pdf_chunk', array( $attachment_id ) );
    }
}

The upload request now finishes instantly. The actual parsing hasn't started — it's just been scheduled.

Step two — the cron job processes a fixed number of pages, then reschedules itself if there's more to do.

define( 'WEBEQUIPE_PAGES_PER_RUN', 20 );

add_action( 'webequipe_process_pdf_chunk', 'webequipe_process_pdf_chunk_handler' );

function webequipe_process_pdf_chunk_handler( $attachment_id ) {
    $file   = get_attached_file( $attachment_id );
    $offset = (int) get_post_meta( $attachment_id, '_webequipe_page_offset', true );

    webequipe_set_status( $attachment_id, 'processing' );

    $parser = new \Smalot\PdfParser\Parser();
    $pdf    = $parser->parseFile( $file );
    $pages  = $pdf->getPages();
    $total  = count( $pages );

    $end = min( $offset + WEBEQUIPE_PAGES_PER_RUN, $total );

    for ( $i = $offset; $i < $end; $i++ ) {
        webequipe_store_page_text( $attachment_id, $i + 1, $pages[ $i ]->getText() );
    }

    update_post_meta( $attachment_id, '_webequipe_page_offset', $end );

    if ( $end < $total ) {
        wp_schedule_single_event( time() + 5, 'webequipe_process_pdf_chunk', array( $attachment_id ) );
    } else {
        webequipe_set_status( $attachment_id, 'indexed' );
        delete_post_meta( $attachment_id, '_webequipe_page_offset' );
    }
}

Twenty pages at a time, every few seconds, until the whole document is indexed. No single request ever does enough work to risk a timeout, no matter how large the file is.

One honest caveat on the snippet above: re-parsing the entire PDF on every chunk just to reach the next offset is wasteful for very large files — in practice you'd want to cache the parsed object or extract page references once rather than re-running parseFile() on every cron tick. I simplified that part here to keep the example readable; it's the kind of optimization that matters more once you're indexing hundreds of large files a day than it does for a single one.

Tracking progress so the admin isn't guessing

None of this is useful if nobody can tell what's actually happening to their file. We track status per attachment in a dedicated table rather than relying on post meta alone:

CREATE TABLE {$wpdb->prefix}webequipe_pdf_search_files (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    attachment_id BIGINT UNSIGNED NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'not_indexed',
    total_pages INT UNSIGNED DEFAULT 0,
    indexed_pages INT UNSIGNED DEFAULT 0,
    updated_at DATETIME NOT NULL,
    KEY attachment_id (attachment_id)
);

That status column is what powers the Manage PDFs screen — every file sits in one of: Not Indexed, Scheduled, Processing, Indexed, Stalled, Error, or Excluded. "Stalled" specifically exists to catch the case where a scheduled cron event never actually ran — which brings up the one WP-Cron quirk worth knowing about.

WP-Cron isn't a real cron

WordPress's cron system doesn't run on a timer in the background the way a system cron job does — it only fires when someone visits the site. On a low-traffic site, that means a scheduled indexing job can sit waiting for a while if nobody happens to load a page.

For anything beyond small personal sites, we point people toward disabling WP-Cron's default trigger and hitting wp-cron.php on a real system cron instead:

// wp-config.php
define( 'DISABLE_WP_CRON', true );

bash

# real system cron, every 5 minutes
*/5 * * * * curl -s https://example.com/wp-cron.php > /dev/null 2>&1

It's a small config change, but it's the difference between "indexing happens promptly" and "indexing happens whenever someone next visits the site."

What this actually bought us

Visitors never notice any of this — search queries run against whatever's already been indexed, and indexing itself never touches a front-end page load. On the admin side, even a huge scanned archive just ticks along in the background instead of hanging a browser tab or silently failing halfway through.

The bigger lesson generalizes past PDFs, honestly: if a task's runtime scales with user-supplied input — file size, record count, whatever — assuming one request can always finish it is asking for a timeout eventually. Chunking with an explicit, inspectable progress state turned out to be a lot more robust than just hoping the PHP process would have enough time.