Macroable Laravel Package

Product Decisions This Supports

• Build vs. buy, resolved in favor of "already have." Macroable is a zero-cost extensibility layer already shipped inside Laravel. It removes an entire category of roadmap work — designing a plugin/hook system, a custom helper registry, or forking framework internals to add domain methods. That budget goes back into product features.
• Feature-level customization speed. Product asks like "format prices, SKUs, and phone numbers the way our market expects," "add a tenant-specific filter to every query," or "give support agents a one-liner for account health" can ship as macros on Str, Collection, or Model rather than as new services, new classes, or upstream PRs.
• Roadmap sequencing for platform work. If multiple products/teams need the same helper semantics (e.g., localized string casing, currency rounding, soft-delete-aware aggregations), standardizing on macros gives a shared, low-ceremony extension surface. That directly informs whether the next quarter's platform investment is "internal shared helpers package" vs. "microservice extraction."
• Architecture and coupling decisions. Macros let us extend vendor and framework classes without inheritance or patching, which keeps upgrade paths to future Laravel majors open. That's a concrete input to decisions about how much we customize the framework vs. work within it.
• Multi-product consistency and reuse. Grouping macros into per-domain macro providers (string macros, collection macros, factory macros) creates a lightweight internal "design system" for backend behavior — reusable across repos, reviewable in one place.
• Risk posture. Adopting it introduces no new vendor, no license review (MIT, part of Laravel), no procurement, no separate security feed to track — it rides Laravel's release train. For a PM, that's a "decide today, revisit at framework upgrades" call, not a multi-sprint evaluation.

One packaging note worth carrying into any decision record: illuminate/macroable is not a separately published Composer package — the Macroable trait lives inside illuminate/support in the Laravel monorepo. The real product decision is therefore "do we standardize on Laravel's macro idiom as our extension pattern?", not "do we add a dependency?"

When to Consider This Package

Consider it when:

• The product runs on Laravel (or on components that already pull in illuminate/support). In that case the capability is already in the dependency tree — the decision is purely about convention and governance.
• The team needs to add behavior to classes it does not own — framework classes (Str, Collection, Stringable), vendor SDK response objects, or Eloquent builders — where inheritance, patching, or wrapping would create upgrade friction.
• You want the same domain helpers available across two or more codebases without publishing and versioning an internal package.
• An extension point must be reachable everywhere in the app with minimal ceremony — e.g., registered once in a service provider's boot() and available app-wide.
• The team is willing to accept a small convention cost: macros are invisible to IDE autocomplete and reflection, so they need a documented registry or a dedicated macro service provider to stay discoverable.

Look elsewhere when:

• The stack isn't Laravel/PHP — this is not portable and not worth emulating for its own sake.
• The codebase is small or the helper is used once. A plain static helper, a dedicated service, or dependency injection will be easier to read, type, and test. Introducing macros for one or two methods buys indirection with no payoff.
• Static analysis and type coverage are hard requirements. Macro calls don't resolve for PHPStan/Psalm or IDE tooling without extra stubs; if your quality bar depends on full static resolution, prefer first-class methods, interfaces, or value objects.
• The extension sits in a hot path. Macros resolve at runtime; tight loops and high-throughput serialization are the wrong place for them.
• A first-class extension point already exists — events/listeners, custom casts, service container bindings, or a documented SDK hook. Using the native seam is cheaper to maintain than a dynamic one.
• You need per-macro versioning, deprecation policy, or independent security tracking. There's no separate package to pin, publish, or audit; governance has to be built internally (a macro registry plus review conventions) or the capability isn't a fit for a platform-level contract.

How to Pitch It (Stakeholders)

For executives (30 seconds): "This is a capability we already own. Laravel ships a built-in mechanism that lets our engineers add product-specific behavior — localized formatting, tenant rules, reporting helpers — to the framework's core classes without forking it or buying anything. It costs nothing, adds no vendor, and keeps our upgrade path to future Laravel versions clean. The upside is speed: customization that would otherwise be a platform project or an upstream contribution becomes a small, reviewed addition. The risk is low and well understood, and the main guardrail is a short internal convention so the team can find and reuse what's been added. Recommendation: standardize on it as our extension pattern, with a documented macro registry."

For engineering: "Macroable is a small trait included with Laravel — you use it on a class and register closures via macro(). It's the same mechanism behind Collection and Str extensions. Proposed conventions: register macros in a dedicated macro service provider during boot(); group them by domain class rather than scattering them; guard registrations with hasMacro() since re-registering silently overwrites; test macros as closures; and keep them out of hot loops. Two things to plan for: macros don't appear in IDE autocomplete or reflection, so we maintain a registry doc plus stub files if we want static analysis to pass; and because the trait is bundled rather than a standalone package, upgrades and any security review ride along with Laravel itself rather than a separate dependency. If a helper is used once or is better expressed as a service, use a service — this is for behavior we want available everywhere, cheaply."