Datetime Laravel Package

Getting Started

Install and verify

composer require fresh/datetime

There is no service provider, no config file, and nothing to publish — this is a plain function library, so installation is the whole setup. Confirm the PHP constraint in composer.json before adding it to an older Laravel app; small utility libraries like this often track recent PHP versions and will block composer update on a legacy project.

Where to look first

1. README.md — the function list is the API surface. Skim it end-to-end once; the value here is coverage of calendar facts you would otherwise hand-roll.
2. src/ — nearly everything lives in one or two files of namespaced functions. Read the file header to see the namespace and whether functions are loaded via autoload.files.
3. tests/ — the fastest way to learn edge-case behaviour (leap years, month-end clamping, week numbering) without guessing.

First use case

Start with the thing Carbon makes awkward: a one-off calendar question where you do not want to construct, mutate, and format an object just to get a scalar back.

use function fresh\datetime\...; // take exact names from the README for your version

// e.g. calendar facts used inside a Blade view or a validation rule
$daysInMonth = ...;   // instead of Carbon::now()->daysInMonth
$isWeekend   = ...;   // instead of $date->isWeekend()

The real test is: pick one place in your codebase where you currently write a three-line Carbon dance to answer a yes/no or integer question, and replace it. If that reads better, adopt the library for that category of problem only. If it reads worse, you have learned that Carbon already covers you and this package is not worth the dependency.

Implementation Patterns

Treat it as a scalar-returning complement to Carbon, not a replacement. Carbon owns timezone-aware arithmetic, diffing, parsing, and serialization. This library owns calendar facts. A healthy split looks like:

• Carbon for anything that crosses a timezone boundary, gets stored, or is diffed against "now".
• This package for pure predicates and integers over an already-resolved DateTimeInterface.

Do not mix them in the same expression chain. Pass Carbon::parse($x) into these functions and get plain values back; never try to get a Carbon out.

Wrap it once, behind a small app-level service. Because these are free functions, they are un-mockable and invisible to the container. A thin adapter gives you a seam and a single place to swap the implementation out later:

final class Calendar
{
    public function daysInMonth(DateTimeInterface $d): int { /* delegate */ }
    public function isWeekend(DateTimeInterface $d): bool { /* delegate */ }
}

Bind it in a service provider and inject it. Costs ten minutes, and it means the day you decide the package is not worth its maintenance you rewrite one class instead of grepping the codebase.

Validation rules and form requests. Age gates, "must be a weekday", "must fall in the current quarter" — these read far better as a Rule closure calling a predicate than as inline Carbon arithmetic, and they are trivially unit-testable because the inputs are explicit.

Factories and seeders. Generating plausible historical dates (a birthday, an invoice date on a business day, a month-end statement date) is a nice fit: the functions are pure, so seeded output stays reproducible.

Tests. This is the strongest argument for the package. Pure functions over explicit inputs mean no Carbon::setTestNow() juggling and no mutable-state surprises in data providers. If you already have a tests/Unit/Dates folder full of hand-rolled calendar helpers, this library replaces it and comes with its own test suite.

Blade. Import the functions at the top of a view composer or dedicated presenter rather than inside templates. Calling namespaced functions from Blade works but makes the template harder to scan, and it hides a hard dependency in the least testable layer of the app.

Incremental adoption. Because there is no bootstrapping, you can use one function in one file and nothing else. Resist building a "date utilities" module around it; the dependency is small enough that partial adoption is the correct default.

Gotchas and Tips

Namespaced functions need use function imports. This is the number-one source of confusion. use Fresh\DateTime\Foo; will not autoload a function. Use use function fresh\datetime\foo; — and note that the namespace casing in the docs may not match the actual declaration, which matters on case-sensitive filesystems. If a function "does not exist" in production but works locally, suspect casing.

Global function collisions. Helpers named things like is_leap_year or days_in_month are exactly the kind of names other packages also define. If you see "cannot redeclare function", you have two libraries fighting. Isolate by importing with an alias: use function fresh\datetime\foo as dt_foo;.

Timezone is implicit. Pure calendar functions typically operate on whatever the DateTimeInterface carries, or fall back to the process default timezone. Set date_default_timezone_set(config('app.timezone')) early (Laravel does this in the framework bootstrap, but queue workers and standalone scripts sometimes do not) and always pass objects that already have the zone you intend. A date that is "the 1st" in UTC is "the 31st" in Auckland.

Nothing is injectable or mockable. There is no facade, no container binding, no Carbon::setTestNow() equivalent. If a function internally calls new DateTime() or time(), you cannot freeze it. Check the signature: if it does not accept a date argument, avoid it in code paths you need to test deterministically — pass your own reference date instead.

IDE and static analysis blindness. Functions are not discoverable by autocomplete the way classes are, and PHPStan/Psalm will flag them as undefined unless the package ships stub files or you add them to scanFiles. Budget for a phpstan.neon entry; without it, the first CI run after adoption will fail.

Vendor risk is the real cost. Eighteen stars, zero dependents, a single maintainer. That is fine for a leaf utility — but pin it ("fresh/datetime": "^1.0" with a committed composer.lock), and be honest that the fallback is a 100-line internal helper file. The licence is MIT, so forking or vendoring is a legitimate escape hatch if the package stalls.

Verify the release cadence claim yourself. The advertised last release date is in the future relative to typical use; check Packagist for the actual tagged version and diff the changelog before assuming API stability. A single 0.x bump can rename functions with no deprecation path.

Extension points are wrappers, not inheritance. You cannot subclass a function. If behaviour is close but not right (week-numbering convention, "week starts on Monday" vs Sunday), do not patch around it at every call site — implement the convention in your Calendar adapter and delegate only for the cases where the library agrees with you.

Debugging tip. When a result looks wrong, reproduce it in php -r with an explicit DateTimeImmutable before blaming Laravel. Nearly every surprise with this class of library is DST or month-end clamping, both of which are visible immediately in a two-line REPL check.