Timeline Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer (note: Laravel doesn't natively support Symfony bundles, but you can integrate the underlying stephpy/timeline library directly):

   composer require stephpy/timeline
   

2. Basic Timeline Setup

   • Create a timeline entity (e.g., UserActivity):

     namespace App\Models;
     
     use Stephpy\Timeline\Annotation\Timeline;
     
     /**
      * @Timeline()
      */
     class UserActivity
     {
         // Your fields (e.g., user_id, action, timestamp)
     }
     

3. First Use Case: Display Timeline

   • Create a controller route to fetch and render timeline data:

     use Stephpy\Timeline\Timeline;
     use Stephpy\Timeline\TimelineItem;
     
     Route::get('/timeline', function () {
         $timeline = new Timeline();
         $timeline->addItem(new TimelineItem(
             'User logged in',
             '2023-01-01T12:00:00',
             'Login action'
         ));
     
         return view('timeline.index', ['timeline' => $timeline]);
     });
     

4. Include Timeline JS Add the timeline library to your resources/views/layouts/app.blade.php:

   <script src="https://cdn.jsdelivr.net/npm/timelinejs3@latest/dist/timeline.embed.min.js"></script>
   

5. Render Timeline in Blade

   <div id="timeline-embed" style="width: 100%; height: 600px;"></div>
   <script>
       var timeline = new TL.Timeline("timeline-embed", {
           embed: true,
           json: @json($timeline->toArray())
       });
   </script>
   

Implementation Patterns

Workflows

1. Entity-Based Timeline Integration

   • Pattern: Attach timeline behavior to Eloquent models using traits or annotations.
   • Example:

     use Stephpy\Timeline\Traits\Timelineable;
     
     class UserActivity extends Model
     {
         use Timelineable;
     
         protected $timelineItems = [];
     }
     

   • Workflow:
     • Add items via model methods:

       $activity->addTimelineItem('Commented on post', '2023-01-01');
       $activity->save();
       

     • Fetch timeline data in controller:

       $timeline = $activity->getTimeline();
       

2. Notification System

   • Pattern: Use the bundle’s notification system for unread counts and bulk actions.
   • Example:

     // Mark all notifications as read
     $this->timelineService->markAllAsRead($userId);
     
     // Get unread count
     $unreadCount = $this->timelineService->getUnreadCount($userId);
     

3. Custom Timeline Rendering

   • Pattern: Extend the default timeline template or use custom JSON data.
   • Example:

     $timeline = new Timeline();
     $timeline->setCustomTemplate('custom_timeline_template');
     $timeline->addItem(new TimelineItem(
         'Custom Event',
         '2023-01-01',
         'Custom content',
         ['class' => 'custom-event']
     ));
     

4. Event-Driven Updates

   • Pattern: Trigger timeline updates via Laravel events.
   • Example:

     // In an event listener
     public function handle(UserLoggedIn $event)
     {
         $timeline = new Timeline();
         $timeline->addItem(new TimelineItem(
             'User logged in',
             now()->toDateTimeString(),
             'IP: ' . $event->ip
         ));
         $timeline->saveToModel($event->user);
     }
     

Integration Tips

• Laravel Service Provider: Create a service provider to bind the timeline library:

  namespace App\Providers;
  
  use Stephpy\Timeline\Timeline;
  use Illuminate\Support\ServiceProvider;
  
  class TimelineServiceProvider extends ServiceProvider
  {
      public function register()
      {
          $this->app->singleton(Timeline::class, function () {
              return new Timeline();
          });
      }
  }
  

• API Integration: Return timeline data as JSON for SPAs:

  Route::get('/api/timeline', function () {
      $timeline = resolve(Timeline::class);
      return response()->json($timeline->toArray());
  });
  

• Caching: Cache timeline data for performance:

  $timeline = Cache::remember("timeline_{$userId}", now()->addHours(1), function () use ($userId) {
      return $this->timelineService->getTimelineForUser($userId);
  });
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Conflicts

   • The bundle is designed for Symfony, so direct Laravel integration may require workarounds (e.g., mocking Symfony components).
   • Fix: Use the standalone stephpy/timeline library and avoid Symfony-specific features.

2. Doctrine ORM Assumptions

   • The bundle assumes Doctrine ORM/ODM. For Laravel’s Eloquent, you’ll need to manually map entities.
   • Tip: Use traits or interfaces to abstract timeline behavior:

     interface Timelineable
     {
         public function getTimelineItems();
         public function addTimelineItem(string $title, string $date, string $text);
     }
     

3. Timeline JS Version Mismatch

   • The bundle uses timeline.js v3, but CDN versions may vary. Test thoroughly for rendering issues.
   • Fix: Use a specific version:

     <script src="https://cdn.jsdelivr.net/npm/timelinejs3@3.1.2/dist/timeline.embed.min.js"></script>
     

4. Notification System Limitations

   • The notification system relies on Symfony’s event system, which may not translate cleanly to Laravel.
   • Workaround: Implement a custom notification tracker using Laravel’s notifiable trait or a separate table.

5. Date Handling Quirks

   • The timeline expects ISO 8601 dates. Laravel’s Carbon instances must be converted:

     $date = now()->toDateTimeString(); // Use this instead of Carbon directly
     

Debugging Tips

1. Timeline Data Validation

   • Ensure timeline items have valid dates and non-empty titles:

     if (empty($item->getDate()) || empty($item->getTitle())) {
         throw new \InvalidArgumentException("Timeline item requires date and title.");
     }
     

2. Check for JavaScript Errors

   • Inspect the browser console for timeline.js errors (e.g., missing data or invalid JSON).
   • Fix: Validate JSON structure:

     $timelineData = $timeline->toArray();
     \Log::debug('Timeline JSON:', [$timelineData]);
     

3. Doctrine Query Debugging

   • If using Eloquent, log queries to identify N+1 issues:

     \DB::enableQueryLog();
     $timeline = $activity->getTimeline();
     \Log::debug(\DB::getQueryLog());
     

4. Caching Issues

   • Clear Laravel cache after config changes:

     php artisan cache:clear
     php artisan view:clear
     

Extension Points

1. Custom Timeline Items

   • Extend the TimelineItem class to add custom fields:

     class CustomTimelineItem extends TimelineItem
     {
         private $customField;
     
         public function __construct(string $title, string $date, string $text, $customField)
         {
             parent::__construct($title, $date, $text);
             $this->customField = $customField;
         }
     
         public function getCustomField()
         {
             return $this->customField;
         }
     }
     

2. Override Timeline Rendering

   • Create a custom template in resources/views/vendor/timeline/items.blade.php:

     <div class="custom-timeline-item">
         <h3>{{ $item->getTitle() }}</h3>
         <p>{{ $item->getText() }}</p>
         <small>{{ $item->getDate() }}</small>
     </div>
     

3. Add Timeline to Existing Models

   • Use Laravel’s accessors to dynamically generate timelines:

     class UserActivity extends Model
     {
         public function getTimelineAttribute()
         {
             return collect($this->items)->map(function ($item) {
                 return [
                     'title' => $item->action,
                     'date' => $item->created_at->toDateTimeString(),
                     'text' => $item->description,
                 ];
             })->toArray();
         }
     }
     

4. Integrate with Laravel Events