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(1mo ago)1929.4k↓16.2%1MITPHPPHP >= 8.2CI failing

Since Aug 11Pushed 8mo agoCompare

[ Source](https://github.com/glhd/special)[ Packagist](https://packagist.org/packages/glhd/special)[ RSS](/packages/glhd-special/feed)WikiDiscussions main Synced 1mo 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) [ ![Coverage Status](https://camo.githubusercontent.com/32ed212766c4b8931b090de20740a03e0d3b47ee2a30e99d82eefdb3c981a4bd/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f31373336343837316237363137643239383936652f746573745f636f766572616765) ](https://codeclimate.com/github/glhd/special/test_coverage) [ ![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 @inxilpro on Twitter](https://camo.githubusercontent.com/e6d0a3893c652423c3a7c6aa648ca6e98a3b06899551e17a2fe5b33528244dcb/68747470733a2f2f696d672e736869656c64732e696f2f747769747465722f666f6c6c6f772f696e78696c70726f3f7374796c653d736f6369616c) ](https://twitter.com/inxilpro)

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

47

—

FairBetter than 94% of packages

Maintenance73

Regular maintenance activity

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

56d 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

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[kyslik/column-sortable

Package for handling column sorting in Laravel 6.x

6485.6M21](/packages/kyslik-column-sortable)[laracraft-tech/laravel-useful-additions

A collection of useful Laravel additions!

58109.4k](/packages/laracraft-tech-laravel-useful-additions)[bjuppa/laravel-blog

Add blog functionality to your Laravel project

483.3k2](/packages/bjuppa-laravel-blog)

PHPackages © 2026

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