Referrer Spam Blacklist Laravel Package

Product Decisions This Supports

• Analytics integrity as a product decision. The headline value isn't security, it's decision-quality: referrer spam inflates sessions, skews acquisition reports, and makes channel attribution look better than it is. If your roadmap or pricing is informed by traffic sources, a dirty referrer field is a measurement bug — this package is a cheap fix for the long tail of it.
• Build vs. buy on deny-list curation. The code is trivial (a plain-text hostname list, zero runtime dependencies). The asset is the curated content and the community pipeline behind it. 4.0.5 is a pure data refresh — "Added more spammers to the list" — which is exactly the maintenance work you'd otherwise assign to someone and forget about. That argues for consuming the vendor's cadence rather than owning curation.
• Release cadence as a dependency-risk input. A patch release containing only data, with no API or schema change, is a healthy signal: the project is in maintenance mode with a live list-updating process, not abandoned and not churning. Useful for your "do we keep this dependency?" review.
• Near-zero upgrade cost, so it doesn't compete for sprint capacity. Semver patch, no config surface, no migration. It rides the routine Composer update. When you're negotiating engineering capacity, this is a line item you can defend as free.
• Where it fits in a Laravel product: filtering inbound referrer values before they hit your analytics tables, your leads/contact_messages tables, or a queued enrichment job — anywhere an unauthenticated Referer header or a self-reported source field lands in data you later report on. Think lead-gen forms, guest comments, review submissions, affiliate/referral self-reporting.
• Explicit non-goal to record. This does not improve security posture. Referrer values are client-controlled and trivially spoofed, so treat it as noise reduction on data quality, never as an abuse-prevention control. Writing that down prevents a future stakeholder from assuming you've "done something about bots."

When to Consider This Package

Adopt when:

• Your funnel reports or dashboards are measurably polluted by known spam referrers and someone has already spent time manually excluding domains.
• You have unauthenticated input surfaces and want a dependency-light, no-third-party-network-call filter that adds zero friction to the real user journey (a genuine conversion consideration versus CAPTCHA-style alternatives).
• Your stack is already Composer-based (Laravel or otherwise) and consuming a static list is architecturally unremarkable.
• You're comfortable with vendor-cadence freshness and a deny-list you don't audit line by line.

Look elsewhere when:

• The need is genuinely adaptive bot defense — rate limiting, device fingerprinting, ML risk scoring, coordinated-attack response. That's a WAF/bot-management purchase, not a text file.
• You require a contractual freshness SLA, change review, or an appeal/override path for blocked entries. A static list in a patch release gives you none of these.
• False positives would be expensive — e.g., partner or affiliate referral domains that could plausibly appear on a community-curated list. You'd need an allowlist layer and an owner for it.
• You need per-decision observability: what was filtered, why, and how to un-filter it. Assume you instrument around this yourself.
• You expected framework integration. This is a data package, not a Laravel package with a service provider, config file, or published middleware. The wiring (a small validator, middleware, or an import job) is your code to own and maintain — budget a few hours, not zero.
• Diligence flag: it shows 0 dependents on Packagist. That doesn't mean unused — it's commonly pulled in directly or vendored by Matomo itself — but it does mean you can't infer ecosystem support from install counts. Validate the list against your own traffic before committing.

How to Pitch It (Stakeholders)

For executives: A low-cost data-quality fix for our public-facing forms and referral tracking. It's a maintained deny-list of known spam referrers that keeps junk out of our analytics, CRM, and support queue — no CAPTCHA, no extra user friction, no measurable conversion impact. The latest release, 4.0.5, is a routine data refresh, so there's no migration and nothing to schedule. Framing matters: this makes our numbers trustworthy, it isn't a security investment. If we later see targeted or adaptive abuse, this is a baseline hygiene layer, not a strategy, and we'll come back with a proper bot-management evaluation.

For engineering: A Composer package containing a curated plain-text hostname list with no runtime dependencies — in practice a data feed, not a library. On a mature 4.x line; 4.0.5 is data-only (more spammer entries, no API/config/schema changes), so it's a safe patch bump on the normal dependency train. Integration in Laravel is our own thin layer — a middleware or validator that normalizes the Referer host and checks it against the list before it reaches analytics or lead storage — so treat it as a small piece of owned code plus a list import, not a drop-in. Two explicit tradeoffs to record: we're accepting a vendor-curated opaque list in exchange for not owning curation, and we should add light instrumentation (count of filtered referrers, sample of blocked hosts) so we can catch false positives and prove it's doing something. Also log the assumption that referrer data is client-controlled and spoofable — this reduces report noise, it does not prevent abuse.