README

Parse documents to Markdown from Laravel. Install the package, set an API key, and call Parse::file('contract.pdf')->parse(); the result arrives in a ParseCompleted event. This is the client SDK for parseforartisans.com.

Ready to use. The managed parse flow is live and verified end to end against parseforartisans.com: install the package, set an API key, and Parse::file()->parse() returns its result in a ParseCompleted event. parse:ping, parse:file, and the full submit, status, and markdown path all work today. BYO-bucket presigning and signed webhook delivery are on the roadmap; see Current status.

Requirements

• PHP ^8.3
• Laravel 12 or 13

Installation

composer require parseforartisans/laravel

Add your credentials to .env:

PARSE_API_KEY=pfa_...
PARSE_WEBHOOK_SECRET=whsec_...

Run the installer. It publishes config/parse.php, the parse_requests migration, and two event listeners into app/Listeners/, then offers to run the migration:

php artisan parse:install

Confirm the key works and the service is reachable:

php artisan parse:ping

✔ Connected to parseforartisans.com
✔ API key valid (plan: free)
✔ Ready to parse

Usage

use ParseForArtisans\Facades\Parse;

$parse = Parse::file('contracts/foo.pdf')->parse();   // default disk
$parse->id;        // uuid
$parse->status();  // 'pending'

Options chain before ->parse():

Parse::file('contracts/foo.pdf')
    ->for($document)         // associate with one of your models, handed back in the event
    ->withMeta(['tenant_id' => $tenant->id])
    ->ocr(true)
    ->ocrLanguage('spa')
    ->pages('1-20')
    ->frontmatter(true)
    ->to('out/foo.md')
    ->parse();

Handle the result in the published listener (app/Listeners/HandleParsedDocument.php):

public function handle(ParseCompleted $event): void
{
    $markdown = $event->request->markdown();
    $document = $event->request->parsable;   // the model from ->for(), or null
}

From the command line:

php artisan parse:file contracts/foo.pdf            # submit, wait, print the Markdown
php artisan parse:file contracts/foo.pdf --save=out.md

The full developer documentation lives at parseforartisans.com/docs.

Configuration

config/parse.php:

'disk'     => env('PARSE_DISK'),               // your bucket. Unset uses our managed dev bucket.
'output'   => 'parsed',                        // prefix where Markdown is written
'delivery' => env('PARSE_DELIVERY', 'auto'),   // auto | webhook | poll

delivery=auto polls on APP_ENV=local and uses webhooks everywhere else. Local poll delivery rides the queue worker that Laravel's composer run dev already runs.

Testing your own code

This package uses Laravel's built-ins, so no bespoke fake is needed:

• Http::fake() stubs the submit and status calls.
• Storage::fake() backs the file reads.
• Dispatch ParseCompleted / ParseFailed directly to drive your listeners.

Local manual test (against the staging or local SaaS)

To test local, unreleased changes to the SDK from a separate Laravel app, require it from a local path instead of Packagist. In the consumer app's composer.json:

"repositories": [
    { "type": "path", "url": "../parse-sdk" }
],
"require": {
    "parseforartisans/laravel": "*"
}

Then:

composer require parseforartisans/laravel       # symlinks the local package

Point the SDK at the live SaaS and set a real key in the consumer app's .env:

PARSE_BASE_URL=https://parseforartisans.com  # the live SaaS (the default; override for staging/local)
PARSE_API_KEY=pfa_...                        # a key minted in the dashboard

Then run, in order:

1. php artisan parse:install and confirm config/parse.php, the migration, and app/Listeners/HandleParsedDocument.php + HandleFailedParse.php were created.
2. php artisan migrate and confirm the parse_requests table exists.
3. php artisan parse:ping and confirm the connected / valid-key / ready output. Try a wrong key to see the failure path.
4. php artisan parse:file <a public PDF URL> (or a path on your default disk) — submits, waits, and prints the parsed Markdown. Add --save=out.md to write it to a file.
5. For the event path, run composer run dev (or queue:listen on a database/redis driver) and call Parse::file('contracts/foo.pdf')->parse() from tinker; your HandleParsedDocument listener fires with the result.

Offline testing (bundled mock backend)

The live SaaS is the primary end-to-end target (above). For offline work the package also ships a local mock backend that implements the wire contract (POST /api/v1/parse, status, markdown, ping) and returns deterministic fake Markdown after a short delay. It is a dev aid, not an installed Artisan command, so run it with PHP's built-in server:

php -S 127.0.0.1:9321 vendor/parseforartisans/laravel/mock/server.php
MOCK_DELAY=5 php -S 127.0.0.1:9321 vendor/parseforartisans/laravel/mock/server.php   # stay pending longer
MOCK_FAIL=pdf php -S 127.0.0.1:9321 vendor/parseforartisans/laravel/mock/server.php  # fail .pdf async

Point the SDK at it with poll delivery, in .env:

PARSE_BASE_URL=http://127.0.0.1:9321
PARSE_API_KEY=pfa_anything             # the mock only checks the pfa_ prefix
PARSE_DELIVERY=poll

Then php artisan parse:file contracts/foo.pdf (needs no queue; ->wait() polls inline), or run a worker and Parse::file('contracts/foo.pdf')->parse() from tinker to drive the ParseCompleted event. An unsupported extension (e.g. .rtf) throws ParseException synchronously, and MOCK_FAIL=pdf drives a ParseFailed event.

Current status

The managed parse flow is ready to use: implemented, covered by Pest tests (Http::fake() / Storage::fake() plus a mock-backend integration test), and verified end to end against the live SaaS. BYO storage and signed webhook delivery are on the roadmap.

License

MIT