PHPackages sferea/spot-uuid-binary - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. sferea/spot-uuid-binary ActiveLibrary[Database & ORM](/categories/database) sferea/spot-uuid-binary ======================= UUID BINARY(16) support for vlucas/spot2 v1.0.1(4mo ago)0397↓50%MITPHPPHP >=8.1 Since Jan 12Pushed 4mo agoCompare [ Source](https://github.com/sferea/spot2-uuid-binary)[ Packagist](https://packagist.org/packages/sferea/spot-uuid-binary)[ RSS](/packages/sferea-spot-uuid-binary/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (1)Versions (3)Used By (0) sferea/spot-uuid-binary ======================= [](#sfereaspot-uuid-binary) UUID `BINARY(16)` support for [`vlucas/spot2`](https://github.com/vlucas/spot2) This library extends **Spot2 ORM** to properly support **UUIDs stored as `BINARY(16)`**, enabling transparent conversion between UUID string and binary representations, and allowing correct usage of UUID binary keys in Spot relations. Spot2 does not natively support UUID binary fields. This package provides a clean, explicit, and non-intrusive solution. --- Features -------- [](#features) - UUID string ↔ `BINARY(16)` automatic conversion - Value Object for UUID handling - UUID-aware `BelongsTo` and `HasMany` relations - PSR-4 compliant - No Spot core overrides - Opt-in per entity / relation --- Requirements ------------ [](#requirements) - PHP >= 8.1 - `vlucas/spot2 ^2.0` --- Installation ------------ [](#installation) ``` composer require sferea/spot-uuid-binary ``` --- Library Initialization (Important) ---------------------------------- [](#library-initialization-important) This library **does not require initialization or bootstrapping**. Once installed with Composer, the library is available immediately. The functionality becomes active only when: - A trait is used inside an Entity - A UUID-aware Relation class is instantiated This keeps the integration explicit and predictable. --- Usage ----- [](#usage) ### 1. Using UUID Binary in an Entity [](#1-using-uuid-binary-in-an-entity) Add the provided trait to your Spot entity. ``` use Sferea\Spot\Traits\HandlerUuidBinary; class User extends \Spot\Entity { use HandlerUuidBinary; protected static $fields = [ 'id' => [ 'type' => 'uuid_binary', 'primary' => true ] ]; } ``` ### Behavior [](#behavior) - If the value is loaded from the database as `BINARY(16)`, it is converted to a UUID string - If the value is assigned as a UUID string, it is converted to `BINARY(16)` - Accessing the field returns a `UuidBinary` value object ``` $user->id->string; // UUID string $user->id->binary; // BINARY(16) (string) $user->id; // BINARY(16) (for database usage) ``` --- UUID Value Object ----------------- [](#uuid-value-object) ### `UuidBinary` [](#uuidbinary) ``` use Sferea\Spot\UuidBinary; $uuid = new UuidBinary( '550e8400-e29b-41d4-a716-446655440000', UuidBinary::TYPE_STRING ); $uuid->string; // UUID string $uuid->binary; // BINARY(16) ``` The value object guarantees consistent UUID conversion and representation. --- Relations with UUID Binary Keys ------------------------------- [](#relations-with-uuid-binary-keys) Spot2 relations fail when primary or foreign keys are stored as UUID binary. This library provides UUID-aware relation classes that solve this limitation. --- ### UuidBelongsTo [](#uuidbelongsto) ``` use Sferea\Spot\Relation\CustomBelongsTo; public static function relations(\Spot\Mapper $mapper, Entity $entity) { return [ 'user' => new CustomBelongsTo( $mapper, $entity, User::class, 'userId.binary' ) ]; } ``` - Supports `BINARY(16)` primary and foreign keys - Supports nested local keys (e.g. `meta.userId`) - Does not modify Spot core behavior --- ### UuidHasMany [](#uuidhasmany) ``` use Sferea\Spot\Relation\CustomHasMany; public static function relations(\Spot\Mapper $mapper, Entity $entity) { return [ 'otpRequests' => new CustomHasMany( $mapper, $entity, OtpRequest::class, 'userId.binary', 'userId' ) ]; } ``` License ------- [](#license) MIT License --- Author ------ [](#author) Martín Isaí Zapata Ramos --- Why This Library? ----------------- [](#why-this-library) Using UUIDs stored as `BINARY(16)`: - Reduces storage size - Improves index performance - Is a production-grade approach This library brings first-class UUID binary support to vlucas/Spot2 without breaking its design philosophy. ### Health Score 38 — LowBetter than 85% of packages Maintenance77 Regular maintenance activity Popularity17 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 126d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dcea844b27395800577717a9f836411b452fe3bd0590049abb80c05989df5275?d=identicon)[Mardock](/maintainers/Mardock) --- Top Contributors [![MartinZptRms](https://avatars.githubusercontent.com/u/53628788?v=4)](https://github.com/MartinZptRms "MartinZptRms (1 commits)") ### Embed Badge ![Health badge](/badges/sferea-spot-uuid-binary/health.svg) ``` [![Health](https://phpackages.com/badges/sferea-spot-uuid-binary/health.svg)](https://phpackages.com/packages/sferea-spot-uuid-binary) ``` ### Alternatives [doctrine/orm Object-Relational-Mapper for PHP 10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter a PHP SQL highlighting library 3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database The Illuminate Database package. 2.8k52.4M9.4k](/packages/illuminate-database)[ramsey/uuid-doctrine Use ramsey/uuid as a Doctrine field type. 90440.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel Reliese Components for Laravel Framework code generation. 1.7k3.4M16](/packages/reliese-laravel)[wildside/userstamps Laravel Userstamps provides an Eloquent trait which automatically maintains `created\_by` and `updated\_by` columns on your model, populated by the currently authenticated user in your application. 7511.7M13](/packages/wildside-userstamps) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)