Erros e Logs

Introdução

Estas são funções para lidar com erros e logs. Elas permitem a você definir a suas próprias regras para manusear erros, assim como para modificar a maneira com que é efetuado o log de erros. Isto permite a você melhorar e adaptar as suas necessidades os avisos de erro.

Com as funções de log, você pode mandar mensagens diretamente para outras máquinas, para um email (ou email para um pager), para os logs do sistema, etc, assim você pode seletivamente logar e monitorar as partes mais importantes das suas aplicações e websites.

As funções de erro permitem você configurar quais níveis de erro devem ser reportados e o tipo de resposta que será dado, indo desde simples avisos até as funções retornadas durante os erros.

Dependências

Nenhuma biblioteca externa é necessária para compilar esta extensão.

Instalação

Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.

Configurações em execução

O comportamento dessas funções podem ser modificado pelas configurações do php.ini.

**Opções de configurações de erros e log**
Nome	Padrão	Modificável	Changelog
error_reporting	NULL	PHP_INI_ALL
display_errors	"1"	PHP_INI_ALL
display_startup_errors	"0"	PHP_INI_ALL	Disponível desde PHP 4.0.3.
log_errors	"0"	PHP_INI_ALL
log_errors_max_len	"1024"	PHP_INI_ALL	Disponível desde PHP 4.3.0.
ignore_repeated_errors	"0"	PHP_INI_ALL	Disponível desde PHP 4.3.0.
ignore_repeated_source	"0"	PHP_INI_ALL	Disponível desde PHP 4.3.0.
report_memleaks	"1"	PHP_INI_ALL	Disponível desde PHP 4.3.0.
track_errors	"0"	PHP_INI_ALL
html_errors	"1"	PHP_INI_ALL	PHP_INI_SYSTEM no PHP <= 4.2.3. Disponível desde PHP 4.0.2.
docref_root	""	PHP_INI_ALL	Disponível desde PHP 4.3.0.
docref_ext	""	PHP_INI_ALL	Disponível desde PHP 4.3.0.
error_prepend_string	NULL	PHP_INI_ALL
error_append_string	NULL	PHP_INI_ALL
error_log	NULL	PHP_INI_ALL
warn_plus_overloading	NULL		Esta opção não é mais disponível no PHP 4.0.0

Para mais detalhes e definições das constantes PHP_INI_*, veja Diretivas do arquivo php.ini.

Breve descrição das diretivas de configuração.

error_reporting integer

Define o nível de erros para reportar. O parâmetro pode ser um inteiro ou uma constante. Os níveis de erros para reportar estão descritos em Constantes Pré-definidas, e no php.ini. Para definir em tempo de execução, use a função error_reporting(). Veja também a diretiva display_errors.

No PHP 4 e PHP 5 o valor padrão é E_ALL & ~E_NOTICE. Esta definição não mostra erros de nível E_NOTICE. Você deve querer mostra-los durante o desenvolvimento.

Nota: Ativando E_NOTICE durante o desenvolvimento tem alguns beneficios. Para o proposito de eliminar erros: mensagens NOTICE irão avisar você sobre possiveis erros em seu código. Por exemplo, o uso de valores não definidos é avisado. É extremamente útil para encontrar erros de digitação e economisar tempo na correção de erros. As mensagens NOTICE irão avisar a você sobre mal estilo. Por exemplo, $arr[item] é melhor que seja escrito como $arr['item'] já que o PHP irá tratar "item" como uma constante. Se não for uma constante, o PHP irá considerar como uma string de índice para a matriz.

Nota: No PHP 5 um novo nível de erro E_STRICT esta disponível. Já que E_STRICT não esta incluída em E_ALL você deve explicitamente ativar este nível de erro. Ativar E_STRICT durante o desenvolvimento tem alguns beneficios. Mensagem STRICT irão ajudar a você a utilizar o metodo mais recente de codificação, por exemplo, avisar você sobre funções obsoletas.

Nota: Constantes do PHP fora do PHP Usar constantes PHP fora do PHP, como no httpd.conf, não terá sentido útiil assim nestes casos os valores integer são requeridos. E já que níveis de erros serão adicionados com o passar do tempo, o valor máximo (para E_ALL) irá provavelmente mudar. Assim no lugar de E_ALL considere usar um grande valor para cobrir todos os valores de agora assim como no futuro, um valor numérico como 2147483647.

