Download the PHP package shipfastlabs/parsel without Composer

Parsel

Parsel provides an expressive PHP API for parsing PDFs, Office documents, and images. Your documents are processed locally, allowing you to extract plain text, structured page data, coordinates, and screenshots without sending files to an external service.

Parsel may return plain text, structured document data, page screenshots, or one page at a time for larger documents. It is designed to feel natural in PHP applications while still giving you access to advanced parser options when you need them.

Parsel requires PHP 8.4 or greater and the lit binary.

Installation

You may install Parsel via Composer:

Install the required lit binary:

For Office documents, spreadsheets, presentations, and images, you may also install the system dependencies:

You may choose the installer used for the lit binary:

You may also install lit yourself using one of the following commands:

If you prefer to install the system dependencies yourself, use the matching commands for your platform:

LibreOffice is used for Office document conversion, ImageMagick is used for image conversion, and OCR support uses Tesseract through liteparse.

Parsing Files

The file method creates a parser instance for a document that already exists on disk. Once a source has been selected, you may choose how the parsed output should be returned.

You may also parse raw bytes. This is useful when working with uploaded files, database blobs, or documents that have not been persisted to disk. Because byte sources do not include a filename, you should provide the file extension.

Parsel may be used with PDFs, Word documents, spreadsheets, presentations, and images. The same fluent API is used for each supported file type:

Plain Text

The text method returns the parsed document text as a string. Parsel removes page header markers from text output before returning it.

Structured Documents

The parse method returns a Document object containing the document text, metadata, pages, and positioned text items. This is useful when you need coordinates, font information, or OCR confidence values.

The document may also be returned as an array:

Page Selection

The page, pages, and pageRange methods may be used to limit parsing to specific pages. These methods are additive, so you may combine multiple calls before parsing the document.

If you only need to limit how many pages are parsed, you may use the maxPages method:

OCR

OCR is disabled by default so that parsing remains fast and predictable. You may enable OCR using the withOcr method:

The withOcr method accepts named arguments for the most common OCR options:

If you would like to be explicit that OCR should not be used, you may call withoutOcr:

Rendering Options

Parsel includes convenience methods for common parser options such as rendering DPI, small text preservation, encrypted documents, and per-call process settings.

Additional Options

If you need to pass a flag that Parsel does not yet provide as a dedicated method, you may pass the option directly using the option method. Boolean options may be passed without a value, while options that require a value may receive one as the second argument.

Saving Output

The save method writes parsed output to disk and returns the path that was written. When the target path ends in .json, Parsel will write JSON output. For all other extensions, Parsel will write plain text.

Screenshots

You may use the screenshots method to render page screenshots into a directory. The method returns the image files found in the output directory after parsing has finished.

For predictable results, you should pass a dedicated output directory that does not contain unrelated files.

Streaming Large Documents

The parse and toArray methods load the parsed document into memory. When working with large documents, you may use lazyPages to process one page at a time.

This allows Parsel to read pages incrementally instead of keeping the full document in memory.

Document Data

A parsed Document contains the full text, metadata, and a list of pages. Each page contains its dimensions, page text, and text items with position data.

Binary Resolution

When Parsel needs to parse a document, it resolves the lit binary in the following order:

1. The per-call binary configured with withBinary.
2. The global binary configured with Parsel::usingBinary.
3. The PARSEL_LIT_BINARY environment variable.
4. The lit binary available on the system PATH.

If no binary can be resolved, Parsel will throw a BinaryNotFoundException.

Testing

Parsel includes a fake runner that allows your tests to exercise parsing code without spawning the real binary. Response keys are matched against the command line as substrings. When multiple responses match, the longest matching key is used.

String responses are returned as successful stdout. If you need control over the exit code or stderr, you may provide a ProcessResult instance instead.

Development

Parsel uses Pint, Rector, PHPStan, and Pest to keep the codebase formatted and well tested.

The integration tests run against a real parser installation and are skipped when the lit binary is not available:

Credits

Parsel is maintained by Shipfastlabs and released under the MIT license.