Download the PHP package kenzal/mysql-binary-uuids without Composer

Laravel MySQL Binary UUIDs

Store UUIDs and ULIDs as efficient binary(16) columns in MySQL instead of char(36) or char(26), saving storage space and improving index performance.

Table of Contents

• Why Use Binary Storage?
• Requirements
• Installation
• Features
• Usage
• Route Model Binding
• API Reference
• Testing
• Performance Considerations
• Compatibility
• Contributing
• Credits

Why Use Binary Storage?

Storing UUIDs and ULIDs as binary data provides significant benefits:

• Storage Efficiency: Binary(16) uses 16 bytes vs char(36)/char(26) which uses 36/26 bytes
• Index Performance: Smaller indexes mean faster lookups and reduced memory usage
• Native Format: UUIDs/ULIDs are stored in their native binary format
• Compatibility: Works seamlessly with Laravel's UUID/ULID objects

Storage Comparison

Requirements

• PHP 8.2+ (for Laravel 12) or PHP 8.3+ (for Laravel 13)
• Laravel 12.0 or 13.0
• MySQL 5.7 or higher (MySQL 8.0+ recommended)

Compatibility Matrix

Installation

Install via Composer:

The service provider will be automatically registered.

[!CAUTION] Upgrading from String (char) UUIDs

If you're migrating an existing project from char(36) or varchar(36) UUIDs to binary(16):

1. Install this package
2. Update your models to use the traits or casts
3. Create migrations to convert columns
4. Plan for a breaking schema change — test thoroughly in staging first

Key query change: Binary(16) columns store UUIDs/ULIDs as raw bytes, not human-readable strings. When querying, you must pass UuidInterface or Ulid objects — raw strings will not be automatically converted to binary at the connection level:

Route-model binding is handled automatically — string UUIDs/ULIDs from URLs are converted to objects before querying.

Features

✨ Automatic Schema Support

UUIDs are automatically stored as binary(16) when using Laravel's schema builder:

🔄 Eloquent Casts

Cast binary UUID/ULID columns to native Laravel objects:

🎯 Model Traits

Drop-in replacements for Laravel's HasUuids and HasUlids traits:

🛠️ Blueprint Macros

Additional Blueprint methods for ULID columns:

Usage

Basic Usage with Casts

Using Model Traits

The HasBinaryUuids and HasBinaryUlids traits provide automatic ID generation:

Using ULIDs

Custom Unique ID Columns

By default, traits apply to the id column. Customize via the uuidColumns() or ulidColumns() methods:

Custom UUID/ULID Types

You can specify custom UUID/ULID subclasses for specific columns using string keys. This is useful when you need to extend UUIDs with domain-specific behavior.

First, create your custom UUID class:

Then reference it in your model:

The same pattern works with ExtensibleUlid and ulidColumns().

Using Directly in casts()

Since ExtensibleUuid and ExtensibleUlid implement Laravel's Castable interface, you can also use them directly in the casts() array without traits:

Using Both UUID and ULID Columns

A model can have both UUID and ULID columns by using one trait for auto-generation and explicit casts for others:

Migration Examples

Creating Tables with UUIDs

Creating Tables with ULIDs

Nullable UUID/ULID Columns

Working with Existing Data

If you're migrating from string-based UUIDs, create a migration to convert:

Route Model Binding

Binary UUID/ULID columns work seamlessly with Laravel's implicit and explicit route-model binding. The traits handle the conversion automatically — string UUIDs/ULIDs from URLs are converted to UuidInterface/Ulid objects before querying, and the connection handles the binary conversion.

Implicit Binding

With traits, no additional configuration is needed:

Explicit Binding

Works with casts too — register the binding in AppServiceProvider:

Or use Laravel's getRouteKeyName() on the model.

Custom Route Key Names

Override getRouteKeyName() to bind on a different binary UUID/ULID column:

API Reference

Casts

BinaryUuid

Casts binary(16) columns to Ramsey\Uuid\UuidInterface objects.

Methods:

• get(): Converts binary data to UUID object
• set(): Accepts UUID strings or objects, converts to binary

BinaryUlid

Casts binary(16) columns to Symfony\Component\Uid\Ulid objects.

Methods:

• get(): Converts binary data to ULID object
• set(): Accepts ULID strings or objects, converts to binary

Traits

HasBinaryUuids

Provides automatic UUID v7 generation with binary storage.

Features:

• Generates UUID v7 for new models
• Applies BinaryUuid cast to uuidColumns() columns
• Sets $keyType = 'uuid' and $incrementing = false (via HasUniqueStringIds)
• Route-model binding — resolves string UUID URLs against binary(16) columns

Methods:

• newUniqueId(): Generates a new UUID v7
• isValidUniqueId($value): Validates UUID format
• uuidColumns(): Returns array of columns that should have UUIDs (default: ['id'])
  • Supports custom UUID subclasses: ['uuid_id' => DocumentUuid::class]

HasBinaryUlids

Provides automatic ULID generation with binary storage.

Features:

• Generates ULIDs for new models
• Applies BinaryUlid cast to ulidColumns() columns
• Sets $keyType = 'uuid' and $incrementing = false (via HasUniqueStringIds)
• Route-model binding — resolves string ULID URLs against binary(16) columns
• ULIDs are chronologically sortable

Methods:

• newUniqueId(): Generates a new ULID
• isValidUniqueId($value): Validates ULID format
• ulidColumns(): Returns array of columns that should have ULIDs (default: ['id'])
  • Supports custom ULID subclasses: ['ulid_id' => CustomUlid::class]

Blueprint Macros

binaryUlid(string $column = 'ulid')

Create a binary(16) ULID column.

foreignBinaryUlid(string $column)

Create a foreign key column for referencing a binary ULID.

Testing

The package includes a comprehensive test suite:

Run specific test suites:

Performance Considerations

Query Performance

Binary UUIDs maintain excellent query performance. When querying, pass UuidInterface or Ulid objects — the connection automatically converts them to binary:

Index Recommendations

For optimal performance:

1. Always index UUID/ULID foreign keys:

2. Use UUID v7 or ULIDs for time-ordered data:

   • Both have time-based sorting
   • Reduces index fragmentation
   • Better for clustered indexes
3. Consider composite indexes:

Compatibility

UUID Versions

This package works with all UUID versions:

• UUID v4: Random UUIDs
• UUID v7: Time-ordered UUIDs (recommended, used by default)

The HasBinaryUuids trait generates UUID v7 by default for better database performance.

ULID Format

ULIDs are 128-bit identifiers:

• 48-bit timestamp (millisecond precision)
• 80-bit random component
• Lexicographically sortable
• Case-insensitive base32 encoding

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Local Testing Configuration

Copy phpunit.xml.dist to phpunit.xml and customize for your local environment:

Then edit phpunit.xml with your local MySQL credentials:

Note: phpunit.xml is gitignored so your local credentials won't be committed.

Running Tests

Or run specific test suites:

Code Style

This package uses Laravel Pint for code formatting. Before submitting a PR:

Make sure all tests pass and code style checks pass before submitting a PR.

License

This package is open-sourced software licensed under the MIT license.

Credits

• Author: J. Kenzal Hunter, Sr. (PGP Info, PGP Key)
• Laravel: Taylor Otwell and the Laravel community
• Ramsey UUID: Ben Ramsey
• Symfony UID: Symfony community

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history.

Made with ❤️ for the Laravel community