Timeline Bundle Laravel Package

Getting Started

Reality check before you composer require anything: this is a Symfony bundle, not a Laravel package. Its composer.json type is symfony-bundle, it depends on Sonata and spy/timeline-bundle (Doctrine-based), and it ships a DependencyInjection/ extension plus Resources/config/*.yml instead of a Laravel ServiceProvider, Facade, or config/*.php. In a fresh Laravel app it installs but never boots — nothing registers, nothing autoloads a provider, nothing appears in php artisan about.

Where to look first:

1. composer.json — confirm "type": "symfony-bundle" and the require block (Sonata admin/block, spy/timeline-bundle, Symfony components, Doctrine). This tells you immediately it won't run in Laravel.
2. DependencyInjection/Configuration.php + *Extension.php — the actual config surface (timeline storage, block registration, service wiring).
3. Resources/config/ — service definitions; this is where the Sonata↔SpyTimeline glue lives.
4. The bundle class itself — usually a thin extends Bundle shell.
5. spy/timeline-bundle docs (not this repo) — the real data model (subjects/verbs/objects, timeline actions, spread, followers). This bundle is only glue.

First use case (Laravel-native): don't install it — port the concept. The SpyTimeline model is an activity feed: a timeline_actions table with polymorphic subject, verb, object, target, and timestamps. That's a migration + Eloquent model + an Event::listen/observer that writes rows. You'll get maintained code and Eloquent ergonomics instead of abandoned Doctrine plumbing.

Implementation Patterns

What the package actually does (Symfony/Sonata context): it registers the SpyTimeline services, wires a Sonata block for rendering a timeline/feed, and exposes a config tree so spy_timeline and Sonata admin/block can share the timeline action manager. Actions are emitted by listeners on domain events; the timeline manager persists them and "spreads" them to followers for feed delivery. Nothing here is Laravel-aware.

How a Laravel dev translates it (recommended workflow):

• Schema (mirrors the SpyTimeline shape):

  Schema::create('timeline_actions', function (Blueprint $table) {
      $table->id();
      $table->morphs('subject');          // who did it
      $table->string('verb');             // what they did
      $table->nullableMorphs('object');   // to what
      $table->nullableMorphs('target');   // for whom / where
      $table->timestamp('occurred_at')->index();
      $table->timestamps();
      $table->index(['subject_type', 'subject_id', 'occurred_at']);
  });
  

• Model: TimelineAction extends Model with morphTo('subject'), morphTo('object'), morphTo('target'), a verb cast to an enum, and a scopes for chronological/feed queries.
• Recorder service: TimelineRecorder->record(Subject $subject, string $verb, ?Model $object = null, ?Model $target = null). Call it from model observers (created, updated, deleted) or from domain events.
• Emission via events: Event::listen(OrderShipped::class, RecordTimelineAction::class) with the listener implementing ShouldQueue so fan-out doesn't block the request.
• Fan-out/spread: for a "feed" (as opposed to a global activity log), add a timeline_spreads table (action_id, follower_id) written by a queued listener — this is the Laravel equivalent of SpyTimeline's "spread."
• Rendering: a Blade component or API resource paginating occurred_at descending; use cursor pagination for large chronological feeds.
• If you genuinely need the Symfony path (legacy app): register in bundles.php/AppKernel, import spy_timeline + sonata_timeline config in YAML, and mount the Sonata block in your admin dashboard. That is the only context where this package does anything.

Integration tips: copy the schema and naming conventions, not the code. Keep verbs in an enum so you can filter feeds later. Queue the fan-out once follower counts grow. Keep the recorder injectable so tests can assert actions without hitting the DB.

Gotchas and Tips

• Abandoned. Archived: yes, Stars: 0, Dependents: 0. No security patches, no compatibility fixes, no issue triage. Treat it strictly as a reference implementation, never a production dependency.
• Composer type is the hard blocker. Installing it into Laravel adds dead weight to vendor/; Symfony bundle classes load but never boot because Laravel never calls register()/boot() on a Symfony\Component\HttpKernel\Bundle\Bundle. composer dump-autoload succeeding tells you nothing.
• Doctrine, not Eloquent. The underlying spy/timeline-bundle entities are Doctrine ORM/ODM. There is no Eloquent model, no morphTo, no HasMany — you'd be reimplementing everything anyway.
• Sonata ≠ Nova/Filament. The "Sonata integration" is Sonata admin/block; the Laravel admin equivalents (Nova, Filament) have no matching extension point.
• Version constraints likely conflict. Repos of this vintage pin old Symfony (~2.x era) and old PHP. Expect composer why-not output on any modern app. Check with composer why-not rmzamora/timeline-bundle before assuming it installs cleanly.
• No extension points reach Laravel. Config lives in a Symfony Configuration tree + compiler passes; there's no equivalent to Laravel\ServiceProvider, Event::listen hooks, or publishable config/ tags.
• Debugging in a Symfony host, if you must: bin/console debug:container | grep timeline, debug:config sonata_timeline, debug:event-dispatcher to confirm the timeline listeners are actually firing. In Laravel there's nothing to debug — which is the tell that it's the wrong tool.
• Best practice: port the concept. Read spy/timeline-bundle's data model, model it in Eloquent, drive emission from Laravel events/observers, and queue the spread. You get the same activity-feed semantics with maintained, idiomatic Laravel code and a security patching path.