{"record":{"id":"4aca64c205b60428","repo":"Intervention/image","slug":"normalized-color-value-must-be-in-range-0-to-1-4aca64","errorCode":null,"errorMessage":"Normalized color value must be in range 0 to 1","messagePattern":"Normalized color value must be in range 0 to 1","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Colors/Hsl/Colorspace.php","lineNumber":57,"sourceCode":"     * @see ColorspaceInterface::colorFromNormalized()\n     *\n     * @throws InvalidArgumentException\n     */\n    public static function colorFromNormalized(array $normalized): HslColor\n    {\n        if (!in_array(count($normalized), [3, 4])) {\n            throw new InvalidArgumentException('Number of color channels must be 3 or 4 for ' . static::class);\n        }\n\n        // add alpha value if missing\n        $normalized = count($normalized) === 3 ? array_pad($normalized, 4, 1) : $normalized;\n\n        return new Color(...array_map(\n            function (string $channel, null|float $normalized) {\n                try {\n                    return $channel::fromNormalized($normalized);\n                } catch (TypeError $e) {\n                    throw new InvalidArgumentException(\n                        'Normalized color value must be in range 0 to 1',\n                        previous: $e,\n                    );\n                }\n            },\n            self::$channels,\n            $normalized,\n        ));\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see ColorspaceInterface::importColor()\n     *\n     * @throws ColorException\n     */\n    public function importColor(ColorInterface $color): HslColor","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Hsl/Colorspace.php#L39-L75","documentation":"Inside Hsl\\Colorspace::colorFromNormalized() each normalized value is passed to the channel factory FloatColorChannel/IntColorChannel::fromNormalized(), which declares a float parameter. Passing null therefore raises a PHP TypeError, which the colorspace catches and converts to this InvalidArgumentException stating 'Normalized color value must be in range 0 to 1'. Despite the message, the actual cause for this specific error is a null (or non-float) entry - out-of-range floats throw a different exception from the channel itself.","triggerScenarios":"Hsl\\Colorspace::colorFromNormalized([0.5, null, 0.5]) - arrays built from nullable database columns, optional API fields, or array_map over data containing nulls. Also any non-float type the channel factory cannot accept (e.g. strings under strict_types).","commonSituations":"Colors assembled from Eloquent/Doctrine records where saturation or alpha is NULL when unspecified; JSON payloads with optional channel keys; defaults applied after the call instead of before.","solutions":["Replace nulls with defaults before calling: $values = array_map(fn ($v) => $v ?? 0.0, $values)","Coerce types: $values = array_map(fn ($v) => floatval($v ?? 0.0), $values)","If null means 'use default alpha', omit the 4th entry entirely (3-entry array gets alpha 1.0)","Reject nulls at the data boundary (form request / API validation) instead of inside image code"],"exampleFix":"// before\n$color = Hsl\\Colorspace::colorFromNormalized($row); // $row = [0.5, null, 0.5]\n\n// after\n$row = array_map(fn ($v) => floatval($v ?? 0.0), $row);\n$color = Hsl\\Colorspace::colorFromNormalized($row);","handlingStrategy":"validation","validationCode":"$normalized = array_map(\n    fn ($v) => is_finite((float) $v) ? floatval($v) : 0.0,\n    array_map(fn ($v) => $v ?? 0.0, $normalized)\n);\nif (in_array(null, $normalized, true)) {\n    throw new InvalidArgumentException('null channel value');\n}","typeGuard":"function hasNoNullChannels(array $values): bool\n{\n    return !in_array(null, $values, true);\n}","tryCatchPattern":null,"preventionTips":["Map nullable columns/keys to defaults before conversion: $v ?? 0.0","Remember the 'range' message can actually mean a null entry","Omit the alpha entry entirely when it is null - the colorspace defaults it to 1.0"],"tags":["php","intervention-image","color","hsl","null-handling","type-error","normalized-value"],"backgroundTag":"null-argument-type-error","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}