No PHP 3, a definição padrão é (E_ERROR | E_WARNING | E_PARSE), indicando a mesma coisa. Note, entretanto, desde que constantes não são suportadas no php3.ini do PHP 3, a definição do nível de erros para reportar deve ser númerica, neste caso 7.

display_errors boolean

Isto determina quando os erros devem ser mostrados como parte da saída ou se devem ser escondidos do usuário.

O valor "stderr" é enviado para stderr ao invés de stdout. O valor é disponível no PHP 5.2.4. Em versões anteriores, esta diretiva era do tipo boolean.

Nota: Isto serve para suportar o seu desenvolvimento e nunca deve ser usado em sistemas de produção (ex. sistemas conectados a internet).

Nota: Mesmo podendo ser display_errors definido em tempo de execução (com ini_set()), ele não terá qualquer efeito se o script tiver erro fatal. Isto é porque a ação desejada em tempo de execução não é executada.

display_startup_errors boolean

Mesmo quando display_errors esta em on, erros que aconteçam durante a inicialização do PHP não são mostrados. É fortemente recomendado manter display_startup_errors em off, exceto para procurar erros.

log_errors boolean

Indica se as mensagens de erro do script devem ficar no log de erros do servidor ou em error_log. Esta opção depende do servidor.

Nota: Você é fortemente avisado para usar o log de erros ao invés de mostra-los em web sites de produção.

log_errors_max_len integer

Define o limite de tamanho da mensagem de erro para logar em bytes. Em error_log é adicionada informação sobre a fonte. O padrão é 1024 e 0 permite que não seja estabelecido nenhum limite. Este tamanho é aplicado aos erros logados, erros exibidos e também a $php_errormsg.

Quando um integer é utilizado, o valor é medido em bytes. Você também pode utilizar a notação resumida como descrito neste FAQ.

ignore_repeated_errors boolean

Não loga mensagens repetidas. Erros repetidos devem acontecer no mesmo arquivo na mesma linha enquanto ignore_repeated_source estiver em true.

ignore_repeated_source boolean

Ignora a fonte da mensagem quando estiver ignorando mensagens repetidos. Quando esta definição ON não irá logar mensagens de erros repetidas de arquivos diferentes ou linhas diferentes.

report_memleaks boolean

Se este parâmetro estiver em Off, quando acontecerem memory leaks não será mostrado (na saída ou no log). Isto só tem efeito numa compilação de debug, e se error_reporting incluir E_WARNING na lista de permitidos.

track_errors boolean

Se ativado, a última mensagem de erro sempre estará disponível na variável $php_errormsg.

html_errors boolean

Desativa as tags HTML nas mensagens de erro. O novo formato de mensagens de erro em HTML produz mensagens que podem ser clicadas e que direcionam o usuário para uma pagina descrevendo o erro ou a função que causou o erro. Estas referencias são afetadas por docref_root e docref_ext.

docref_root string

O novo formato de mensagens de erro em HTML produz mensagens que podem ser clicadas e que direcionam o usuário para uma pagina descrevendo o erro ou a função que causou o erro. No caso de paginas de manual você pode baixar o manual na sua língua e definir esta diretiva para a sua cópia local. Se a sua cópia local do manual podur ser acessada por '/manual/' você pode simplesmente usar docref_root=/manual/ . Adicionalmente você deve definir docref_ext para ser igual a extensão da sua cópia docref_ext=.html . É possível usar referencias externas. Por exemplo, você pode usar docref_root=https://manual/en/ ou docref_root="https://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"

A maior parte do tempo você deve querer que o valor de docref_root termine com uma barra '/'. Mas veja o segundo exemplo acima o qual não tem ou não necessita isso.

Nota: Isto é para suportar o seu desenvolvimento já que torna mais fácil encontrar a descrição de uma função. Entretando não deve ser usado em sistemas de produção (ex. sistemas conectados na internet).

docref_ext string

Veja docref_root.

Nota: O valor de docref_ext deve começar com um ponto '.'.

error_prepend_string string

String para mostrar antes de uma mensagem de erro.

