Download the PHP package omaralalwi/laravel-time-craft without Composer

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
  • The HasReadableDates Trait
• 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).
• Readable date accessors — a drop-in trait that adds human-readable readable_created_at / readable_updated_at / readable_deleted_at accessors (and a generic readableDate() helper) to any model, without clobbering the real Carbon timestamps.
• 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 ^8.1 – ^8.4
• Laravel 10.x, 11.x, 12.x, or 13.x (Eloquent / Carbon) — the scopes rely on Laravel's query builder and the now()/today() helpers.

Each Laravel version keeps its own PHP floor: Laravel 10 needs PHP ^8.1, Laravel 11/12 need ^8.2, and Laravel 13 needs ^8.3. Composer automatically installs the highest Laravel your PHP version supports.

Installation

Install the package via Composer:

The service provider is auto-discovered — no manual registration needed.

(Optional) publish the configuration file:

Configuration

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

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:

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:

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

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

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.

The HasReadableDates Trait

Tired of formatting created_at / updated_at / deleted_at in every model, controller, and Blade view? Add the trait once and get ready-to-display, human-readable date accessors:

Non-destructive by design: unlike overriding the timestamp attributes directly, this trait adds separate readable_* accessors. Your real $order->created_at keeps returning a Carbon instance, so date math, sorting, comparisons and casting all keep working — you just get a formatted string on the side.

Format any date field. Use readableDate() for columns beyond the standard timestamps:

Include them in JSON / API responses by appending the accessors:

Safe on models without the columns. readable_deleted_at returns null unless the model uses SoftDeletes (detected recursively, so it also works when SoftDeletes comes from a parent class), and the readable_created_at / readable_updated_at accessors return null when the model has public $timestamps = false.

Customizing the format

The format is resolved through a three-level fallback (first match wins):

1. The model's protected $readableDateFormat property.
2. The readable_datetime_format value from the config.
3. The built-in default, F j, Y g:i A.

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

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.