{"record":{"id":"e9bb3f5893aa7e0f","repo":"PHPOffice/PHPWord","slug":"the-gd-extension-is-required-to-process-gd-images","errorCode":null,"errorMessage":"The GD extension is required to process GD images.","messagePattern":"The GD extension is required to process GD images\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/PhpWord/Element/Image.php","lineNumber":403,"sourceCode":"                    $actualSource = Settings::getTempDir() . DIRECTORY_SEPARATOR . $imageFilename;\n                }\n            }\n            $zip->close();\n        } else {\n            $actualSource = $source;\n        }\n\n        // Can't find any case where $actualSource = null hasn't captured by\n        // preceding exceptions. Please uncomment when you find the case and\n        // put the case into Element\\ImageTest.\n        // if ($actualSource === null) {\n        //     return null;\n        // }\n\n        // Read image binary data and convert to hex/base64 string\n        if ($this->sourceType == self::SOURCE_GD) {\n            if (!extension_loaded('gd')) {\n                throw new RuntimeException('The GD extension is required to process GD images.');\n            }\n            $imageResource = call_user_func($this->imageCreateFunc, $actualSource);\n            if ($this->imageType === 'image/png') {\n                // PNG images need to preserve alpha channel information\n                imagesavealpha($imageResource, true);\n            }\n            ob_start();\n            $callback = $this->imageFunc;\n            $callback($imageResource);\n            $imageBinary = ob_get_contents();\n            ob_end_clean();\n        } elseif ($this->sourceType == self::SOURCE_STRING) {\n            $imageBinary = $this->source;\n        } else {\n            $fileHandle = fopen($actualSource, 'rb', false);\n            $fileSize = filesize($actualSource);\n            if ($fileHandle !== false && $fileSize > 0) {\n                $imageBinary = fread($fileHandle, $fileSize);","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/PHPOffice/PHPWord/blob/aef95c04151b5633cc505f672ddd6a71da900ee1/src/PhpWord/Element/Image.php#L385-L421","documentation":"When an Image was created from a GD image resource (SOURCE_GD), getImageString() must re-encode the image via the PHP GD extension. If ext-gd is not loaded, a RuntimeException is thrown because the image cannot be serialized into the document. This is an environment/extension problem, not a data problem.","triggerScenarios":"Creating an Image from a GD resource (e.g. imagecreatefrompng) and calling getImageString()/getImageStringData() on a PHP build compiled without GD.","commonSituations":"Minimal Docker/Alpine PHP images without php-gd, shared hosting without GD enabled, or forgetting to install/enable the extension after a PHP upgrade.","solutions":["Install/enable the GD extension: e.g. apt-get install php-gd or docker-php-ext-install gd, then restart PHP.","Verify with extension_loaded('gd') or php -m | grep gd before processing GD images.","Load the image from a file path or binary string instead of a GD resource, avoiding the GD code path.","Add ext-gd to composer.json require so deployment tooling enforces it."],"exampleFix":"// before\n$image = new Image($section, $gdResource);\n// after\nif (!extension_loaded('gd')) { throw new RuntimeException('Enable ext-gd'); }\n$image = new Image($section, $gdResource);","handlingStrategy":"fallback","validationCode":"if (!extension_loaded('gd')) {\n    // avoid the GD source path; load image from file/bytes instead\n}","typeGuard":"function gdAvailable(): bool { return extension_loaded('gd') && function_exists('imagecreatefromstring'); }","tryCatchPattern":"try { $data = $image->getImageStringData(); } catch (\\RuntimeException $e) { $data = file_get_contents($imagePath); }","preventionTips":["Install/enable ext-gd in all environments (Dockerfile, CI, prod)","Add ext-gd to composer.json require","Prefer file-path or string image sources when GD isn't guaranteed"],"tags":["phpword","gd","missing-extension","environment"],"backgroundTag":"missing-dependency","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"}