knplabs/knp-time-bundle

Making your dates and durations look sensible and descriptive

v2.4.0 2024-06-11 09:38 UTC

Requires

• php: >=8.1
• symfony/config: ^5.4|^6.0|^7.0
• symfony/dependency-injection: ^5.4|^6.0|^7.0
• symfony/translation: ^5.4|^6.0|^7.0

Requires (Dev)

• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^9.6
• symfony/framework-bundle: ^5.4|^6.0|^7.0
• symfony/phpunit-bridge: ^5.4|^6.0|^7.0
• symfony/twig-bundle: ^5.4|^6.0|^7.0

Suggests

• symfony/twig-bundle: to use the Twig `time_diff()` function and `|time_diff`/`|duration` filter

Conflicts

• phpunit/phpunit: <8.0

MIT

• KnpLabs Team
• Symfony Community

• knp
• knplabs
• bundle
• time
• date
• descriptive time
• duration

README

Friendly ago/until dates ("5 minutes ago" or "in 5 minutes") and durations ("2 mins")!

Last edited: {{ post.updatedAt|time_diff }} <!-- Last edited: 1 week ago -->

Event date: {{ event.date|time_diff }} <!-- Event date: in two weeks -->

Read time: {{ post.readTimeInSeconds|duration }} <!-- Read time: 2 minutes -->

Age: {{ user.birthdate|age }} <!-- Age: 30 years old -->

Want to see it used in a screencast 🎥? Check out SymfonyCasts: https://symfonycasts.com/screencast/symfony-doctrine/ago

The formatted date/duration can be translated into any language, and many are supported out of the box.

Installation

Use Composer to install the library:

composer require knplabs/knp-time-bundle

Woo! You did it! Assuming your project uses Symfony Flex, the bundle should be configured and ready to go. If not, you can enable Knp\Bundle\TimeBundle\KnpTimeBundle manually.

Usage

Twig

Time formatting:

{{ someDateTimeVariable|time_diff }} {# 2 weeks ago #}

{# |ago is an alias for |time_diff #}
{{ someDateTimeVariable|ago }} {# 1 second ago #}

{# ... or use the equivalent function: #}
{{ time_diff(someDateTimeVariable) }} {# in 2 months #}

Note: the time_diff filter/function and ago alias works fine for dates in the future, too.

Duration formatting:

{{ someDurationInSeconds|duration }} {# 2 minutes #}

Age formatting:

{# with filter: #}
Age: {{ user.birthdate|age }} {# Age: 30 years old #}

{# ... or use the equivalent function: #}
Age: {{ age(user.birthdate) }} {# Age: 30 years old #}

Service

You can also format dates and durations in your services/controllers by autowiring/injecting the Knp\Bundle\TimeBundle\DateTimeFormatter service:

use Knp\Bundle\TimeBundle\DateTimeFormatter;
// ...

public function yourAction(DateTimeFormatter $dateTimeFormatter)
{
    $someDate = new \DateTimeImmutable('-2 years'); // or $entity->publishedDate()
    $toDate = new \DateTimeImmutable('now');

    $agoTime = $dateTimeFormatter->formatDiff($someDate, $toDate); // $toDate parameter is optional and defaults to "now"

    $readTime = $dateTimeFormatter->formatDuration(64); // or $entity->readTimeInSeconds()

    $ageTime = $dateTimeFormatter->formatAge($someDate, $toDate); // $toDate parameter is optional and defaults to "now"

    return $this->json([
        //  ...
        'published_at' => $agoTime, // 2 years ago
        'read_time' => $readTime, // 1 minute
        // ...
    ]);
}

Controlling the Translation Locale

The bundle will automatically use the current locale when translating the "time_diff" ("ago") and "duration" messages. However, you can override the locale:

{{ someDateTimeVariable|time_diff(locale='es') }}

{{ someDurationInSeconds|duration(locale='es') }}

{{ someDateTimeVariable|age(locale='es') }}

Tests

If you want to run tests, please check that you have installed dev dependencies.

./vendor/bin/phpunit

Maintainers

Anyone can contribute to this repository (and it's warmly welcomed!). The following people maintain and can merge into this library:

• @akovalyov
• @weaverryan
• @NicolasNSSM