Macroable Laravel Package

Product Decisions This Supports

• Developer Productivity & Code Reusability: Enables teams to extend Hyperf’s core classes (e.g., collections, strings, or custom objects) with reusable, domain-specific macros—reducing boilerplate and accelerating feature development. Ideal for teams adopting Hyperf from Laravel, where macros are a familiar pattern.
• Consistency in Custom Logic: Standardizes how custom behaviors (e.g., query builders, validation helpers, or domain-specific transformations) are applied across the codebase, aligning with Laravel’s macro pattern. Reduces technical debt by centralizing logic in a maintainable way.
• Roadmap for Hyperf Adoption: Justifies investing in Hyperf as a Laravel alternative by leveraging familiar patterns (e.g., macros) for PHP developers migrating from Laravel or building new high-performance applications. Lowers the barrier to entry for teams transitioning ecosystems.
• Build vs. Buy: Avoids reinventing macro functionality from scratch, saving engineering time while maintaining flexibility to customize behavior. The package’s MIT license and active development (recent 3.2.x releases) make it a low-risk, high-reward choice.
• Use Cases:
  • Domain-Specific Extensions: Add reusable methods to Hyperf’s Collection class (e.g., calculateRevenue() for e-commerce) or custom objects (e.g., sanitizePayload() for API responses).
  • Query and Validation Logic: Simplify complex operations in microservices (e.g., custom query scopes or payload transformations) without subclassing or annotations.
  • Fluent APIs: Build domain-specific languages (DSLs) for internal tools or public APIs (e.g., Order::build()->withPromotions()->calculateTax()).
  • Legacy Code Modernization: Gradually migrate Laravel macros to Hyperf while preserving functionality during a framework transition.

When to Consider This Package

• Adopt if:
  • Your team is using Hyperf and needs to extend core classes with reusable logic (e.g., collections, strings, or custom objects) without subclassing or annotations.
  • You prioritize developer velocity and want to avoid repetitive code while keeping logic centralized and maintainable.
  • Your application requires domain-specific extensions (e.g., custom query macros, validation helpers) that align with Laravel’s macro pattern, especially if migrating from Laravel.
  • You’re building high-performance microservices or APIs where Hyperf’s speed is critical, but need Laravel-like abstractions for productivity.
  • Your roadmap includes dual Laravel/Hyperf development, and you need a bridge to reuse macro patterns incrementally.
• Look elsewhere if:
  • Your team is not using Hyperf (this package is Hyperf-specific; alternatives like illuminate/macroable may fit Laravel or other frameworks).
  • You need enterprise-grade support or a mature ecosystem (low stars/dependents may indicate limited community adoption or documentation).
  • Your use case requires highly specialized macros that aren’t covered by the package’s core functionality (may need custom development or alternative patterns like decorators/AOP).
  • You’re evaluating alternative frameworks (e.g., Symfony, Swoole) that don’t support this pattern natively or have built-in alternatives (e.g., Symfony’s compiler passes).
  • Your application is stateless or purely functional, where macros add unnecessary complexity or runtime overhead.

How to Pitch It (Stakeholders)

For Executives: "This package allows our Hyperf-based applications to extend core functionality with reusable, domain-specific macros—just like Laravel’s system. It’s a lightweight, high-impact way to boost developer productivity by eliminating boilerplate code for common operations (e.g., collections, validation, or queries). With minimal overhead, we can standardize custom logic across the codebase, reduce technical debt, and accelerate feature delivery—all while leveraging Hyperf’s high performance. It’s a strategic fit if we’re committed to Hyperf, as it aligns with Laravel’s familiar patterns for teams migrating or building new systems. The MIT license and active development ensure low risk, while the package’s design saves months of engineering time that would otherwise be spent reinventing this functionality."

For Engineering: *"The hyperf/macroable package brings Laravel’s macro system to Hyperf, enabling us to dynamically extend classes like Collection, String, or custom objects with reusable methods. Here’s how it helps:

• Collections: Add domain-specific methods like groupByDate() or calculateMetrics() without subclassing or annotations.
• Requests/Responses: Inject custom transformations (e.g., sanitizePayload()) or validation logic directly into objects.
• Query Builders: Define reusable scopes or conditions (e.g., User::whereActive()->withRoles()) in a fluent, maintainable way.
• Legacy Code: Migrate Laravel macros to Hyperf incrementally, preserving functionality during a framework transition.

This avoids code duplication, makes logic easier to maintain, and keeps our Hyperf apps consistent with Laravel’s ecosystem. The package is a trait, so integration is minimal—just add use Macroable to any class and start defining macros. Recent releases (v3.2.x) show active development, and the MIT license means no vendor lock-in. It’s a low-risk, high-reward choice for Hyperf projects needing Laravel-like abstractions."*

For Architects/Tech Leads: *"This package addresses a critical gap in Hyperf’s ecosystem by providing a Laravel-compatible macro system for extending classes dynamically. Key benefits:

• Performance: Macros add negligible overhead (method lookup via data_get), making them suitable for high-concurrency Hyperf applications.
• Flexibility: Works with Hyperf’s DI container, coroutines, and PSR standards, unlike Laravel’s event-driven macro registration.
• Migration Path: If we’re transitioning from Laravel, this package lets us reuse macro patterns without rewriting core logic from scratch.
• Scalability: Stateless macros scale horizontally with Hyperf’s process model; stateful macros can leverage Redis or databases for shared state.

Trade-offs:

• Debugging: Macros can obscure call stacks; we’ll need to document macro usage and consider naming conventions (e.g., macro_* prefixes).
• Hyperf-Specific Quirks: Macros registered via the container may not persist across worker processes, requiring explicit synchronization for shared state.
• Alternatives: For stateful behavior, we could explore Hyperf’s decorators or AOP (e.g., hyperf/aop), but macros offer a simpler syntax for most use cases.

Recommendation: Adopt this package for domain-specific extensions (e.g., collections, queries, validation) and pair it with Hyperf’s native tools for infrastructure concerns (e.g., middleware, annotations). Start with non-critical macros in utility classes, then expand to core services as confidence grows."*