PHPackages                             laracraft-tech/laravel-date-scopes - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. laracraft-tech/laravel-date-scopes

ActiveLibrary[Database & ORM](/categories/database)

laracraft-tech/laravel-date-scopes
==================================

Some useful date scopes for your Laravel Eloquent models!

v2.4.0(1y ago)515215.0k↓11.7%31[2 PRs](https://github.com/laracraft-tech/laravel-date-scopes/pulls)2MITPHPPHP ^8.1CI passing

Since Apr 8Pushed 2mo ago6 watchersCompare

[ Source](https://github.com/laracraft-tech/laravel-date-scopes)[ Packagist](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)[ Docs](https://github.com/laracraft-tech/laravel-date-scopes)[ RSS](/packages/laracraft-tech-laravel-date-scopes/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (13)Versions (21)Used By (2)

Laravel Date Scopes
===================

[](#laravel-date-scopes)

[![Latest Version on Packagist](https://camo.githubusercontent.com/343bb6e2fae70a853560c303d91970798e1e713059ddf8b15743de3167d6b602/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c61726163726166742d746563682f6c61726176656c2d646174652d73636f7065732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)[![Tests](https://github.com/laracraft-tech/laravel-date-scopes/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/laracraft-tech/laravel-date-scopes/actions/workflows/run-tests.yml)[![License](https://camo.githubusercontent.com/03e836d2e1bfd5d521220b7f06a7097a1033bab671146b74ff4cd886995d168d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c61726163726166742d746563682f6c61726176656c2d646174652d73636f7065732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)[![Total Downloads](https://camo.githubusercontent.com/abfb319832d5f57bb7c0dea5f300dc0b8fb0c6cee27c7f6944a2ec4ef83776cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c61726163726166742d746563682f6c61726176656c2d646174652d73636f7065732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)[![Imports](https://github.com/laracraft-tech/laravel-date-scopes/actions/workflows/check_imports.yml/badge.svg?branch=main)](https://github.com/laracraft-tech/laravel-date-scopes/actions/workflows/check_imports.yml)

This package provides a big range of useful **date scopes** for your Laravel Eloquent models!

Let's assume you have a `Transaction` model. If you now give it the `DateScopes` trait, you can do something like this:

```
use LaracraftTech\LaravelDateScopes\DateScopes;

class Transaction extends Model
{
    use DateScopes;
}

// query transactions created today
Transaction::ofToday();
 // query transactions created during the last week
Transaction::ofLastWeek();
 // query transactions created during the start of the current month till now
Transaction::monthToDate();
 // query transactions created during the last year, start from 2020
Transaction::ofLastYear(startFrom: '2020-01-01');

// ... and much more scopes are available (see below)

// For sure, you can chain any Builder function you want here.
// Such as these aggregations, for instance:
Transaction::ofToday()->sum('amount');
Transaction::ofLastWeek()->avg('amount');
```

ToC
---

[](#toc)

- [`Installation`](#installation)
- [`Configuration`](#configuration)
    - [`Global configuration`](#global-configuration)
    - [`Fluent date range configuration`](#fluent-date-range-configuration)
    - [`Fluent created_at column configuration`](#fluent-date-range-configuration)
    - [`Custom start date`](#custom-start-date)
- [`Scopes`](#scopes)

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require laracraft-tech/laravel-date-scopes
```

Configuration
-------------

[](#configuration)

### Inclusive/Exclusive

[](#inclusiveexclusive)

In **statistics**, when asking for "the last 7 days", the current day may or may not be included in the calculation depending on the context and the specific requirements of the analysis.

If you want to **include** the current day in the calculation, you would generally use an **inclusive** range, meaning that you would include records created on the **current day** as well as records created in the previous 6 days.

If you want to **exclude** the current day in the calculation, you would generally use an **exclusive** range, meaning that you would include records created in the previous 7 days, but not records created on the **current day**.

Ultimately, it **depends** on the context and what you're trying to achieve with your data. It's always a good idea to clarify the requirements and expectations with stakeholders to ensure that you're including or excluding the correct records.

The same **concept** applies to other time intervals like weeks, months, quarters, and years etc.

The default for this package is **exclusive** approach, which means when you for instance query for the last 7 days it will **not include** the current day! You can change the default if you need in the published config file.

### Global configuration

[](#global-configuration)

You can publish the config file with:

```
php artisan vendor:publish --tag="date-scopes-config"
```

This is the contents of the published config file:

```
return [
    /**
     * If you want to include the current day/week/month/year etc. in the range,
     * you could use the inclusive range here as a default.
     * Note that you can also fluently specify the range for quite every scope we offer
     * directly when using the scope:
     * Transaction::ofLast7Days(customRange: DateRange::INCLUSIVE); (this works for all but the singular "ofLast"-scopes)
     * This will do an inclusive query, even though the global default range here is set to exclusive.
     */
    'default_range' => env('DATE_SCOPES_DEFAULT_RANGE', DateRange::EXCLUSIVE->value),

    /**
     * If you use a global custom created_at column name, change it here.
     */
    'created_column' => env('DATE_SCOPES_CREATED_COLUMN', 'created_at'),
];
```

If you want to change the default range to inclusive set `DATE_SCOPES_DEFAULT_RANGE=inclusive` in your `.env`.

### Fluent date range configuration

[](#fluent-date-range-configuration)

As already mentioned above in the `default_range` config description text, you can also fluently specify the range for quite every scope we offer directly when using the scope:

```
// This works for all "ofLast"-scopes, expect the singulars like "ofLastHour",
// because it would not make sense for those.
Transaction::ofLast7Days(customRange: DateRange::INCLUSIVE);
```

This will do an inclusive query (today-6 days), even though the global default range here was set to exclusive.

### Fluent created\_at column configuration

[](#fluent-created_at-column-configuration)

If you only want to change the `created_at` field in one of your models and not globally just do:

```
use LaracraftTech\LaravelDateScopes\DateScopes;

class Transaction extends Model
{
    use DateScopes;

    public $timestamps = false;

    const CREATED_AT = 'custom_created_at';
}
// also make sure to omit the default $table->timestamps() function in your migration
// and use something like this instead: $table->timestamp('custom_created_at')->nullable();
```

### Custom start date

[](#custom-start-date)

If you want data not starting from now, but from another date, you can do this with:

```
// query transactions created during 2019-2020
Transaction::ofLastYear(startFrom: '2020-01-01')
```

### Custom datetime column

[](#custom-datetime-column)

If you want to use column other than `created_at` column, you can pass the column name as parameter to the scope:

```
Transaction::ofToday(column: 'approved_at')
```

Scopes
------

[](#scopes)

- [`seconds`](#seconds)
- [`minutes`](#minutes)
- [`hours`](#hours)
- [`days`](#days)
- [`weeks`](#weeks)
- [`months`](#months)
- [`quarters`](#quarters)
- [`years`](#years)
- [`decades`](#decades)
- [`centuries`](#centuries)
- [`millenniums`](#millenniums)
- [`toNow/toDate`](#toNowtoDate)

### Seconds

[](#seconds)

```
// query by SECONDS
Transaction::ofJustNow(); // query transactions created just now
Transaction::ofLastSecond(); // query transactions created during the last second
Transaction::ofLast15Seconds(); // query transactions created during the last 15 seconds
Transaction::ofLast30Seconds(); // query transactions created during the last 30 seconds
Transaction::ofLast45Seconds(); // query transactions created during the last 45 seconds
Transaction::ofLast60Seconds(); // query transactions created during the last 60 seconds
Transaction::ofLastSeconds(120); // query transactions created during the last N seconds
```

### Minutes

[](#minutes)

```
// query by MINUTES
Transaction::ofLastMinute(); // query transactions created during the last minute
Transaction::ofLast15Minutes(); // query transactions created during the last 15 minutes
Transaction::ofLast30Minutes(); // query transactions created during the last 30 minutes
Transaction::ofLast45Minutes(); // query transactions created during the last 45 minutes
Transaction::ofLast60Minutes(); // query transactions created during the last 60 minutes
Transaction::ofLastMinutes(120); // query transactions created during the last N minutes
```

### Hours

[](#hours)

```
// query by HOURS
Transaction::ofLastHour(); // query transactions created during the last hour
Transaction::ofLast6Hours(); // query transactions created during the last 6 hours
Transaction::ofLast12Hours(); // query transactions created during the last 12 hours
Transaction::ofLast18Hours(); // query transactions created during the last 18 hours
Transaction::ofLast24Hours(); // query transactions created during the last 24 hours
Transaction::ofLastHours(48); // query transactions created during the last N hours
```

### Days

[](#days)

```
// query by DAYS
Transaction::ofToday(); // query transactions created today
Transaction::ofYesterday(); // query transactions created yesterday
Transaction::ofLast7Days(); // query transactions created during the last 7 days
Transaction::ofLast21Days(); // query transactions created during the last 21 days
Transaction::ofLast30Days(); // query transactions created during the last 30 days
Transaction::ofLastDays(60); // query transactions created during the last N days
```

### Weeks

[](#weeks)

```
// query by WEEKS
Transaction::ofLastWeek(); // query transactions created during the last week
Transaction::ofLast2Weeks(); // query transactions created during the last 2 weeks
Transaction::ofLast3Weeks(); // query transactions created during the last 3 weeks
Transaction::ofLast4Weeks(); // query transactions created during the last 4 weeks
Transaction::ofLastWeeks(8); // query transactions created during the last N weeks
```

### Months

[](#months)

```
// query by MONTHS
Transaction::ofLastMonth(); // query transactions created during the last month
Transaction::ofLast3Months(); // query transactions created during the last 3 months
Transaction::ofLast6Months(); // query transactions created during the last 6 months
Transaction::ofLast9Months(); // query transactions created during the last 9 months
Transaction::ofLast12Months(); // query transactions created during the last 12 months
Transaction::ofLastMonths(24); // query transactions created during the last N months
```

### Quarters

[](#quarters)

```
// query by QUARTERS
Transaction::ofLastQuarter(); // query transactions created during the last quarter
Transaction::ofLast2Quarters(); // query transactions created during the last 2 quarters
Transaction::ofLast3Quarters(); // query transactions created during the last 3 quarters
Transaction::ofLast4Quarters(); // query transactions created during the last 4 quarters
Transaction::ofLastQuarters(8); // query transactions created during the last N quarters
```

### Years

[](#years)

```
// query by YEARS
Transaction::ofLastYear(); // query transactions created during the last year
Transaction::ofLastYears(2); // query transactions created during the last N years
```

### Decades

[](#decades)

```
// query by DECADES
Transaction::ofLastDecade(); // query transactions created during the last decade
Transaction::ofLastDecades(2); // query transactions created during the last N decades
```

### Centuries

[](#centuries)

The **centuries** may return a different range then you maybe would expect. For instance `Transaction::ofLastCentury()` would apply a range from 1901-01-01 00:00:00 to 2000-12-31 23:59:59. Maybe you would expect a range from: 1900-01-01 00:00:00 to 1999-12-31 23:59:59.

Checkout Wikipedia for this behavior: [https://en.wikipedia.org/wiki/20th\_century](https://en.wikipedia.org/wiki/20th_century)

```
// query by CENTURIES
Transaction::ofLastCentury(); // query transactions created during the last century
Transaction::ofLastCenturies(2); // query transactions created during the last N centuries
```

### Millenniums

[](#millenniums)

The **millenniums** may return a different range then you maybe would expect. For instance `Transaction::ofLastMillennium()` would apply a range from 1001-01-01 00:00:00 to 2000-12-31 23:59:59. Maybe you would expect a range from: 1000-01-01 00:00:00 to 1999-12-31 23:59:59.

Checkout Wikipedia for this behavior: [https://en.wikipedia.org/wiki/2nd\_millennium](https://en.wikipedia.org/wiki/2nd_millennium)

```
// query by MILLENNIUMS
Transaction::ofLastMillennium(); // query transactions created during the last millennium
Transaction::ofLastMillenniums(2); // query transactions created during the last N millenniums
```

### toNow/toDate

[](#tonowtodate)

```
// query by toNow/toDate
Transaction::secondToNow(); // query transactions created during the start of the current second till now (equivalent of just now)
Transaction::minuteToNow(); // query transactions created during the start of the current minute till now
Transaction::hourToNow(); // query transactions created during the start of the current hour till now
Transaction::dayToNow(); // query transactions created during the start of the current day till now
Transaction::weekToDate(); // query transactions created during the start of the current week till now
Transaction::monthToDate(); // query transactions created during the start of the current month till now
Transaction::quarterToDate(); // query transactions created during the start of the current quarter till now
Transaction::yearToDate(); // query transactions created during the start of the current year till now
Transaction::decadeToDate(); // query transactions created during the start of the current decade till now
Transaction::centuryToDate(); // query transactions created during the start of the current century till now
Transaction::millenniumToDate(); // query transactions created during the start of the current millennium till now
```

Testing
-------

[](#testing)

```
composer test
```

Upgrading
---------

[](#upgrading)

Please see [UPGRADING](UPGRADING.md) for details.

### Changelog

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security
--------

[](#security)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Zacharias Creutznacher](https://github.com/laracraft-tech)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance70

Regular maintenance activity

Popularity55

Moderate usage in the ecosystem

Community27

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~49 days

Recently: every ~103 days

Total

16

Last Release

390d ago

Major Versions

v1.1.1 → v2.0.02023-10-12

### Community

Maintainers

![](https://www.gravatar.com/avatar/cf347b32c0d1fceabbcbce7626ad662faa34738396fd9f774231d55370823713?d=identicon)[Sairahcaz](/maintainers/Sairahcaz)

---

Top Contributors

[![Sairahcaz](https://avatars.githubusercontent.com/u/7384870?v=4)](https://github.com/Sairahcaz "Sairahcaz (82 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (18 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (8 commits)")[![aymanalhattami](https://avatars.githubusercontent.com/u/34315778?v=4)](https://github.com/aymanalhattami "aymanalhattami (6 commits)")[![imanghafoori1](https://avatars.githubusercontent.com/u/6961695?v=4)](https://github.com/imanghafoori1 "imanghafoori1 (3 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (2 commits)")[![ziming](https://avatars.githubusercontent.com/u/679513?v=4)](https://github.com/ziming "ziming (1 commits)")[![denniseilander](https://avatars.githubusercontent.com/u/3907144?v=4)](https://github.com/denniseilander "denniseilander (1 commits)")[![javierpomachagua](https://avatars.githubusercontent.com/u/7298734?v=4)](https://github.com/javierpomachagua "javierpomachagua (1 commits)")[![keatliang2005](https://avatars.githubusercontent.com/u/473990?v=4)](https://github.com/keatliang2005 "keatliang2005 (1 commits)")

---

Tags

analyticsdateeloquentfincancelaravelscopesstatisticslaravellaravel-date-scopeslaracraft-tech

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/laracraft-tech-laravel-date-scopes/health.svg)

```
[![Health](https://phpackages.com/badges/laracraft-tech-laravel-date-scopes/health.svg)](https://phpackages.com/packages/laracraft-tech-laravel-date-scopes)
```

###  Alternatives

[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

423715.4k1](/packages/clickbar-laravel-magellan)[watson/validating

Eloquent model validating trait.

9723.3M47](/packages/watson-validating)[spatie/laravel-health

Monitor the health of a Laravel application

86910.0M83](/packages/spatie-laravel-health)[jerome/filterable

Streamline dynamic Eloquent query filtering with seamless API request integration and advanced caching strategies.

19226.1k](/packages/jerome-filterable)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2121.2M13](/packages/reedware-laravel-relation-joins)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)