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(5mo ago)0464↓77.8%MITPHPPHP >=8.1

Since Jan 12Pushed 5mo 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 3d 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

37

—

LowBetter than 81% of packages

Maintenance70

Regular maintenance activity

Popularity16

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

173d 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

[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k117.2M118](/packages/jdorn-sql-formatter)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M87](/packages/propel-propel1)[jfelder/oracledb

Oracle DB driver for Laravel

11518.4k](/packages/jfelder-oracledb)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)