You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -17,15 +16,120 @@ Install this package as a dependency using Composer.
17
16
composer require cycle/entity-behavior-identifier
18
17
```
19
18
20
-
## Snowflake Examples
19
+
## Usage
21
20
22
-
**Snowflake:** A distributed ID generation system developed by Twitter that produces 64-bit unique, sortable identifiers. Each ID encodes a timestamp, machine ID, and sequence number, enabling high-throughput, ordered ID creation suitable for large-scale distributed applications.
21
+
The package provides various types of identifiers, for generating unique values or as alternatives to auto-increment
22
+
IDs, helping ensure uniqueness and flexibility across an application.
23
23
24
-
> **Note:** Support for Snowflake identifiers will arrive soon, stay tuned.
24
+
> **Note: ** Most identifiers encode metadata such as node ID and epoch offset. These values are typically
25
+
> derived from the platform or system rather than defined within an entity. Each applicable listener class provides a
26
+
> `setDefaults` method to allow these values to be set at an appropriate time within your application.
25
27
26
-
## ULID Examples
28
+
For example:
27
29
28
-
**ULID (Universally Unique Lexicographically Sortable Identifier):** A 128-bit identifier designed for high uniqueness and lexicographical sortability. It combines a timestamp component with random data, allowing for ordered IDs that can be generated rapidly and are human-readable, making it ideal for databases and distributed systems.
**Snowflake (Generic):** A flexible Snowflake implementation that generates globally unique, time-ordered 64-bit IDs
39
+
without adhering to any specific platform’s conventions, suitable for general distributed systems.
40
+
41
+
```php
42
+
use Cycle\Annotated\Annotation\Column;
43
+
use Cycle\Annotated\Annotation\Entity;
44
+
use Cycle\ORM\Entity\Behavior\Identifier;
45
+
use Ramsey\Identifier\Snowflake;
46
+
47
+
#[Entity]
48
+
#[Identifier\SnowflakeGeneric(field: 'id')]
49
+
class User
50
+
{
51
+
#[Column(type: 'id', primary: true)]
52
+
public Snowflake $id;
53
+
}
54
+
```
55
+
56
+
**Snowflake (Discord):** Implements Discord’s Snowflake format, generating 64-bit IDs that encode a timestamp,
57
+
worker ID, and sequence number. Useful when interoperating with Discord’s API or matching its ID structure.
58
+
59
+
```php
60
+
use Cycle\Annotated\Annotation\Column;
61
+
use Cycle\Annotated\Annotation\Entity;
62
+
use Cycle\ORM\Entity\Behavior\Identifier;
63
+
use Ramsey\Identifier\Snowflake;
64
+
65
+
#[Entity]
66
+
#[Identifier\SnowflakeDiscord(field: 'id')]
67
+
class User
68
+
{
69
+
#[Column(type: 'id', primary: true)]
70
+
public Snowflake $id;
71
+
}
72
+
```
73
+
74
+
**Snowflake (Instagram):** Follows Instagram’s Snowflake structure to produce unique, sortable 64-bit IDs suitable for
75
+
applications that need compatibility with Instagram-style ID sequences.
76
+
77
+
```php
78
+
use Cycle\Annotated\Annotation\Column;
79
+
use Cycle\Annotated\Annotation\Entity;
80
+
use Cycle\ORM\Entity\Behavior\Identifier;
81
+
use Ramsey\Identifier\Snowflake;
82
+
83
+
#[Entity]
84
+
#[Identifier\SnowflakeInstagram(field: 'id')]
85
+
class User
86
+
{
87
+
#[Column(type: 'id', primary: true)]
88
+
public Snowflake $id;
89
+
}
90
+
```
91
+
92
+
**Snowflake (Mastodon):** Generates IDs compatible with Mastodon’s distributed Snowflake system, encoding time and node
93
+
information to ensure uniqueness across instances.
94
+
95
+
```php
96
+
use Cycle\Annotated\Annotation\Column;
97
+
use Cycle\Annotated\Annotation\Entity;
98
+
use Cycle\ORM\Entity\Behavior\Identifier;
99
+
use Ramsey\Identifier\Snowflake;
100
+
101
+
#[Entity]
102
+
#[Identifier\SnowflakeMastodon(field: 'id')]
103
+
class User
104
+
{
105
+
#[Column(type: 'id', primary: true)]
106
+
public Snowflake $id;
107
+
}
108
+
```
109
+
110
+
**Snowflake (Twitter):** Produces 64-bit IDs in the format used by Twitter, encoding timestamp, machine ID, and sequence
111
+
number for globally unique, time-sortable identifiers. Ideal for high-throughput distributed systems.
112
+
113
+
```php
114
+
use Cycle\Annotated\Annotation\Column;
115
+
use Cycle\Annotated\Annotation\Entity;
116
+
use Cycle\ORM\Entity\Behavior\Identifier;
117
+
use Ramsey\Identifier\Snowflake;
118
+
119
+
#[Entity]
120
+
#[Identifier\SnowflakeTwitter(field: 'id')]
121
+
class User
122
+
{
123
+
#[Column(type: 'id', primary: true)]
124
+
public Snowflake $id;
125
+
}
126
+
```
127
+
128
+
### ULID Examples
129
+
130
+
**ULID (Universally Unique Lexicographically Sortable Identifier):** A 128-bit identifier designed for high uniqueness
131
+
and lexicographical sortability. It combines a timestamp component with random data, allowing for ordered IDs that can
132
+
be generated rapidly and are human-readable, making it ideal for databases and distributed systems.
29
133
30
134
```php
31
135
use Cycle\Annotated\Annotation\Column;
@@ -42,9 +146,10 @@ class User
42
146
}
43
147
```
44
148
45
-
## UUID Examples
149
+
###UUID Examples
46
150
47
-
**UUID Version 1 (Time-based):** Generated using the current timestamp and the MAC address of the computer, ensuring unique identification based on time and hardware.
151
+
**UUID Version 1 (Time-based):** Generated using the current timestamp and the MAC address of the computer, ensuring
152
+
unique identification based on time and hardware.
48
153
49
154
```php
50
155
use Cycle\Annotated\Annotation\Column;
@@ -61,7 +166,8 @@ class User
61
166
}
62
167
```
63
168
64
-
**UUID Version 2 (DCE Security):** Similar to version 1 but includes a local identifier such as a user ID or group ID, primarily used in DCE security contexts.
169
+
**UUID Version 2 (DCE Security):** Similar to version 1 but includes a local identifier such as a user ID or group ID,
170
+
primarily used in DCE security contexts.
65
171
66
172
```php
67
173
use Cycle\Annotated\Annotation\Column;
@@ -78,7 +184,8 @@ class User
78
184
}
79
185
```
80
186
81
-
**UUID Version 3 (Name-based, MD5):** Created by hashing a namespace identifier and name using MD5, resulting in a deterministic UUID based on input data.
187
+
**UUID Version 3 (Name-based, MD5):** Created by hashing a namespace identifier and name using MD5, resulting in a
188
+
deterministic UUID based on input data.
82
189
83
190
```php
84
191
use Cycle\Annotated\Annotation\Column;
@@ -99,7 +206,8 @@ class User
99
206
}
100
207
```
101
208
102
-
**UUID Version 4 (Random):** Generated entirely from random or pseudo-random numbers, offering high unpredictability and uniqueness.
209
+
**UUID Version 4 (Random):** Generated entirely from random or pseudo-random numbers, offering high unpredictability
210
+
and uniqueness.
103
211
104
212
```php
105
213
use Cycle\Annotated\Annotation\Column;
@@ -116,7 +224,8 @@ class User
116
224
}
117
225
```
118
226
119
-
**UUID Version 5 (Name-based, SHA-1):** Similar to version 3 but uses SHA-1 hashing, providing a different deterministic UUID based on namespace and name.
227
+
**UUID Version 5 (Name-based, SHA-1):** Similar to version 3 but uses SHA-1 hashing, providing a different deterministic
228
+
UUID based on namespace and name.
120
229
121
230
```php
122
231
use Cycle\Annotated\Annotation\Column;
@@ -137,7 +246,8 @@ class User
137
246
}
138
247
```
139
248
140
-
**UUID Version 6 (Draft/Upcoming):** An experimental or proposed version focused on improving time-based UUIDs with more sortable properties (not yet widely adopted).
249
+
**UUID Version 6 (Draft/Upcoming):** An experimental or proposed version focused on improving time-based UUIDs with more
250
+
sortable properties (not yet widely adopted).
141
251
142
252
```php
143
253
use Cycle\Annotated\Annotation\Column;
@@ -154,7 +264,8 @@ class User
154
264
}
155
265
```
156
266
157
-
**UUID Version 7 (Draft/Upcoming):** A newer proposal designed to incorporate sortable features based on Unix timestamp, enhancing performance in database indexing.
267
+
**UUID Version 7 (Draft/Upcoming):** A newer proposal designed to incorporate sortable features based on Unix timestamp,
268
+
enhancing performance in database indexing.
158
269
159
270
```php
160
271
use Cycle\Annotated\Annotation\Column;
@@ -171,7 +282,7 @@ class User
171
282
}
172
283
```
173
284
174
-
You can find more information about Entity behavior UUID [here](https://cycle-orm.dev/docs/entity-behaviors-identifier).
285
+
Read more about identifier generation in [Entity Behaviors: Identifiers](https://cycle-orm.dev/docs/entity-behaviors/identifiers.md).
0 commit comments