- What is djl997/blade-shortcuts and what does it do?
- It is a small library of Blade directives for Laravel, including a @date directive that wraps Carbon formatting presets such as dateOrDiff. It adds no persistence, queues, or external services; it is a thin presentation-layer helper that runs during view rendering. Its value is consistency and less repetitive formatting markup across many Blade templates, not new capability.
- How do I install djl997/blade-shortcuts in a Laravel app?
- Run composer require djl997/blade-shortcuts on a project using PHP 8.1 or newer and Laravel 10 or newer. There are no migrations, no config file to publish, and no infrastructure change involved, so integration is measured in minutes. After installing, use the directives directly in your Blade views.
- Which Laravel and PHP versions does blade-shortcuts support?
- This release requires PHP 8.1+ and Laravel 10+. Laravel 6, 7, 8, and 9 and PHP 8.0 are not supported, so projects on those versions must stay on an older constraint such as below 1.11.0 or upgrade the framework first. CI is also reported to test newer framework versions, so check the composer constraint before installing on pre-release Laravel builds in production.
- How does the @date directive work and what is dateOrDiff?
- The @date directive renders a date using Carbon formatting presets instead of writing Carbon::parse and format calls in every view. The dateOrDiff preset shows a relative string for near dates and falls back to a formatted date further out. It is intended for server-rendered UI such as admin panels, transactional emails, and PDF templates.
- Why did future date output change in Laravel 11 and Carbon 3?
- In the 1.11 release, dateOrDiff renders a formatted date for future dates more than roughly 23 hours away instead of relative text like tomorrow or in 2 days. That corrected behaviour applies on Carbon 3 and Laravel 11+, while Laravel 10 keeps the older output. Because the visible text changed under a minor version, snapshot tests, cached HTML, emails, PDFs, and translation assertions should be reviewed.
- Should I pin blade-shortcuts to avoid the behavioural change?
- Pin to below 1.11.0 if you depend on the previous relative output or cannot move to Laravel 10+ yet, and record the upgrade as tech debt with an owner. For Laravel 10+ projects, upgrade in a branch, run the full test suite, and check any test or cached artefact asserting relative date strings. How the maintainer classifies this release should guide how tightly you constrain the package.
- Does blade-shortcuts work with API-only, Inertia, or Vue and React front ends?
- No. The package only affects Blade-rendered server-side views, so API-first services, Inertia with React or Vue, and headless front ends gain nothing and would duplicate formatting logic on the client. Adopt it only where Blade templates are the rendering layer.
- How do I test Blade templates that use @date and relative date strings?
- Freeze time with Carbon test helpers such as setTestNow or travelTo so relative strings are deterministic, then assert the exact rendered output. Test the lowest supported combination you actually run, since dateOrDiff output differs between Laravel 10 and Laravel 11+. Re-check email, PDF, and cached fragment tests after upgrading.
- Is blade-shortcuts localised, and which timezone is used for relative dates?
- The relative strings come from Carbon, so they follow its locale handling; the package adds no translation layer of its own, and translated output should be verified per locale. Timezone handling is not a separate package setting and follows Carbon and your app.timezone, so the roughly 23-hour future-date check can still mislabel around DST boundaries or in non-UTC and per-user timezones. Confirm expectations for your app timezone before relying on tomorrow-style output.
- What are the alternatives to djl997/blade-shortcuts for formatting dates in Blade?
- For a single call, inline Carbon::parse with isoFormat or diffForHumans in the view, or a model accessor, is equivalent and adds no dependency. You can also register your own Blade directive in a service provider or use a view component. The package pays off when many templates need the same formatting conventions.