tonysm / local-time-laravel
A port of the `local-time` gem from Basecamp.
Requires
- php: ^7.4|^8.0|^8.1|^8.2|^8.3
- illuminate/support: ^8.47|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^6.0|^8.0
- phpunit/phpunit: ^10.5
README
This is a Laravel port of the local_time
gem from Basecamp. It makes it easy to display date and time to users in their local time. Its Blade components render a time
HTML tag in UTC (making it cache friendly), and the JavaScript component immediately converts those elements from UTC to the Browser's local time.
Installation
- Install the package via Composer:
composer require tonysm/local-time-laravel
- Install the
local-time
JS lib via NPM:
npm install local-time -D
And then import it on your resources/app.js
file, like so:
// ... import LocalTime from "local-time" LocalTime.start()
Usage
This package adds a couple Blade components to your project, they are:
<x-local-time :value="now()" />
Formats the Carbon instance using the default format string. It will convert the regular PHP formats to the strftime
format for you.
<x-local-time :value="now()" format="F j, Y g:ia" />
Alias for <x-local-time />
with a month-formatted default. It converts that format to %B %e, %Y %l:%M%P
.
<x-local-date :value="now()" format="F j, Y" />
You can configure the format used by passing it as a prop to the component. Any other attribute will be rendered in the generated time
tag.
<x-local-time :value="now()" class="my-time" />
Renders the time
tag using the default time format and adds the given class
tag attribute to the element.
Note: The included strftime JavaScript implementation is not 100% complete. It supports the following directives: %a %A %b %B %c %d %e %H %I %l %m %M %p %P %S %w %y %Y %Z
Time ago helper
<x-local-time-ago :value="now()" />
Displays the relative amount of time passed. With age, the descriptions transition from {quantity of seconds, minutes, or hours} to {date + time} to {date}. The <time>
elements are updated every 60 seconds.
Examples (in quotes):
- Recent: "a second ago", "32 seconds ago", "an hour ago", "14 hours ago"
- Yesterday: "yesterday at 5:22pm"
- This week: "Tuesday at 12:48am"
- This year: "on Nov 17"
- Last year: "on Jan 31, 2012"
Relative time helper
Preset time and date formats that vary with age. The available types are date, time-ago, time-or-date, and weekday. Like the <x-local-time />
component, type
can be passed a string.
<x-local-relative-time :value="now()" type="weekday" /> <x-local-relative-time :value="now()" type="time-or-date" />
Available type
options:
date
: Includes the year unless it's current. "Apr 11" or "Apr 11, 2013"time-ago
: See above.<x-local-time-ago />
calls<x-local-time-relative />
with thistype
option.time-or-date
: Displays the time if it occurs today or the date if not. "3:26pm" or "Apr 11"weekday
: Displays "Today", "Yesterday", or the weekday (e.g. Wednesday) if the time is within a week of today.weekday-or-date
: Displays the weekday if it occurs within a week or the date if not. "Yesterday" or "Apr 11"
Example
php artisan tinker >>> $user->created_at => Illuminate\Support\Carbon @1625103168 {#4106 date: 2021-06-30 22:32:48.0 UTC (+00:00), }
<x-local-time :value="$user->created_at" />
Renders:
<time data-format="%B %e, %Y %l:%M%P" data-local="time" datetime="2021-06-30T22:32:48Z">June 30, 2021 22:32pm</time>
And is converted client-side to:
<time data-format="%B %e, %Y %l:%M%P" data-local="time" datetime="2021-06-30T22:32:48Z" title="June 30, 2013 22:32pm EDT" data-localized="true">June 30, 2021 22:32pm</time>
Configuration
To configure the default date and time formats, you can use the useTimeFormat
and useDateFormat
methods on the LocalTimeLaravelFacade
on your AppServiceProvider
, like so:
<?php use Illuminate\Support\ServiceProvider; use Tonysm\LocalTimeLaravel\LocalTimeLaravelFacade; class AppServiceProvider extends ServiceProvider { public function boot() { LocalTimeLaravelFacade::useTimeFormat('H:i'); LocalTimeLaravelFacade::useDateFormat('d/m/Y H:i'); } }
The JavaScript lib allows some configurations as well as internationalization (i18n). To know more about that, head out to the Rails gem documentation.
Testing
composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email tonysm@hey.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
Laravel Package Boilerplate
This package was generated using the Laravel Package Boilerplate.