Laravel Date Scopes

https://github.com/laracraft-tech/laravel-date-scopes
Admin
This package provides a range of useful date scopes for your Laravel Eloquent models, allowing for...
Tokens:42,064
Snippets:388
Trust Score:7.5
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Complete Configuration File Example

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/configuration.md

A complete example of the laravel-date-scopes configuration file, including default range and created column settings.

```php
<?php

use LaracraftTech\LaravelDateScopes\DateRange;

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 it for quite every scope we offer
     * directly when using the scope:
     * Transaction::ofLast7Days(customRange: DateRange::INCLUSIVE);
     * 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 have a custom created_at column name, change it here.
     */
    'created_column' => env('DATE_SCOPES_CREATED_COLUMN', 'created_at'),
];
```

--------------------------------

### Install Laravel Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Install the package using Composer. This command fetches the latest version and adds it to your project's dependencies.

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

--------------------------------

### Filter Historical Data with a Specific Start Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Example of using the `startFrom` parameter to filter data from a specific historical date.

```php
$from2020 = Transaction::ofLastYear(startFrom: '2020-01-01')->get();
```

--------------------------------

### Setting Environment Variables for Configuration

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/LaravelDateScopesServiceProvider.md

Examples of environment variables to override default package configuration settings.

```bash
DATE_SCOPES_DEFAULT_RANGE=inclusive
DATE_SCOPES_CREATED_COLUMN=created_at
```

--------------------------------

### Valid Value Examples for Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/errors.md

Provides examples of valid positive integer values that can be used with date scope methods without throwing an exception.

```PHP
Transaction::ofLastDays(1);
Transaction::ofLastHours(24);
Transaction::ofLastMonths(12);
```

--------------------------------

### Example Usage of DateScopes Trait

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/INDEX.md

Demonstrates how to add the DateScopes trait to your Eloquent models and call scopes on them. Refer to the usage guide for more patterns.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LaracraftTech\DateScopes\DateScopes;

class YourModel extends Model
{
    use DateScopes;

    // ...
}

```

--------------------------------

### Created Column Usage Example

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/configuration.md

Illustrates how the 'created_column' setting is used by scopes and how to override it.

```php
// Uses the configured 'created_at' column
Transaction::ofLastDays(7)->get();

// Override with custom column parameter
Transaction::ofLastDays(7, column: 'published_at')->get();

// Or define CREATED_AT on the model
class Transaction extends Model
{
    const CREATED_AT = 'submitted_at';
}
// Now scopes use 'submitted_at' by default
```

--------------------------------

### Query Transactions from Start of Period to Now/Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/README.md

Use these methods to query transactions from the start of a period (second, minute, hour, day, week, month, quarter, year, decade, century, millennium) up to the current moment.

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

--------------------------------

### Example: Throwing and Catching DateException

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateException.md

Demonstrates how to manually throw a DateException and how it might be caught by a scope method like scopeOfLastUnit().

```php
// Throws DateException
DateException::invalidValue();

// Caught in scopeOfLastUnit()
try {
    Transaction::ofLastDays(0)->get();
} catch (DateException $e) {
    echo $e->getMessage();  // "The $value parameter must be a positive integer."
}
```

--------------------------------

### Querying Records with Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/README.md

Utilize various scopes to filter records by date. Examples include querying for today, last week, month-to-date, and last year with optional start dates.

```php
// 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');
```

--------------------------------

### Custom Start Date for Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/README.md

Define a custom start date for date range queries, allowing you to query data from a specific point in time rather than the current moment. This example shows querying transactions created during a specific year.

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

--------------------------------

### Created Column Example Configuration

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/configuration.md

Set the 'created_column' in the configuration file or via an environment variable to specify the default timestamp column.

```php
// config/date-scopes.php
return [
    'created_column' => 'created_at',  // Default Laravel timestamp
];
```

```dotenv
DATE_SCOPES_CREATED_COLUMN=created_at
```

--------------------------------

### Historical Data Queries

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/scope-reference.md

Retrieve historical data by specifying a start date for the calculation.

```php
// Transactions from last year starting from 2020
$historical = Transaction::ofLastYear(startFrom: '2020-01-01')->get();

