PHPackages                             shipfastlabs/parsel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. shipfastlabs/parsel

ActiveLibrary[PDF & Document Generation](/categories/documents)

shipfastlabs/parsel
===================

A pure-PHP, expressive wrapper around the liteparse `lit` CLI for fast, local document parsing.

v0.0.3(1mo ago)3342.1k↑34.3%8[1 PRs](https://github.com/shipfastlabs/parsel/pulls)MITPHPPHP ^8.4.0CI passing

Since May 29Pushed 2w ago3 watchersCompare

[ Source](https://github.com/shipfastlabs/parsel)[ Packagist](https://packagist.org/packages/shipfastlabs/parsel)[ GitHub Sponsors](https://github.com/pushpak1300)[ RSS](/packages/shipfastlabs-parsel/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (16)Versions (6)Used By (0)

Parsel
======

[](#parsel)

 [![Parsel](./art/og.png)](./art/og.png)

 [![Tests](https://github.com/shipfastlabs/parsel/actions/workflows/tests.yml/badge.svg)](https://github.com/shipfastlabs/parsel/actions) [![Latest Version](https://camo.githubusercontent.com/566988c958b2b43f91c6483be8e8d829fac5f1e340c08582afdfa67bf52f351e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73686970666173746c6162732f70617273656c)](https://packagist.org/packages/shipfastlabs/parsel) [![Total Downloads](https://camo.githubusercontent.com/8a795a42cb7f6cc1eb57bcfa5edb62b9b86d6a3082ad81e1dfdaf1d77028ebd8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73686970666173746c6162732f70617273656c)](https://packagist.org/packages/shipfastlabs/parsel) [![License](https://camo.githubusercontent.com/c1d3cb020bad80c8060d91322f8681618ee6bc7b5937f56c093c2fb366995393/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f73686970666173746c6162732f70617273656c)](https://packagist.org/packages/shipfastlabs/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.

```
use Shipfastlabs\Parsel;

$text = Parsel::file('invoice.pdf')->text();

$document = Parsel::file('invoice.pdf')
    ->pageRange(1, 5)
    ->withOcr(language: 'eng')
    ->withDpi(300)
    ->parse();

foreach ($document->pages as $page) {
    foreach ($page->items as $item) {
        echo "{$item->text} @ ({$item->x}, {$item->y})\n";
    }
}
```

Parsel requires PHP 8.4 or greater and the `lit` binary.

Installation
------------

[](#installation)

You may install Parsel via Composer:

```
composer require shipfastlabs/parsel
```

Install the required `lit` binary:

```
vendor/bin/parsel-install-lit
```

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

```
vendor/bin/parsel-install-lit --with-system-dependencies
```

You may choose the installer used for the `lit` binary:

```
vendor/bin/parsel-install-lit --manager=npm
vendor/bin/parsel-install-lit --manager=pnpm
vendor/bin/parsel-install-lit --manager=bun
vendor/bin/parsel-install-lit --manager=pip
vendor/bin/parsel-install-lit --manager=cargo
```

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

```
cargo install liteparse
pip install liteparse
npm i -g @llamaindex/liteparse
pnpm add -g @llamaindex/liteparse
bun add -g @llamaindex/liteparse
```

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

```
# macOS
brew install --cask libreoffice # For Office Document
brew install imagemagick # For Images

# Ubuntu / Debian
apt-get install libreoffice # For Office Document
apt-get install imagemagick # For Images

# Windows
choco install libreoffice-fresh # For Office Document
choco install imagemagick.app # For Images
```

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

Parsing Files
-------------

[](#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.

```
use Shipfastlabs\Parsel;

$text = Parsel::file('/path/to/report.pdf')->text();
```

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.

```
$document = Parsel::bytes($uploadedBytes, 'pdf')->parse();
```

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

```
$text = Parsel::file('contract.docx')->text();

$rows = Parsel::file('report.xlsx')->text();

$slides = Parsel::file('deck.pptx')->text();

$scan = Parsel::file('receipt.png')
    ->withOcr()
    ->text();

$photo = Parsel::file('invoice.jpg')
    ->withOcr(language: 'eng')
    ->parse();
```

Plain Text
----------

[](#plain-text)

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

```
$text = Parsel::file('document.pdf')
    ->withoutOcr()
    ->text();
```

Structured Documents
--------------------

[](#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.

```
$document = Parsel::file('document.pdf')->parse();

echo $document->text;
echo $document->pageCount();

foreach ($document->pages as $page) {
    foreach ($page->items as $item) {
        echo $item->text;
    }
}
```

The document may also be returned as an array:

```
$array = Parsel::file('document.pdf')->toArray();
```

Page Selection
--------------

[](#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.

```
Parsel::file('document.pdf')->page(7);

Parsel::file('document.pdf')->pages(1, 3, 5);

Parsel::file('document.pdf')->pages('1-5', 10);

Parsel::file('document.pdf')->pageRange(1, 5);

Parsel::file('document.pdf')->pageRange(1, 5)->page(10);
```

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

```
Parsel::file('document.pdf')->maxPages(50)->text();
```

OCR
---

[](#ocr)

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

```
$text = Parsel::file('scan.pdf')->withOcr()->text();
```

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

```
$text = Parsel::file('scan.pdf')
    ->withOcr(
        language: 'fra',
        tessdataPath: '/usr/share/tessdata',
        serverUrl: 'http://localhost:8828/ocr',
        workers: 8,
    )
    ->text();
```

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

```
$text = Parsel::file('document.pdf')->withoutOcr()->text();
```

Rendering Options
-----------------

[](#rendering-options)

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

```
Parsel::file('document.pdf')->withDpi(300);

Parsel::file('document.pdf')->preserveSmallText();

Parsel::file('secret.pdf')->withPassword('hunter2');

Parsel::file('document.pdf')->withBinary('/usr/local/bin/lit');

Parsel::file('document.pdf')->withTimeout(120);
```

Additional Options
------------------

[](#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.

```
Parsel::file('document.pdf')->option('some-new-flag');

Parsel::file('document.pdf')->option('some-new-flag', 42);
```

Saving Output
-------------

[](#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.

```
Parsel::file('document.pdf')->save('document.txt');

Parsel::file('document.pdf')->save('document.json');
```

Screenshots
-----------

[](#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.

```
$screenshots = Parsel::file('document.pdf')
    ->pageRange(1, 5)
    ->screenshots('/tmp/parsel-pages');
```

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

Streaming Large Documents
-------------------------

[](#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.

```
foreach (Parsel::file('large-document.pdf')->lazyPages() as $page) {
    foreach ($page->items as $item) {
        // Process one page at a time...
    }
}
```

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

Document Data
-------------

[](#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.

```
$document->text;
$document->metadata;
$document->pages;
$document->pageCount();

$page->number;
$page->width;
$page->height;
$page->text;
$page->items;

$item->text;
$item->x;
$item->y;
$item->width;
$item->height;
$item->fontName;
$item->fontSize;
$item->confidence;
```

Binary Resolution
-----------------

[](#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`.

```
Parsel::usingBinary('/usr/local/bin/lit');

Parsel::defaultTimeout(120);
```

Testing
-------

[](#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.

```
use Shipfastlabs\Parsel;

$fake = Parsel::fake([
    '--format json' => file_get_contents(__DIR__.'/fixtures/lit-output.json'),
]);

$document = Parsel::file('invoice.pdf')->parse();

expect($fake->recordedCommands()[0])->toContain('--format', 'json');
```

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
-----------

[](#development)

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

```
composer lint
composer test:types
composer test:unit
composer test
```

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

```
./vendor/bin/pest --group=integration
```

Credits
-------

[](#credits)

Parsel is maintained by [Shipfastlabs](https://shipfastlabs.com) and released under the [MIT license](LICENSE.md).

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance94

Actively maintained with recent releases

Popularity41

Moderate usage in the ecosystem

Community15

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

3

Last Release

47d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31663512?v=4)[Pushpak Chhajed](/maintainers/pushpak1300)[@pushpak1300](https://github.com/pushpak1300)

---

Top Contributors

[![pushpak1300](https://avatars.githubusercontent.com/u/31663512?v=4)](https://github.com/pushpak1300 "pushpak1300 (24 commits)")[![impruthvi](https://avatars.githubusercontent.com/u/61496236?v=4)](https://github.com/impruthvi "impruthvi (11 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")

---

Tags

docsocrpdftext-extarctionphppdfparserdocumentOCRlitliteparse

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/shipfastlabs-parsel/health.svg)

```
[![Health](https://phpackages.com/badges/shipfastlabs-parsel/health.svg)](https://phpackages.com/packages/shipfastlabs-parsel)
```

###  Alternatives

[pontedilana/php-weasyprint

PHP library allowing PDF generation from an url or a html page. Wrapper for Kozea/WeasyPrint.

791.2M18](/packages/pontedilana-php-weasyprint)[mostafaznv/pdf-optimizer

PDF optimization tool for PHP and Laravel applications

172166.2k](/packages/mostafaznv-pdf-optimizer)[rockett/weasyprint

A feature-rich WeasyPrint wrapper for generating PDFs from HTML and CSS, with support for PDF/A, PDF/UA, attachments, and optional Laravel integration.

30224.7k](/packages/rockett-weasyprint)[tecnickcom/tc-lib-pdf-parser

PHP library to parse PDF documents

38126.9k9](/packages/tecnickcom-tc-lib-pdf-parser)[paperdoc-dev/paperdoc-lib

A zero-dependency PHP library for generating, parsing and converting documents (PDF, HTML, CSV, DOCX)

1253.7k](/packages/paperdoc-dev-paperdoc-lib)[kaleu62/pi-reader

A Simple PDF and Image parser

1129.7k](/packages/kaleu62-pi-reader)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)