Laravel Archivable Laravel Package

Getting Started

• Install with composer require nexusbrother/laravel-archivable and review the package README first. The 1.0.1 release is a patch update, so expect bug fixes only; no breaking changes are indicated by the changelog link.
• Publish any package assets: php artisan vendor:publish --provider="Nexusbrother\Archivable\ArchivableServiceProvider" (check the README for the exact provider/tag).
• Run the published migration to add the archive column/table. Inspect the migration before running it in production, especially if the package adds indexes or foreign keys.
• Add the Archivable trait to the Eloquent model you want to archive:

  use Nexusbrother\Archivable\Traits\Archivable;
  
  class Order extends Model
  {
      use Archivable;
  }
  

• First use case: archive old orders instead of deleting them, then query active orders normally while keeping archived records available for audits/reporting.

  $order->archive();
  $activeOrders = Order::all(); // archived records excluded by default
  $archivedOrders = Order::onlyArchived()->get();
  

Implementation Patterns

• Default scope vs explicit queries: Most archivable packages add a global scope excluding archived records. Use the package's withArchived() / onlyArchived() scopes rather than manually removing global scopes where possible.

  Order::withArchived()->where('customer_id', $id)->get();
  Order::onlyArchived()->paginate();
  

• Archiving and restoring in workflows: Wrap archive/restore operations in transactions when they trigger related model changes or events.

  DB::transaction(function () use ($order) {
      $order->archive();
      $order->notes()->archive();
  });
  

• Scheduled archival: Use a queued job or console command to archive stale records in chunks. Avoid loading entire tables into memory.

  Order::where('created_at', '<', now()->subYears(2))
      ->chunkById(500, fn ($orders) => $orders->each->archive());
  

• Admin/reporting screens: Explicitly include archived records in admin queries. Consider a dedicated “Archived” filter instead of relying on the default scope.
• Relationships: Decide whether related models should be archived alongside the parent. If the package does not cascade automatically, implement cascading in a service class or model event.
• API resources: Archived models may still be returned by relationship queries if the related model’s global scope is not applied. Use withArchived() intentionally and document it.
• Bulk operations: Prefer package-provided bulk archive methods if available. If using update(), remember that model events may not fire, so audit hooks can be skipped.
• Testing: Use factories with archived states if the package provides them, or call archive() explicitly in tests. Assert both default-scope behavior and explicit archived queries.

Gotchas and Tips

• Global scope surprises: Archived records disappear from queries unexpectedly. Debug with Order::withoutGlobalScopes()->find($id) to confirm the record exists and is archived.
• Unique constraints: Archiving instead of deleting keeps rows in the table, so unique indexes on fields like email or slug can block re-use. Plan partial indexes or include the archived flag in uniqueness rules.
• Foreign keys: If archived records remain in the same table, foreign key constraints still apply. If the package moves records to an archive table, verify foreign key behavior and restore ordering.
• Migration order: Run the package migration before deploying code that uses the trait. In rolling deployments, deploy migrations first, then application code.
• Config caching: After changing package config, run php artisan config:clear locally and php artisan config:cache in production if your deployment uses config caching.
• Events and observers: Check whether archive() and restore() fire model events. Use observers for audit logging, but avoid infinite loops when an observer archives related models.
• Mass assignment: Ensure archive-related columns are guarded or handled by the package. Do not allow user input to set archived_at directly.
• Upgrading to 1.0.1: Run composer update nexusbrother/laravel-archivable, review the GitHub compare link for the actual commits, and run your test suite. Since this is a patch release, focus regression testing on archival/restore behavior rather than expecting new APIs.
• Extension points: Look for package events, configurable column names, custom archive table names, and overridable methods in the trait. Prefer overriding those over forking the package.