// Data from last 30 days of 2022
$archive = Transaction::ofLastDays(30, startFrom: '2022-12-31')->get();
```

--------------------------------

### Default Range Example Configuration

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/configuration.md

Set the 'default_range' in the configuration file or via an environment variable to control date range behavior.

```php
// config/date-scopes.php
return [
    'default_range' => 'inclusive',  // All scopes include current period by default
];
```

```dotenv
DATE_SCOPES_DEFAULT_RANGE=inclusive
```

--------------------------------

### Getting Default DateRange from Config

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateRange.md

Illustrates how to retrieve the configured default date range mode and compare it with enum cases.

```php
use LaracraftTech\LaravelDateScopes\DateRange;

$defaultRange = DateRange::from(config('date-scopes.default_range'));

if ($defaultRange === DateRange::INCLUSIVE) {
    // Global default is inclusive
}
```

--------------------------------

### Generated Documentation Files

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/COMPLETION_REPORT.md

Lists the files generated as part of the documentation project, including the main report, index, README, guides, reference files, and API details.

```bash
/workspace/home/output/
├── COMPLETION_REPORT.md                    ← This file
├── INDEX.md                                ← Documentation index
├── README.md                               ← Main entry point
├── overview.md                             ← Architecture/overview
├── usage-guide.md                          ← How to use
├── scope-reference.md                      ← All scopes lookup
├── configuration.md                        ← Configuration guide
├── types.md                                ← Type definitions
├── errors.md                               ← Error reference
└── api-reference/
    ├── DateScopes.md                       ← Trait docs
    ├── DateRange.md                        ← Enum docs
    ├── DateException.md                    ← Exception docs
    └── LaravelDateScopesServiceProvider.md ← Provider docs
```

--------------------------------

### Chainable Queries with Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/overview.md

Demonstrates how to chain date scopes with other Eloquent query builder methods like where, orderBy, and get.

```php
Transaction::ofLastMonth()
    ->where('status', 'completed')
    ->orderBy('amount', 'desc')
    ->get();
```

--------------------------------

### Advanced Usage of Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Demonstrates chaining date scopes with other query methods, using scopes with aggregations, and applying custom columns and date ranges. Also shows how to query historical data from a specific start date.

```php
use LaracraftTech\LaravelDateScopes\DateScopes;
use LaracraftTech\LaravelDateScopes\DateRange;

class Transaction extends Model
{
    use DateScopes;
}

// Chain with other query methods
$thisMonth = Transaction::monthToDate()
    ->where('status', 'completed')
    ->orderBy('created_at', 'desc')
    ->get();

// Use with aggregations
$weeklyTotal = Transaction::ofLastWeek()->sum('amount');
$monthlyAverage = Transaction::ofLastMonth()->avg('amount');

// Custom column and date range
$approved = Transaction::ofLast30Days(
    column: 'approved_at',
    customRange: DateRange::INCLUSIVE
)->get();

// Historical data from a specific start date
$historical = Transaction::ofLastYear(startFrom: '2020-01-01')->get();
```

--------------------------------

### Filter Transactions by Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Basic examples of using the `ofToday`, `monthToDate`, and `ofLastQuarter` scopes to filter Eloquent models.

```php
$today = Transaction::ofToday()->get();
$thisMonth = Transaction::monthToDate()->get();
$lastQuarter = Transaction::ofLastQuarter()->get();
```

--------------------------------

### Index Timestamp Column for Performance

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Example of adding an index to a timestamp column in a database migration to improve query performance.

```php
Schema::table('transactions', function (Blueprint $table) {
    $table->index('created_at');
});
```

--------------------------------

### Basic Scope Usage Example

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/INDEX.md

Illustrates a basic query using a date scope on an Eloquent model. Ensure the DateScopes trait is used in your model.

```php
$users = User::scopeOfLastMonth()->get();

```

--------------------------------

### Minute to Now Scope

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieve records from the start of the current minute to the current moment. Accepts an optional column name.

```php
public function scopeMinuteToNow(Builder $query, ?string $column = null): Builder
```

```php
$minuteToNow = Transaction::minuteToNow()->get();
```

--------------------------------

### Second to Now Scope

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieve records from the start of the current second to the current moment. Accepts an optional column name.

```php
public function scopeSecondToNow(Builder $query, ?string $column = null): Builder
```

```php
$secondToNow = Transaction::secondToNow()->get();
```

--------------------------------

### Filter with Custom Date Range (Inclusive)

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Shows how to use the `customRange` parameter with `DateRange::INCLUSIVE` to include the start and end dates.

```php
use LaracraftTech\LaravelDateScopes\DateRange;

