Rulerz Laravel Package

Technical Evaluation

Architecture fit

• RulerZ is a standalone PHP rule engine implementing the Specification pattern: business rules are authored in a human-readable DSL, composed with boolean operators, and compiled to a target (array/Traversable, Doctrine, Eloquent, Elasticsearch) for evaluation.
• From a TPM lens, the value proposition is rule centralization: one authoritative definition per business rule instead of duplicated conditionals across checkout, admin, reporting, and search. That is a roadmap enabler for later self-serve rule authoring, not just a code cleanup.
• Strong fit for Laravel domains where rules are (a) reused across more than one surface, (b) change on a business cadence, and (c) must run against both a relational store and an in-memory collection. Eligibility gates, pricing/promotions, audience segmentation, entitlement/trial limits, and moderation policies all qualify.
• Poor fit for one-off where() clauses or static filters — the abstraction does not pay for itself. The TPM decision is "adopt OSS Specification layer vs. build a thin in-house one," with no licensing cost either way.

Integration feasibility

• Composer-installable and Laravel-usable, but not a first-class Laravel package. Expect to build the engine wiring, Eloquent target adapter integration, rule repository, validation, caching, and observability ourselves inside a service provider + domain service.
• Eloquent support is the critical unknown. Adapter compatibility with the current Laravel/PHP version — especially around query builder internals, relationships, soft deletes, and global scopes — must be proven by spike, not assumed.
• Rule storage is a product decision: code/config (developer-owned) vs. database-backed (admin-editable, but introduces validation, versioning, and an untrusted-input security surface).
• MIT license makes fork/vendor a legally clean fallback if upstream is inactive — but that converts an OSS dependency into an internal maintenance line item.

Technical risk

• Maintenance risk (primary): 876 stars is respectable but the dataset reports zero dependents and a modest overall score. Verify last release, commit cadence, open-issue age, PHP version constraints, and test coverage before commit. A niche single-maintainer library is a plausible abandonment risk.
• Framework compatibility risk: Laravel/Eloquent APIs evolve; an aging adapter can break on upgrade and block the platform.
• Security risk: If rules are ever user-authored, the DSL becomes an input surface — expensive queries (DoS), unintended field exposure, or injection if the target compiler doesn't parameterize safely. Treat as a security review gate.
• Semantic drift risk: The array adapter and SQL adapter can diverge on nulls, dates, enums, case sensitivity, and relationships. Contract tests per rule family are mandatory.
• Debuggability risk: Opaque generated SQL and parser errors degrade production support; rule validation, error messaging, and query logging are prerequisites.
• Lock-in risk: Rules couple to RulerZ's DSL and adapter semantics — mitigate behind an internal interface.

Key questions

• Who authors rules: developers only, internal ops, or end customers? (Drives security and UX scope.)
• Are rules trusted/reviewed or user-supplied? (Drives validation and DoS controls.)
• Which targets are required: Eloquent SQL pushdown, in-memory, Elasticsearch, or several?
• Which PHP/Laravel/DB versions must be supported, and does the Eloquent adapter pass contract tests on them?
• Is upstream actively maintained, or will we fork and own it?
• Latency, query-count, and pagination requirements for rule-filtered lists?
• Do we need rule versioning, audit trails, approvals, rollback? (RulerZ is a library, not a BRMS.)
• What's already in the stack — Laravel query builder, Spatie query builder, Symfony ExpressionLanguage, hand-written Specification classes?

Integration Approach

Stack fit

• Adopt RulerZ as an internal domain service behind an application-level RuleEngine interface; do not let the library leak across controllers and models. This boundary is the exit ramp if the package stalls.
• Use the Eloquent target for list/filter screens so rules compile to SQL and preserve pagination and indexing; use the array target for single-record checks and non-persisted candidates.
• Store rule expressions with product metadata: name, description, owner, target, status, version, timestamps. Validate/lint on save, not at runtime.
• Keep presentation-layer filters separate from domain rules. A UI filter builder may generate RulerZ expressions, but the domain must never accept raw unvalidated user strings.
• Enforce multi-tenancy and query scopes outside the DSL — never rely on rule authors to include tenant isolation.

