DEV Community: Webequipe

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.

Why Testing Our WordPress Plugin on One Website Wasn’t Enough

Webequipe — Thu, 23 Jul 2026 11:58:32 +0000

When we first tested our WordPress PDF search plugin, everything worked as expected.

We installed it on a clean WordPress website, added the search form using a shortcode, uploaded several PDFs, and tested the full process.

The form looked good.

The search button worked.

The results appeared correctly.

From our side, the feature looked ready.

Then we tested the plugin on another WordPress website using the Avada theme.

The search form appeared, but the layout was broken. The search button moved below the input field, some styles were overwritten, and in certain layouts the form width became much smaller than expected.

The plugin was working, but it did not feel like a working product.

That was when we learned an important lesson:

A WordPress plugin is not really tested until it has been tested outside the environment where it was developed.

The Issue We Found

Our PDF search form was added using a shortcode.

A website administrator could place something like this on any page:
[webequipe_pdf_search_form]
The shortcode generated a simple search form with:

A search input
A search button
A results container

On our test website, the input and button appeared in one row.

But on the Avada website, the theme’s global form styles affected our plugin.

Avada already included CSS rules for form inputs, buttons, containers, and responsive layouts. Some of those styles were more specific than our plugin styles, so the theme rules took priority.
The result looked something like this:

The input inherited an unexpected height
The button received theme padding
The button width changed
The form container inherited a maximum width
Mobile styles were triggered earlier than expected

This was not a PHP error or a fatal WordPress error.

It was a compatibility issue.

And from a customer’s point of view, a broken layout is still a plugin problem.

The Biggest Mistake in Our Code

Our original CSS was too general.

We used selectors like this:

.pdf-search-form { 
  display: flex; 
  gap: 10px; 
} 
.pdf-search-form input { 
  width: 100%; 
  padding: 12px; 
} 
.pdf-search-form button { 
  padding: 12px 20px; 
}

This worked on a basic WordPress theme.

But it created two problems.

First, the class name was not specific enough. Another theme or plugin could use a similar class name.

Second, our selectors were weaker than some theme selectors.

A theme might use a rule like:

.fusion-body .post-content input[type="search"] {
   height: 50px; 
   border-radius: 0; 
}

Because that selector was more specific, it could override our plugin styling.

Our code was not technically incorrect.

But it assumed that the plugin would control the page styling.

In WordPress, that assumption is risky.

How We Investigated the Problem

At first, we checked whether the shortcode output was different.

It was not.

The same HTML was generated on both websites.

Then we checked whether JavaScript was failing.

There were no console errors.

Next, we inspected the form using the browser developer tools.

That showed us the real issue.

Several styles were coming from the Avada theme instead of our plugin stylesheet.

We tested the same plugin with a default WordPress theme, and the form worked correctly again.

That confirmed that the problem was not the shortcode or search logic. It was the CSS interaction between the plugin and the theme.

How We Fixed It

We updated the plugin to use a unique wrapper class.

Instead of relying only on a general form class, we wrapped the full shortcode output inside a plugin-specific container.

function webequipe_render_pdf_search_form() {
    ob_start();
    ?>
    <div class="webequipe-pdf-search">
        <form class="webequipe-pdf-search__form" method="get">
            <input
                type="search"
                name="pdf_search"
                class="webequipe-pdf-search__input"
                placeholder="Search PDFs..."
            >

            <button
                type="submit"
                class="webequipe-pdf-search__button"
            >
                Search
            </button>
        </form>

        <div class="webequipe-pdf-search__results"></div>
    </div>
    <?php

    return ob_get_clean();
}

add_shortcode(
    'webequipe_pdf_search_form',
    'webequipe_render_pdf_search_form'
);

Then we updated the CSS to target only elements inside our plugin.

.webequipe-pdf-search {
    width: 100%;
    max-width: 100%;
}

.webequipe-pdf-search .webequipe-pdf-search__form {
    display: flex;
    align-items: stretch;
    width: 100%;
    gap: 10px;
    margin: 0;
}

.webequipe-pdf-search .webequipe-pdf-search__input {
    flex: 1;
    width: auto;
    min-width: 0;
    height: 48px;
    margin: 0;
    padding: 10px 14px;
    box-sizing: border-box;
}

.webequipe-pdf-search .webequipe-pdf-search__button {
    width: auto;
    min-width: 110px;
    height: 48px;
    margin: 0;
    padding: 10px 18px;
    box-sizing: border-box;
    cursor: pointer;
}

