Boolean Softdeletes Laravel Package

Technical Evaluation

What it is (and isn't). laravel-json-api/boolean-softdeletes is a thin adapter at the persistence/API seam. It teaches laravel-json-api to interpret boolean soft-delete state produced by yocto/illuminate-database-softdeletes: translating a deleted boolean column into JSON:API semantics (filter[trashed] values, restore/force-delete actions, route binding of trashed records, serialization without a phantom deleted_at). It removes a specific piece of custom glue; it does not improve architecture, and outside the exact intersection of both prerequisites — laravel-json-api and the Yocto trait — it delivers zero value.

Architecture fit. Strictly conditional. Fit is high only where the team has already committed to laravel-json-api conventions and has an active, justified reason to prefer a boolean soft-delete model (typically high-volume tables where an indexed boolean beats a nullable timestamp index, and "is deleted" is the only question the query layer asks). For teams on Laravel's native SoftDeletes, this is a schema and semantics migration, not an integration.

Integration feasibility. Technically plausible for a competent Laravel team: composer install of both halves, trait swap per model, an additive boolean column with default and index, and a schema concern applied per schema. The package is small enough to audit fully in an afternoon. The described core use case — GET /api/posts?filter[trashed]=with plus a PATCH restore round-trip — is a compact, testable acceptance criterion for a spike. Feasibility is constrained not by code but by adoption signal: 3 stars, 0 dependents, no evidence of production use, single-maintainer risk, and documentation that itself tells you to verify namespaces against vendor source rather than trust the README.

Technical risk. High relative to the value delivered. Concrete risks:

• Abandonment / single maintainer. No community pressure to track Laravel or laravel-json-api breaking changes.
• Transitive dependency risk through the Yocto package — its own maintenance cadence and its version-varying default column naming.
• Unclear compatibility matrix — PHP, Laravel, laravel-json-api, Yocto, and database drivers; no evident CI matrix.
• Behavioral edge cases — restore, force-delete, relation cascades, unique constraints, authorization on trashed retrieval.
• Semantic and data-migration risk moving from deleted_at to a boolean: a flag loses who and when, so auditable delete history requires an audit table regardless of this package.
• Apache-2.0 removes license cost, not ownership cost.

Key questions to resolve before any commitment. Which versions of PHP, Laravel, laravel-json-api, the Yocto package, and which database drivers are supported, and is there a CI matrix? What is the release cadence and security policy? Exactly how does boolean state map onto withTrashed() / onlyTrashed() scopes and the filter[trashed] values (with / only)? Does route binding resolve trashed records so restore doesn't 404? What are the defaults and configurability of the Yocto column name in the pinned version? Who owns the vendored fork if upstream goes quiet, and what is the exit plan?

Integration Approach

Stack fit. Adopt only where laravel-json-api and a boolean soft-delete model are both already chosen or actively justified (e.g., high-volume tables with measured index/query-plan benefit). Not a drop-in for teams on native SoftDeletes unless they accept both a schema migration and a semantics change. If the stack is on native soft deletes and not under performance pressure, the correct TPM answer is to skip and revisit only if both prerequisites become true.

Migration path. Inventory every model using native SoftDeletes and classify by volume and audit need. For existing tables: add the boolean column additively, backfill from deleted_at, dual-write or shadow-read during transition, update query scopes, policies, JSON:API filters, and tests, then cut over and drop deleted_at only after a defined rollback window. Greenfield work should still start with a time-boxed spike on one low-risk model so the trait swap and schema concern are proven before spreading. Where delete auditability is a compliance or product requirement, design the audit table up front rather than discovering the gap post-migration.

Compatibility. Pin everything — PHP, Laravel, laravel-json-api, Yocto, database driver — and encode the matrix as contract tests: filter[trashed] across all supported values; pagination and includes over trashed collections; restore round-trip; force-delete; route binding of trashed resources; authorization on trashed retrieval; and correct exclusion of deleted records from default listings. Confirm package discovery and config behavior in the actual application skeleton, and verify the Yocto default column name in the pinned version rather than assuming.

Sequencing (stage-gated).

1. Sandbox spike on one low-risk model; exit criterion is filter[trashed]=with plus a successful restore round-trip.
2. Answer the version/key questions and write the contract test suite.
3. Migration design with backfill and rollback documented and reviewed.
4. Pilot with explicit restore/force-delete and authorization flows.
5. Production-readiness review covering data exposure, security, and maintainability — including the vendor-or-fork decision.
6. Limited rollout; 7) broader rollout only on proven stability. Do not sequence this as a broad platform change.

Operational Impact

Maintenance. Assume you own it. With 3 stars and 0 dependents there is no community pressure to track upstream; budget for vendoring (recommended), dependency updates, and periodic compatibility re-testing against new Laravel / laravel-json-api releases. The mitigating factor is size: the code is small enough to audit and own, which makes vendoring a defensible call rather than a leap of faith.

Support. No commercial support is evident. Name an internal maintainer before adoption, define severity triage for security patches, and write the fork-and-own exit plan into the decision record. Treat upstream as source-available reference, not a supported library.

Scaling. The adapter itself is unlikely to be the bottleneck; query plans and indexing will dominate. Boolean soft-delete can simplify state and shrink indexes, but index usefulness depends on selectivity — validate on representative query plans, since a low-cardinality flag on a large table with skewed distribution may not behave as hoped. Load-test both trashed and non-trashed collection filters.

Failure modes (ordered by severity).

• Highest: data exposure — incorrect filter-to-scope translation surfaces deleted records in default listings. This is a security/privacy bug, not a UX bug; it warrants explicit regression tests and monitoring.
• Route binding failing for trashed records, so restore returns 404.
• Inconsistent restore/force-delete behavior across schemas or relations.
• Breaking changes in Laravel or laravel-json-api with no upstream fix forthcoming.
• Data loss or semantic drift during timestamp-to-boolean conversion.
• Vulnerabilities in the transitive Yocto chain.
• Authorization gaps around trashed resource retrieval — trashed records often remain addressable by ID, so test this directly.

Ramp-up. Developer ramp-up is low: thin adapter, familiar Laravel patterns, auditable in an afternoon. Organizational ramp-up is higher: the team must absorb new soft-delete semantics, execute a safe data migration, update policies and tests, and operationalize a lightly adopted dependency with no safety net.

TPM recommendation. Treat this as a reference implementation or bounded spike, not a committed production dependency, unless a strategic boolean soft-delete requirement (measured performance gain or an explicit schema policy) justifies owning the vendored fork. Approve the spike with a fixed timebox and the restore round-trip as the exit criterion; defer the dependency decision to the spike's results. Frame it for stakeholders as a near-zero-cost tactical enabler with an ownership ask, not a platform decision — and be explicit that the real cost is migration and long-term custody, not license fees.