OG Framework
OG Framework Documentação
Voltar para Documentação

Ferramentas

Crawler System

Wrapper de alto nível sobre o symfony/dom-crawler para manipulação e extracção de dados de documentos HTML.

Para Que Serve?

O Crawler resolve um problema específico: trabalhar com HTML de fontes externas de forma segura e eficiente. Imagina que recebes emails em HTML que precisas de mostrar no ERP, ou que tens um proxy que exibe páginas externas dentro da aplicação. Em ambos os casos, precisas de:

  • Sanitizar: Remover scripts, iframes, e event handlers que podem ser perigosos.
  • Manipular: Adicionar atributos, remover elementos, reescrever URLs.
  • Extrair: Obter links, imagens, metadados, ou converter para texto simples.

O Crawler fornece uma API fluente para todas estas operações.

Uso Básico

Exemplo Típico

Este exemplo mostra um caso real: receber HTML de um email externo, limpá-lo de conteúdo perigoso, e aplicar lazy loading às imagens para melhorar performance. 

use Og\Modules\Common\Facades\Crawler;

// HTML recebido de fonte externa (email, api, etc.)
$htmlExterno = $this->emailService->getBody($emailId);

// Processar com API fluente
$htmlSeguro = Crawler::parse($htmlExterno)
    ->sanitize()                              // Remove scripts e event handlers
    ->removeElements('style, .tracking-pixel') // Remove elementos específicos
    ->addAttribute('img', 'loading', 'lazy')  // Lazy loading em imagens
    ->addAttribute('a[target="_blank"]', 'rel', 'noopener') // Segurança em links
    ->html();

return view('emails.show', ['content' => $htmlSeguro]);

Sanitização

A sanitização é crucial quando mostras HTML de fontes não confiáveis. Sem ela, um atacante pode injectar JavaScript malicioso que corre no contexto da tua aplicação — o famoso ataque XSS (Cross-Site Scripting).

O Que o sanitize() Remove?

  • • Tags perigosas: <script>, <iframe>, <object>, <embed>
  • • Event handlers: onclick, onload, onerror, etc.
  • • URLs JavaScript: href="javascript:..."
  • • Data URIs em imagens: Podem esconder código malicioso
// Antes: HTML potencialmente perigoso
$html = '<div onclick="alert(1)">Texto</div><script>malicious()</script>';

// Depois: HTML seguro
$safe = Crawler::parse($html)->sanitize()->html();
// Resultado: '<div>Texto</div>'

Reescrita de URLs

Quando crias um proxy de conteúdo (para mostrar páginas externas dentro do ERP, por exemplo), precisas que todos os links e recursos passem pelo teu servidor. O método rewriteUrls() faz isto automaticamente.

Exemplo de Proxy

$proxyBase = 'https://meuapp.com/proxy?url=';

$htmlOriginal = '<a href="https://externo.com/pagina">Link</a>
<img src="https://externo.com/imagem.jpg">';

$htmlProxied = Crawler::parse($htmlOriginal)
    ->rewriteUrls($proxyBase)
    ->html();

// Resultado:
// <a href="https://meuapp.com/proxy?url=https://externo.com/pagina">Link</a>
// <img src="https://meuapp.com/proxy?url=https://externo.com/imagem.jpg">

O rewriteUrls() é inteligente: também processa URLs em CSS inline e atributos srcset de imagens responsivas.

Extracção de Dados

Além de manipular, o Crawler também pode extrair informação estruturada do HTML. Isto é útil para web scraping, análise de emails, ou indexação de conteúdo.

Extrair Metadados

Obtém título, descrição, Open Graph e Twitter Cards de uma página. 

$meta = Crawler::parse($html)->extractMeta();

// Resultado:
// [
//     'title' => 'Título da Página',
//     'description' => 'Descrição meta...',
//     'og' => [
//         'title' => 'OG Title',
//         'image' => 'https://...',
//     ],
//     'twitter' => [...]
// ]

Extrair Links e Imagens

// Todos os links
$links = Crawler::parse($html)->extractLinks();
// [['text' => 'Clique aqui', 'href' => 'https://...', 'rel' => 'noopener'], ...]

// Todas as imagens
$images = Crawler::parse($html)->extractImages();
// [['src' => 'https://...', 'alt' => 'Descrição', 'width' => 800], ...]

// Converter para texto simples (remove todas as tags)
$text = Crawler::parse($html)->toPlainText();
Paginação Utilities