@media screen and (max-width: 600px) {
    .webequipe-pdf-search .webequipe-pdf-search__form {
        flex-direction: column;
    }

    .webequipe-pdf-search .webequipe-pdf-search__button {
        width: 100%;
    }
}

This made the styles more specific without depending on Avada itself.

We did not add code such as:

.avada-theme .pdf-search-form {
    /* Avada-specific fix */
}

That would have solved only one theme problem.
Instead, we improved the plugin’s own CSS structure so it would be safer across many themes.

We Also Changed How the Styles Were Loaded

Previously, the stylesheet was loaded everywhere.

We improved this by loading the required assets when the shortcode was used.

function webequipe_pdf_search_shortcode() {
    wp_enqueue_style(
        'webequipe-pdf-search',
        plugin_dir_url(__FILE__) . 'assets/css/pdf-search.css',
        array(),
        '1.0.1'
    );

    return webequipe_render_pdf_search_form();
}

add_shortcode(
    'webequipe_pdf_search_form',
    'webequipe_pdf_search_shortcode'
);

This helped us keep the plugin assets connected to the feature that needed them.

It also reduced the chance of unnecessary styles affecting other parts of the website.

How We Tested the Fix

After updating the code, we did not test it only on the same development website.

We checked the shortcode on:

A clean WordPress installation
A website using Avada
A website using Elementor
A default WordPress block theme
Desktop, tablet, and mobile screen sizes
Pages with narrow and full-width containers

We also tested the form inside different page sections.

That was important because the same theme can behave differently depending on whether the shortcode is placed inside a full-width section, column, widget area, or normal content area.

What We Learned

The biggest lesson was not that Avada caused a problem.

Avada was doing what a WordPress theme normally does: applying consistent styles across the website.

The real issue was that our plugin was not isolated enough from the surrounding website.

We learned a few important things from this:

Use unique names

Plugin classes, CSS selectors, functions, hooks, and database keys should use a unique prefix.

A general name may work today but conflict with another theme or plugin later.

Test inside real page builders

A shortcode should not only be tested inside the standard WordPress editor.

It should also be tested inside popular themes and page builders where users are likely to place it.

Do not test only functionality

The search feature technically worked on the Avada website.

But the layout problem still affected the customer experience.

Plugin QA should include both functionality and visual behaviour.

Avoid theme-specific fixes when possible

Adding separate fixes for every theme can become difficult to maintain.

It is usually better to strengthen the plugin’s own structure first.

One WordPress website is only one environment

A successful test on one website does not prove that a plugin is ready for every WordPress website.

Each site may have a different theme, page builder, CSS structure, plugin combination, PHP version, and hosting setup.

Final Thought

WebEquipe PDF Search did not fail because its PDF indexing or search logic was broken.

The issue appeared because we had tested the search form in an environment that was too controlled. Once we placed the same shortcode on a website using the Avada theme, we saw how easily theme styles could affect the plugin’s layout.

This experience changed how we test WebEquipe PDF Search.

We now understand that building a WordPress plugin is not only about making its main feature work. It is also about making sure that feature continues to work across themes, page builders, screen sizes, and website configurations we do not control.

A successful test on our development website is no longer the end of QA.

For WebEquipe PDF Search, it is only the beginning.

How to Audit PDF Content on a WordPress Site Before Improving Search

Webequipe — Thu, 16 Jul 2026 10:28:16 +0000

Sure, this topic is better for dev.to. Here is the blog draft:

How to Audit PDF Content on a WordPress Site Before Improving Search

Many WordPress sites have PDF files.

Some have only a few brochures or forms.
Some have hundreds of documents, reports, manuals, policies, notices, or guides.

But before improving PDF search, one important step is often skipped:

Auditing the PDF content first.

Because not every PDF problem is a search problem.

Sometimes the issue is poor file naming.
Sometimes PDFs are scanned and need OCR.
Sometimes important documents are uploaded but not linked from any page.
Sometimes private files are accidentally public.

A simple audit helps you understand what you actually need.

1. Check how many PDFs exist

Start with the basic question:

How many PDFs are uploaded to the WordPress media library?

If you are a developer, you can quickly check PDF attachments like this:

$pdfs = get_posts([
    'post_type'      => 'attachment',
    'post_mime_type' => 'application/pdf',
    'post_status'    => 'inherit',
    'posts_per_page' => -1,
]);

