Advanced Error Handling 🚨

<?php
// An EXCEPTION is an object that says "something went wrong" and stops normal
// flow until some code 'catches' it. You guard risky code inside a try block.

function divide(int $a, int $b): float
{
    // Dividing by zero throws a DivisionByZeroError in PHP — we re-flag it as
    // an Exception so the caller can catch it like any other failure.
    if ($b === 0) {
        throw new InvalidArgumentException("Cannot divide by zero");
    }
    return $a / $b;
}

foreach ([[10, 2], [7, 0]] as [$a, $b]) {
    try {
        // 'try' = "attempt this; it might throw".
        $result = divide($a, $b);
        echo "$a / $b = $result\n";
    } catch (InvalidArgumentException $e) {
        // 'catch' runs ONLY if a matching exception was thrown.
        echo "Skipped: " . $e->getMessage() . "\n";
    } finally {
        // 'finally' ALWAYS runs — success or failure. Perfect for cleanup.
        echo "  (done with $a / $b)\n";
    }
}
?>

10 / 2 = 5
  (done with 10 / 2)
Skipped: Cannot divide by zero
  (done with 7 / 0)

<?php
// PHP's hierarchy. Everything throwable implements the Throwable interface:
//   Throwable
//   ├── Error      — engine-level faults: TypeError, DivisionByZeroError, ...
//   └── Exception  — the kind YOUR code should throw and catch
//       ├── RuntimeException, InvalidArgumentException, LogicException, ...

function parseAge(string $input): int
{
    if (!is_numeric($input)) {
        // You throw an Exception on purpose to signal a recoverable problem.
        throw new InvalidArgumentException("'$input' is not a number");
    }
    return (int) $input;
}

// Catch the MOST SPECIFIC type first, then fall back to broader ones.
foreach (["42", "oops"] as $value) {
    try {
        echo "Age: " . parseAge($value) . "\n";
    } catch (InvalidArgumentException $e) {
        // Specific catch: we know exactly what kind of failure this is.
        echo "Bad input: " . $e->getMessage() . "\n";
    } catch (Throwable $e) {
        // Safety net: catches anything — Error OR Exception — we didn't expect.
        echo "Unexpected: " . $e->getMessage() . "\n";
    }
}

// You can even catch an engine Error. Here a TypeError is thrown because a
// string can't be used where an int is required.
try {
    echo (10 / 0);                 // DivisionByZeroError
} catch (DivisionByZeroError $e) {
    echo "Math error: " . $e->getMessage() . "\n";
}
?>

Age: 42
Bad input: 'oops' is not a number
Math error: Division by zero

<?php
// A CUSTOM EXCEPTION is just a class that 'extends Exception'. It can carry
// extra data (here an HTTP status code) so each error knows how to be handled.
class AppException extends Exception
{
    public function __construct(string $message, private int $statusCode = 500)
    {
        parent::__construct($message);   // let Exception store the message
    }

    public function getStatusCode(): int
    {
        return $this->statusCode;
    }
}

// Child classes set their own status code — granular, type-safe errors.
class ValidationException extends AppException
{
    public function __construct(public string $field, string $message)
    {
        parent::__construct($message, 422);   // 422 = Unprocessable Entity
    }
}

class NotFoundException extends AppException
{
    public function __construct(string $resource, int $id)
    {
        parent::__construct("$resource #$id not found", 404);
    }
}

$samples = [
    new ValidationException("email", "Invalid email format"),
    new NotFoundException("User", 42),
];

echo "Exception            | Code | Message\n";
echo "---------------------+------+----------------------------\n";
foreach ($samples as $e) {
    // get_class() = the class name; getStatusCode() = our custom data.
    printf("%-20s | %-4d | %s\n", get_class($e), $e->getStatusCode(), $e->getMessage());
}
?>

Exception            | Code | Message
---------------------+------+----------------------------
ValidationException  | 422  | Invalid email format
NotFoundException    | 404  | User #42 not found

