README

simple trait and helper functions that allow you, Effortlessly manage date and time queries in Laravel apps, with pre-built scopes and helper functions with ease.

Features

• Flexible Date Scopes: Easily filter records based on various time frames (e.g., today, yesterday, current week, last month, etc.).
• Helper Functions: Utility functions for formatting dates, times, and human-readable date-time representations.
• Dynamic Field Support: Scopes can be applied to any date or time field in your models.

Installation

You can install the package via Composer:

composer require omaralalwi/laravel-time-craft

publish the package's configuration file:

php artisan vendor:publish --tag=laravel-time-craft

Usage

Using the HasDateTimeScopes Trait

Add the HasDateTimeScopes trait to your Eloquent model:

use Omaralalwi\LaravelTimeCraft\Traits\HasDateTimeScopes;

class Order extends Model
{
    use HasDateTimeScopes;
}

Available Scopes in HasDateTimeScopes trait

You can apply various scopes in your model queries. Below are the descriptions, usage examples, and corresponding outputs for each scope:

• today : Filters records created today.

  $todayOrders = Order::today()->get();

• yesterday : Filters records created yesterday.

  $yesterdayOrders = Order::yesterday()->get();

• oneWeekAgo : Filters records created in the last seven days.

  $lastSevenDaysOrders = Order::oneWeekAgo()->get();

• lastWeek : Filters records created in the last week.

  $lastWeekOrders = Order::lastWeek()->get();

• currentWeek : Filters records created in the current week.

  $currentWeekOrders = Order::currentWeek()->get();

• last7Days : Filters records created in the last 7 days.

  $last7DaysOrders = Order::last7Days()->get();

• last10Days : Filters records created in the last 10 days.

  $last10DaysOrders = Order::last10Days()->get();

• last14Days : Filters records created in the last 14 days.

  $last14DaysOrders = Order::last14Days()->get();

• last15Days : Filters records created in the last 15 days.

  $last15DaysOrders = Order::last15Days()->get();

• last21Days : Filters records created in the last 21 days.

  $last21DaysOrders = Order::last21Days()->get();

• last30Days : Filters records created in the last 30 days.

  $last30DaysOrders = Order::last30Days()->get();

• lastDays($days) : Filters records created in the last number of days specified.

  // Filters records created in the last 5 days
  $last5DaysOrders = Order::lastDays(null,5)->get(); // null mean take default field 'created_at' , or you can pass it 'created_at'
  // Filters records created in the last 12 days
  $last10DaysOrders = Order::lastDays(null,12)->get();

• oneMonthAgo : Filters records created in the last 30 days.

  $ordersLast30Days = Order::oneMonthAgo()->get();

• lastMonth : Filters records created last month.

  $lastMonthOrders = Order::lastMonth()->get();

• currentMonth : Filters records created in the current month.

  $thisMonthOrders = Order::currentMonth()->get();

• lastYear : Filters records created in the last year.

  $lastYearOrders = Order::lastYear()->get();

• oneYearAgo : Filters records created exactly one year ago.

  $oneYearAgoOrders = Order::oneYearAgo()->get();

• currentYear : Filters records created in the current year.

  $thisYearOrders = Order::currentYear()->get();

• betweenDates : Filters records within a specific date range.

  $ordersBetweenDates = Order::betweenDates('2024-01-01', '2024-01-31')->get();

Customize Scoping field

all scopes using created_at by default. You can override by three ways:-

in config file as default for all models

'default_field' => 'your_specific_field'

customize it for every model : by adding following line in model class:

class Order extends Model
{
    use HasDateTimeScopes;

    protected $dateField = 'updated_at';
}

pass field name directly when using the scopes:

$lastWeekOrders = Order::lastWeek('updated_at')->get();

Format Date Time Using Helper Functions

You can use the provided helper functions in your application (in Blade files or in any class). Below are the descriptions, usage examples, and corresponding outputs for each helper function:

• formatDate : Formats a given date to "Y-m-d" format.

  $formattedDate = formatDate($order->created_at); // 2024-08-25

• formatTime : Formats a given time to "h:i:s A" format.

  $formattedTime = formatTime($order->created_at); // 10:38:12 PM

• getHumanDateTime : Formats the created_at datetime to "Y-m-d H:i:s A" format.

  $humanDateTime = getHumanDateTime($order->created_at); // 2017-02-15 10:38:12 PM

• formatDateTime : Formats a given date and time to "Y-m-d H:i:s A" format.

  $formattedDateTime = formatDateTime($order->created_at); // 2017-02-15 10:38:12 PM

• formatTimeAgo : Gets a human-readable "time ago" format for a given date.

  $timeAgo = formatTimeAgo($order->created_at); // 2 days ago

• startOfDay : Gets the start of the day for a given date.

  $startOfDay = startOfDay($order->created_at); // 2024-08-23 00:00:00

• endOfDay : Gets the end of the day for a given date.

  $endOfDay = endOfDay($order->created_at); // 2024-08-23 23:59:59

• isWeekend : Checks if a given date is on the weekend.

  $isWeekend = isWeekend($order->created_at); // true or false

• addDays : Adds a specified number of days to a given date.

  $futureDate = addDays($order->created_at, 10); // 2024-09-02

• subtractDays : Subtracts a specified number of days from a given date.

  $pastDate = subtractDays($order->created_at, 10); // 2024-08-13

Helpful Packages

You may be interested in our other packages:

• Gpdf : PDF converter for php & Laravel apps, support storing PDF files to S3.
• laravel-taxify : simplify tax (VAT) calculations in laravel apps.
• laravel-deployer : Streamlined deployment for Laravel and Node.js apps.
• laravel-trash-cleaner : Cleans logs and debug files for logs and debugging packages.

Tests

tests will coming soon.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

The MIT License (MIT). Please see License File for more information.

📚 Helpful Open Source Packages

• Lexi Translate simplify managing translations for multilingual Eloquent models with power of morph relationships and caching .

• Gpdf Open Source HTML to PDF converter for PHP & Laravel Applications, supports Arabic content out-of-the-box and other languages..

• laravel Taxify Laravel Taxify provides a set of helper functions and classes to simplify tax (VAT) calculations within Laravel applications.

• laravel Deployer Streamlined Deployment for Laravel and Node.js apps, with Zero-Downtime and various environments and branches.

• laravel Trash Cleaner clean logs and debug files for debugging packages.

• Laravel Startkit Laravel Admin Dashboard, Admin Template with Frontend Template, for scalable Laravel projects.