README

A Laravel wrapper for WeasyPrint, a powerful tool for generating PDFs. This package provides an easy-to-use interface for generating, saving, downloading, and displaying PDFs in Laravel applications.

About WeasyPrint

WeasyPrint is a Python-based library that converts HTML and CSS documents into PDFs. It supports modern web standards, making it ideal for generating high-quality PDFs from complex HTML and CSS.

Key Features of WeasyPrint:

• High-Quality Output: Supports modern CSS features like Flexbox, Grid, and more.
• Cross-Platform: Works on Linux, macOS, and Windows (with some setup).
• Open Source: Free to use and actively maintained.

Features

This Laravel package provides seamless integration with WeasyPrint, enabling easy PDF generation with various options:

• 📄Generate PDFs from Blade views, HTML strings, files, or URLs.
• 💾 Save PDFs to disk or display them directly to the browser.
• 📥 Download PDFs with custom filenames.
• ⚙ Set custom options for WeasyPrint (e.g., metadata, attachments).
• ⏳ Timeout configuration for long-running processes.
• 🔧 Disable/Enable the package dynamically via configuration.

With these features, generating and managing PDFs in your Laravel project becomes effortless! 🚀

Prerequisites

Before using this package, ensure the following dependencies are installed:

• Python: WeasyPrint requires Python 3 or higher to work correctly.
• WeasyPrint: Install WeasyPrint using pip or a package manager.

Installation

1. Install the package via Composer:

composer require hkwise/laravel-weasyprint

2. Publish the Configuration File (Optional)

php artisan vendor:publish --provider="HKWise\WeasyPrint\WeasyPrintServiceProvider"

3. Install WeasyPrint

Linux

The easiest way to install WeasyPrint on Linux is to use the package manager of your distribution.

• Debian/Ubuntu

Install WeasyPrint using apt:

sudo apt install weasyprint

• Fedora

Install WeasyPrint using dnf:

sudo dnf install weasyprint

• Archlinux

Install WeasyPrint using pacman:

sudo pacman -S python-weasyprint

Alternatively, install via pip:

pip install weasyprint

macOS

The easiest way to install WeasyPrint on macOS is to use Homebrew:

brew install weasyprint

Windows

To use WeasyPrint on Windows, the easiest way is to use the executable of the latest release.

If you want to use WeasyPrint as a Python library, you’ll have to follow a few extra steps. Please read this carefully.

The first step is to install the latest version of Python.

When Python is installed, you have to install Pango and its dependencies. The easiest way to install these libraries is to use MSYS2. Here are the steps you have to follow:

• Install MSYS2 keeping the default options.
• After installation, in MSYS2’s shell, execute pacman -S mingw-w64-x86_64-pango.
• Close MSYS2’s shell.

You can then launch a Windows command prompt by clicking on the Start menu, typing cmd and clicking the “Command Prompt” icon. Install WeasyPrint in a virtual environment using pip:

python3 -m venv venv
venv\Scripts\activate.bat
python3 -m pip install weasyprint
python3 -m weasyprint --info

For more detailed installation instructions, visit the WeasyPrint Documentation.

Customizing the Configuration

You can modify the package settings in config/weasyprint.php:

• Enable/Disable Package: Set 'enabled' => false, to disable WeasyPrint without removing it.

• Change Default Save Path: Update 'default_path' => storage_path('app/custom-pdfs'), to save PDFs in a different directory.

• Adjust Timeout: Modify 'timeout' => 120, to increase the maximum execution time.

This configuration ensures flexibility while using WeasyPrint in your Laravel application. 🚀

Usage

1. Generate PDF from a Blade View and Download

use HKWise\WeasyPrint\Facades\WeasyPdf;

$data = ['name' => 'John Doe'];
return WeasyPdf::loadView('pdf.invoice', $data)->download('invoice.pdf');

2. Generate PDF from HTML and Save to Disk

use HKWise\WeasyPrint\Facades\WeasyPdf;

