try catch w PHP: wyjątki, finally i Throwable

W PHP kod, który może zawieść, umieszczasz w try { ... }, a porażkę obsługujesz w catch (Exception $e) { ... }. Jeśli coś w bloku try rzuci wyjątek, PHP od razu przeskakuje do pasującego catch, a $e->getMessage() mówi, co poszło nie tak. Jeśli nic nie zostanie rzucone, blok catch jest pomijany.

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

try {
    echo divide(10, 4), "\n";
    echo divide(10, 0), "\n";      // exception: the next line never runs
    echo "not printed\n";
} catch (InvalidArgumentException $e) {
    echo 'Error: ', $e->getMessage(), "\n";
}

echo "The script keeps going\n";

Zmień divide(10, 0) na divide(10, 5) i uruchom ponownie: wyjątku nie ma, więc not printed zostaje wypisane, a blok catch jest pomijany. Bez try wyjątek zakończyłby skrypt krytycznym błędem „Uncaught”. Jak rzucać własne wyjątki i pisać klasy wyjątków, opisuje strona o wyjątkach.

Składnia try catch

Pełna forma ma trzy części. Wymagane jest tylko try oraz co najmniej jedno catch albo finally:

try {
    // code that may throw
} catch (SomeException $e) {
    // runs if SomeException (or a subclass) was thrown
} catch (OtherException | ThirdException $e) {
    // runs for either of these types
} finally {
    // always runs, thrown or not
}

Typ w catch decyduje o tym, co jest łapane: sama klasa i każda klasa, która ją rozszerza. Od PHP 8.0 zmienna jest opcjonalna, gdy jej nie potrzebujesz: catch (JsonException) { ... }.

Catch Exception vs Error vs Throwable

Od PHP 7 błędy wykrywane przez samo PHP (wywołanie brakującej metody, zły typ argumentu, dzielenie przez zero) rzucają Error, a nie Exception, a PHP 8 zamieniło wiele dawnych ostrzeżeń w TypeError i ValueError. Obie klasy implementują interfejs Throwable, ale żadna nie rozszerza drugiej, więc catch (Exception $e) nie łapie Error:

Throwable
├── Exception                 (problems a program expects and handles)
│   ├── InvalidArgumentException, RuntimeException, JsonException, ...
└── Error                     (engine errors, usually a bug in the code)
    ├── TypeError
    ├── ValueError
    ├── ArithmeticError
    │   └── DivisionByZeroError
    └── UnhandledMatchError, ...

Uruchom to, aby zobaczyć, który catch obsługuje każdy problem:

<?php
$problems = [
    'divide by zero' => fn () => 10 % 0,
    'wrong type'     => fn () => strlen([]),
    'bad value'      => fn () => str_repeat('x', -1),
    'missing method' => fn () => (new stdClass())->save(),
    'own exception'  => fn () => throw new RuntimeException('disk full'),
];

foreach ($problems as $label => $run) {
    try {
        $run();
    } catch (Exception $e) {
        echo "$label: caught as Exception (", get_class($e), ")\n";
    } catch (Error $e) {
        echo "$label: caught as Error (", get_class($e), ")\n";
    }
}

Co więc łapać?

• catch (SomeSpecificException $e), gdy wiesz, co może pójść źle i co z tym zrobić. To większość kodu.
• catch (Exception $e) dla „czegokolwiek, co biblioteka lub mój kod rzuciły celowo”.
• catch (Throwable $e) na najwyższym poziomie (obsługa żądania, uruchamianie zadań), aby logować każdą porażkę, także błędy samego PHP, i pokazać przyjazny komunikat.

Przechwytywanie kilku typów wyjątków

Napisz kilka bloków catch, aby różne typy obsługiwać na różne sposoby. PHP próbuje ich od góry do dołu i używa pierwszego pasującego, więc konkretny typ musi stać przed swoim rodzicem, inaczej rodzic złapie wszystko pierwszy. Gdy kilka typów traktujesz tak samo, połącz je w jednym catch przez |:

