PHPackages                             phpgears/identity - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. phpgears/identity

ActiveLibrary

phpgears/identity
=================

Identity object for PHP

0.2.4(5y ago)14962MITPHPPHP ^7.1CI failing

Since Sep 16Pushed 5y ago2 watchersCompare

[ Source](https://github.com/phpgears/identity)[ Packagist](https://packagist.org/packages/phpgears/identity)[ Docs](https://github.com/phpgears/identity)[ RSS](/packages/phpgears-identity/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (3)Dependencies (21)Versions (11)Used By (2)

[![PHP version](https://camo.githubusercontent.com/d0b5687c6812c5d52d86a548e09db527eeb7860f82adbb677de00a36ddbed1b4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344372e312d3838393242462e7376673f7374796c653d666c61742d737175617265)](http://php.net)[![Latest Version](https://camo.githubusercontent.com/b9aa1123266a39555f5bbf6908e6e275bc95af83bb647b57e6c4bf4547fa7431/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/phpgears/identity)[![License](https://camo.githubusercontent.com/6ee71628945d7fbbe316944aaba787faf7fdc4b91245058ff1686bdf571717f9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://github.com/phpgears/identity/blob/master/LICENSE)

[![Build Status](https://camo.githubusercontent.com/cd8dc6d205bd2ebd86723fd5e7c6cb5aa63b0843d515f11c645a84da9c749689/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f636f6d2f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.com/github/phpgears/identity)[![Style Check](https://camo.githubusercontent.com/b78ea68f8f01ef744e4a85113e02e85d2964fd3347e2e91a8a8451a1e5138e01/68747470733a2f2f7374796c6563692e696f2f7265706f732f3134393031353431372f736869656c64)](https://styleci.io/repos/149015417)[![Code Quality](https://camo.githubusercontent.com/563db55831eb57cee86b53c048ccbd427959acd013fd03d527ce9657ab4071c6/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/phpgears/identity)[![Code Coverage](https://camo.githubusercontent.com/4d332dff20ff7c392c3a8ba3ace8d4919144927233f371c3180e9257eb3e6b5a/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/github/phpgears/identity)

[![Total Downloads](https://camo.githubusercontent.com/95702b2661a2998bc4ac6587a781faa8157d425816883a67e3c8f5c4460c07a5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/phpgears/identity/stats)[![Monthly Downloads](https://camo.githubusercontent.com/b9144a5a9f3cb4346db91974a3649cc9f2e734ccc373b2e6e50a43c4da827d6e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f70687067656172732f6964656e746974792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/phpgears/identity/stats)

Identity
========

[](#identity)

Identity objects for PHP

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require phpgears/identity

```

Usage
-----

[](#usage)

Require composer autoload file

```
require './vendor/autoload.php';
```

By extending `Gears\Identity\AbstractIdentity` you can easily have an Identity class

```
use Gears\Identity\AbstractIdentity;

class CustomIdentity extends AbstractIdentity
{
    final public static function fromString(string $value)
    {
        // Check $value validity as an identity

        return new static($value);
    }
}
```

### Implementations

[](#implementations)

Due to its popularity UUID ([RFC 4122](http://tools.ietf.org/html/rfc4122)) based identity implementations are provided

##### UuidIdentity

[](#uuididentity)

```
use Gears\Identity\UuidIdentity;
use Gears\Identity\OrderedUuidIdentityGenerator;
use Gears\Identity\UuidIdentityGenerator;
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4()->toString();
$identity = UuidIdentity::fromString($uuid);

// From generator
$identity = (new UuidIdentityGenerator())->generate();
$identity = (new OrderedUuidIdentityGenerator())->generate();

// Get original UUID string
$originalUuid = $identity->getValue();
```

If you want a more concise UUID based identities you can use any of the following:

##### CondensedUuidIdentity

[](#condenseduuididentity)

UUID without dashes

```
use Gears\Identity\CondensedUuidIdentity;
use Gears\Identity\CondensedUuidIdentityGenerator;
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4()->toString();
$identity = CondensedUuidIdentity::fromString(\str_replace('-', '', $uuid));

$identity = CondensedUuidIdentity::fromUuid($uuid); // From UUID string
$identity = (new CondensedUuidIdentityGenerator())->generate(); // From generator

// Get original UUID string
$originalUuid = \sprintf('%s%s-%s-%s-%s-%s%s%s', ...\str_split($identity->getValue(), 4));
```

##### HashUuidIdentity

[](#hashuuididentity)

Require

```
composer require hashids/hashids

```

```
use Gears\Identity\HashUuidIdentity;
use Gears\Identity\HashUuidIdentityGenerator;
use Hashids\Hashids;
use Ramsey\Uuid\Uuid;

$hashIds = new Hashids();
$uuid = Uuid::uuid4()->toString();
$hashedUuid = $hashIds->encodeHex(\str_replace('-', '', $uuid));
$identity = HashUuidIdentity::fromString($hashedUuid);

$identity = HashUuidIdentity::fromUuid($uuid); // From UUID string
$identity = (new HashUuidIdentityGenerator())->generate(); // From generator

// Get original UUID string
$originalUuid = \sprintf('%s%s-%s-%s-%s-%s%s%s', ...\str_split($hashIds->decodeHex($identity->getValue()), 4));
```

##### ShortUuidIdentity

[](#shortuuididentity)

Require

```
composer require pascaldevink/shortuuid

```

```
use Gears\Identity\ShortUuidIdentity;
use Gears\Identity\ShortUuidIdentityGenerator;
use PascalDeVink\ShortUuid\ShortUuid;
use Ramsey\Uuid\Uuid;

$shortUuid = new ShortUuid();
$identity = ShortUuidIdentity::fromString($shortUuid->uuid4());

$identity = ShortUuidIdentity::fromUuid(Uuid::uuid4()->toString()); // From UUID string
$identity = (new ShortUuidIdentityGenerator())->generate(); // From generator

// Get original UUID string
$originalUuid = $shortUuid->decode($identity->getValue())->toString();
```

##### Base62UuidIdentity

[](#base62uuididentity)

Require

```
composer require tuupola/base62

```

```
use Gears\Identity\Base62UuidIdentity;
use Gears\Identity\Base62UuidIdentityGenerator;
use Ramsey\Uuid\Uuid;
use Tuupola\Base62;

$base62 = new Base62();
$uuid = Uuid::uuid4()->toString();
$base62Uuid = $base62->encode(\hex2bin(\str_replace('-', '', $uuid)));
$identity = Base62UuidIdentity::fromString($base62Uuid);

$identity = Base62UuidIdentity::fromUuid($uuid); // From UUID string
$identity = (new Base62UuidIdentityGenerator())->generate(); // From generator

// Get original UUID string
$originalUuid = \sprintf('%s%s-%s-%s-%s-%s%s%s', ...\str_split(\bin2hex($base62->decode($identity->getValue())), 4));
```

#### Non-UUID based identities

[](#non-uuid-based-identities)

[phpgears/identity-extra](https://github.com/phpgears/identity-extra) hosts non UUID based identity implementations, such as Mongo's ObjectId and several others, consider checking it depending on your use case

The Right Identity
------------------

[](#the-right-identity)

There is no point on creating non-unique identities, always use a proven method of ensuring the uniqueness of the identity value. This can basically be stated as: **DO NOT implement your own mechanism for creating unique identifiers, ever, period**

**It's highly discouraged to allow identities with *arbitrary* string values**, or values that cannot be checked against to certify correctness, that is the reason why a general open-value identity class will never be provided in this package and **you should never implement such a thing**.

If you want to maximize interoperability with other systems on your architecture or others', such as message queues, webhooks, shared messages systems, etc, you most probably should go with plain ol' UUID identities as the format is widely accepted and has support in all mayor languages

If you have full control of your architecture and all the systems it shares data with you may consider using a more concise UUID identifier, or a non-UUID identifier which can have other benefits such as being more user/url friendly, being sortable, etc

Instead of randomly generated unique value, such as a UUID, you may be able to use real life unique identifiers that can be validated, such as IBAN for bank accounts or ISBN for publications. Strive for this kind of identifiers where possible

```
use Biblys\Isbn\Isbn;
use Gears\Identity\AbstractIdentity;
use Gears\Identity\Exception\InvalidIdentityException;

class ISBNIdentity extends AbstractIdentity
{
    final public static function fromString(string $value)
    {
        $isbn = new Isbn($value);
        if (!$isbn->isValid()) {
            throw new InvalidIdentityException(\sprintf('"%s" is not a valid ISBN', $value));
        }

        return new static($isbn->format('ISBN-13'));
    }
}
```

Contributing
------------

[](#contributing)

Found a bug or have a feature request? [Please open a new issue](https://github.com/phpgears/identity/issues). Have a look at existing issues before.

See file [CONTRIBUTING.md](https://github.com/phpgears/identity/blob/master/CONTRIBUTING.md)

License
-------

[](#license)

See file [LICENSE](https://github.com/phpgears/identity/blob/master/LICENSE) included with the source code for a copy of the license terms.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~88 days

Recently: every ~106 days

Total

10

Last Release

2002d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c50421f1ab4148354dc2dd5dcaba168656b17ea913b310d112deb39a6f73ca1?d=identicon)[juliangut](/maintainers/juliangut)

---

Top Contributors

[![juliangut](https://avatars.githubusercontent.com/u/1104131?v=4)](https://github.com/juliangut "juliangut (36 commits)")

---

Tags

identityimmutable

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/phpgears-identity/health.svg)

```
[![Health](https://phpackages.com/badges/phpgears-identity/health.svg)](https://phpackages.com/packages/phpgears-identity)
```

###  Alternatives

[league/oauth2-client

OAuth 2.0 Client Library

3.8k118.6M1.2k](/packages/league-oauth2-client)[league/oauth1-client

OAuth 1.0 Client Library

99698.8M106](/packages/league-oauth1-client)[onelogin/php-saml

PHP SAML Toolkit

1.3k44.0M107](/packages/onelogin-php-saml)[aeon-php/calendar

PHP type safe, immutable calendar library

2079.7M16](/packages/aeon-php-calendar)[darsyn/ip

An immutable IP Address value object that provides several different notations, including helper functions.

2572.0M20](/packages/darsyn-ip)[telesign/telesign

TeleSign SDK

162.1M2](/packages/telesign-telesign)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)