error_append_string string

String para mostrar após uma mensagem de erro.

error_log string

O nome do arquivo onde os erros do script serão logados. O arquivo deve poder ser escrito pelo usuário do servidor web. Se o valor especial syslog é usado, os erros são enviados para o log do sistema. No Unix, isto indica syslog(3) e no Windows NT isto indica o log do evento. O log de sistema não é suportado no Windows 95. Veja também: syslog(). Se esta diretiva não for definida, os erros são enviados para o log de erros do SAPI. Por exemplo, é para o log de erros do Apache ou stderr para o CLI.

warn_plus_overloading boolean

Se ativado, esta opção faz o PHP mostrar um aviso quando o operador de adição (+) é usado em strings. Isto é para tornar mais fácil encontrar scripts que precisam ser rescritos usando o operador de concatenação (.). Esta opção não existe no PHP 4.

Constantes pré-definidas

As constantes listadas abaixo estão sempre disponíveis como parte do núcleo do PHP.

Nota: Você pode usar estes nomes de constantes no php.ini mas não fora do PHP, como no httpd.conf, aonde você deve usar os valores.

**Erros e Log**
Valor	Constante	Descrição	Nota
1	`E_ERROR` (integer)	Erros em tempo de execução fatais. Estes indicam erros que não podem ser recuperados, como problemas de alocação de memória. A execução do script é interrompida.
2	`E_WARNING` (integer)	Avisos em tempo de execução (erros não fatais). A execução do script não é interrompida.
4	`E_PARSE` (integer)	Erro em tempo de compilação. Erros gerados pelo interpretador.
8	`E_NOTICE` (integer)	Notícia em tempo de execução. Indica que o script encontrou alguma coisa que pode indicar um erro, mas que também possa acontecer durante a execução normal do script.
16	`E_CORE_ERROR` (integer)	Erro fatal que acontece durante a inicialização do PHP. Este é parecido com `E_ERROR`, exceto que é gerado pelo núcleo do PHP.	Desde PHP 4
32	`E_CORE_WARNING` (integer)	Avisos (erros não fatais) que aconteçam durante a inicialização do PHP. Este é parecido com `E_WARNING`, exceto que é gerado pelo núcleo do PHP.	Desde PHP 4
64	`E_COMPILE_ERROR` (integer)	Erro fatal em tempo de compilação. Este é parecido com `E_ERROR`, exceto que é gerado pelo Zend Scripting Engine.	Desde PHP 4
128	`E_COMPILE_WARNING` (integer)	Aviso em tempo de compilação. Este é parecido com `E_WARNING`, exceto que é geredo pelo Zend Scripting Engine.	Desde PHP 4
256	`E_USER_ERROR` (integer)	Erro gerado pelo usuário. Este é parecido com `E_ERROR`, exceto que é gerado pelo código PHP usando a função trigger_error().	Desde PHP 4
512	`E_USER_WARNING` (integer)	Aviso gerado pelo usuário. Este é parecido com `E_WARNING`, exceto que é gerado pelo código PHP usando a função trigger_error().	Desde PHP 4
1024	`E_USER_NOTICE` (integer)	Notícia gerada pelo usuário. Este é parecido com `E_NOTICE`, exceto que é gerado pelo código PHP usando a função trigger_error().	Desde PHP 4
2048	`E_STRICT` (integer)	Notícias em tempo de execução. Permite ao PHP sugerir mudanças ao seu código as quais irão assegurar melhor interoperabilidade e compatibilidade futura do seu código.	Desde PHP 5
4096	`E_RECOVERABLE_ERROR` (integer)	Erro fatal capturável. Indica que um erro provavelmente perigoso aconteceu, mas não deixou o Engine em um estado instável. Se o erro não for pego por uma manipulador definido pelo usuário (veja também set_error_handler()), a aplicação é abortada como se fosse um `E_ERROR`.	Desde PHP 5.2.0
8191	`E_ALL` (integer)	Todos erros e avisos, como suportado, exceto de nível `E_STRICT` no PHP < 6.	6143 no PHP 5.2.x e 2047 anteriormente

