Configuration

This package comes preloaded with a sensible set of default configurations. These defaults are sourced from the package directly, unless you publish the config into your application.

For additional type-safety, default configuration is prepared using the Config class. It must be cast to an array, and the service instance will automatically hydrate it when needed.

Changing configuration

Once the default configuration has been loaded into a service instance, you can change it one of two ways:

Config tapping

On service instances

Tapping involves the use of a callback that mutates the existing Config object in the service instance, using the tapConfig method.

You need only change the properties you want to change, and everything else will remain untouched (derived from the defaults).

use WeasyPrint\Objects\Config;

$service->tapConfig(
  static function (Config $config): void {
    $config->binary = '/absolute/path/to/weasyprint';
    $config->timeout = 5_000;
  }
);

In classes

If you are using class-based PDFs, then you can add a config method that behaves like tapConfig to your class:

use WeasyPrint\PDF;
use WeasyPrint\Objects\Config;

class MyPDF extends PDF
{
  public function config(Config $config): void
  {
    $config->timeout = 10_000;
  }
}

Overriding Config

To override the configuration with a brand new Config object, you can call setConfig, which accepts the object and sets it on the service instance.

use WeasyPrint\Objects\Config;

$service->setConfig(new Config(
  binary: '/absolute/path/to/weasyprint',
  timeout: 5000,
));

CAUTION

Unlike tapping, overriding the configuration will disregard any defaults that you might have set in your configuration file, or those set in the unpublished configuration file. Instead, the defaults are derived from the constructor of Config object.

NOTE

Class-based PDFs cannot override service instance config.

Available Options

The table below lists the options that are available.

Option	Type	Description
binary	string|null	The path to the WeasyPrint binary on your system. If it is available globally, the package will find and use it. If not, then you will need to specify the absolute path.
cachePrefix	string	The cache prefix to use for the temporary filename.
timeout	int	The amount of seconds to allow a conversion to run for.
inputEncoding	string	Force the input character encoding. utf-8 is recommended.
presentationalHints	bool	Enable or disable HTML Presentational Hints.
mediaType	string|null	Optionally set the media type to use for CSS [at]media. Defaults to print at binary-level.
baseUrl	string|null	Optionally set the base URL for relative URLs in the HTML input.
stylesheets	array	Stylesheets to use alongside the HTML input. Each stylesheet may be the absolute path to a file, or a URL.
processEnvironment	array	The environment variables passed to Symfony Process when executing the WeasyPrint binary.
pdfVariant	PDFVariant|string|null	Optionally specify a PDF variant. See the PDFVariant enum cases.
pdfVersion	PDFVersion|string|null	Optionally specify a PDF version. See the PDFVersion enum cases.
skipCompression	bool	For debugging purposes, do not compress PDFs.
customMetadata (only in 10.x+)	bool	Include custom HTML meta tags in PDF metadata.
srgb (only in 10.x+)	bool	Include sRGB color profile.
optimizeImages	bool	Optimize the size of embedded images with no quality loss.
fullFonts	bool	When possible, embed unmodified font files in the PDF.
hinting	bool	Keep hinting information in embedded font files.
dpi	int|null	Set the maximum resolution of images embedded in the PDF.
jpegQuality	int|null	Set the JPEG output quality, from 0 (worst) to 95 (best).
pdfForms	bool	Render PDF forms from HTML elements.

As noted before, you may publish the configuration file if you’d like to make changes to it – but, in most cases, you’ll want to make use of environment variables by adding them to your .env file or using whatever mechanism your app uses to resolve them.

return (array) new \WeasyPrint\Objects\Config(
  binary: env('WEASYPRINT_BINARY'),
  cachePrefix: env('WEASYPRINT_CACHE_PREFIX', 'weasyprint_cache'),
  timeout: (int) env('WEASYPRINT_TIMEOUT', '60'),
  inputEncoding: env('WEASYPRINT_INPUT_ENCODING', 'utf-8'),
  presentationalHints: env('WEASYPRINT_PRESENTATIONAL_HINTS', true),
  mediaType: env('WEASYPRINT_MEDIA_TYPE'),
  baseUrl: env('WEASYPRINT_BASE_URL'),
  stylesheets: [],
  processEnvironment: [
    'LC_ALL' => env('WEASYPRINT_LOCALE', 'en_US.UTF-8'),
  ],
  pdfVariant: \WeasyPrint\Enums\PDFVariant::fromEnvironment(
    'WEASYPRINT_PDF_VARIANT',
  ),
  pdfVersion: \WeasyPrint\Enums\PDFVersion::fromEnvironment(
    'WEASYPRINT_PDF_VERSION',
  ),
  skipCompression: env('WEASYPRINT_SKIP_COMPRESSION', false),
  customMetadata: env('WEASYPRINT_SRGB', false),
  srgb: env('WEASYPRINT_SRGB', false),
  optimizeImages: env('WEASYPRINT_OPTIMIZE_IMAGES', false),
  fullFonts: env('WEASYPRINT_FULL_FONTS', false),
  hinting: env('WEASYPRINT_HINTING', false),
  dpi: env('WEASYPRINT_DPI', null),
  jpegQuality: env('WEASYPRINT_JPEG_QUALITY', null),
  pdfForms: env('WEASYPRINT_PDF_FORMS', false),
);