first commit

1 files changed, 109 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3d74b4a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# Snowflake ID Generator
+
+A flexible, customizable distributed ID generator inspired by Twitter's
+Snowflake, built for PHP 8.2+.
+
+Unlike traditional implementations with hard-coded structures, this package
+lets you **build your own ID format** to perfectly suit your application's
+needs.
+
+## Installation
+
+The package can be installed through Composer:
+
+```bash
+composer require lizhineng/snowflake
+```
+
+**Requirements:** PHP 8.2 or higher
+
+## Quick Start
+
+```php
+use Zhineng\Snowflake\Constant;
+use Zhineng\Snowflake\Manager;
+use Zhineng\Snowflake\Sequence;
+use Zhineng\Snowflake\Structure;
+use Zhineng\Snowflake\Timestamp;
+
+$structure = new Structure;
+$structure->add(Sequence::make('sequence', 12));
+$structure->add(Constant::make('instance', 10));
+$structure->add(Timestamp::make('timestamp', 41));
+
+$manager = new Manager;
+$manager->structureUsing($structure);
+
+$id1 = $manager->nextId(); // e.g., 123456789012345678
+$id2 = $manager->nextId(); // e.g., 123456789012345679
+```
+
+## Usage
+
+### Field Types
+
+#### Timestamp
+
+Timestamp field tracks milliseconds since epoch, defaulting to 41 bits
+and the name `timestamp`:
+
+```php
+Timestamp::make();
+```
+
+Optionally set a custom epoch via the third parameter—accepts a `DateTime`
+object or an integer (milliseconds since Unix epoch):
+
+```php
+$epoch = new \DateTime('2026-01-01 00:00:00');
+Timestamp::make('timestamp', 41, $epoch);
+```
+
+#### Constant
+
+Fixed value field for static identifiers (e.g., datacenter ID, machine ID).
+Value defaults to 0 if not specified.
+
+```php
+// Machine ID with value 5 (10 bits)
+Constant::make('machine_id', 10, 5);
+
+// Datacenter ID with value 2 (5 bits)
+Constant::make('datacenter_id', 5, 2);
+```
+
+#### Sequence
+
+Auto-incrementing sequence that resets to 0 whenever any other field changes.
+An `OverflowException` is thrown if the value exceeds its maximum.
+
+```php
+// 12-bit sequence (range 0-4095)
+Sequence::make('sequence', 12);
+```
+
+### Building Custom Structures
+
+Customize the ID format to suit your needs—the structure is built from
+**right to left** (LSB to MSB):
+
+```php
+$structure = new Structure;
+
+// Bit layout: [timestamp:41][instance:10][sequence:12] = 63 bits
+$structure->add(Sequence::make('sequence', 12));
+$structure->add(Constant::make('instance', 10));
+$structure->add(Timestamp::make('timestamp', 41));
+
+echo $structure->size(); // 63
+```
+
+## Testing
+
+```bash
+composer run test
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.