Utils Bundle Laravel Package

Getting Started

• Install with Composer (composer require the package) — Laravel package auto-discovery registers the service provider, so no manual wiring is needed in a standard app.
• Read the README section on finding/extracting HTML tags first; the 7.5.0 release focuses on that code path, so start with the tag-finding API rather than the broader config surface.
• Publish any config only if you need to override defaults (php artisan vendor:publish --tag=...); for a first integration the defaults are usually sufficient.
• First use case: take a string of user- or CMS-supplied content, locate the HTML tag you care about (e.g. confirm a <script>/<iframe>/wrapper tag exists, or extract a fragment), and act on it in a controller or form request.

use Vendor\Package\FindHtmlTagException;

try {
    $tag = $finder->find($content); // returns the located tag/fragment
} catch (FindHtmlTagException $e) {
    // 7.5.0: failure is now signalled explicitly
    report($e);
    $tag = null;
}

Implementation Patterns

• Fail-fast validation: Call the tag finder inside a FormRequest or dedicated validator rule, catch FindHtmlTagException, and convert it to a validation error (422) rather than letting a 500 bubble up.
• Encoded-entity inputs: Content arriving from WYSIWYG editors, JSON APIs, or stored CMS fields is often entity-encoded (<div>). As of 7.5.0 the package resolves these correctly, so pass the raw string through instead of pre-calling html_entity_decode().
• Service wrapper: Wrap the finder in a small application service (HtmlTagInspector) so exception handling, logging, and any pre/post-processing live in one place and call sites stay clean.
• Pipeline integration: Use it as a step in a content-sanitization or import pipeline — detect tags first, then hand off to your sanitizer/cleaner. Keep the "find" and "mutate" concerns separated.
• Queued/background parsing: For large HTML documents (email bodies, imported pages), run tag-finding in a queued job and record failures via the exception rather than swallowing them.
• Testing: Add fixtures containing literal tags and encoded entities (<, <) to lock in the 7.5.0 behaviour, and assert FindHtmlTagException is thrown for malformed input.

Gotchas and Tips

• Behavioural change in 7.5.0: the package now throws FindHtmlTagException when it cannot find a tag. Code that previously relied on a silent null/false return will now surface an exception — audit every call site after upgrading and add try/catch where a missing tag is a normal outcome.
• Don't double-decode: the entity fix means calling html_entity_decode() yourself before passing content can change what the finder sees. Remove old workarounds and let the package handle encoded entities.
• Catch the specific type: catch FindHtmlTagException, not \Exception, so genuine bugs aren't masked as "tag not found".
• Log context, not just the message: when catching, include the input length/content type in your log — the exception indicates a parsing problem, and reproducing it needs the source string.
• Config caching: if you publish and edit config, run php artisan config:cache (and clear it in local dev) or changes won't take effect.
• Version pinning: pin to ^7.5 in composer.json so the new exception contract and entity handling are guaranteed; check the changelog before jumping minor versions.
• Extension point: if the package exposes custom matchers or callbacks, keep them in your wrapper service rather than scattering them across controllers — this makes future breaking changes (like this exception addition) a one-file fix.