updated docs

docs/_static/theme.css

@@ -0,0 +1,3 @@
+.highlight-php .k {
+  color: #0077aa; /* Example: make PHP keywords a different color */
+}

docs/compatibility.rst

@@ -0,0 +1,34 @@
+Compatibility Matrix
+====================
+
+UUID Support
+------------
+
+- ``v1``, ``v3``, ``v4``, ``v5``: RFC 4122 / RFC 9562 compatible layouts.
+- ``v6``, ``v7``: RFC 9562 time-ordered UUIDs.
+- ``v8``: custom payload strategy inside UUID v8 envelope.
+- ``guid()``: Microsoft-compatible GUID text formatting helper.
+
+Non-UUID Families
+-----------------
+
+- ULID: Crockford Base32 ULID with monotonic and random modes.
+- Snowflake: 64-bit Twitter-style ID (41/5/5/12).
+- Sonyflake: 64-bit Sonyflake-style ID (39/16/8).
+- TBSL: project-specific time-based sortable hex identifier.
+- NanoID and CUID2: URL-safe random IDs.
+- KSUID and XID: sortable short ID families.
+
+Binary and Alternate Encodings
+------------------------------
+
+- UUID / ULID / TBSL: ``toBytes()`` / ``fromBytes()``.
+- UUID / ULID / Snowflake / Sonyflake / TBSL: ``toBase()`` / ``fromBase()``.
+- KSUID / XID: ``toBytes()`` / ``fromBytes()``.
+
+Runtime Requirements
+--------------------
+
+- Minimum PHP: ``8.2``
+- Required extension: ``ext-bcmath``
+- Optional sequence backends: filesystem, in-memory, PSR-16 cache, callback.

docs/conf.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import datetime
+import os
+
+project = "UID"
+author = "Infocyph"
+year_now = datetime.date.today().strftime("%Y")
+copyright = f"2024-{year_now}"
+version = os.environ.get("READTHEDOCS_VERSION", "latest")
+release = version
+language = "en"
+root_doc = "index"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinxcontrib.phpdomain",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "attrs_block",
+    "attrs_inline",
+    "tasklist",
+    "fieldlist",
+]
+
+myst_heading_anchors = 3
+autosectionlabel_prefix_document = True
+todo_include_todos = True
+
+intersphinx_mapping = {
+    "php": ("https://www.php.net/manual/en/", None),
+}
+
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "repository_url": "https://github.com/infocyph/UID",
+    "repository_branch": "main",
+    "path_to_docs": "docs",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_download_button": True,
+    "home_page_in_toc": True,
+    "show_toc_level": 2,
+}
+
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+html_css_files = ["theme.css"]
+html_title = f"UID - {version} Documentation"
+html_show_sourcelink = True
+html_show_sphinx = False
+html_last_updated_fmt = "%Y-%m-%d"

docs/db-storage.rst

@@ -0,0 +1,44 @@
+Database Storage
+================
+
+UID includes ``Infocyph\\UID\\DbStorage`` with recommendations for UUID, ULID, and Snowflake.
+
+UUID
+----
+
+- MySQL: prefer ``BINARY(16)`` for compact indexes.
+- PostgreSQL: prefer native ``UUID`` type.
+- Ordering: ``UUIDv7`` provides better insertion locality than ``UUIDv4``.
+
+ULID
+----
+
+- MySQL: ``CHAR(26)`` (readable) or ``BINARY(16)`` (compact/index-friendly).
+- PostgreSQL: ``CHAR(26)`` or ``BYTEA`` depending on interoperability.
+- Ordering: canonical ULID text is chronologically sortable.
+
+Snowflake and Sonyflake
+-----------------------
+
+- MySQL: ``BIGINT UNSIGNED``.
+- PostgreSQL: ``BIGINT`` if range is safe, otherwise ``NUMERIC(20,0)``.
+- Ordering: numeric sort equals time sort.
+
+TBSL
+----
+
+- Use ``CHAR(20)`` for canonical uppercase hex.
+- Use ``BINARY(10)`` when compactness matters.
+
+Programmatic Access
+-------------------
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\DbStorage;
+
+   $uuidAdvice = DbStorage::uuid();
+   $ulidAdvice = DbStorage::ulid();
+   $snowflakeAdvice = DbStorage::snowflake();

docs/exceptions.rst

@@ -0,0 +1,31 @@
+Exceptions
+==========
+
+Hierarchy
+---------
+
+- ``Infocyph\\UID\\Exceptions\\UIDException``
+- ``Infocyph\\UID\\Exceptions\\UUIDException``
+- ``Infocyph\\UID\\Exceptions\\ULIDException``
+- ``Infocyph\\UID\\Exceptions\\SnowflakeException``
+- ``Infocyph\\UID\\Exceptions\\SonyflakeException``
+- ``Infocyph\\UID\\Exceptions\\FileLockException``
+
+Usage Pattern
+-------------
+
+Catch specific exceptions when you need algorithm-level handling,
+or catch ``UIDException`` for a package-wide fallback.
+
+.. code-block:: php
+
+   <?php
+
+   use Infocyph\UID\Exceptions\UIDException;
+   use Infocyph\UID\UUID;
+
+   try {
+       $uuid = UUID::normalize('{INVALID}');
+   } catch (UIDException $e) {
+       // Handle UID package errors.
+   }

