Configuration

The factory comes with sensible defaults out of the box, so configuration is entirely optional. When you do need to customise behaviour, there are a few ways to do it.

Passing Configuration

As covered in the Factory docs, you can pass configuration when creating a new instance - either as a Config object or an array:

use WeasyPrint\Objects\Config;
use WeasyPrint\WeasyPrintFactory;

// Using the Config class (recommended for type-safety and IDE hints):
$factory = new WeasyPrintFactory(
  new Config(
    timeout: 120,
    optimizeImages: true,
  )
);

// Using an array:
$factory = new WeasyPrintFactory([
  'timeout' => 120,
  'optimize_images' => true,
]);

Changing Configuration

After creating a factory, you can change its configuration using tapConfig() or setConfig().

tapConfig()

Tapping lets you mutate specific properties on the existing Config object while leaving everything else untouched:

use WeasyPrint\Objects\Config;

$factory->tapConfig(
  static function (Config $config): void {
    $config->binary = '/usr/local/bin/weasyprint';
    $config->timeout = 120;
  }
);

setConfig()

To replace the configuration entirely, use setConfig() with a new Config object:

use WeasyPrint\Objects\Config;

$factory->setConfig(new Config(
  binary: '/usr/local/bin/weasyprint',
  timeout: 120,
));

WARNING

Unlike tapConfig(), this replaces the entire configuration. Any values you don't explicitly set will fall back to the Config constructor defaults, not any previously configured values.

Available Options

binary

• Type: string|null - Default: null

The path to the WeasyPrint binary. If WeasyPrint is available globally, the package will find and use it automatically. Otherwise, provide an absolute path.

cachePrefix

• Type: string - Default: 'weasyprint_cache'

The prefix used for temporary filenames.

timeout

• Type: int - Default: 60

The number of seconds to allow a conversion to run for.

inputEncoding

• Type: string - Default: 'utf-8'

Force the input character encoding. Must be a valid encoding supported by mb_list_encodings().

presentationalHints

• Type: bool - Default: true

Enable or disable HTML Presentational Hints.

mediaType

• Type: string|null - Default: null

Set the media type to use for CSS @media. Defaults to print at binary level.

baseUrl

• Type: string|null - Default: null

Set the base URL for relative URLs in the HTML input.

stylesheets

• Type: array - Default: []

Additional stylesheets to use alongside the HTML input. Each entry may be an absolute file path or a URL.

processEnvironment

• Type: array - Default: ['LC_ALL' => 'en_US.UTF-8']

Environment variables passed to Symfony Process when executing the binary.

pdfVariant

• Type: PDFVariant|string|null - Default: null

Specify a PDF variant. You can pass the enum directly or use its string value:

use WeasyPrint\Enums\PDFVariant;

new Config(pdfVariant: PDFVariant::PDF_A_2B);
new Config(pdfVariant: 'pdf/a-2b');

Available variants

PDF/A: PDF_A_1B, PDF_A_2B, PDF_A_3B, PDF_A_1A, PDF_A_2A, PDF_A_3A, PDF_A_2U, PDF_A_3U, PDF_A_4U, PDF_A_4E, PDF_A_4F

PDF/UA: PDF_UA_1, PDF_UA_2

PDF/X: PDF_X_1A, PDF_X_3, PDF_X_4, PDF_X_5G

Debug: DEBUG

pdfVersion

• Type: PDFVersion|string|null - Default: null

Specify a PDF version. You can pass the enum directly or use its string value:

use WeasyPrint\Enums\PDFVersion;

new Config(pdfVersion: PDFVersion::VERSION_2_0);
new Config(pdfVersion: '2.0');

Available versions

VERSION_1_4 (1.4), VERSION_1_7 (1.7), VERSION_2_0 (2.0)

skipCompression

• Type: bool - Default: false

Do not compress PDFs. Useful for debugging.

customMetadata

• Type: bool - Default: false

Include custom HTML meta tags in PDF metadata.

srgb

• Type: bool - Default: false

Include sRGB color profile.

optimizeImages

• Type: bool - Default: false

Optimize the size of embedded images with no quality loss.

fullFonts

• Type: bool - Default: false

When possible, embed unmodified font files in the PDF.

hinting

• Type: bool - Default: false

Keep hinting information in embedded font files.

dpi

• Type: int|null - Default: null

Set the maximum resolution of images embedded in the PDF. Must be greater than 0 when set.

jpegQuality

• Type: int|null - Default: null

Set the JPEG output quality, from 0 (worst) to 95 (best).

pdfForms

• Type: bool - Default: false

Render PDF forms from HTML elements.

noHttpRedirects

• Type: bool - Default: false

Disable following HTTP redirects.

failOnHttpErrors

• Type: bool - Default: false

Abort the conversion on HTTP errors.

Validation

The Config class validates certain options on construction:

• dpi must be greater than 0 when set.
• jpegQuality must be between 0 and 95 when set.
• inputEncoding must be a valid encoding supported by PHP's mb_list_encodings().

Invalid values will throw an exception immediately, so configuration errors surface early.