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.

Configuration Defaults

Below are the default configuration options, which you can override per the above.

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(
  /**
   * The path to the WeasyPrint binary on your system. If it is available on
   * your system globally, the package will find and use it. If not, then
   * you will need to specify the absolute path.
   */
  binary: env('WEASYPRINT_BINARY'),

  /**
   * The cache prefix to use for the temporary filename.
   */
  cachePrefix: env('WEASYPRINT_CACHE_PREFIX', 'weasyprint_cache'),

  /**
   * The amount of seconds to allow a conversion to run for.
   */
  timeout: (int) env('WEASYPRINT_TIMEOUT', 120),

  /**
   * Force the input character encoding. utf-8 is recommended.
   */
  inputEncoding: env('WEASYPRINT_INPUT_ENCODING', 'utf-8'),

  /**
   * Enable or disable HTML Presentational Hints.
   */
  presentationalHints: (bool) env('WEASYPRINT_PRESENTATIONAL_HINTS', true),

  /**
   * Optionally set the media type to use for CSS @media.
   * Defaults to `print` at binary-level.
   */
  mediaType: env('WEASYPRINT_MEDIA_TYPE'),

  /**
   * Optionally set the base URL for relative URLs in the HTML input.
   */
  baseUrl: env('WEASYPRINT_BASE_URL'),

  /**
   * Optionally provide an array of stylesheets to use
   * alongside the HTML input. Each stylesheet may the absolute
   * path to a file, or a URL. It is recommended to do this
   * at runtime.
   */
  stylesheets: [],

  /**
   * The environment variables passed to Symfony Process when executing
   * the WeasyPrint binary.
   */
  processEnvironment: ['LC_ALL' => env(
    'WEASYPRINT_LOCALE',
    'en_US.UTF-8'
  )],

  /**
   * Optionally specify a PDF variant.
   */
  pdfVariant: WeasyPrint\Enums\PDFVariant::fromEnvironment(
    'WEASYPRINT_PDF_VARIANT'
  ),

  /**
   * Optionally specify a PDF version.
   */
  pdfVersion: WeasyPrint\Enums\PDFVersion::fromEnvironment(
    'WEASYPRINT_PDF_VERSION'
  ),

  /**
   * For debugging purposes, do not compress PDFs.
   */
  skipCompression: env('WEASYPRINT_SKIP_COMPRESSION', false),

  /**
   * Optimize the size of embedded images with no quality loss.
   */
  optimizeImages: env('WEASYPRINT_OPTIMIZE_IMAGES', false),

  /**
   * When possible, embed unmodified font files in the PDF.
   */
  fullFonts: env('WEASYPRINT_FULL_FONTS', false),

  /**
   * Keep hinting information in embedded font files.
   */
  hinting: env('WEASYPRINT_HINTING', false),

  /**
   * Set the maximum resolution of images embedded in the PDF.
   */
  dpi: env('WEASYPRINT_DPI', null),

  /**
   * Set the JPEG output quality, from 0 (worst) to 95 (best).
   */
  jpegQuality: env('WEASYPRINT_JPEG_QUALITY', null),

  /**
   * Render PDF forms from HTML elements.
   */
  pdfForms: env('WEASYPRINT_PDF_FORMS', false),
);