Trigger Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleentfaar/trigger-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Cleentfaar\TriggerBundle\CLTriggerBundle::class => ['all' => true],
   ];
   

2. Configure Triggers Define triggers in config/packages/cleentfaar_trigger.yaml:

   cleentfaar_trigger:
       triggers:
           reset_password:
               parameter: reset
               handler: App\Handler\ResetPasswordHandler
               redirect:
                   url: /login
                   strip_parameters: [reset, token]
   

3. First Use Case Trigger a one-time action via URL:

   /dashboard?reset=true
   

   The ResetPasswordHandler will execute, then redirect to /login with reset and token removed.

Implementation Patterns

Common Workflows

1. One-Time Actions Use for password resets, email verifications, or temporary state changes:

   cleentfaar_trigger:
       triggers:
           verify_email:
               parameter: verify
               handler: App\Handler\VerifyEmailHandler
               redirect: /dashboard
   

2. Conditional Execution Combine with Symfony’s RequestStack to check additional conditions:

   // src/Handler/ResetPasswordHandler.php
   public function handle(Request $request, $value)
   {
       if (!$request->get('token')) {
           throw new \RuntimeException('Token missing');
       }
       // Proceed with logic
   }
   

3. Parameter Stripping Automatically clean URLs post-execution:

   redirect:
       strip_parameters: [action, id, token]
   

4. Event-Based Triggers Dispatch Symfony events inside handlers:

   $eventDispatcher->dispatch(new PasswordResetEvent($user));
   

Integration Tips

• Dependency Injection Use Symfony’s autowiring to inject services into handlers:

  // src/Handler/ExampleHandler.php
  public function __construct(private UserRepository $users)
  {
  }
  

• Validation Validate parameters in handlers before processing:

  if (!preg_match('/^[a-f0-9]{64}$/', $value)) {
      throw new \InvalidArgumentException('Invalid token format');
  }
  

• Logging Log trigger executions for debugging:

  $this->logger->info('Trigger executed', ['trigger' => 'reset_password', 'params' => $request->query->all()]);
  

Gotchas and Tips

Pitfalls

1. Parameter Collisions Avoid naming triggers after existing route parameters to prevent conflicts. Use unique names like trigger_verify_email.

2. Handler Visibility Handlers must be public and follow the signature:

   public function handle(Request $request, $value): void
   

3. Redirect Loops Ensure redirect.url does not include the trigger parameter to avoid infinite redirects.

4. Case Sensitivity Trigger parameters are case-sensitive (?Reset=true ≠ ?reset=true).

5. Caching Issues Clear Symfony’s cache after adding/updating triggers:

   php bin/console cache:clear
   

Debugging

• Check Trigger Execution Enable debug mode to see if handlers are called:

  APP_ENV=dev APP_DEBUG=1 php bin/console server:run
  

  Look for handler logs in var/log/dev.log.

• Validate YAML Use symfony/validator to validate config:

  php bin/console debug:config cleentfaar_trigger
  

Extension Points

1. Custom Handlers Extend Cleentfaar\TriggerBundle\Handler\AbstractHandler for reusable logic.

2. Dynamic Triggers Register triggers programmatically in a compiler pass:

   // src/DependencyInjection/Compiler/TriggerPass.php
   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('cleentfaar_trigger.handler.dynamic');
       $definition->addMethodCall('addTrigger', ['dynamic_name', new Reference('service.id')]);
   }
   

3. Middleware Integration Use Symfony’s Middleware to pre-process requests before trigger evaluation:

   // src/Kernel.php
   $middleware->add(new class implements MiddlewareInterface {
       public function handle(Request $request, callable $next): Response {
           if ($request->query->has('trigger')) {
               // Custom logic
           }
           return $next($request);
       }
   });
   

4. Event Listeners Listen for trigger.pre_execute and trigger.post_execute events:

   # config/services.yaml
   services:
       App\EventListener\TriggerListener:
           tags:
               - { name: kernel.event_listener, event: trigger.pre_execute, method: onPreExecute }