8ctopus/pigeon-invoice

Create pdf and html invoices

5.0.1 2024-05-29 06:10 UTC

README

packagist downloads min php version license tests code coverage badge lines of code

Create pdf invoices

features

  • create pdf and html invoices
  • fully customizable thanks to Twig templates
  • localizable (demo shows Arabic, French, German, Greek, Japanese, Korean, Russian and Traditional Chinese)
  • extendable to include custom data (see the extend dir)
  • choice of pdf engines: Dompdf using either CPDF or PDFLib and wk<html>topdf
  • adjust paper size

invoice demo screenshot

requirements

  • php > 8.0 with ext-dom and ext-mbstring installed

demo

  • git clone the project
composer install
php demo.php
  • check generated invoices invoice.pdf and invoice.html

install

  • install package
composer require 8ctopus/pigeon-invoice
  • copy the resources directory to your project
use Oct8pus\Invoice\Company;
use Oct8pus\Invoice\Discount;
use Oct8pus\Invoice\Invoice;
use Oct8pus\Invoice\Item;
use Oct8pus\Invoice\Person;
use Oct8pus\Invoice\Shipping;
use Oct8pus\Invoice\Tax;

require_once __DIR__ . '/vendor/autoload.php';

$invoice = (new Invoice([
    'rootDir' => __DIR__ . DIRECTORY_SEPARATOR . 'resources',
    'templatesDir' => 'templates',
    'locale' => 'en'
]))
    ->setSeller((new Company())
        ->setName('Widgets LLC')
        ->setWebsite('https://www.widgets.ru')
        ->setEmail('hello@widgets.ru')
        ->setStreet1('16 Leo Tolstoy Street')
        ->setZip('119021')
        ->setCity('Moscow')
        ->setCountry('Russia'))

    ->setBuyer((new Person())
        ->setFirstName('Yuri')
        ->setLastName('Kamasov')
        ->setStreet1('Krasnoarmeyskaya 1')
        ->setZip('620026')
        ->setCity('Yekaterinburg')
        ->setCountry('Russia'))

    ->setDate(new DateTime('28-04-2022'))
    ->setNumber('EN43UD6JA7I2LNBC17')
    ->setCurrency('EUR')

    // add items
    ->addItem((new Item())->setName('Item 1')->setPrice(4.99)->setQuantity(1))
    ->addItem((new Item())->setName('Item 2')->setPrice(9.99)->setQuantity(2))
    ->addItem((new Item())->setName('Item 3')->setPrice(3.99)->setQuantity(3))

    ->setDiscount((new Discount())->setName('Special Offer')->setPrice(10.00))

    ->setShipping((new Shipping())->setName('Shipping')->setPrice(5.00))

    ->setTax((new Tax())->setName('VAT')->setPercentage(0.21))

    ->setCustomFields([
        'notes' => 'Thank you for shopping with us!',
    ]);

$html = $invoice->renderHtml();

file_put_contents('invoice.html', $html);

$pdf = $invoice->renderPdf([
    'paper' => 'A4',
    'orientation' => 'portrait',
    // allow to download content from the internet such as fonts
    'isRemoteEnabled' => true,
    // valid options: CPDF, PDFLib, GD, wkhtmltopdf and auto
    'pdfBackend' => 'CPDF',
]);

file_put_contents('invoice.pdf', $pdf);

pdf engines

  • Dompdf includes three engines

    • CPDF (bundled with Dompdf)
    • PDFLib is a commercial library with more advanced rendering than CPDF. It takes the form of a php extension that you will need to add to your php configuration.
    • GD will produce a pdf containing an image
  • wk<html>topdf

To use the wk<html>topdf engine, you will need to download the binary for your system and add it to the current working directory getcwd() or to the system path.

Twig templates reference documentation

https://twig.symfony.com/doc/3.x/

custom fonts

Fonts can either be provided as a style sheet link in the html head, which requires the isRemoteEnabled permission:

<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@300;700&display=swap" rel="stylesheet">

or from the local drive using css, but only in TrueType *.ttf format:

@font-face {
    font-family: 'Tangerine';
    src: url('../fonts/tangerine-400.ttf');
    font-weight: normal;
}

@font-face {
    font-family: 'Tangerine';
    src: url('../fonts/tangerine-700.ttf');
    font-weight: bold;
}

I would recommend you use the second variant in production.

support more languages

A font supports a limited number of languages, and therefore if you want to support many different languages, you will need to add fonts that have the glyphs for the language characters. Here's an example where the default font is Segoe UI (latin languages), then it falls back to Meiyro UI for Japanese, and Malgun Gothic for Korean:

font-family: 'Segoe UI', 'Meiryo UI', 'Malgun Gothic', sans-serif;

If the font does not support the language, you will see small squares instead of the correct characters. These are called tofu because they resemble small blocks of tofu.

More info: https://github.com/dompdf/dompdf/wiki/UnicodeHowTo

credits

tests

composer test

Note: tests do not check the pdf output, it seems it's not ready yet in DomPDF

clean code

composer fix