ProjectSaturnStudios/QuickUUID

A simple PHP library providing helper functions to easily generate version 4 (random) and version 5 (name-based, SHA-1) UUIDs. It leverages the robust ramsey/uuid package under the hood.

Features

• Generate UUIDv4.
• Generate UUIDv5 with a specified name and an optional namespace.
• A primary helper new_uuid() that intelligently calls either v4 or v5 generation based on provided arguments.
• Configurable default namespace for UUIDv5 generation.

Installation

Install the package via Composer:

composer require projectsaturnstudios/quickuuid

Basic Usage

<?php

require_once 'vendor/autoload.php'; // Not needed if used within a framework like Laravel that handles autoloading

// Generate a UUIDv4
$uuid4 = new_uuid4();
echo "UUIDv4: $uuid4\n";

// --- UUIDv5 Generation ---

// Define a name for your UUIDv5
$name = 'com.example.myapp.someidentifier';

// Generate a UUIDv5 using the default namespace
// The default namespace is `Ramsey\Uuid\Uuid::NAMESPACE_DNS` unless you define
// the `QUICKUUID_DEFAULT_V5_NAMESPACE` constant before this helper file is loaded.
$uuid5_default_ns = new_uuid5($name);
echo "UUIDv5 (default NS): $uuid5_default_ns\n";

// Generate a UUIDv5 with a custom namespace
$customNamespace = 'a1b2c3d4-e5f6-7788-9900-aabbccddeeff'; // Replace with your actual valid UUID namespace
if (Ramsey\Uuid\Uuid::isValid($customNamespace)) {
    $uuid5_custom_ns = new_uuid5($name, $customNamespace);
    echo "UUIDv5 (custom NS - '{$customNamespace}'): $uuid5_custom_ns\n";
} else {
    echo "Custom namespace '{$customNamespace}' is not a valid UUID.\n";
}

// --- General Purpose new_uuid() Helper ---

// No name provided, so it generates a UUIDv4
$another_uuid4 = new_uuid(); 
echo "Another UUIDv4: $another_uuid4\n";

// Name provided, so it generates a UUIDv5 with the default namespace
$another_uuid5_default_ns = new_uuid($name);
echo "Another UUIDv5 (default NS): $another_uuid5_default_ns\n";

// Name and custom namespace provided for UUIDv5 generation
if (Ramsey\Uuid\Uuid::isValid($customNamespace)) {
    $another_uuid5_custom_ns = new_uuid($name, $customNamespace); 
echo "Another UUIDv5 (custom NS - '{$customNamespace}'): $another_uuid5_custom_ns\n";
}

?>

UUIDv5 Namespace Configuration

The new_uuid5() and new_uuid() (when generating a v5 UUID) functions use a default namespace. This default is Ramsey\Uuid\Uuid::NAMESPACE_DNS.

You can change this application-wide default by defining the QUICKUUID_DEFAULT_V5_NAMESPACE constant before the quickuuid/src/Helpers/helpers.php file is loaded by Composer. Make sure the value you define is a valid UUID string.

Example (e.g., in your bootstrap/app.php or an early Composer autoloaded file):

if (!defined('QUICKUUID_DEFAULT_V5_NAMESPACE')) {
    define('QUICKUUID_DEFAULT_V5_NAMESPACE', 'YOUR-OWN-DEFAULT-NAMESPACE-UUID'); // Replace with your actual UUID
}

// Composer will then load quickuuid's helpers, which will use this constant.

Dependencies

• PHP ^8.2
• ramsey/uuid: ^4.7

Running Quality Assurance

This package uses PHPUnit for tests and PHPStan for static analysis.

To run tests:

composer test

To run static analysis:

composer analyse

License

This package is licensed under the MIT License. See the LICENSE.md file for details.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.