Laravel Time Helpers Laravel Package

Getting Started

mateusjunges/laravel-time-helpers is a small utility package that wraps common Carbon/time manipulations into terse helper calls, so you stop re-writing Carbon::now()->addDays(3)->startOfDay() style chains across controllers, jobs, and Blade views.

1. Install with Composer — Laravel's package discovery handles registration, so there is usually no manual providers entry:

   composer require mateusjunges/laravel-time-helpers
   

2. Check the support matrix before you commit. v1.1.0 requires PHP ^8.0 and Laravel 9. If the app is still on Laravel 7/8 or PHP 7.4, pin ^1.0 instead:

   composer require mateusjunges/laravel-time-helpers:^1.0
   

3. Look first at the package README's helper table — the value of a package like this is the exact function names and return types, and that list is the whole API surface. There is typically nothing to publish or configure.
4. First use case: pick one noisy spot in your codebase — usually a scheduled job or a dashboard query — and replace the inline Carbon chain with the equivalent helper. Confirm the returned instance type (mutable Carbon vs CarbonImmutable) before spreading it further.

Implementation Patterns

Wrap, don't scatter. Helpers are global functions, so they are easy to litter through views. Prefer calling them in one place (a model scope, an action class, or a Blade component) so the rest of the app depends on your abstraction rather than on the package. That keeps a future removal cheap.

Pair with scopes for query building. The natural integration is a local scope that resolves the helper once and applies it as a bound parameter:

public function scopeCreatedWithin(Builder $query, string $window): Builder
{
    return $query->where('created_at', '>=', now()->sub($window));
}

Keeping the helper call inside the scope means the value is computed at call time and stays testable via Carbon::setTestNow().

Use in scheduled work and cache TTLs. Time helpers read best where a literal duration is the point — ->delay(...), Cache::put($key, $value, ...), queue retry windows. These are the places where an inline Carbon chain obscures intent.

Keep the dependency at the edges. Treat the package like a convenience layer: reference it from controllers, console commands, and Blade components, not from domain entities. Domain code should accept a DateTimeInterface and let the caller decide how it was produced.

Upgrade path for v1.1.0. Because the release is purely a support-matrix bump, adoption is a two-line change in composer.json plus a CI matrix update. Bump PHP to ^8.0, move the Laravel constraint to ^9.0, then run the suite — the helpers themselves are unchanged from 1.0.1, so regressions will come from your own PHP 8 / Laravel 9 migration, not from this package.

Gotchas and Tips

• Silent constraint failures. If composer update refuses the package, the cause is almost always the PHP or Laravel constraint, not a dependency conflict with anything else. Run composer why-not mateusjunges/laravel-time-helpers 1.1.0 first.
• Global function collisions. Helper packages define namespaced-or-global functions; if another package (or your own app/helpers.php) defines the same name, you get a fatal redeclare error that only shows at runtime. Grep your helper files before installing.
• Carbon mutability. If a helper returns a mutable Carbon, chaining ->addDay() mutates the shared instance and can silently corrupt a value you reused elsewhere. Prefer ->copy() or CarbonImmutable where available.
• Timezone is your config, not the package's. Helpers resolve against config('app.timezone'). In a queue worker or an Octane process with a stale config cache, this is a classic source of "works locally, off by hours in production" bugs — verify with php artisan config:clear before debugging the package.
• DST and month arithmetic. Anything built on addMonth() / addDay() around DST boundaries can shift by an hour or overflow (Jan 31 + 1 month). Test those cases explicitly rather than trusting the helper name.
• Testing. Carbon::setTestNow() and Laravel's travelTo() / freezeTime() intercept Carbon globally, so helpers are testable without mocking — but reset with Carbon::setTestNow() in tearDown() to avoid leaking frozen time between tests.
• No extension points to speak of. This is a thin convenience package; if you need custom behaviour (business hours, holiday calendars), wrap it in your own class instead of hoping for a config hook.
• Pinning discipline. Given the 1.0 → 1.1 jump dropped two major support lines without deprecation noise, pin to ^1.1 and read release notes before minor bumps — the maintainer treats support-matrix and feature changes as the same class of release.