{"record":{"id":"1d6dae9615ba33c3","repo":"ramsey/uuid","slug":"expected-version-1-time-based-uuid","errorCode":null,"errorMessage":"Expected version 1 (time-based) UUID","messagePattern":"Expected version 1 \\(time-based\\) UUID","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Codec/OrderedTimeCodec.php","lineNumber":59,"sourceCode":" *\n * @immutable\n */\nclass OrderedTimeCodec extends StringCodec\n{\n    /**\n     * Returns a binary string representation of a UUID, with the timestamp fields rearranged for optimized storage\n     *\n     * @return non-empty-string\n     */\n    public function encodeBinary(UuidInterface $uuid): string\n    {\n        if (\n            /** @phpstan-ignore possiblyImpure.methodCall */\n            !($uuid->getFields() instanceof Rfc4122FieldsInterface)\n            /** @phpstan-ignore possiblyImpure.methodCall */\n            || $uuid->getFields()->getVersion() !== Uuid::UUID_TYPE_TIME\n        ) {\n            throw new InvalidArgumentException('Expected version 1 (time-based) UUID');\n        }\n\n        /** @phpstan-ignore possiblyImpure.methodCall */\n        $bytes = $uuid->getFields()->getBytes();\n\n        return $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5]\n            . $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3]\n            . substr($bytes, 8);\n    }\n\n    /**\n     * Returns a UuidInterface derived from an ordered-time binary string representation\n     *\n     * @throws InvalidArgumentException if $bytes is an invalid length\n     *\n     * @inheritDoc\n     */\n    public function decodeBytes(string $bytes): UuidInterface","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Codec/OrderedTimeCodec.php#L41-L77","documentation":"OrderedTimeCodec::encodeBinary() rearranges the timestamp bytes of a UUID so v1 UUIDs sort naturally in database indexes; it accepts only version 1 (time-based) RFC 4122 UUIDs. If the fields object is not a Rfc4122FieldsInterface or the version nibble is not 1 (Uuid::UUID_TYPE_TIME), it throws InvalidArgumentException. You hit it by asking a non-v1 UUID carrying this codec for its bytes (getBytes() delegates to encodeBinary()).","triggerScenarios":"$factory->setCodec(new OrderedTimeCodec($factory->getUuidBuilder())) set factory-wide, then $factory->uuid4()->getBytes() (or uuid3/uuid5); building a v3/v4/v5 Uuid with an OrderedTimeCodec and serializing it to bytes.","commonSituations":"Enabling ordered-time storage for index friendliness while still generating v4 random UUIDs through the same factory; mixing COMB/ordered-time strategy with non-time UUID versions; codec switched globally instead of per-version.","solutions":["Use OrderedTimeCodec only with version 1 UUIDs (Uuid::uuid1()); leave the default codec (or StringCodec) on factories that produce other versions.","Keep two factory/codec contexts: one OrderedTimeCodec factory for v1, one default factory for everything else.","For time-ordered non-v1 identifiers prefer UUIDv7 (Uuid::uuid7()) or a COMB with TimestampFirstCombCodec instead of ordered-time v1."],"exampleFix":"// before\n$factory->setCodec(new OrderedTimeCodec($factory->getUuidBuilder()));\n$bytes = $factory->uuid4()->getBytes(); // InvalidArgumentException\n\n// after\n$factory->setCodec(new OrderedTimeCodec($factory->getUuidBuilder()));\n$bytes = $factory->uuid1()->getBytes(); // 16 ordered-time bytes","handlingStrategy":"type-guard","validationCode":"// Only encode time-based UUIDs through the ordered-time codec.\n$fields = $uuid->getFields();\nif ($fields instanceof \\Ramsey\\Uuid\\Rfc4122\\FieldsInterface && $fields->getVersion() === Uuid::UUID_TYPE_TIME) {\n    $orderedBytes = $orderedCodec->encodeBinary($uuid);\n}","typeGuard":"/** @psalm-assert-if-true \\Ramsey\\Uuid\\Rfc4122\\UuidV1 $uuid */\nfunction isUuidV1(UuidInterface $uuid): bool\n{\n    return $uuid instanceof \\Ramsey\\Uuid\\Rfc4122\\UuidV1;\n}","tryCatchPattern":"try {\n    $bytes = $uuid->getBytes();\n} catch (\\Ramsey\\Uuid\\Exception\\InvalidArgumentException $e) {\n    // Non-v1 UUID reached the ordered-time codec; fall back to standard bytes.\n    $bytes = $uuid->getFields()->getBytes();\n}","preventionTips":["Scope OrderedTimeCodec to a dedicated v1-only factory; keep the default codec elsewhere.","Type-hint factories and variables as UuidV1 where ordered-time encoding is required.","Prefer UUIDv7 for time-ordered keys - it needs no special codec.","Add an architecture test asserting getBytes() is only called on UuidV1 instances in the ordered-time module."],"tags":["php","ramsey-uuid","ordered-time-codec","codec","uuid-v1"],"backgroundTag":"uuid-version-mismatch","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}