Timeline Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bkstg/timeline-bundle
   

   Add to config/app.php under providers:

   Backstage\TimelineBundle\TimelineBundle::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Backstage\TimelineBundle\TimelineBundle" --tag=config
   

   Locate config at config/timeline.php.

3. First Use Case Create a timeline entry via CLI:

   php artisan timeline:create --event="Project Kickoff" --description="Team alignment meeting" --user=1
   

   Verify in database (timeline_events table) or via:

   $events = \Backstage\TimelineBundle\Entity\TimelineEvent::all();
   

Implementation Patterns

Core Workflows

1. Event Creation

   • Manual: Use TimelineEvent entity with Eloquent:

     $event = new \Backstage\TimelineBundle\Entity\TimelineEvent();
     $event->event = "Code Review";
     $event->description = "Review PR #42";
     $event->user_id = auth()->id();
     $event->save();
     

   • Automated: Trigger via observers/queues (e.g., after Issue::created):

     use Backstage\TimelineBundle\Services\TimelineService;
     
     class IssueObserver {
         public function created(Issue $issue) {
             app(TimelineService::class)->createEvent(
                 "Issue Created",
                 "Issue #{$issue->id} opened",
                 auth()->id(),
                 ['issue_id' => $issue->id]
             );
         }
     }
     

2. Displaying Timelines

   • API Endpoint: Use the bundle’s built-in controller:

     Route::get('/timeline', [TimelineController::class, 'index']);
     

   • Custom View: Fetch events via repository:

     $events = app(\Backstage\TimelineBundle\Repository\TimelineEventRepository::class)
         ->findByUser(auth()->id(), 10); // Last 10 events
     

     Render with Blade:

     @foreach($events as $event)
         <div class="timeline-item">
             <h3>{{ $event->event }}</h3>
             <p>{{ $event->description }}</p>
             <small>{{ $event->created_at->diffForHumans() }}</small>
         </div>
     @endforeach
     

3. Filtering/Sorting

   • Use repository methods:

     // Events for a project (custom metadata)
     $events = $repo->findByMetadata('project_id', 5);
     
     // Events between dates
     $events = $repo->findBetween(
         Carbon::yesterday(),
         Carbon::tomorrow()
     );
     

Gotchas and Tips

Pitfalls

1. Metadata Handling

   • The metadata field is stored as JSON. Ensure data is serializable:

     // ❌ Fails: Circular reference
     $event->metadata = ['user' => auth()->user()];
     
     // ✅ Works: Use IDs or arrays
     $event->metadata = ['user_id' => auth()->id()];
     

2. User Association

   • The user_id is required but not validated by default. Add to your TimelineEvent model:

     protected $with = ['user']; // Eager-load user
     public function user() {
         return $this->belongsTo(User::class);
     }
     

3. CLI Command Quirks

   • The timeline:create command lacks --metadata support. Extend it:

     // app/Console/Commands/CreateTimelineEvent.php
     protected $signature = 'timeline:create
         {--metadata= : JSON metadata (e.g., --metadata={"key":"value"})}';
     

Debugging

• Missing Events? Check timeline_events table and ensure:

  • user_id exists in users table.
  • No database transactions are rolled back silently.

• Performance Add indexes to timeline_events(user_id, created_at):

  php artisan schema:dump --prune
  

  Then manually add:

  Schema::table('timeline_events', function (Blueprint $table) {
      $table->index(['user_id', 'created_at']);
  });
  

Extension Points

1. Custom Event Types Override the TimelineEvent entity or use traits:

   namespace App\Entities;
   
   use Backstage\TimelineBundle\Entity\TimelineEvent as BaseEvent;
   
   class CustomTimelineEvent extends BaseEvent {
       protected $casts = [
           'priority' => 'integer', // Add custom fields
       ];
   }
   

2. Webhook Integration Listen for timeline.event.created events:

   Event::listen('timeline.event.created', function ($event) {
       // Send Slack notification, etc.
   });
   

3. Testing Use the TimelineEventFactory for fixtures:

   $event = TimelineEventFactory::create()
       ->event('Deployment')
       ->user($user)
       ->create();