Identity

Identity objects for PHP

Installation

Composer

composer require phpgears/identity

Usage

Require composer autoload file

require'./vendor/autoload.php';

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

useGears\Identity\AbstractIdentity;
class CustomIdentity extends AbstractIdentity
{
finalpublicstaticfunctionfromString(string$value)
{
// Check $value validity as an identityreturnnewstatic($value);
}
}

Implementations

Due to its popularity UUID (RFC 4122) based identity implementations are provided

UuidIdentity

useGears\Identity\UuidIdentity;
useGears\Identity\OrderedUuidIdentityGenerator;
useGears\Identity\UuidIdentityGenerator;
useRamsey\Uuid\Uuid;
$uuid = Uuid::uuid4()->toString();
$identity = UuidIdentity::fromString($uuid);
// From generator$identity = (newUuidIdentityGenerator())->generate();
$identity = (newOrderedUuidIdentityGenerator())->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

UUID without dashes

useGears\Identity\CondensedUuidIdentity;
useGears\Identity\CondensedUuidIdentityGenerator;
useRamsey\Uuid\Uuid;
$uuid = Uuid::uuid4()->toString();
$identity = CondensedUuidIdentity::fromString(\str_replace('-', '', $uuid));
$identity = CondensedUuidIdentity::fromUuid($uuid); // From UUID string$identity = (newCondensedUuidIdentityGenerator())->generate(); // From generator// Get original UUID string$originalUuid = \sprintf('%s%s-%s-%s-%s-%s%s%s', ...\str_split($identity->getValue(), 4));

HashUuidIdentity

Require https://github.com/ivanakimov/hashids.php

composer require hashids/hashids

useGears\Identity\HashUuidIdentity;
useGears\Identity\HashUuidIdentityGenerator;
useHashids\Hashids;
useRamsey\Uuid\Uuid;
$hashIds = newHashids();
$uuid = Uuid::uuid4()->toString();
$hashedUuid = $hashIds->encodeHex(\str_replace('-', '', $uuid));
$identity = HashUuidIdentity::fromString($hashedUuid);
$identity = HashUuidIdentity::fromUuid($uuid); // From UUID string$identity = (newHashUuidIdentityGenerator())->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

Require https://github.com/pascaldevink/shortuuid

composer require pascaldevink/shortuuid

useGears\Identity\ShortUuidIdentity;
useGears\Identity\ShortUuidIdentityGenerator;
usePascalDeVink\ShortUuid\ShortUuid;
useRamsey\Uuid\Uuid;
$shortUuid = newShortUuid();
$identity = ShortUuidIdentity::fromString($shortUuid->uuid4());
$identity = ShortUuidIdentity::fromUuid(Uuid::uuid4()->toString()); // From UUID string$identity = (newShortUuidIdentityGenerator())->generate(); // From generator// Get original UUID string$originalUuid = $shortUuid->decode($identity->getValue())->toString();

Base62UuidIdentity

Require https://github.com/tuupola/base62

composer require tuupola/base62

useGears\Identity\Base62UuidIdentity;
useGears\Identity\Base62UuidIdentityGenerator;
useRamsey\Uuid\Uuid;
useTuupola\Base62;
$base62 = newBase62();
$uuid = Uuid::uuid4()->toString();
$base62Uuid = $base62->encode(\hex2bin(\str_replace('-', '', $uuid)));
$identity = Base62UuidIdentity::fromString($base62Uuid);
$identity = Base62UuidIdentity::fromUuid($uuid); // From UUID string$identity = (newBase62UuidIdentityGenerator())->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

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

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

useBiblys\Isbn\Isbn;
useGears\Identity\AbstractIdentity;
useGears\Identity\Exception\InvalidIdentityException;
class ISBNIdentity extends AbstractIdentity
{
finalpublicstaticfunctionfromString(string$value)
{
$isbn = newIsbn($value);
if (!$isbn->isValid()) {
thrownewInvalidIdentityException(\sprintf('"%s" is not a valid ISBN', $value));
}
returnnewstatic($isbn->format('ISBN-13'));
}
}

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file CONTRIBUTING.md

License

See file LICENSE included with the source code for a copy of the license terms.