Hook Press Laravel Package

Technical Evaluation

Architecture Fit

• Discoverability Optimization: HookPress leverages Composer hooks to pre-build a static class map (traits, interfaces, classes) during composer install/update, eliminating runtime discovery overhead (e.g., get_declared_classes(), class_uses(), or Laravel’s app:discover). This aligns well with performance-critical Laravel applications (e.g., APIs, microservices) where class discovery is a bottleneck.
• Caching Layer: The package’s O(1) lookup for "discoverable" entities reduces dynamic reflection calls, which is valuable for:
  • Service Providers: Faster binding resolution (e.g., bindIf(), when() conditions).
  • Middleware/Event Listeners: Reduced latency in dependency resolution.
  • Dynamic Proxies: Useful for packages like Laravel Scout or Eloquent events.
• Filtering Capability: The ability to filter classes/traits/interfaces by namespace or annotations enables granular control, which is critical for:
  • Modular Monoliths: Isolating discovery to specific modules (e.g., App\Modules\*).
  • Plugin Systems: Dynamically loading/unloading features without full autoload scans.

Integration Feasibility

• Laravel Compatibility: Explicitly designed for Laravel (uses Illuminate\Support\ServiceProvider hooks), with minimal friction for:
  • Service Registration: Can be bootstrapped via config/app.php or a dedicated provider.
  • Cache Integration: Works with Laravel’s cache drivers (e.g., Redis, file) for the static map.
• Composer Hooks: Relies on Composer’s post-autoload-dump hook, which is standard but requires:
  • CI/CD Awareness: Hooks must be triggered in build pipelines (e.g., GitHub Actions, Docker builds).
  • Local Development: Developers must run composer install --no-dev or composer update to regenerate the cache.
• Backward Compatibility: Non-intrusive; existing discovery mechanisms (e.g., ClassFinder, get_declared_classes()) remain functional.

Technical Risk

• Composer Hook Reliability:
  • Risk: Hooks may fail silently if Composer’s post-autoload-dump is skipped (e.g., in Docker builds with --no-install).
  • Mitigation: Add a post-install-cmd script in composer.json to enforce hook execution:

    "scripts": {
      "post-install-cmd": [
        "HookPress\\HookPress::generateCache"
      ]
    }
    

  • Fallback: Implement a runtime check to verify cache existence and regenerate if missing.
• Cache Invalidation:
  • Risk: Stale cache during development if classes are added/removed without composer dump-autoload.
  • Mitigation: Use Laravel’s config('hookpress.cache_lifetime') to set short TTLs (e.g., 5 minutes) in dev environments.
• Namespace Collisions:
  • Risk: Overlapping namespaces between core app and third-party packages may cause unintended filtering.
  • Mitigation: Document namespace whitelisting/blacklisting strategies in the team’s architecture guidelines.
• Testing Overhead:
  • Risk: Unit tests relying on dynamic discovery (e.g., get_declared_traits()) may break.
  • Mitigation: Mock the HookPress cache in tests or use HookPress::disable() for isolated test suites.

Key Questions

1. Performance Benchmarks:
   • What’s the measurable improvement in class discovery for our most critical paths (e.g., API request handling, job queues)?
   • How does this compare to alternatives like OPcache or Laravel’s built-in ClassFinder?
2. Adoption Scope:
   • Should we restrict HookPress to specific modules (e.g., only for plugins) or enable it globally?
   • How will this interact with existing service providers that rely on dynamic discovery?
3. CI/CD Impact:
   • Will Composer hooks add significant build time? If so, should we cache the HookPress output in CI?
   • How will we handle environments where composer dump-autoload is prohibited (e.g., serverless functions)?
4. Maintenance:
   • Who owns the HookPress cache invalidation strategy (e.g., post-deploy hooks, manual triggers)?
   • How will we monitor cache hit/miss ratios to validate ROI?
