Laravel Time Series Laravel Package

Technical Evaluation

Architecture fit

• The package is a conventional Laravel add-on: a service provider, publishable config, migrations for a series-style table plus an entries-style table, and Eloquent models with query/aggregation helpers on top. That is the same shape as our existing domain models, so it slots into a monolith or a modular Laravel app without introducing a new runtime, daemon, or external datastore.
• The data model is row-per-datapoint with aggregation computed at query time (period/interval/date-range filters, sum/avg/min/max per bucket). This is a good fit for product-facing reporting — signups per day, orders per hour, usage counters — where cardinality is bounded and reads are dashboard-driven.
• It is not a time-series database. It will not replace Prometheus/InfluxDB/ClickHouse for high-cardinality observability, per-second metrics, or retention policies measured in years. Scope it to application reporting, not infrastructure telemetry.
• Caching support is a genuine architectural plus for the dashboard use case, but it is a read-path band-aid, not a substitute for indexing or pre-aggregation. We should treat cache as an optimization we own, not a scaling guarantee.

Integration feasibility

• Low ceremony: composer require, publish migrations/config, run migrations, define series, write points, query. A Laravel developer can produce a working spike in under a day.
• The real feasibility question is version compatibility, not design. Last release was 2022-02-27 and the highest tag is v1.0.0-beta-9, meaning the public API has never been declared stable. We must verify against our actual target (Laravel 10/11, PHP 8.2/8.3, Carbon 2.x/3.x, MySQL 8 / Postgres 15) before committing.
• Effort estimate: 1–2 dev-days for a compatibility + performance spike; roughly one sprint to harden (abstraction layer, retention job, indexes, tests) before production use.

Technical risk

• Maintenance staleness (high). Single maintainer, 96 stars, no release in over two years, still pre-1.0. Bus factor is effectively one. Assume we will own this code.
• Pre-1.0 API instability (medium). Beta tags reserve the right to break signatures. Any direct use of package classes should be wrapped so an upgrade or fork swap is contained.
• Query performance at volume (medium-high). Bucketing by arbitrary interval typically means date-truncation functions in GROUP BY, which are not sargable against a plain timestamp index. Cost grows with range width, not just row count. Wide date ranges and short intervals are the worst case.
• Correctness edge cases (medium). Timezone/DST bucketing in interval aggregation is a classic source of off-by-one and double-counted hours; DB portability of date functions across MySQL/Postgres/SQLite is another. These need explicit tests, not assumptions.
• Dependency drift (medium). Eloquent/Carbon/DBAL major bumps are the most likely breakage vector on our next framework upgrade.

Key questions

1. What is our expected write rate and total entry volume at 12 months, and what retention window do we need?
2. What are the read patterns — fixed dashboard ranges, or arbitrary user-selected ranges and intervals?
3. Which database engines must be supported (prod vs. CI vs. local SQLite)?
4. Is aggregation executed in SQL or in PHP? (Determines the scaling ceiling.)
5. How does the package handle timezones and DST in bucketing, and is that documented/tested?
6. Does it support multi-tenancy cleanly (tenant-scoped series, or do we add a discriminator ourselves)?
7. Does it enforce uniqueness on (series, timestamp) to make writes idempotent under retry?
8. What is our appetite for forking an MIT package and owning it internally?
9. Does any existing hand-rolled metrics/reporting table need migration, and is backfill acceptable as a one-off?
10. Is the cache layer compatible with our cache driver and invalidation strategy (tags supported? Redis?).

Integration Approach

Stack fit

• Standard Laravel service-provider package; no infrastructure additions. It sits behind our existing cache and queue, and can be wrapped in a MetricsRepository/service class so controllers, dashboards, and jobs never touch package classes directly.
• Fits best as the reporting read-model for product metrics. Keep it out of request-critical write paths until write throughput is measured.

Migration path

