Timeline Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stephpy/timeline
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Stephpy\Timeline\TimelineServiceProvider"
   

2. First Use Case: Create a timeline in a controller:

   use Stephpy\Timeline\Timeline;
   
   public function showTimeline()
   {
       $timeline = Timeline::create()
           ->addEntry('2023-01-15', 'User registered', ['user_id' => 123])
           ->addEntry('2023-01-16', 'First purchase', ['amount' => 99.99]);
   
       return view('timeline.view', ['timeline' => $timeline]);
   }
   

3. Blade Rendering: Use the included Blade directive:

   @timeline($timeline)
   

   Or customize with a view:

   @include('timeline::default', ['timeline' => $timeline])
   

Implementation Patterns

Core Workflows

1. Event-Based Timelines:

   // In an event listener
   public function handle(OrderShipped $event)
   {
       Timeline::create()
           ->addEntry(now(), 'Order shipped', ['order_id' => $event->order->id])
           ->save(); // Persists to database if configured
   }
   

2. Dynamic Grouping:

   $timeline = Timeline::create()
       ->groupBy('type') // Groups entries by metadata key
       ->addEntry(..., ['type' => 'payment'])
       ->addEntry(..., ['type' => 'notification']);
   

3. Integration with Eloquent:

   // Fetch timeline from a model
   $user = User::find(1);
   $timeline = $user->timeline()->get(); // Assumes `hasMany` relationship
   

Advanced Patterns

• Custom Entry Classes:

  class CustomEntry extends \Stephpy\Timeline\Entry
  {
      public function getIcon()
      {
          return '✉️';
      }
  }
  Timeline::create()->addEntry(new CustomEntry(...));
  

• Pagination:

  $timeline = Timeline::create()->paginate(10);
  

• Conditional Rendering:

  @timeline($timeline, [
      'show_dates' => true,
      'group_by' => 'category',
      'template' => 'custom.timeline'
  ])
  

Blade Component Integration

<!-- Register custom component -->
@php
    view()->share('timelineComponent', function ($timeline) {
        return \Stephpy\Timeline\Blade::render($timeline, 'custom.view');
    });
@endphp

<!-- Usage -->
@timelineComponent($timeline)

Gotchas and Tips

Common Pitfalls

1. Date Handling:

   • Ensure dates passed to addEntry() are Carbon instances or ISO strings. Ambiguous formats may cause sorting issues.
   • Fix: Use now() or Carbon::parse() for consistency.

2. Metadata Overwrite:

   • Subsequent addEntry() calls with the same key overwrite metadata. Use arrays for cumulative data:

     ->addEntry(..., ['tags' => ['new', 'old']]) // Merges if configured
     

3. Grouping Quirks:

   • groupBy() requires metadata keys to exist in all entries. Use groupBy(fn($entry) => $entry->metadata['key'] ?? 'default') for fallback.

4. Database Persistence:

   • The package doesn’t auto-migrate. Run:

     php artisan vendor:publish --tag=timeline-migrations
     php artisan migrate
     

   • Tip: Disable persistence for read-only timelines to avoid overhead.

Debugging Tips

• Inspect Raw Data:

  dd($timeline->getEntries()->toArray());
  

• Check Config:

  dd(config('timeline'));
  

  • Key settings: default_template, date_format, enable_persistence.

Extension Points

1. Custom Templates:

   • Override resources/views/vendor/timeline/default.blade.php.
   • Tip: Use @inject('timeline', 'Stephpy\Timeline\Timeline') in custom views.

2. Event Listeners:

   • Extend the TimelineSaved event to trigger actions post-save:

     Timeline::saved(function ($timeline) {
         // Send notification, log, etc.
     });
     

3. Filtering:

   • Use the filter() method with closures:

     $timeline->filter(fn($entry) => $entry->metadata['status'] === 'active');
     

4. Performance:

   • For large datasets, use ->limit(100) or lazy-load entries:

     $timeline->getEntries()->take(50);