Laravel Date Scopes Laravel Package

Technical Evaluation

Architecture fit

• The package is a single trait (LaracraftTech\LaravelDateScopes\DateScopes) that contributes Eloquent local scopes to a model. It does not introduce a service provider you must wire, a facade, a repository abstraction, or a persistence layer — it rides on Laravel's native __callStatic → scope resolution. That is the lowest-coupling integration shape available in the Eloquent ecosystem.
• Because scopes return a Builder, they compose with everything we already do: ->sum(), ->avg(), ->paginate(), ->where(), policies, and API resources. No new query paradigm to teach.
• Footprint is genuinely small: roughly two config keys (default_range, created_column) and a set of range-computing methods. If the vendor disappears, inlining equivalent whereBetween clauses per model is an afternoon of work. Lock-in risk is near zero, which is the main reason this is approvable at all.
• It is opinionated about semantics, not architecture. That is where the actual risk lives (see below), and it's a product/requirements risk rather than an engineering one.

Integration feasibility

• composer require laracraft-tech/laravel-date-scopes, optionally vendor:publish --tag="date-scopes-config", add use DateScopes; to target models. No migrations, no schema change, no queue worker, no infra touch. A single PR can land this.
• Works against existing created_at columns out of the box, and supports per-call column overrides (ofToday(column: 'approved_at')) plus per-model CREATED_AT overrides — enough to cover our likely column variants (approved_at, paid_at, shipped_at) without forking.
• ofLastYear(startFrom: '2020-01-01') and the *ToDate() family cover the reporting shapes we actually need (MTD, QTD, YTD) more directly than hand-rolled Carbon math.

Technical risk

• Timezone correctness is the top risk and it is silent. The scopes derive boundaries from application time (now()), while most of our tables store created_at in UTC. If app.timezone ≠ storage timezone, "today" and "month to date" drift by hours and, at month boundaries, by a full day. This produces plausible-but-wrong dashboards — far worse than an exception. Must be explicitly resolved before adoption.
• Inclusive/exclusive default is exclusive, meaning "last 7 days" excludes today. That is a defensible statistical convention and a very common stakeholder mismatch. Any number that reaches finance or an external report needs the convention written down and locked via DATE_SCOPES_DEFAULT_RANGE in .env, not left to the package default.
• Boundary semantics are not documented at the second level. Whether a range ends at 23:59:59 or < next period start matters for records written in the final second. Should be verified against the package test suite rather than assumed.
• Calendar edge cases: week start (locale-dependent startOfWeek), quarter definition, DST transitions on day/week scopes, and the deliberately counter-intuitive century/millennium boundaries (documented, Wikipedia-referenced). The century/millennium behavior is correct-but-surprising; not a blocker, but it will generate a support ticket if someone reads "last century" naively.
• Config cache coupling: changing DATE_SCOPES_DEFAULT_RANGE requires a config recache. This is a deploy-procedure item, not a defect.
• Bus factor 1. Single maintainer, dependabot-driven releases, no listed dependents in the registry data. The Laravel 13 support in v2.5.0 is a strong health signal (the maintainer is tracking framework releases), but we should not treat long-term maintenance as guaranteed.

Key questions

1. What is app.timezone versus the storage timezone for each candidate table, and does the package shift boundaries into the DB timezone or not?
2. Which inclusive/exclusive convention do finance and product sign off on, and do we set it globally or per call site?
3. Does the package define week start as ISO Monday, and does that match our reporting calendar?
4. What PHP and Laravel versions are actually supported in the constraint, and does that align with our LTS window?
5. Are all candidate datetime columns indexed, and do we need composite indexes for the aggregate queries these scopes will generate?
6. Do we want the trait on models directly, or behind our own domain-named scopes (ofCurrentBillingPeriod()) to keep vendor vocabulary out of controllers and Blade?

Integration Approach

Stack fit