• Greenfield: no migration. Publish migrations, add indexes on (series_id, created_at/timestamp) if not already present, and create series via seeders or an admin surface.
• Replacing hand-rolled tables: run in parallel — dual-write to the new series while reading from the old path, backfill history with a chunked job, then cut reads over behind a feature flag. Keep the old tables for one release cycle as a rollback path.
• Escape hatch: because the license is MIT, a fork is a legitimate migration path. Plan for it rather than treating it as failure — vendor the fork under our org, pin the SHA, and treat upstream as a source of patches only.

Compatibility

• Establish a CI matrix leg that runs the package against our exact Laravel/PHP/database versions before any code is written against it. Treat that leg as a permanent canary.
• Verify: Carbon major version, PHP 8.2+ deprecations (dynamic properties, implicit nullable), doctrine/dbal presence if column changes are needed, and DB-specific date functions.
• Pin the composer constraint explicitly (e.g., 1.0.0-beta9 exact or a narrow range) — never * or an open ^ on a beta.

Sequencing

1. Spike (week 1): install on a branch, run the CI matrix, load-test with realistic volume (e.g., 10M entries) to measure aggregation latency across typical ranges.
2. Decide (end week 1): build-vs-buy gate — proceed if latency and compat are acceptable and the wrapper is thin; otherwise implement a minimal internal equivalent (two tables + a bucketing query builder) at comparable cost to hardening the fork.
3. Wrap (week 2): introduce the repository abstraction, timezone/DST tests, unique constraint, and a retention/pruning command.
4. Pilot (week 3): one non-critical dashboard, feature-flagged, with query timing and cache hit-rate instrumented.
5. Roll out (week 4+): migrate remaining reporting surfaces incrementally; document the fork policy and upgrade runbook.

Operational Impact

Maintenance

• Treat this as internally owned code from day one. Budget roughly 2–5 engineer-days per year for routine upkeep, plus a spike on each Laravel major upgrade.
• Keep a fork with a pinned version and a documented divergence log. Upstream is unlikely to ship fixes; our fork is the support contract.
• Watch the entries table like a first-class asset: monitor row count growth, index bloat, and slow-query logs on the aggregation path.

Support

• Community-only, no vendor SLA, sparse documentation (mostly README). No external escalation path.
• Mitigation: internal runbook covering schema, retention job, cache invalidation, and the fork/upgrade procedure; plus contract tests that pin expected aggregation behavior so a fork or upgrade can be validated quickly.
• On-call implication is modest if scoped to dashboards — a broken report is a degraded feature, not an outage. Keep it off the critical write path to preserve that property.

Scaling

• Write path scales linearly with inserts; the ceiling is DB write throughput and index maintenance, not the package.
• Read path is the constraint. Mitigations in order of preference: (1) index on (series_id, timestamp); (2) cache with sane TTLs and per-tenant/user keying; (3) pre-aggregated rollup tables populated by scheduled jobs for the ranges dashboards actually request; (4) table partitioning by time plus a retention/pruning job; (5) read replica for reporting queries.
• Add a hard cap on queryable range and minimum interval at the API boundary — the cheapest way to prevent a user from requesting five years at one-minute granularity.

Failure modes

• Slow aggregation on wide ranges → request timeouts and DB CPU spikes; mitigate with range caps, rollups, and replicas.
• Cache stampede on popular dashboards after TTL expiry or deploy; mitigate with jittered TTLs and a short lock.
• Unbounded table growth without a retention job → degrading writes and backups; mitigate with a scheduled prune/partition drop.
• DST/timezone bucketing errors → silently wrong reports; mitigate with explicit timezone-boundary tests.
• Duplicate points on retry if no uniqueness constraint → inflated sums; mitigate with a unique index and upsert writes.
• Beta API break or abandoned upstream → forced fork; mitigated by the wrapper and pinned version.
• Framework upgrade breakage (Carbon/Eloquent) → caught by the permanent CI matrix leg.

Ramp-up

• Low for anyone fluent in Laravel: roughly half a day to productive use, given the Eloquent-idiomatic API.
• The non-obvious parts are timezone/interval semantics and the caching layer — those need a short internal write-up rather than being left to discover in production.
• Overall recommendation: adopt conditionally — good fit for product reporting behind a thin abstraction, contingent on the compatibility and load spike passing and on explicit acceptance that we own a fork.