$inclusive = Transaction::ofLast7Days(customRange: DateRange::INCLUSIVE)->get();
```

--------------------------------

### Scope Quarter To Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current quarter to now. Ideal for quarterly business reviews or performance tracking.

```php
public function scopeQuarterToDate(Builder $query, ?string $column = null): Builder
```

```php
$quarterToDate = Transaction::quarterToDate()->get();
```

--------------------------------

### Perform Aggregations on Filtered Data

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Examples of using scopes in conjunction with Eloquent aggregation methods like `sum`, `count`, and `avg`.

```php
$total = Transaction::monthToDate()->sum('amount');
$count = Transaction::ofLastWeek()->count();
$average = Transaction::ofLast30Days()->avg('amount');
```

--------------------------------

### DateScopes Trait Documentation

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/INDEX.md

Complete trait documentation for the DateScopes trait, including core methods, grouped scopes by time unit, 'to now' and 'to date' scopes, and full parameter documentation with usage examples.

```APIDOC
## DateScopes Trait

### Description
This trait provides a comprehensive set of date-related scopes for Eloquent models.

### Methods
- `scopeOfLastUnit(string $unit, ...$args)`: Core method for scoping by the last unit of time.
- Scopes are grouped by time unit: seconds, minutes, hours, days, weeks, months, quarters, years, decades, centuries, millenniums.
- Includes "To now" and "to date" scopes.

### Parameters
- Full parameter documentation and usage examples are available in the source file `api-reference/DateScopes.md`.
```

--------------------------------

### Using startFrom Parameter

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/scope-reference.md

Specify a reference date for calculations using a parseable string or Carbon instance. Defaults to now().

```php
Transaction::ofLastDays(7, startFrom: '2023-06-15')->get();
Transaction::ofLastWeeks(2, startFrom: Carbon::parse('2023-01-01'))->get();
```

--------------------------------

### Using Named Arguments for startFrom Parameter

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/UPGRADING.md

When upgrading from v1 to v2, the 'startFrom' parameter was introduced. You may need to adjust the order of arguments or use named arguments for clarity and compatibility.

```php
// Instead of doing this:
Transaction::ofLast7Days(DateRange::INCLUSIVE);
// Do this:
Transaction::ofLast7Days(customRange: DateRange::INCLUSIVE);
```

--------------------------------

### Combining All Parameters

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/scope-reference.md

Demonstrates how to use all optional parameters together in a single scope query.

```php
// All parameters together
$results = Transaction::ofLastDays(
    days: 30,
    startFrom: '2023-06-15',
    customRange: DateRange::INCLUSIVE,
    column: 'approved_at'
)->get();
```

--------------------------------

### Run Tests

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/README.md

Execute the test suite for the package using Composer.

```bash
composer test
```

--------------------------------

### scopeMillenniumToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current millennium to now.

```APIDOC
## scopeMillenniumToDate

### Description
Retrieves records from the start of the current millennium to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::millenniumToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2001-01-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### Publishing Configuration File

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/LaravelDateScopesServiceProvider.md

Command to publish the package's configuration file to the application's config directory.

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

--------------------------------

### Global Configuration via Environment Variables

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/usage-guide.md

Configure default behaviors for date scopes globally using environment variables in your .env file.

```bash
# .env
DATE_SCOPES_DEFAULT_RANGE=inclusive
DATE_SCOPES_CREATED_COLUMN=submitted_at
```

--------------------------------

### scopeCenturyToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current century to now.

```APIDOC
## scopeCenturyToDate

### Description
Retrieves records from the start of the current century to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::centuryToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2001-01-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### scopeDecadeToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current decade to now.

```APIDOC
## scopeDecadeToDate

### Description
Retrieves records from the start of the current decade to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::decadeToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2020-01-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### Configuring Default DateRange

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateRange.md

Shows how to set the default date range mode globally using the configuration file or environment variables.

```php
use LaracraftTech\LaravelDateScopes\DateRange;

// In config/date-scopes.php
return [
    'default_range' => DateRange::INCLUSIVE->value,  // 'inclusive'
];

// Or via environment variable
// .env: DATE_SCOPES_DEFAULT_RANGE=inclusive
```

--------------------------------

### scopeQuarterToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current quarter to now.

```APIDOC
## scopeQuarterToDate

### Description
Retrieves records from the start of the current quarter to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::quarterToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2023-10-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### scopeMonthToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current month to now.

```APIDOC
## scopeMonthToDate

### Description
Retrieves records from the start of the current month to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::monthToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2023-10-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### scopeWeekToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current week to now.

