Engineering Manager

👋🏽 Smaïne Milianni

      @SmaineDev

      smaine-milianni.medium

      ismail1432

      ismail1432/conferences

✍🏿

 

🍿

Futur Responsable Com' de la conf

@SmaineDev

An \Exception?

🧨 Occurs during program execution, interrupts the normal execution flow

🧩 Can be triggered by the code itself, the system, or an external resource (DB, file, API…)

👻 Can happen at any point in the code, often where it's least expected 😭

💥 Without proper handling, it causes the program to crash or behave unpredictably

@SmaineDev

🙌 Since PHP 5 Object-oriented error handling

💡 Introduction of the \Exception class, the try/catch/ finally mechanism

PHP 7️⃣ unifies error handling further with \Throwable

🪆Exceptions are objects : they carry a message, a code, a stack trace…

🕸️ You can extend the base Exception class to create your own custom exceptions

🎣Exceptions can be nested catch one, throw another with more context

💄Follows OOP principles : inheritance, polymorphism, and encapsulation apply to exceptions too

The PHP Way 🐘

@SmaineDev

Don't Let Errors

Run the Show 🎬

🛣️ Altering the workflow of a program

⚠️ Without exceptions : an error can fail silently or crash the program abruptly

👮‍♂️ With exceptions : you intercept the error and decide how to react

🌊You can propagate the exception, log it, display a user-friendly message, or implement a fallback

🦾Makes your program more robust & resilient

@SmaineDev

  🖐️ A Family Story

@SmaineDev

\Exception

Base class for all users exceptions

\Error

Base class for all internal error

interface \Throwable

@SmaineDev

interface Throwable
  |- Error implements Throwable
      |- ArithmeticError extends Error
          |- DivisionByZeroError extends ArithmeticError
      |- AssertionError extends Error
      |- ParseError extends Error
      |- TypeError extends Error
          |- ArgumentCountError extends TypeError
  |- Exception implements Throwable
      |- ClosedGeneratorException extends Exception
      |- DOMException extends Exception
      |- ErrorException extends Exception
      |- IntlException extends Exception
      |- LogicException extends Exception
          |- BadFunctionCallException extends LogicException
              |- BadMethodCallException extends BadFunctionCallException
          |- DomainException extends LogicException
          |- InvalidArgumentException extends LogicException
          |- LengthException extends LogicException
          |- OutOfRangeException extends LogicException
      |- PharException extends Exception
      |- ReflectionException extends Exception
      |- RuntimeException extends Exception
          |- OutOfBoundsException extends RuntimeException
          |- OverflowException extends RuntimeException
          |- PDOException extends RuntimeException
          |- RangeException extends RuntimeException
          |- UnderflowException extends RuntimeException
          |- UnexpectedValueException extends RuntimeException

@SmaineDev

<?php
interface Throwable extends Stringable
{
    public function getMessage(): string;

    /** @return int */
    public function getCode();
    public function getFile(): string;
    public function getLine(): int;
    public function getTrace(): array;
    public function getPrevious(): ?Throwable;
    public function getTraceAsString(): string;
}

class Exception implements Throwable
{
    final private function __clone() {}
    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null) {}
    public function __wakeup() {}
    final public function getMessage(): string {}
    /** @return int */
    final public function getCode() {}
    final public function getFile(): string {}
    final public function getLine(): int {}
    final public function getTrace(): array {}
    final public function getPrevious(): ?Throwable {}
    final public function getTraceAsString(): string {}
    public function __toString(): string {}
}

class Error implements Throwable
{
   // ...
}

@SmaineDev

Everything fails all the time🔥

@SmaineDev

@SmaineDev

🔉 The Bubbling Effect

🃏 An error code is assigned to the exception

 

🧑🏿‍🦯‍➡️The exception travels up the call stack frame by frame

 

🛑 Each function/method in the stack is exited immediately

 

☄️ If no catch is found along the way, the exception reaches the top of the stack

@SmaineDev

Catch, Inspect,  Re-throw

🎣 A catch block intercepts the exception and gives you full access to it ($e)

📝 You can log it, transform it, or wrap it into a new exception

🪃 Re-throwing and sends it back up the stack

🏁 A finally block is always executed

@SmaineDev

try { ... }

 

catch(e) { ... }

 

<?= code/>

 

finally { ... }

 

Workflow

@SmaineDev

What Should I Do

if I met an \Exception?

@SmaineDev

Log

Throw

Catch

@SmaineDev

Application

Business Logic 📖

Persistence 💾

Application - Domain - Infrastructure

User Side 🙋

