Bonchaq Laravel Package

Getting Started

Install the package with Composer and run its migrations before adding maturity tracking to existing models. Publish any config if the package exposes it, then clear config cache so the new delete/restore behavior is active.

Look first at:

1. The README section for the maturity trait/contract and model setup.
2. The package migration to see how maturity records are stored and whether they use soft deletes.
3. The package tests for delete/restore if you rely on soft-deleted parent models.
4. The service provider/config for lifecycle hooks or cascade settings.

The first practical use case is a model that already uses SoftDeletes and has associated maturity records—contracts, subscriptions, warranties, loans, credentials, or similar. Upgrade to 1.3.1 or later if deleting and restoring that parent model should keep its maturity records consistent.

Conceptually, the setup is:

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
use Vendor\Package\Concerns\HasMaturities; // confirm exact namespace in README

class Contract extends Model
{
    use SoftDeletes;
    use HasMaturities;
}

Then create maturity records through the package’s relation/API rather than hand-rolling cascading logic. Let the package handle what happens when the parent is deleted or restored.

Implementation Patterns

Treat delete/restore as a lifecycle workflow. Since 1.3.1 specifically handles maturity behavior on delete and restore, avoid adding your own observer that also deletes/restores maturity records. Duplicating that logic is the fastest way to get double-processing or inconsistent states.

Create parent and maturities transactionally. If a contract/subscription is created with one or more maturity dates, wrap the parent creation and maturity creation in a database transaction. This keeps the package’s lifecycle assumptions valid from the first write.

Use model instances for deletes when maturities matter. Prefer:

$contract->delete();
$contract->restore();

over bulk query deletes when you expect the package to react to the lifecycle. Bulk operations can bypass Eloquent model events depending on how the package hooks in.

Query with deleted-state awareness. For dashboards and APIs, explicitly decide whether trashed parents should expose their maturities. Use the package scopes if available, or combine them with withTrashed() / onlyTrashed() deliberately rather than accidentally showing restored or deleted maturity data.

Keep admin/API resources aligned. If you expose maturity records through API resources, Filament/Nova resources, or dashboards, include the parent’s deleted/restored state in filters and policies. A restored parent should not appear to have “lost” maturities, and a deleted parent should not continue to drive overdue notifications.

Schedule maturity jobs against active parents. Notification or status-transition jobs should join/query only parents that are not deleted, unless the business rule explicitly requires trashed records. Re-run these jobs after restore to catch anything that became active again.

Test the lifecycle explicitly. Add feature tests for:

$contract->delete();
$this->assertSoftDeleted($contract);
// assert maturity records are in the expected deleted/inactive state

$contract->restore();
$this->assertNotSoftDeleted($contract);
// assert maturity records are restored/reactivated exactly once

Use the package’s extension points sparingly. If you need custom maturity calculation, status labels, or notification timing, prefer config, scopes, or a small service around the package rather than overriding lifecycle behavior that 1.3.1 now owns.

Gotchas and Tips

• Force deletes are different from soft deletes. 1.3.1 improves delete and restore, but hard deletes may still permanently remove or orphan maturity data depending on your foreign keys and config. Test forceDelete() separately if you expose it.
• Bulk deletes may bypass model events. Model::where(...)->delete() is not equivalent to calling delete() on each model. If maturities must follow the parent lifecycle, use instance deletes or the package’s documented bulk-safe method.
• Restore is not always idempotent by default. Verify that restoring an already-restored parent, or restoring a parent whose maturities were manually changed, does not duplicate or overwrite records unexpectedly.
• Watch event ordering. If you have existing observers for deleting, deleted, restoring, or restored, confirm they do not also mutate maturity records. Let the package handle its own records unless you have a clear reason not to.
• Clear config cache after upgrades. Run php artisan config:clear and, in production, your normal deploy cache rebuild. Lifecycle/config behavior can appear “stuck” after a package update if cached config is stale.
• Check date casting and timezone handling. Maturity dates are usually business-date sensitive. Confirm whether the package stores dates as date, datetime, or timestamps, and keep app timezone behavior consistent with scheduled jobs.
• Add database constraints where possible. A foreign key from maturity records to the parent model helps catch orphaned records, especially if custom code or force deletes are introduced later.
• Debug lifecycle issues with events and SQL logs. If delete/restore behavior looks wrong, log model events and enable query logging around the operation. Confirm whether the package is acting through Eloquent events, observers, or explicit service calls.
• Prefer restoring the parent, not manually restoring children. In normal flows, call restore() on the parent and let 1.3.1 align maturities. Manual child restoration should be reserved for data repair or migration scripts.