README

本包为您的 Laravel Eloquent 模型提供了一系列有用的 日期范围！

假设您有一个 Transaction 模型。如果您现在给它添加 DateScopes 特性，您可以这样做

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');

安装

您可以通过 composer 安装此包

composer require laracraft-tech/laravel-date-scopes

配置

包含/不包含

在统计中，当询问“过去 7 天”时，当前天可能包含或不包含在计算中，这取决于上下文和分析的具体要求。

如果您想包含当前天在计算中，您通常会使用一个包含的范围，这意味着您将包括在当前天创建以及之前 6 天创建的记录。

如果您想排除当前天在计算中，您通常会使用一个 不包含 的范围，这意味着您将包括之前 7 天创建的记录，但不包括在当前天创建的记录。

最终，这取决于上下文以及您试图通过数据实现的目标。始终与利益相关者明确要求是很重要的，以确保您包含或排除正确的记录。

同样的概念也适用于其他时间间隔，如周、月、季度和年等。

此包的默认为 不包含 方法，这意味着当您查询过去 7 天时，它将 不包含 当前天！您可以在发布的配置文件中更改默认值。

全局配置

您可以通过以下方式发布配置文件

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

这是发布配置文件的内容

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'),
];

如果您想将默认范围更改为包含，请在您的 .env 中设置 DATE_SCOPES_DEFAULT_RANGE=inclusive。

流畅的日期范围配置

如前面所述，在 default_range 配置描述文本中，您还可以在调用范围时直接指定我们提供的几乎每个范围的值

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

这将执行一个包含查询（今天-6 天），尽管全局默认范围设置为不包含。

流畅的 created_at 列配置

如果您只想更改某个模型中的 created_at 字段而不是全局更改，只需这样做

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();

自定义起始日期

如果您想要从另一个日期而不是现在开始的数据，您可以这样做

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

秒

// 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

分钟

// 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

小时

// 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

天

// 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

周

// 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

月

// 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

季度

// 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

年

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

十年

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

世纪

世纪可能会返回您可能不会预期的不同范围。例如，Transaction::ofLastCentury() 将应用一个范围从 1901-01-01 00:00:00 到 2000-12-31 23:59:59。您可能期望的范围是从：1900-01-01 00:00:00 到 1999-12-31 23:59:59。

有关此行为，请参阅维基百科：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

千年

千年可能会返回一个不同于您预期的范围。例如，Transaction::ofLastMillennium()将应用从1001-01-01 00:00:00到2000-12-31 23:59:59的范围。您可能期望的范围是从：1000-01-01 00:00:00到1999-12-31 23:59:59。

有关此行为，请参阅维基百科：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

// 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

测试

composer test

升级

请参阅UPGRADING以获取详细信息。

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

请审查我们的安全策略，了解如何报告安全漏洞。

鸣谢

许可协议

MIT许可协议（MIT）。请参阅许可文件以获取更多信息。

laracraft-tech / laravel-date-scopes

维护者

详情