<?php
function loadUser(mixed $id): array
{
    if (!is_int($id)) {
        throw new InvalidArgumentException("ID must be an integer, got " . get_debug_type($id));
    }
    if ($id < 1) {
        throw new DomainException("ID must be positive, got $id");
    }
    if ($id > 100) {
        throw new OutOfBoundsException("No user with ID $id");
    }
    return ['id' => $id, 'name' => 'User ' . $id];
}

foreach ([7, 'abc', -5, 500] as $id) {
    try {
        $user = loadUser($id);
        echo "Found {$user['name']}\n";
    } catch (OutOfBoundsException $e) {
        echo "404: {$e->getMessage()}\n";
    } catch (InvalidArgumentException | DomainException $e) {
        echo '400: ', $e->getMessage(), ' (', get_class($e), ")\n";
    }
}

Wszystkie trzy klasy rozszerzają Exception, więc jedno catch (Exception $e) też by je złapało, ale wtedy kod nie mógłby już odpowiedzieć 404 dla jednej i 400 dla pozostałych.

finally: kod, który zawsze się wykonuje

Blok finally wykonuje się po try i catch bez względu na to, jak się zakończyły: normalnie, ze złapanym wyjątkiem, z wyjątkiem, którego nikt nie złapał, albo przez return. To miejsce na zwolnienie tego, co zajął blok try: zamknięcie pliku, zwolnienie blokady, zatrzymanie licznika czasu.

<?php
function process(string $file): string
{
    $handle = fopen($file, 'w');
    echo "opened $file\n";
    try {
        fwrite($handle, "data\n");
        if ($file === 'bad.txt') {
            throw new RuntimeException('write check failed');
        }
        return 'saved';           // finally still runs before returning
    } finally {
        fclose($handle);
        echo "closed $file\n";
    }
}

echo process('good.txt'), "\n\n";

try {
    echo process('bad.txt'), "\n";
} catch (RuntimeException $e) {
    echo 'Failed: ', $e->getMessage(), "\n";
}

Dla good.txt plik jest zamykany, zanim zostanie wypisane saved, bo finally wykonuje się, zanim funkcja faktycznie zwróci wartość. Dla bad.txt w process() nie ma catch: finally zamyka plik, a potem wyjątek wędruje dalej do catch wywołującego.

Unikaj return w finally: zastępuje wartość zwróconą przez blok try i po cichu wyrzuca wyjątek, który był w drodze:

function f(): string
{
    try {
        return 'from try';
    } finally {
        return 'from finally';
    }
}

function g(): string
{
    try {
        throw new RuntimeException('lost');
    } finally {
        return 'no exception reaches the caller';
    }
}

echo f(); // from finally
echo g(); // no exception reaches the caller

Ponowne rzucenie lub opakowanie wyjątku

Czasem blok catch może tylko częściowo obsłużyć problem: zalogować go, posprzątać, a potem puścić dalej. throw $e; rzuca ten sam wyjątek ponownie. Częściej chcesz dodać kontekst, zachowując pierwotną przyczynę, i do tego służy trzeci argument konstruktora, $previous:

<?php
class ConfigException extends RuntimeException {}

function readConfig(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (JsonException $e) {
        // Wrap: a clearer message, the original kept as "previous"
        throw new ConfigException('config.json is not valid JSON', 0, $e);
    }
}

try {
    print_r(readConfig('{"debug": true}'));
    readConfig('{"debug": true,}');
} catch (ConfigException $e) {
    echo $e->getMessage(), "\n";
    echo 'Caused by: ', get_class($e->getPrevious()), ': ', $e->getPrevious()->getMessage(), "\n";
}

Wywołujący ma do czynienia z jednym ConfigException i nie musi wiedzieć, że konfiguracja jest w JSON, a getPrevious() zachowuje niskopoziomowe szczegóły do logu.

Nieprzechwycone wyjątki i globalny handler

Wyjątek, którego nie obsłuży żaden catch, kończy skrypt krytycznym błędem z klasą, komunikatem, plikiem i linią oraz śladem stosu:

