Conditionable Laravel Package

Technical Evaluation

What this package actually is. illuminate/conditionable is not a third-party utility — it is the read-only, subtree-split distribution of the Conditionable trait from laravel/framework, published by the Laravel team under MIT. It ships one trait (Illuminate\Support\Conditionable) exposing when() and unless() on any class that uses it. Registry signals in the brief — 0 dependents, stars attributed to the parent repo — are artifacts of monorepo splitting and understate adoption badly: this code is installed in effectively every Laravel application via illuminate/support, illuminate/collections, and illuminate/database. Any assessment that reads it as an "unofficial reimplementation" is measuring the wrong artifact, and that misframing should be corrected before it drives a decision.

Architecture fit: high, but usually invisible. For a Laravel application the trait is already present transitively; adding a direct requirement changes nothing functionally. The genuine architectural fit is narrower and sharper: (a) framework-agnostic PHP libraries that want fluent conditionals without dragging in all of illuminate/support; (b) shared internal packages (DTOs, builders, service objects) that must not assume a full Laravel runtime. In a full Laravel app the correct posture is "present, not declared."

Integration feasibility: trivial. Zero configuration, zero dependencies, zero bootstrapping. The one detail worth flagging to engineers is that the package name and the namespaced class diverge (illuminate/conditionable → Illuminate\Support\Conditionable), which trips up dependency audits and import greps.

Technical risk: low, and almost entirely version-graph risk rather than code risk. The trait is ~60 lines of pure PHP with no I/O, no parsing, no network surface. Real risks:

• Major-version coupling. Releases track Laravel majors (10.x/11.x/12.x) on the framework's cadence, not an independent one. A direct constraint that drifts from the framework's own constraint invites Composer resolution backtracking — the failure mode is an unexplained downgrade of the entire illuminate/* set, not a loud error.
• Behavioral drift across majors. Later versions accept a third $default argument on when(); code written against 12.x and resolved to an older major will fail at runtime, not at install time.
• Trait/method collisions. A class that already defines when() silently wins over the trait — no fatal, but divergent semantics.
• Declared-but-unused dependency noise. Requiring the package directly in an app where it is already transitive adds a maintenance knob with no benefit.

Key questions for the team:

1. Is the consumer a Laravel application or a distributable/reusable package? (This single answer determines whether the package is a decision at all.)
2. Does any code reference Illuminate\Support\Conditionable directly, or is the trait only inherited through framework base classes?
3. What is our version policy — do we pin the split package to the same major as laravel/framework in lockstep, and who enforces it?
4. Are we relying on the third $default argument or unless() semantics that are major-gated?
5. Have third-party dependencies pinned older majors of this package in a way that constrains our framework upgrade window?

Integration Approach

Stack fit. Laravel 10/11/12: already installed, no action required — treat as part of the platform, not the dependency inventory. Non-Laravel PHP 8.x services and internal Composer libraries: genuinely useful, and the only context where a direct requirement is justified. Symfony or other-framework codebases: not applicable.

Migration path. There is no runtime migration — the trait is API-identical whether reached via the split package or via illuminate/support, so any code using it continues to work unchanged if the dependency posture shifts. The only "migration" is administrative: correcting the dependency declaration so it reflects reality.

Compatibility and sequencing.

1. Inventory first. Run composer why illuminate/conditionable and composer show illuminate/conditionable to confirm it is transitive and identify which major is resolved. Do this before any change; it is the whole audit.
2. Decide by consumer type. Application → take no action, and explicitly record "no direct requirement" as the decision. Library/package → add illuminate/conditionable to require with a constraint matching the lowest framework major you support; if the trait appears only in test doubles, put it in require-dev instead.
3. Align majors. Where a direct requirement exists, constrain it in lockstep with the framework major (or with the supported-PHP/library matrix for standalone packages) and add a CI check so drift is caught at PR time, not at upgrade time.
4. Resolve collisions. Where domain classes already define when()/unless(), rename or wrap rather than relying on trait precedence.
5. Defer the build-vs-buy debate. Copying the trait inline is technically viable (MIT, ~60 lines) and occasionally correct for zero-dependency libraries, but it trades a maintained upstream for a local patch obligation. Default to the dependency; only vendor it if the package must have literally no Composer requirements.

Guardrail to communicate. Do not let engineers add illuminate/conditionable to a Laravel application's composer.json as a "safety" measure. It is a no-op that creates a version constraint someone will later have to reconcile during a framework upgrade.

Operational Impact

Maintenance: effectively nil. Upstream is maintained by the Laravel team with the framework's release cadence and MIT licensing; there is no separate roadmap, no deprecation stream, and no configuration to age. Budget zero engineering hours. The only recurring cost is the CI guardrail that keeps any direct constraint aligned with the framework major.

Support. Documentation lives in the Laravel docs (collections/conditionals), not in the package — engineers searching the package name for guidance will find little, which is a discoverability wrinkle, not a support gap. Security advisories arrive through the framework's advisory channel rather than a package-specific feed; if the org tracks per-package CVE feeds, this package will look permanently stale and should be excluded from that alerting to avoid noise.

Scaling. Irrelevant at any realistic volume — one conditional branch and a closure invocation per call. The only measurable cost is closure allocation in extremely tight loops (large collection pipelines over hundreds of thousands of items); the fix is a plain if in that hot path, not a change in dependency.

Failure modes to plan for:

• Silent resolution downgrade. A transitive or direct constraint conflict causes Composer to settle on an older illuminate/* set. Symptom: missing methods, puzzling runtime errors after an unrelated composer update. Detection: assert the resolved framework major in CI.
• Behavioral skew on when()'s third argument. Code assumes $default support that the resolved major does not provide.
• Trait precedence confusion. A locally defined when() shadows the trait and behaves differently from every other when() in the codebase.
• Ownership ambiguity. Because no team "owns" a transitive dependency, upgrades get attributed to nobody during framework major bumps; assign it explicitly to the platform owner alongside laravel/framework.

Ramp-up: under 15 minutes. Engineers already use when() on Collections and Eloquent builders, so the concept is pre-loaded. The only teachable gap is split-package literacy — understanding that illuminate/* packages are framework components, that their versions move with the framework, and that a direct requirement is a package-authoring tool, not an application-installation step. Put that in one paragraph of the platform onboarding doc and it is settled.

Bottom line for the roadmap. This is not a build/buy decision and should not consume a decision slot. Adopt it implicitly as a platform component in applications; adopt it explicitly only where a reusable library needs fluent conditionals without Laravel's full support layer. The measurable lever is dependency hygiene — keeping declared constraints honest and aligned — not capability, cost, or risk reduction.