{"record":{"id":"4a84df72bc30f6f2","repo":"PHPOffice/PHPWord","slug":"pdf-rendering-library-or-library-path-has-not-been-defined","errorCode":null,"errorMessage":"PDF rendering library or library path has not been defined.","messagePattern":"PDF rendering library or library path has not been defined\\.","errorType":"exception","errorClass":"PhpOffice\\PhpWord\\Exception\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpWord/Writer/PDF.php","lineNumber":48,"sourceCode":" */\nclass PDF\n{\n    /**\n     * The wrapper for the requested PDF rendering engine.\n     *\n     * @var AbstractRenderer\n     */\n    private $renderer;\n\n    /**\n     * Instantiate a new renderer of the configured type within this container class.\n     */\n    public function __construct(PhpWord $phpWord)\n    {\n        $pdfLibraryName = Settings::getPdfRendererName();\n        $pdfLibraryPath = Settings::getPdfRendererPath();\n        if (null === $pdfLibraryName || null === $pdfLibraryPath) {\n            throw new Exception('PDF rendering library or library path has not been defined.');\n        }\n\n        $includePath = str_replace('\\\\', '/', get_include_path());\n        $rendererPath = str_replace('\\\\', '/', $pdfLibraryPath);\n        if (strpos($rendererPath, $includePath) === false) {\n            set_include_path(get_include_path() . PATH_SEPARATOR . $pdfLibraryPath);\n        }\n\n        $rendererName = static::class . '\\\\' . $pdfLibraryName;\n        $this->renderer = new $rendererName($phpWord);\n    }\n\n    /**\n     * Magic method to handle direct calls to the configured PDF renderer wrapper class.\n     *\n     * @param string $name Renderer library method name\n     * @param mixed[] $arguments Array of arguments to pass to the renderer method\n     *","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/PHPOffice/PHPWord/blob/aef95c04151b5633cc505f672ddd6a71da900ee1/src/PhpWord/Writer/PDF.php#L30-L66","documentation":"The PDF writer delegates rendering to an external library (Dompdf/TCPDF/MPDF) configured via Settings::setPdfRendererName() and Settings::setPdfRendererPath(). The constructor requires both to be configured; if either is null the PDF backend is unusable and it throws before any rendering is attempted.","triggerScenarios":"Creating a PDF writer (e.g. IOFactory::createWriter($phpWord, 'PDF')) without first calling Settings::setPdfRendererName() and Settings::setPdfRendererPath(); config set in one environment but missing in another; library path pointing outside available include paths.","commonSituations":"New deployments where the PDF bootstrap code was omitted; using the 'PDF' writer for the first time; framework config files not loaded in CLI workers; upgrading PhpWord where default renderer settings changed.","solutions":["Configure both settings before constructing the writer: Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF) and Settings::setPdfRendererPath('/path/to/dompdf').","Ensure the chosen rendering library is installed (composer require dompdf/dompdf) and its path is correct.","Verify with Settings::getPdfRendererName()/getPdfRendererPath() before creating the writer.","Wrap writer construction in try/catch and fall back to another export format (e.g. HTML) when PDF support is not configured."],"exampleFix":"// before\n$writer = \\PhpOffice\\PhpWord\\IOFactory::createWriter($phpWord, 'PDF'); // throws: renderer not defined\n// after\nSettings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF);\nSettings::setPdfRendererPath('/var/www/vendor/dompdf/dompdf');\n$writer = \\PhpOffice\\PhpWord\\IOFactory::createWriter($phpWord, 'PDF');\n$writer->save('doc.pdf');","handlingStrategy":"validation","validationCode":"function pdfConfigured(): bool {\n    return \\PhpOffice\\PhpWord\\Settings::getPdfRendererName() !== null\n        && \\PhpOffice\\PhpWord\\Settings::getPdfRendererPath() !== null;\n}\n// call before: if (!pdfConfigured()) { configurePdfRenderer(); }","typeGuard":null,"tryCatchPattern":"try {\n    $writer = \\PhpOffice\\PhpWord\\IOFactory::createWriter($phpWord, 'PDF');\n} catch (\\PhpOffice\\PhpWord\\Exception\\Exception $e) {\n    if (str_contains($e->getMessage(), 'PDF rendering library')) {\n        Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF);\n        Settings::setPdfRendererPath($dompdfPath);\n        $writer = \\PhpOffice\\PhpWord\\IOFactory::createWriter($phpWord, 'PDF');\n    } else { throw $e; }\n}","preventionTips":["Centralize PDF renderer settings in bootstrap config loaded in every entry point (web + CLI + workers).","Verify the renderer library is installed and its path exists at deploy time.","Add a health check that asserts getPdfRendererName()/Path() are non-null.","Document the required Settings calls where the PDF writer is first used in the codebase."],"tags":["phpword","pdf","config","settings"],"backgroundTag":"missing-required-config","analyzedSha":"aef95c04151b5633cc505f672ddd6a71da900ee1","analyzedAt":"2026-09-14T10:53:58.933Z","contentChangedAt":"2026-09-14T10:53:58.933Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}