Domain

Infrastructure

@SmaineDev

High-level layer 🕹️

Application - Domain - Infrastructure

Low-level layer 🦄

Catch

Log ?

Handle Response

Catch

Log

Throw

@SmaineDev

<?php
namespace App\Infrastructure;
class StripeProvider
{
    // Service to update a user in Stripe via API (Low-level layer)
    public function updateUser($id)
    {
        try{
            $response = $this->stripeHttpClient->put($id, $data);    
        } catch (\Exception $e) {
            return false;
        }
    }
}

namespace App\Domain;
class UpdateAccountHandler
{
    // Handler to update a user in Stripe via API (Low-level layer)
    public function update(UserId $id, array $data)
    {
        // tambouille 🍲
        
        $result = $stripeProvider->updateUser($id, $data);
        
         // tambouille 🍲
         
        return $result;
    }
}
<?php
namespace App\Application;
#[AsCommand(name: 'app:xls:update_user')]
class UpdateAccountCommand
{
    // Custom Command Feature Update User acount from XLS (High level layer)
    public function execute($id, $data)
    {
        $result = $this->updateAccountHandler->update($id, $data);
        
        if(!$result) {
          // ?
        }
    }
}
class UpdateAccountAction
{
    #[Route('/users/{id}', name: 'user_update')]
    public function __invoke($id, $data)
    {
        $result = $this->updateAccountHandler->update($id, $data);
        
        if(!$result) {
          // ?
        }
       
        return $this->render('account.html.twig');
    }
}

<?php
class StripeProvider
{
    public function updateUser($id)
    {
        try{
            $response = $this->stripeHttpClient->put($id, $data);    
        } catch (\Exception $e) {
            // Yolo Mode, No log, No traces 🕳️
            return false; 😱
        }
    }
}
class UpdateAccountAction
{
    #[Route('/users/{id}', name: 'user_update')]
    public function __invoke($id, $data)
    {
       try {
          $result = $this->updateAccountHandler->update($id, $data);
        } catch (\Exception $e) {
          // Already catched, no Exception 😭😭😭
        }
        if(!$result) {
          // ?
        }
        return $this->render('account.html.twig');
    }
}
    
<?php
class StripeProvider
{
    public function updateUser($id)
    {
        try{
            $response = $this->httpClient->put($id, $data);
        } catch (ClientException $e){
            $statusCode = $e->getResponse()->getStatusCode();
            if(400 === $statusCode) {
                $this->logger('Validation errors . $e->message');
                throw new ValidationException($e);
            }
            if(404 === $statusCode) {
                $this->logger('User not found errors . $e->message');
                throw new NotFoundHttpException($e);
            }
        } catch (\Exception $e) {
            // 💡 Add context to thanks yourself when you will debug
            $this->logger('Unable to update User id: .$id');
            // Rethrow to not silent and hide the problem
            throw new $e; 
        }
    }
 }

Improvements 💅

class UpdateAccountAction
{
    public function __invoke($id, $data)
    {
       try {
          $result = $this->updateAccountHandler->update($id, $data);
        } catch (ValidationException | NotFoundHttpException $e){
            $errors = "User cannot be update";
        }
        
        return $this->render('account.html.twig', ['errors' => $errors ?? null]);
    }
}
class UpdateAccountCommand
{
    public function __invoke($id, $data)
    {
      try {
        $this->updateAccountHandler->update($id, $data);
        // ...
        $io->success('blabla');
        return Command::SUCCESS;
        
      } catch (ValidationException | NotFoundHttpException $e) {
        $io->error('User cannot be update');
        return Command::FAILURE;
     }
    }
}
class UpdateAccountAction
{
    public function __invoke($id, $data)
    {
       try {
          $result = $this->updateAccountHandler->update($id, $data);
        } catch (ValidationException | NotFoundHttpException $e){
            $errors = "User cannot be update";
        }
        
        return $this->render('account.html.twig', ['errors' => $errors ?? null]);
    }
}
class UpdateAccountCommand
{
    public function __invoke($id, $data)
    {
      try {
        $this->updateAccountHandler->update($id, $data);
        // ...
        $io->success('blabla');
        return Command::SUCCESS;
        
      } catch (ValidationException | NotFoundHttpException $e) {
        $io->error('User cannot be update');
        return Command::FAILURE;
     }
    }
}
<?php
class UpdateAccountCommand
{
  public function __invoke(string $csvFilePath)
  {
      $rows = $this->parseCsv($csvFilePath);
      /** @var Row $row */
      foreach ($rows as $row) {
          try {
              $this->updateAccountHandler->update($id, $data);
              $io->success("User {$id} updated successfully");

          } catch (ValidationException | NotFoundHttpException $e) {
              $io->error("User {$row->id} failed: " . $e->getMessage());
              // Skip Exception.

          } catch (FileException $e) {
              $io->error('Unable to process the file');
              // File corrupt, fail fast.
              return Command::FAILURE;
          }
      }

      $io->success('CSV import finished');
      
      return Command::SUCCESS;
  }
}
<?php
class UpdateAccountCommand
{
  public function __invoke(string $csvFilePath)
  {
      $rows = $this->parseCsv($csvFilePath);
      /** @var Row $row */
      foreach ($rows as $row) {
          try {
              $this->updateAccountHandler->update($id, $data);
              $io->success("User {$id} updated successfully");

          } catch (ValidationException | NotFoundHttpException $e) {
              $io->error("User {$row->id} failed: " . $e->getMessage());
              // Skip Exception.

          } catch (FileException $e) {
              $io->error('Unable to process the file');
              // File corrupt, fail fast.
              return Command::FAILURE;
          }
      }

      $io->success('CSV import finished');
      
      return Command::SUCCESS;
  }
}

