Download the PHP package steven-fox/laravel-sqids without Composer

Sqids for Laravel.

This package brings Sqids functionality, with the option of multiple named configurations (alphabet and minimum encoding length), to your Laravel application. It's a batteries-included wrapper for the PHP Sqids package.

Features

• Uses the PHP Sqids implementation under the hood, so features like custom alphabets, minimum encoded sqid lengths, and blocklists are available with this package.
• Permits multiple sqid configurations that can be referenced by name to use for decoding/encoding with a specific alphabet and minLength.
• Makes it easy to validate an encoded Sqid to ensure it's canonical (in other words, to ensure it is an original Sqid that was generated with your alphabet configuration) when decoding.
• Makes it easy to work with single integers for the common use case of encoding/decoding numeric database IDs.
• Makes it easy to extend the package's EncodedSqid & DecodedSqid objects so you can create dedicated Sqid classes for your custom configurations (meaning you can have a set of Sqids that are always used for a particular Model or other use case).

Here are some quick examples.

Installation

You can install the package via composer:

You can publish the config file with:

Once the config file has been published, it is recommended to set your custom sqid configurations. This package allows you to use one or more named sqid configurations simultaneously and define one of them as a default. For each sqid configuration, you may specify a custom alphabet (which can provide a sense of uniqueness to your encoded sqids) and a minimum sqid length.

Usage

Prerequisite: Review the Sqids documentation

Although this package is easy to use, it's recommended to review the Sqids documentation to understand the underlying functionality. There are a number of good use cases for Sqids, but there are also many where they should not be used (for example, as encryption or to encode sensitive numbers).

Consider using the playground to get a feel for the encoded Sqids created by different alphabet + minLength combinations.

The Intended Pattern

It's intended to primarily use extensions of the EncodedSqid and DecodedSqid classes in your application. For example:

• You create a DecodedSqid using the numeric id of a model and then you encode() that, ultimately providing a string you can use somewhere (like in a url).
• When your app handles something that involves a Sqid string (like a request url), you create an EncodedSqid instance using the provided Sqid string and then you decode(), ultimately yielding the numeric model id you need to fetch from the database.

If you plan on using multiple Sqid configurations (for example, one configuration per model), then you will likely want to create your own Encoded/Decoded Sqid classes - one for each configuration - that extend the EncodedSqid and DecodedSqid classes provided by this package. By doing this, you can instantiate your objects with the correct Sqid configuration "baked in", meaning you will not have to call the $encodedSqid->usingConfigName('user-model')->... method everywhere.

Here's a simple example:

With that in place, you can now instantiate your UserDecodedSqid and the 'user' configuration will be used automatically. Once you perform an encode() operation, the resulting object will be an instance of your UserEncodedSqid, which will also reference the 'user' configuration automatically.

Making a custom EncodedSqid is essentially the same process.

Using EncodedSqids

Using the DecodedSqid

Using the Sqidder

In this package, the Sqidder (pronounced squid-er) is a Sqids implementation class that can perform encoding and decoding based on a Sqid configuration. At its core, it is a wrapper for the SqidsInterface implementation. Thus, it provides the encode() and decode() interface methods, along with an additional method from the ConfigBasedSqidder contract (original to this package) that permit selection of a specific coder for a particular Sqid configuration.

The EncodedSqid and DecodedSqid classes use the Sqidder internally and that is meant to be the primary interaction. However, it is also possible to use the Sqidder directly and a Facade is provided for easy access.

Canonical Sqids

The Sqidder does not perform Sqid validation when decoding to check if the encoded string is canonical. The EncodedSqid, however, does provide a validation option and is enabled by default when decoding.

Due to the Sqids algorithm, multiple encoded strings may decode to the same number(s). Thus, a canonical Sqid is one that originally came from your alphabet configuration. You can check if an encoded Sqid is canonical by decoding it into its number(s) and then re-encoding those numbers. If the original Sqid and the re-encoded Sqid are identical, then the original is canonical.

For example, using a standard alphabet, the encoded string 'Ul' will decode to the number [41]. However, re-encoding the number [41] produces a Sqid of 'qp'. Thus, the original Sqid of 'Ul' is not canonical and, in many circumstances, should be considered invalid.

Using Multiple Sqid Configurations

Testing

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Steven Fox

License

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