echo 'Total PDFs found: ' . count($pdfs);

If the number is small, you may only need better page links and titles.

If the number is large, you probably need a proper document search experience.

2. Review file names

Bad file names make PDFs harder to manage.

Examples of weak names:

file-final.pdf
document-new.pdf
scan-123.pdf
updated-copy.pdf

Better names:

employee-handbook-2026.pdf
product-safety-manual.pdf
annual-report-2025.pdf
refund-policy.pdf

Good file names help admins, developers, and users understand the document faster.

3. Check if PDFs are text-based or scanned

This is one of the most important audit steps.

Open a PDF and try to select the text.

If you can select and copy the words, it is probably a text-based PDF.

If you cannot select the words, it may be a scanned PDF.

Simple rule:

Text can be copied → text-based PDF
Text cannot be copied → scanned PDF, OCR may be needed

This matters because text-based PDFs are easier to index.
Scanned PDFs usually need OCR before they become searchable.

Find important but hidden PDFs

A PDF can be uploaded to WordPress but still be hard to find.

Ask:

Is this PDF linked from any page?
Is it part of a document library?
Does the page explain what the PDF contains?
Can users find it without knowing the exact file name?

A PDF should not only be a download link. It should have context.

Example:

<h2>Product Safety Manual</h2>
<p>Includes setup instructions, safety rules, and maintenance notes.</p>
<a href="/uploads/product-safety-manual.pdf">View PDF</a>

This is better than only saying:

<a href="/uploads/file.pdf">Download</a>

5. Check private or restricted PDFs

Not every PDF should be public.

Some websites have private documents for members, staff, students, or customers.

During the audit, check:

Which PDFs should be public?
Which PDFs should be private?
Are private PDFs appearing in public search results?
Are restricted PDFs protected properly?

This is very important for membership sites, internal portals, schools, healthcare sites, and organizations with private documents.

6. Check what users are actually searching for

Before changing search, try to understand user needs.

Look at:

common support questions
site search logs, if available
popular document pages
frequently downloaded PDFs
repeated questions from users

This helps you decide which PDFs are most important to make searchable first.

7. Decide what kind of PDF search you need

After the audit, you can make a better decision.

For example:

Where WebEquipe PDF Search fits

For WordPress sites with many PDFs, WebEquipe PDF Search can help make PDF content searchable.

It can index text-based PDFs and let users search inside PDF content using a shortcode search form.

For scanned PDFs, OCR support is needed, which is part of the Pro workflow.

The main goal is simple:

Help users find the information inside PDFs, not just the PDF file itself.

Final checklist

Before improving PDF search on a WordPress site, check:

✅ How many PDFs are uploaded?
✅ Are file names clear?
✅ Are PDFs text-based or scanned?
✅ Are important PDFs linked from pages?
✅ Are private PDFs protected?
✅ What are users searching for?
✅ Do you need normal indexing, OCR, or private search?

Final thought

Improving PDF search is not only about adding a search box.

First, you need to understand your PDF content.

A simple audit can show whether your site needs better organization, OCR, private search, or full PDF indexing.

Once you know that, improving search becomes much easier — and much more useful for your users.

AI Agents Can Read Your Website — But Can They Read Your PDF

Webequipe — Thu, 09 Jul 2026 07:02:31 +0000

Websites are changing.

A few years ago, we mainly cared about human visitors and Google search. Now we also need to think about AI search tools, chatbots, RAG systems, and AI agents that read website content to answer questions.

But there is one problem many WordPress sites still ignore:

A lot of important content is locked inside PDFs.

And if that PDF content is not searchable or properly indexed, users may never find it.

PDFs Are Not Just Attachments

Many websites upload PDFs for things like:

manuals
reports
policy documents
forms
product guides
public notices
documentation
brochures

The problem is that most site owners treat these PDFs like simple downloadable files.

But if the PDF contains useful information, then it is not just a file.

It is part of your website content.

For example, a visitor may search: refund policy for international orders

Maybe the answer exists inside a PDF. But if your WordPress search cannot read inside that PDF, the visitor gets no result.

From the user’s point of view, the content does not exist.

AI Agents Have the Same Problem

AI tools are becoming better at reading web pages. But a random PDF link is not always enough.

An AI agent or chatbot needs clear, accessible, searchable content.

If your important information is inside a PDF but not extracted or indexed, then your site creates a gap:

