Dom Laravel Package

Getting Started

Start by installing via Composer: composer require zenstruck/dom. The primary entry point is the Zenstruck\Dom\Dom class — instantiate it with HTML using Dom::fromHtml($markup) or from a response body. Your first step is typically parsing and extracting data:

$dom = Dom::fromHtml($html);
$title = $dom->find('h1')->text();

For Laravel, integrate it directly into feature tests: fetch a page with ->get(), pass ->response()->original’s content, and validate structure without browser automation.

Implementation Patterns

• Test-driven DOM assertions: Use built-in assertions in Laravel tests for HTML validation:

  $dom = Dom::fromHtml($this->get('/products')->content());
  $dom->assert()->count('.product-card', 10);
  $dom->find('.hero-title')->assert()->contains('New Collection');
  

• Batch extraction with collections: Chain findAll() → map() for structured data:

  $items = $dom->findAll('.item')->map(fn ($node) => [
      'name' => $node->find('.name')->text(),
      'price' => $node->find('.price')->text(),
  ]);
  

• Extensibility for domain logic: Wrap repeated patterns into custom methods:

  class Dom extends \Zenstruck\Dom\Dom {
      public function findPrice(): ?string { return $this->find('.price')->text(); }
  }
  

• HTTP client synergy: Combine with Laravel’s Http for scraping:

  $html = Http::get($url)->body();
  $dom = Dom::fromHtml($html)->assert()->success();
  

Gotchas and Tips

• No built-in HTML5 repair: Unlike Symfony’s DomCrawler, malformed HTML may cause silent failures — use Dom::fromHtml($html, true) if the second arg enables HTML5 parsing, or preprocess with tidy.
• Collection vs node behavior: findAll() returns an iterable collection — assertions like ->assert()->text(...) operate on each node, not collectively. Use first() or last() to assert on a single element.
• Whitespace artifacts: Text nodes often contain newlines/indentation — always use ->text(true) (if trim-aware) or wrap extraction: trim($node->text()).
• Namespace pitfalls: For XML feeds/SVG, Dom::fromXml() requires explicit namespace registration in XPath-like selectors — verify syntax in tests.
• Sparse docs but intuitive API: With limited community support, rely on the source code’s inline docblocks (often more complete than README). Check Dom::extend() for custom method hooks — invaluable when core functionality lags.
• Assert() context matters: ->assert()->exists() checks the current selector context — avoid chaining findAll() before assertions unless intentional. Preface with find() for precision.