Conditionable Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is designed for Hyperf (a high-performance PHP framework), not Laravel. While PHP is shared, Laravel’s ecosystem (e.g., Eloquent, Blade, Service Providers) is fundamentally different from Hyperf’s coroutine-based, PSR-15 middleware architecture.
• Core Use Case: The package appears to enable conditional logic (e.g., middleware, route guards, or request filtering) in Hyperf’s pipeline. Laravel already has built-in solutions (e.g., Route::middleware(), Gate, Policy) for similar use cases, reducing the need for this package.
• Potential Overlap: If the goal is dynamic middleware/condition checks, Laravel’s existing middleware stack (or packages like spatie/laravel-middleware) may suffice without introducing Hyperf-specific dependencies.

Integration Feasibility

• Low Feasibility: Direct integration into Laravel is not recommended due to:
  • Hyperf’s coroutine and async model (Laravel is synchronous).
  • Hyperf’s PSR-15 middleware implementation differs from Laravel’s PSR-15 + PSR-3 stack.
  • No Laravel-specific adapters or documentation exist.
• Workarounds:
  • Reimplement logic in Laravel using existing middleware or policy-based conditions.
  • Hybrid microservices: If Hyperf is used for performance-critical APIs, this package could be used there while Laravel handles business logic.

Technical Risk

• High Risk:
  • Framework Mismatch: Hyperf’s event loop and coroutine model are incompatible with Laravel’s request lifecycle.
  • Dependency Bloat: Introducing Hyperf dependencies (e.g., hyperf/di, hyperf/http-server) would complicate Laravel’s autoloading and service container.
  • Maintenance Burden: No Laravel community support; debugging would require Hyperf expertise.
• Mitigation:
  • Isolation: Use the package only in a separate Hyperf service (e.g., via API contracts).
  • Feature Parity: Replace functionality with Laravel-native alternatives (e.g., Illuminate\Contracts\Auth\Access\Gate).

Key Questions

1. Why Hyperf? What specific Hyperf features (e.g., async, coroutines) are required that Laravel lacks?
2. Use Case Clarity: Is this for request filtering, auth/authorization, or another conditional logic scenario? Laravel may already solve it.
3. Performance Gains: Does Hyperf’s async model provide measurable benefits over Laravel’s synchronous stack for this use case?
4. Team Expertise: Does the team have Hyperf experience? If not, ramp-up time could be significant.
5. Long-Term Viability: Is Hyperf adoption planned, or is this a one-off experiment?

Integration Approach

Stack Fit

• Incompatible Stack:
  • Laravel’s Symfony HTTP Kernel vs. Hyperf’s Swoole/React-based server.
  • Laravel’s Service Container (PSR-11) vs. Hyperf’s Dependency Injection (PSR-11 + coroutines).
  • Laravel’s Blade/Twig vs. Hyperf’s template-agnostic approach.
• Partial Fit:
  • If using Lumen (Laravel’s micro-framework), some middleware concepts overlap, but Hyperf’s async model still diverges.
  • API-only Laravel apps might tolerate Hyperf for performance-critical paths, but integration would require custom bridges.

Migration Path

1. Assess Overlap:
   • Map Hyperf’s Conditionable features to Laravel equivalents (e.g., middleware groups, policies).
   • Example: Replace ConditionableMiddleware with Laravel’s Middleware::when() or Route::middleware(['auth', 'role:admin']).
2. Isolated Adoption:
   • Deploy Hyperf as a separate service (e.g., for high-load APIs) and use Laravel for business logic.
   • Communicate via API contracts (e.g., JSON:API, GraphQL).
3. Custom Wrapper (High Effort):
   • Create a Laravel facade that proxies to a Hyperf service (e.g., via HTTP calls or gRPC).
   • Example:

     // Hypothetical wrapper (not production-ready)
     class HyperfConditionable
     {
         public function check(Request $request): bool
         {
             return Http::post('hyperf-service/condition', $request->toArray())->json();
         }
     }
     

   • Risk: Adds latency and complexity; better to stick to Laravel-native solutions.

Compatibility

• Middleware:
  • Laravel’s Illuminate\Http\Middleware implements Psr\Http\Message\ServerRequestHandlerInterface.
  • Hyperf’s middleware extends Psr\Http\Server\MiddlewareInterface (PSR-15) but relies on coroutines.
  • Conflict: Laravel’s middleware runs synchronously; Hyperf’s may block or fail unpredictably.
• Dependency Injection:
  • Hyperf’s Container is not compatible with Laravel’s Illuminate\Container.
  • Solution: Avoid shared dependencies; treat Hyperf as a black box.
• Configuration:
  • Hyperf uses .env + PHP config files; Laravel’s .env is similar but not identical in behavior.

Sequencing

1. Phase 1: Evaluate Alternatives
   • Replace Hyperf’s Conditionable logic with Laravel middleware/policies.
   • Example: Use Illuminate\Auth\Access\Gate for authorization checks.
2. Phase 2: Proof of Concept (If Necessary)
   • Spin up a Hyperf micro-service to test performance gains.
   • Benchmark against Laravel’s native solutions.
3. Phase 3: Hybrid Integration (If Justified)
   • Use API gateways (e.g., Kong, Traefik) to route requests between Laravel and Hyperf.
   • Example:

     Client → Kong → [Laravel (Business Logic)] → [Hyperf (Conditional Checks)] → Response
     

4. Phase 4: Full Migration (Rarely Needed)
   • Only if Hyperf provides critical performance or feature advantages.
   • Requires rewriting Laravel app in Hyperf (high cost).

Operational Impact

Maintenance

• High Overhead:
  • Dual Stack: Managing both Laravel and Hyperf increases operational complexity.
  • Dependency Isolation: Hyperf packages may conflict with Laravel’s composer dependencies.
  • Debugging: Stack traces will be unfamiliar; Hyperf’s coroutine errors (e.g., CoroutineException) are not Laravel-friendly.
• Documentation:
  • No Laravel-specific guides; Hyperf’s docs assume its own ecosystem.
  • Workaround: Maintain a runbook for Hyperf-specific issues (e.g., Swoole worker crashes).

Support

• Limited Ecosystem:
  • No Laravel community support for Hyperf packages.
  • Fallback: Rely on Hyperf’s GitHub issues or paid support (if available).
• Vendor Lock-in:
  • Hyperf’s Conditionable may evolve independently of Laravel’s needs.
  • Risk: Future Laravel updates could break custom bridges.

Scaling

• Vertical Scaling:
  • Hyperf’s async model may help with I/O-bound tasks (e.g., API calls, DB queries).
  • But: Laravel’s synchronous model is sufficient for most CPU-bound or simple conditional logic.
• Horizontal Scaling:
  • Hyperf’s coroutines can improve concurrency, but Laravel’s queue workers (e.g., laravel-queue) often suffice.
  • Trade-off: Hyperf’s scaling benefits may not justify the integration cost.
• Resource Usage:
  • Hyperf’s Swoole/React dependencies increase memory/CPU usage compared to Laravel’s native stack.

Failure Modes

Ramp-Up

• Team Onboarding:
  • Hyperf Learning Curve: 2–4 weeks for PHP devs unfamiliar with coroutines/Swoole.
  • Laravel Devs: May resist adopting a non-Laravel stack.
• Tooling:
  • IDE Support: Hyperf’s code may not integrate well with Laravel’s IDE plugins (e.g., PHPStorm’s Laravel helpers).
  • CI/CD: Requires separate pipelines for Laravel and Hyperf services