🤕 Common Mistakes

Catching Exception too broadly

Swallowing the exception silently

Using exceptions for normal flow control

Not logging / losing the stack trace

Throwing a generic exception instead of a domain exception

Re-throwing for no reason

Generic 

or

Custom

The \Exception that proves the Rules

Custom \Exception use cases

🍈 You need to handle a specific scenario

🍓 You need to give your error an "identity"

🍍 You need to add extra information to the exception

🥭 You need to catch it specifically without catching unrelated exceptions

🍏 You need to make your code self-documenting

@SmaineDev

<?php

// ❌ Bad
throw new Exception("User not found");
throw new Exception("Invalid email");

// ✅ Good — custom exception
throw new UserNotFoundException("User {$id} not found");
throw new InvalidEmailException("Invalid email: {$email}");

// ✅ Even better — static named constructors
throw UserNotFoundException::byId($id);
throw UserNotFoundException::byName($name);
throw InvalidEmailException::alreadyExists($email);

@SmaineDev

<?php

class UserNotFoundException extends RuntimeException
{
    public static function byId(int $id): self
    {
        return new self("User with id '{$id}' was not found");
    }

    public static function byName(string $name): self
    {
        return new self("User with name '{$name}' was not found");
    }
}

class InvalidEmailException extends RuntimeException
{
    public static function alreadyExists(string $email): self
    {
        return new self("Email '{$email}' is already taken");
    }

    public static function invalidFormat(string $email): self
    {
        return new self("Email '{$email}' has an invalid format");
    }
}

Senzu Bean 🫘

🛑 Don't catch to return null/false in low-level layer

🎣 Catch at the right time, you favorite framework handles well the \Exception

📖 Use Explicit message and Explicit naming

🪃Throw good \Exceptions (RuntimeException...)

⚠️ An \Exception is caught once

✅ Test the \Exceptions and the worst case scenario

💡Avoid Generic \Exception and use Custom/Domain exception

@SmaineDev

Intercepting Exceptions in Symfony

