README

Turn any PDF into a Pingen-ready A4 letter and send it through the Pingen print & mail API — with a generated address cover page, automatic A4 normalisation, and safe print margins.

Pingen reads the recipient address off the first page of the PDF (the window-envelope zone) and rejects non-A4 pages or content in the protected border/postage areas. This package handles all of that for you:

1. Draws an address cover page (recipient in the window zone).
2. Merges cover + your documents into one file (via a pluggable driver).
3. Re-lays every page to A4 with safe margins — Letter, legal, or compressed source PDFs all come out clean.

Then it uploads, creates and sends the letter via Pingen.

Requirements

• PHP 8.2+
• Laravel 10, 11 or 12
• A Pingen account + a Developer-App (OAuth2 client_credentials)
• A PDF merge driver — one of:
  • ConvertAPI (recommended, no server binary) — composer require convertapi/convertapi-php
  • Ghostscript (gs installed on the server)
  • FPDI (pure PHP, only for simple/uncompressed inputs)

Installation

composer require hamza-rico/laravel-pingen-letter
php artisan vendor:publish --tag=pingen-letter-config

Configuration

Add to your .env:

PINGEN_STAGING=true
PINGEN_CLIENT_ID=your-client-id
PINGEN_CLIENT_SECRET=your-client-secret
PINGEN_ORGANISATION_ID=your-organisation-uuid

# merge driver: convertapi | ghostscript | fpdi
PINGEN_MERGER=convertapi
CONVERTAPI_SECRET=your-convertapi-secret
# or, for ghostscript:
# PINGEN_MERGER=ghostscript
# PINGEN_GS_BIN=/usr/bin/gs

Pingen offers a free staging environment that mails nothing — keep PINGEN_STAGING=true until you're ready to go live.

Usage

use HamzaRico\PingenLetter\Facades\PingenLetter;
use HamzaRico\PingenLetter\DTO\Recipient;
use HamzaRico\PingenLetter\Enums\DeliveryProduct;

$letter = PingenLetter::to(new Recipient(
        name:    'Jane Doe',
        street:  'Musterstrasse 12',
        zip:     '10115',
        city:    'Berlin',
        country: 'DE',
    ))
    ->documents([
        'https://example.com/translation.pdf',
        storage_path('app/certificate.pdf'),
    ])
    ->deliveryProduct(DeliveryProduct::Cheap)
    ->color()
    ->duplex()
    ->send();

// ['id' => '…', 'url' => 'https://app.pingen.com/…', 'status' => 'sent', 'pages' => 3]

Just build the print-ready PDF (no sending)

$pdf = PingenLetter::to($recipient)
    ->documents([$path])
    ->build(); // ['path' => '/tmp/…​.pdf', 'pages' => 2]

Low-level API access

$client = PingenLetter::client();
$client->getLetter($id);       // status + tracking
$client->cancelLetter($id);    // cancel (only while submitted / print preparation)
$client->calculatePrice([...]); // price for a country + options

Page limits

Pingen enforces per-country page limits — tightest are Netherlands (14) and India (16); most others allow 120–500. Check the page count from build() before sending if you mail to those countries.

Delivery products

cheap (default), fast, bulk, premium, registered. Pingen maps these to each destination country's real postal product. Only registered provides a carrier tracking number; standard letters give status updates only.

Testing

composer install
vendor/bin/phpunit

License

MIT.