Website pages = readable
PDF files = often hidden
Search result = incomplete
AI answer = missing context

This is a bigger issue for websites that depend on documents, such as universities, government websites, nonprofits, healthcare sites, legal sites, SaaS documentation, and product manual libraries.

Text PDFs vs Scanned PDFs

Not all PDFs are the same.

There are usually three types:

Text-based PDFs
These PDFs contain selectable text. The text can usually be extracted and indexed.
Scanned PDFs
These are basically images inside a PDF. You cannot properly search them unless OCR is used.
Mixed PDFs
Some pages have text, and some pages are scanned images.

This matters because your search system must understand what kind of PDF it is handling.

A simple text PDF may only need text extraction.
A scanned PDF needs OCR.

A Quick WordPress Check

If you are a developer, you can quickly check how many PDFs exist on a WordPress site:

$pdfs = get_posts([
    'post_type'      => 'attachment',
    'post_mime_type' => 'application/pdf',
    'post_status'    => 'inherit',
    'posts_per_page' => -1,
]);

echo 'Total PDFs found: ' . count($pdfs);

If the number is high, then your site probably has a lot of hidden content.

The next question is:

Can users actually search inside those PDFs?

Make PDFs More Useful

A better document structure can help both users and AI systems.

Instead of only adding a plain PDF link like this:

<a href="/files/safety-manual.pdf">Download PDF</a>

Add context around it:

<article class="document-card">
  <h2>Product Safety Manual</h2>
  <p>
    Includes installation steps, safety warnings,
    and maintenance instructions.
  </p>
  <a href="/files/safety-manual.pdf">View PDF</a>
</article>

This helps users understand the document before opening it.
It also gives search engines and AI tools better context.

A Simple PDF Search Workflow

A useful PDF search system should work like this:

PDF uploaded ↓ Text extracted or OCR processed ↓ Content indexed ↓ User searches from WordPress ↓ Relevant PDF result appears

That is the missing layer in many WordPress websites.

Where WebEquipe PDF Search Fits

For WordPress sites, a plugin like WebEquipe PDF Search can help make PDF content searchable.

You can add a PDF search form using a shortcode like:

[webequipe_pdf_search_form placeholder="Search PDFs..." button_text="Search" results_per_page="10"]

The free version is useful for text-based PDFs.
For scanned PDFs, OCR support is needed, which is where a Pro/OCR workflow becomes important.

The goal is not only to “search files.”

The real goal is to make PDF content part of the website experience.

Final Thought

AI agents, chatbots, and modern search tools are changing how people find information.

But if your most valuable content is hidden inside PDFs, your website may look complete while still being difficult to search.

So before adding another AI tool to your WordPress site, ask one simple question:

Can users — and AI systems — actually read what is inside your PDFs?

Why PDF Indexing in WordPress Needs Background Processing

Webequipe — Fri, 03 Jul 2026 06:20:24 +0000

Uploading a PDF to WordPress feels simple.

You add the file to the Media Library, WordPress stores it, and the file is ready to use.

But if you want that PDF to become searchable, the work does not stop at upload.

The plugin has to read the PDF, extract the text, clean the content, store it in a searchable index, and later match that content with user search queries.

That sounds fine for one small PDF.

But what happens when the file has 100 pages?

Or when the website has hundreds of PDFs?

Or when the PDF is scanned and needs OCR?

That is where background processing becomes important.

PDF Indexing Is Heavier Than Normal WordPress Tasks

Most WordPress content is already stored in the database.

When you publish a post, the title and body content are saved in fields like post_title and post_content. Search can query that data directly.

PDFs are different.

A PDF is a file. WordPress stores the file information, but it does not automatically read the actual text inside that file.

So a PDF search plugin needs to do extra work:

For a small text-based PDF, this may happen quickly.

But large files can take more time. Some PDFs have complex layouts, repeated headers, tables, images, or broken text structure. Scanned PDFs are even heavier because they need OCR before any text can be indexed.

Trying to do all of this instantly during upload is risky.

The Problem With Processing During Upload

When a user uploads a PDF, WordPress is handling that request in real time.

If your plugin starts parsing a large PDF immediately, several things can go wrong:

The upload request may become slow
PHP execution time may run out
Memory usage may increase
The admin screen may freeze
OCR processing may take too long
The user may not know whether indexing succeeded or failed

This creates a bad experience.

