Custom Fonts for DOMPDF
When integrating DOMPDF into a PHP project, relying on system-installed fonts often leads to inconsistent output across different server environments. Developers frequently encounter issues where specific typefaces requested in CSS simply do not render, falling back to defaults or causing layout shifts. The core problem lies in understanding how DOMPDF handles font registration and the strict requirements for TTF files within its rendering pipeline.
The user's attempt to utilize 'Airplanes in the Night Sky' (likely referring to "Nightsky") alongside standard fonts like Segoe Print and Lucida Handwriting highlights a common misconception: CSS @font-face rules are not sufficient on their own. DOMPDF does not fetch fonts from external CDNs or local web font files automatically. To use these fonts, they must be explicitly registered with the PDF engine before the HTML content is parsed.
The TTF Requirement
The most frequent point of failure is the file format. DOMPDF requires TrueType Font (.ttf) files for full Unicode support and consistent rendering. If you are attempting to use OpenType Collection (.otc) or PostScript Type 1 (.pfb/.pfm) formats without conversion, the library will fail to map the font family to a usable font file. You must ensure that every custom font referenced in your HTML is available as a .ttf file within your application's directory structure.
Registering Fonts with font_dir
The mechanism for adding these fonts is defined in the DOMPDF_Config class, specifically via the font_dir property. This configuration option points to a directory where DOMPDF will look for registered fonts. You cannot simply place a .ttf file in your public/assets/fonts folder and expect it to work; you must explicitly tell DOMPDF about it.
The standard approach involves loading the config file and setting the font_dir to point to a specific subdirectory containing your TTF files. Once this path is set, you must call add_font() for each font family you intend to use. This method accepts the font file path, a unique font name (which will appear in PDF metadata), optional encoding, and whether the font should be subsetted.
Here is how the configuration logic typically looks when initializing the DOMPDF instance:
require_once('dompdf_config.inc.php');
$fontDir = 'path/to/your/custom_fonts'; // Directory containing .ttf files
$dompdf = new DOMPDF();
$dompdf->load_config();
$dompdf->set_option('font_dir', $fontDir);
// Register the custom font
// 1. Font file path: relative or absolute
// 2. Font family name: used in CSS (case-insensitive)
// 3. Encoding: usually 'utf-8' for modern fonts
// 4. Subset: true reduces PDF size by including only used characters
$dompdf->add_font('Nightsky', 'path/to/Airplanes_in_the_Night_Sky.ttf', '', true);
// Register standard custom fonts if they are available as TTF
$dompdf->add_font('SegoePrint', 'path/to/SegoePrint.ttf', '', true);
$dompdf->add_font('LucidaHandwriting', 'path/to/LucidaHandwriting.ttf', '', true);
CSS Mapping and Encoding
Once the fonts are registered, your HTML and CSS must match the font family name exactly (ignoring case). In the provided code snippet, the user defines div.ClJ{font: nightsky;}. This will only work if 'Nightsky' was passed as the second argument to add_font().
However, a critical detail often overlooked is the encoding. If your custom font supports Unicode characters, you must pass 'utf-8' as the third parameter to add_font(). If the encoding is left empty or set to 'cp1252', any characters outside that ASCII range will appear as squares or missing glyphs in the generated PDF.
Streamlining the Workflow
While manually calling add_font() for every new typeface works, it can become tedious. A more robust pattern involves creating a helper method in your controller or service layer to handle font registration dynamically based on an array of file paths and names. This keeps your main logic clean and ensures that all required fonts are loaded before the render() call is triggered.
Remember that DOMPDF caches font subsets. If you modify a font file after the initial render, you may need to clear the cache or restart the PHP process depending on how your deployment environment handles static files. For production environments, ensure that the path provided to font_dir exists and is readable by the web server user (e.g., www-data), as permission errors here will silently result in font fallbacks.
For teams building complex PDF generation pipelines within the Laravel ecosystem, maintaining a centralized directory for these assets and referencing them consistently helps avoid the "it works on my machine" problem. If you require further assistance with integrating DOMPDF into your specific stack, resources like https://laravelcompany.com can provide additional context on deployment best practices.