Product Decisions This Supports
- Build vs. buy for HTML extraction: Gives you a jQuery-style selector API (
pq('div.item > a')->attr('href')) for pennies of integration effort, so a scraping/extraction feature can ship without building a DOM traversal layer or adopting a full crawler framework.
- Scraper architecture choice: It is effectively the DOM engine behind QueryList. If your roadmap includes content aggregation, price/listing monitoring, SEO auditing, or data ingestion from third-party pages, this is a low-commitment way to validate the use case before investing in a maintained stack.
- Buy/borrow decision on the whole QueryList stack: Adopting this package is usually a proxy decision for "do we standardize on QueryList for crawling?" Treat it as a trial balloon, not an independent technology choice.
- Legacy-compatibility roadmap calls: Useful where the constraint is an old PHP runtime, no Composer-first autoloading discipline, or shared hosting with tight deployment rules — a single-file, drop-in library removes infrastructure work from the critical path.
- Technical-debt triage: Because this wraps an unmaintained upstream (phpQuery, essentially frozen since the PHP 5 era), adopting it creates a known future migration item. That belongs in your debt register up front, not discovered during a PHP upgrade.
- Opportunity sizing (deprioritize): With ~140 stars, a low opportunity score (~22), and no meaningful dependent ecosystem in the index, this is not a signal of a growing standard. Do not build a platform strategy or public API surface on it.
When to Consider This Package
Adopt when most of these hold:
- You are already on, or explicitly evaluating, QueryList — this is its dependency, and mixing versions of phpQuery independently is a recipe for global-class collisions.
- The work is an internal tool, prototype, or one-off scraper with a bounded lifetime (weeks to a few months), not a customer-facing contract.
- You need jQuery-familiar selectors and your team's PHP skill set is stronger in jQuery/CSS selectors than in XPath or
DOMDocument traversal.
- You are on a legacy runtime or constrained host and a single-file, no-frills library materially reduces deployment risk.
- Your inputs are known, trusted, or low-stakes HTML — or you are prepared to sandbox/sanitize externally.
Look elsewhere when:
- You need long-term support, security patching, or PHP 8.x+ guarantees. Upstream phpQuery is dormant; verify compatibility yourself and assume no fixes are coming.
- You need PSR-4 namespacing, dependency isolation, or clean testability — the single-file/global-class model (
pq(), global phpQuery) fights modern codebases and parallel test runs.
- You are parsing untrusted or adversarial HTML at scale, where parser correctness and DoS resistance matter.
- You need HTML5 conformance for malformed markup — evaluate
symfony/dom-crawler + symfony/css-selector, Masterminds/html5, DiDom, or PHP 8.4's native Dom\HTMLDocument instead.
- You want an active maintainer and a visible roadmap — none of that exists here.
- You need throughput at high volume; measure before committing, since you inherit an old parser's performance profile.
How to Pitch It (Stakeholders)
For executives: We can validate an HTML-extraction use case in days rather than weeks, at near-zero licensing cost (permissive open source), by leaning on a mature, jQuery-style API our engineers already know. The trade-off is that this is a tactical dependency, not a strategic platform bet: the underlying library is unmaintained, ecosystem momentum is negligible, and adopting it books a future migration. Recommendation: approve for a time-boxed internal pilot, not for anything customer-facing or long-lived.
For engineering: This is the single-file Composer packaging of phpQuery, and it is the DOM layer QueryList depends on. Practical guidance: pin the version, isolate all selector logic behind a thin internal adapter interface, add fixture-based tests that don't depend on its globals, and avoid importing pq() throughout the codebase so a swap to Symfony DomCrawler (or native Dom\HTMLDocument on PHP 8.4+) is a single-file change. Do not fork or patch unless you are prepared to own it permanently.
Decision requested: Approval to prototype behind an adapter, with an explicit review gate at the end of the pilot that asks one question — does the extraction feature earn a maintained replacement?