Tappable Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The hyperf/tappable package is a port of Laravel’s illuminate/tappable, which provides the macroable trait and tappable contract—core components for Laravel’s service container and macro system. If the existing Laravel codebase relies on macros (e.g., Str::macro(), Collection::macro()) or tappable services, this package could be a direct replacement in a Hyperf migration or a dual-stack integration (Laravel + Hyperf).
• Hyperf Ecosystem Synergy: Hyperf is a high-performance PHP framework, and this package aligns with its dependency injection (DI) and extension mechanisms. It could enable dynamic method injection (macros) in Hyperf services, similar to Laravel’s app()->bind() or app()->extend().
• Use Case Alignment:
  • Legacy Laravel Code Reuse: If parts of the codebase use Laravel’s tappable features (e.g., custom string/collection macros), this package allows seamless porting to Hyperf.
  • Hyperf-Specific Extensions: Could enable runtime method injection for Hyperf’s processes, coroutines, or RPC services without modifying core classes.
• Anti-Patterns:
  • Overhead for Simple Use Cases: If the codebase doesn’t use macros or dynamic service extensions, this package adds unnecessary complexity.
  • Hyperf’s Native Alternatives: Hyperf already supports DI extensions via define() in config/autoload.php or middlewares/bindings in container.php. This package may duplicate functionality unless macros are explicitly needed.

Integration Feasibility

• API Parity: The package replicates Laravel’s:
  • Macroable trait (for adding static methods at runtime).
  • Tappable contract (for resolving services with custom logic).
  • MacroableServiceProvider (for registering macros).
• Hyperf-Specific Adaptations:
  • Container Integration: Hyperf uses PSR-11 (PHP-DI) by default. The package must ensure compatibility with Hyperf’s Container class (extends Illuminate\Container\Container in some Hyperf versions).
  • Autoloading: Macros must be autoloaded via Hyperf’s autoload configuration (e.g., autoloads/macros.php).
  • Service Providers: Hyperf uses define() in config/autoload.php for bindings. The package may require a custom service provider to register macros.
• Testing Overhead:
  • Macro Behavior: Testing dynamic method injection in Hyperf’s coroutine/process context may require mocking or custom test cases.
  • Performance Impact: Macros add runtime reflection, which could introduce micro-latency in high-throughput Hyperf applications.

Technical Risk

Key Questions

1. Why Macros?

   • Does the codebase heavily rely on Laravel’s Str::macro(), Collection::macro(), or custom tappable services?
   • Are macros used for domain-specific language (DSL) extensions (e.g., Order::calculateTax())?

2. Hyperf-Specific Constraints

   • Will macros be used in Hyperf processes (e.g., ProcessManager) or RPC services?
   • Does Hyperf’s PSR-11 container need to be extended, or can illuminate/tappable be polyfilled?

3. Alternatives

   • Can Hyperf’s native DI extensions (define(), bind()) replace macros?
   • Is there a Hyperf-first package (e.g., hyperf/extender) that achieves the same goal?

4. Testing Strategy

   • How will macro behavior be tested in Hyperf’s async (coroutine/swoole) environment?
   • Are there race conditions when macros modify shared services?

5. Future-Proofing

   • Will Hyperf deprecate illuminate/tappable in favor of native solutions?
   • Is the package actively maintained (last release in 2026, but low stars suggest niche use).

Integration Approach

Stack Fit

• Hyperf Core Compatibility:

  • Container: Works if Hyperf’s Container extends Illuminate\Container\Container (common in older versions). For newer Hyperf (PHP-DI), a shim layer may be needed.
  • Service Providers: Hyperf uses define() in config/autoload.php. Macros should be registered in a custom ServiceProvider (extending Hyperf\Di\Container).
  • Coroutines/Processes: Macros must be thread-safe if used in async contexts (e.g., Swoole\Coroutine).

• Laravel Interop:

  • If the codebase is migrating from Laravel, this package provides 1:1 macro support.
  • For dual-stack (Laravel + Hyperf), consider conditional loading (e.g., if (app()->runningInHyperf())).

• Tooling Integration:

  • IDE Support: Macros may break static analysis (PHPStan, Psalm) due to dynamic method injection.
  • Dependency Injection: Ensure macros don’t conflict with Hyperf’s autowiring.

Migration Path

1. Assessment Phase:

   • Audit all macro usages in the Laravel codebase (e.g., Str::macro(), Collection::macro()).
   • Identify tappable services (e.g., custom resolvers in AppServiceProvider).

2. Proof of Concept (PoC):

   • Set up a Hyperf skeleton with hyperf/tappable.
   • Replicate 1-2 critical macros to verify behavior.
   • Test in synchronous and coroutine contexts.

3. Incremental Rollout:

   • Phase 1: Replace Laravel macros with hyperf/tappable in non-critical modules.
   • Phase 2: Migrate tappable services (e.g., custom app()->bind() logic).
   • Phase 3: Refactor global macros (e.g., Str::macro()) to scoped macros (e.g., App\Extensions\StrMacros).

4. Fallback Plan:

   • If integration fails, use Hyperf’s native DI (define(), bind()) or a custom macro system built on PHP’s spl_object_hash().

Compatibility

Sequencing

1. Prerequisites:

   • Upgrade Hyperf to a version that supports illuminate/container (or implement a shim).
   • Ensure PHP 8.1+ (for named arguments, attributes, and performance).

2. Core Integration:

   • Install hyperf/tappable via Composer.
   • Create a MacroServiceProvider to register macros:

     namespace App\Providers;
     
     use Hyperf\Di\Annotation\Inject;
     use Hyperf\Contract\ContainerInterface;
     use Hyperf\Framework\ServiceProvider;
     use Hyperf\Tappable\Macroable;
     
     class MacroServiceProvider extends ServiceProvider
     {
         public function register()
         {
             if (method_exists(Macroable::class, 'macroable')) {
                 Macroable::macroable($this->