{"record":{"id":"34fb0cb7d75e8d7e","repo":"ramsey/uuid","slug":"fields-used-to-create-a-uuidv7-must-represent-a-ve","errorCode":null,"errorMessage":"Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID","messagePattern":"Fields used to create a UuidV7 must represent a version 7 \\(Unix Epoch time\\) UUID","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/UuidV7.php","lineNumber":51,"sourceCode":"    use TimeTrait;\n\n    /**\n     * Creates a version 7 (Unix Epoch time) 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_UNIX_TIME) {\n            throw new InvalidArgumentException(\n                'Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID',\n            );\n        }\n\n        parent::__construct($fields, $numberConverter, $codec, $timeConverter);\n    }\n}\n","sourceCodeStart":33,"sourceCodeEnd":59,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/UuidV7.php#L33-L59","documentation":"Ramsey\\Uuid\\Rfc4122\\UuidV7 wraps a field set that must represent a version 7 (Unix Epoch time-ordered) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_UNIX_TIME (7) and throws Ramsey\\Uuid\\Exception\\InvalidArgumentException otherwise. The invariant matters because UuidV7 exposes time-based accessors (getDateTime()) that only make sense for the 48-bit Unix-timestamp layout. Version 7 support arrived in ramsey/uuid 4.7, so mixed-version environments are a common source of mismatched bytes.","triggerScenarios":"Calling new UuidV7($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 7 — e.g. fields from a v4 UUID produced by an older generator, or bytes from Uuid::uuid1(). Also custom builders that instantiate UuidV7 for every time-ordered UUID including v1/v6.","commonSituations":"Migrating from v4/v1 to v7 while application code still wraps all bytes in UuidV7; third-party systems emitting v6 (reordered time) UUIDs consumed as v7; fixture files with hardcoded v4 strings fed into v7 code paths.","solutions":["Generate v7 UUIDs with Uuid::uuid7($dateTime) instead of constructing UuidV7 manually","Wrap existing values with Uuid::fromString()/Uuid::fromBytes() so the builder resolves the class from the version nibble","Verify $fields->getVersion() === Uuid::UUID_TYPE_UNIX_TIME before constructing UuidV7 directly","In custom builders, branch on getVersion() (v1 -> UuidV1, v6 -> UuidV6, v7 -> UuidV7) instead of hardcoding one class"],"exampleFix":"// before: $fields carry version 6 bits but the code assumes v7\n$uuid = new UuidV7($fields, $numberConverter, $codec, $timeConverter);\n// InvalidArgumentException: Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID\n\n// after: generate a time-ordered v7\n$uuid = Uuid::uuid7();\n\n// or resolve the class from existing bytes\n$uuid = Uuid::fromBytes($bytes);\nif ($uuid instanceof \\Ramsey\\Uuid\\Rfc4122\\UuidV7) {\n    $timestamp = $uuid->getDateTime();\n}","handlingStrategy":"validation","validationCode":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Uuid;\n\n// Run before constructing UuidV7\nif ($fields->getVersion() !== Uuid::UUID_TYPE_UNIX_TIME) {\n    throw new \\InvalidArgumentException(\n        'Cannot build UuidV7 from version ' . $fields->getVersion() . ' fields'\n    );\n}","typeGuard":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Rfc4122\\UuidV7;\nuse Ramsey\\Uuid\\Uuid;\n\nfunction isVersion7Fields(FieldsInterface $fields): bool\n{\n    return $fields->getVersion() === Uuid::UUID_TYPE_UNIX_TIME;\n}\n\n$uuid = Uuid::fromString($value);\nif ($uuid instanceof UuidV7) {\n    $created = $uuid->getDateTime();\n}","tryCatchPattern":"use Ramsey\\Uuid\\Exception\\InvalidArgumentException;\n\ntry {\n    $uuid = new UuidV7($fields, $numberConverter, $codec, $timeConverter);\n} catch (InvalidArgumentException $e) {\n    $uuid = new Ramsey\\Uuid\\Uuid($fields, $numberConverter, $codec, $timeConverter);\n}","preventionTips":["Generate with Uuid::uuid7(); wrap with Uuid::fromString()/fromBytes()","During v4-to-v7 migrations, gate time-based logic on instanceof UuidV7 or getVersion()","Do not conflate v1/v6 (Gregorian/reordered time) with v7 (Unix epoch) — the version nibble differs","Assert the version nibble before direct construction"],"tags":["php","ramsey-uuid","uuid","validation","constructor","version-mismatch","uuidv7","time-ordered"],"backgroundTag":"uuid-version-mismatch","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}