Subversion-Projekte lars-tiefland.laravel_shop

# Laravel Date Scopes

[![Latest Version on Packagist](https://img.shields.io/packagist/v/laracraft-tech/laravel-date-scopes.svg?style=flat-square)](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://img.shields.io/packagist/l/laracraft-tech/laravel-date-scopes.svg?style=flat-square)](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)

<!--[![Total Downloads](https://img.shields.io/packagist/dt/laracraft-tech/laravel-date-scopes.svg?style=flat-square)](https://packagist.org/packages/laracraft-tech/laravel-date-scopes)-->

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

## Installation

You can install the package via composer:

```bash

composer require laracraft-tech/laravel-date-scopes

```

## Configuration

### Inclusive/Exclusive

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

You can publish the config file with:

```bash

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

```

This is the contents of the published config file:

```php

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(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 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:

```php

// This works for all "ofLast"-scopes, expect the singulars like "ofLastHour",

// because it would not make sense for those.

Transaction::ofLast7Days(DateRange::INCLUSIVE);

```

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

## 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)

Let's assume you have an `Transaction` model class.

Now when you give it the `DateScopes` trait, you can use the following scopes:

```php

use LaracraftTech\LaravelDateScopes\DateScopes;

class Transaction extends Model

{

    use DateScopes;

}

```

### Seconds

```php

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

```php

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

```php

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

```php

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

```php

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

```php

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

```php

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

```php

// query by YEARS

Transaction::ofLastYear(); // query transactions created during the last year

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

```

### Decades

```php

// query by DECADES

Transaction::ofLastDecade(); // query transactions created during the last decade

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

```

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

```php

// query by CENTURIES

Transaction::ofLastCentury(); // query transactions created during the last century

Transaction::ofLastCenturies(2); // query transactions created during the last N centuries

```

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

```php

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

```php

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

```bash

composer test

```

## Changelog

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

## Contributing

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

## Security Vulnerabilities

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

## Credits

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

- [All Contributors](../../contributors)

## License

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