```APIDOC
## scopeWeekToDate

### Description
Retrieves records from the start of the current week to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model''s primary key or created_at/updated_at.

### Request Example
```php
Transaction::weekToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2023-10-23 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### scopeDayToNow

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current day (midnight) to now.

```APIDOC
## scopeDayToNow

### Description
Retrieves records from the start of the current day (midnight) to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::dayToNow()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2023-10-27 10:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### Query Optimization with Date Scopes

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/usage-guide.md

Demonstrates efficient querying using date scopes for filtering data within a specific month and contrasts it with inefficient full-table loading and PHP-based filtering. Also shows how to add an index to the created_at column for performance.

```php
// ✅ Good: Creates efficient WHERE BETWEEN query
$transactions = Transaction::ofLastMonth()
    ->where('status', 'completed')
    ->get();

// ❌ Avoid: Loading entire table and filtering in PHP
$transactions = Transaction::all()
    ->filter(fn ($t) => $t->created_at->diffInMonths(now()) <= 1)
    ->filter(fn ($t) => $t->status === 'completed');
```

```php
// ✅ Good: Index on created_at column for performance
Schema::create('transactions', function (Blueprint $table) {
    $table->id();
    $table->timestamps();
    $table->index('created_at');  // Add this
});
```

--------------------------------

### scopeYearToDate

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current year (January 1) to now.

```APIDOC
## scopeYearToDate

### Description
Retrieves records from the start of the current year (January 1) to now.

### Method
N/A (This is a scope method for Eloquent models)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **column** (string) - Optional - The column to apply the date scope to. Defaults to the model's primary key or created_at/updated_at.

### Request Example
```php
Transaction::yearToDate()->get();
```

### Response
#### Success Response (200)
Eloquent Collection of matching records.

#### Response Example
```json
[
  {
    "id": 1,
    "column1": "value1",
    "created_at": "2023-01-01 00:00:00",
    "updated_at": "2023-10-27 10:00:00"
  }
]
```
```

--------------------------------

### Service Provider Configuration Logic

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/LaravelDateScopesServiceProvider.md

The core logic within the service provider for naming the package and handling configuration files.

```php
$package
    ->name('laravel-date-scopes')
    ->hasConfigFile();
```

--------------------------------

### Handle Date Exception

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/README.md

Demonstrates how to catch and handle the specific DateException thrown by the package for invalid date parameters.

```php
use LaracraftTech\LaravelDateScopes\DateException;

try {
    Transaction::ofLastDays(-1)->get();
} catch (DateException $e) {
    echo $e->getMessage();  // "The $value parameter must be a positive integer."
}
```

--------------------------------

### Scope Century To Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current century to now. Applicable for very long-term historical analysis.

```php
public function scopeCenturyToDate(Builder $query, ?string $column = null): Builder
```

```php
$centuryToDate = Transaction::centuryToDate()->get();
```

--------------------------------

### Scope Decade To Date

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/api-reference/DateScopes.md

Retrieves records from the start of the current decade to now. Useful for long-term trend analysis.

```php
public function scopeDecadeToDate(Builder $query, ?string $column = null): Builder
```

```php
$decadeToDate = Transaction::decadeToDate()->get();
```

--------------------------------

### Date Scopes Quick Lookup

Source: https://github.com/laracraft-tech/laravel-date-scopes/blob/main/_autodocs/scope-reference.md

A quick reference table for all available date scope methods, their parameters, and descriptions.

```APIDOC
## Date Scopes Reference

This section provides a quick lookup table for the date scope methods available in the package.

