UUIDv7

Chaque identifiant d’enregistrement storh est un UUIDv7 : un horodatage en millisecondes sur 48 bits suivi d’entropie aléatoire, au format standard UUID de 36 caractères. Comme l’horodatage vient en premier, les identifiants se trient par heure de création ; cette seule propriété permet la plupart des usages de storh : pagination par curseur (after($id)), lectures par plage horaire, saut de segments dans le journal et ordre stable partout.

$id = Storh\UuidV7::generate();

Storh\UuidV7::is_valid($id);          // bool, accepts upper and lower case
Storh\UuidV7::assert_valid($id);      // throws StorageException instead
$timestampMs = Storh\UuidV7::timestamp_ms($id);

La génération est monotone au sein d’un processus : les identifiants créés dans la même milliseconde incrémentent l’entropie précédente au lieu d’en générer une nouvelle ; même les rafales d’écritures rapides restent donc triées dans leur ordre de création.

Accès par date

Pour définir des fenêtres temporelles, storh dérive les valeurs minimale et maximale possibles de UUIDv7 pour un horodatage en millisecondes, puis compare les identifiants à ces bornes :

$query = Storh\RecordQuery::all()->time_range_ms(
    1_700_000_000_000,
    1_700_000_060_000,
);

$lower = Storh\UuidV7::min_for_timestamp_ms(1_700_000_000_000);
$upper = Storh\UuidV7::max_for_timestamp_ms(1_700_000_060_000);

C’est pourquoi les lectures par plage horaire n’ont pas besoin de champ d’horodatage dans les données de l’enregistrement : l’identifiant contient l’heure de création.

Fournir vos propres identifiants

Tous les moteurs acceptent un identifiant explicite pour chaque écriture ($docs->put($data, $id)) ainsi qu’un appelable id_generator dans leurs constructeurs. Les identifiants générés par l’une ou l’autre méthode sont validés en tant que UUIDv7 ; vos générateurs personnalisés doivent donc en produire. Les générateurs déterministes permettent à la suite de tests de créer des données de test reproductibles. UuidV7::reset_for_tests() efface l’état de monotonie au niveau du processus entre les cas de test.