Laravel Daily Activity Laravel Package

Product Decisions This Supports

• Feature go/no-go on streaks and daily check-ins. Habit tracking, learning streaks, login rewards, wellness check-ins, and GitHub-style "contribution calendar" surfaces are all directly supported by a single package. This turns a multi-sprint gamification feature into a small integration task, so it can be scheduled into an upcoming release rather than a quarter.
• Build vs. buy for the activity data store. The core design choice — a 46-byte annual bitmap per subject instead of one row per activity event — is a product-relevant cost decision, not just a technical one. One million subjects with a year of history is on the order of tens of megabytes rather than hundreds of millions of rows. That changes hosting cost, backup windows, and query latency at a scale where "just add a table" starts to hurt.
• Metric integrity for retention reporting. Per-day deduplication makes "active days" a well-defined, non-inflatable number. Product, growth, and finance can quote the same streak and active-day figures without arguing about whether five events in one hour count as one active day. Current streak and longest streak become reliable inputs to retention dashboards and experiment readouts.
• Roadmap sequencing for engagement work. Active-days-this-week / this-month, current streak, and longest streak are exactly the primitives behind streak-freeze mechanics, milestone rewards, re-engagement emails ("you're 2 days from your record"), and cohort analysis. Shipping the data layer first de-risks every downstream engagement bet.
• Backfill and correction as a product capability. Backdated entries and retroactive "make-up" check-ins let support fix user streaks after timezone disputes or outages, and let us import historical activity at launch so day-one users don't see empty calendars. That is a support-cost and launch-quality decision.
• Where it should not drive decisions. The bitmap is a query-optimized store, not an event log. It answers "was this subject active on day X" extremely well and "what did they do, in what order, how many times" not at all. If funnels, per-action audit trails, or hourly granularity are on the roadmap, this package is a complement to an event pipeline, not a replacement — and it must not be presented internally as an analytics solution.

When to Consider This Package

Adopt when most of the following hold:

• The product question is genuinely binary and daily — did the user show up today, and what is their streak. Not "how many times" or "how long."
• The subject is an Eloquent model, and may be polymorphic: users, teams, courses enrolment, devices. Anything with a morph relation works.
• You are on PHP 8.3+ and Laravel 12/13, on SQLite, MySQL, or PostgreSQL. Outside that matrix, evaluate against the framework version you actually run.
• History is long and cardinality is high. The bitmap's advantage compounds with years of retained activity across many subjects; at low volume a plain table is simpler and fine.
• Streak edge cases matter to you. Leap years, year boundaries, and DST/timezone transitions are where homegrown streak code produces support tickets. This package explicitly covers cross-year, leap-year, and app-timezone behaviour, plus a benchmark script comparing streak approaches.
• Writes are moderate and concentrated per subject. One bitmap row per subject per year means a hot row per active user; commit-after-cache and concurrency protection help, but very high parallel write volume against a single subject deserves a load test before committing.
• You want configurability without forking. Custom activity model and cache key prefix are supported, which is what makes wrapping it behind an internal interface practical.

Look elsewhere, or plan to extend, when:

• You need per-user timezones. Timezone handling is app-level; a global product with users in many zones will need per-subject offsets managed in your own layer, and that is real work to scope.
• You need event-level analytics — funnels, cohorts, counts per day, audit trails, or replay.
• You need sub-daily granularity (hourly activity, session length).
• You need multiple distinct activity types counted independently per day, where one bit per day is too coarse.
• You require commercial support, an SLA, or a security review with a vendor contact. v1.0.0 with a single maintainer and no prior release history is the main adoption risk; mitigate by pinning the version and isolating usage behind an internal adapter.
• The stack is not Laravel/PHP, or you are on an older PHP/Laravel combination this release does not declare support for.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is an off-the-shelf Laravel component that gives us daily-activity tracking, activity calendars, and streak counts — the mechanics behind most retention and habit features — for a few hours of integration instead of a multi-week build. It stores activity in an unusually compact form (46 bytes per user per year), so it lowers infrastructure cost rather than adding to it, and it makes "active days" and "streak" a single, consistent number across product, growth, and finance reporting. Risk is contained: it is an isolated, replaceable dependency behind our own interface, version-pinned, and the migration lives in our schema. Recommendation: adopt for the streak/calendar workstream, do not treat it as our analytics platform.

For engineering — the short version: A small, focused surface: publish config and migration, run it, use the model trait. Polymorphic subject support, per-day dedupe, explicit-date writes and backfill, calendar plus range/week/month active-day queries, current and all-time-longest streaks. App-timezone aware, handles year boundaries and leap years, and the streak path is optimized (lazy year reads for the current streak, byte-table scanning for the record) with a benchmark script in the repo. Configurable activity model and cache key prefix, cache writes deferred to transaction commit, concurrency protection included. PHP 8.3+, Laravel 12/13, SQLite/MySQL/PostgreSQL.

Shared risk register to state up front: v1.0.0, single maintainer, no long track record. Mitigations: pin to ^1.0, wrap behind an internal activity interface so the dependency is swappable, add our own tests for the edge cases we care about (DST, per-user timezone offsets if we go global, backfill under load), and load-test concurrent writes to a single hot subject before we rely on it for a launch spike.