Date Scopes V1

.github/ISSUE_TEMPLATE/config.yml

@@ -1,14 +1,14 @@
 blank_issues_enabled: false
 contact_links:
   - name: Ask a question
-    url: https://github.com/:vendor_name/:package_name/discussions/new?category=q-a
+    url: https://github.com/laracraft-tech/laravel-date-scopes/discussions/new?category=q-a
     about: Ask the community for help
   - name: Request a feature
-    url: https://github.com/:vendor_name/:package_name/discussions/new?category=ideas
+    url: https://github.com/laracraft-tech/laravel-date-scopes/discussions/new?category=ideas
     about: Share ideas for new features
   - name: Report a security issue
-    url: https://github.com/:vendor_name/:package_name/security/policy
+    url: https://github.com/laracraft-tech/laravel-date-scopes/security/policy
     about: Learn how to notify us for sensitive bugs
   - name: Report a bug
-    url: https://github.com/:vendor_name/:package_name/issues/new
+    url: https://github.com/laracraft-tech/laravel-date-scopes/issues/new
     about: Report a reproducible bug

.github/workflows/run-tests.yml

@@ -14,9 +14,12 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest]
         php: [8.2, 8.1]
-        laravel: [9.*]
+        laravel: [10.*, 9.*]
         stability: [prefer-lowest, prefer-stable]
         include:
+          - laravel: 10.*
+            testbench: 8.*
+            carbon: ^2.63
           - laravel: 9.*
             testbench: 7.*
             carbon: ^2.63

CHANGELOG.md

@@ -1,3 +1,3 @@
 # Changelog
 
-All notable changes to `:package_name` will be documented in this file.
+All notable changes to `laravel-date-scopes` will be documented in this file.

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) :vendor_name <[email protected]>
+Copyright (c) laracraft-tech <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,61 +1,220 @@
-# :package_description
-
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-[![Tests](https://github.com/:vendor_slug/:package_slug/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/:vendor_slug/:package_slug/actions/workflows/run-tests.yml)
-[![Check & fix styling](https://github.com/:vendor_slug/:package_slug/actions/workflows/fix-php-code-style-issues.yml/badge.svg?branch=main)](https://github.com/:vendor_slug/:package_slug/actions/workflows/fix-php-code-style-issues.yml)
-[![License](https://img.shields.io/packagist/l/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-<!--[![Total Downloads](https://img.shields.io/packagist/dt/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)-->
-<!--delete-->
----
-This repo can be used to scaffold a Laravel package. Follow these steps to get started:
-
-1. Press the "Use this template" button at the top of this repo to create a new repo with the contents of this skeleton.
-2. Run "php ./configure.php" to run a script that will replace all placeholders throughout all the files.
-3. Have fun creating your package.
-4. If you need help creating a package, consider picking up our <a href="https://laravelpackage.training">Laravel Package Training</a> video course.
----
-<!--/delete-->
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+# 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 :vendor_slug/:package_slug
+composer require laracraft-tech/laravel-date-scopes
 ```
 
-You can publish and run the migrations with:
+## Configuration
 
-```bash
-php artisan vendor:publish --tag=":package_slug-migrations"
-php artisan migrate
-```
+### 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.
+
+### Config
 
 You can publish the config file with:
 
 ```bash
-php artisan vendor:publish --tag=":package_slug-config"
+php artisan vendor:publish --tag="laravel-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 optionally specify it 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 have a custom created_at column name, change it here.
+     */
+    'created_column' => env('DATE_SCOPES_CREATED_COLUMN', 'created_at'),
 ];
 ```
 
-Optionally, you can publish the views using
+If you want to change the default range to inclusive set `DATE_SCOPES_DEFAULT_RANGE=inclusive` in your `.env`.
 
-```bash
-php artisan vendor:publish --tag=":package_slug-views"
+## Scopes
+
+- [`seconds`](#seconds)
+- [`minutes`](#minutes)
+- [`hours`](#hours)
+- [`months`](#months)
+- [`quarters`](#quarters)
+- [`years`](#years)
+- [`decades`](#decades)
+- [`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::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
+```
+
+### Quarter
+
+```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
+```
+
+### Millennium
+
+```php
+// query by MILLENNIUM
+Transaction::ofLastMillennium(); // query transactions created during the last millennium
+Transaction::ofLastMillenniums(2); // query transactions created during the last N millenniums
 ```
 
-## Usage
+### toNow/toDate
 
 ```php
-$variable = new VendorName\Skeleton();
-echo $variable->echoPhrase('Hello, VendorName!');
+// query by toNow/toDate
+Transaction::secondToNow(); // query transactions created during the start of the current second to now (not really usefull I guess)
+Transaction::minuteToNow(); // query transactions created during the start of the current minute to now
+Transaction::hourToNow(); // query transactions created during the start of the current hour to now
+Transaction::dayToNow(); // query transactions created during the start of the current day to now
+Transaction::weekToDate(); // query transactions created during the start of the current week to now
+Transaction::monthToDate(); // query transactions created during the start of the current month to now
+Transaction::quarterToDate(); // query transactions created during the start of the current quarter to now
+Transaction::yearToDate(); // query transactions created during the start of the current year to now
+Transaction::decadeToDate(); // query transactions created during the start of the current decade to now
+Transaction::millenniumToDate(); // query transactions created during the start of the current millennium to now
 ```
 
 ## Testing
@@ -78,7 +237,7 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 ## Credits
 
-- [:author_name](https://github.com/:author_username)
+- [Zacharias Creutznacher](https://github.com/laracraft-tech)
 - [All Contributors](../../contributors)
 
 ## License