Url Highlight Symfony Bundle Laravel Package

Getting Started

This release is a dependency bump: the package now requires Url highlight v3. There is no new first-party API described in the release notes, so treat v3.0.0 primarily as a compatibility release — the Laravel wrapper surface (facade/helper/config) is expected to be unchanged, while the underlying highlighting engine has moved to a new major version.

Minimal steps:

1. composer require <vendor>/<package>:^3.0 and let Composer resolve url-highlight ^3.0.
2. If you published the config previously, re-publish and diff it: php artisan vendor:publish --tag=<package>-config --force (inspect before overwriting).
3. Smoke-test the one call site you almost certainly have — rendering user text with clickable links:

{!! $highlighter->highlight(e($comment->body)) !!}

4. First use case to validate: a comment/description field containing bare URLs, rendered in Blade. Confirm links are produced, rel="nofollow noopener" (or your configured attributes) are applied, and trailing punctuation is not swallowed into the href.

Where to look first: the package's composer.json constraint on the underlying library, then the upstream Url highlight v3 changelog/UPGRADE notes — that is where any behaviour change will actually live. The Laravel wrapper rarely changes independently of its engine.

Implementation Patterns

Render-time highlighting (most common). Keep stored content raw and highlight on output. This lets you change link behaviour (attributes, target, CSS class) without a data migration.

{!! UrlHighlight::highlight(e($post->body)) !!}

Escape before highlighting — the highlighter's output is intentionally HTML.

Accessor / API resource pattern. If the same field is rendered in Blade, JSON, and emails, centralise it:

public function getBodyHtmlAttribute(): string
{
    return UrlHighlight::highlight(e($this->body));
}

Then expose it via an API Resource so web and mobile clients agree on linkification. Beware double-escaping if a consumer escapes again.

Pipeline placement. Highlight late. Order should be: sanitise → highlight → (optionally) markdown. Running the highlighter before sanitisation means your sanitiser may strip the <a> tags it just created; running it on already-rendered HTML risks mangling existing anchors and attributes.

Chunked processing for long text. Highlighting is regex-driven; for large documents (imported articles, log viewers) split on paragraph boundaries and highlight per chunk rather than one multi-megabyte string.

Testing. Pin behaviour with a data provider rather than asserting on a full HTML string — upstream major versions change attribute order and edge-case matching:

#[DataProvider('urls')]
public function test_highlights_urls(string $input, string $expectedHref): void { /* ... */ }

Include cases for: bare domain vs scheme, https:// only, trailing ./,/), URLs in parentheses, query strings with &, and non-URLs that look like domains (file.php, v1.2.3).

Caching. Highlighted HTML is deterministic for a given engine version and config. If you render the same content repeatedly (feeds, sitemaps, newsletters), cache the highlighted string and bust the cache on content update — and on package upgrade, since v3 may legitimately produce different output for the same input.

Gotchas and Tips

• This is a major version bump with a one-line changelog. The absence of detail is the risk. Before merging, read the upstream Url highlight v3 release notes directly: look for removed/renamed methods, changed constructor signatures, new required config keys, and a bumped PHP minimum. Composer will surface the PHP constraint immediately; it will not surface behavioural changes.
• Output may change even though your code doesn't. v3 can match different URL shapes, alter default rel/target attributes, or change how trailing punctuation and IDNs are handled. Any test asserting exact HTML will fail — that's the canary, not the bug. Regenerate snapshots deliberately and review the diff.
• XSS is the classic failure here. Highlighting produces HTML. If you ever call it on unescaped user input, you have created a link-injection vector (javascript: scheme, attribute-breaking quotes). Escape first, always, and consider an allowlist of schemes if the underlying library permits configuration.
• Don't run it on trusted HTML. Existing <a href="..."> anchors, code blocks, and <pre> content will be re-processed or corrupted. Highlight plain text only, or strip/placeholder protected regions first.
• Email vs web mismatch. mailto: detection and URL-vs-email ambiguity is a recurring upstream edge case; check both renderers if you highlight in notifications.
• Extension points. Most of these wrappers expose a custom renderer/highlighter binding or a config-driven attribute set. That is the right place to add rel="nofollow noopener", target="_blank", or a CSS class — not string post-processing on the returned HTML.
• Debugging tip. If links stop appearing entirely after upgrade, check in this order: config not re-published, a scheme allowlist defaulting tighter in v3, and the underlying library being pinned back by another dependency (composer why url-highlight).
• Lock the underlying version in CI and add one integration test that asserts a known URL becomes an anchor. It is the cheapest guard against the next silent major bump.