• Assumes Laravel + Eloquent and created_at-style timestamp columns. Fits anywhere we already have Eloquent models with a datetime we report on: transactions, invoices, orders, events, audit records. Does not fit reporting that runs off raw query builder, stored procedures, or a warehouse/BI layer — those need the same logic expressed in SQL, and duplicating it invites drift.
• Composer-only dependency; no PHP extensions, no runtime services.

Migration path

• Greenfield: add the trait to reporting-facing models in the same PR that introduces the first report.
• Brownfield: inventory existing date filters — whereDate, whereBetween, whereRaw, Carbon-in-controller math — and replace them scope-by-scope, asserting equivalence with a characterization test per replaced call site. Do not do a bulk find-and-replace; each replacement is a semantic decision.
• Exit path is trivial and should be documented up front: if the package is abandoned or a boundary is wrong, the scopes are one-line whereBetween implementations we can vendor inline.

Compatibility

• Constrain the Composer requirement to a caret range on the current minor and pin exactly in composer.lock. Verify PHP/Laravel support against our matrix before merge.
• No conflicts expected with other Eloquent extensions; scope name collisions with existing model methods are the only realistic clash, and those surface immediately at boot/test time.

Sequencing

1. Spike (1–2 days): install, add trait to one low-risk model, write tests that assert generated SQL and returned rows across a timezone boundary and a DST transition. Resolve the timezone question here, not later.
2. Convention decision: ADR recording inclusive/exclusive choice, week-start, quarter definition, and timezone policy. Set DATE_SCOPES_DEFAULT_RANGE explicitly.
3. Pilot (1 sprint): convert one internal, non-customer-facing report. Compare against the existing implementation for a full period.
4. Expand: roll into additional models/reports in small batches, each with a characterization test.
5. Guardrails: lint/CI check that new date filtering in reporting code uses scopes rather than ad-hoc Carbon math, and a documented fallback if the package goes stale.

Operational Impact

Maintenance

• Minimal ongoing cost: no migrations, no background jobs, no config drift beyond one env var. Upgrades ride along with framework bumps; the release history suggests the maintainer ships Laravel-major support promptly.
• The real maintenance obligation is semantic: the inclusive/exclusive and timezone decisions must live in an ADR and in test fixtures, or they will be silently "fixed" by a future developer and shift historical numbers.

Support

• Support surface is narrow and answerable from the README: which scope means what, and why "last 7 days" excludes today. Expect repeated questions; pre-empt them with a short internal cheat sheet mapping business phrasing ("this week's sales") to the exact scope and convention.
• The century/millennium scopes should be documented internally as "correct but non-obvious" so nobody files a bug against intended behavior.
• No vendor SLA. Support is the README, the test suite, and the maintainer's GitHub. Plan for self-service.

Scaling

• No application-layer overhead: scopes compile to a whereBetween-style predicate, so cost is entirely the database's. At scale the deciding factor is indexing on the datetime column and on (tenant_id, created_at) composites for multi-tenant aggregates.
• Watch for dashboards that fan out many aggregate queries per page load — that's a query-count/ caching concern, independent of the package.
• Read-only predicates mean no locking or write-path impact.

Failure modes

• Silent off-by-one-day from timezone mismatch or inclusive/exclusive misreading — highest severity, undetectable without tests.
• Boundary-inclusive drift for records landing in the last second of a period.
• Config cache staleness after changing DATE_SCOPES_DEFAULT_RANGE, producing mixed conventions between environments.
• Unindexed column turning a convenience scope into a full scan on a large table.
• Abandonment — low impact given the inlining escape hatch, but should be an acknowledged item on the dependency review list rather than a surprise.
• Note the 0 dependents registry signal: treat it as "adoption not yet proven," not "unusable" — 513 stars and active Laravel-major releases are the stronger indicators here.

Ramp-up

• Developer ramp-up is roughly 15 minutes: the README is complete and example-driven, and the scope names are self-describing.
• The cost is not learning the API, it's learning the convention. Budget half a day for the team lead to write the ADR and boundary tests; that artifact, not the README, is what makes the integration safe to operate.