getTrace()

PHP getTrace()

Exception::getTrace() restituisce lo stack trace di un'eccezione come array. Ogni elemento descrive una chiamata a funzione o metodo presente nello stack al momento in cui l'eccezione è stata lanciata, ordinata dal punto di lancio verso l'esterno. È uno degli strumenti più utili per capire dove e come si è verificato un errore.

Questa pagina illustra cosa restituisce getTrace(), la struttura di ogni frame della traccia e come differisce dal più familiare getTraceAsString(). Il metodo è definito sull'interfaccia base Throwable, quindi è disponibile su ogni oggetto Exception ed Error.

public Exception::getTrace(): array

Non accetta argomenti e restituisce un array indicizzato. Il frame 0 è la chiamata più interna (la funzione che ha effettivamente lanciato l'eccezione), e gli indici crescono verso il chiamante più esterno.

Esempio rapido

Lo script seguente lancia un'eccezione da una chiamata annidata e stampa ogni frame della traccia:

<?php

function readConfig($path) {
    return parseFile($path);
}

function parseFile($path) {
    throw new Exception("Cannot read file: $path");
}

try {
    readConfig('/etc/app.conf');
} catch (Exception $e) {
    $trace = $e->getTrace();
    echo "Number of frames: " . count($trace) . "\n";
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() called in {$frame['file']} on line {$frame['line']}\n";
    }
}

Output:

Number of frames: 2
#0 parseFile() called in /path/to/script.php on line 4
#1 readConfig() called in /path/to/script.php on line 12

Si noti che il frame della funzione che ha lanciato l'eccezione (parseFile) riporta la riga in cui è stata chiamata (riga 4, all'interno di readConfig), non la riga dell'istruzione throw. La riga del lancio è disponibile separatamente tramite getLine() e getFile().

Cosa contiene ogni frame della traccia

Ogni frame è un array associativo. Le chiavi più utili sono:

Questo script esamina un singolo frame nel dettaglio:

<?php

function divide($a, $b) {
    if ($b === 0) {
        throw new InvalidArgumentException('Division by zero');
    }
    return $a / $b;
}

try {
    divide(10, 0);
} catch (Exception $e) {
    print_r($e->getTrace()[0]);
}

Output:

Array
(
    [file] => /path/to/script.php
    [line] => 11
    [function] => divide
    [args] => Array
        (
            [0] => 10
            [1] => 0
        )

)

Nota di sicurezza: il campo args contiene i valori effettivi degli argomenti, che possono includere password, token o altri dati sensibili. Non esporre mai un array getTrace() grezzo agli utenti finali — registrarlo lato server. L'impostazione INI zend.exception_ignore_args di PHP (attiva per impostazione predefinita dal PHP 7.4) rimuove args per evitare la divulgazione di dati sensibili; se non si vede una chiave args, è per questo motivo.

getTrace() vs getTraceAsString()

getTrace() fornisce l'array grezzo in modo da poterlo formattare, filtrare o serializzare a piacere. Se si vuole semplicemente una stringa leggibile, usare getTraceAsString(), che restituisce le stesse informazioni già formattate:

<?php

try {
    throw new RuntimeException('Something broke');
} catch (Throwable $e) {
    echo $e->getTraceAsString();
}

Usare la forma array quando si vuole scorrere i frame in modo programmatico (ad esempio per costruire un report di errore personalizzato o inviare dati strutturati a un servizio di logging), e la forma stringa per visualizzazione rapida o righe di log.

Dove si colloca getTrace() nell'API delle eccezioni

getTrace() è uno dei diversi accessori di sola lettura disponibili su ogni eccezione. Sono più potenti quando usati insieme all'interno di un blocco catch:

• getMessage() — il messaggio di errore leggibile dall'utente.
• getCode() — il codice di errore numerico.
• getFile() e getLine() — dove è stata lanciata l'eccezione.
• getTraceAsString() — la traccia come stringa.
• getPrevious() — l'eccezione concatenata, se presente.

Per un quadro più completo sul lancio e la cattura delle eccezioni, vedere throw, try e la classe Exception.

Buone pratiche per la gestione delle eccezioni in PHP

Per garantire che il codice sia manutenibile e facile da debuggare, è importante seguire le buone pratiche nella gestione delle eccezioni in PHP. Ecco alcuni suggerimenti da tenere a mente:

1. Usare messaggi di eccezione significativi.

Quando si lancia un'eccezione, assicurarsi che il messaggio sia informativo e utile. Dovrebbe spiegare cosa è andato storto e come risolverlo. Ad esempio:

<?php

if ($someCondition) {
  throw new Exception('Invalid input: the email address is not valid.');
}

2. Catturare solo le eccezioni che si è in grado di gestire.

Quando si catturano le eccezioni, è importante catturare solo quelle che si è in grado di gestire. Se si cattura un'eccezione che non si sa come gestire, si potrebbe nascondere il problema reale rendendolo più difficile da debuggare. Ad esempio:

<?php

try {
  // Some code that may throw an exception.
} catch (InvalidArgumentException $e) {
  // Handle the invalid argument exception.
} catch (Exception $e) {
  // Handle all other exceptions.
}

3. Registrare le eccezioni.

Registrare le eccezioni può aiutare a diagnosticare problemi e risolvere guasti. È una buona idea registrare le eccezioni in un file o database in modo da poterle consultare in seguito. Ad esempio:

<?php

try {
  // Some code that may throw an exception.
} catch (Exception $e) {
  error_log($e->getMessage(), 0);
}

4. Usare gerarchie di eccezioni.

L'uso di gerarchie di eccezioni può aiutare a organizzare il codice e rendere più semplice catturare tipi specifici di eccezioni. Ad esempio, si potrebbe creare una classe DatabaseException che estende la classe Exception, e poi lanciare quell'eccezione quando si verifica un errore del database. Si potrebbe poi catturare solo le istanze di DatabaseException quando si gestiscono gli errori del database.

Conclusione

La gestione delle eccezioni è un aspetto critico della programmazione PHP, e il metodo getTrace() è uno strumento prezioso per il debugging e la risoluzione dei problemi. Restituendo un backtrace del contesto di esecuzione, è possibile individuare dove si è verificata un'eccezione e come è stata scatenata.

In questa guida abbiamo trattato le basi della gestione delle eccezioni in PHP, incluso come lanciare e catturare le eccezioni, e le buone pratiche per utilizzarle efficacemente. Abbiamo anche esplorato il metodo getTrace() e come può aiutare a diagnosticare e correggere gli errori nel codice.

Seguendo queste buone pratiche e sfruttando il metodo getTrace(), è possibile scrivere codice PHP robusto, affidabile e facile da mantenere. La gestione delle eccezioni può sembrare un dettaglio minore, ma può fare una grande differenza nella qualità e nell'usabilità del codice.

Practice