Excepciones Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (if still functional):

   composer require boson/excepciones-bundle
   

   Register the bundle in config/app.php under extra.bundles (Symfony-style, though Laravel compatibility is untested due to age).

2. First Use Case Import exceptions in your Laravel controller/service:

   use Boson\ExcepcionesBundle\Exception\BosonException;
   use Boson\ExcepcionesBundle\Exception\ValidationException;
   

   Throw them like native Laravel exceptions:

   throw new BosonException('Custom error message', 400);
   

3. Where to Look First

   • Check Resources/doc/index.rst for original Symfony documentation (may require translation).
   • Inspect src/Exception/ for available exception classes (e.g., BosonException, ValidationException).
   • Override default behavior in config/excepciones.php (if present).

Implementation Patterns

Workflow Integration

1. Consistent Exception Handling Replace generic throw new \Exception() with bundle exceptions for domain-specific errors:

   // Before
   throw new \Exception('Invalid input', 422);
   
   // After
   throw new ValidationException('Invalid input', ['field' => 'required']);
   

2. Global Exception Handling Extend Laravel’s App\Exceptions\Handler to customize responses:

   public function render($request, \Throwable $exception)
   {
       if ($exception instanceof BosonException) {
           return response()->json([
               'error' => $exception->getMessage(),
               'code' => $exception->getCode(),
           ], $exception->getCode());
       }
       return parent::render($request, $exception);
   }
   

3. Validation-Specific Patterns Use ValidationException for API validation failures:

   throw new ValidationException('Validation failed', [
       'errors' => ['email' => ['The email is invalid.']]
   ]);
   

4. Service Layer Abstraction Create a ExceptionService to centralize exception logic:

   class ExceptionService {
       public function throwValidationError(array $errors) {
           throw new ValidationException('Validation failed', ['errors' => $errors]);
       }
   }
   

Laravel-Specific Tips

• Leverage Laravel’s HTTP Responses Combine with response()->json() or abort() for consistency:

  abort(new BosonException('Not found', 404));
  

• Localization Extend Laravel’s localization system to support exception messages:

  // lang/en/exceptions.php
  return [
      'boson.validation' => 'Validation failed: :errors',
  ];
  

Gotchas and Tips

Pitfalls

1. Outdated Compatibility

   • Symfony 2.x Dependency: The bundle targets Symfony 2.x. Laravel 5.5+ may require polyfills or manual adaptation (e.g., Symfony\Component\HttpKernel\Exception\HttpException).
   • No Laravel-Specific Features: Expect no built-in support for Laravel’s Validator, FormRequest, or ApiResource.

2. Missing Configuration

   • The bundle lacks a config/excepciones.php file. Assume defaults or create your own:

     // config/excepciones.php
     return [
         'default_status_code' => 500,
         'validation_status_code' => 422,
     ];
     

3. No Exception Listener Unlike Symfony, Laravel doesn’t auto-register exception listeners. Manually bind them in AppServiceProvider:

   public function boot() {
       $this->app->make(\Boson\ExcepcionesBundle\DependencyInjection\Compiler\ExceptionListenerPass::class);
   }
   

4. Deprecated Symfony Components

   • Symfony\Component\HttpKernel\Exception\FlattenException may conflict with Laravel’s Whoops or Debugbar. Exclude via Composer:

     "replace": {
         "symfony/http-kernel": "4.4.*"
     }
     

Debugging

• Exception Hierarchy Use get_class($exception) to debug inheritance:

  if ($exception instanceof \Boson\ExcepcionesBundle\Exception\BosonException) {
      // Handle Boson-specific logic
  }
  

• Stack Trace Analysis Older Symfony exceptions may show unfamiliar stack traces. Filter with:

  $exception->getTraceAsString();
  

Extension Points

1. Custom Exceptions Extend existing exceptions to add Laravel-specific logic:

   namespace App\Exceptions;
   
   use Boson\ExcepcionesBundle\Exception\BosonException;
   
   class AppBosonException extends BosonException {
       public function render($request) {
           return response()->json(['error' => $this->message], $this->code);
       }
   }
   

2. Middleware Integration Create middleware to preemptively catch bundle exceptions:

   public function handle($request, Closure $next) {
       try {
           return $next($request);
       } catch (BosonException $e) {
           return response()->json(['error' => $e->getMessage()], $e->getCode());
       }
   }
   

3. Testing Mock exceptions in PHPUnit:

   $this->expectException(\Boson\ExcepcionesBundle\Exception\ValidationException::class);
   $this->expectExceptionMessage('Validation failed');
   

Performance

• Avoid Overhead: Bundle exceptions are lightweight, but excessive nesting (e.g., throw new CustomException(new BosonException())) may complicate debugging. Prefer flat hierarchies.