Boolean Softdeletes Laravel Package

Product Decisions This Supports

• Defining the delete lifecycle in the public API contract. If records are exposed to clients through JSON:API, this package supports decisions about how "trashed" state is represented, filtered, restored, and permanently destroyed — without a bespoke serializer, endpoint, or filter convention invented per team. It turns a product question ("what does delete mean to a client?") into a standard set of JSON:API semantics rather than a one-off.
• Data-model choice: boolean flag vs. deleted_at timestamp. It removes a concrete blocker to adopting yocto/illuminate-database-softdeletes (an indexed boolean column) behind a standard JSON:API surface. That is a real product-adjacent decision for high-volume tables where an indexed boolean is smaller and faster than a nullable timestamp index, and where "is this deleted?" is the only question the query layer asks.
• Roadmap enablers: trash, restore, force-delete UX. Admin panels, moderation queues, and end-user "recently deleted" views all need list-with-trashed, restore, and permanent delete. This is a small enabler for shipping those features if the stack is already laravel-json-api — it shortens the distance from roadmap item to demo.
• Build vs. buy for a narrow integration. It is the "buy" option (Apache-2.0, zero license cost) for a bounded glue problem: wiring a non-native soft-delete trait into an existing JSON:API conventions layer. The alternative is a maintained-in-house adapter with the same surface area.
• Standards compliance over ad-hoc API. Using JSON:API conventions for trashed filtering and lifecycle actions keeps the API consistent with the rest of the product, rather than introducing one-off ?include_deleted=true style flags that accumulate as permanent inconsistencies.
• Scope control on the roadmap. This is a thin adapter, not a platform. With 3 stars and 0 dependents, it is a candidate for a time-boxed spike, never a roadmap pillar. A PM should treat it as decision-supporting utility — useful for de-risking a specific design choice, not something to build strategy on top of.

When to Consider This Package

Consider it when:

• The product is already committed to laravel-json-api and to the yocto/illuminate-database-softdeletes trait, or is actively evaluating that trait for measured performance reasons.
• You need restore / force-delete / include-trashed behavior exposed through JSON:API and want to avoid writing, testing, and maintaining that integration yourself.
• The tables in question are high-volume, and an indexed boolean is demonstrably better than a nullable timestamp column in your query plans. Without that evidence, native soft deletes are the safer product bet.
• You are prepared to vendor or fork a small dependency and own it, with your own test coverage and a named internal maintainer. Engineering cost is low because the source is small and auditable in an afternoon.
• You can sequence it as a bounded spike with a concrete exit criterion — e.g. GET /api/posts?filter[trashed]=with plus a PATCH restore round-trip on one low-risk model — rather than as a mid-sprint platform change.

Look elsewhere when:

• The stack is not on laravel-json-api, or uses Laravel's native SoftDeletes. The value only exists at that exact intersection; elsewhere it adds nothing.
• You need auditable delete history (who deleted, when). A boolean flag alone loses that; a timestamp plus an audit table is the better product model. Plan the audit table up front rather than discovering the gap post-migration.
• You require maintained, well-supported dependencies for compliance or long-term support. With 3 stars, 0 dependents, and no evident commercial support, assume no community safety net and no guaranteed upstream fixes.
• You are under delivery pressure. Adopting an unproven adapter mid-sprint is a worse trade than native soft deletes now and a refactor later.
• The opportunity is speculative rather than tied to a real performance or UX requirement. Treat low-signal packages as spikes, not commitments.
• There is a data-exposure sensitivity you cannot test adequately. Incorrect filter-to-scope translation that surfaces deleted records in default listings is a security/privacy bug, not a UX bug, and it deserves explicit contract tests before rollout.

How to Pitch It (Stakeholders)

For executives: This is a free, Apache-2.0 licensed adapter that closes a small but real integration gap. It lets us expose "delete, restore, permanently delete" behavior through our standard JSON:API interface while using a faster boolean-based soft-delete data model. License cost is zero; the real ask is a short engineering spike plus, if adopted, the discipline to vendor the code so we own it. It is not a strategic platform decision — it is a tactical enabler with low downside because the code is small and the license is permissive. Note the risk profile honestly: near-zero adoption means no upstream safety net, so the recommendation is approve the spike, not a committed dependency, and defer the production decision to the spike's results.

For engineering: The package connects the yocto/illuminate-database-softdeletes trait to laravel-json-api so schema adapters, the filter[trashed] values (with / only), and restore/force-delete actions work against a boolean column instead of deleted_at. It is glue at the persistence/API seam, and only pays off if we are already on both halves of the stack. Plan for: reading the vendor source rather than trusting the README (namespaces and the Yocto default column name vary by version), pinning the full compatibility matrix, and writing contract tests for the lifecycle — trashed filtering across all values, pagination and includes over trashed collections, restore round-trip, force-delete, route binding of trashed resources (restore returning 404 is a classic failure), authorization on trashed retrieval, and correct exclusion of deleted records from default listings. Assume we own maintenance: vendor the code, name a maintainer, and write the fork-and-own exit plan into the decision record before it reaches production.