History Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require panoscape/history
   

   For Laravel 5.6.x, use composer require "panoscape/history:^1.0".

2. Publish Config & Migrations:

   php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=migrations
   php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=config
   

   Run migrations:

   php artisan migrate
   

3. Enable History for a Model: Use the HasHistory trait in your Eloquent model:

   use Panoscape\History\Traits\HasHistory;
   
   class User extends Model
   {
       use HasHistory;
   }
   

4. First Use Case: Track changes to a model:

   $user = User::find(1);
   $user->name = 'Updated Name';
   $user->save(); // Automatically records history
   

Implementation Patterns

Core Workflows

1. Tracking Changes:

   • Enable history on models via HasHistory trait.
   • All save(), update(), and create() operations are automatically tracked.
   • Example:

     $post = Post::find(1);
     $post->title = 'New Title';
     $post->save(); // History recorded in `history_entries` table
     

2. Querying History:

   • Access history entries via history() method:

     $history = $post->history()->latest()->get();
     

   • Filter by field or change type:

     $history = $post->history()->whereField('title')->get();
     

3. Customizing History:

   • Override getHistoryAttributes() to specify fields to track:

     protected function getHistoryAttributes()
     {
         return ['title', 'content', 'published_at'];
     }
     

   • Exclude fields from history:

     protected function getHistoryExcludedAttributes()
     {
         return ['password', 'api_token'];
     }
     

4. Manual History Recording:

   • Manually trigger history recording:

     $user->recordHistory(); // Manually record changes
     

5. Soft Deletes:

   • Enable soft deletes for history entries:

     use Panoscape\History\Traits\HasSoftDeletes;
     
     class HistoryEntry extends Model
     {
         use HasSoftDeletes;
     }
     

Integration Tips

• Events: Listen to history.created events for custom logic:

  History::created(function ($history) {
      // Custom logic (e.g., notifications)
  });
  

• APIs: Expose history endpoints in your API:

  Route::get('/posts/{post}/history', function (Post $post) {
      return $post->history()->latest()->get();
  });
  

• Admin Panels: Integrate with admin panels (e.g., Nova, Filament) for history views.

Gotchas and Tips

Pitfalls

1. Performance:

   • Tracking history adds overhead. Avoid enabling it on high-frequency models (e.g., visits).
   • Use getHistoryAttributes() to limit tracked fields.

2. Database Bloat:

   • History entries accumulate over time. Consider archiving old entries:

     HistoryEntry::where('created_at', '<', now()->subYears(1))->delete();
     

3. Soft Deletes:

   • If using soft deletes, ensure history_entries table has deleted_at column:

     Schema::table('history_entries', function (Blueprint $table) {
         $table->softDeletes();
     });
     

4. Mass Updates:

   • Mass updates (e.g., User::update(['active' => false])) may not trigger history. Use individual updates or manual recording:

     User::chunk(100, function ($users) {
         foreach ($users as $user) {
             $user->active = false;
             $user->save(); // Triggers history
         }
     });
     

5. Model Events:

   • Overriding saving() or saved() may interfere with history tracking. Use getHistoryAttributes() instead.

Debugging

• Missing History:

  • Check if HasHistory trait is applied.
  • Verify history_entries table exists and has correct columns (model_type, model_id, changes, etc.).
  • Enable Laravel debugging:

    History::setDebug(true); // Logs history operations
    

• Incorrect Changes:

  • Ensure getHistoryAttributes() includes the modified fields.
  • Use dd($history->changes) to inspect recorded changes.

Extension Points

1. Custom History Table:

   • Override the table name in config:

     'table' => 'custom_history_entries',
     

   • Publish and modify the migration:

     php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=migrations
     

2. Custom History Model:

   • Extend the HistoryEntry model:

     class CustomHistoryEntry extends Panoscape\History\Models\HistoryEntry
     {
         protected $table = 'custom_history';
     }
     

   • Bind it in HistoryServiceProvider:

     $this->app->bind(
         Panoscape\History\Models\HistoryEntry::class,
         CustomHistoryEntry::class
     );
     

3. Custom Change Format:

   • Override getChanges() in HasHistory trait to format changes differently:

     protected function getChanges(array $old, array $new)
     {
         return ['custom_format' => $old, 'custom_new' => $new];
     }
     

4. Middleware for History:

   • Use middleware to conditionally enable/disable history:

     public function handle($request, Closure $next)
     {
         History::disable();
         $response = $next($request);
         History::enable();
         return $response;
     }