2026.07.28.
Kódolás, keretrendszerek

PHP hibakezelés exception és naplózással

Temesvári László

PHP hibakezelés: Exception osztályok és naplózás – Ne csak kapd el, hanem jegyezd is fel!

Sziasztok kollégák! Ma egy olyan témába mélyedünk bele, amit sokan ismerünk, de kevesen használunk profi módon: a PHP hibakezelés exception osztályokkal és a naplózással. Gondoljatok csak bele: hány alkalommal futottatok már bele egy olyan „kis ördögű” bugba, ami production környezetben jelentkezik, de helyben nem tudjátok reprodukálni? Pont erre a problémára találták ki a rendszeres exception kezelést és naplózást.

Miért éri meg exception-ökkel foglalkozni?

A régi szép időkben a PHP-ben még a @ jel segítségével próbáltuk elnyomni a hibákat, vagy éppenséggel az error_reporting(0)-val küldtük a picsába az összes figyelmeztetést. Ma már sokkal elegánsabb eszközeink vannak. Az exception-ök nem csak arról szólnak, hogy „valami elromlott”, hanem strukturált információt szállítanak a hiba természetéről, kontextusáról, és legfontosabb: irányíthatóak.

Képzeljétek el, hogy egy REST API-t fejlesztetek, és a validator azt mondja, hogy érvénytelen email cím érkezett. Egy sima hibaüzenet helyett dobhatok egy InvalidEmailException-t, amit a kontroller szinten elkapok és átalakítok szép JSON válasszá.

Egy életszerű példa: Validáció exception-ökkel

Nézzünk egy konkrét példát, ahol saját exception osztályt készítünk:

field = $field;
        $this->invalidValue = $invalidValue;
        $defaultMessage = "A(z) {$field} mező érvénytelen értéket kapott: " . json_encode($invalidValue);
        parent::__construct($message ?: $defaultMessage, $code, $previous);
    }
    
    public function getField(): string {
        return $this->field;
    }
    
    public function getInvalidValue() {
        return $this->invalidValue;
    }
    
    public function toArray(): array {
        return [
            'error' => 'validation_failed',
            'field' => $this->field,
            'invalid_value' => $this->invalidValue,
            'message' => $this->getMessage()
        ];
    }
}

class UserRegistration {
    public function register(array $data): void {
        if (!filter_var($data['email'] ?? '', FILTER_VALIDATE_EMAIL)) {
            throw new ValidationException('email', $data['email'] ?? '');
        }
        
        if (strlen($data['password'] ?? '') register(['email' => 'rossz.email', 'password' => '123']);
} catch (ValidationException $e) {
    http_response_code(400);
    echo json_encode($e->toArray());
} catch (Exception $e) {
    http_response_code(500);
    error_log("Regisztrációs hiba: " . $e->getMessage());
    echo json_encode(['error' => 'internal_server_error']);
}

A naplózás: amikor a hiba elszalad a kezeink közül

De várjunk csak! Mi van akkor, ha egy exception elkapásra kerül, de mi nem csak a felhasználónak akarunk visszajelezni, hanem rögzíteni is szeretnénk a hibát? Itt jön a képbe a naplózás.

A legnagyobb bak, amit láttam: a fejlesztők elkapják az exception-t, kiírják a felhasználónak valami barátságos üzenetet, de elfelejtik naplózni. Aztán amikor a production környezetben megjelenik egy hiba, nincs nyoma, hogy mi történt.

logFile = __DIR__ . '/../logs/' . $logFile;
    }
    
    public function logException(Throwable $e, string $context = ''): void {
        $logEntry = sprintf(
            "[%s] %s: %s in %s:%d\nContext: %s\nStack trace:\n%s\n\n",
            date('Y-m-d H:i:s'),
            get_class($e),
            $e->getMessage(),
            $e->getFile(),
            $e->getLine(),
            $context,
            $e->getTraceAsString()
        );
        
        file_put_contents($this->logFile, $logEntry, FILE_APPEND | LOCK_EX);
    }
}

// Globális exception handler
set_exception_handler(function (Throwable $e) {
    $logger = new ApplicationLogger();
    $logger->logException($e, 'Global exception handler');
    
    // Development környezetben részletes hibát mutatunk
    if (getenv('APP_ENV') === 'development') {
        echo '<pre>';
        var_dump($e);
        echo '</pre>';
    } else {
        // Productionben általános hibaüzenet
        http_response_code(500);
        echo 'Sajnáljuk, technikai hiba történt. A fejlesztők értesítve lettek.';
    }
});

