Class Metadata Laravel Package

Product Decisions This Supports

• Where we persist class names. A recurring decision is whether type identifiers stored in the database, config, or API payloads should be raw FQCNs (App\Payments\StripeGateway) or stable short keys (stripe). This package gives a first-class way to maintain the alias↔class mapping, so the "store FQCNs and hope we never rename" shortcut stops being the default.
• Build vs. buy for internal registries. Most codebases eventually grow a hand-rolled Class => 'slug' constant map or a switch on class names. This is a candidate drop-in replacement for that pattern: small surface area, MIT, and it removes an internal file that only one team understands.
• Roadmap for extensibility. If the roadmap includes plugins, tenant-specific module toggles, CMS block types, or payment/shipping provider lists, a class-alias + metadata registry is the plumbing those features need. Deciding to adopt it now is cheaper than retrofitting identifiers after data exists.
• Refactor and migration cost. Aliases decouple persisted values from namespaces and class names. That directly lowers the cost of renames, module extraction, and namespace cleanup — a recurring tax on fast-moving codebases.
• API and audit-log contracts. If type fields appear in public API responses or audit/event logs, aliases become part of the product contract. Choosing them deliberately (rather than exposing FQCNs) is a compatibility decision worth making early.
• Metadata-driven behavior. If we expect to attach more than a name to a type — display label, icon, sort order, feature flags — a metadata registry keeps that out of match statements scattered across the codebase.

When to Consider This Package

Consider it when:

• Class names are already (or are about to be) persisted in the DB, queued jobs, cache keys, or API payloads, and you want bidirectional alias lookup.
• You need more than one alias per class — e.g. label + key + group — and want it in one place.
• Lookups happen frequently per request and you want a precomputed/cached map rather than reflection or attribute scanning at runtime.
• You're comfortable with a framework-agnostic PHP library. It is not a Laravel package with a service provider or facade; expect to wire it yourself (bindings, config file, cache store).
• Dependency minimalism matters more than ecosystem gravity.

Look elsewhere when:

• The need is only Eloquent polymorphic relations. Laravel's built-in Relation::morphMap() already solves that and is one less dependency.
• You want attribute/annotation-driven discovery with heavy tooling — Symfony's metadata/Doctrine components or a container-compiled map will be a better fit.
• You need metadata that changes at runtime from a database or admin UI; this is oriented toward a defined, cacheable mapping.
• Your dependency policy rejects low-adoption libraries (14 stars, effectively single-maintainer). Mitigation: the package is small enough to vendor or fork, so treat it as readable source you adopt, not infrastructure you depend on.
• You're on a legacy PHP version or need long-term vendor support/SLA — there's none here.

How to Pitch It (Stakeholders)

To executives: This is a tiny, MIT-licensed utility that solves a persistent, unglamorous problem — our code and our stored data currently share the same names, so renaming a class risks corrupting historical records or breaking API clients. Adopting stable aliases removes that coupling. Cost is near zero (small dependency, no licensing, no vendor contract), and the alternative is either a bespoke internal map or continued refactor friction. Recommend approving a short timeboxed spike, not a broad mandate.

To engineering: Small, framework-agnostic PHP library that maps classes to human-readable aliases plus arbitrary metadata, with cached lookups so you're not paying for reflection per request. It replaces the ad-hoc class-to-slug maps we keep rewriting, and gives us one place to change when a class moves. Trade-off: no Laravel integration out of the box (we wire the cache and config ourselves), low upstream adoption, and it's essentially one maintainer's project — so we wrap it behind a thin internal interface. That wrapper costs an afternoon and makes exit trivial if the package stalls. Recent tagged release (Dec 2025) and MIT license keep the risk profile low; the main risk is abandonment, which the wrapper neutralizes.