{"record":{"id":"058335d839c9e8ab","repo":"Intervention/image","slug":"the-stroke-color-must-be-fully-opaque-058335","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/Drivers/Imagick/Modifiers/TextModifier.php","lineNumber":96,"sourceCode":"    }\n\n    /**\n     * Create a ImagickDraw object to draw the outline stroke effect on the Image\n     *\n     * @throws StateException\n     * @throws DriverException\n     * @throws RuntimeException\n     */\n    private function imagickDrawStroke(ImageInterface $image, FontInterface $font): ?ImagickDraw\n    {\n        if (!$font->hasStrokeEffect()) {\n            return null;\n        }\n\n        $color = $this->driver()->decodeColor($font->strokeColor());\n\n        if ($color->isTransparent()) {\n            throw new StateException(\n                'The stroke color must be fully opaque',\n            );\n        }\n\n        $color = $this->driver()->colorProcessor($image)->export($color);\n\n        return $this->processor()->toImagickDraw($font, $color);\n    }\n\n    /**\n     * Maybe draw given line of text on frame instance depending on given\n     * ImageDraw instance. Optionally move line position by given offset.\n     *\n     * @throws ModifierException\n     */\n    private function maybeDrawTextline(\n        FrameInterface $frame,\n        Line $textline,","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/TextModifier.php#L78-L114","documentation":"StateException from the Imagick text modifier: the stroke color (decoded from the font's strokeColor setting) is transparent while a stroke effect is active. This mirrors the text-fill check - ImageMagick cannot render a stroke outline from a fully transparent color, so the modifier fails before drawing anything.","triggerScenarios":"$image->text('label', $x, $y, fn ($font) => $font->color('fff')->stroke('transparent', 2)), or any stroke color with alpha 0 ('rgba(0,0,0,0)', 8-digit hex ending in 00) while strokeWidth > 0.","commonSituations":"Configurable text styles where an empty stroke color defaults to 'transparent'; conditionally disabling the stroke by setting a transparent stroke color instead of removing the effect; palette-driven designs that include a fully transparent variant.","solutions":["Remove the stroke effect entirely when no outline is wanted (do not set a stroke color at all)","Use an opaque stroke color such as '#000000' or 'rgba(0,0,0,1)'","Only set strokeColor when strokeWidth is greater than zero, with a validated opaque value"],"exampleFix":"// before\n$image->text('hi', 0, 0, fn ($font) => $font\n    ->color('#ffffff')\n    ->stroke('transparent', 2)\n);\n\n// after - no stroke effect at all\n$image->text('hi', 0, 0, fn ($font) => $font\n    ->color('#ffffff')\n);","handlingStrategy":"validation","validationCode":"// omit the stroke entirely when no outline is wanted\n$callback = function ($font) use ($textColor, $strokeColor, $strokeWidth) {\n    $font->color($textColor);\n    if ($strokeWidth > 0 && isOpaqueHexColor($strokeColor)) {\n        $font->stroke($strokeColor, $strokeWidth);\n    }\n};\n$image->text($caption, $x, $y, $callback);","typeGuard":"function isOpaqueHexColor(string $color): bool\n{\n    return (bool) preg_match('/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i', $color);\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\StateException;\n\ntry {\n    $image->text($caption, $x, $y, $fontCallback);\n} catch (StateException $e) {\n    throw new InvalidArgumentException('Invalid stroke config: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Do not use 'transparent' as a way to disable the stroke - remove the stroke call","Only set strokeColor when strokeWidth > 0","Validate style presets against the opaque-color rule in unit tests"],"tags":["imagick","text","font","stroke","color","state"],"backgroundTag":"invalid-color-value","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}