Esr Bundle Laravel Package

Getting Started

whatwedo/esr-bundle is not a Laravel package — it is a Symfony 2-era bundle that wraps Swiss ESR (orange Einzahlungsschein) PDF generation, later extended with Swiss QR-invoice support. Treat it as a reference implementation you mine rather than something you composer require into a Laravel app.

Look here first, in this order:

1. composer.json — tells you which PDF engine (TCPDF/FPDF/mPDF) and which QR library it delegates to. That dependency, not the bundle, is what you actually want to reuse.
2. DependencyInjection/Configuration.php — the canonical list of config keys (account/IBAN, client number, reference prefix, company address, fonts, PDF options). This is your source of truth for a Laravel config/esr.php.
3. Resources/config/services.* — the service IDs and constructor arguments, i.e. the wiring you must reproduce by hand in a service provider.
4. src/ — the generator class itself. If it has no ContainerAware/ContainerInterface coupling, instantiate it directly and skip the bundle entirely.

Install attempt (expect friction):

composer require whatwedo/esr-bundle --ignore-platform-reqs
composer why-not whatwedo/esr-bundle  # see which Symfony/PHP constraint blocks you

If the constraints are Symfony 2.x / PHP 5.x–7.x, do not fight it. Copy the generator source into app/Support/Esr/ (MIT license permits this, keep the header) and wire it yourself.

First use case — a single slip behind a download route:

// app/Services/Esr/InvoiceSlipGenerator.php
public function pdf(Invoice $invoice): string
{
    $data = [
        'account'   => config('esr.iban'),
        'client'    => config('esr.client_number'),
        'reference' => $this->reference($invoice),   // ESR reference w/ check digit
        'amount'    => number_format($invoice->total, 2, '', ''), // 8 digits, no separator
        'currency'  => 'CHF',
        'debtor'    => $invoice->customer->toEsrAddress(),
    ];

    return $this->renderer->render($data); // returns raw PDF bytes
}

// routes/web.php
Route::get('/invoices/{invoice}/slip', fn (Invoice $invoice) =>
    response($generator->pdf($invoice), 200, ['Content-Type' => 'application/pdf'])
);

