KnpTimeBundle 使用与技术文档

1. 安装指南

要使用 KnpTimeBundle，首先需要通过 Composer 安装库：

composer require knplabs/knp-time-bundle

如果您的项目使用 Symfony Flex，安装后 Bundle 会自动配置并可以使用。如果不是，则需要手动启用 Knp\Bundle\TimeBundle\KnpTimeBundle。

2. 项目使用说明

Twig 模板使用

时间格式化：

{{ someDateTimeVariable|time_diff }} {# 例如：2周前 #}

{# |ago 是 |time_diff 的别名 #}
{{ someDateTimeVariable|ago }} {# 例如：1秒前 #}

{# ... 或者使用等效的函数： #}
{{ time_diff(someDateTimeVariable) }} {# 例如：2个月后 #}

注意：time_diff 过滤器/函数和 ago 别名同样适用于未来日期。

持续时间格式化：

{{ someDurationInSeconds|duration }} {# 例如：2分钟 #}

年龄格式化：

{# 使用过滤器： #}
年龄：{{ user.birthdate|age }} {# 例如：30岁 #}

{# ... 或者使用等效的函数： #}
年龄：{{ age(user.birthdate) }} {# 例如：30岁 #}

服务中使用

您还可以在服务/控制器中通过自动装配/注入 Knp\Bundle\TimeBundle\DateTimeFormatter 服务来格式化日期和持续时间：

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

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

    $agoTime = $dateTimeFormatter->formatDiff($someDate, $toDate); // `$toDate` 参数是可选的，默认为 "now"

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

    $ageTime = $dateTimeFormatter->formatAge($someDate, $toDate); // `$toDate` 参数是可选的，默认为 "now"

    return $this->json([
        // ...
        'published_at' => $agoTime, // 2年前
        'read_time' => $readTime, // 1分钟
        // ...
    ]);
}

3. 项目API使用文档

KnpTimeBundle 提供了以下 Twig 过滤器和函数：

• time_diff：计算两个日期之间的差异，并返回友好格式。
• ago：time_diff 的别名，用于显示 "多久之前" 的格式。
• duration：将秒数转换为友好格式的持续时间。
• age：计算年龄。

此外，在服务中可以使用 DateTimeFormatter 类的方法：

• formatDiff：格式化两个日期之间的差异。
• formatDuration：格式化持续时间。
• formatAge：格式化年龄。

4. 项目安装方式

如上所述，通过 Composer 安装 KnpTimeBundle：

composer require knplabs/knp-time-bundle

确保项目已安装所有必要的依赖项，并根据需要配置 Twig 环境以使用新的过滤器和服务。