Download the PHP package michalsn/codeigniter4-uuid without Composer

CodeIgniter 4 UUID

UUID and ULID support for CodeIgniter 4 with seamless Model integration.

Installation

Configuration

Publish the configuration file:

This creates app/Config/Uuid.php where you can customize the defaults:

Usage

Model Integration

Use the HasUuid trait to add UUID support to your models:

The trait automatically:

• Generates UUIDs for the primary key on insert
• Handles UUID conversion for find(), update(), and delete() operations
• Supports both single and batch inserts

[!NOTE] If you already use initialize() method in your model, then you have to add $this->initUuid() call inside this method to make the UUID package work.

Cast Syntax

The uuid cast accepts optional parameters for version and storage type:

UUID on Non-Primary Key Fields

You can use UUIDs on any field, not just primary keys:

UUIDs are only auto-generated for the primary key field. For other fields, you must provide the value:

Storage Types

String Storage (default)

Stores UUIDs as 36-character strings (e.g., 550e8400-e29b-41d4-a716-446655440000).

Binary Storage

Stores UUIDs as 16-byte binary for better performance and smaller storage footprint, but at the cost of readability.

With binary storage:

• The model returns UUIDs as RFC4122 strings (human-readable)
• Internally converts to binary for database operations
• Supports MySQL, PostgreSQL, SQLite3, Oracle, and SQL Server

UUID Service

Generate UUIDs using the service:

Working with UUIDs:

Parse existing UUIDs:

Validate UUIDs:

Supported UUID Versions

Recommendation: Use UUID v7 for new projects. It provides:

• Chronological ordering (great for database indexes)
• Better performance than v4 for sorted queries
• Standard UUID format compatibility

Migration from v1

Breaking Changes

1. Dependency Change: Switched from ramsey/uuid to symfony/uid
2. UUID v2 Removed: UUID v2 (DCE Security) is no longer supported
3. Removed Classes: UuidModel, UuidEntity, UuidCast (old location) removed
4. New Trait-Based Approach: Use HasUuid trait instead of extending UuidModel
5. Type-Safe Versions: Use UuidVersion and UuidType enum instead of string constants

Migration Steps

1. Update composer.json

Run composer update.

2. Update Model Classes

Before (v1):

After (v2):

3. Update Entity Classes

Before (v1):

After (v2):

Entities no longer need special handling. Use standard CodeIgniter entities - the model's cast handles UUID conversion automatically.

4. Update Configuration

Before (v1):

After (v2):

5. Update UUID String Conversion (Optional)

The old Ramsey UUID method names still work for backward compatibility:

6. Remove v2 Usage

If you were using UUID v2, you'll need to migrate to a different version (v4 or v7 recommended).

7. Accessing the Underlying Symfony UID (Optional)

If you need direct access to the underlying Symfony UID object:

New Features in v2

• ULID Support: Generate and parse ULIDs alongside UUIDs
• SQLite Support: Binary UUID storage now works with SQLite3
• Backward Compatible API: Old Ramsey method names (toString(), getBytes()) still work

License

The MIT License (MIT). Please see License File for more information.