Hquery Laravel Package

Product Decisions This Supports

• Build vs. buy for data acquisition. hQuery gives you the parsing half of a scraping pipeline in-house, with zero licensing cost and no vendor lock-in. It shifts spend from per-request scraping APIs (ScrapingBee, Apify, Zyte) to engineering time, which is the right trade when volume is high and extraction logic is stable.
• Feature scoping for "import from web/HTML" capabilities. Any roadmap item that ingests HTML — competitor price monitoring, catalogue ingestion from supplier portals, job-board aggregation, real-estate listing feeds, content migration — can be scoped against what hQuery can and cannot do out of the box.
• Replacing fragile regex scraping. A common PM-visible symptom is a scraper that breaks every time a site changes markup. Moving to CSS-selector-based extraction is a maintainability decision, not just a technical one, and it directly reduces on-call load and incident frequency.
• HTML-to-structured-data features inside the product. If your product parses customer-supplied HTML (email templates, exported reports, invoice HTML, CMS exports, RSS/Atom bodies), this is a candidate extraction engine that avoids adding a DOM-extension or Symfony DomCrawler dependency.
• Test-fixture tooling. Teams maintaining scrapers need to assert against saved HTML snapshots; a fast, dependency-free parser is a legitimate choice for the test harness as well as production.
• Roadmap gating for JS-heavy targets. Because hQuery does not execute JavaScript, it clarifies which scraping use cases belong on the roadmap and which require a headless-browser investment (Playwright/Puppeteer service) — a materially different cost and infrastructure story.
• Prioritising where not to invest. The package's low adoption (359 stars, 0 dependents) is a signal: treat it as a utility, not a platform bet. Do not build a product strategy around it; do build tactical features with it.

When to Consider This Package

Adopt when:

• You are on PHP (including legacy PHP 5/7 estates) and want HTML extraction without adding Composer dependencies or requiring ext-dom/libxml tuning.
• Throughput and memory matter — bulk ingestion of large or numerous HTML documents where parse time is a measurable bottleneck.
• Your extraction needs are selector-shaped (classes, IDs, attributes, descendant/child combinators, :first, :eq, attribute operators) and map cleanly onto a jQuery-style mental model your frontend engineers already have.
• You want a thin, auditable dependency surface in a security-sensitive or compliance-constrained environment.
• The work is batch/offline: nightly crawls, ETL, report generation, migration scripts.

Look elsewhere when:

• JavaScript-rendered pages are in scope. hQuery sees only the HTML you hand it. You need a browser-automation layer regardless; adding hQuery underneath it is optional.
• You need full CSS3 or rigorous standards compliance. hQuery implements a practical subset, not the spec. Complex :nth-child chains, pseudo-elements, and edge-case selector semantics will surprise you. Symfony DomCrawler + CssSelector, or DOMDocument + XPath, is the safer choice for standards-critical work.
• You need an end-to-end scraping framework. There is no HTTP client, retry/backoff, proxy rotation, rate limiting, robots.txt handling, or queue. Those are yours to build or buy separately.
• Maintenance and longevity are hard requirements. Low star count, no dependents, and a small maintainer base mean bus-factor risk. For a multi-year core dependency, prefer an actively maintained library.
• You need modern PHP ergonomics — typed APIs, PHP 8 attributes, async/concurrent parsing, or framework integration (Laravel service provider, facades, testing helpers). Expect to write a small adapter yourself.
• Security posture demands hardened parsing of hostile input. It is a parser for untrusted HTML; validate its behaviour under your threat model and pin the version.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed, zero-dependency PHP library that turns raw HTML into structured data very quickly. It lets us build web-data ingestion features — price monitoring, supplier catalogue import, content migration, HTML report parsing — without per-request fees to a scraping vendor and without adding third-party code to our supply chain. The cost is engineering time, not licence spend, and the risk is contained: it is a utility we can swap out behind a thin internal interface if it stops being maintained.

To engineering: It is a jQuery-style selector engine for HTML in PHP — no Composer dependencies, PHP 5+, extremely fast on megabyte-scale documents, and familiar to anyone who has written front-end selectors. It covers the practical CSS selector subset most scrapers actually use and gives you attribute/text extraction directly. It deliberately does not do HTTP, JavaScript rendering, proxies, or the full CSS3 spec, so we pair it with our existing HTTP layer and keep a headless browser for JS-heavy targets. Recommend wrapping it behind an internal HtmlExtractor interface so we are not coupled to it, pinning the version, and fuzzing it against hostile markup before it touches customer input.