The user only wanted to upload a document. They should not have to wait while the system tries to fully process a 200-page PDF in the same request.

That is why PDF indexing should be treated as a background job, not an upload-time task.

A Better Flow: Queue the Work

A more reliable approach is to separate file upload from file processing.

The upload should stay fast. After upload, the plugin creates an indexing job and processes it later.

A simple flow looks like this:

This makes the system much easier to manage.

Instead of forcing everything to happen immediately, the plugin can process PDFs one by one in the background.

For example, the plugin can store a job like this:

[
    'attachment_id' => 245,
    'status'        => 'pending',
    'type'          => 'text_extraction',
    'attempts'      => 0,
    'created_at'    => current_time('mysql'),
]

Then a background worker can pick up pending jobs and process them safely.

Status Tracking Matters

Background processing also makes status tracking possible.

A PDF can move through states like:

pending
processing
indexed
ocr_required
failed

This is useful for admins.

Without status tracking, users have no idea what happened. A PDF may be uploaded, but not searchable. Or OCR may fail silently. Or the file may be too large to process.

A clear status helps users understand the situation.

For example:

“Pending” means the file is waiting to be processed
“Processing” means indexing is running
“Indexed” means the PDF is searchable
“OCR required” means normal text extraction found little or no text
“Failed” means the job needs attention or retry

This makes the plugin feel more predictable.

OCR Makes Background Processing Even More Important

Text-based PDFs can often be processed with a parser.

Scanned PDFs are different.

A scanned PDF is basically an image inside a PDF file. A normal parser may return empty content because there is no text layer.

In that case, OCR is needed.

OCR usually means:

Convert PDF page to image
↓
Send image to OCR engine
↓
Receive detected text
↓
Store text in search index

This is much heavier than normal text extraction.

If the plugin uses an external OCR service like Google Vision API, the processing time also depends on API response time, page count, network conditions, and retry handling.

Running this during upload is not a good idea.

A queue-based system gives the plugin room to process OCR safely without breaking the admin experience.

Retry Logic Helps With Real-World Failures

Background jobs can fail for many reasons.

The file may be corrupted.
The server may run out of memory.
The OCR API may timeout.
The PDF parser may fail on a strange file structure.

Instead of failing permanently, the plugin can retry the job.

For example:

if ($job['attempts'] < 3) {
    retry_indexing_job($job['id']);
} else {
    mark_job_as_failed($job['id']);
}

This makes the system more resilient.

Not every failure needs to become a support issue. Some failures can be retried automatically.

Final Thoughts

PDF search looks simple from the outside.

A visitor searches, and a PDF appears in the result.

But behind that simple experience, the plugin has to extract content, detect scanned files, run OCR when needed, store searchable text, and handle failures.

That is why background processing matters.

It keeps uploads fast.
It avoids PHP timeout issues.
It makes OCR manageable.
It allows status tracking.
It gives the system a way to retry failed jobs.

For WebEquipe PDF Search, this kind of thinking is important because PDF indexing is not just a search feature. It is a processing pipeline.

And when a WordPress plugin handles heavy file processing, the best experience is usually the one users do not have to wait for.

Why WordPress Search Ignores Your PDFs — and How to Fix It

Webequipe — Thu, 25 Jun 2026 11:41:45 +0000

WordPress search works well when your content lives inside posts and pages.

But if important information is inside PDF files, WordPress often misses it completely.

A visitor may search for a phrase that clearly exists inside a PDF manual, report, form, or policy document. But WordPress returns no result.

The PDF is uploaded.
The content exists.
But search still cannot find it.

So why does this happen?

WordPress Search Does Not Read PDF Content

Default WordPress search mainly checks database fields like:

post_title
post_content
post_excerpt

When you publish a post, the content is stored in post_content, so WordPress can search it.

But when you upload a PDF, WordPress treats it as a media attachment. It stores the file title, URL, MIME type, upload date, and some metadata.

What it does not do by default is open the PDF, read the text inside it, and save that text into post_content.

So this kind of situation is common:

PDF file: employee-handbook.pdf
Text inside PDF: "Remote work requests must be approved by HR"
WordPress searchable content: filename and attachment data only
Search query: "remote work requests"
Result: no match

The text is inside the file, but not inside the database fields WordPress normally searches.

That is the main reason PDF search fails.

Not All PDFs Are the Same

Before fixing PDF search, you need to understand one important difference.

There are two common types of PDFs:

Text-based PDFs
Scanned PDFs

They may look the same in the browser, but technically they behave very differently.

Text-Based PDFs

A text-based PDF contains real selectable text.

If you can open a PDF, select a sentence, copy it, and paste it into a text editor, it probably has a text layer.

These PDFs are usually exported from tools like Word, Google Docs, InDesign, or reporting software.

For these files, a plugin can use a PDF parser to extract the text.
In PHP, one common library is smalot/pdfparser.

use Smalot\PdfParser\Parser; 
$parser = new Parser(); 
$pdf = $parser->parseFile($file_path); 

$text = $pdf->getText(); 
if (! empty($text)) { 
// Store extracted text for search 
}

After extraction, the text needs to be stored somewhere searchable.

For small use cases, post meta may work. But for better control and performance, a custom database table is usually better.

Example:

CREATE TABLE wp_pdf_search_index ( 
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, 
  attachment_id BIGINT UNSIGNED NOT NULL, 
  extracted_text LONGTEXT NOT NULL, 
  indexed_at DATETIME NOT NULL, 
  FULLTEXT KEY pdf_text_index (extracted_text) 
);

Then the plugin can search the extracted PDF content:

SELECT attachment_id 
FROM wp_pdf_search_index 
WHERE MATCH(extracted_text) 
AGAINST ('remote work requests' IN NATURAL LANGUAGE MODE);

So the PDF itself is not searched directly every time.

Instead, the plugin extracts the PDF text once, stores it, and searches the stored index.

Showing PDF Results in WordPress Search

Once PDF content is indexed, the next step is showing matching PDF files in the search results.

A plugin can hook into WordPress search using pre_get_posts, or it can provide a separate PDF search form.

For example, a shortcode-based PDF search form can be placed on a resource page:

[webequipe_pdf_search_form]

[webequipe_pdf_search_form placeholder="Search PDFs…" button_text="Search" results_per_page="10"]

This is useful for documentation pages, school notice sections, report libraries, member portals, or product manual pages.

The Scanned PDF Problem

Text extraction works only when the PDF contains real text.

But many PDFs are scanned documents.

Examples:

Old reports
Signed forms
Scanned notices
Paper manuals
Archive documents
Government or legal documents

A scanned PDF may look readable to a human, but technically each page is just an image.
So when a parser runs this:

$text = $pdf->getText();

It may return:

There are visible words on the page, but no machine-readable text layer.

This is where normal PDF parsing stops.

OCR Is Needed for Scanned PDFs

For scanned PDFs, the solution is OCR.

OCR means Optical Character Recognition. It reads text from images and converts it into machine-readable text.

The flow looks like this:

Google Vision API is one common OCR option. It can read pixel-based document images and return detected text.

A simplified flow:

$image_path = '/tmp/page-1.png'; 
$ocr_text = run_google_vision_ocr($image_path); 
if (! empty($ocr_text)) { 
  index_pdf_text($attachment_id, $ocr_text); 
}

The key idea is simple:

Text-based PDFs need parsing.
Scanned PDFs need OCR first.

If a search plugin treats both the same way, scanned PDFs will usually fail.

A Simple Detection Strategy

Most users do not know whether their PDF is text-based or scanned.

So the plugin should decide automatically.
A practical approach is:

$text = extract_pdf_text($file_path); 
if (strlen(trim($text)) > 100) { 
  index_pdf_text($attachment_id, $text);
} else { 
  queue_pdf_for_ocr($attachment_id); 
}

First, try normal extraction.

If enough text is found, index it.

If the result is empty or too short, send the file to OCR.

For large PDFs or OCR processing, this should run in the background. Otherwise, uploads can become slow and PHP timeouts can happen.

A better flow is:

In WordPress, this can be handled with WP-Cron, Action Scheduler, or a custom queue system.

Final Thoughts

WordPress search ignores PDFs because PDF content is not stored in the database fields WordPress normally searches.

To fix it, you need a separate indexing pipeline.

For text-based PDFs, extract the text and store it in a searchable index.

For scanned PDFs, run OCR first, then store the detected text.

That is the technical foundation of PDF search in WordPress.

We built this into WebEquipe PDF Search. The free version helps index text-based PDFs, and the Pro version adds OCR support for scanned PDFs.

But the bigger idea is simple:

Uploading a PDF does not automatically make its content searchable.

If your WordPress site depends on PDFs, those files need to be treated as part of your search index.