So you’ve got a PDF that’s acting up — won’t open, shows gibberish, or throws errors. You’re a PHP developer looking for a programmatic fix. This guide is for you. By the end, you’ll have a working PHP script that can repair common PDF issues like broken cross-reference tables, missing pages, and garbled content streams.
We’ll use PHP libraries like FPDI (a fork of FPDF and FPDI) and also explore calling external tools like Ghostscript. No expensive software needed — just your dev environment and some patience.
What You’ll Need
- PHP 7.4 or higher (8.x recommended)
- Composer for dependency management
- A corrupted PDF file to test on (backup the original)
- Basic knowledge of PHP and command line
- Optional: Ghostscript installed on your server
If you haven’t already, take a look at our guide on general PDF repair to understand what’s happening under the hood.
Step 1: Install Required PHP Libraries
We’ll use FPDI (FPDI is a set of PHP classes that can read and write PDF files). Install it via Composer:
This will also pull in FPDF. If you need more advanced features, you can also install setasign/fpdi-tcpdf or setasign/fpdi-tfpdf. For now, the base package is enough.
Step 2: Create a PHP Script to Open and Parse the PDF
Create a new PHP file, say repair.php. Start by loading the library and opening the corrupted PDF:
If this step fails, the PDF has structural damage. That’s okay — we’ll repair it in the next steps.
Step 3: Repair the Cross-Reference Table
FPDI can often handle a broken xref table by rebuilding it. If setSourceFile throws an exception about the xref table, you can try to bypass it by manually reading the file and fixing the table. However, the easiest approach is to use the Fpdi::setSourceFile with the useXrefTable option set to false. But FPDI doesn’t have that option directly. Instead, you can use a low-level approach or rely on external tools.
A more practical method is to use Ghostscript to rebuild the PDF. Run this command on your server:
For more details, check out our dedicated guide on Ghostscript repair PDF.
Step 4: Handle Garbled Content Streams
If the PDF opens but text is garbled, the content streams might be damaged. One way to fix this is to extract and re-encode the streams. FPDI can’t do that directly, but you can use a combination of FPDI and TCPDF. First, install TCPDF:
Then, you can import each page and write it out again, effectively rebuilding the content. This often clears up garbled text. Here’s a snippet:
This method recompresses the streams and can fix many issues. For a deep dive, see our article on xref table repair.
Step 5: Save and Verify the Repaired PDF
After running the script, you’ll have repaired.pdf. Open it in a PDF viewer to check. If it still has issues, try the Ghostscript method above. You can also perform PDF error scanning with tools like qpdf or Mutool. See our guide on Mutool repair PDF for another command-line option.
Common Pitfalls
- Missing FPDI dependency: Always run
composer installafter cloning or deploying. Double-check yourvendorfolder. - Permission issues: The web server user may not have write access to the output directory. Use an absolute path with proper permissions or write to
/tmp. - Memory exhaustion with large PDFs: Increase PHP memory limit with
ini_set('memory_limit', '256M');or process pages in batches.
Where to Next
You’ve learned the basics of PDF repair with PHP. For more advanced scenarios, explore our guides on Ghostscript repair PDF, Mutool repair PDF, and general PDF repair. If you’re dealing with specific issues like a broken xref table, our xref table repair article has you covered. And don’t forget to scan your PDFs for errors regularly with our PDF error scanning tips.
