PHP Exception Handling Explained — try, catch, finally and Custom Exceptions

<?php

/**
 * Simulates reading a user record from a database.
 * This mirrors what happens in real apps when DB connections are involved.
 */
function fetchUserById(int $userId, bool $simulateFailure = false): array
{
    // Pretend we opened a database connection here
    echo "[DB] Opening connection...\n";

    try {
        if ($simulateFailure) {
            // This is what happens when the DB is unreachable or the query fails
            throw new RuntimeException(
                "Could not fetch user #$userId: connection timed out after 30s"
            );
        }

        // Happy path: query succeeds
        echo "[DB] Query executed successfully.\n";
        return ['id' => $userId, 'name' => 'Alice Nguyen', 'email' => 'alice@example.com'];

    } catch (RuntimeException $exception) {
        // We catch the specific exception type — not just any throwable
        // This lets other exception types bubble up if we don't handle them
        echo "[ERROR] Database error caught: " . $exception->getMessage() . "\n";

        // Return a safe default so the caller doesn't receive null unexpectedly
        return [];

    } finally {
        // This block ALWAYS runs — connection is always cleaned up
        // Even if catch() threw another exception, this still executes
        echo "[DB] Closing connection (finally block ran).\n";
    }
}

// --- Run 1: Normal operation ---
echo "=== Successful Fetch ===\n";
$user = fetchUserById(42, simulateFailure: false);
echo "User data: " . json_encode($user) . "\n\n";

// --- Run 2: Simulated failure ---
echo "=== Failed Fetch ===\n";
$user = fetchUserById(42, simulateFailure: true);
echo "User data: " . json_encode($user) . "\n";

<?php

// ─────────────────────────────────────────────
// EXCEPTION HIERARCHY
// ─────────────────────────────────────────────

/**
 * Base class for ALL payment-related errors in this system.
 * Catching this type handles any payment failure — useful at the controller layer.
 */
class PaymentException extends RuntimeException {}

/**
 * Thrown when the card processor declines the charge.
 * Carries extra context beyond a plain message.
 */
class PaymentDeclinedException extends PaymentException
{
    public function __construct(
        private readonly string $declineReason,
        private readonly string $cardLastFour,
        int $processorCode,
        \Throwable $previous = null   // $previous links to the original low-level error
    ) {
        // Build a human-readable message for logs
        $message = "Card ending $cardLastFour declined: $declineReason (code: $processorCode)";
        parent::__construct($message, $processorCode, $previous);
    }

    public function getDeclineReason(): string { return $this->declineReason; }
    public function getCardLastFour(): string  { return $this->cardLastFour; }
}

/**
 * Thrown when we can't even reach the payment gateway — not a card problem.
 */
class PaymentGatewayUnavailableException extends PaymentException {}

// ─────────────────────────────────────────────
// SERVICE LAYER
// ─────────────────────────────────────────────

class PaymentService
{
    /**
     * Attempts to charge a card. Throws typed exceptions instead of returning
     * ambiguous booleans or null values that callers might forget to check.
     */
    public function chargeCard(string $cardLastFour, float $amountGbp): void
    {
        echo "[PaymentService] Attempting to charge £$amountGbp to card ending $cardLastFour\n";

        // Simulate: card ending 0000 always gets declined
        if ($cardLastFour === '0000') {
            throw new PaymentDeclinedException(
                declineReason: 'Insufficient funds',
                cardLastFour: $cardLastFour,
                processorCode: 1051
            );
        }

        // Simulate: card ending 9999 means gateway is down
        if ($cardLastFour === '9999') {
            throw new PaymentGatewayUnavailableException(
                "Stripe gateway returned HTTP 503 — try again in 30 seconds"
            );
        }

        echo "[PaymentService] Charge successful. Reference: TXN-" . strtoupper(bin2hex(random_bytes(4))) . "\n";
    }
}

// ─────────────────────────────────────────────
// CONTROLLER / CALLER LAYER
// ─────────────────────────────────────────────

function handleCheckout(string $cardLastFour, float $amount): void
{
    $paymentService = new PaymentService();

    try {
        $paymentService->chargeCard($cardLastFour, $amount);
        echo "[Checkout] Payment complete. Sending confirmation email.\n";

    } catch (PaymentDeclinedException $e) {
        // We know specifically WHY it failed — we can give useful feedback
        echo "[Checkout] Card declined: " . $e->getDeclineReason() . "\n";
        echo "[Checkout] Ask customer to try a different card ending in " . $e->getCardLastFour() . "\n";

    } catch (PaymentGatewayUnavailableException $e) {
        // Different failure, different response — queue a retry instead
        echo "[Checkout] Gateway down. Queuing payment for retry: " . $e->getMessage() . "\n";

    } catch (PaymentException $e) {
        // Fallback: catches any PaymentException subclass we didn't anticipate
        echo "[Checkout] Unexpected payment error: " . $e->getMessage() . "\n";
    }
}

echo "=== Test 1: Successful charge ===\n";
handleCheckout('4242', 79.99);

echo "\n=== Test 2: Declined card ===\n";
handleCheckout('0000', 79.99);

echo "\n=== Test 3: Gateway unavailable ===\n";
handleCheckout('9999', 79.99);

<?php

/**
 * A minimal but production-realistic global exception handler setup.
 * In a real app, $logger would be a Monolog instance or similar PSR-3 logger.
 */

