Using Relative Date Helpers in Laravel's Query Builder

With the release of Laravel 11.42, we now have access to useful relative query builder methods for dates. While you don't need to refactor all your applications to use these methods, they add a nice, readable touch to relative date logic in your models. Let's look at an example using an Article model:

Imagine you have a scope to get published posts that include a specific status, and the published_at date must be either equal to now() or before now():

use Illuminate\Database\Eloquent\Builder;
use App\Models\Article;

public function scopeActive(): Article|Builder
{
    return $this->where('status', ArticleStatus::Published)
                ->where('published_at', '<=', now());
}

You can use this scope elsewhere in the code to constrain articles to only active ones.

Article::with('user', 'category', 'tags')
    ->active()
    ->orderByDesc('published_at')
    ->limit(20)
    ->get();

Now, with Laravel 11.42, we can make a slight adjustment to the scopeActive() method to use a relative date method. We want the whereNowOrPast to match our original logic:

$this->where('status', ArticleStatus::Published)
-      ->where('published_at', '<=', now());
+      ->whereNowOrPast('published_at');

If we want to use the query builder to find articles marked as Published but are still in the future, we can use the whereFuture() method:

$this->where('status', ArticleStatus::Published)
     ->whereFuture('published_at');

What if we wanted to find articles before or after today's date? The new relative date helpers have variants such as or, and not:

$this->whereAfterToday('published_at')
     ->orWhereBeforeToday('published_at');

If you'd like to learn more about all the new relative date methods added to Laravel in v11.42, check out Pull Request #54408. These methods are located in a new trait called BuildsWhereDateClauses.