👂🏼 Listen kernel.exception Event via an Event Subscriber or Event Listener (attribute #[AsEventListener])

🔫 Fired automatically when an unhandled exception reaches the kernel

🎁 Gives you access to the full exception object + the original request

📩 You can return a custom Response and stop propagation

⚖️ Symfony's own ErrorListener listens too, mind your priority to run before it

@SmaineDev

🏷️ #[WithHttpStatus] & #[WithLogLevel]

use Psr\Log\LogLevel;
use Symfony\Component\HttpKernel\Attribute\WithHttpStatus;
use Symfony\Component\HttpKernel\Attribute\WithLogLevel;

#[WithHttpStatus(409)]
class OutOfStockException extends \DomainException {}

#[WithHttpStatus(429, headers: ['Retry-After' => 60])]
class RateLimitExceededException extends \RuntimeException {}

#[WithLogLevel(LogLevel::WARNING)]
class PaymentFailedException extends \RuntimeException {}

💎 Your Domain exceptions declare their own status & severity, no listener, no mapping (Symfony 6.3+)

@SmaineDev

 🔄 Transforming Exceptions in Symfony

🎨 Override error/*.html.twig templates per HTTP status code (error/404.html.twig, error/500.html.twig)

 

⚙️ Use a custom ErrorController to fully control the response format (json, html, csv…)

 

🔥 Decorate the ProblemNormalizer to reshape the JSON error payload (RFC 7807)

@SmaineDev

📖 Logging Exceptions in Symfony

MonologBundle FTW🔥

🖊️ Exceptions are automatically logged at the right severity level

🎚️ Tune the severity per exception with #[WithLogLevel]

🪛 Configurable channels (app, payment, api…) to separate concerns

📩 Send logs to files, Slack, Sentry, Datadog… via handlers

🔋 Add context via Processors

@SmaineDev

📬 And in Async? Exceptions in Messenger

🚫 No HTTP response in a worker : the exception drives the retry

# config/packages/messenger.yaml
framework:
    messenger:
        failure_transport: failed
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                retry_strategy:
                    max_retries: 3
                    delay: 1000
                    multiplier: 2   # 1s, 2s, 4s… exponential backoff
// don't retry what can never succeed 🧱
throw new UnrecoverableMessageHandlingException('Order already refunded');

🔁 Transient error (timeout, deadlock…)? Retry with backoff

⚰️ Permanent error? Fail fast => straight to the failed transport

@SmaineDev

The API Platform Way 

Your API speaks HTTP… your \Exceptions should too 📡

@SmaineDev

👻 Errors Out of the Box 🎁

🚨Uncaught \Exception is turned into a structured HTTP error response

🗣️Content negotiation: errors follow the requested format (hydra/json-ld..)

🧱Since API Platform 3.2 : errors are ApiResources themselves!

📜RFC 7807 Problem Details (application/problem+json) by default

Map \Exceptions

to Status Codes

# config/packages/api_platform.yaml
api_platform:
    defaults:
        rfc_7807_compliant_errors: true

    exception_to_status:
        # built-in exceptions
        Symfony\Component\Serializer\Exception\ExceptionInterface: 400
        ApiPlatform\Exception\InvalidArgumentException: 400

        # your Domain exceptions 💎
        App\Exception\ProductNotFoundException: 404
        App\Exception\OutOfStockException: 409

🪄 Throw your Domain \Exception, API Platform picks the right status code

@SmaineDev

🎯 …or per Resource & Operation

#[ApiResource(
    exceptionToStatus: [
        ProductNotFoundException::class => 404,
        OutOfStockException::class => 409,
    ],
    operations: [
        new Post(
            processor: PlaceOrderProcessor::class,
            // operation level wins over resource level 🥇
            exceptionToStatus: [
                PaymentFailedException::class => 402,
            ],
        ),
    ],
)]
class Order {}

🎚️ Precedence : Operation > Resource > Global config

@SmaineDev

Validation Already Handled ✅

⚙️ ValidationException → 422 Unprocessable Entity, automatically

🧾 One entry per violation : perfect for form mapping on the client side

@SmaineDev

RFC 7807 (Problem Details)

API Platform's additions based on SF validator

💎 Your Own Error Resource

use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ErrorResource]
class OutOfStockError extends \Exception implements ProblemExceptionInterface
{
    public function getType(): string { return '/errors/out-of-stock'; }
    public function getTitle(): ?string { return 'Out of stock'; }
    public function getStatus(): ?int { return 409; }
    public function getDetail(): ?string { return $this->getMessage(); }
    public function getInstance(): ?string { return null; }
}

// in your Provider / Processor
throw new OutOfStockError('Product 42 is out of stock 😢');

🪆 The \Exception is the API resource : full control over the error payload

@SmaineDev

🎛️ Customize the Error Provider

use ApiPlatform\State\ApiResource\Error;

#[AsAlias('api_platform.state.error_provider')]
#[AsTaggedItem('api_platform.state.error_provider')]
final class ErrorProvider implements ProviderInterface
{
    public function provide(
     Operation $operation,
     array $uriVariables = [], 
     array $context = []): object
    {
        $exception = $context['request']->attributes->get('exception');
        $status = $operation->getStatus() ?? 500;

        $error = Error::createFromException($exception, $status);

        if ($status >= 500) {
            $error->setDetail('Something went wrong');
        }

        return $error;
    }
}

🧰 One place to translate, enrich or redact every error of your API

@SmaineDev

🏆 Good Practices in API Platform

🎯 Throw Domain \Exceptions, map them with exceptionToStatus

🤫 Never leak internals : hide messages & stack traces of 5xx

🧾 Let the Validator produce the 422s, don't reinvent it

🔉 Keep Monolog/Sentry in the loop : kernel.exception still fires

✅ Test status codes and error payloads with ApiTestCase

📚 Document your errors in OpenAPI so consumers know what to expect

@SmaineDev

Any Question before I Quit?