<?php
// Exception chaining keeps the ORIGINAL cause attached while you re-throw a
// friendlier, higher-level exception. Pass the cause as the 3rd argument.
class ConfigException extends Exception {}

function loadConfig(string $path): array
{
    try {
        // This low-level call fails with a built-in exception.
        throw new RuntimeException("file '$path' not readable");
    } catch (RuntimeException $cause) {
        // 0 = default code; $cause = the previous exception we are wrapping.
        throw new ConfigException("Could not load config", 0, $cause);
    }
}

try {
    loadConfig("/etc/app.ini");
} catch (ConfigException $e) {
    echo "Top:   " . $e->getMessage() . "\n";
    // getPrevious() walks back to the original root cause.
    echo "Cause: " . $e->getPrevious()->getMessage() . "\n";
}
?>

Top:   Could not load config
Cause: file '/etc/app.ini' not readable

<?php
// In DEVELOPMENT you want every detail on screen; in PRODUCTION you must hide
// it from users (it leaks paths, queries, secrets) and log it instead.
$isProduction = true;                          // flip to false on your machine

if ($isProduction) {
    ini_set("display_errors", "0");            // never show errors to visitors
    error_reporting(E_ALL);                    // but still REPORT them (to logs)
} else {
    ini_set("display_errors", "1");            // show everything while coding
    error_reporting(E_ALL);
}

// set_error_handler(): turn old-style PHP warnings/notices into exceptions so
// they flow through the same try/catch path as everything else.
set_error_handler(function (int $level, string $message, string $file, int $line) {
    throw new ErrorException($message, 0, $level, $file, $line);
});

// set_exception_handler(): the LAST line of defence — runs for any exception
// that nothing else caught, just before the script would die.
set_exception_handler(function (Throwable $e) {
    // error_log() writes to the server log — the right place for the details.
    error_log("UNCAUGHT: " . $e->getMessage() . " in " . $e->getFile() . ":" . $e->getLine());
    http_response_code(500);
    // Users only ever see a safe, generic message.
    echo "Sorry, something went wrong. Please try again later.\n";
});

echo "Handlers registered.\n";

// A leftover undefined variable would normally be a notice; our error handler
// now turns it into an exception we can catch.
try {
    $total = $price * 2;                       // $price was never defined
} catch (ErrorException $e) {
    echo "Caught a converted warning: " . $e->getMessage() . "\n";
}
?>

Handlers registered.
Caught a converted warning: Undefined variable $price

<?php
// 🎯 YOUR TURN — finish the try/catch so the bad call is handled gracefully.

function withdraw(int $balance, int $amount): int
{
    if ($amount > $balance) {
        // 1) throw an exception when there isn't enough money
        throw ___("Insufficient funds");   // 👉 use  new RuntimeException
    }
    return $balance - $amount;
}

foreach ([50, 200] as $amount) {
    // 2) wrap the risky call so a thrown exception doesn't crash the loop
    ___ {                                  // 👉 the keyword is  try
        echo "New balance: " . withdraw(100, $amount) . "\n";
    } catch (RuntimeException $e) {        // 3) (already done) catch it
        echo "Declined: " . $e->getMessage() . "\n";
    }
}

// ✅ Expected output:
//    New balance: 50
//    Declined: Insufficient funds
?>

New balance: 50
Declined: Insufficient funds

<?php
// 🎯 YOUR TURN — build a custom exception and throw it.

// 1) make PaymentException a real exception type
class PaymentException ___ Exception {}   // 👉 the keyword is  extends

function charge(int $cents): string
{
    if ($cents <= 0) {
        // 2) throw your new exception with a message
        throw new ___("Amount must be positive");   // 👉 PaymentException
    }
    return "Charged $cents cents";
}

try {
    echo charge(-5) . "\n";
} catch (PaymentException $e) {
    echo "Payment failed: " . $e->getMessage() . "\n";
}

// ✅ Expected output:
//    Payment failed: Amount must be positive
?>

Payment failed: Amount must be positive