Rulerz Bundle Laravel Package

Technical Evaluation

Architecture fit. RulerZ is a rule-engine/specification library: business rules are expressed once (as a string DSL or a Specification object) and then either evaluated in-memory against PHP objects/arrays or compiled to a target query language (Doctrine DQL, Elasticsearch DSL, SQL). kphoen/rulerz-bundle is not the engine — it is a thin Symfony integration layer that registers the rulerz service, wires per-target compilers, exposes the spec parser, and adds a Twig extension (rulerz_can, rulerz_can_see). The architectural value is real: it moves authorization/eligibility/filtering logic out of controllers and Eloquent/Doctrine chains into a testable, declarative layer.

Integration feasibility — the headline risk. This package cannot be dropped into a Laravel application. It is a Symfony Bundle: it depends on symfony/framework-bundle (^2.8|^3.x), registers through Kernel::registerBundles(), and ships a DependencyInjection\Extension. Laravel has no bundle registry, no compiler passes, no Bundle class. Adoption therefore has two distinct paths:

1. Adopt the bundle — only viable if the target is a Symfony 2.8/3.x LTS app that has not moved on. For a Laravel codebase this is a non-starter.
2. Adopt the core kphoen/rulerz library and write a ~100–200 line RulerzServiceProvider plus a Blade directive to replace the Twig extension. This is the only credible route, and it means the package under review contributes essentially nothing but reference configuration.

Technical risk. High. Last release 2016-06-11 — roughly nine years stale — with 37 stars and zero dependents. That combination is the signature of an abandoned integration shim. Expect: PHP 8 incompatibilities (old reflection usage, deprecated dynamic properties, each()-era idioms), Symfony 4+ DI incompatibilities (setSynthetic, private-service semantics, removed bundle inheritance), and unconstrained transitive pins that will fight a modern composer.lock. The underlying kphoen/rulerz core is itself dormant. MIT license removes legal friction but not maintenance burden.

Key questions.

• Is "user-definable business rules" a genuine product requirement, or is this a solution looking for a problem? A fixed set of Eloquent scopes or Laravel Policies may cover 90% of the need at zero risk.
• Which evaluation target actually matters: in-memory object evaluation, or compiled query pushdown? If only in-memory, symfony/expression-language (actively maintained, works fine in Laravel) is a direct substitute.
• Will rule strings ever be authored by end users? If yes, the DSL parser becomes an injection surface for the DQL/ES compilers and needs explicit threat modeling.
• Who owns the fork when upstream is dead? Named maintainer or the package is unownable.

Integration Approach

Stack fit. Assume Laravel 10/11 on PHP 8.2/8.3. The bundle's constraints (php >=5.6, symfony/framework-bundle ^2.8|^3.0) hard-conflict; composer require kphoen/rulerz-bundle will fail resolution immediately. Do not spend time trying to force it with --ignore-platform-reqs — you would install a Symfony kernel into a Laravel app for no benefit.

Recommended migration path.

1. Require kphoen/rulerz core only, if the spike justifies it at all.
2. Build App\Providers\RulerzServiceProvider: bind RulerZ\RulerZ as a singleton, instantiate the compiler(s) you need (DoctrineCompiler only if you actually use Doctrine; otherwise array/NativeCompiler), and register a RuleFactory/spec parser.
3. Replace the Twig extension with a Blade directive (@rulerzCan(...)) or, better, a Gate-adjacent helper so authorization stays in one place.
4. Model reusable rules as classes implementing RulerZ\Spec\Specification rather than raw DSL strings in config — this keeps rules unit-testable and IDE-navigable.
5. Vendor the bundle's Resources/config/*.yml as documentation for which services to bind; do not install the YAML.

Compatibility. Treat the core library as legacy: pin it exactly, run the full test suite on every PHP minor upgrade, and isolate all RulerZ\* imports behind your own RuleEngine interface so a future swap to symfony/expression-language or a hand-rolled evaluator is a one-file change.

Sequencing. (a) Two-day spike proving one real rule end-to-end against a representative model; (b) go/no-go against the ExpressionLanguage alternative; (c) if go, wrap behind an interface and ship with contract tests; (d) only then migrate existing ad-hoc rule logic. Never sequence this ahead of a feature that needs it.

Operational Impact

Maintenance. You are adopting a fork on day one. Budget 1–2 engineer-days per PHP minor release for compatibility patching, plus an unbounded tail for security issues in the DSL parser. Upstream will not help; there is no maintainer to file against.

Support. Community-only, and effectively no community: 37 stars and 0 dependents means no Stack Overflow corpus, no third-party blog coverage, and thin official docs. Internal documentation and a runbook for "rule fails to parse in production" are mandatory, not optional.

Scaling. In-memory evaluation is O(rules × rows) in PHP — fine for hundreds of entities, not for report generation over thousands. Compiled DQL/SQL pushdown scales well but couples you to a specific query builder and makes the compiled output hard to review. The failure pattern to watch in Laravel specifically is per-model evaluation inside a loop: foreach ($users as $u) { $rulerz->satisfies($u, $rule); } over 10k rows is an N+1-shaped performance cliff, and lazy-loading relations referenced in a rule turns it into a query storm.

Failure modes.

• Parse failure on malformed or user-supplied rules — surfaces at runtime, not deploy time, unless rules are validated at write time.
• Injection via DQL/ES compilation — a rule authored by a non-trusted source becomes a query-injection vector; treat rule strings as untrusted input.
• Semantic drift between targets — the same rule can behave differently in-memory versus compiled; pin behavior with golden-case tests per target.
• Silent abandonment — the package rots invisibly; add a composer outdated gate and a calendar reminder for the fork.

Ramp-up. The DSL has non-obvious syntax (notably #-prefixed parameter binding and target-specific operator availability). Expect 1–2 days for a mid-level engineer to be productive, plus ongoing friction for anyone who has not internalized which operators compile to which backend.

TPM recommendation. Do not adopt kphoen/rulerz-bundle. It is a Symfony-only shim with a nine-year-old last release and zero dependents, and it cannot be installed into a Laravel application. If a declarative rule layer is genuinely required, prototype symfony/expression-language first — same product outcome, actively maintained, framework-agnostic — and only fall back to forking kphoen/rulerz core if compiled query pushdown proves to be a hard requirement.