Murmurhash Laravel Package

Product Decisions This Supports

Feature-level decisions

• Deterministic cohort assignment for A/B tests, feature flags, and progressive rollouts. Hashing experiment_id + user_id gives a stable 0–99 bucket with no database lookup, no sticky-session infrastructure, and identical results across every app server, queue worker, and Lambda. This is the single highest-leverage use: it turns "we need a flags service" into afternoons of work.
• Cache key generation and normalization for CDN/Redis keys where key length and CPU cost matter (URLs, serialized payloads, long query strings).
• Deduplication and fingerprinting of non-adversarial payloads — import files, webhook bodies, log lines — where you need fast equality checks, and where "rare collision" is an acceptable tradeoff for speed.
• Bloom filter / negative-cache layers to protect a database from penetration by nonexistent-key lookups; these structures need several independent, well-distributed hashes per key, which is exactly what seeded MurmurHash3 provides.
• Rate-limit bucket keys and log sampling (hash the request ID, keep the bottom N%).

Roadmap-level decisions

• Sharding and partition-count changes. Consistent hashing rings and modulo partitioning both need a cheap, uniformly distributed hash. Adding shards later is far less painful if the bucketing function is fixed and documented today. This is a "decide the hashing contract before you need it" item, not a feature.
• Build vs. buy vs. use-native. This is a ~200-line MIT implementation of a published algorithm. "Buy" is irrelevant; the real decision is this package vs. a PHP extension vs. hash('xxh3') vs. hand-rolling. The honest answer is that hand-rolling is a bad idea (easy to get wrong, silently), and this package is the cheapest credible option in pure PHP.
• Cross-language interop commitments. If a Java/Go/Python service must compute the same bucket as the PHP app — common when a Kafka consumer or a data pipeline needs to agree with the web tier — you are effectively pinned to MurmurHash3 (and to a specific variant and seed). That is an architecture decision worth recording in an ADR, not a library detail.

Explicit non-decision

• Not a security primitive. No passwords, API tokens, session IDs, signatures, or anything an attacker can grind. It is non-cryptographic by design and trivially invertible-adjacent under brute force for short inputs. Say this out loud in the ticket so nobody "reuses the hash helper" later.

When to Consider This Package

Strong fit

• You need MurmurHash3 specifically for compatibility with an existing system: Guava Hashing.murmur3_32 in Java, mmh3 in Python, Cassandra-style partitioning, Kafka's default partitioner (murmur2 — verify variant), or a data-warehouse pipeline that already buckets on murmur.
• You need seed support and stable 32-bit output, and you want it as a Composer dependency rather than a vendored snippet.
• Volumes are moderate — order thousands of hashes per second, or hashing short strings where a few microseconds are irrelevant next to the I/O you are protecting.
• You want no extensions, no ops surface: works on any shared host, any managed PHP runtime, any container.
• You need reproducibility: MIT, tiny, single-purpose, and forkable in an afternoon if upstream goes quiet. For a hash your data layout depends on, "I can vendor this forever" is a genuine feature.

Look elsewhere

• Throughput matters. Pure-PHP MurmurHash3 is roughly one to two orders of magnitude slower than a native implementation. Benchmark before putting it on a hot path; a per-request hash is fine, a per-row hash over a million-row import is not. Prefer hash('xxh3')/xxh128 (PHP 8.1+, in core, no dependency) or a C extension such as php-murmur if you need speed and don't need MurmurHash3 parity.
• You need 64-bit or 128-bit MurmurHash3. Verify the variant and output width before assuming this package covers it; PHP integer width and 32-bit platforms make x64 variants fiddly. If you need murmur3_x64_128, plan on an extension.
• Maintenance posture is a hard requirement. Last release April 2021, ~129 stars, no dependents listed. That is not disqualifying for a frozen algorithm, but it does mean: no PHP 9 support guarantee, no security-response process, and you own compatibility testing. If your org's policy requires a maintained vendor, this fails it — vendor the file instead and own it.
• You need a cryptographic or keyed-MAC hash. Use sodium_crypto_generichash, hash_hmac, or password_hash. Wrong tool entirely.
• You already have a bucketing abstraction. If the platform team exposes Bucketer::bucket($key, $n), do not add a transitive dependency to a leaf service; ask them to swap the implementation.

Adoption checklist if you proceed

1. Pin the exact version in composer.json; hashes are a data-format contract.
2. Add golden-value tests — hardcode expected outputs for a fixed set of inputs and seeds, cross-checked against a Java or Python reference. A silent variant/endianness bug in a sharding hash redistributes production data.
3. Wrap it behind your own interface (Hasher::hash(string $key, int $seed): int) so the implementation can be swapped for xxh3 or an extension without touching call sites.
4. Document the seed and bucket-count formula in an ADR next to the shard map.

How to Pitch It (Stakeholders)

For executives (30 seconds). We need a small, deterministic hashing utility to unblock consistent feature rollouts and horizontal sharding. The chosen option is a free, MIT-licensed, ~200-line library that ships as a normal Composer dependency — no vendor contract, no new infrastructure, no ops work. It is a commodity algorithm, not a strategic bet; the main risk is that it is unmaintained since 2021, which we mitigate by pinning the version and adding golden-value tests. Cost is a code review, not a budget line. It is explicitly not a security component and will not be used for passwords or tokens.

For engineering leads. It gives us deterministic bucketing — hash experiment_id + user_id, take modulo 100, get the same variant on every box forever, with no shared state. Same primitive covers cache-key generation, Bloom-filter hashing, and shard assignment, so one dependency serves several needs. Tradeoffs, plainly: pure PHP, so it is slow relative to native — fine for per-request hashing, not for bulk row-by-row passes; and if we are on PHP 8.1+ and don't need MurmurHash3 wire-compatibility with another service, hash('xxh3') is faster, in core, and a better default. The reason to pick this package over xxh3 is interop: matching an existing Java, Python, or pipeline implementation that already buckets on MurmurHash3. It's a stale repo — treat the code as frozen, wrap it behind our own Hasher interface, and add cross-implementation golden tests so a variant or endianness regression can't silently reshuffle tenants. If throughput or 64/128-bit output becomes a requirement, the interface lets us swap the backend without a migration.

The ask. One reviewer, one ADR, and a decision on whether we are standardizing on MurmurHash3 (interop-driven) or xxh3 (performance-driven). The wrong outcome is two teams picking differently and incompatible buckets.