Default Value Filterable Laravel Package

Technical Evaluation

What it is (inferred): A small Laravel/Eloquent package exposing trait(s) that (a) apply default attribute values to models and (b) enable query filtering — most likely via a filterable allow-list and a builder scope. The published footprint (2 stars, 0 dependents, score 0.01, single release on 2025-01-16) indicates a personal/solo project with essentially no production signal.

Architecture fit: Low-friction by construction. Laravel packages of this shape are a service provider plus one or more traits, so they slot into any Eloquent-centric codebase without touching framework internals. The real question is incremental value: Laravel already covers the default-value half via $attributes, casts, and Attribute accessors, and the filtering half via local scopes or Builder macros. This package only earns its place if its filter ergonomics are materially better than 30 lines of in-house scope code.

Integration feasibility: Easy to install, easy to remove. composer require plus a trait import per model; no infrastructure, no migrations, no config publishing in the likely case. A spike is a half-day including parity tests.

Technical risk:

• Abandonment / bus factor 1. No dependents means no downstream pressure to fix breakage on Laravel majors. Treat any version constraint as a snapshot, not a guarantee.
• Filter surface is the sharp edge. If the filterable allow-list is opt-in and enforced, risk is contained. If filters are derived from request input or model $fillable, you inherit SQL-injection and mass-assignment-adjacent exposure. This must be read in source, not assumed from the README.
• Semantics collision. Defaults applied at instantiation can silently overwrite intent on updates, and can conflict with Model::preventSilentlyDiscardingAttributes, upsert, and factory states — subtle, hard-to-test bugs.
• Supply chain: negligible blast radius (small dep tree, no native code), but also no security response process.

Key questions to answer before adoption:

1. Does the filter allow-list require explicit per-column opt-in, and how are operators handled?
2. What are the illuminate/* and PHP version constraints — does it cover Laravel 11/12?
3. Does the default-value path run on newInstance, create, or hydration — and does it clobber explicit null?
4. Test coverage and license (MIT vs. unclear) — is forking legally and practically clean?
5. Does filtering generate indexed, sargable WHERE clauses, or does it wrap columns in functions?
6. Trait method-collision behavior against SoftDeletes, HasFactory, and existing local scopes.

Integration Approach

Stack fit: Standard Composer package for Laravel 9–11 / PHP 8.1+. It matches the prevailing idiom (provider + trait), so no architectural adaptation, no new runtime, no queue or cache surface. It will not fight a modular/DDD layout because it lives at the model layer — which is also the reason to be cautious: model-layer magic is the hardest thing to unwind later.

Migration path:

• Greenfield: adopt per model, gated behind an internal interface so the trait is swappable.
• Brownfield: do not swap in place. Write an equivalent local trait (App\Support\Concerns\HasDefaults, FiltersQueries) that mirrors current behavior, move models onto it, then treat the package as a reference implementation rather than a dependency. This costs roughly the same effort as integrating properly and removes the abandonment risk entirely.

Compatibility checks to run in the spike: composer why-not for the Laravel constraint; a test asserting defaults do not override explicit null or dirty attributes; a test asserting non-allow-listed filter keys are ignored rather than applied; a test for nested/relation filters, which is where hand-rolled filter packages typically break (N+1 or unindexed joins).

Sequencing:

1. Read the source end-to-end (it is small) and record the filter grammar and allow-list enforcement.
2. Spike on one low-traffic, read-heavy model behind a config flag.
3. Parity suite against existing scopes; compare query logs, not just result sets.
4. Expand to 2–3 models, or decide to vendor the code into app/Support with attribution.
5. Either way, pin the version and record a fork/exit date on the dependency register.

Operational Impact

Maintenance: The dominant cost. Assume no upstream fixes; budget a one-time fork (~1–2 days) or ~1 day per quarter of watch-and-patch across Laravel majors. Vendoring converts an open-ended dependency risk into a bounded, owned asset — for a package this small, that is the better trade.

Support: GitHub issues only, single maintainer, no SLA, no security disclosure path. Acceptable for internal, non-customer-facing read filters; not acceptable on a path where a filter bug becomes a data-exposure incident.

Scaling: Default-value logic is in-process and effectively free. Filtering is the scaling question: it is only as good as the indexes behind it. Watch for filters that force LIKE '%…%', whereDate(), or relation traversals — these degrade non-linearly on large tables. Instrument query count and p95 latency on the pilot model before and after.

Failure modes to monitor:

• Silent default overwrite on update (data-correctness bug, no exception raised).
• Filter key accepted that shouldn't be → cross-tenant or draft-record leakage.
• Trait method collision after a framework or package upgrade → fatal at boot, caught by CI, or worse, at deploy.
• Abandonment: package becomes incompatible with a Laravel major, blocking the framework upgrade path for the whole app.

Ramp-up: Low — a Laravel-fluent engineer is productive in under a day. The catch is that thin documentation means onboarding is really source reading, so the knowledge concentrates in whoever did the spike. Mitigate with a short ADR and the parity tests in-repo.

Recommendation: Do not take this as a hard production dependency on core models. Evaluate it as a design reference, then either integrate narrowly behind an internal abstraction on non-critical read paths, or vendor the ~few hundred lines into app/Support under the package license. The opportunity score (34.32) reflects a genuinely useful problem space — defaults plus declarative filtering is real toil — but the adoption signals (2 stars, 0 dependents, 0.01) mean the TPM's job here is to harvest the idea, not the dependency.