PHP Academy · Aula

Registro de erros e boas práticas

Registre erros em arquivos e siga padrões de tratamento de erros em produção.

Registro de erros e boas práticas é uma aula grátis de PHP Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de PHP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de PHP Academy inclui 4 aulas no total.

Por que o registro é importante

Em produção, não é possível exibir erros aos usuários, mas ainda é necessário saber quando algo dá errado. O registro captura detalhes dos erros em arquivos ou serviços para que você possa investigá-los posteriormente.

error_log()

A função de registro mais simples — grava uma mensagem no registro de erros do PHP:

<?php
error_log('User login failed for: ' . $email);
error_log('DB query took: ' . $duration . 'ms');

// Send to email (not recommended for high traffic)
error_log('Critical: server out of memory', 1, 'admin@example.com');

Registro estruturado

Registre dados estruturados como JSON para facilitar a análise e as consultas:

<?php
function logEvent(string $level, string $message, array $context = []): void {
    $entry = array_merge([
        'ts'      => date('c'),
        'level'   => $level,
        'message' => $message,
    ], $context);

    error_log(json_encode($entry));
}

logEvent('ERROR', 'Payment failed', [
    'order_id' => 123,
    'amount'   => 99.99,
    'user_id'  => 45,
]);

Níveis de registro (PSR-3)

O PSR-3 define níveis de registro padrão:

emergência — sistema inutilizável
alerta — é necessário tomar uma medida
crítico — condições críticas
erro — erros em tempo de execução
aviso — ocorrências excepcionais que não são erros
notificação — eventos normais, mas significativos
informação — mensagens informativas
depuração — informações detalhadas de depuração

Registrador Monolog

Monolog é a biblioteca padrão de registro do PHP, compatível com PSR-3:

<?php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('app');
$log->pushHandler(new StreamHandler('/var/log/app.log', Logger::DEBUG));

$log->info('User logged in', ['user_id' => 42]);
$log->error('Payment failed', ['order' => 99, 'reason' => 'card_declined']);
$log->warning('Slow query', ['duration_ms' => 3200]);

Tratamento de exceções em produção

Um manipulador de exceções adequado para produção, que registra o erro e retorna uma resposta segura:

<?php
set_exception_handler(function(\Throwable $e) {
    $id = uniqid('err_');
    error_log(json_encode([
        'error_id' => $id,
        'class'    => get_class($e),
        'message'  => $e->getMessage(),
        'file'     => $e->getFile(),
        'line'     => $e->getLine(),
        'trace'    => $e->getTraceAsString(),
    ]));
    http_response_code(500);
    echo json_encode(['error' => 'Server error', 'id' => $id]);
    exit(1);
});

Rotação de registros

Os arquivos de registro crescem indefinidamente — faça a rotação deles com logrotate no Linux ou com manipuladores baseados em tempo no Monolog:

<?php
use Monolog\Handler\RotatingFileHandler;

$handler = new RotatingFileHandler(
    '/var/log/app.log',
    30,              // keep 30 days
    Logger::DEBUG
);

// Creates dated files: app-2024-05-27.log
$log = new Logger('app');
$log->pushHandler($handler);

Registro com contexto detalhado

Inclua o contexto da requisição em cada entrada de registro para facilitar a depuração:

<?php
function getRequestContext(): array {
    return [
        'url'     => $_SERVER['REQUEST_URI'] ?? '',
        'method'  => $_SERVER['REQUEST_METHOD'] ?? '',
        'ip'      => $_SERVER['REMOTE_ADDR'] ?? '',
        'user_id' => $_SESSION['user_id'] ?? null,
    ];
}

// Add to every log call:
$log->error('Order failed', array_merge(
    getRequestContext(),
    ['order_id' => $orderId]
));

Evitando dados confidenciais nos registros

Nunca registre informações confidenciais:

Senhas e tokens
Números de cartão de crédito
Dados pessoais (conformidade com GDPR)
Pilhas de chamadas completas das exceções em respostas exibidas aos usuários

<?php
// Bad:
error_log('Login attempt: ' . $email . ' / ' . $password);

// Good:
error_log('Login failed for user: ' . substr($email, 0, 3) . '***');

Sentry e rastreamento externo de erros

Em produção, use serviços de rastreamento de erros, como o Sentry, para centralizar os erros e gerar alertas:

<?php
// After composer require sentry/sdk
\Sentry\init(['dsn' => getenv('SENTRY_DSN')]);

// Automatic capture of unhandled exceptions
// Manual capture:
try {
    processOrder();
} catch (\Throwable $e) {
    \Sentry\captureException($e);
    throw $e;
}

Pré-condições baseadas em asserções

Use asserções para detectar erros de programação durante o desenvolvimento:

<?php
// assert() throws AssertionError when false (dev mode)
assert(is_int($userId), 'userId must be an integer');
assert($amount > 0, 'amount must be positive');

// Or throw explicitly:
if (!is_int($userId)) {
    throw new \InvalidArgumentException('userId must be int');
}

Verificação rápida

De acordo com o PSR-3, qual nível de registro indica uma situação que exige atenção imediata?

Recapitulação: registro de erros

Boas práticas de registro:

Use registros JSON estruturados com marca de tempo, nível, mensagem e contexto
Siga os níveis de registro do PSR-3
Use o Monolog em aplicações de produção
Faça a rotação dos registros para evitar que o disco fique cheio
Nunca registre senhas ou dados confidenciais
Use o Sentry ou uma ferramenta semelhante para rastreamento de erros em tempo real

Perguntas Frequentes

A aula “Registro de erros e boas práticas” é grátis?

Sim — o texto completo de “Registro de erros e boas práticas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de PHP Academy, atualize para CoddyKit PRO. O curso de PHP Academy inclui 4 aulas no total.

O que vou aprender em “Registro de erros e boas práticas”?

Registre erros em arquivos e siga padrões de tratamento de erros em produção. Você pratica PHP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar PHP Academy?

Nenhuma experiência prévia é necessária. PHP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Registro de erros e boas práticas”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de PHP Academy?

Sim. Cada aula de PHP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para PHP Academy