Application Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require draw/application-bundle
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Draw\ApplicationBundle\ApplicationBundleServiceProvider::class,
   ],
   

2. First Use Case: Domain Logic Container Register a domain logic handler in config/application.php (created automatically):

   'handlers' => [
       'user_registration' => [
           'class' => App\Services\UserRegistrationHandler::class,
           'method' => 'handle',
       ],
   ],
   

3. Triggering Logic Inject the ApplicationBundle facade into a controller:

   use Draw\ApplicationBundle\Facades\ApplicationBundle;
   
   public function register(Request $request) {
       $result = ApplicationBundle::run('user_registration', $request->all());
       return response()->json($result);
   }
   

Implementation Patterns

Workflow: Domain-Driven Design (DDD) Integration

1. Separation of Concerns

   • Place business logic in dedicated handlers (e.g., UserRegistrationHandler).
   • Use the bundle to orchestrate calls between handlers.

2. Dependency Injection Bind handlers to the container in ApplicationBundleServiceProvider:

   $this->app->bind('user_registration', function ($app) {
       return new UserRegistrationHandler(
           $app->make(UserRepository::class),
           $app->make(EmailService::class)
       );
   });
   

3. Middleware Integration Use the bundle to validate requests before processing:

   public function handle($request, Closure $next) {
       $validated = ApplicationBundle::validate('user_registration', $request->all());
       if ($validated) {
           return $next($request);
       }
       return response()->json(['error' => 'Validation failed'], 422);
   }
   

Integration Tips

• Laravel Events: Dispatch events after running handlers:

  ApplicationBundle::run('user_registration', $data);
  event(new UserRegistered($data));
  

• Logging: Wrap handler execution in a try-catch to log errors:

  try {
      ApplicationBundle::run('order_processing', $orderData);
  } catch (\Exception $e) {
      Log::error("Order processing failed: " . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Handler Registration Overrides

   • If a handler is registered twice (e.g., in config and via bind()), the last registration wins. Use extend() for merging:

     $this->app->extend('user_registration', function ($handler) {
         return new ExtendedUserRegistrationHandler($handler);
     });
     

2. Circular Dependencies

   • Avoid circular calls between handlers (e.g., HandlerA calls HandlerB, which calls HandlerA). Use events or queues instead.

3. Configuration Caching

   • Clear config cache after modifying config/application.php:

     php artisan config:clear
     

Debugging

• Handler Not Found Check if the handler is properly registered in config/application.php or bound in the service provider. Enable debug mode:

  ApplicationBundle::setDebug(true); // Logs unresolved handlers
  

• Method Invocation Errors Ensure the method key in the config matches the handler’s public method name (case-sensitive).

Extension Points

1. Custom Validators Extend validation logic by creating a validator class and binding it:

   $this->app->bind('user_registration_validator', function () {
       return new CustomUserValidator();
   });
   

2. Pre/Post Hooks Use Laravel’s app facade to tap into handler execution:

   $this->app->afterResolving('user_registration', function ($handler) {
       // Run code after handler is resolved
   });
   

3. Testing Mock the bundle in tests:

   $this->app->instance('user_registration', Mockery::mock(UserRegistrationHandler::class));