Rulerz Laravel Package

Product Decisions This Supports

• Dynamic merchandising, filtering, and ranking without redeploys. If the roadmap includes "show, hide, or boost products by attribute, stock, margin, or customer segment," a rule engine is directly in scope. This package replaces scattered conditionals with named, testable specifications.
• Promotion, eligibility, and pricing logic. Discount stacking, "eligible if cart > $X and tier = gold and not already discounted," free-shipping thresholds, and coupon preconditions become expressible as readable rules instead of a 400-line if block in a checkout service — each with a name, an owner, and a unit test.
• Build vs. buy: buy the primitive, build the product. This is a library, not a rules platform. Adopting it settles "composable rule objects vs. hand-rolled conditionals," not "rules product vs. no rules product." Authoring UI, persistence, versioning, and audit trail remain your build.
• Segmentation and personalization. Customer/audience specifications composed with and/or/not apply equally to content targeting, feature gating, and email audience definitions — one mental model across features, lower onboarding cost.
• Cross-datasource consistency (a real QA cost saver). Write one rule, execute it against arrays (tests, prototypes), an ORM (transactional reads), or a search index (large catalogs). This is what lets a PM credibly promise "the same rule applies in preview and production."
• Roadmap enabler for self-service. If a future milestone is "marketing defines audience rules without engineering," this is a plausible engine underneath that UI — an enabling spike, not a shipped capability.
• Explicitly rule out: real-time bidding, per-request pricing at >1k RPS, and anything requiring non-technical authors to write rules today.

When to Consider This Package

Adopt (or spike) when:

• Business rules are genuinely volatile — changed monthly by commercial or marketing — and each change costs an engineering ticket plus a release.
• The same logical condition is duplicated across controllers, query builders, and admin filters, and the copies have drifted.
• You need rules to run against more than one backend (in-memory for tests, ORM for transactional reads, search index for catalog queries) from a single source of truth.
• Your team is PHP/Laravel-native and would otherwise reinvent a mini-DSL badly — the Specification pattern is exactly what most teams rebuild poorly.
• You want rules unit-testable in isolation, the strongest long-term argument for the pattern.

Look elsewhere, or proceed only with an ownership plan, when:

• Community and maintenance signals are the headline risk. Zero stars, zero dependents, a fork under a vendor since absorbed into commercetools. Evaluate upstream k-phoen/rulerz first and treat this fork as a patch source. Verify last commit, PHP version support vs. your runtime, open issues, and whether it still pulls the effectively-unmaintained hoa/* compiler.
• No persistence, versioning, authoring UI, or audit log ships with it. If governance, "who changed this rule and when," or regulatory explainability is required, you need a BRMS (Camunda DMN, Drools) or a product, not a library.
• Non-developers must author rules. The DSL is developer-facing; plan a translation layer or pick a system with a builder UI.
• Hot-path performance matters. No index-awareness or caching story out of the box — benchmark against your real catalog size before committing.
• There is no Eloquent target. In-memory filter() over Collections works today; compiling specs to Illuminate\Database\Query\Builder requires a custom target (roughly 200–400 LOC) or a Doctrine DBAL bridge.
• Rules are single-consumer and low-change. Three static conditions in one place is over-engineering.
• You are not prepared to vendor or fork it. Assume you may inherit maintenance; budget for a pinned fork and a named owner.

Minimum due diligence before commitment: license compatibility (MIT — fine), security advisory history, PHP/Laravel version matrix, adapter coverage for your datastores, a timeboxed spike converting three real production rules, and a written exit plan (rules as plain classes behind an interface so the engine is swappable).

How to Pitch It (Stakeholders)

For executives (one paragraph): We repeatedly pay engineering to hard-code commercial logic — promotions, eligibility, product visibility, audience targeting — and each change is a ticket plus a release. This library lets us express those rules once, in a testable form, and run them identically against our database, our search index, and our tests. The upside is faster commercial iteration and fewer "the discount fired twice" incidents. The caveat is material: it is a low-adoption fork of a dormant open-source project, so we would adopt it behind our own interface with a named owner and a fallback plan. Recommendation: fund a two-week spike, not a commitment — the decision to make now is "encode rules as composable objects," which is defensible regardless of whether this specific library survives.

For engineering: This gives you the Specification pattern with a real DSL — composable and/or/not, named rules, adapters for arrays/Doctrine/search — replacing condition-soup in services with small, individually unit-tested classes and one rule definition executed consistently across test and production paths. Costs: a dependency on an unmaintained-adjacent fork (audit it, consider upstream first), a learning curve on the DSL, no built-in persistence or caching, and no first-party Eloquent/Scout target. Mitigation: define a thin internal SpecificationEngine interface bound as a singleton, keep rules as plain PHP objects, install via a VCS repository pinned to a commit SHA and mirror into an internal namespace, and vendor the fork if needed. That containment makes the library a replaceable implementation detail rather than an architectural bet — a future swap to symfony/expression-language or a hand-rolled predicate tree becomes an internal refactor.

For product and commercial teams: You gain a shared, precise vocabulary for rules and a much shorter path from "change the eligibility criteria" to "it's live." You do not gain a self-service rule editor — that remains a separate roadmap item, with this package as one input to it.