docs/framework-integration.rst

@@ -0,0 +1,40 @@
+Framework Integration
+=====================
+
+Laravel
+-------
+
+- Helper functions are available through Composer autoload.
+- Prefer UUIDv7 or ULID for ordered primary keys.
+- Keep IDs as strings in application boundaries; convert to binary only at persistence edges.
+
+Symfony
+-------
+
+- Helper functions are available through Composer autoload.
+- Prefer central generation through ``Infocyph\\UID\\Id`` inside services.
+
+Generic PHP Apps
+----------------
+
+- Use ``Id::nanoId()`` for short public IDs.
+- Use ``Id::deterministic()`` for stable IDs from payloads.
+- Use config objects for policy/output tuning:
+
+  - ``SnowflakeConfig``
+  - ``SonyflakeConfig``
+  - ``TBSLConfig``
+
+- Use value objects for richer domain models:
+
+  - ``UuidValue``
+  - ``UlidValue``
+  - ``SnowflakeValue``
+  - ``SonyflakeValue``
+  - ``TbslValue``
+
+Distributed Sequence Coordination
+---------------------------------
+
+For PSR-16 cache providers in distributed environments, use
+``PsrSimpleCacheSequenceProvider`` with a synchronizer callback backed by a distributed lock.

docs/helpers.rst

@@ -0,0 +1,80 @@
+Global Helper Functions
+=======================
+
+UID autoloads helper functions from ``src/functions.php``.
+
+UUID Helpers
+------------
+
+- ``uuid1(?string $node = null)``
+- ``uuid3(string $namespace, string $string)``
+- ``uuid4()``
+- ``uuid5(string $namespace, string $string)``
+- ``uuid6(?string $node = null)``
+- ``uuid7(?DateTimeInterface $dateTime = null, ?string $node = null)``
+- ``uuid8(?string $node = null)``
+- ``guid(bool $trim = true)``
+
+UUID Utility Helpers
+--------------------
+
+- ``uuid_nil()``, ``uuid_max()``
+- ``uuid_is_nil(string $uuid)``, ``uuid_is_max(string $uuid)``
+- ``uuid_normalize(string $uuid)``, ``uuid_compact(string $uuid)``
+- ``uuid_urn(string $uuid)``, ``uuid_braces(string $uuid)``
+- ``uuid_to_base(string $uuid, int $base)``, ``uuid_from_base(string $encoded, int $base)``
+
+ULID Helpers
+------------
+
+- ``ulid(?DateTimeInterface $dateTime = null)``
+- ``ulid_monotonic(?DateTimeInterface $dateTime = null)``
+- ``ulid_random(?DateTimeInterface $dateTime = null)``
+- ``ulid_to_base(string $ulid, int $base)``
+- ``ulid_from_base(string $encoded, int $base)``
+
+Snowflake/Sonyflake/TBSL Helpers
+--------------------------------
+
+- ``snowflake(int $datacenter = 0, int $workerId = 0)``
+- ``snowflake_is_valid(string $id)``
+- ``snowflake_to_base(string $id, int $base)``
+- ``snowflake_from_base(string $encoded, int $base)``
+
+- ``sonyflake(int $machineId = 0)``
+- ``sonyflake_is_valid(string $id)``
+- ``sonyflake_to_base(string $id, int $base)``
+- ``sonyflake_from_base(string $encoded, int $base)``
+
+- ``tbsl(int $machineId = 0, bool $sequenced = false)``
+- ``tbsl_is_valid(string $id)``
+- ``tbsl_to_base(string $id, int $base)``
+- ``tbsl_from_base(string $encoded, int $base)``
+
+Short/Random/Opaque Helpers
+---------------------------
+
+- ``nanoid(int $size = 21)``
+- ``nanoid_is_valid(string $id, ?int $size = null)``
+- ``cuid2(int $maxLength = 24)``
+- ``cuid2_is_valid(string $id)``
+- ``opaque_id(int $length = 12)``
+- ``deterministic_id(string $payload, int $length = 24, string $namespace = 'default')``
+
+Other Helpers
+-------------
+
+- ``ksuid(?DateTimeInterface $dateTime = null)``
+- ``xid()``
+
+Example
+-------
+
+.. code-block:: php
+
+   <?php
+
+   $id = uuid7();
+   $ul = ulid_random();
+   $sf = snowflake(1, 2);
+   $short = nanoid(16);