PHPackages                             hadi-aghandeh/laravel-friendly-id - 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. [Utility & Helpers](/categories/utility)
4. /
5. hadi-aghandeh/laravel-friendly-id

ActiveLibrary[Utility & Helpers](/categories/utility)

hadi-aghandeh/laravel-friendly-id
=================================

map integer id to a friendly string

0.1.5(1y ago)1584[3 issues](https://github.com/HadiAghandeh/laravel-friendly-id/issues)MITPHPPHP ^8.0

Since Oct 6Pushed 1y ago1 watchersCompare

[ Source](https://github.com/HadiAghandeh/laravel-friendly-id)[ Packagist](https://packagist.org/packages/hadi-aghandeh/laravel-friendly-id)[ RSS](/packages/hadi-aghandeh-laravel-friendly-id/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (4)Versions (7)Used By (0)

Laravel Friendly ID - Laravel String ID
=======================================

[](#laravel-friendly-id---laravel-string-id)

[![](https://camo.githubusercontent.com/aef1b5ed2bb9c65a348f0a0d68c8b1634265286a41d0fe89f5a266c8a448dc00/68747470733a2f2f7669736974636f756e742e69747376672e696e2f6170693f69643d686164692d616768616e6465682d6c61726176656c2d667269656e646c792d6964266c6162656c3d566965777326636f6c6f723d31322669636f6e3d31267072657474793d74727565)](https://visitcount.itsvg.in)[![Laravel Friendly ID - Laravel String ID](image.jpg)](image.jpg)

**Looking to convert the integer primary ID of your laravel model to an user friendly string?**

This package enables you to generate string-based IDs for your models, without the need for a separate ID column. By default, Laravel uses integer IDs with MySQL, but in many cases, you may need unique string identifiers for your models. This package helps you implement these unique string IDs seamlessly.

**1335684976 -> encode -> xxx-xxxx-xxx -> decode -> 1335684976**

Here are some potential uses for having a string representation of IDs:
-----------------------------------------------------------------------

[](#here-are-some-potential-uses-for-having-a-string-representation-of-ids)

- **URL Creation**: A string representation of integer IDs can enhance your application's readability by masking real IDs and improving clarity, especially in URLs. Such as Google Meet style urls
- **Model Tracking**: You can use string IDs instead of integers for better user experience.
- **Reference Codes**: For customer-facing references, like invoices or orders, string IDs are more user-friendly than raw numbers.
- **API Responses**: String-based IDs can make API data less predictable and easier to manage across different systems.
- **Cross-System Compatibility**: Some external systems may require a string format for identifiers, and strings can offer better flexibility for integration.

Laravel Friendly ID is easy to use:
-----------------------------------

[](#laravel-friendly-id-is-easy-to-use)

```
// use the trait
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use HadiAghandeh\FriendlyId\Traits\FriendlyId;

class Post extends Model
{
    use FriendlyId;
}

// get encoded id
$post = Post::find(1);
$friendlyId = $post->friendly_id // = xxx-xxxx-xxx

// find the model
$post = Post::whereFriendlyId($friendlyId);
```

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

[](#installation)

Install the package via Composer:

```
composer require hadi-aghandeh/laravel-friendly-id
```

### Configuration

[](#configuration)

After installing the package, publish the configuration file:

```
php artisan vendor:publish --tag="friendly-id"
```

This will create a `config/friendly-id.php` file where you can customize the encoding settings.

### Default Configuration

[](#default-configuration)

```
return [
 /*
     |--------------------------------------------------------------------------
     | Alphabets
     |--------------------------------------------------------------------------
     |
     | provide a alphabet string it is best if you provide a string with randomized order
     |
     */
    'alphabet' => env('FRIENDLY_ID_ALPHABET', "abcdefghijklmnopqrstuvwxyz"),

    /*
     |--------------------------------------------------------------------------
     | Encoder Name
     |--------------------------------------------------------------------------
     |
     | available option BASEN, SQIDS and WORDS
     |
     */
    'encoder' => env('FRIENDLY_ID_ENCODER', 'SQIDS'),

    /*
     |--------------------------------------------------------------------------
     | Minimum length
     |--------------------------------------------------------------------------
     |
     | This option controls the minimum length of the encoded string
     |
     */
    'length' => env('FRIENDLY_ID_LENGTH', 10),

    /*
     |--------------------------------------------------------------------------
     | Default column
     |--------------------------------------------------------------------------
     |
     | This option controls the default column that friendly id uses
     |
     */
    'column' => env('FRIENDLY_ID_COLUMN', 'id'),
];
```

- `alphabet`: The set of characters used to encode the ID. By default, it uses `"abcdefghijklmnopqrstu"`. You can modify it via environment variables.
- `encoder`: The encoder algorithm used to create friendly IDs. The default encoder is `"SQIDS"`. You can change this through the `FRIENDLY_ID_ENCODER` environment variable. available encoders are `BASEN` and `SQIDS`

Encoders
--------

[](#encoders)

### BASEN

[](#basen)

This changes the base of the integer to letters provided by FRIENDLY\_ID\_ALPHABET.

Example output with a length of 7:

```
124 -> ctt-rctz
125 -> ctt-rcty
50000 -> ctt-tyrj
50001 -> ctt-tyri
50002 -> ctt-tyrh
100000 -> ctt-pfwd
100001 -> ctt-pfwc
100002 -> ctt-pfwb
1000000 -> ctv-oodv
1000000000 -> ndh-nmh
1000000001 -> ndh-nmg

```

### SQIDS

[](#sqids)

This uses the well-known Sqids algorithm with its PHP package.

Example output with a length of 10:

```
100002 -> esz-xmrs-alo
1000000 -> msw-pppt-ozp
1000000000 -> uyr-vkkk-kgq
1000000001 -> gmx-qeee-rkr
1000000002 -> mqs-dppp-sto
1256541245 -> vdb-ryev-tqc
1000000000000 -> mzj-rppp-ppp
12545656455156 -> etv-cbxc-lts-s

```

### WORDS

[](#words)

Sometimes, you may prefer your string to be a mix of words. These strings are easier to remember due to their use of vowels.

```
50001 -> hem-ho
50002 -> nap-pan
100000 -> rich-feet
100001 -> land-sum
100002 -> like-big
1000000 -> wine-safe-farm

```

Usage
-----

[](#usage)

To start using friendly IDs in your Laravel models, simply use the `FriendlyId` trait in your model class.

### Example

[](#example)

#### Add Trait to a Model

[](#add-trait-to-a-model)

```
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use HadiAghandeh\FriendlyId\Traits\FriendlyId;

class Post extends Model
{
    use FriendlyId;
}
```

#### Encode and Decode Friendly IDs

[](#encode-and-decode-friendly-ids)

You can now use the `encodeFriendlyId` method to generate a friendly string representation of the model's ID:

```
$post = Post::find(1);
$friendlyId = $post->encodeFriendlyId();

echo $friendlyId; // e.g., "abc-def-ghi"
```

To decode a friendly ID back to the original integer ID, use the `decodeFriendlyId` method:

```
$decodedId = Post::decodeFriendlyId('abc-def-ghi');
echo $decodedId; // e.g., 1
```

#### Query by Friendly ID

[](#query-by-friendly-id)

You can use the `whereFriendlyId` scope to query a model by its friendly ID:

```
$post = Post::whereFriendlyId('abc-def-ghi')->first();
```

### Configuration Customization

[](#configuration-customization)

To customize the encoding behavior, you can update your `.env` file with the following environment variables:

```
FRIENDLY_ID_ALPHABET=yourcustomalphabet
FRIENDLY_ID_ENCODER=yourencoder
```

- `FRIENDLY_ID_ALPHABET`: Defines the custom alphabet used to generate friendly IDs.
- `FRIENDLY_ID_ENCODER`: Defines the encoding mechanism to use. Currently, the default is `"SQIDS"`.

### Exception Handling

[](#exception-handling)

The `decodeFriendlyId` method will return `null` if the provided friendly ID is invalid or cannot be decoded.

```
$invalidId = Post::decodeFriendlyId('invalid-id'); // returns null
```

Testing
-------

[](#testing)

You can run tests for this package using PHPUnit:

```
vendor/bin/phpunit
```

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

Support
=======

[](#support)

If this package helps you, please consider giving it a ⭐ on GitHub! Your support means a lot and helps to maintain this project.

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

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

Total

6

Last Release

580d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0cf0eb705be83687b56c9fb1284b298815d86025fe6f87c048aae9e45a7302f2?d=identicon)[aghandeh](/maintainers/aghandeh)

---

Top Contributors

[![HadiAghandeh](https://avatars.githubusercontent.com/u/28506997?v=4)](https://github.com/HadiAghandeh "HadiAghandeh (9 commits)")

---

Tags

encodingfriendlyidlaravelreadableurl

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hadi-aghandeh-laravel-friendly-id/health.svg)

```
[![Health](https://phpackages.com/badges/hadi-aghandeh-laravel-friendly-id/health.svg)](https://phpackages.com/packages/hadi-aghandeh-laravel-friendly-id)
```

###  Alternatives

[red-explosion/laravel-sqids

Easily generate Stripe/YouTube looking IDs for your Laravel models.

4530.8k](/packages/red-explosion-laravel-sqids)[guava/sqids-for-laravel

This is a laravel wrapper for sqids.

142.4k](/packages/guava-sqids-for-laravel)

PHPackages © 2026

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