PHPackages                             glhd/special - 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. glhd/special

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

glhd/special
============

0.12.0(3mo ago)2033.9k↓64.3%1MITPHPPHP >= 8.2CI passing

Since Aug 11Pushed 3mo agoCompare

[ Source](https://github.com/glhd/special)[ Packagist](https://packagist.org/packages/glhd/special)[ RSS](/packages/glhd-special/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (10)Dependencies (12)Versions (19)Used By (0)

 [ ![Build Status](https://github.com/glhd/special/workflows/PHPUnit/badge.svg) ](https://github.com/glhd/special/actions) [ ![Latest Stable Release](https://camo.githubusercontent.com/20cf34e7b6314ccf9507d25af1a3c44d696687267162eb9525d7d949211c5374/68747470733a2f2f706f7365722e707567782e6f72672f676c68642f7370656369616c2f762f737461626c65) ](https://packagist.org/packages/glhd/special) [ ![MIT Licensed](https://camo.githubusercontent.com/43294ed8087559bba09b7f5a0c0c559be907793848bfba24f3f5fda58e4f4bf0/68747470733a2f2f706f7365722e707567782e6f72672f676c68642f7370656369616c2f6c6963656e7365) ](./LICENSE) [ ![Follow @cmorrell.com on bsky](https://camo.githubusercontent.com/8790699596340eff27762850c822f5e8e08a379e860085e46bf69359e4d2bc18/68747470733a2f2f696d672e736869656c64732e696f2f626c7565736b792f666f6c6c6f776572732f636d6f7272656c6c2e636f6d) ](https://bsky.app/profile/cmorrell.com)

Special✨
========

[](#special)

Sometimes, certain database records are just **special✨**, and you need to reference them inside your code.

You might have a few special vendors that have special handling in a few special places, and maybe their own special artisan commands run from time-to-time.

special✨ lets you use [backed enums](https://www.php.net/manual/en/language.enumerations.backed.php)to reference Eloquent models. Rather than backing your enum with a string or integer, think of it as backing your enum with a database record.

If the record is missing, you can let special✨ automatically create it for you. This is especially great in testing, where you may have a few special records that need to exist for a few special tests, but you don't want to track which tests need to run special seeders at setup.

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

[](#installation)

```
composer require glhd/special
```

Usage
-----

[](#usage)

To start, create a new enum and use the `EloquentBacking` trait provided by this package.

You can **optionally** add a `CreateWith` attribute to any of your enum cases, and special✨ will use those values to automatically create the model record for you if it's missing.

```
use Glhd\Special\EloquentBacking;

enum SpecialOrganizations: string
{
	use EloquentBacking;

	#[CreateWith(['name' => 'Laravel', 'url' => 'https://laravel.com/'])]
	case Laravel = 'laravel';

	#[CreateWith(['name' => 'Spatie', 'url' => 'https://spatie.be/'])]
	case Spatie = 'spatie';

	#[CreateWith(['name' => 'Thunk', 'url' => 'http://thunk.dev/'])]
	case Thunk = 'kathunk';

	// If your enum name is the same as the model name, this is optional.
	public static function modelClass(): string
	{
		return Organization::class;
	}
}
```

Now, you can use those enums to access the backing models. By default, strings are assumed to be a `slug` column, and integers are assumed to be the `id` column, but this can be configured at the project level or the individual enum level.

```
SpecialOrganizations::Laravel->toArray();

// [
//   'id' => 1337,
//   'slug' => 'laravel',
//   'name' => 'Laravel',
//   'url' => 'https://laravel.com/',
//   'created_at' => [...],
//   'updated_at' => [...],
// ]
```

Special enums decorate the underlying model, so you can often just call the enum as though it were the model itself. But sometimes you want the actual copy of the model instance, which you can do with:

```
// Get a copy of the model — only loads from DB once, but clones each time
SpecialOrganizations::Laravel->get();

// Get a single, shared copy — same instance each time
SpecialOrganizations::Laravel->singleton();

// Get a fresh copy — always loads from the DB
SpecialOrganizations::Laravel->fresh();
```

Using the primary key cache
---------------------------

[](#using-the-primary-key-cache)

Often, the only reason you need a special enum is to use its primary key in another query or to set up a relationship. Special✨ keeps a cache of the 50 most recently-used primary keys so that in many cases, you don't have to do a single database lookup. You can configure the number of keys cached and the cache TTL by publishing the package config.

```
PullRequest::create([
    'organization_id' => SpecialOrganizations::Laravel->getKey(),
    'ref_number' => 47785,
    'title' => '[10.x] Add Collection::enforce() method',
]);
```

As long as `SpecialOrganizations::Laravel` has been used in the last hour, the `'organization_id'` value can be set without making a single query to the database.

Due to the nature of these kinds of enums, this is usually pretty safe, since they're used with the types of records that aren't likely to change in your application ever. That said, you can always clear the cache at any time with `php artisan cache:clear-special-keys`.

Using with Laravel relations
----------------------------

[](#using-with-laravel-relations)

Often times you want to use a special enum to look up related models. We provide a few convenient ways to do this:

```
PullRequests::query()
  ->forSpecial(SpecialOrganizations::Laravel)
  ->dumpRawSql();

// select *
// from `pull_requests`
// where `organization_id` = 1337
```

Or, you can use a special enum to constrain an existing query. The exact same query can be generated with:

```
SpecialOrganizations::Laravel
  ->constrain(PullRequests::query())
  ->dumpRawSql();
```

The `constrain()` method (and `forSpecial` macro) both use the primary key cache under the hood. This means that most relational queries using special enums will not trigger any additional database queries.

Automatic Model Observation
---------------------------

[](#automatic-model-observation)

Special✨ automatically registers model observers for any model that you retrieve. This means that if you update or delete a special model during a request, subsequent calls to the enum will automatically reflect those changes.

This works regardless of whether the updated model was retrieved using the package.

```
// Get a copy of the Laravel organization, which causes it to be
// cached for the rest of the request.
$laravel = SpecialOrganizations::Laravel->singleton();
assert($laravel->name === 'Laravel');

// Now we'll update it without using our enum
$org = Organizations::where('slug', 'laravel')->first();
$org->update(['name' => 'Laravel LLC']);

// Later calls to the enum will reflect the changes
$laravel = SpecialOrganizations::Laravel->singleton();
assert($laravel->name === 'Laravel LLC');
```

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance81

Actively maintained with recent releases

Popularity37

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.7% 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 ~68 days

Recently: every ~185 days

Total

15

Last Release

102d ago

PHP version history (2 changes)0.1.0PHP >= 8.1

0.10.0PHP >= 8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/21592?v=4)[Chris Morrell](/maintainers/inxilpro)[@inxilpro](https://github.com/inxilpro)

---

Top Contributors

[![inxilpro](https://avatars.githubusercontent.com/u/21592?v=4)](https://github.com/inxilpro "inxilpro (76 commits)")[![onairmarc](https://avatars.githubusercontent.com/u/50760632?v=4)](https://github.com/onairmarc "onairmarc (1 commits)")

---

Tags

laravel

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/glhd-special/health.svg)

```
[![Health](https://phpackages.com/badges/glhd-special/health.svg)](https://phpackages.com/packages/glhd-special)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M193](/packages/laravel-ai)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)[api-platform/laravel

API Platform support for Laravel

58171.5k14](/packages/api-platform-laravel)[wearepixel/laravel-cart

A cart implementation for Laravel

1374.8k](/packages/wearepixel-laravel-cart)

PHPackages © 2026

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