Installs: 453

Dependents: 0

Suggesters: 0

Security: 0

Stars: 2

Watchers: 1

Forks: 0

Open Issues: 0

pkg:composer/antikirra/tsid

3.1.0 2025-10-18 18:08 UTC

This package is auto-updated.

Last update: 2025-10-19 08:12:28 UTC


README

Packagist Dependency Version Packagist Version Code Coverage

Ultra-fast, lightweight PHP library for generating unique timestamp-based identifiers with nanosecond precision. Perfect for distributed systems, high-throughput applications, and scenarios requiring guaranteed unique ID generation without external dependencies.

Install

composer require antikirra/tsid:^3.0

Why TSID?

  • Blazing Fast Performance - Zero dependencies, minimal overhead, optimized for speed
  • 🔧 Universal Compatibility - Works seamlessly from PHP 5.6 to PHP 8.4+
  • Nanosecond Precision - Guaranteed uniqueness even in high-frequency generation
  • 🎯 Snowflake Alternative - Simple, efficient replacement for complex ID generators
  • 📦 Lightweight - Compact, pure PHP implementation with no bloat
  • 🚀 Production Ready - Battle-tested in high-load distributed environments

Features

  • High-Performance ID Generation: Up to 39M+ unique IDs per second (Apple M4, PHP 8.4)
  • Timestamp-Based: IDs contain creation time information for easy sorting and analysis
  • Strictly Monotonic: Guarantees each ID is always greater than the previous, even during clock adjustments
  • Collision-Free: Mathematical guarantee of uniqueness within single process
  • Memory Efficient: Minimal memory footprint, perfect for microservices
  • Legacy Support: Compatible with ancient PHP versions (5.6+) and modern PHP 8.4
  • Zero Dependencies: No external libraries, frameworks, or extensions required
  • Process-Safe: Safe for use in single-threaded PHP processes with static state management
  • 100% Test Coverage: Fully tested with 42 test cases and 5,781 assertions

Perfect for

  • Distributed Systems: Unique ID generation across multiple servers
  • High-Frequency APIs: REST APIs, microservices, real-time applications
  • Database Primary Keys: Alternative to auto-increment IDs in sharded databases
  • Logging & Tracing: Unique request IDs, transaction tracking
  • Message Queues: Job IDs, task identifiers in queue systems
  • Legacy Systems: Drop-in solution for old PHP applications requiring unique IDs

Requirements

  • PHP: 5.6 or higher
  • Extensions: None (uses only core PHP functions)
  • Memory: Minimal (< 1MB)
  • Dependencies: Zero

Basic usage

<?php

use function Antikirra\tsid;
use function Antikirra\tsids;

require __DIR__ . '/vendor/autoload.php';

echo tsid(); // (int) 1752909802717089759

var_dump(tsids(2)); // array(2) { [0] => int(1752909802717089762) [1] => int(1752909802717090791) }

Testing

The library is thoroughly tested with comprehensive test coverage:

  • Test Framework: Pest
  • Total Tests: 42 passing
  • Total Assertions: 5,781
  • Code Coverage: 100% (lines and functions)

Test Categories

  • Basic Functionality: ID generation, type validation, uniqueness
  • Monotonicity: Strictly ascending order verification
  • Batch Generation: Mass ID generation (up to 10,000 IDs)
  • Precision: Nanosecond-level timestamp accuracy
  • Edge Cases: Input validation, boundary conditions
  • Performance: High-frequency generation tests

Keywords

timestamp-id, unique-identifier, php-id-generator, high-performance, snowflake-alternative, distributed-systems, nanosecond-precision, php-5.6-compatible, zero-dependencies, microtime-based-id