Laravel Time Craft

A simple trait and a set of helper functions that let you effortlessly manage date and time queries in Laravel apps — with pre-built Eloquent scopes and formatting helpers, ready to use out of the box.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
  • The HasDateTimeScopes Trait
  • Available Scopes
  • Customizing the Date Field
  • A Note on Timezones
• Helper Functions
• Testing
• Changelog
• Contributing
• License
• More Open Source Packages

Features

• Flexible date scopes — filter records by common time frames (today, yesterday, current week, last month, last N days, and more).
• Helper functions — utilities for formatting dates, times, and human-readable "time ago" representations.
• Dynamic field support — every scope can target any date/time column, configurable globally, per model, or per call.

Requirements

• PHP >= 7.4
• Laravel (Eloquent / Carbon) — the scopes rely on Laravel's query builder and the now()/today() helpers.

Installation

Install the package via Composer:

composer require omaralalwi/laravel-time-craft

The service provider and the LaravelTimeCraft facade are auto-discovered — no manual registration needed.

(Optional) publish the configuration file:

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

Configuration

Publishing creates config/laravel-time-craft.php:

return [
    // The default column used by all scopes when no field is given.
    'default_field' => 'created_at',
];

When a scope needs to know which column to filter on, it resolves the field through a three-level fallback (first match wins):

1. The field passed directly to the scope call.
2. The model's protected $dateField property.
3. The default_field value from the config (created_at by default).

See Customizing the Date Field for examples.

Usage

The HasDateTimeScopes Trait

Add the trait to any Eloquent model:

use Illuminate\Database\Eloquent\Model;
use Omaralalwi\LaravelTimeCraft\Traits\HasDateTimeScopes;

class Order extends Model
{
    use HasDateTimeScopes;
}

Available Scopes

Heads up: the *Ago scopes (oneWeekAgo, oneMonthAgo, oneYearAgo) match a single, exact day in the past — not a range. To filter everything since a point in time, use the lastNDays range scopes instead.

Day

Exact day in the past (*Ago)

Last N days (range, from N days ago until now)

Argument order for lastDays: the field comes first, the number of days second. Pass null for the field to use the default. Example: Order::lastDays(null, 5)->get(); filters the last 5 days on the default field; Order::lastDays('updated_at', 5)->get(); filters on updated_at.

Week

Month

Year

Custom range

Customizing the Date Field

All scopes use created_at by default. You can override the field in three ways:

1. Globally, for every model, via the config file:

'default_field' => 'your_specific_field',

2. Per model, by adding a $dateField property:

class Order extends Model
{
    use HasDateTimeScopes;

    protected $dateField = 'updated_at';
}

3. Per call, by passing the field name directly:

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

A Note on Timezones

Scopes are built on Laravel's now() / today() helpers, so "today", "this week", etc. are evaluated against your application timezone (config('app.timezone')). Make sure your app timezone and the stored timestamps are consistent to get the results you expect.

Helper Functions

These globally-available functions can be used anywhere (Blade files, classes, controllers). Each accepts a \DateTime/Carbon instance or a date string.

getHumanDateTime and formatDateTime produce the same format, but differ in input handling: getHumanDateTime only formats Carbon instances (anything else is returned as-is), while formatDateTime also parses date strings.

Testing

composer install   # install dev dependencies first
composer test      # run the PHPUnit suite

composer test-coverage   # run with an HTML coverage report in ./coverage

The package uses Orchestra Testbench to boot a minimal Laravel app for testing.

Changelog

Please see CHANGELOG for details on what has changed recently.

Contributing

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

License

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

📚 More Open Source Packages

• Lexi Translate simplify managing translations for multilingual Eloquent models with the 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 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 across various environments and branches.

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

• Laravel Startkit Laravel Admin Dashboard & Admin Template with a frontend template, for scalable Laravel projects.