sferea/spot-uuid-binary

UUID BINARY(16) support for vlucas/spot2

v1.0.1 2026-01-12 17:25 UTC

Requires

• php: >=8.1
• vlucas/spot2: ^2.0 || dev-master

MIT

• Martín Isaí Zapata Ramos

README

UUID BINARY(16) support for 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

• 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

• PHP >= 8.1
• vlucas/spot2 ^2.0

Installation

composer require sferea/spot-uuid-binary

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

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

• 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

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

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

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

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

MIT License

Author

Martín Isaí Zapata Ramos

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.