https://github.com/ramsey/identifier
A PHP library for generating and working with identifiers, including UUIDs, ULIDs, and Snowflakes
https://github.com/ramsey/identifier
guid id identifier php snowflake uid ulid uuid
Last synced: about 2 months ago
JSON representation
A PHP library for generating and working with identifiers, including UUIDs, ULIDs, and Snowflakes
- Host: GitHub
- URL: https://github.com/ramsey/identifier
- Owner: ramsey
- License: mit
- Created: 2022-09-10T23:07:47.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-10T03:25:57.000Z (4 months ago)
- Last Synced: 2025-06-10T04:21:46.770Z (4 months ago)
- Topics: guid, id, identifier, php, snowflake, uid, ulid, uuid
- Language: PHP
- Homepage:
- Size: 811 KB
- Stars: 46
- Watchers: 4
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
ramsey/identifier
A PHP library for generating and working with identifiers
## About
ramsey/identifier is a PHP library designed for generating, parsing, and working with a variety of unique identifiers.
It provides an object-oriented interface for several industry-standard identifier formats—including UUIDs, ULIDs, and
Snowflake IDs. This library emphasizes standards-compliance, interoperability, and developer ergonomics, making it easy
to create and manipulate identifiers in modern PHP applications.
This project adheres to a [code of conduct](CODE_OF_CONDUCT.md). By participating in this project and its community, you
are expected to uphold this code.
## Installation
Install this package as a dependency using [Composer](https://getcomposer.org).
``` bash
composer require ramsey/identifier
```
## Usage
ramsey/identifier provides ways to generate industry-standard identifiers, such as UUIDs, ULIDs, and Snowflake IDs. You
can do this using the provided factory classes:
```php
use Ramsey\Identifier\Snowflake\GenericSnowflakeFactory;
use Ramsey\Identifier\Snowflake\Epoch;
use Ramsey\Identifier\Ulid\UlidFactory;
use Ramsey\Identifier\Uuid\UuidFactory;
// Create a UUID.
$uuid = (new UuidFactory())->create();
// Create a ULID.
$ulid = (new UlidFactory())->create();
// Create a Snowflake.
$snowflake = (new GenericSnowflakeFactory(1, Epoch::Unix))->create();
```
With `UuidFactory`, you may create UUIDs of different versions:
```php
use Ramsey\Identifier\Uuid\NamespaceId;
$factory = new UuidFactory();
// Create random UUIDs (version 4).
$uuidV4 = $factory->v4();
// Create named-based UUIDs using SHA-1 hashing (version 5).
$uuidV5 = $factory->v5(NamespaceId::Url, 'https://example.com/post/1234');
// Create Unix Epoch time-based UUIDs (version 7).
$uuidV7 = $factory->v7();
```
You may also parse existing identifiers:
```php
// Parse a UUID.
$uuid = (new UuidFactory())->createFromString('01977bea-d1c0-7154-87bb-6550974155c2');
// Parse a ULID.
$ulid = (new UlidFactory())->createFromString('01JXXYNME0E5A8FEV5A2BM2NE2');
// Parse a Snowflake ID.
$snowflake = (new GenericSnowflakeFactory(1, Epoch::Unix))->createFromInteger(7340580095540599922);
```
Each of these identifiers happen to contain the same timestamp, which we can retrieve:
```php
echo $uuid->getDateTime()->format('Y-m-d H:i:s.v P') . "\n";
echo $ulid->getDateTime()->format('Y-m-d H:i:s.v P') . "\n";
echo $snowflake->getDateTime()->format('Y-m-d H:i:s.v P') . "\n";
```
This will print:
```
2025-06-17 03:24:36.160 +00:00
2025-06-17 03:24:36.160 +00:00
2025-06-17 03:24:36.160 +00:00
```
The UUID and ULID shown above have the same underlying byte values. Every version 7 UUID can also be expressed as a
ULID, but not every ULID can be converted into a version 7 UUID. Similarly, Snowflake identifiers and ULIDs both encode
a timestamp and randomness, but their formats are not directly interchangeable with UUIDs or each other.
```php
if ($uuid->equals($ulid)) {
echo "They are equal!\n";
}
if ($uuid->equals($snowflake)) {
echo "The timestamp is the same, but they aren't equal.\n"
}
```
## Contributing
Contributions are welcome! To contribute, please familiarize yourself with [CONTRIBUTING.md](CONTRIBUTING.md).
## Coordinated Disclosure
Keeping user information safe and secure is a top priority, and we welcome the contribution of external security
researchers. If you believe you've found a security issue in software that is maintained in this repository, please read
[SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report.
## Copyright and License
ramsey/identifier is copyright © [Ben Ramsey](https://ramsey.dev) and [Contributors](https://github.com/ramsey/identifier/graphs/contributors)
and licensed for use under the terms of the GNU Lesser General Public License (LGPL-3.0-or-later) as published by the
Free Software Foundation. Please see [COPYING.LESSER](COPYING.LESSER), [COPYING](COPYING), and [NOTICE](NOTICE) for more
information.