Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc update for 2.0 #180

Merged
merged 1 commit into from
Jul 31, 2023
Merged

Doc update for 2.0 #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 48 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,20 @@
# Friendly *ago* dates ("5 minutes ago")!
# knplabs/knp-time-bundle

This bundle does one simple job: takes dates and gives you friendly "2 hours ago"-type messages. Woh!
Friendly *ago*/*until* dates ("5 minutes ago" or "in 5 minutes") and *durations* ("2 mins")!

```html+jinja
Last edited {{ post.updatedAt|ago }}
<-- Last edited 1 week ago -->
```twig
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 mins -->
```

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

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

## INSTALLATION
## Installation

Use Composer to install the library:

Expand All @@ -23,56 +26,75 @@ 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
## Usage

### Twig

In Twig:
Time formatting:

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

... or use the equivalent function:
{{ time_diff(someDateTimeVariable) }}
{# |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 "ago" filter works fine for dates in the future, too.
> **Note**: the `time_diff` filter/function and `ago` alias works fine for dates in the future, too.

### In controllers
Duration formatting:

You can also "ago" dates inside PHP by autowiring the `Knp\Bundle\TimeBundle\DateTimeFormatter` service:
```twig
{{ someDurationInSeconds|duration }} {# 2 mins #}
```

### 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 \DateTime('2017-02-11'); //or $entity->publishedDate()
$now = new \DateTime();

$agoTime = $dateTimeFormatter->formatDiff($someDate, $now);
$someDate = new \DateTimeImmutable('2017-02-11'); // 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()

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

## Controlling the Translation Locale

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

```twig
{{ someDateTimeVariable|ago(locale='es') }}
{{ someDateTimeVariable|time_diff(locale='es') }}

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

## TESTS
## Tests

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

```bash
./vendor/bin/simple-phpunit
./vendor/bin/phpunit
```

## Maintainers
Expand Down
6 changes: 3 additions & 3 deletions composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"name": "knplabs/knp-time-bundle",
"type": "symfony-bundle",
"description": "Making your dates look sensible and descriptive",
"keywords": ["time", "date", "descriptive time", "knplabs", "knp", "bundle"],
"description": "Making your dates and durations look sensible and descriptive",
"keywords": ["time", "date", "descriptive time", "knplabs", "knp", "bundle", "duration"],
"homepage": "https://github.com/KnpLabs/KnpTimeBundle",
"license": "MIT",

Expand Down Expand Up @@ -33,7 +33,7 @@
},

"suggest": {
"symfony/twig-bundle": "to use the Twig `time_diff()` function or `|time_diff` filter"
"symfony/twig-bundle": "to use the Twig `time_diff()` function and `|time_diff`/`|duration` filter"
},

"conflict": {
Expand Down