PHPackages                             rossbearman/eloquent-calamari - 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. [Database & ORM](/categories/database)
4. /
5. rossbearman/eloquent-calamari

ActiveLibrary[Database & ORM](/categories/database)

rossbearman/eloquent-calamari
=============================

Obfuscate incrementing IDs with Sqids for Laravel and Eloquent.

v2.0.0(1mo ago)46.7k↓50%2MITPHPPHP ^8.2CI passing

Since Feb 15Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/rossbearman/eloquent-calamari)[ Packagist](https://packagist.org/packages/rossbearman/eloquent-calamari)[ Docs](https://github.com/rossbearman/eloquent-calamari)[ RSS](/packages/rossbearman-eloquent-calamari/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (18)Versions (9)Used By (0)

Eloquent Calamari - Sqids for Laravel Models
============================================

[](#eloquent-calamari---sqids-for-laravel-models)

[![Latest Stable Version](https://camo.githubusercontent.com/dab056e38571045c695a50804a3c4597eeda2daa480f5f0e5e404812ceafe68b/68747470733a2f2f706f7365722e707567782e6f72672f726f7373626561726d616e2f656c6f7175656e742d63616c616d6172692f762f737461626c653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rossbearman/eloquent-calamari)[![Test Status](https://camo.githubusercontent.com/35fc58a299a56009b355c726a5e1a3643f94394d3c0398a35feb8c05a9fca61d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f7373626561726d616e2f656c6f7175656e742d63616c616d6172692f706870756e69742e796d6c3f6c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/rossbearman/eloquent-calamari/actions/workflows/phpunit.yml?query=branch:main)[![Analysis Status](https://camo.githubusercontent.com/2f04a1a4d9c263679a68c3762e16bbeed9cdc4d59a928f7224227781b2f6c70f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f7373626561726d616e2f656c6f7175656e742d63616c616d6172692f7068707374616e2e796d6c3f6c6162656c3d616e616c79736973267374796c653d666c61742d737175617265)](https://github.com/rossbearman/eloquent-calamari/actions/workflows/phpstan.yml?query=branch:main)[![MIT Licensed](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/rossbearman/eloquent-calamari/blob/main/LICENSE.md)

Eloquent Calamari integrates the [Sqids](https://sqids.org/php)[1](#user-content-fn-1-fc9bba8ac889f61e5de749e78af315a8) algorithm into Laravel and Eloquent, enabling you to seamlessly use obfuscated, unique IDs in place of your internal auto-incrementing IDs.

- Obfuscate auto-incrementing IDs with short, unique identifiers
- Unique Sqids across models, ID 1 will be represented differently on every model
- Optional route model binding with `SqidBasedRouting`
- Transparently handle non-canonical IDs

`example.com/link/2fC37YMkO` === `Link::find(1)`

`example.com/video/TaRfL1RAK` === `Video::find(1)`

Getting Started
---------------

[](#getting-started)

Require this package with [Composer](https://getcomposer.org/).

`composer require rossbearman/eloquent-calamari`

Add the `HasSqid` and `SqidBasedRouting` traits to your models.

```
use RossBearman\Sqids\HasSqid;
use RossBearman\Sqids\SqidBasedRouting;

class Customer extends Model
{
    use HasSqid, SqidBasedRouting;
}
```

Create a route for your model.

```
Route::get('/customer/{customer}', fn (Customer $customer) => $customer);
```

```
$customer = Customer::create(['name' => 'Squidward']);

$customer->id; // 1
$customer->sqid; // 3irWXI2rFV
```

`example.com/customer/3irWXI2rFV` now returns the Customer details.

### Querying

[](#querying)

Common query methods are also available.

```
Customer::findBySqid($sqid);

Customer::findBySqidOrFail($sqid);

Customer::whereSqid($sqid)->get();

Customer::whereSqidIn($sqids)->get();

Customer::whereSqidNotIn($sqids)->get();
```

### Representation

[](#representation)

By default the Sqid is not included in the model's `toArray()` or `toJson()` output and the ID is not hidden from these. You can use Eloquent's `appends` and `hidden` properties to achieve this.

```
class Customer extends Model
{
    use HasSqid, SqidBasedRouting;

    protected $appends = ['sqid'];
    protected $hidden = ['id'];
}
```

### Custom Routing

[](#custom-routing)

You can take advantage of `SqidBasedRouting` while still having a different default binding by overriding the model's `getRouteKeyName()` method.

```
class Customer extends Model
{
    use HasSqid, SqidBasedRouting;

    public function getRouteKeyName(): string
    {
        return 'id';
    }
}
```

```
// Routes by ID by default
Route::get('/admin/customer/{customer}', fn (Customer $customer) => $customer);

// Routes by Sqid when specified
Route::get('/customer/{customer:sqid}', fn (Customer $customer) => $customer);
```

Configuration
-------------

[](#configuration)

By default, Eloquent Calamari generates a random [alphabet](https://sqids.org/faq#unique) for each model, by shuffling the default alphabet with the [Xoshiro256StarStar](https://www.php.net/manual/en/class.random-engine-xoshiro256starstar.php) algorithm, seeded with a combination of the name of the model and the key set in the config.

This ensures that entities of different models with the same ID will have a unique Sqid, however it is fragile to the model name or app key being changed. If either of these are changed, Sqids will no longer resolve back to the same ID.

Important

**It is highly recommended** that you explicitly set a pre-shuffled alphabet for each model using the `sqids.alphabets` config key, which will disable the shuffling behaviour for that model.

### Setting alphabets

[](#setting-alphabets)

Start by publishing the `sqids.php` config file to your `config` directory.

```
php artisan vendor:publish --provider="RossBearman\Sqids\SqidsServiceProvider"
```

Then generate a new alphabet for your model.

```
php artisan sqids:alphabet "App\Models\Customer"
```

You can also generate alphabets for multiple models at once.

```
php artisan sqids:alphabet "App\Models\Customer" "App\Models\Order" "App\Models\Invoice"
```

Follow the instructions provided by the command to add the new keys to your `config/sqids.php` and `.env` files.

### Confirm alphabet is being used

[](#confirm-alphabet-is-being-used)

To ensure that Eloquent Calamari is using the expected alphabet for a specific model, use the following command.

```
php artisan sqids:check
```

This will list all the models that have successfully been registered in the config and whether the class string can be resolved to a class in your application.

### Setting minimum Sqid lengths

[](#setting-minimum-sqid-lengths)

By default, all Sqids will be a minimum of 10 characters. You can adjust this for each model by assigning different values (to a minimum of 3) to the `sqids.min_lengths` config array.

```
    'min_lengths' => [
        App\Model\Customer::class => 20,
        App\Model\Order::class => 8,
        App\Model\Invoice::class => 30,
    ],
```

The maximum length of a Sqid is dependent on the input ID and the alphabet used. A more varied alphabet (upper and lower case letters, numbers and symbols) will result in shorter Sqids.

### Canonical Sqids

[](#canonical-sqids)

By design, [multiple Sqids can resolve to the same number](https://sqids.org/faq#collisions), however Eloquent Calamari will always return the same Sqid for a given number. Furthermore, this is the only Sqid that can be used to access an entity, and any other Sqid that would normally resolve to the same number will be rejected.

This check can be disabled on a per-model basis by adding an entry to the `sqids.canonical_checks` config array.

```
    'canonical_checks' => [
        App\Model\Customer::class => false,
    ],
```

Development
-----------

[](#development)

PHPUnit tests:

```
composer test
```

PHPStan analysis:

```
composer analyse
```

Pint linting:

```
composer lint
```

Security
--------

[](#security)

Please email Ross Bearman  if you have discovered a vulnerability in this package.

License
-------

[](#license)

MIT License (MIT). Please see [LICENSE.md](LICENSE.md) for more information.

Footnotes
---------

1. Sqids is the latest version of the Hashids algorithm, redesigned to accomodate custom blocklists and a better encoding scheme. [↩](#user-content-fnref-1-fc9bba8ac889f61e5de749e78af315a8)

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance89

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

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 ~110 days

Recently: every ~92 days

Total

8

Last Release

54d ago

Major Versions

v0.1.0 → v1.0.02024-02-15

v1.x-dev → v2.0.02026-03-25

### Community

Maintainers

![](https://www.gravatar.com/avatar/dc56eb4366311c8b5584d2356c0b6ac6f53af74fb8fbe4de9261b2124c63c678?d=identicon)[rossbearman](/maintainers/rossbearman)

---

Top Contributors

[![rossbearman](https://avatars.githubusercontent.com/u/212036?v=4)](https://github.com/rossbearman "rossbearman (17 commits)")

---

Tags

laraveleloquenthashidssqids

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/rossbearman-eloquent-calamari/health.svg)

```
[![Health](https://phpackages.com/badges/rossbearman-eloquent-calamari/health.svg)](https://phpackages.com/packages/rossbearman-eloquent-calamari)
```

###  Alternatives

[cviebrock/eloquent-sluggable

Easy creation of slugs for your Eloquent models in Laravel

4.0k13.6M253](/packages/cviebrock-eloquent-sluggable)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[watson/validating

Eloquent model validating trait.

9723.3M47](/packages/watson-validating)[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[cviebrock/eloquent-taggable

Easy ability to tag your Eloquent models in Laravel.

567694.8k3](/packages/cviebrock-eloquent-taggable)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2121.2M13](/packages/reedware-laravel-relation-joins)

PHPackages © 2026

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