Download the PHP package bensondevs/supercharged-enums without Composer

⚡ Supercharged Enums

Backed enum helpers (find, options, comparisons, labels) via the EnumExtension trait—no framework dependencies. The package also ships optional ready-made enums for everyday domains (HTTP, calendar and time, measurement units, finance, logging, deployment environments, and more) under BensonDevs\SuperchargedEnums\Common\, each wired with the same helpers. See Bundled Common enums.

Requirements: PHP 8.2 or later. The EnumExtension trait targets backed enums (string or int). Pure unit enums without a backing type are not supported by lookup normalization.

Table of contents

• Installation
  • Laravel Boost
  • Laravel Artisan stubs
• Quick start
• Features
  • Core helpers
  • Lookup
  • Case listing
  • Naming
  • Select maps
  • Comparisons and ordering
• Modular composition
• Bundled Common enums
• Development
• Support
• License

Installation

Laravel Boost

This package ships Laravel Boost AI resources for coding agents:

• Skill (supercharged-enums-development) — on-demand patterns for EnumExtension, lookup, select maps, comparisons, and bundled Common\ enums
• Guidelines — always-loaded overview and conventions

Boost discovers these automatically from resources/boost/ in the installed package. No ServiceProvider or extra configuration is required in this library.

In a Laravel project that uses Boost:

Boost integration is opt-in on the consumer side. The package remains framework-agnostic.

Laravel Artisan stubs

For Laravel projects, you can publish a customized enum.backed.stub so php artisan make:enum generates backed enums with EnumExtension already applied.

Enable (one-time, manual):

Generate enums as usual:

Example output:

Notes:

• Laravel-only and opt-in — publishing is required; non-Laravel projects are unaffected.
• Only backed enums (--string / --int) use this stub. Pure unit enums are unchanged.
• If your app already has stubs/enum.backed.stub (for example from php artisan stub:publish), use --force to overwrite — that replaces your existing customization.
• Stub publishing is separate from Laravel Boost; Boost skills and guidelines do not require publishing stubs.

Quick start

Add the trait to your own enum, or use a bundled one from Common\—same helpers either way.

Your enum

Lookup — request / DB strings → cases (null when unknown)

Labels and forms

Comparisons — declaration order, not backing-value sort

Bundled time units — DurationUnit with conversions and the same helpers

Bundled measurement units — Common\Measure

More domains (HTTP status codes, money rounding, data sizes) are listed under Bundled Common enums.

Features

Modular composition.

Core helpers

default() follows declaration order, not the smallest or largest backing value. For example, HttpStatusCode defaults to Continue (100) because it is declared first, even though other codes have smaller numeric semantics in different contexts.

There is no separate config flag: declare the case you want as the default first, or override default() on your enum to return any case you prefer. findOrDefault() and any code that falls back to default() will use whichever you define.

If you use a partial trait stack without EnumExtension, define default() yourself (for example return self::cases()[0];) so findOrDefault() keeps working.

Lookup

find() accepts:

• An enum instance (returned as-is)
• null (returns null)
• A backing value: string keys for string-backed enums; int keys for int-backed enums, with numeric strings coerced to int (e.g. '2' → 2)

When $strict is false and tryFrom() does not match, cases may define alternate keys via an instance method:

• Aliases are consulted only when $strict is false.
• With $strict true, resolution is limited to tryFrom() (backing values only).
• If the same alias appears on multiple cases, behavior is undefined; the first match in cases() iteration order wins.

Case listing

Naming

getName() normalizes case names for display: underscores and hyphens become spaces, PascalCase is split, and the result is title-cased (NoShow → "No show", FirstOption → "First option").

Select maps

Build value => label maps for HTML <select> elements, JSON APIs, and similar UIs.

Label resolution (options()), first match wins:

1. label() instance method
2. getLabel()
3. getName()
4. Raw PHP case name

Description resolution (asSelectDescriptions()):

1. getDescription()
2. getLabel()
3. Raw PHP case name

Filtering which cases appear in maps

Define either an allow-list or a deny-list as a static method returning enum cases and/or backing scalars:

• When both selectables() and unselectables() exist, selectables() wins.
• Filtered cases keep declaration order from the enum.

Comparisons and ordering

Operands accept enum instances, backing scalars, or null. Scalars and aliases resolve through find() (non-strict), same as lookup.

Declaration order, not backing values

Ordering methods (compareTo, isBefore, isAfter, next, previous, min, max, and related helpers) use the index in cases(), not numeric or lexical order of backing values. A case declared first with backing value 2 is still “before” a case declared second with backing value 1.

Notes:

• isIn / isNotIn ignore entries that do not resolve to a case.
• compareTo returns -1, 0, 1, or null when the other operand does not resolve.
• isBetween is inclusive on both ends by default; pass includeStart: false or includeEnd: false for exclusive bounds.
• next / previous return null at the end of the list unless $wrap is true.
• min / max skip unresolvable operands; return null if none resolve.

Equality

Order — declaration order, not backing-value sort

Range — reversed bounds are swapped automatically

Position

Navigation — null at the end unless $wrap is true

Aggregates — skip unresolvable operands; null if none resolve

Modular composition

Individual concerns live under src/Concerns/ and can be used without the full trait:

Caveat: findOrDefault() calls default(), which is defined on EnumExtension, not on EnumLookup alone. With a partial stack, use find($key) ?? self::cases()[0] or add your own default() helper.

🔋 Bundled Common enums

Optional backed enums under BensonDevs\SuperchargedEnums\Common\. Each uses Core helpers to override.

Per-enum case lists and domain-specific methods are documented under docs/common/.

Usage examples

Behavior is covered by the Pest test suite.

Development

Support

If this package saves you time, consider supporting its maintenance:

• GitHub Sponsors
• Trakteer

Thank you for helping keep Supercharged Enums maintained.

License

MIT