Frontend kapcsolat: jQuery és Bootstrap hibajelzés

Természetesen a backend exception-ök mellett a frontenden is szeretnénk értelmes hibajelzéseket. Íme egy példa, hogyan dolgozhat fel egy jQuery/Bootstrap alapú frontend a backendről érkező validációs hibákat:

$(document).ready(function() {
    $('#registrationForm').submit(function(e) {
        e.preventDefault();
        
        $.ajax({
            url: '/api/register',
            method: 'POST',
            data: $(this).serialize(),
            dataType: 'json'
        })
        .done(function(response) {
            $('#successAlert').removeClass('d-none').addClass('show');
            $('#errorContainer').addClass('d-none');
        })
        .fail(function(xhr) {
            $('#successAlert').removeClass('show').addClass('d-none');
            
            if (xhr.status === 400 && xhr.responseJSON) {
                var error = xhr.responseJSON;
                var $errorContainer = $('#errorContainer');
                var $errorList = $('#errorList');
                
                $errorList.empty();
                
                // Ha validációs hiba tömb jön
                if (Array.isArray(error.errors)) {
                    error.errors.forEach(function(err) {
                        $errorList.append(
                            $('<li>').addClass('list-group-item list-group-item-danger')
                                     .text(err.field + ': ' + err.message)
                        );
                    });
                } else if (error.field) {
                    // Egyedi validációs hiba
                    $errorList.append(
                        $('<li>').addClass('list-group-item list-group-item-danger')
                                 .text(error.field + ': ' + error.message)
                    );
                }
                
                $errorContainer.removeClass('d-none').addClass('show');
            } else {
                // Egyéb szerverhiba
                alert('Váratlan hiba történt. Kérjük, próbálja újra később.');
            }
        });
    });
});

És a hozzátartozó CSS/SCSS:

.error-highlight {
    border-color: #dc3545 !important;
    box-shadow: 0 0 0 0.2rem rgba(220, 53, 69, 0.25);
    
    & ~ .invalid-feedback {
        display: block;
    }
}

#errorContainer {
    transition: all 0.3s ease;
    
    &:not(.show) {
        opacity: 0;
        max-height: 0;
        overflow: hidden;
    }
    
    &.show {
        opacity: 1;
        max-height: 500px;
    }
}

Gyakori buktatók, amiket érdemes elkerülni

1. Túl sok catch blokk: Nem kell minden exception típust külön kezelni. Használjatok alap exception osztályokat, amiket később lehet specializálni.

2. Információvesztés: Amikor új exception-t dobunk egy másik exception kapcsán, mindig adjuk át az eredetit a $previous paraméterben.

3. Érzékeny adatok naplózása: Soha ne naplózzatok jelszavakat, kreditkártya számokat vagy személyes adatokat!

4. Naplófájlok elszaporítása: Implementáljatok log rotation-t, vagy használjatok professzionális naplózó eszközt, mint a Monolog.

5. Frontend és backend hibajelzés eltérése: Tartsátok szinkronban, hogy milyen hibakódokat és üzenetformátumokat használtok.

Összegzés

A jó hibakezelés és naplózás olyan, mint a biztosítás: amikor jól működik, nem is gondolunk rá, de amikor baj van, akkor nagyon hálásak vagyunk érte. Az exception osztályok segítenek strukturáltan kezelni a hibákat, a naplózás pedig megőrzi a nyomot, hogy később visszakövetkeztethessünk a problémák forrására.

Ne úgy tekintsetek a hibakezelésre, mint egy kötelező rosszra, hanem mint a kódotok dokumentációjának egy részére – ami élőben mutatja, hogy mi történik, amikor a dolgok nem a tervek szerint alakulnak.

Bónusz tipp: Tekintsetek rá a Monolog csomagra, ha komolyabb naplózási igényeitek vannak, és a PSR-3 szabványra, ha interoperábilis megoldásokat szeretnétek.

Használjátok egészséggel, és remélem, legközelebb már nem egy „Undefined index” fogad titeket a logfájlokban, hanem értelmes, strukturált hibajelentések!

Kapcsolódó cikkek