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.

sferea / spot-uuid-binary

Maintainers

Details