<?php
// No try/catch anywhere in this file
function charge(int $cents): void
{
    if ($cents <= 0) {
        throw new DomainException("Amount must be positive, got $cents");
    }
}

charge(500);
echo "first charge ok\n";
charge(-1);
echo "never printed\n";

PHP wypisuje first charge ok, a potem:

PHP Fatal error:  Uncaught DomainException: Amount must be positive, got -1 in /home/index.php:6
Stack trace:
#0 /home/index.php(12): charge()
#1 {main}
  thrown in /home/index.php on line 6

Na działającej stronie ten komunikat nigdy nie powinien trafić do odwiedzających. set_exception_handler() rejestruje funkcję, która dostaje każdy wyjątek, którego nikt nie złapał: jedno miejsce, by go zalogować i wypisać uprzejmą stronę:

<?php
set_exception_handler(function (Throwable $e) {
    // In production: write $e to a log file here
    echo "<h1>Something went wrong</h1>\n";
    echo "<p>We have been notified. Please try again later.</p>\n";
    echo '<!-- ', get_class($e), ': ', htmlspecialchars($e->getMessage()), " -->\n";
});

echo "<p>Loading your dashboard...</p>\n";
throw new RuntimeException('Database timeout');

Handler się wykonuje, a potem skrypt się zatrzymuje; nie da się wznowić działania po throw. To, czy na stronie w ogóle pojawia się tekst błędu PHP, kontroluje display_errors, opisane w raportowaniu błędów.

Ostrzeżenia to nie wyjątki

try/catch widzi tylko to, co zostało rzucone. Wiele starszych funkcji PHP nie rzuca wyjątków: zwracają false lub null i co najwyżej wypisują ostrzeżenie. json_decode() to typowy przypadek i otoczenie go przez try niczego nie zmienia, dopóki nie poprosisz go o rzucanie:

<?php
$broken = '{"name": "Ada",}';

try {
    $data = json_decode($broken, true);
    var_dump($data);                    // NULL, and no exception
    echo 'Error: ', json_last_error_msg(), "\n";
} catch (JsonException $e) {
    echo "never reached\n";
}

try {
    $data = json_decode($broken, true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Caught: ', $e->getMessage(), "\n";
}

Dla funkcji bez takiej flagi sprawdzaj wartość zwracaną (if ($handle === false)) albo najpierw warunek wstępny (file_exists(), isset()). set_error_handler(), który rzuca ErrorException, zamienia każde ostrzeżenie w prawdziwy wyjątek, jeśli chcesz jednej zasady dla wszystkiego.

Przepis: walidacja formularza przez wyjątki

Praktyczny wzorzec: funkcje walidujące rzucają wyjątki, a strona je łapie i pokazuje komunikat obok formularza. Uruchom, wpisz wiek w formularzu i naciśnij Send: ten sam skrypt uruchomi się ponownie z wypełnionym $_POST.

<?php
function validAge(string $raw): int
{
    if (trim($raw) === '') {
        throw new InvalidArgumentException('Please enter your age.');
    }
    $age = filter_var($raw, FILTER_VALIDATE_INT);
    if ($age === false) {
        throw new InvalidArgumentException('Age must be a whole number.');
    }
    if ($age < 13) {
        throw new RangeException('You must be at least 13 to sign up.');
    }
    return $age;
}

$raw = $_POST['age'] ?? '';
$message = '';

if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    try {
        $age = validAge($raw);
        $message = "<p style=\"color:green\">Welcome, age $age accepted.</p>";
    } catch (InvalidArgumentException | RangeException $e) {
        $message = '<p style="color:red">' . htmlspecialchars($e->getMessage()) . '</p>';
    }
}
?>
<form method="post">
    <label>Age <input name="age" value="<?= htmlspecialchars($raw) ?>"></label>
    <button>Send</button>
</form>
<?= $message ?>

Spróbuj pustego pola, twelve, 9 i 30. Każda niespełniona zasada rzuca wyjątek z własnym komunikatem, a jedno catch zamienia je wszystkie w tę samą czerwoną linię. Strona o formularzach rozwija to o kilka pól i błędy przy każdym z nich.