Blade Shortcuts Laravel Package

Getting Started

This package gives you a Blade directive for rendering dates, with the headline feature being the dateOrDiff format — recent dates render relatively ("3 hours ago") while older ones fall back to a formatted date.

• Requirements as of 1.11.0: PHP 8.1+ and Laravel 10+. If you're still on Laravel 6–9 or PHP 8.0, stay pinned to ^1.10; 1.11.0 drops those platforms outright.
• Install: composer require the package, then (only if you need to change defaults) publish its config with php artisan vendor:publish. Most projects can skip publishing entirely.
• Look here first: the config file for the default date format and locale, and the package source for the list of named format keys it accepts (e.g. dateOrDiff). Those two things cover 90% of real usage.
• First use case: drop it into a Blade view instead of ->format() calls:

{{-- absolute, using the configured default format --}}
@date($post->published_at)

{{-- relative when recent, absolute when not --}}
@date($comment->created_at, 'dateOrDiff')

That's the whole onboarding. Swap it in wherever you currently have a mix of diffForHumans() and format() in views, and you immediately get consistent presentation.

Implementation Patterns

Config-driven default, per-call override. Set your house style once in the config (e.g. d M Y), then override only where the context demands it — @date($invoice->due_at, 'dateOrDiff') in an activity feed, the default in a detail page header.

Feed / inbox lists. dateOrDiff is purpose-built for chronological lists where recent items read better as "5 minutes ago" but a two-year-old item should read as a date. Use it for comments, audit logs, notifications and activity streams.

Semantic markup around it. Dates in tables and lists benefit from a machine-readable companion attribute:

<time datetime="{{ $order->created_at->toIso8601String() }}">
    @date($order->created_at, 'dateOrDiff')
</time>

Mail and notification templates. Blade directives work in Markdown mail views, so @date($booking->starts_at) keeps email copy consistent with the web UI without duplicating formatting logic in the Mailable.

Testing with a frozen clock. Anything using dateOrDiff is time-dependent, so pin time in tests:

Carbon::setTestNow('2025-03-01 12:00:00');
$this->get('/comments')
    ->assertSee('2 hours ago');

Reset in tearDown() (Carbon::setTestNow()), and prefer asserting on the rendered string rather than the raw model attribute.

Keep it out of APIs. Directives are a presentation concern. Resources should emit ISO-8601 and let the front end format. Mixing the two leads to clients parsing human strings.

Partial/component encapsulation. If your team repeatedly writes <time> wrappers, extract a small anonymous Blade component that takes a Carbon instance and a format key. That gives you one place to change when the design changes, while still delegating formatting to the directive.

Gotchas and Tips

The 1.11.0 behaviour change is the one to watch. Before this release, @date($date, 'dateOrDiff') on a future date could render "tomorrow" or "in 2 days". Now anything more than ~23 hours ahead renders the formatted date instead. Any test asserting tomorrow / in N days, or any UI copy that assumed future-relative labels, will need updating. Past dates are unaffected.

Boundary semantics. The cutoff is expressed in hours, not calendar days, so "tomorrow at 09:00" from "today at 15:00" may fall inside the window and still read relatively. Don't build business logic on top of the rendered string — it's display-only, and DST transitions make wall-clock reasoning around the boundary unreliable.

Carbon 2 vs Carbon 3. Laravel 11+ ships Carbon 3, and the fix in this release is explicitly Carbon 3 behaviour. If you support multiple Laravel versions in one codebase (or a package that does), verify dateOrDiff output per framework version rather than assuming parity — diff resolution differs.

Null and optional dates. Guard before calling the directive. A nullable deleted_at or published_at passed straight in will either throw or render an empty/garbage value depending on config. Use @if ($model->published_at) … @endif or the null-safe operator.

Stale compiled views after upgrading. Blade directives are compiled into cached views. If output looks unchanged after composer update, run php artisan view:clear before debugging anything else — this burns more time than any real bug.

Timezone. Output uses the application timezone. Store UTC, and convert explicitly (or set app.timezone deliberately) when users span regions — otherwise a 23:30 UTC comment shows as "yesterday" to a user in Sydney.

Localisation. Relative strings and month names follow the app locale; set it per-request before rendering rather than expecting the package to infer a user's language. If you have locale-switching middleware, ensure it runs before the view renders (i.e. not only in a queued job).

Upgrade path discipline. Because 1.11.0 raised the floor to Laravel 10 / PHP 8.1, older apps stop receiving fixes at 1.10.x. Check your composer.json constraints and CI matrix before bumping; if you maintain a fork or downstream package, mirror the package's own tested matrix (Laravel 10–13 across multiple PHP versions) so you catch regressions where they actually occur.

Extension points. Rather than sprinkling format strings across views, publish the config and add named formats there — it keeps overrides discoverable and means a design change is a one-line edit. Reserve inline format arguments for genuinely one-off cases.