Propel Eventdispatcher Behavior Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add to composer.json:

   "require": {
       "willdurand/propel-eventdispatcher-behavior": "dev-master"
   }
   

   Run composer update.

2. Configure Propel Add to propel.ini or build.properties:

   propel.behavior.eventdispatcher.class = vendor.willdurand.propel-eventdispatcher-behavior.src.EventDispatcherBehavior
   

3. Apply to a Model In schema.xml, add the behavior to a <table>:

   <behavior name="event_dispatcher" />
   

4. First Use Case Dispatch an event in a model method:

   $this->getEventDispatcher()->dispatch('user.created', new UserEvent($this));
   

Implementation Patterns

Workflow Integration

1. Event-Driven Model Logic Use getEventDispatcher() to trigger events in model methods (e.g., save(), delete()):

   public function save() {
       $this->getEventDispatcher()->dispatch('user.pre_save', $this);
       parent::save();
       $this->getEventDispatcher()->dispatch('user.post_save', $this);
   }
   

2. Listener Registration Register listeners in a service provider or bootstrap file:

   $dispatcher = $this->getEventDispatcher();
   $dispatcher->addListener('user.created', function ($event) {
       // Handle user creation
   });
   

3. Event Objects Create custom event classes (e.g., UserEvent) extending Event:

   class UserEvent extends Event {
       public function __construct(private UserModel $user) {}
       public function getUser() { return $this->user; }
   }
   

4. Global vs. Instance Dispatchers

   • Global: Register listeners once (e.g., in a service container).
   • Instance: Dispatch per-model instance (e.g., for dynamic events).

5. Propel Lifecycle Hooks Combine with Propel’s preInsert, postUpdate, etc., for granular control:

   <table name="user">
       <behavior name="event_dispatcher" />
       <column name="name" type="VARCHAR" behavior="[preInsert, postUpdate]"/>
   </table>
   

Gotchas and Tips

Pitfalls

1. Singleton Dispatcher

   • The behavior creates a per-class dispatcher (not per-instance).
   • Avoid stateful listeners; use event objects for data sharing.

2. Propel Schema Updates

   • Adding the behavior to an existing table does not retroactively add events to past operations.
   • Test thoroughly after schema changes.

3. Circular Dependencies

   • Avoid dispatching events in listeners that might trigger the same event recursively.
   • Example: A user.updated listener modifying the user again.

4. Performance

   • Event dispatching adds overhead. Use sparingly for critical paths.
   • Benchmark if dispatching in bulk operations (e.g., batch updates).

Debugging

1. Listener Not Triggering?

   • Verify the event name matches exactly (case-sensitive).
   • Check if the listener is registered before dispatching.

2. Dispatcher Not Available?

   • Ensure the behavior is correctly configured in propel.ini.
   • Confirm the table includes <behavior name="event_dispatcher" />.

3. Propel Caching

   • Clear Propel’s cache (php propel:build --no-confirm) if changes aren’t reflected.

Extension Points

1. Custom Event Dispatcher Override the default dispatcher by extending the behavior:

   class CustomEventDispatcherBehavior extends EventDispatcherBehavior {
       protected function getDispatcher() {
           return new CustomDispatcher(); // Your implementation
       }
   }
   

   Update propel.ini to point to your class.

2. Dynamic Event Names Use model properties to construct event names:

   $eventName = 'user.'.$this->getType().'.created';
   $this->getEventDispatcher()->dispatch($eventName, $this);
   

3. Integration with Laravel

   • Service Provider: Bind the dispatcher to Laravel’s container:

     $this->app->bind('propel.dispatcher', function () {
         return PropelModel::getEventDispatcher();
     });
     

   • Event Facade: Create a facade for cleaner syntax:

     class PropelEvent {
         public static function dispatch($event, $subject) {
             $model = PropelModel::getModel($subject);
             $model->getEventDispatcher()->dispatch($event, $subject);
         }
     }
     

     Usage: PropelEvent::dispatch('user.created', $user);

4. Testing

   • Mock the dispatcher in unit tests:

     $dispatcher = Mockery::mock('Symfony\Component\EventDispatcher\EventDispatcher');
     $this->getEventDispatcher()->shouldReceive('dispatch')->once();