Laravel Date Scopes Laravel Package

Product Decisions This Supports

• Build vs. buy on a commodity capability. Date-range filtering is something every Laravel product with a dashboard, activity feed, or admin panel eventually needs. This package turns a recurring "write three more Carbon scopes" chore into a one-line composer require. The build cost is small in absolute terms, but the cost of inconsistent implementations across teams is not — this is a standardization decision more than a technical one.
• Defining metric semantics before they become a dispute. The inclusive/exclusive question ("does 'last 7 days' include today?") is a business definition, not an engineering detail. The package's default_range config and per-query customRange override force this into a deliberate, documented decision instead of letting three developers each pick a different answer. Every report, invoice summary, and exec dashboard downstream inherits that decision.
• Which reporting features are cheap to ship. Period-to-date scopes (monthToDate, quarterToDate, yearToDate) are exactly the shapes that finance, sales, and ops stakeholders ask for. If those are on the roadmap, this package shortens the estimate on the reporting epic meaningfully.
• Lifecycle-stage analytics, not just creation analytics. The column: parameter (e.g. ofLast30Days(column: 'approved_at')) supports questions like "how many refunds were approved in the last week" or "how many accounts were verified this quarter." That's a product analytics capability, not just a query helper — it decides whether you can answer funnel-timing questions without a warehouse.
• Backfill and historical analysis. startFrom: lets you scope "last 12 months" from a fixed anchor date, which matters for cohort-style analysis and for reproducing a number that was reported at a point in time (audit/defensibility).
• Aggregation-first design. Scopes return a query builder, so they compose with sum(), avg(), groupBy(). The PM-relevant consequence: KPI cards and trend charts can be built on the same primitives rather than needing a separate metrics layer for a small-to-mid product.
• Roadmap triage input. If the upcoming work is mostly CRUD plus a handful of "last N" filters, this is sufficient and you should not spin up a data warehouse yet. If the upcoming work involves cross-entity cohort analysis, custom fiscal calendars, or per-customer timezones, this package is the wrong tool and the roadmap needs a data platform item instead.

When to Consider This Package

Adopt when:

• You have more than a couple of Eloquent models that need time-windowed queries, and you want one vocabulary (ofLast30Days) instead of N bespoke scopes.
• You have multiple developers or teams touching reporting code, and metric consistency is worth more than the tiny dependency.
• You're building an internal admin or analytics surface where users expect the familiar preset filters (today, last 7 days, MTD, YTD).
• You've been bitten by off-by-one range bugs ("why is today missing from the last-7-days number?") and want the semantics centralized and testable.
• You want to codify the inclusive/exclusive default as a documented product decision rather than an implicit one.
• Your timestamps are mostly created_at-shaped — the package's center of gravity.

Look elsewhere or defer when:

• Analytical query volume is the primary workload. Reporting belongs in a warehouse/BI layer (dbt, BigQuery, Metabase). Don't let convenience scopes become the accidental reporting architecture.
• You need business calendars. Fiscal years, 4-4-5 retail calendars, custom holiday-aware week boundaries, or "Q1 starts in February" are out of scope. So is anything requiring per-user or per-tenant timezone offsets in the range calculation — verify this against your requirements before committing, because a naive UTC/Laravel-timezone assumption can silently shift daily boundaries for non-UTC customers.
• You only need one or two of these queries. Write the local scope; a dependency you don't need is a dependency you have to audit.
• Supply-chain or longevity risk is a hard gate. This is a single-maintainer package with a small dependent footprint. If your org requires a funded, multi-maintainer dependency for anything in the reporting path, either fork it internally (MIT makes this trivial and it's ~a trait plus a service class) or reimplement.
• You need something the scope list doesn't cover. No arbitrary custom ranges from user-selected date pickers, no week-start-day configuration, no grouping/bucketing helpers (perDay, perWeek) — you'll still hand-write those.

Adoption caveat worth surfacing early: the default is exclusive. That's a defensible statistics default but a common product surprise — expect at least one "today's numbers are zero" ticket in the first week if stakeholders assume inclusive. Make the decision explicitly and put it in the config, not in tribal knowledge. Also note the century/millennium scopes follow ordinal conventions (the 20th century is 1901–2000), which will look like a bug to anyone who hasn't read the README.

How to Pitch It (Stakeholders)

For executives: A small, MIT-licensed, low-risk library that standardizes how our product answers "how much happened in the last week/month/quarter." The real value isn't the code it saves — it's that every dashboard, report, and admin screen uses one definition of a time window instead of several. That prevents the "why does the exec dashboard disagree with the ops dashboard" conversation, which costs far more than this package does. Cost: essentially zero licenses, roughly half a day of engineering plus one product decision on inclusive vs. exclusive defaults. It's a tactical accelerator, not a platform bet — easily replaced or removed later.

For engineering: A trait you add to a model that gives you ~60 named scopes across seconds through millennia, plus period-to-date helpers, with customRange, startFrom, and column: options so you're not locked into created_at. It returns a normal Builder, so it chains with sum, avg, groupBy, and your existing scopes. Tests, changelog, and current Laravel support are in place, and it's MIT so the fallback is a fork. It removes a repetitive, bug-prone class of Carbon boundary code. Mitigation for the two real risks: (1) it's a small single-maintainer package, so if reporting is business-critical, wrap it behind an internal base model or trait so the swap-out cost stays near zero; (2) the default is exclusive — set DATE_SCOPES_DEFAULT_RANGE deliberately per product surface rather than relying on the default.

The ask: approve a one-day spike to wire it into a single reporting model behind an internal trait, confirm the inclusive/exclusive decision with the stakeholder who owns the numbers, and then decide on broader rollout.