Migration path

• Start with one bounded, low-blast-radius use case — internal admin segmentation or eligibility screening — not customer-facing pricing or compliance.
• Map existing filters to RulerZ expressions and run dual evaluation in shadow mode: compare RulerZ-generated SQL/results against the current implementation before cutover.
• If the Eloquent adapter is incompatible, options rank as: fall back to Symfony ExpressionLanguage / hand-written Specifications > fork-and-patch the adapter under MIT > pin an older Laravel/PHP combination (least preferred; it mortgages the platform).
• Migrate incrementally by rule family behind feature flags, never as a big-bang rewrite of all filtering.

Compatibility

• Build a compatibility matrix across PHP, Laravel, database driver, and adapter. Test generated SQL on every supported DB (MySQL/PostgreSQL) if both matter.
• Explicitly verify behavior for nullable columns, dates/timezones, enums, JSON columns, relationships, soft deletes, and global scopes.
• Pin the Composer version; gate upgrades behind rule contract tests. No automatic minor upgrades.
• Confirm rule compilation cannot bypass Laravel query scopes or tenant isolation.

Sequencing

1. Spike: Prove install, Eloquent adapter, and one representative rule on the target Laravel/PHP version.
2. Risk review: Security review (untrusted rules, query cost), license/fork policy, validation strategy.
3. Wrap: Build the internal rule service, repository, validator, cache, and observability.
4. Pilot: Migrate one internal use case behind a flag with dual-run comparison.
5. Harden: Contract tests, error handling, authoring docs, rollback procedure.
6. Expand or replace: Decide broaden / fork / replace based on pilot metrics and maintenance signals.

Operational Impact

Maintenance

• Assume low upstream support risk until demonstrated otherwise. Name an internal owner and budget recurring time for dependency review, adapter patches, and PHP/Laravel upgrade testing.
• Under MIT, forking is legally trivial but operationally real: a fork needs CI, a patch set, and a release process — treat it as a product maintenance cost, not a quick fix.
• Rule definitions are production configuration. They require code review, version control, and change management with the same rigor as application code.

Support

• No commercial support or SLA should be assumed. Rely on community issues, source reading, and internal documentation.
• Fund a short enablement guide: DSL basics, adapter differences, reading generated SQL, interpreting parser errors, and a catalog of representative rules.
• Build runbooks for: disabling a bad rule, rolling back a rule version, and inspecting compiled queries in production.

Scaling

• Measure and cache compilation cost; avoid reparsing the same rules per record or per request.
• Prefer SQL pushdown for large datasets — in-memory evaluation over large collections will spike memory/CPU and is not a scaling story.
• Watch expensive generated queries: missing indexes, LIKE scans, OR-heavy expressions, relationship traversal. Add query logging and slow-rule alerts.
• Test pagination and count queries independently; compiled rules can affect them differently.

Failure modes

• Invalid rule syntax → runtime errors: validate on save, fail closed with a clear message.
• Unsupported operators or adapter gaps → silent behavior differences: contract-test every rule family against each target.
• Untrusted rules → DoS queries or data leakage: restrict accessible fields, enforce cost limits, review generated SQL.
• Upstream abandonment or PHP/Laravel incompatibility → blocked platform upgrades: the RuleEngine abstraction boundary is the insurance policy — keep it clean and keep a documented fallback.
• Semantic drift between in-memory and SQL evaluation → inconsistent product behavior across surfaces: shadow-mode dual runs and a shared contract test suite.

Ramp-up

• Developers need a modest but real DSL learning curve plus adapter-specific knowledge; plan for a short ramp and pair a spike owner with the pilot team.
• The pilot should deliberately exercise the hardest cases (relationships, nulls, dates) so the enablement guide captures real failure modes before broad adoption.
• Expect the first rule family to take the longest; subsequent families reuse the wrapper, repository, and contract tests, so velocity improves materially after the pilot.