Ignore Query Strings Laravel Package

Getting Started

• Install with composer require fdmind/ignore-query-strings. This is a new major (v3.0.0), so pin the constraint (^3.0) and read the README/CHANGELOG/UPGRADE notes before upgrading an existing install — config keys and defaults changed.
• Look first at the published config file. v3 adds two new concepts you need to see: safe params (defaults: page, q) and safe paths / URI path exclusions (defaults covering glide and cp-style routes). Run php artisan vendor:publish --tag=ignore-query-strings-config --force and diff against your current config rather than blindly overwriting.
• Then inspect the middleware class itself: check whether path exclusions are exact-match or prefix-match, whether matching is case-sensitive, and how it escapes param keys (see Gotchas).
• Register the middleware early in the web group, or scoped to public marketing routes only.
• First use case: /?utm_source=facebook&utm_campaign=spring&fbclid=abc should resolve to the same cached page as /, while /?utm_source=facebook&page=2 must still behave as page 2 (now protected by the default safe params). Verify with curl -I on all three and compare cache headers and redirect behavior.

Implementation Patterns

• Lean on the new defaults as a baseline, then extend: keep the built-in page and q, and add your app's real state params (sort, filter, category, locale, currency, page[size], s, query, offset) to the safe list. Defaults cover the common cases, not your app.
• Use URI path exclusions as your primary safety control for stateful areas: /admin, /cp, /checkout, /cart, /account, /api, /livewire/*, /filament/*, image-transform routes (Glide-style /img/...), signed asset/preview routes, and auth callbacks. Path exclusions are easier to reason about and audit than a growing param blocklist.
• Keep the default safe paths for glide and cp unless you have remapped those routes — if you mount your control panel or image CDN elsewhere, add your own paths and verify the defaults don't accidentally shadow a public route.
• Place the middleware before your response-cache or static-cache middleware. The cache lookup must see the normalized URI, otherwise it still misses.
• Apply by route group, not globally: landing pages, blog posts, public marketing pages. Exclude search results, filters, pagination, signed URLs, payment returns, previews.
• Preserve attribution before stripping. If the redirect drops utm_*/gclid before analytics JS runs, capture campaign data server-side (session, CRM, event pipeline) or have your analytics tool forward it.
• Pair with edge cache config. Cloudflare/Fastly/Nginx still key on the query string unless told otherwise; normalization in PHP won't help a request served at the edge.
• Tests to add: tracking URL hits canonical cache entry; ?page=2 and ?q=shoes are preserved by default; a custom safe param is preserved; an excluded path is untouched; signed URLs pass through; param keys containing regex metacharacters (utm.source, fbclid[0], a+b) match literally; no redirect loops.

Gotchas and Tips

• v3 changes default behavior: page and q are now safe out of the box. If your config previously re-listed them, remove duplicates, and re-run any test that asserted q was stripped.
• The regex-escaping fix means param keys are now matched literally. If you were (intentionally or not) relying on pattern behavior like utm_.* or gclid|fbclid inside a single key, that will silently stop matching as a wildcard. Confirm in the source whether wildcards are supported explicitly; if not, enumerate keys.
• Path exclusion semantics matter more than the list itself: test /admin vs /admin/ vs /Admin vs /admin/users?utm_source=x, and confirm the query string isn't considered part of the path during matching.
• Middleware order is still the most common failure. Confirm with php artisan route:list -v and inspect the HTTP kernel/group order.
• Never globally strip query strings. Search, pagination, filters, locale, currency, signed URLs, OAuth callbacks, and payment returns all depend on them.
• Redirect side effects: 301 gets cached hard by browsers and hurts future attribution; prefer 302 for campaign stripping. Watch for loops if the query string is reintroduced downstream.
• Avoid this on authenticated/private pages — stripping user-specific params or tokens risks cache poisoning. Anonymous public pages only.
• After editing config run php artisan config:clear, and clear the response cache when validating or stale entries will mask the result.
• Debug with curl -I and cache headers (X-Cache, Age, Cache-Control), plus logging of the original vs normalized URI. Compare first (uncached) and second request for both clean and tracking URLs.
• Treat the major bump as a real upgrade: review the source diff, keep the ignored/safe lists in app config or env, and wrap app-specific normalization in your own middleware so a future package release can't change your cache behavior underneath you.