Validate the output once against the official Swiss QR validation portal (or PostFinance's checker) before you build anything on top of it.

Implementation Patterns

1. Config port, not config import. Mirror the bundle's configuration tree into config/esr.php and feed it from .env. Keep the bundle's array shape so upstream fixes remain easy to port.

// config/esr.php
return [
    'iban'          => env('ESR_IBAN'),
    'qr_iban'       => env('ESR_QR_IBAN'),   // required for QR invoices
    'client_number' => env('ESR_CLIENT_NUMBER'),
    'company'       => ['name' => ..., 'street' => ..., 'zip' => ..., 'city' => ...],
    'reference_prefix' => 'RF',
    'pdf' => ['font' => 'ocrb', 'margin_top' => 0],
];

2. Wrap the renderer behind an interface. One method in, PDF bytes out. That single seam lets you swap the legacy ESR slip for the newer QR-bill library later without touching controllers.

interface PaymentSlipRenderer {
    public function render(PaymentSlipData $data): string;
}

3. Map Eloquent → value object, never pass models in. Build a small DTO (PaymentSlipData) from your Invoice/Customer models. Keeps the copied generator free of Laravel coupling and makes it testable.

4. Reference number generation is the core business logic. The ESR reference is client_number + invoice_number, padded, then a recursive mod-10 check digit appended:

private const TABLE = [0, 9, 4, 6, 8, 2, 7, 1, 3, 5];

public function checkDigit(string $digits): int
{
    $carry = 0;
    foreach (str_split($digits) as $d) {
        $carry = self::TABLE[($carry + (int) $d) % 10];
    }
    return (10 - $carry) % 10;
}

For QR invoices, choose reference type deliberately: QRR (27-digit ESR reference, needs QR-IBAN) vs SCOR (ISO 11649 RF..., works with a normal IBAN). Persist the reference on the invoice row so it never drifts after edits.

5. Generate asynchronously for anything bulk. PDF rendering is CPU-bound and the legacy libraries are slow. Throw a job, write to Storage, and let the download route serve the file:

dispatch(new GeneratePaymentSlip($invoice))->onQueue('pdf');

6. Integration tip — isolate if you must run the bundle. If you truly need the bundle's assembled services, run a minimal Symfony kernel in a separate container and call it over HTTP from Laravel. Do not boot a Symfony kernel inside a Laravel request; the container, event dispatcher, and Twig setups will collide.

7. Tests that actually catch regressions:

$pdf = $renderer->render($fixture);
$this->assertStringStartsWith('%PDF', $pdf);
$this->assertSame('210000000003139471430009017', $data->reference); // golden value

Golden-value tests on the reference number and a byte-sniff on the PDF are the highest-value assertions. Optionally render page-to-image and diff against a known-good slip.

8. Overriding output. The bundle renders through Twig templates in Resources/views. When you extract the code, copy those templates into resources/views/vendor/esr/ and keep the same variable names — that is the easiest extension point for logos and address layout.

Gotchas and Tips

• Symfony 2-era constraints will block a modern Laravel install. Expect PHP 5.x/7.x and symfony/*: ~2.8 pins. --ignore-platform-reqs may install but will fatal at runtime on PHP 8.1+ (dynamic properties, each(), create_function, TCPDF/FPDF deprecations). Plan on copying the source.
• QR-IBAN vs IBAN is the #1 rejection cause. A QR-IBAN is a normal IBAN whose IID (institution ID, positions 5–9) falls in 30000–31999. Pair QRR references with QR-IBAN and SCOR references with a regular IBAN; mixing them fails validation downstream, often silently in PDF-only checks.
• Amount formatting is strict. Eight digits, zero-padded, no decimal separator, right-aligned (00001250 = CHF 12.50). Currency is CHF only. Passing 12.5 or "12.50" produces a slip the bank rejects.
• The check-digit table is easy to get subtly wrong. Use the exact recursive table [0,9,4,6,8,2,7,1,3,5]; a hand-rolled "mod 10" from another country's spec will generate valid-looking but invalid references. Test with known-good numbers from the PostFinance spec.
• Fonts matter. The slip needs a fixed-width, OCR-B-style font for the coded line at the bottom. If the PDF library falls back to Helvetica, the print line misaligns and scanners reject it. Ship the font file with your app and reference it by absolute path.
• Do not scale the page. The orange slip has fixed geometry relative to A4. Users printing "fit to page" is a support ticket, not a bug — but your margins must be exact, so never let the PDF library auto-shrink.
• Config quirks: the bundle's Configuration.php defaults are not documented anywhere else. Any key you omit silently takes the bundle default, which is how blank company names and wrong account numbers slip into production. Port all keys, even the ones you think you don't need.
• Debugging workflow: dump the intermediate data array before it hits the renderer. Almost every failure is bad input data (empty reference, wrong IBAN, amount with a decimal point), not a PDF bug. If the PDF looks wrong, diff the data array first.
• Low bus factor. 12 stars, 0 dependents, no active maintainers. If this is production-critical: pin the commit, vendor the generator into your repo, add your own reference-number tests, and keep a second implementation (e.g. a maintained Swiss QR-bill package) as a fallback behind your PaymentSlipRenderer interface.
• Extension points, in order of safety: (1) your own renderer implementation, (2) copied Twig templates, (3) decorating the generator class, (4) forking the bundle. Never patch vendor/ in place.
• License is MIT for the bundle, but check the QR/PDF dependencies independently — some Swiss QR libraries carry attribution requirements or are LGPL.
• QR-bill migration: the orange ESR slip is being phased out in favour of the QR-bill. If you are starting fresh, budget for the QR path only and treat the ESR code as legacy support for existing print runs.