// ─────────────────────────────────────────────
// STEP 1: Convert legacy PHP errors into ErrorException
// This means a missing array key or a deprecated function call
// becomes a catchable exception rather than a silent warning.
// ─────────────────────────────────────────────
set_error_handler(function (int $severity, string $message, string $file, int $line): bool {
    // Only convert errors that match the current error_reporting level
    if (!(error_reporting() & $severity)) {
        return false; // Let PHP handle it normally
    }
    throw new ErrorException($message, 0, $severity, $file, $line);
});

// ─────────────────────────────────────────────
// STEP 2: Register a global handler for UNCAUGHT exceptions
// This is your last line of defence — anything not caught elsewhere lands here.
// ─────────────────────────────────────────────
set_exception_handler(function (Throwable $uncaughtException): void {
    // In production: log to file/service, show generic error page
    // In development: show full details
    $isDevelopment = (getenv('APP_ENV') === 'development');

    $logEntry = sprintf(
        "[UNCAUGHT] %s: %s in %s on line %d\nStack trace:\n%s",
        get_class($uncaughtException),
        $uncaughtException->getMessage(),
        $uncaughtException->getFile(),
        $uncaughtException->getLine(),
        $uncaughtException->getTraceAsString()
    );

    // Simulate logging (in real app: $logger->critical($logEntry))
    echo "[LOG] " . $logEntry . "\n";

    if ($isDevelopment) {
        echo "\n[DEV] Exception chained from: ";
        $previous = $uncaughtException->getPrevious();
        echo $previous ? $previous->getMessage() : "(none)";
        echo "\n";
    } else {
        echo "\n[USER] Something went wrong. Our team has been notified.\n";
    }

    // Always exit with a non-zero code so process managers know something failed
    exit(1);
});

// ─────────────────────────────────────────────
// STEP 3: Demonstrate exception chaining in action
// ─────────────────────────────────────────────

function loadConfigFile(string $filePath): array
{
    // In real code this would be: file_get_contents(), json_decode(), etc.
    // We simulate the low-level failure:
    throw new RuntimeException("File not found: $filePath");
}

function bootApplication(): void
{
    try {
        $config = loadConfigFile('/etc/myapp/config.json');
    } catch (RuntimeException $lowLevelError) {
        // Wrap the low-level error in a domain-meaningful exception.
        // Pass $lowLevelError as $previous so the full chain is preserved.
        throw new RuntimeException(
            "Application failed to boot: configuration could not be loaded",
            500,
            $lowLevelError  // <-- this is the chain link
        );
    }
}

// This exception is not caught anywhere — the global handler will catch it
puts_("--- Triggering uncaught exception via exception chain ---\n");

function puts_(string $text): void { echo $text; } // helper for clarity

bootApplication(); // throws → global handler fires

<?php

class UserNotFoundException extends RuntimeException {}
class UserSuspendedException extends RuntimeException {
    public function __construct(string $username, private readonly \DateTimeImmutable $suspendedUntil) {
        parent::__construct("User '$username' is suspended until " . $suspendedUntil->format('Y-m-d'));
    }
    public function getSuspendedUntil(): \DateTimeImmutable { return $this->suspendedUntil; }
}
class DatabaseUnavailableException extends RuntimeException {}
class InvalidCredentialsException extends RuntimeException {}

/**
 * Simulates an authentication service with multiple failure modes.
 */
function authenticateUser(string $username, string $password): string
{
    // Simulate different failure scenarios based on username
    return match($username) {
        'ghost'     => throw new UserNotFoundException("No account found for '$username'"),
        'banned'    => throw new UserSuspendedException('banned', new \DateTimeImmutable('+7 days')),
        'wrongpass' => throw new InvalidCredentialsException("Password incorrect for '$username'"),
        'dbdown'    => throw new DatabaseUnavailableException("Auth DB unreachable"),
        default     => "session_token_" . md5($username . time())
    };
}

/**
 * Handles login — catches what it can recover from, re-throws what it can't.
 */
function handleLoginRequest(string $username, string $password): void
{
    try {
        $sessionToken = authenticateUser($username, $password);
        echo "[Auth] Login successful. Token: $sessionToken\n";

    } catch (UserSuspendedException $e) {
        // We have specific context — we can give a targeted message
        $until = $e->getSuspendedUntil()->format('d M Y');
        echo "[Auth] Account suspended until $until. Contact support@example.com\n";

    } catch (UserNotFoundException | InvalidCredentialsException $e) {
        // PHP 8 union catch: both failures get the same vague response
        // (intentionally vague — never tell attackers which one failed)
        echo "[Auth] Invalid username or password.\n";

    } catch (DatabaseUnavailableException $e) {
        // This layer can't fix a DB outage — re-throw so the framework
        // can log it and show a 503 page
        echo "[Auth] DB unavailable — re-throwing for framework to handle\n";
        throw; // bare throw — preserves original stack trace!
    }
}

$testCases = [
    ['alice',     'correct_password'],
    ['ghost',     'any_password'],
    ['banned',    'any_password'],
    ['wrongpass', 'wrong_password'],
];

foreach ($testCases as [$username, $password]) {
    echo "\n--- Login attempt: $username ---\n";
    try {
        handleLoginRequest($username, $password);
    } catch (\Throwable $e) {
        // Top-level catch for anything re-thrown (like DatabaseUnavailableException)
        echo "[FRAMEWORK] Unhandled error logged and 503 returned: " . $e->getMessage() . "\n";
    }
}

// Test the DB-down case separately
echo "\n--- Login attempt: dbdown ---\n";
try {
    handleLoginRequest('dbdown', 'any');
} catch (\Throwable $e) {
    echo "[FRAMEWORK] Unhandled error logged and 503 returned: " . $e->getMessage() . "\n";
}