ramsey/uuidThe `ramsey/uuid` library is a robust and widely-used PHP package for generating and working with Universally Unique Identifiers (UUIDs). UUIDs are 128-bit numbers used to uniquely identify information in computer systems. Their primary purpose is to enable distributed systems to assign unique identifiers without a central coordinating authority, minimizing the likelihood of collisions.\n\n`ramsey/uuid` provides comprehensive support for various UUID versions as defined by RFC 4122 and later drafts:\n* Version 1 (Time-based): Generated using the current timestamp and the MAC address of the computer.\n* Version 3 (Name-based, MD5): Generated by hashing a name (e.g., URL, OID, FQDN) with MD5.\n* Version 4 (Random): Generated using purely random numbers. This is the most commonly used version due to its simplicity and high collision resistance.\n* Version 5 (Name-based, SHA-1): Similar to Version 3 but uses SHA-1 hashing, offering better cryptographic strength.\n* Version 6 (Reordered Time-based): A draft standard designed to provide better database indexing performance than v1 by reordering the timestamp fields.\n* Version 7 (Unix Epoch Time-based): A draft standard designed for better database indexing and human readability by starting with a Unix epoch timestamp. It's gaining popularity for modern applications.\n* Version 8 (Custom): A draft standard allowing for custom-defined UUIDs.\n* NIL UUID: A special UUID consisting of all zeros.\n* MAX UUID: A special UUID consisting of all ones.\n\nKey features of the `ramsey/uuid` library include:\n1. UUID Generation: Easily generate UUIDs of different versions.\n2. Parsing and Validation: Convert string representations of UUIDs into `UuidInterface` objects and validate their format.\n3. Node Provider Support: Supports different methods for obtaining the 'node' portion of time-based UUIDs (e.g., MAC address, random nodes).\n4. Serialization: Convert UUID objects to their string representation, byte string, or JSON representation.\n5. Immutability: UUID objects are immutable, ensuring consistency.\n6. Database Integration: Often used in conjunction with ORMs like Doctrine to handle UUIDs as primary keys.\n\nTo install `ramsey/uuid`, you typically use Composer: `composer require ramsey/uuid`. It's an essential tool for any PHP application requiring unique, distributed identifiers.
Example Code
<?php\n\nrequire 'vendor/autoload.php';\n\nuse Ramsey\Uuid\Uuid;\nuse Ramsey\Uuid\Exception\UnserializableValueException;\n\necho "Ramsey/Uuid Example\n\n";\n\n// --- 1. Generating a UUID v4 (Random) ---\n// This is the most common type and suitable for most general-purpose unique identifiers.\n$uuidV4 = Uuid::uuid4();\necho "UUID v4 (Random): " . $uuidV4->toString() . "\n";\necho "UUID v4 Version: " . $uuidV4->getVersion() . "\n\n";\n\n// --- 2. Generating a UUID v1 (Time-based) ---\n// Uses the current timestamp and MAC address (if available, otherwise a random node).\ntry {\n $uuidV1 = Uuid::uuid1();\n echo "UUID v1 (Time-based): " . $uuidV1->toString() . "\n";\n echo "UUID v1 Version: " . $uuidV1->getVersion() . "\n";\n echo "UUID v1 Node: " . $uuidV1->getNodeHex() . "\n"; // MAC address or random\n echo "UUID v1 Timestamp: " . $uuidV1->getDateTime()->format('Y-m-d H:i:s.u') . "\n\n";\n} catch (UnserializableValueException $e) {\n echo "Could not generate UUID v1: " . $e->getMessage() . "\n\n";\n}\n\n\n// --- 3. Generating a UUID v3 (Name-based, MD5) ---\n// Requires a namespace UUID and a name.\n$namespace = Uuid::uuid5(Uuid::NAMESPACE_URL, 'example.com'); // Using a predefined namespace\n$uuidV3 = Uuid::uuid3($namespace, 'my-resource-name');\necho "UUID v3 (Name-based, MD5): " . $uuidV3->toString() . "\n";\necho "UUID v3 Version: " . $uuidV3->getVersion() . "\n\n";\n\n// --- 4. Generating a UUID v5 (Name-based, SHA-1) ---\n// Similar to v3 but uses SHA-1 hashing, which is cryptographically stronger.\n$uuidV5 = Uuid::uuid5(Uuid::NAMESPACE_URL, 'another-resource-name');\necho "UUID v5 (Name-based, SHA-1): " . $uuidV5->toString() . "\n";\necho "UUID v5 Version: " . $uuidV5->getVersion() . "\n\n";\n\n// --- 5. Generating a UUID v6 (Reordered Time-based) ---\n// Offers better database indexing than v1.\n$uuidV6 = Uuid::uuid6();\necho "UUID v6 (Reordered Time-based): " . $uuidV6->toString() . "\n";\necho "UUID v6 Version: " . $uuidV6->getVersion() . "\n";\necho "UUID v6 Timestamp: " . $uuidV6->getDateTime()->format('Y-m-d H:i:s.u') . "\n\n";\n\n// --- 6. Generating a UUID v7 (Unix Epoch Time-based) ---\n// A modern time-based UUID, good for database indexing and human readability.\n$uuidV7 = Uuid::uuid7();\necho "UUID v7 (Unix Epoch Time-based): " . $uuidV7->toString() . "\n";\necho "UUID v7 Version: " . $uuidV7->getVersion() . "\n";\necho "UUID v7 Timestamp: " . $uuidV7->getDateTime()->format('Y-m-d H:i:s.u') . "\n\n";\n\n\n// --- 7. Parsing an existing UUID string ---\n$uuidString = 'a1b2c3d4-e5f6-7890-1234-567890abcdef';\ntry {\n $parsedUuid = Uuid::fromString($uuidString);\n echo "Parsed UUID: " . $parsedUuid->toString() . "\n";\n echo "Parsed UUID Version: " . $parsedUuid->getVersion() . "\n\n";\n} catch (\InvalidArgumentException $e) {\n echo "Failed to parse UUID: " . $e->getMessage() . "\n\n";\n}\n\n// --- 8. Validating a UUID string ---\n$validUuid = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';\n$invalidUuid = 'not-a-valid-uuid';\n\nif (Uuid::isValid($validUuid)) {\n echo "Validation: '" . $validUuid . "' is a valid UUID.\n";\n} else {\n echo "Validation: '" . $validUuid . "' is NOT a valid UUID.\n";\n}\n\nif (Uuid::isValid($invalidUuid)) {\n echo "Validation: '" . $invalidUuid . "' is a valid UUID.\n";\n} else {\n echo "Validation: '" . $invalidUuid . "' is NOT a valid UUID.\n";\n}\n\necho "\n--- Additional Operations ---\n";\n\n// Get as bytes\n$uuidBytes = $uuidV4->getBytes();\necho "UUID v4 as bytes (raw): " . bin2hex($uuidBytes) . "\n";\n\n// Compare UUIDs\n$anotherUuidV4 = Uuid::uuid4();\nif ($uuidV4->equals($anotherUuidV4)) {\n echo "UUIDs are equal (unlikely for random ones).\n";\n} else {\n echo "UUIDs are not equal.\n";\n}\n\n// Convert to array\n$uuidArray = $uuidV4->jsonSerialize();\necho "UUID v4 as array (JSON serializable): " . json_encode($uuidArray) . "\n";\n?>