Eventy Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tormjens/eventy
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Tormjens\Eventy\EventyServiceProvider"
   

2. First Hook Register a filter in a service provider (e.g., AppServiceProvider):

   use Tormjens\Eventy\Facades\Eventy;
   
   Eventy::filter('user.created', function ($user) {
       // Modify the user before saving
       $user->setAttribute('verified', true);
       return $user;
   });
   

3. Triggering a Hook Use the Eventy::apply() method to run filters/actions:

   $user = User::create([...]);
   Eventy::apply('user.created', $user); // Runs all registered filters
   

4. Basic Action Register and trigger an action:

   // Register
   Eventy::action('user.logged_in', function ($user) {
       Log::info("User logged in: {$user->email}");
   });
   
   // Trigger
   Eventy::apply('user.logged_in', $user);
   

Where to Look First

• Documentation: Check the GitHub README for examples and API reference.
• Config: config/eventy.php for default settings (e.g., priority handling, debug mode).
• Facade: Tormjens\Eventy\Facades\Eventy is the primary entry point.

Implementation Patterns

1. Filtering Data (Pre-Processing)

Use Case: Modify data before saving/returning (e.g., sanitization, default values).

// Register a filter for API responses
Eventy::filter('api.user.response', function ($user) {
    return $user->only(['id', 'name', 'email']); // Strip sensitive data
});

// Trigger in a controller
$user = User::find(1);
$response = Eventy::apply('api.user.response', $user);
return response()->json($response);

2. Chaining Filters

Leverage priority to control execution order:

// High priority (runs first)
Eventy::filter('order.process', function ($order) {
    $order->setStatus('processing');
}, 100);

// Low priority (runs last)
Eventy::filter('order.process', function ($order) {
    $order->sendNotification();
}, -100);

3. Conditional Hooks

Use closures to conditionally apply hooks:

Eventy::filter('user.update', function ($user, $data) {
    if (auth()->check() && auth()->user()->isAdmin()) {
        $data['is_admin'] = true; // Only admins can set this
    }
    return $data;
});

4. Dynamic Hook Names

Generate hook names dynamically for reusable logic:

function registerUserHooks($modelName) {
    Eventy::filter("{$modelName}.created", function ($model) {
        // Common logic for all models
        $model->setAttribute('created_via', 'api');
        return $model;
    });
}

// Usage
registerUserHooks('user');
registerUserHooks('post');

5. Integrating with Laravel Events

Bridge Laravel’s built-in events to eventy hooks:

// In a service provider
Event::listen('user.created', function ($user) {
    Eventy::apply('user.created', $user);
});

6. Testing Hooks

Mock hooks in tests using partials:

// Test file
Eventy::partial('user.created', function ($user) {
    $this->assertEquals('verified', $user->verified);
});

// Run test
Eventy::apply('user.created', new User());

Gotchas and Tips

Pitfalls

1. Priority Collisions

   • Default priority is 0. Overlapping priorities may lead to undefined behavior.
   • Fix: Explicitly set priorities (e.g., 100, -100).

2. Memory Leaks with Closures

   • Storing closures in hooks can cause memory issues if not unbound.
   • Fix: Unregister hooks in booted methods or use Eventy::forget().

3. Circular Dependencies

   • Hooks modifying data that triggers the same hook can cause infinite loops.
   • Fix: Use a flag to track execution:

     Eventy::filter('user.update', function ($user) {
         if (!isset($user->skipHook)) {
             $user->skipHook = true;
             // ... logic
             unset($user->skipHook);
         }
     });
     

4. Debugging Hooks

   • Enable debug mode in config/eventy.php to log hook execution:

     'debug' => env('APP_DEBUG', false),
     

   • Check logs for triggered hooks and their order.

Tips

1. Namespace Hooks Prefix hooks to avoid collisions (e.g., auth.user.login instead of user.login).

2. Use Partials for Testing Temporarily override hooks in tests without modifying production code:

   Eventy::partial('user.created', function ($user) {
       // Test-specific logic
   });
   

3. Performance For high-traffic apps, cache hook registrations:

   Eventy::cacheHooks(true); // Enable in config
   

4. Extending Functionality

   • Custom Hook Types: Extend the Eventy facade to support before/after hooks:

     Eventy::before('user.delete', function ($user) {
         // Pre-delete logic
     });
     

   • Hook Metadata: Store metadata (e.g., priority, description) in a database for dynamic management.

5. Laravel 10+ Compatibility

   • If using newer Laravel versions, ensure the package’s composer.json supports your PHP/Laravel version.
   • Check for updates to the tormjens/eventy package for Laravel 10+ fixes.

6. Security

   • Validate hook inputs to prevent injection:

     Eventy::filter('user.update', function ($user, $data) {
         $data = array_intersect_key($data, array_flip(['name', 'email'])); // Whitelist
         return $data;
     });