{"record":{"id":"ddf17038354f3f9b","repo":"Intervention/image","slug":"the-stroke-color-must-be-fully-opaque-ddf170","errorCode":null,"errorMessage":"The stroke color must be fully opaque","messagePattern":"The stroke color must be fully opaque","errorType":"exception","errorClass":"StateException","httpStatus":null,"severity":"error","filePath":"src/Modifiers/TextModifier.php","lineNumber":60,"sourceCode":"            throw new StateException(\n                'The text color must be fully opaque when using the stroke effect',\n            );\n        }\n\n        return $color;\n    }\n\n    /**\n     * Decode outline stroke color.\n     *\n     * @throws StateException\n     */\n    protected function strokeColor(): ColorInterface\n    {\n        $color = $this->driver()->decodeColor($this->font->strokeColor());\n\n        if ($color->isTransparent()) {\n            throw new StateException(\n                'The stroke color must be fully opaque',\n            );\n        }\n\n        return $color;\n    }\n\n    /**\n     * Return array of offset points to draw text stroke effect below the actual text.\n     *\n     * @return array<PointInterface>\n     */\n    protected function strokeOffsets(FontInterface $font): array\n    {\n        $offsets = [];\n\n        if ($font->strokeWidth() <= 0) {\n            return $offsets;","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Modifiers/TextModifier.php#L42-L78","documentation":"TextModifier::strokeColor() decodes the font's stroke color for the text outline effect. Because the outline is drawn underneath the actual text (TextModifier.php:30-33), a fully transparent stroke color would either be invisible or interfere with the layering, so any transparent decoded stroke color throws StateException. Note the default stroke color is opaque white ('ffffff' in Font.php:28), so this only fires when a transparent stroke color is set explicitly.","triggerScenarios":"Setting $font->strokeColor('transparent') or $font->strokeColor('rgba(255, 255, 255, 0)') on a font used with $image->text(); the exception is raised when the driver renders the stroke, not when the color is set.","commonSituations":"Theme-driven watermark configs where 'none' is encoded as 'transparent'; attempting to disable the outline by making it transparent instead of setting strokeWidth to 0; copying color values with an alpha channel of 0 from a design tool.","solutions":["Use a fully opaque stroke color such as '000000' or 'ffffff'","To disable the outline, set $font->strokeWidth(0) instead of a transparent stroke color","Validate configured stroke colors for full opacity before rendering text"],"exampleFix":"// before\n$font->strokeColor('transparent');\n\n// after\n$font->strokeWidth(0); // outline disabled properly","handlingStrategy":"validation","validationCode":"use Intervention\\Image\\Colors\\Rgb\\Color;\n\n// Before rendering stroked text, ensure the stroke color is opaque\n$stroke = $font->strokeColor();\n$isTransparent = $stroke instanceof Color ? $stroke->isTransparent() : $stroke === 'transparent';\n\nif ($isTransparent) {\n    $font->strokeWidth(0); // disable outline instead of a transparent stroke\n}\n\n$image->text('caption', 10, 10, $font);","typeGuard":"function hasOpaqueStrokeColor($font): bool\n{\n    $stroke = $font->strokeColor();\n\n    return !($stroke === 'transparent'\n        || (str_starts_with((string) $stroke, 'rgba') && str_ends_with((string) $stroke, ', 0)')));\n}\n\n// exact check requires decoding through the driver; avoid transparent stroke colors in stroked configs","tryCatchPattern":"use Intervention\\Image\\Exceptions\\StateException;\n\ntry {\n    $image->text('Watermark', 10, 10, $font);\n} catch (StateException $e) {\n    // message: 'The stroke color must be fully opaque'\n    $font->strokeColor('000000');\n    $image->text('Watermark', 10, 10, $font);\n}","preventionTips":["Disable outlines with strokeWidth(0), never with a transparent stroke color","Validate theme/watermark color configs for full opacity before use","Defaults are safe (stroke color 'ffffff'); only explicit transparent values trigger this"],"tags":["text","font","stroke","color","state","intervention-image"],"backgroundTag":"invalid-color-value","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}