Os valores acima (numéricos ou simbolicos) são usados para criar um bitmask que especifica quais erros reportar.Você pode usar os operadores Bit-a-bit para combinar estes valores ou mascarar certos tipos de erro. Note que somente '|', '~', '!', '^' and '&' serão ententidos dentro do php.ini, entretanto, nenhum operador será entendido no php3.ini.

Exemplos

Abaixo você poderá ver um exemplo de como usar as capacidades de gerenciamento de erros no PHP. Nós definimos uma função para gerenciamento de erros a qual guardas as informações dentro de um arquivo (usando um formato XML), e envia um e-mail para o desenvolvador caso um erro crítico na lógica aconteça.

Example#1 Usando gerenciamento de erro em um script


<?php
// nós iremos fazer o nosso próprio gerenciamento de erros
error_reporting(0);

// função definida pelo usuário para gerenciamento de erros
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) 
{
    // timestamp para a entrada do erro
    $dt = date("Y-m-d H:i:s (T)");

    // Define uma matriz associativa com as strings dos erros
    $errortype = array (
                E_ERROR              => "Error",
                E_WARNING            => "Warning",
                E_PARSE              => "Parsing Error",
                E_NOTICE             => "Notice",
                E_CORE_ERROR         => "Core Error",
                E_CORE_WARNING       => "Core Warning",
                E_COMPILE_ERROR      => "Compile Error",
                E_COMPILE_WARNING    => "Compile Warning",
                E_USER_ERROR         => "User Error",
                E_USER_WARNING       => "User Warning",
                E_USER_NOTICE        => "User Notice",
                E_STRICT             => "Runtime Notice",
                E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                );
    // define quais erros nós iremos salvar
    $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

    $err = "<errorentry>\n";
    $err .= "\t<datetime>" . $dt . "</datetime>\n";
    $err .= "\t<errornum>" . $errno . "</errornum>\n";
    $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
    $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
    $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
    $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

    if (in_array($errno, $user_errors)) {
        $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
    }
    $err .= "</errorentry>\n\n";

    // para teste
    // echo $err;

    // salva para o log de erros, e envia um email para o desenvolvedor em caso de erro crítico
    error_log($err, 3, "/usr/local/php4/error.log");
    if ($errno == E_USER_ERROR)
        mail("[email protected]", "Critical User Error", $err);
}


function distance($vect1, $vect2)
{
    if (!is_array($vect1) || !is_array($vect2)) {
        trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
        return NULL;
    }

    if (count($vect1) != count($vect2)) {
        trigger_error("Vectors need to be of the same size", E_USER_ERROR);
        return NULL;
    }

    for ($i=0; $i<count($vect1); $i++) {
        $c1 = $vect1[$i]; $c2 = $vect2[$i];
        $d = 0.0;
        if (!is_numeric($c1)) {
            trigger_error("Coordinate $i in vector 1 is not a number, using zero",
                            E_USER_WARNING);
            $c1 = 0.0;
        }
        if (!is_numeric($c2)) {
            trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                            E_USER_WARNING);
            $c2 = 0.0;
        }
        $d += $c2*$c2 - $c1*$c1;
    }
    return sqrt($d);
}

$old_error_handler = set_error_handler("userErrorHandler");

// constante indefinida, gera um aviso
$t = I_AM_NOT_DEFINED;

// define alguns "vetores"
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);

// gera um erro do usuário
$t1 = distance($c, $b) . "\n";

// gera outro erro do usuário
$t2 = distance($b, "i am not an array") . "\n";

// gera um aviso
$t3 = distance($a, $b) . "\n";

?>

Veja também

Veja também syslog().

Índice

debug_backtrace — Gera um backtrace
debug_print_backtrace — Mostra um backtrace
error_get_last — Get the last occurred error
error_log — Envia uma mensagem de erro para algum lugar
error_reporting — Define quais erros serão reportados
restore_error_handler — Restaura a função anterior para gerenciamento de erro
restore_exception_handler — Restauda a função tratadora de exceções anterior.
set_error_handler — Define uma função do usuário para manipular erros
set_exception_handler — Define uma função definida pelo usuário para tratamento de exceções
trigger_error — Gera uma mensagem a nível de usuário de erro/aviso/notícia
user_error — Apelido para trigger_error

enchant_dict_suggest

debug_backtrace

Referência das Funções

PHP Manual