PHPackages                             omaralalwi/laravel-time-craft - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. omaralalwi/laravel-time-craft

ActiveLibrary[Database & ORM](/categories/database)

omaralalwi/laravel-time-craft
=============================

Laravel Time Craft is a powerful package for handling date and time scopes in your Laravel applications. It provides a set of convenient traits and helper functions to simplify date and time operations.

2.0.1(1mo ago)131.7k3MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Aug 24Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/omaralalwi/laravel-time-craft)[ Packagist](https://packagist.org/packages/omaralalwi/laravel-time-craft)[ Docs](https://github.com/omaralalwi/laravel-time-craft)[ RSS](/packages/omaralalwi-laravel-time-craft/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (5)Dependencies (6)Versions (13)Used By (0)

Laravel Time Craft
==================

[](#laravel-time-craft)

 [ ![Laravel Time Craft](https://raw.githubusercontent.com/omaralalwi/laravel-time-craft/master/public/images/laravel-time-craft.jpg) ](https://github.com/omaralalwi/laravel-time-craft)

[![Latest Version on Packagist](https://camo.githubusercontent.com/042c95b41ed6e81ddaee1790c873ba602121ed6cfed60ceb0747f09401756701/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d6172616c616c77692f6c61726176656c2d74696d652d63726166742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omaralalwi/laravel-time-craft)[![Total Downloads](https://camo.githubusercontent.com/92d08b363b149d48cd1fd79677795183b4d7bd224513bfee9e56ad398d2db088/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6d6172616c616c77692f6c61726176656c2d74696d652d63726166742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omaralalwi/laravel-time-craft)[![GitHub Issues](https://camo.githubusercontent.com/b96e1c8e75351ced98f63d23bcaa75c7f1146293f5fa2854c86898b5bc92ef1a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6f6d6172616c616c77692f6c61726176656c2d74696d652d63726166742e737667)](https://github.com/omaralalwi/laravel-time-craft/issues)[![GitHub Stars](https://camo.githubusercontent.com/0afad22c3e24e64d97935735a660dc6be52efe95a4440be483535d21c20244bf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f6f6d6172616c616c77692f6c61726176656c2d74696d652d63726166742e737667)](https://github.com/omaralalwi/laravel-time-craft/stargazers)[![License](https://camo.githubusercontent.com/ab1cbe5b17b4819f7f4e6064e44975ac27354e72e8691edb1a7f899b19cb4e25/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f6d6172616c616c77692f6c61726176656c2d74696d652d63726166742e737667)](https://github.com/omaralalwi/laravel-time-craft/blob/master/LICENSE.md)

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

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [The `HasDateTimeScopes` Trait](#the-hasdatetimescopes-trait)
    - [Available Scopes](#available-scopes)
    - [Customizing the Date Field](#customizing-the-date-field)
    - [A Note on Timezones](#a-note-on-timezones)
    - [The `HasReadableDates` Trait](#the-hasreadabledates-trait)
- [Helper Functions](#helper-functions)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [License](#license)
- [More Open Source Packages](#-more-open-source-packages)

Features
--------

[](#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
------------

[](#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
------------

[](#installation)

Install the package via Composer:

```
composer require omaralalwi/laravel-time-craft
```

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

(Optional) publish the configuration file:

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

Configuration
-------------

[](#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',

    // The format used by the HasReadableDates trait for the readable_* accessors.
    'readable_datetime_format' => 'F j, Y g:i A',
];
```

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](#customizing-the-date-field) for examples.

Usage
-----

[](#usage)

### The `HasDateTimeScopes` Trait

[](#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

[](#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

[](#day)

ScopeDescriptionExample`today()`Records dated today.`Order::today()->get();``yesterday()`Records dated yesterday.`Order::yesterday()->get();`#### Exact day in the past (`*Ago`)

[](#exact-day-in-the-past-ago)

ScopeDescriptionExample`oneWeekAgo()`Records dated **exactly** 7 days ago.`Order::oneWeekAgo()->get();``oneMonthAgo()`Records dated **exactly** 30 days ago.`Order::oneMonthAgo()->get();``oneYearAgo()`Records dated **exactly** one year ago.`Order::oneYearAgo()->get();`#### Last N days (range, from N days ago until now)

[](#last-n-days-range-from-n-days-ago-until-now)

ScopeDescriptionExample`last7Days()`Records from the last 7 days.`Order::last7Days()->get();``last10Days()`Records from the last 10 days.`Order::last10Days()->get();``last14Days()`Records from the last 14 days.`Order::last14Days()->get();``last15Days()`Records from the last 15 days.`Order::last15Days()->get();``last21Days()`Records from the last 21 days.`Order::last21Days()->get();``last30Days()`Records from the last 30 days.`Order::last30Days()->get();``lastDays($field = null, $days = 7)`Records from the last `$days` days.`Order::lastDays(null, 12)->get();`> **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

[](#week)

ScopeDescriptionExample`currentWeek()`Records in the current calendar week.`Order::currentWeek()->get();``lastWeek()`Records in the previous calendar week.`Order::lastWeek()->get();`#### Month

[](#month)

ScopeDescriptionExample`currentMonth()`Records in the current month.`Order::currentMonth()->get();``lastMonth()`Records in the previous month.`Order::lastMonth()->get();`#### Year

[](#year)

ScopeDescriptionExample`currentYear()`Records in the current year.`Order::currentYear()->get();``lastYear()`Records in the previous year.`Order::lastYear()->get();`#### Custom range

[](#custom-range)

ScopeDescriptionExample`betweenDates($start, $end, $field = null)`Records within an inclusive date range. Accepts `Carbon` instances or `Y-m-d` strings.`Order::betweenDates('2024-01-01', '2024-01-31')->get();`### Customizing the Date Field

[](#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

[](#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

[](#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:

```
use Illuminate\Database\Eloquent\Model;
use Omaralalwi\LaravelTimeCraft\Traits\HasReadableDates;

class Order extends Model
{
    use HasReadableDates;
}
```

```
$order->readable_created_at;   // "April 30, 2023 3:49 PM"
$order->readable_updated_at;   // "April 30, 2023 3:49 PM"
$order->readable_deleted_at;   // "April 30, 2023 3:49 PM" (only when the model uses SoftDeletes)
```

> **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:

```
$order->readableDate('shipped_at');   // "April 30, 2023 3:49 PM"
```

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

```
class Order extends Model
{
    use HasReadableDates;

    protected $appends = ['readable_created_at'];
}
```

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

[](#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`.

```
// Per model:
class Order extends Model
{
    use HasReadableDates;

    protected $readableDateFormat = 'd/m/Y H:i';
}
```

```
// Globally, in config/laravel-time-craft.php:
'readable_datetime_format' => 'd M Y, g:i A',
```

Helper Functions
----------------

[](#helper-functions)

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

FunctionDescriptionExampleOutput`formatDate($date)`Format a date as `Y-m-d`.`formatDate($order->created_at)``2024-08-25``formatTime($time)`Format a time as `h:i:s A`.`formatTime($order->created_at)``10:38:12 PM``formatDateTime($dateTime)`Format date + time as `Y-m-d H:i:s A`. Parses strings too.`formatDateTime($order->created_at)``2017-02-15 10:38:12 PM``getHumanDateTime($createdAt)`Format a `Carbon` instance as `Y-m-d H:i:s A`. Returns the input unchanged if it is **not** a `Carbon` instance.`getHumanDateTime($order->created_at)``2017-02-15 10:38:12 PM``formatTimeAgo($dateTime)`Human-readable "time ago".`formatTimeAgo($order->created_at)``2 days ago``startOfDay($date)`Start of the given day.`startOfDay($order->created_at)``2024-08-23 00:00:00``endOfDay($date)`End of the given day.`endOfDay($order->created_at)``2024-08-23 23:59:59``isWeekend($date)`Whether the date falls on Sat/Sun.`isWeekend($order->created_at)``true` / `false``addDays($date, $days)`Add days, returns `Y-m-d`.`addDays($order->created_at, 10)``2024-09-02``subtractDays($date, $days)`Subtract days, returns `Y-m-d`.`subtractDays($order->created_at, 10)``2024-08-13`> `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
-------

[](#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](https://github.com/orchestral/testbench) to boot a minimal Laravel app for testing.

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for details on what has changed recently.

Contributing
------------

[](#contributing)

Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting a pull request.

License
-------

[](#license)

The MIT License (MIT). Please see the [License File](LICENSE.md) for more information.

---

📚 More Open Source Packages
---------------------------

[](#-more-open-source-packages)

- [![Lexi Translate](https://raw.githubusercontent.com/omaralalwi/lexi-translate/master/public/images/lexi-translate-banner.jpg) **Lexi Translate** ](https://github.com/omaralalwi/lexi-translate) simplify managing translations for multilingual Eloquent models with the power of morph relationships and caching.
- [![Gpdf](https://raw.githubusercontent.com/omaralalwi/Gpdf/master/public/images/gpdf-banner-bg.jpg) **Gpdf** ](https://github.com/omaralalwi/Gpdf) Open Source HTML to PDF converter for PHP & Laravel applications, supports Arabic content out-of-the-box and other languages.
- [![Laravel Taxify](https://raw.githubusercontent.com/omaralalwi/laravel-taxify/master/public/images/taxify.jpg) **Laravel Taxify** ](https://github.com/omaralalwi/laravel-taxify) a set of helper functions and classes to simplify tax (VAT) calculations within Laravel applications.
- [![Laravel Deployer](https://raw.githubusercontent.com/omaralalwi/laravel-deployer/master/public/images/deployer.jpg) **Laravel Deployer** ](https://github.com/omaralalwi/laravel-deployer) Streamlined deployment for Laravel and Node.js apps, with zero-downtime across various environments and branches.
- [![Laravel Trash Cleaner](https://raw.githubusercontent.com/omaralalwi/laravel-trash-cleaner/master/public/images/laravel-trash-cleaner.jpg) **Laravel Trash Cleaner** ](https://github.com/omaralalwi/laravel-trash-cleaner) clean logs and debug files for debugging packages.
- [![Laravel Startkit](https://raw.githubusercontent.com/omaralalwi/laravel-startkit/master/public/screenshots/backend-rtl.png) **Laravel Startkit** ](https://github.com/omaralalwi/laravel-startkit) Laravel Admin Dashboard & Admin Template with a frontend template, for scalable Laravel projects.

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance94

Actively maintained with recent releases

Popularity30

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~173 days

Total

5

Last Release

32d ago

Major Versions

1.0.2 → 2.0.02026-07-17

PHP version history (2 changes)1.0.0PHP >=7.4

2.0.0PHP ^8.1|^8.2|^8.3|^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/46733da79a34ff686b036a09af1dcc6d21054aee25a5e029500dc87d3c69ba89?d=identicon)[WatheqAlshowaiter](/maintainers/WatheqAlshowaiter)

![](https://www.gravatar.com/avatar/92882431481b621f6509ff259dd600e327c27fc77adcba4fcc7177659059c9a8?d=identicon)[omaralalwi](/maintainers/omaralalwi)

---

Top Contributors

[![omaralalwi](https://avatars.githubusercontent.com/u/25439498?v=4)](https://github.com/omaralalwi "omaralalwi (35 commits)")

---

Tags

carboncastingdatedate-scopesdatetimeeloquentfilterslaravellaravel-scopeslaravel-time-craftormqueriesscopestraitlaravelormeloquentlaravel-packagetraitdatetimequerycarbonfiltersscopescastingquerieslaravel-date-scopesmutatorsomaralalwilaravel-time-craftlaravel querieslaravel scopeslaravel time scopescommon laravel scopesdate-scopes

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/omaralalwi-laravel-time-craft/health.svg)

```
[![Health](https://phpackages.com/badges/omaralalwi-laravel-time-craft/health.svg)](https://phpackages.com/packages/omaralalwi-laravel-time-craft)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.9M110](/packages/mongodb-laravel-mongodb)[kirschbaum-development/eloquent-power-joins

The Laravel magic applied to joins.

1.6k35.7M52](/packages/kirschbaum-development-eloquent-power-joins)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8723.3M27](/packages/yajra-laravel-oci8)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)