Download the PHP package tonysm/globalid-laravel without Composer

Introduction

Identify app models with a URI.

A Global ID is an app wide URI that uniquely identifies a model instance:

This is helpful when you need a single identifier to reference different classes of objects.

One example is storing model references in places where you cannot enforce constraints or cannot make use of the convenient Eloquent relationships, such as storing model references in a rich text content field. We need to reference a model object rather than serialize the object itself. We can pass a Global ID that can be used to locate the model when it's time to render the rich text content. The rendering doesn't need to know the details of model naming and IDs, just that it has a global identifier that references a model.

Another example is a drop-down list of options, consisting of both Users and Groups. Normally we'd need to come up with our own ad hoc scheme to reference them. With Global IDs, we have a universal identifier that works for objects of both classes.

Inspiration

Heavily inspired by the globalid gem.

Installation

Via Composer:

Usage

Add the HasGlobalIdentification trait to any Eloquent model (or any class with a find($id), findMany($ids): Collection static methods, and a getKey() instance method):

Then you can create GlobalIds and SignedGlobalIds like so:

You may customize the location logic using a custom locator.

Signed Global IDs

For added security GlobalIDs can also be signed to ensure that the data hasn't been tampered with.

Expiration

Signed Global IDs can expire some time in the future. This is useful if there's a resource people shouldn't have indefinite access to, like a share link.

An auto-expiry of 1 month is set by default. You can override this default by passing a expiration resolver Closure from any Service Provider boot method. This resolver will get called every time a SGID is created:

This way any generated SGID will use that relative expiry.

It's worth noting that expiring SGIDs are not idempotent because they encode the current timestamp; repeated calls to to_sgid will produce different results. For example:

You need to explicitly pass ['expires_at' => null] to generate a permanent SGID that will not expire,

Purpose

You can even bump the security up some more by explaining what purpose a Signed Global ID is for. In this way evildoers can't reuse a sign-up form's SGID on the login page. For example:

Locating many Global IDs

When needing to locate many Global IDs use Tonysm\GlobalId\Facades\Locator->locateMany or Tonysm\GlobalId\Facades\Locator::locateManySigned() for Signed Global IDs to allow loading Global IDs more efficiently.

For instance, the default locator passes every $modelId per $modelName thus using $modelName::findMany($ids) versus Tonysm\GlobalId\Facades\Locator->locate()'s $modelName::find($id).

In the case of looking up Global IDs from a database, it's only necessary to query once per $modelName as shown here:

Note the order is maintained in the returned results.

Custom App Locator

A custom locator can be set for an app by calling Tonysm\GlobalId\Locator::use() and providing an app locator to use for that app. A custom app locator is useful when different apps collaborate and reference each others' Global IDs. When finding a Global ID's model, the locator to use is based on the app name provided in the Global ID url.

Using a custom Locator:

After defining locators as above, URIs like gid://foo/Person/1 will now use that locator. Other apps will still keep using the default locator.

Custom Polymorphic Types

When using the Custom Polymorphic Types feature from Eloquent, the model name inside the GID URI will use your alias instead of the model's FQCN.

Testing the Package

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

You're encouraged to submit pull requests, propose features and discuss issues.

Security Vulnerabilities

Drop me an email at [email protected] if you want to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.

Credits

• Tony Messias
• All Contributors