### `ofJustNow()`
#### Description
Retrieves records from the current second (inclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

### `ofLastSecond()`
#### Description
Retrieves records from the last second (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast15Seconds()`
#### Description
Retrieves records from the last 15 seconds.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast30Seconds()`
#### Description
Retrieves records from the last 30 seconds.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast45Seconds()`
#### Description
Retrieves records from the last 45 seconds.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast60Seconds()`
#### Description
Retrieves records from the last 60 seconds.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastSeconds(int $seconds)`
#### Description
Retrieves records from the last N seconds.
#### Parameters
- `seconds` (int) - Required - The number of seconds.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastMinute()`
#### Description
Retrieves records from the last minute (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast15Minutes()`
#### Description
Retrieves records from the last 15 minutes.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast30Minutes()`
#### Description
Retrieves records from the last 30 minutes.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast45Minutes()`
#### Description
Retrieves records from the last 45 minutes.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast60Minutes()`
#### Description
Retrieves records from the last 60 minutes.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastMinutes(int $minutes)`
#### Description
Retrieves records from the last N minutes.
#### Parameters
- `minutes` (int) - Required - The number of minutes.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastHour()`
#### Description
Retrieves records from the last hour (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast6Hours()`
#### Description
Retrieves records from the last 6 hours.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast12Hours()`
#### Description
Retrieves records from the last 12 hours.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast18Hours()`
#### Description
Retrieves records from the last 18 hours.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast24Hours()`
#### Description
Retrieves records from the last 24 hours.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastHours(int $hours)`
#### Description
Retrieves records from the last N hours.
#### Parameters
- `hours` (int) - Required - The number of hours.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofToday()`
#### Description
Retrieves records from today (inclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

### `ofYesterday()`
#### Description
Retrieves records from yesterday (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast7Days()`
#### Description
Retrieves records from the last 7 days.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast14Days()`
#### Description
Retrieves records from the last 14 days.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast21Days()`
#### Description
Retrieves records from the last 21 days.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast30Days()`
#### Description
Retrieves records from the last 30 days.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastDays(int $days)`
#### Description
Retrieves records from the last N days.
#### Parameters
- `days` (int) - Required - The number of days.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastWeek()`
#### Description
Retrieves records from the last week (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast2Weeks()`
#### Description
Retrieves records from the last 2 weeks.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast3Weeks()`
#### Description
Retrieves records from the last 3 weeks.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast4Weeks()`
#### Description
Retrieves records from the last 4 weeks.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastWeeks(int $weeks)`
#### Description
Retrieves records from the last N weeks.
#### Parameters
- `weeks` (int) - Required - The number of weeks.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastMonth()`
#### Description
Retrieves records from the last month (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast3Months()`
#### Description
Retrieves records from the last 3 months.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast6Months()`
#### Description
Retrieves records from the last 6 months.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast9Months()`
#### Description
Retrieves records from the last 9 months.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast12Months()`
#### Description
Retrieves records from the last 12 months.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastMonths(int $months)`
#### Description
Retrieves records from the last N months.
#### Parameters
- `months` (int) - Required - The number of months.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastQuarter()`
#### Description
Retrieves records from the last quarter (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLast2Quarters()`
#### Description
Retrieves records from the last 2 quarters.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast3Quarters()`
#### Description
Retrieves records from the last 3 quarters.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLast4Quarters()`
#### Description
Retrieves records from the last 4 quarters.
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastQuarters(int $quarters)`
#### Description
Retrieves records from the last N quarters.
#### Parameters
- `quarters` (int) - Required - The number of quarters.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastYear()`
#### Description
Retrieves records from the last year (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLastYears(int $years)`
#### Description
Retrieves records from the last N years.
#### Parameters
- `years` (int) - Required - The number of years.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastDecade()`
#### Description
Retrieves records from the last decade (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLastDecades(int $decades)`
#### Description
Retrieves records from the last N decades.
#### Parameters
- `decades` (int) - Required - The number of decades.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastCentury()`
#### Description
Retrieves records from the last century (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLastCenturies(int $centuries)`
#### Description
Retrieves records from the last N centuries.
#### Parameters
- `centuries` (int) - Required - The number of centuries.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `ofLastMillennium()`
#### Description
Retrieves records from the last millennium (exclusive).
#### Parameters
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
EXCLUSIVE

### `ofLastMillenniums(int $millennium)`
#### Description
Retrieves records from the last N millenniums.
#### Parameters
- `millennium` (int) - Required - The number of millenniums.
- `startFrom?` (mixed) - Optional - The starting point for the query.
- `customRange?` (bool) - Optional - Whether to use a custom range.
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
Config

### `secondToNow()`
#### Description
Retrieves records from the start of the second to now (inclusive).
#### Parameters
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

### `minuteToNow()`
#### Description
Retrieves records from the start of the minute to now (inclusive).
#### Parameters
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

### `hourToNow()`
#### Description
Retrieves records from the start of the hour to now (inclusive).
#### Parameters
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

### `dayToNow()`
#### Description
Retrieves records from the start of the day to now (inclusive).
#### Parameters
- `column?` (string) - Optional - The database column to apply the scope to.
#### Default Range
INCLUSIVE

```
Tokens:
Raw