From a49763dd739c3c68c4a8322896d594e926ac8e6b Mon Sep 17 00:00:00 2001
From: Zhineng Li <im@zhineng.li>
Date: Mon, 5 Jan 2026 16:26:11 +0800
Subject: first commit

---
 src/Component.php | 33 ++++++++++++++++++++++++++
 src/Constant.php  | 36 +++++++++++++++++++++++++++++
 src/Field.php     | 58 ++++++++++++++++++++++++++++++++++++++++++++++
 src/Makable.php   | 13 +++++++++++
 src/Manager.php   | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/Sequence.php  | 42 +++++++++++++++++++++++++++++++++
 src/Structure.php | 62 +++++++++++++++++++++++++++++++++++++++++++++++++
 src/Timestamp.php | 38 ++++++++++++++++++++++++++++++
 8 files changed, 351 insertions(+)
 create mode 100644 src/Component.php
 create mode 100644 src/Constant.php
 create mode 100644 src/Field.php
 create mode 100644 src/Makable.php
 create mode 100644 src/Manager.php
 create mode 100644 src/Sequence.php
 create mode 100644 src/Structure.php
 create mode 100644 src/Timestamp.php

(limited to 'src')

diff --git a/src/Component.php b/src/Component.php
new file mode 100644
index 0000000..67cf96a
--- /dev/null
+++ b/src/Component.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+interface Component
+{
+    /**
+     * The bit size.
+     */
+    public function bits(): int;
+
+    /**
+     * The component value.
+     */
+    public function value(): int;
+
+    /**
+     * The maximum value based on the number of bits.
+     */
+    public function maxValue(): int;
+
+    /**
+     * Set the bit offset.
+     */
+    public function setOffset(int $offset): Component;
+
+    /**
+     * The bit offset.
+     */
+    public function offset(): int;
+}
diff --git a/src/Constant.php b/src/Constant.php
new file mode 100644
index 0000000..6cd63a7
--- /dev/null
+++ b/src/Constant.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+final class Constant extends Field
+{
+    use Makable;
+
+    public function __construct(
+        string $name,
+        int $bits,
+        public readonly int $value = 0
+    ) {
+        parent::__construct($name, $bits);
+
+        if ($this->value < 0) {
+            throw new \InvalidArgumentException('Field value must be non-negative.');
+        }
+
+        if ($this->value > $this->maxValue()) {
+            throw new \InvalidArgumentException(sprintf(
+                'Field value %d exceeds maximum %d for %d bits.',
+                $this->value,
+                $this->maxValue(),
+                $this->bits
+            ));
+        }
+    }
+
+    public function value(): int
+    {
+        return $this->value;
+    }
+}
diff --git a/src/Field.php b/src/Field.php
new file mode 100644
index 0000000..9e11bad
--- /dev/null
+++ b/src/Field.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+abstract class Field implements Component
+{
+    /**
+     * The bit offset.
+     */
+    private int $offset = 0;
+
+    public function __construct(
+        public readonly string $name,
+        public readonly int $bits,
+    ) {
+        if ($bits < 1 || $bits > 63) {
+            throw new \InvalidArgumentException('Bits must be between 1 and 63.');
+        }
+    }
+
+    /**
+     * The bit size.
+     */
+    public function bits(): int
+    {
+        return $this->bits;
+    }
+
+    /**
+     * The maximum value based on the number of bits.
+     */
+    public function maxValue(): int
+    {
+        return (1 << $this->bits) - 1;
+    }
+
+    /**
+     * Set the bit offset.
+     */
+    public function setOffset(int $offset): static
+    {
+        $this->offset = $offset;
+
+        return $this;
+    }
+
+    /**
+     * The bit offset.
+     */
+    public function offset(): int
+    {
+        return $this->offset;
+    }
+
+    abstract public function value(): int;
+}
diff --git a/src/Makable.php b/src/Makable.php
new file mode 100644
index 0000000..15352dc
--- /dev/null
+++ b/src/Makable.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+trait Makable
+{
+    public static function make(mixed ...$args): static
+    {
+        return new static(...$args);
+    }
+}
diff --git a/src/Manager.php b/src/Manager.php
new file mode 100644
index 0000000..215ec50
--- /dev/null
+++ b/src/Manager.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+final class Manager
+{
+    /**
+     * The ID format.
+     */
+    private Structure $structure;
+
+    /**
+     * The last value except sequence.
+     */
+    private int $lastCombination = 0;
+
+    /**
+     * Set the ID format.
+     */
+    public function structureUsing(Structure $structure): self
+    {
+        $this->structure = $structure;
+        $this->lastCombination = 0;
+
+        return $this;
+    }
+
+    /**
+     * Generate the next Snowflake ID.
+     */
+    public function nextId(): int
+    {
+        if (! isset($this->structure)) {
+            throw new \RuntimeException('ID structure is not defined.');
+        }
+
+        $id = 0;
+        $sequence = null;
+
+        foreach ($this->structure->components() as $field) {
+            // Defer sequence until after detecting other-field changes
+            // so we can reset it if needed.
+            if ($field instanceof Sequence) {
+                $sequence = $field;
+
+                continue;
+            }
+
+            $current = $field->maxValue() & $field->value();
+            $id |= $current << $field->offset();
+        }
+
+        // The ID variable now holds the combination of all fields except
+        // sequence. Reset the sequence field if any other field has changed.
+        if ($this->lastCombination !== $id) {
+            $sequence?->reset();
+        }
+
+        $this->lastCombination = $id;
+
+        if ($sequence instanceof Sequence) {
+            $id |= ($sequence->maxValue() & $sequence->value()) << $sequence->offset();
+        }
+
+        return $id;
+    }
+}
diff --git a/src/Sequence.php b/src/Sequence.php
new file mode 100644
index 0000000..d799e29
--- /dev/null
+++ b/src/Sequence.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+final class Sequence extends Field
+{
+    use Makable;
+
+    /**
+     * The current value.
+     */
+    private int $value = 0;
+
+    public function value(): int
+    {
+        return $this->next();
+    }
+
+    public function next(): int
+    {
+        $current = $this->value++;
+
+        if ($current > $this->maxValue()) {
+            throw new \OverflowException(sprintf(
+                'Sequence "%s" exceeded its maximum value of %d.',
+                $this->name,
+                $this->maxValue()
+            ));
+        }
+
+        return $current;
+    }
+
+    public function reset(): self
+    {
+        $this->value = 0;
+
+        return $this;
+    }
+}
diff --git a/src/Structure.php b/src/Structure.php
new file mode 100644
index 0000000..307397d
--- /dev/null
+++ b/src/Structure.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+final class Structure
+{
+    /**
+     * The ID components.
+     *
+     * @var \Zhineng\Snowflake\Component[]
+     */
+    private array $fields = [];
+
+    /**
+     * The current bit offset.
+     */
+    private int $currentOffset = 0;
+
+    /**
+     * The number of sequence fields added.
+     */
+    private int $sequenceCount = 0;
+
+    /**
+     * Add a field to the structure.
+     */
+    public function add(Component $field): self
+    {
+        if ($field instanceof Sequence && ++$this->sequenceCount > 1) {
+            throw new \LogicException('Only one sequence field is allowed in a structure.');
+        }
+
+        if ($this->currentOffset + $field->bits() > 63) {
+            throw new \OverflowException('Total structure size cannot exceed 63 bits.');
+        }
+
+        $this->fields[] = $field->setOffset($this->currentOffset);
+        $this->currentOffset += $field->bits();
+
+        return $this;
+    }
+
+    /**
+     * The ID components.
+     *
+     * @return \Zhineng\Snowflake\Component[]
+     */
+    public function components(): array
+    {
+        return $this->fields;
+    }
+
+    /**
+     * The total size in bits.
+     */
+    public function size(): int
+    {
+        return $this->currentOffset;
+    }
+}
diff --git a/src/Timestamp.php b/src/Timestamp.php
new file mode 100644
index 0000000..a23ba13
--- /dev/null
+++ b/src/Timestamp.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zhineng\Snowflake;
+
+final class Timestamp extends Field
+{
+    use Makable;
+
+    /**
+     * The epoch in milliseconds.
+     */
+    public readonly int $epoch;
+
+    public function __construct(
+        string $name = 'timestamp',
+        int $bits = 41,
+        \DateTime|int|null $epoch = null
+    ) {
+        parent::__construct($name, $bits);
+
+        $this->epoch = $epoch instanceof \DateTime
+            ? $epoch->getTimestamp() * 1000
+            : ($epoch ?? 0);
+
+        if ($this->epoch < 0) {
+            throw new \InvalidArgumentException('Epoch must be non-negative.');
+        }
+    }
+
+    public function value(): int
+    {
+        $now = (int) floor(microtime(as_float: true) * 1000);
+
+        return $now - $this->epoch;
+    }
+}
-- 
cgit v1.2.3