PHP Exception Handling

An Exception in PHP is an object that represents an error or unexpected condition. When thrown, it interrupts normal execution flow and transfers control to the nearest matching catch block, or to the uncaught exception handler if not caught.

class InsufficientFundsException extends RuntimeException {}

function withdraw(float $amount, float $balance): float {
    if ($amount > $balance) {
        throw new InsufficientFundsException(
            "Cannot withdraw $amount; balance is $balance",
            code: 1001
        );
    }
    return $balance - $amount;
}

try {
    $newBalance = withdraw(500, 100);
} catch (InsufficientFundsException $e) {
    echo $e->getMessage(); // "Cannot withdraw 500; balance is 100"
    echo $e->getCode();    // 1001
}

The Throwable hierarchy:

Throwable
├── Error          (engine-level: TypeError, ParseError, ArithmeticError, etc.)
└── Exception      (application-level)
    ├── LogicException        (programming errors detectable before runtime)
    │   ├── InvalidArgumentException
    │   ├── OutOfRangeException
    │   └── BadMethodCallException
    └── RuntimeException      (errors detectable only at runtime)
        ├── OutOfBoundsException
        ├── UnexpectedValueException
        └── OverflowException

PHP 8.x additions:

• ValueError (PHP 8.0) — thrown when a function argument is of the right type but an invalid value
• throw as an expression — can be used in match arms, null coalescing, and arrow functions

PHP handles exceptions using try/catch/finally blocks. Code that might throw is placed in try; exception handlers in catch; cleanup code in finally.

Basic pattern:

try {
    $result = riskyOperation();
} catch (SpecificException $e) {
    // handle specific case
    logError($e);
} catch (AnotherException | YetAnotherException $e) {
    // catch multiple types in one block (PHP 8.0+)
    notifyAdmin($e);
} catch (\Throwable $e) {
    // catch any Error or Exception — use as a last resort
    throw $e; // re-throw rather than swallowing
} finally {
    // runs regardless of whether an exception was thrown or caught
    cleanup();
}

Catching Throwable vs Exception:

• Exception — catches only application-level exceptions
• Throwable — catches both Exception and Error (PHP engine errors like TypeError, Error, etc.)
• In most application code, catching Exception is appropriate. Use Throwable in framework-level code or global handlers.

Re-throwing with context (exception chaining):

try {
    $pdo->query($sql);
} catch (PDOException $e) {
    throw new RepositoryException('Failed to fetch user', previous: $e);
}

The getPrevious() method retrieves the original cause, preserving the full chain for debugging.

Global exception handler:

set_exception_handler(function (\Throwable $e): void {
    error_log($e->getMessage());
    http_response_code(500);
    echo 'An error occurred.';
});

The throw keyword raises an exception, immediately interrupting the current execution path and transferring control to the nearest enclosing catch block.

function divide(int $a, int $b): float {
    if ($b === 0) {
        throw new DivisionByZeroError('Cannot divide by zero');
    }
    return $a / $b;
}

PHP 8.0: throw as an expression Before PHP 8.0, throw was a statement and could only appear on its own line. PHP 8.0 made throw an expression, enabling its use in:

• Null coalescing:

  $user = findUser($id) ?? throw new NotFoundException("User $id not found");
  

• Ternary:

  $value = $validated ? $input : throw new InvalidArgumentException('Invalid');
  

• Match arms:

  $status = match($code) {
    200 => 'OK',
    404 => 'Not Found',
    default => throw new UnexpectedValueException("Unknown code: $code"),
  };
  

• Arrow functions:

  $mustExist = fn($v) => $v ?? throw new RuntimeException('Required');
  

Re-throwing:

catch (PDOException $e) {
    throw new RepositoryException('DB error', previous: $e); // wraps original
}

Interview note: Know when to throw vs return a special value. throw is appropriate for exceptional conditions (programming errors, resource unavailability). Returning null or false is appropriate when "no result" is a normal, expected outcome.

Create a custom exception by extending Exception or a more specific subclass. This allows callers to catch your specific exception type separately from generic ones.

// Define custom exceptions
class UserNotFoundException extends RuntimeException {}

class ValidationException extends InvalidArgumentException {
    /** @param array $errors */
    public function __construct(
        private array $errors,
        string $message = 'Validation failed',
        int $code = 422,
        ?\Throwable $previous = null,
    ) {
        parent::__construct($message, $code, $previous);
    }

    /** @return array */
    public function getErrors(): array {
        return $this->errors;
    }
}

Usage:

function findUser(int $id): User {
    $user = $this->repository->find($id);
    if (!$user) {
        throw new UserNotFoundException("User with ID $id does not exist", 404);
    }
    return $user;
}

try {
    $user = findUser(99);
} catch (UserNotFoundException $e) {
    http_response_code($e->getCode());
    echo $e->getMessage();
}

// ValidationException with structured error data
try {
    validate($input);
} catch (ValidationException $e) {
    return response()->json(['errors' => $e->getErrors()], 422);
}

Best practices:

• Extend the most specific standard exception that fits (e.g., InvalidArgumentException, RuntimeException, OverflowException)
• Use custom exception classes rather than passing error codes in generic exceptions — callers can catch by type
• Add domain-specific methods (like getErrors()) to carry structured failure data

Both Exception and ErrorException extend the Exception base class and implement Throwable, but they serve different purposes:

Exception The base class for all application-level exceptions in PHP. Used for expected, recoverable error conditions in your own code.

throw new RuntimeException('File not found');
throw new InvalidArgumentException('Age must be positive');

ErrorException A bridge class that wraps PHP's native error system (warnings, notices, etc.) as catchable exceptions. It adds an $severity parameter mapping to the PHP error level constant.

// Convert PHP warnings/notices to exceptions
set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline): bool {
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
    $result = file_get_contents('/nonexistent/file.txt'); // triggers E_WARNING
} catch (ErrorException $e) {
    echo "Caught: " . $e->getMessage();
    echo "Severity: " . $e->getSeverity(); // E_WARNING = 2
}

Key difference:

PHP 8.x context: Many PHP errors that previously only generated E_WARNING or E_NOTICE now throw actual Error subclasses (TypeError, ValueError). The need for ErrorException wrappers is diminishing, but the pattern is still common in legacy codebases and libraries.