{"record":{"id":"687eaa8b2f7ba74f","repo":"ramsey/uuid","slug":"fields-used-to-create-a-uuidv3-must-represent-a-ve","errorCode":null,"errorMessage":"Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID","messagePattern":"Fields used to create a UuidV3 must represent a version 3 \\(name-based, MD5-hashed\\) UUID","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/UuidV3.php","lineNumber":50,"sourceCode":"final class UuidV3 extends Uuid implements UuidInterface\n{\n    /**\n     * Creates a version 3 (name-based, MD5-hashed) UUID\n     *\n     * @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID\n     * @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers\n     * @param CodecInterface $codec The codec to use when encoding or decoding UUID strings\n     * @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a\n     *     UUID to unix timestamps\n     */\n    public function __construct(\n        Rfc4122FieldsInterface $fields,\n        NumberConverterInterface $numberConverter,\n        CodecInterface $codec,\n        TimeConverterInterface $timeConverter,\n    ) {\n        if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_MD5) {\n            throw new InvalidArgumentException(\n                'Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID',\n            );\n        }\n\n        parent::__construct($fields, $numberConverter, $codec, $timeConverter);\n    }\n}\n","sourceCodeStart":32,"sourceCodeEnd":58,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/UuidV3.php#L32-L58","documentation":"Ramsey\\Uuid\\Rfc4122\\UuidV3 wraps a field set that must represent a version 3 (name-based, MD5-hashed) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_HASH_MD5 (3) and throws Ramsey\\Uuid\\Exception\\InvalidArgumentException for any other version nibble. This keeps the class's name-based semantics honest: a UuidV3 instance guarantees it was derived from an MD5 hash of a namespace plus name. The factory/builder normally performs this construction for you.","triggerScenarios":"Calling new UuidV3($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 3 — commonly fields decoded from a version 5 (SHA1) UUID string, or bytes from Uuid::uuid5()/uuid4(). Also custom builders/codecs that always instantiate UuidV3 regardless of the decoded version.","commonSituations":"Hand-wrapping decoded fields in a version-specific class instead of using Uuid::fromString(); mixing up v3 (MD5) and v5 (SHA1) name-based UUIDs; hardcoded class references in a custom codec; fixtures built from a v4 random UUID.","solutions":["Create v3 UUIDs with Uuid::uuid3($namespace, $name) instead of constructing UuidV3 directly","Use Uuid::fromString($uuidString) to wrap existing values — it returns the correct UuidV* class for the version nibble","Before manual construction, assert $fields->getVersion() === Uuid::UUID_TYPE_HASH_MD5 and correct the version bits otherwise","In custom builders, dispatch on $fields->getVersion() and use the base Ramsey\\Uuid\\Uuid for versions you do not map explicitly"],"exampleFix":"// before: $fields decoded from a version 5 UUID string\n$uuid = new UuidV3($fields, $numberConverter, $codec, $timeConverter);\n// InvalidArgumentException: Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID\n\n// after: generate with the factory\n$uuid = Uuid::uuid3($namespace, 'example.com');\n\n// or let the builder pick the class from the string\n$uuid = Uuid::fromString('6fa459ea-ee8a-3ca4-894e-db77e160355e'); // instanceof UuidV3","handlingStrategy":"validation","validationCode":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Uuid;\n\n// Run before constructing UuidV3\nif ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_MD5) {\n    throw new \\InvalidArgumentException(\n        'Cannot build UuidV3 from version ' . $fields->getVersion() . ' fields'\n    );\n}","typeGuard":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Rfc4122\\UuidV3;\nuse Ramsey\\Uuid\\Uuid;\n\nfunction isVersion3Fields(FieldsInterface $fields): bool\n{\n    return $fields->getVersion() === Uuid::UUID_TYPE_HASH_MD5;\n}\n\n$uuid = Uuid::fromString($value);\nif ($uuid instanceof UuidV3) {\n    // safe to treat as MD5 name-based\n}","tryCatchPattern":"use Ramsey\\Uuid\\Exception\\InvalidArgumentException;\n\ntry {\n    $uuid = new UuidV3($fields, $numberConverter, $codec, $timeConverter);\n} catch (InvalidArgumentException $e) {\n    $uuid = Uuid::fromString($fields->getBytes() !== '' ? bin2hex($fields->getBytes()) : '');\n}","preventionTips":["Generate with Uuid::uuid3($namespace, $name); wrap with Uuid::fromString()","Distinguish v3 (MD5) from v5 (SHA1) before choosing a class","Assert the version nibble before direct construction","Avoid hardcoding version-specific classes in codecs/builders"],"tags":["php","ramsey-uuid","uuid","validation","constructor","version-mismatch","md5"],"backgroundTag":"uuid-version-mismatch","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}