Core Bundle Laravel Package

Getting Started

• Install the package via Composer, then publish its config and migrations (php artisan vendor:publish --tag=...) and run php artisan migrate before touching any entity.
• Add the package trait to the entity model(s) you want tracked. Start with a single low-risk model to confirm history rows are written on create/update.
• First use case: put history on an entity that also supports archiving. Create, update, then archive the record and inspect the history table — as of v1.19.0 the history is reset automatically on archive, so this is the first behavior to verify in your environment.
• If the default reset is wrong for that entity, override resetOnArchive() on the model before wiring archiving into real workflows.

Implementation Patterns

• Trait-based tracking. Apply the package trait per model; keep the tracked field set explicit rather than "everything" so history stays small and readable.

• Archive lifecycle hook. Archiving an entity now triggers an automatic history reset. Treat archive as a lifecycle boundary: whatever you want preserved for compliance must be copied out (or the reset disabled) before the archive call.

• Per-entity opt-out. Override resetOnArchive on the entity to return false where archiving is a soft-hide rather than a disposal. This is the intended extension point, so keep the logic declarative:

  public function resetOnArchive(): bool
  {
      return $this->should_purge_history ?? true;
  }
  

• Conditional resets. If only some archives should purge history, encode the decision in the override (a model attribute, an enum on the entity, a config flag) instead of branching at every call site — the archive call stays uniform and the policy lives with the entity.

• Bulk archives. Archiving in loops or batches now fans out into history deletes. Wrap batch operations in a transaction, chunk large sets, and consider a queued job per entity so a failed reset doesn't abort the whole batch.

• Service-layer archiving. Keep archive() calls behind a small action/service class so you can add logging, authorization, and post-archive side effects in one place rather than scattering them across controllers.

• Testing. In feature tests, assert both the entity state and history count around archive(). Use RefreshDatabase and disable events when seeding, otherwise seed-time archives will silently reset fixtures' history.

• Restore semantics. Decide up front whether "unarchive" should re-create history from scratch; the reset is one-way, so any restore path that expects the old trail needs its own reconstruction logic.

Gotchas and Tips

• Silent history loss is the headline risk. v1.19.0 changes existing archive flows: entities that used to retain history will now drop it. Audit every model that uses archiving before deploying, and add a regression test per model asserting the expected reset behavior.
• Method resolution. The override must be defined on the entity class (or a parent that wins in trait resolution). If your model extends a base model that already defines resetOnArchive, your override may never run — check with class_uses and a quick dd() in the method.
• Signature and return type. Match the package's declared return type exactly; a mismatched signature will fatal at call time rather than at boot, so it won't show up until someone archives.
• Archive ≠ delete. If your compliance story relies on history surviving archival, default-on reset is the wrong default for you. Flip it to opt-in per entity rather than relying on reviewers catching it.
• Events and listeners. Observers and queued listeners that read history during/after an archive may now see an empty trail. Check ordering assumptions and any listeners reacting to the archive event.
• Polymorphic references. History rows keyed by morph map can be left orphaned or wiped in bulk; confirm the reset respects your morph aliases and doesn't cascade into unrelated entity types.
• Config and deploy quirks. Run php artisan config:cache after config changes, and ensure migrations are applied before the first archive in a fresh environment (seeders included).
• Debugging resets. Log inside your resetOnArchive override and around the archive call to confirm which branch ran; the reset itself is quiet, so without logging a "missing history" bug looks like a tracking failure.
• Performance. Bulk archives now issue bulk deletes against the history table. Index the foreign key columns history uses, and chunk operations so large archives don't lock history for long.
• Extension point hygiene. Because resetOnArchive is a plain method override, keep it side-effect free and cheap — it may be evaluated per entity during batch archives.