projectsaturnstudios / quickuuid
Simple helper functions to easily generate UUIDs (v4 and v5).
Requires
- php: ^8.2
- ramsey/uuid: ^4.7
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.5 || ^11.0
README
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.