Hook Press Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require teofanis/hook-press
   

   Add to composer.json under extra:

   "hook-press": {
       "enabled": true,
       "cache-path": "bootstrap/cache/hookpress",
       "discover": ["app/Contracts/*", "app/Traits/*"]
   }
   

   Run composer dump-autoload to trigger the Composer hook.

2. First Use Case: Use the HookPress facade to fetch cached classes:

   use Teofanis\HookPress\Facades\HookPress;
   
   $contracts = HookPress::get('App\\Contracts\\*');
   $traits = HookPress::get('App\\Traits\\*');
   

Where to Look First

• Configuration: config/hookpress.php (auto-generated after first run).
• Cache: bootstrap/cache/hookpress/ (pre-built class maps).
• Facade: HookPress::get($pattern) for runtime lookups.

Implementation Patterns

Core Workflows

1. Class Discovery:

   • Define discovery patterns in composer.json under hook-press.discover.
   • Example: Cache all Service classes:

     "hook-press": {
         "discover": ["app/Services/*"]
     }
     

   • Access via:

     $services = HookPress::get('App\\Services\\*');
     

2. Dynamic Filtering:

   • Use HookPress::filter() to narrow results at runtime:

     $activeServices = HookPress::filter($services, fn($class) => class_exists($class));
     

3. Integration with Service Providers:

   • Bind discovered classes to the container:

     public function register()
     {
         $classes = HookPress::get('App\\Contracts\\*');
         foreach ($classes as $class) {
             $this->app->bind($class, fn($app) => new $class());
         }
     }
     

4. Caching Strategies:

   • Tag-based invalidation: Extend Teofanis\HookPress\Cache\CacheManager to clear cache on config changes.
   • Manual refresh: Call HookPress::refresh() after adding new classes.

Advanced Patterns

• Trait/Interface Enforcement: Use HookPress::validate() to ensure discovered classes implement traits/interfaces:

  $validClasses = HookPress::validate($classes, 'App\\Contracts\\Validatable');
  

• Lazy Loading: Defer class instantiation until needed:

  $classNames = HookPress::get('App\\Lazy\\*');
  $instances = collect($classNames)->map(fn($class) => new $class());
  

• Testing: Mock HookPress in tests:

  HookPress::shouldReceive('get')->andReturn(['Mock\\Class']);
  

Gotchas and Tips

Common Pitfalls

1. Cache Staleness:

   • Issue: Cache isn’t updated after adding new classes.
   • Fix: Run composer dump-autoload or manually call HookPress::refresh().

2. Pattern Mismatches:

   • Issue: HookPress::get() returns empty results.
   • Debug: Verify composer.json patterns match actual class paths (e.g., App\Contracts\* vs. app/Contracts/*).

3. Composer Hook Conflicts:

   • Issue: Hook fails silently if another package overrides Composer scripts.
   • Fix: Ensure hook-press runs last in post-autoload-dump:

     "scripts": {
         "post-autoload-dump": [
             "@hook-press",
             "other-scripts"
         ]
     }
     

4. Namespace Collisions:

   • Issue: Duplicate class names in different namespaces.
   • Fix: Use fully qualified names (e.g., App\\Services\\*) or filter results:

     HookPress::filter($classes, fn($class) => str_starts_with($class, 'App\\Services\\'));
     

Debugging Tips

• Inspect Cache:

  ls -la bootstrap/cache/hookpress/
  cat bootstrap/cache/hookpress/classes.json
  

• Enable Logging: Set HOOKPRESS_DEBUG=1 in .env to log discovery steps.

Extension Points

1. Custom Cache Drivers: Extend Teofanis\HookPress\Cache\CacheInterface for Redis/Memcached:

   HookPress::setCacheDriver(new RedisCache());
   

2. Pre/Post-Processors: Add logic before/after discovery via hook-press.processors in composer.json:

   "hook-press": {
       "processors": ["App\\HookPress\\Processors\\ValidateTrait"]
   }
   

3. Dynamic Patterns: Override HookPress::getPatterns() to fetch patterns from a config file:

   public function getPatterns(): array
   {
       return config('hookpress.patterns');
   }
   

Performance Notes

• Cache Hit Ratio: Aim for >95% to avoid runtime discovery.
• Avoid Over-Discovery: Limit patterns to essential classes (e.g., app/Contracts/* instead of app/*).