{"record":{"id":"5d80b24ec13f64e8","repo":"ramsey/uuid","slug":"value-must-be-a-hexadecimal-number","errorCode":null,"errorMessage":"Value must be a hexadecimal number","messagePattern":"Value must be a hexadecimal number","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Type/Hexadecimal.php","lineNumber":125,"sourceCode":"        }\n        // @codeCoverageIgnoreEnd\n\n        $this->unserialize($data['string']);\n    }\n\n    /**\n     * @return non-empty-string\n     */\n    private function prepareValue(string $value): string\n    {\n        $value = strtolower($value);\n\n        if (str_starts_with($value, '0x')) {\n            $value = substr($value, 2);\n        }\n\n        if (!preg_match('/^[A-Fa-f0-9]+$/', $value)) {\n            throw new InvalidArgumentException('Value must be a hexadecimal number');\n        }\n\n        /** @var non-empty-string */\n        return $value;\n    }\n}\n","sourceCodeStart":107,"sourceCodeEnd":132,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Type/Hexadecimal.php#L107-L132","documentation":"Ramsey\\Uuid\\Type\\Hexadecimal is the value object for hexadecimal numbers (used by Uuid::fromHexadecimal() and node/field accessors). prepareValue() lowercases the input, strips an optional leading '0x', and then requires the remainder to match /^[A-Fa-f0-9]+$/ — a non-empty run of hex digits. Anything else, including an empty string or a bare '0x', throws Ramsey\\Uuid\\Exception\\InvalidArgumentException.","triggerScenarios":"Constructing new Hexadecimal('#ff6600') (CSS-style hash), new Hexadecimal(''), new Hexadecimal('0x') (prefix only), new Hexadecimal('g123'), or a string containing whitespace like 'a1b2 c3'. Also user-supplied hex input from forms or APIs passed through unvalidated.","commonSituations":"Color codes copied from CSS; concatenating an optional '0x' prefix onto an empty variable; substr() operations that leave an empty string; copy/paste of hex with a '#' or spaces; feeds from external systems using different hex notations.","solutions":["Strip non-hex decorations before constructing: ltrim($value, '#') and remove whitespace","Validate before construction: after removing an optional '0x', check $value !== '' && ctype_xdigit($value)","Normalize input to lowercase hex digits only — the class lowercases anyway","Default empty inputs to a meaningful value or reject them at the API boundary"],"exampleFix":"// before\n$hex = new Hexadecimal('#ff6600');\n// InvalidArgumentException: Value must be a hexadecimal number\n\n// after: strip decorations and validate\n$raw = strtolower(ltrim($input, '#'));\nif ($raw === '' || !ctype_xdigit($raw)) {\n    throw new \\InvalidArgumentException('Expected a hexadecimal number');\n}\n$hex = new Hexadecimal($raw); // 'ff6600'","handlingStrategy":"validation","validationCode":"// Run before constructing Hexadecimal\n$raw = strtolower(trim((string) $value));\n$raw = preg_replace('/^0x/', '', $raw) ?? '';\n$raw = ltrim($raw, '#');\nif ($raw === '' || !ctype_xdigit($raw)) {\n    throw new \\InvalidArgumentException('Expected a hexadecimal number, got: ' . $value);\n}","typeGuard":"function isHexadecimalString(string $value): bool\n{\n    $value = preg_replace('/^0x/i', '', $value) ?? '';\n    return $value !== '' && ctype_xdigit($value);\n}","tryCatchPattern":"use Ramsey\\Uuid\\Exception\\InvalidArgumentException;\n\ntry {\n    $hex = new Hexadecimal($input);\n} catch (InvalidArgumentException $e) {\n    throw new \\InvalidArgumentException('hex field must contain only hex digits', 0, $e);\n}","preventionTips":["Strip '#' prefixes and whitespace at the input boundary","Reject empty strings and a bare '0x' before construction","Use ctype_xdigit() for validation — it matches the library's own rule","For color-like hex inputs, normalize explicitly before reuse"],"tags":["php","ramsey-uuid","hexadecimal","validation","type-object"],"backgroundTag":"hex-validation-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}