Download the PHP package bfocus/monitor without Composer

bfocus/monitor

Monitoramento de erros do bFocus para PHP: os erros não tratados do seu sistema chegam ao bFocus, são agrupados entre todos os clientes e viram demanda para a equipe.

Zero dependências (só ext-curl e ext-json) · PHP 8.1+ · nunca derruba o app · Laravel e PSR-15.

Instalar

Ligar (uma linha)

A chave do agente está no bFocus em Monitoramento → Agentes. O init não faz chamada de rede e liga a captura de:

• exceção não tratada (set_exception_handler, nível fatal) — o handler que já existia continua rodando depois do nosso; sem handler, o PHP quebra como sempre (mensagem, HTTP 500, saída 255);
• erro fatal (E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR) visto no encerramento.

O PHP não tem thread: os eventos ficam numa fila (até 100) e saem no encerramento do script (ou num Monitor::flush()). No PHP-FPM o envio acontece depois de fastcgi_finish_request(): a resposta já foi entregue e o usuário não espera o monitor.

Sinal de vida: o painel mostra o agente vivo mesmo sem erro. O pacote manda no máximo 1 a cada 5 min por processo, junto do envio no encerramento (no FPM, depois da resposta). Com APCu o intervalo vale entre as requisições do mesmo worker; sem APCu, numa requisição web ele só vai junto de um envio de erros. Worker/daemon de longa duração: chame Monitor::heartbeat() no laço (respeita os 5 min).

Opções: base_url, sample_rate (0..1), ignore (textos contidos; "/regex/" também vale), before_send (recebe o evento e devolve o evento alterado ou null para descartar), auto_capture => false (sem ganchos globais), heartbeat => false (sem sinal de vida), in_app_prefixes (namespaces/caminhos seus mesmo em vendor/) e project_root.

Laravel

Laravel 11+ (bootstrap/app.php):

Estrutura antiga com app/Exceptions/Handler.php (também vale no Laravel 11 atualizado):

Configuração no .env (ou em config/services.php → 'bfocus_monitor' => [...], com as mesmas chaves do init):

O ambiente vem do APP_ENV. Só chega ao bFocus o que o Laravel reportaria (404, validação e o $dontReport ficam de fora), e o log continua como sempre.

Laminas / Mezzio / Slim (PSR-15)

Precisa de psr/http-server-middleware (todo framework PSR-15 já traz):

Sem Monitor::init antes, o middleware liga pelo ambiente (BFOCUS_MONITOR_KEY, BFOCUS_MONITOR_RELEASE, BFOCUS_MONITOR_ENVIRONMENT/APP_ENV, BFOCUS_SIGNING_SECRET). Ele abre um escopo por requisição (rota e URL sem query string), captura a exceção e a relança.

Quem foi afetado (identidade)

Com signing_secret (o segredo da chave de assinatura do sistema, o mesmo do userHash do widget) o pacote assina a identidade sozinho. Sem ele, passe o hash que o seu servidor já gera: setUser($id, $empresa, $userHash). Sem assinatura válida o erro conta como "não identificado". Monitor::signUser($secret, $id, $empresa) gera o mesmo hash para entregar ao front.

Manual

Em processo longo (Octane, RoadRunner, Swoole, workers de fila) chame Monitor::flush() ao fim de cada requisição/job — o encerramento do script demora a chegar.

O que é enviado

Tipo e mensagem da exceção (encadeadas com getPrevious(): vai a causa raiz, com (dentro de: …)), os frames (de fora para dentro, o do throw por último, caminho relativo à raiz do projeto, inApp falso para vendor/), release, ambiente, rota, URL sem query, identidade, tags, passos e versão do PHP/SO. Nunca: corpo de requisição, cookies, headers. O mesmo erro sai no máximo 1 vez a cada 30 s, e no máximo 100 eventos por minuto.

Testes

Licença MIT — Berni Software.