Eloquent Preferences Laravel Package

Technical Evaluation

Architecture fit. klaude/eloquent-preferences is a conventional Laravel leaf dependency: a service provider, a publishable config and migration, and a HasPreferences-style trait that exposes a polymorphic preferences relation on any Eloquent model. It does not impose architectural opinions beyond the trait, so it composes cleanly with existing domain models and does not constrain how we structure controllers, services, or APIs. The trade-off is that preference semantics (typing, defaults, validation, caching) live in application code, not in the package.

Integration feasibility. Low effort: composer require, publish config/migration, add the trait to target models, backfill. Realistic estimate is one to three days for a pilot model plus a half-day for migration and backfill, assuming no naming collisions with an existing preferences or settings table. Feasibility hinges on the supported framework matrix, which the release notes do not state reliably.

Technical risk. Moderate, concentrated in four areas:

• Pre-1.0 semver. The package is at v0.6.0; breaking changes can arrive in a minor bump. Any adoption should be pinned to an exact version with a deliberate upgrade cadence.
• Bus-factor. Single primary maintainer, with three first-time contributors landing in a single PR. Bus factor of one is the dominant long-term risk.
• Test-matrix signal. A "PHP 8.1 compatibility issue" fix implies the prior release was broken on a PHP version that has been current since late 2021, and the Laravel support line ("Added Laravel versions 9 through compatibility issue") is truncated to the point of being unreadable. Both suggest CI coverage is thin and release notes are low-fidelity.
• Low intrinsic blast radius. No external I/O, no network calls, no credential handling. Failure is confined to preference read/write paths, which limits worst-case severity.

Key questions.

1. What is the actual supported matrix per composer.json (illuminate/*, PHP constraint)? Does it cover Laravel 10/11, or only 9?
2. Is there a CI matrix, and what is current coverage? Any static analysis or test suite we can run locally?
3. Does the package support typed/cast values, per-attribute defaults, and bulk reads, or is it raw key/value strings?
4. Any built-in caching or eager-load guidance, or is N+1 on the caller?
5. What is the commit/release cadence over the last 12–18 months, and are issues being triaged?
6. Does the migration name or table name conflict with anything we already ship?
7. Has this been benchmarked against spatie/laravel-settings, a JSON column, or fixed columns for our specific access patterns?

Integration Approach

Stack fit. Best fit is a Laravel 8/9-era application on PHP 8.0/8.1 that needs per-model, user-editable preferences without schema churn per new preference. Poor fit if we are already on Laravel 10/11 (unverified), or if preferences are few, stable, and hot-path — fixed columns or a JSON column would be simpler and faster.

Migration path. Publish config and migration, run in a staging environment first, verify the polymorphic index and column types against our DB engine. If consolidating existing settings columns, run a dual-write window: write to both old columns and preferences, backfill historical rows, read from preferences behind a feature flag, then drop the old columns after a soak period. Ensure the rollback path restores reads from the original columns before any data is deleted.

Compatibility. Do not accept the release notes' compatibility claim at face value. Validate the composer.json constraints against our pinned framework and PHP versions in a throwaway branch before committing. If Laravel 10/11 is unsupported, do not work around it with --ignore-platform-reqs; either pin the framework, fork and patch the constraint with a documented maintenance obligation, or select an alternative.

Sequencing.

1. Spike branch: install, publish, migrate, exercise the trait on a scratch model; run the package's own test suite if present.
2. Comparative evaluation against one alternative for a single representative use case.
3. Wrap the package behind a thin internal interface (e.g. a PreferenceRepository contract) so the underlying implementation is swappable — this is the single highest-value risk mitigation and costs little.
4. Pilot on one non-critical model with low write volume.
5. Backfill and dual-write for any consolidated data.
6. Broader rollout with a documented upgrade policy (pinned version, quarterly review).

Operational Impact

Maintenance. Expect to own more of this than a typical dependency. Pin the version, watch the upstream repo for releases, and budget a recurring review. Because the wrapper interface exists, an abandonment scenario degrades to a bounded rewrite of one adapter rather than a cross-cutting refactor.

Support. No vendor SLA. Upstream responsiveness is community-driven and uneven; the v0.6.0 notes suggest PRs are merged in batches. Internal documentation should capture our pinned version, the rationale, and the exit plan so support does not depend on tribal knowledge.

Scaling. One row per preference per model instance. The primary scaling concern is not storage but query count: hydrating a collection of models and reading preferences per model is a classic N+1. Mitigate by eager-loading the relation and, if read volume justifies it, adding an application-level cache keyed by model type and ID with explicit invalidation on write. Table growth is linear and predictable; the polymorphic index on (model_type, model_id) should be verified against real query plans once volume is meaningful.

Failure modes.

• Framework or PHP upgrade breaks the package because the constraint is stale — highest likelihood.
• Migration or table-name collision with existing settings infrastructure.
• N+1 query amplification on list endpoints after rollout, invisible in low-traffic testing.
• Stale cache after preference writes if caching is added without disciplined invalidation.
• Orphaned rows or unexpected cascade behavior when parent models are deleted — confirm FK/cascade semantics.
• Silent default-value drift between package behavior and application expectations when a preference key has never been written.

Ramp-up. Low. A mid-level Laravel developer should be productive in under half a day; the API surface is small and idiomatic. The real ramp-up cost is not the package but the operational discipline around it: the version pin, the wrapper interface, and the upgrade runbook. Document those three artifacts alongside the integration so the next engineer inherits a decision, not a surprise.