Utils Bundle Laravel Package

Product Decisions This Supports

• Content-ingestion and authoring features: Any roadmap item that needs to locate, validate, or index specific HTML tags inside a string (heading extraction for SEO/TOC, template linting, rich-text normalization, email/notification builders) can lean on this package instead of bespoke regex. The 7.5.0 fix for encoded HTML entities (<, &, etc.) directly reduces false negatives in user-generated or CMS-sourced content, which is where these features usually break.
• Build vs. buy: Reinforces "buy/borrow" over "build" for tag-finding logic. HTML parsing edge cases (entities, malformed markup) are a known tar pit; a maintained package with typed error handling is cheaper than owning regex maintenance.
• Reliability investment for existing surfaces: The new FindHtmlTagException converts silent/ambiguous failure modes into catchable, observable errors. That supports a small roadmap item to add explicit error handling, logging, and user-facing fallbacks wherever tag detection feeds a feature (e.g., "we couldn't analyze your content" states).
• Risk/upgrade decision: 7.5.0 is a semver-minor, additive release — no migration work. PM call is a routine dependency bump, contingent on engineering confirming no code path relied on the previous non-throwing behavior.
• Deprioritization signal: Because the package handles entity decoding and error signaling itself, we can defer building an in-house content-parsing utility and redirect that effort to higher-value differentiators.

When to Consider This Package

Adopt when:

• You are on PHP/Laravel and need to find or validate specific tags in HTML strings as part of content processing, not to render or manipulate a full document.
• Your inputs include real-world content with encoded entities — the 7.5.0 fix is precisely the class of bug that bites in production.
• You want failures to be explicit: the new exception lets you distinguish "tag not found / parse problem" from "no match," enabling better UX and monitoring.
• The team is comfortable catching a package-specific exception in feature code.

Look elsewhere when:

• You need full DOM traversal, mutation, or CSS-selector querying — use DOMDocument, Symfony DomCrawler, or a mature HTML parser instead.
• The requirement is security sanitization (XSS prevention). A tag finder is not a sanitizer; pair with HTMLPurifier or an equivalent allow-list sanitizer.
• You need to execute or render JavaScript-dependent markup (headless browser territory).
• You are not on PHP/Laravel, or you need a vendor-supported SLA — this is a community package and should be treated as such in risk reviews.
• Inputs are strictly controlled and schema-validated upstream, making the added dependency low value.

How to Pitch It (Stakeholders)

To executives: This is a low-risk, no-cost dependency upgrade. It fixes a real-world bug (content containing encoded HTML entities was being misread) and adds proper error reporting so failures surface in logs instead of silently degrading a feature. No migration, no timeline impact — a routine bump we can fold into the next maintenance window. It also lets us avoid building and maintaining our own HTML parsing utility.

To engineering: 7.5.0 is additive and backwards-compatible in API terms, but note the behavioral shift: code paths that previously failed quietly may now throw FindHtmlTagException. Audit any call sites involved in tag detection, add targeted try/catch with logging and a graceful fallback, and add a fixture test with encoded entities (<div>, &) to lock in the fix. Keep the package scoped to tag-finding; route sanitization and DOM manipulation to the tools already designated for those jobs.