5. Alternatives:
   • Could we achieve similar gains with OPcache or Laravel’s ClassFinder optimizations?
   • Is there a hybrid approach (e.g., HookPress for traits/interfaces, OPcache for classes)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Primary Use Cases:
    • Service Providers: Accelerate bindIf() or when() conditions in AppServiceProvider.
    • Dynamic Proxies: Reduce reflection overhead in packages like Laravel Scout or Eloquent events.
    • Middleware: Faster resolution of injected dependencies (e.g., resolveCallback in middleware).
  • Compatibility:
    • Laravel 10/11: Explicitly tested (last release 2025-08-31).
    • PHP 8.1+: Required for Composer hooks and attributes (used for filtering).
    • Cache Drivers: Supports all Laravel cache backends (Redis, file, database).
• Non-Laravel PHP:
  • Limited Value: HookPress is Laravel-specific; avoid for vanilla PHP projects.

Migration Path

1. Assessment Phase:
   • Audit current class discovery bottlenecks using Xdebug or Blackfire.
   • Identify high-impact areas (e.g., service providers, middleware) for HookPress.
2. Pilot Integration:
   • Install via Composer:

     composer require teofanis/hook-press
     

   • Configure in config/app.php:

     'providers' => [
         HookPress\HookPressServiceProvider::class,
     ],
     

   • Define discoverable entities in config/hookpress.php:

     'discoverables' => [
         'classes' => ['App\Modules\\*\\Services\\*'],
         'traits' => ['App\Traits\\*'],
         'interfaces' => ['App\Contracts\\*'],
     ],
     

3. Incremental Rollout:
   • Phase 1: Enable HookPress for non-critical modules (e.g., plugins).
   • Phase 2: Expand to core service providers; monitor performance.
   • Phase 3: Replace dynamic discovery in middleware/events with HookPress lookups.
4. Fallback Strategy:
   • Implement a runtime check to degrade gracefully if the cache is missing:

     if (!HookPress::hasCache()) {
         // Fallback to get_declared_classes()
     }
     

Compatibility

• Composer Version: Requires Composer 2.5+ (for stable hooks).
• Laravel Features:
  • Service Container: HookPress integrates with Laravel’s container but doesn’t replace it.
  • Packages: May conflict with packages that modify composer.json hooks (e.g., Laravel Pint, Pest).
  • Testing: Requires adjustments for tests using dynamic discovery (see Technical Risk).
• Deployment:
  • Shared Hosting: May fail if Composer hooks are disabled (e.g., Heroku, shared PHP environments).
  • Docker: Ensure composer dump-autoload runs in build stages.

Sequencing

1. Pre-requisites:
   • Upgrade to PHP 8.1+ and Laravel 10/11 if not already.
   • Standardize Composer hooks across the codebase.
2. Core Integration:
   • Register HookPress provider and configure config/hookpress.php.
   • Test cache generation locally and in CI.
3. Performance Tuning:
   • Benchmark cache hit rates and adjust cache_lifetime.
   • Optimize discoverable namespaces to avoid over-fetching.
4. Monitoring:
   • Log cache misses to identify stale or missing entries.
   • Set up alerts for failed Composer hook executions.

Operational Impact

Maintenance

• Cache Management:
  • Proactive: Add a php artisan hookpress:clear command to invalidate cache during deployments.
  • Automated: Use Laravel’s post-deploy hooks or Forge/Envoyer scripts to regenerate cache.
  • Monitoring: Track cache size and regeneration frequency (e.g., via Laravel Horizon or Prometheus).
• Configuration Drift:
  • Risk: config/hookpress.php may diverge across environments.
  • Mitigation: Use Laravel’s environment config or a dedicated package (e.g., spatie/laravel-config-array) for dynamic filtering rules.
• Dependency Updates:
  • Risk: Breaking changes if HookPress evolves (e.g., new filtering syntax).
  • Mitigation: Pin the package version in composer.json until adoption is widespread.

Support

• Debugging:
  • Cache Issues: Provide visibility into