WeasyPdf::loadHTML('<h1>Hello, World!</h1>')->save(storage_path('app/example.pdf'));

3. Generate PDF from a URL and Display in the browser

use HKWise\WeasyPrint\Facades\WeasyPdf;

return WeasyPdf::generate('https://weasyprint.org')->inline();

4. Generate PDF from a File and Download

use HKWise\WeasyPrint\Facades\WeasyPdf;

return WeasyPdf::loadFile(public_path('myfile.html'))->download('myfile.pdf');

5. You can chain multiple methods together. For example, you can save the PDF to disk first, then download it:

use HKWise\WeasyPrint\Facades\WeasyPdf;

return WeasyPdf::loadHtml('<h1>Hello, WeasyPrint!</h1>')
    ->save(storage_path('app/pdfs/myfile.pdf'))
    ->download('myfile.pdf');

6. Set Custom Options

You can pass additional WeasyPrint options using the setOptions method:

use HKWise\WeasyPrint\Facades\WeasyPdf;

return WeasyPdf::loadHTML('<h1>Test</h1>')
    ->setOptions([
        'custom-metadata' => 'metadata.json',
        'attachment' => ['note.txt', 'photo.jpg'],
    ])
    ->download('document.pdf');

Adjust Document Dimensions

This package does not support setting page size or document margins via configuration options. Instead, you must define these settings using the CSS @page at-rule in your HTML or stylesheets.

Example: Set Page Size and Margins

@page {
  size: Letter; /* Change from the default size of A4 */
  margin: 3cm; /* Set margin on each page */
}

There is much more which can be achieved with the @page at-rule, such as page numbers, headers, etc. Read more about the page at-rule.

Customizing the Facade Alias

By default, the Facade is registered as WeasyPdf. If you want to use a different alias (e.g., WPdf), you can manually register it in config/app.php:

'aliases' => [
    // Other aliases
    'WPdf' => HKWise\WeasyPrint\Facades\WeasyPdf::class,
],

After updating the alias, you can use WPdf instead of WeasyPdf:

use WPdf;

return WPdf::loadHTML('<h1>Hello, World!</h1>')->inline();

Alternatively, you can register both aliases:

'aliases' => [
    // Other aliases
    'WeasyPdf' => HKWise\WeasyPrint\Facades\WeasyPdf::class,
    'WPdf' => HKWise\WeasyPrint\Facades\WeasyPdf::class,
],

Now, you can use either WeasyPdf or WPdf:

use WeasyPdf;
use WPdf;

// Both will work
return WeasyPdf::loadHTML('<h1>Hello, World!</h1>')->inline();
return WPdf::loadHTML('<h1>Hello, World!</h1>')->inline();

Methods

Troubleshooting

1. WeasyPrint Command Not Found

• Ensure WeasyPrint is installed on your system:

pip install weasyprint

• On Linux (Debian/Ubuntu), you can install WeasyPrint using:

sudo apt install weasyprint

2. Timeout Errors

• Increase the timeout value in config/weasyprint.php if PDF generation takes longer than expected.

3. Local Environment Issues

This package may not work properly in local environments on Windows or macOS due to missing system dependencies for WeasyPrint. If you face issues while generating PDFs locally, consider disabling the package in non-production environments.

You can achieve this by modifying the enabled option in the configuration file (config/weasyprint.php):

'enabled' => app()->environment(['production', 'prod']),

This ensures the package is only enabled in production environments.

How It Works

Laravel’s app()->environment() method checks the current application environment based on the APP_ENV value set in your .env file.

For example, if your .env file contains:

APP_ENV=local

Then app()->environment(['production', 'prod']) will return false, disabling the package. However, in a production environment:

APP_ENV=production

app()->environment(['production', 'prod']) will return true, enabling the package.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This package is open-source software licensed under the MIT License.

Credits

• Developed by Hassan Khan
• Inspired by weasyprint.