Zest Jq Laravel Package

Technical Evaluation

Architecture fit. wikimedia/zest-jq is not a Laravel package — it is a standalone PHP library providing a jQuery-style fluent wrapper over CSS selector queries against a DOM document (built in the Wikimedia Zest/MediaWiki ecosystem). There is no service provider, facade, config file, or publishable asset. Architecturally that is fine, but it means the package lives as a leaf dependency inside a single domain service class rather than participating in Laravel's container or lifecycle. Treat it as a utility, not infrastructure.

Integration feasibility. Composer-installable with PSR-4 autoloading and an MIT license, so legal/procurement friction is essentially zero. The real feasibility question is the transitive dependency graph: verify in composer.json whether it requires ext-dom, ext-libxml, RemexHtml (Wikimedia's HTML5 parser), or the underlying Zest selector engine. Anything pulling RemexHtml adds weight and a second Wikimedia library to track. Also confirm the PHP version constraint against your Laravel runtime (Laravel 10/11/12 → PHP 8.1+); a library last targeted at PHP 7.x may install cleanly but is effectively untested on your runtime.

Technical risk — this is the dominant factor. The repository is an explicit read-only GitHub mirror; development happens on Gerrit. Consequences: no GitHub issue tracker, pull requests will not be merged, and there is no visible roadmap or release cadence on the mirror. With 1 star and 0 dependents, there is no community safety net — no Stack Overflow corpus, no third-party blog coverage, no downstream projects absorbing breaking changes. The opportunity score (47.78) against an overall score of 0.005 signals a library that is technically interesting but functionally unadopted. Practically: if you need a bug fixed, you fork it, and you own it thereafter.

Additional risk surface: parsing untrusted HTML through DOMDocument/libxml carries the usual entity-expansion and malformed-markup failure modes; and a CSS selector engine will not match browser semantics exactly (pseudo-classes, :has(), case sensitivity in attribute selectors), which creates silent divergence between what your tests expect and what users see.

Key questions for the maintainer/team:

1. What is the actual dependency tree, and does it drag in RemexHtml or Zest as separate versioned packages?
2. Does it parse real-world malformed HTML5, or only well-formed XML/DOM input?
3. Which selector subset is supported relative to symfony/css-selector?
4. Is there any tag/release history on Gerrit, and does the project publish SemVer intent?
5. What is the concrete use case that symfony/dom-crawler + symfony/css-selector cannot satisfy? If there is no compelling answer, this evaluation should end there.

Integration Approach

Stack fit. Best suited to server-side HTML post-processing: transforming rendered Blade output, sanitising/normalising email templates, or manipulating third-party HTML fragments before storage. It is a poor fit for scraping at scale or for anything requiring browser-accurate selector semantics.

Migration path. Two realistic entry points: (a) replacing regex-based HTML manipulation in an existing service, or (b) porting jQuery-style DOM logic that currently runs client-side into a server-side render pipeline. In both cases, do not let ZestJQ types leak into your domain code. Define a narrow internal interface (e.g. HtmlSelector::select(string $html, string $selector): array) and implement it once against ZestJQ. This makes a later swap to symfony/dom-crawler a one-class change, which is the single most important design decision given the maintenance profile.

Compatibility. Namespacing is Wikimedia\..., so collision risk is nil. Pin an exact version (or a commit hash) in composer.json — with no release discipline visible on the mirror, ^1.0 style constraints are unsafe. Run composer why-not php and a composer update --dry-run against your actual platform requirements before committing.

Sequencing:

1. Spike (1–2 days): install in a scratch branch, run it against 20–30 representative production HTML samples, and compare selector results against symfony/css-selector on the same inputs.
2. Decision gate: if the spike shows no measurable advantage over Symfony's crawler, stop — take the well-supported dependency.
3. Adapter + tests: wrap behind your own interface; build a fixture-based test suite that pins current behaviour so an upstream or fork change is detectable.
4. Narrow rollout: one non-critical code path, feature-flagged, before any user-facing surface.
5. Fork contingency: if the spike succeeds and you need changes, fork to your VCS with a documented sync process against Gerrit.

Operational Impact

Maintenance. This is the ledger item that will cost you. Upstream lives on Gerrit with a MediaWiki-shaped contribution process (Gerrit accounts, Phabricator). Your team's GitHub-native workflow does not apply. Budget for one engineer to own the dependency, and assume that any fix beyond a trivial patch becomes an internal fork. The mirror may also lag or stop syncing without notice.

Support. No vendor, no SLA, no GitHub issues. Escalation path is a Gerrit patch review on a volunteer-maintained Wikimedia library — acceptable for a MediaWiki extension, marginal for a commercial Laravel product.

Scaling. DOM construction is memory-bound and per-document. Fine for per-request fragments in the kilobyte-to-low-megabyte range; do not use it inside queue workers processing large batches without chunking, and do not expect any caching layer — memoise parsed results yourself if the same document is queried repeatedly. Profile against your PHP-FPM memory limit early; libxml node trees are considerably heavier than the source string.

Failure modes to instrument:

• Malformed HTML → exceptions or silent partial trees (test with genuinely broken markup, not tidy fixtures).
• Selector semantics drift → a selector that works in the browser returns nothing server-side; assert on output, not on "no exception."
• PHP/libxml version drift on base-image upgrades → behaviour changes without a package version change.
• Untrusted input → entity expansion and external-entity risk; disable network access and entity loading explicitly, and never feed it unsanitised user HTML.
• Namespace or API changes on a Gerrit-side refactor with no changelog.

Ramp-up. Low. The jQuery-like API is familiar to most web developers, so the fluent chain is readable within hours — call it half a day to first productive use. The hidden cost is documentation: expect to read the source and the test suite to understand supported selectors and edge-case behaviour, adding perhaps another day for the engineer who owns the adapter and its fixtures.

TPM recommendation. Approve only for a single, well-bounded HTML-manipulation use case where a spike demonstrates a concrete advantage over symfony/dom-crawler, and only behind an internal interface with an exit path. Do not adopt it as a general-purpose HTML layer, and do not let it become load-bearing without a named internal owner and a tested fork strategy.