Would you be open to receive a port of resilience improvements from smalot/pdfparser?

[vitormattos]

I’m working on a PR for the smalot/pdfparser project that significantly improves the parser’s resilience to malformed PDFs. Practically: from 870 PDFs parsed from the PDF.js, the successful count rose to 922, +52 files that previously failed now parse correctly.

At LibreSign we plan to use this to replace pdfinfo (a Poppler binary). I opened a PR to smalot/pdfparser to add support for extracting page dimensions (CropBox/MediaBox), which would let us remove the current LibreSign workaround that relies on pdfinfo for many problematic PDFs.

Would you be interested in accepting a port of my contribution into this project? I propose to port PR smalot/pdfparser#795, it was developed with TDD and fixtures for all fixes required to extract page dimensions, and it produced the improvement described above.

Your project appears more active than smalot’s and targets supported PHP versions only. However, your package doesn’t seem to include smalot’s commit history, which reduces visibility in my view. Given these points, and despite having fewer contributors than smalot/pdfparser, it would make more sense for me to focus effort here, so LibreSign can rely on a stable package and contribute to its maintenance.

Would you be open to discussing this?

[PrinsFrank]

Thanks for reaching out and for your interest in this library!

To clarify: This library is fully written from scratch, so is not using anything from the smalot/pdfparser package. That explains why you're not seeing any shared commit history.

Regarding the CropBox and MediaBox; This functionality is already supported here, you can retrieve that data from the page dictionaries like this:

$document = (new PdfParser())
    ->parseFile(__DIR__ . '/file.pdf');

foreach ($document->getPages() as $page) {
    $cropBox = $page->getDictionary()
        ->getValueForKey(DictionaryKey::CROP_BOX, Rectangle::class);
    $mediaBox = $page->getDictionary()
        ->getValueForKey(DictionaryKey::MEDIA_BOX, Rectangle::class);
}

I have encountered the same issues with smalot/pdfparser: A lot of PDFs could not be successfully parsed. I've tried to fix some of the issues, but could not wrap my head around some design patterns there, and I was unable to fix some things without touching a lot of code. So ultimately I gave up and decided to write a new library that had smaller and more focussed classes with a single responsibility.

I've also made another design decision: Anything that the library doesn't account for results in an exception, instead of silently ignoring an unknown pattern. This means that at the start of this library it would throw a lot of exceptions, but it has gradually reached a stable state, and I do trust its output. This approach also ensures that errors are visible and can be acted upon, improving the parser's robustness over time.

Given the fundamental differences in design and codebase between the two libraries, I don't think it makes sense to work on a full port of that PR. Many of the issues in that PR don't apply to this library as it's fundamentally a different package. Feel free to try it out though! I don't think it will parse all your PDFs without errors just yet, but it probably will parse a significant amount!

If you're encountering errors, please feel free to open an issue or a PR! Just a heads-up for PRs: I aim to keep contributions focussed on a single issue, with a maximum of 200-300 lines of code (excluding tests). This ensures changes are easier to review, test and maintain. Let me know if anything is unclear or if you need help getting started!

[vitormattos]

Thanks for the detailed reply, this really helped me better understand the project and your design decisions.

As a maintainer of open source projects myself, I fully understand and agree with your contribution guidelines (single issue per PR, small and focused changes, easy to review).

I also appreciate your approach of favoring explicit exceptions over silently handling unknown patterns. That makes a lot of sense from a maintainability perspective, and I’ll make sure to align with that.

Given that, I’d like to propose the following approach:

• First, review and, if necessary, improve the way to retrieve basic PDF metadata. As a starting point, I’d focus on providing a simple way to obtain page dimensions (width and height for all pages). This would be a single, focused PR.

• I will run a local benchmark against the PDF.js and veraPDF corpora using your library as-is, along with a small analysis tool.

• For each failure, I will:

  • group them by exception type,

  • isolate minimal reproducible PDF samples,

  • and open focused issues including:

    • a minimal repro file,
    • the exact exception and stack trace,
    • expected vs actual behavior,
    • and tests using real PDF fixtures.

• Then, I’ll submit small PRs addressing one issue at a time, staying within your preferred size (~200–300 lines excluding tests), always including tests.

If this approach sounds good to you, I’ll start by opening the first focused issue with a minimal reproducible example.

[PrinsFrank]

Great!, that sounds like a good plan! I'll close this issue and I'll see new ones appear then! Thanks for the help!!