Timelinebundle Laravel Package

Getting Started

Read this first: v4.0.0 is a compatibility-only release. The sole change is "Symfony5" (PR #219) — the bundle now requires Symfony 5 and no longer supports Symfony 4. There are no new features, no deprecations, and no API changes called out. Treat this as a hard upgrade gate, not a feature upgrade.

What this package actually is: stephpy/timeline-bundle is a Symfony bundle, not a Laravel package. It provides Doctrine-backed activity-feed / timeline persistence: you push() an action into a component's timeline and read it back ordered by date. A Laravel developer will usually encounter it in one of two situations:

1. Doctrine/Symfony interop — you're sharing a database or a service layer with a Symfony 5 app and need the same timeline tables.
2. Borrowing the pattern — you're modelling an activity feed in Eloquent and want a reference implementation.

Minimal steps if you genuinely need the bundle (Symfony 5 host required):

1. composer require stephpy/timeline-bundle:^4.0 — this will fail on Symfony 4.x or PHP below the bundle's floor; that failure is the breaking change.
2. Map the four classes in config/packages/stephpy_timeline.yaml: action, component, timeline, timeline_action — pointing at your own Doctrine entities (or the bundle's, if you use mapped superclasses).
3. Run the Doctrine schema diff to create timeline, timeline_action, etc.
4. Inject TimelineManager and make your first call:

   $timelineManager->push($component, $action, $subject);
   

   where $component is the timeline owner (e.g. a user), $action is the verb (e.g. "commented"), and $subject is the object acted upon.

First use case to build: a per-user activity feed ("Alice commented on Post #12") — the canonical use of this bundle.

Implementation Patterns

• Push-at-the-edge. Call push() from a domain event listener or service, not from controllers. The manager persists rows synchronously; there is no queueing in the bundle.
• Component as tenant. A Component is your feed bucket. Use user:{id} semantics so one user's feed is one timeline rather than one global table scan.
• Action as enum. Keep Action rows seeded and stable (like, comment, follow). Renaming an action row silently orphans history — treat them as append-only reference data.
• Read side. getTimeline($component) returns the timeline with its actions; paginate in your own repository layer rather than loading the whole feed. The bundle does not ship pagination.
• Delete/rebuild. deleteTimeline($component) is available for GDPR-style erasure or feed reset. This is a destructive operation — wrap it in a transaction and log it.
• Laravel-side mirror. If you're reimplementing in Eloquent: timelines (component), actions (verb lookup), timeline_actions (timeline_id, action_id, subject_type, subject_id, created_at) with a morph relation for the subject. Index (timeline_id, created_at) — that's the query you'll actually run.
• Integration tip: if you must consume the bundle from Laravel, do it through Doctrine (via laravel-doctrine/orm) and treat the bundle's config as static YAML you translate into a Doctrine connection config. It will not register itself as a Laravel service provider — there is no TimelineBundleServiceProvider.

Gotchas and Tips

• v4.0.0 is breaking for Symfony 4. This is the headline. If your host app is on Symfony 4.4 LTS with no upgrade path, stay on ^3.1 and pin it. There is no deprecation shim — the constraint simply won't resolve.
• No upgrade guide was published. The changelog is a single PR title. Before upgrading, diff the composer.json constraints yourself (PHP floor and symfony/* ranges) — do not assume a patch-level-smooth bump because the version jumped 3.1.1 → 4.0.0.
• Semantic versioning here is meaningful. A major bump for a one-line CI/constraint change means the maintainer treats framework support as part of the public API. Budget a lockfile-only upgrade, but verify your own Symfony version before merging.
• Config key drift is the usual debugging entry point. A typo in stephpy_timeline.drivers.orm.classes produces confusing Doctrine mapping errors rather than a clear "class not found" — the failure surfaces at schema build or first push(), not at container compile.
• No Laravel autodiscovery. Installing this in a Laravel app does nothing on its own. There is no facade, no published config, no migrations. Everything is manual wiring.
• Timezone/ordering. Timeline ordering comes from the persisted action date. If you set timestamps in application code, be explicit about UTC; Doctrine's datetime has no timezone, so mixed-offset writes will sort incorrectly.
• Extension points. The driver abstraction (drivers.orm) is the intended seam — if you need Redis or MongoDB-backed timelines, that is where you'd implement. Given the package's low activity (one commit between 3.1.1 and 4.0.0), avoid betting on upstream driver support and plan to own any custom driver.
• Maintenance signal. A major release containing exactly one dependency PR suggests maintenance mode. For a new Laravel project, prefer a native activity-log package and use this bundle only when Symfony interop is a hard requirement.