Weave Code
Laravel Date Scopes Laravel Package
laracraft-tech/laravel-date-scopes
Laravel Date Scopes adds a wide range of ready-made date scopes to your Eloquent models via a simple trait. Query records with ofToday(), ofLastWeek(), monthToDate(), ofLastYear(), and many more—fully chainable with any builder method like sum or avg.
Some useful date scopes for your Laravel Eloquent models!
Frequently asked questions about Laravel Date Scopes
- How do I install laravel-date-scopes and add it to an Eloquent model?
- Install it with composer require laracraft-tech/laravel-date-scopes, then add use LaracraftTech\LaravelDateScopes\DateScopes; to the model you want to query by date. The trait is the only integration step: there are no migrations, service providers to register, or schema changes. Optionally publish the config to set a global inclusive/exclusive default and a global created_at column override.
- What date scopes does laravel-date-scopes provide?
- The trait adds a wide range of named Eloquent scopes such as ofToday, ofLastWeek, monthToDate, and ofLastYear, along with hour, century, and millennium variants. Each scope is a normal query scope, so it returns an Eloquent builder you can further constrain. You can call them statically on the model, for example Transaction::ofToday(), or chain them inside an existing query.
- Are the date ranges in laravel-date-scopes inclusive or exclusive by default?
- The package defaults to exclusive ranges, so a last 7 days scope does not include the current day. You can change the global default in the published config or override it per call with the customRange argument. This matters if you are replacing hand-rolled inclusive queries, because metrics can shift by a day.
- How do I pass a custom start date to a laravel-date-scopes query?
- Use the startFrom argument on a scope, for example Transaction::ofLastYear(startFrom: '2020-01-01'). The range is then anchored to that date instead of being calculated purely from the current time. Note that the singular ofLastHour-style scopes do not accept customRange, so range policy cannot be applied uniformly across every scope.
- Can I change the timestamp column that laravel-date-scopes queries?
- Yes. The config exposes a global created_column override, and individual scope calls accept a column argument for per-query overrides. If a model defines its own CREATED_AT while the config also sets created_column, confirm which one wins in your application before relying on it. The column should be a real datetime or timestamp column with an index for good performance.
- Can I chain sum, avg, and other aggregations onto the date scopes?
- Yes. Every scope returns a standard Eloquent builder, so you can chain any builder method, including aggregates such as Transaction::ofToday()->sum('amount') or Transaction::ofLastWeek()->avg('amount'). The trait does not interfere with global scopes, soft deletes, or multi-tenant scopes because it only adds query constraints. Test the interaction with SoftDeletes in your own models to make sure the added constraints behave as expected.
- Which Laravel and PHP versions does laravel-date-scopes support?
- The package targets modern Laravel applications on PHP 8.x, and version 2.5.0 added Laravel 13 support with a release dated 2026-04-01. That release cadence suggests active maintenance by the single maintainer. Always check the composer.json constraints for the exact minimum Laravel and PHP versions before upgrading.
- Do laravel-date-scopes queries use database indexes, or do they wrap columns in date functions?
- The README does not document whether the scopes compile to index-friendly whereBetween predicates on the raw column or to whereDate-style function wrapping. On MySQL, wrapping the column in DATE() can prevent index use, and on Postgres it may force a sequential scan on large tables. Run EXPLAIN on your actual queries before using these scopes in high-volume reporting paths.
- How does laravel-date-scopes handle timezones and daylight saving time?
- Timezone behavior is not documented in the README, so it is unclear whether ranges are resolved in app.timezone or UTC. That distinction affects correctness at DST transitions and for distributed writers, and can cause off-by-hours artifacts around midnight. Confirm the behavior in a test with explicit timezone settings before depending on these scopes for daily reporting.
- What are the alternatives to laravel-date-scopes for date filtering in Laravel?
- You can always hand-roll the same queries with Carbon and whereBetween, which gives you full control over boundary semantics, timezone handling, and index-friendly SQL. The package is a small single trait under the MIT license, so vendoring or forking it is realistic if you need to adjust behavior. For simple cases, native Eloquent where clauses plus Carbon may be enough, while this package saves boilerplate when you need many named ranges.
Weaver
How can I help you explore Laravel packages today?