date_diff
The date_diff filter gets the difference between now (or a passed date) and the date value the filter is applied to. This is referred to as the "date interval". An example usage could be if you need to show a countdown to a date when a page reloads but you don't need it to be a real-time countdown powered by Javascript.
{{ myDate|date_diff }}
Date value
The date value and the optional date option can be just about any valid representation of a date. See the Date Input Formats page for more details.
For example:
{{ 'November 15, 2019 8:32pm'|date_diff({'date': '2020-1-22 22:42'}) }}
Return values
There are three types of returns values from the date_diff filter. They are configured in the options array as described below.
- The default formatted string showing the date interval.
- A custom formatted string showing the date interval.
- An object holding the interval values.
By default the date_diff filter will return a string showing a formatted interval value. For example, "1 month, 3 days, 15 hours, and 37 minutes". By using the options described below you can either pass your own custom format for the returned value, or you can get an object returned that holds the interval values so that you can format your own string.
Also note that if the date you're comparing to is in the past then the date interval will be negative.
Default formatted string
By default the date_diff filter will return a string showing a formatted interval value. For example, "1 month, 3 days, 15 hours, and 37 minutes".
When generating the default formatted string the filter will start at "year" and go down to "seconds". If the value is greater than zero or it's proceeding value is used, then it will be added to the string.
For example, if the date interval is less than a year then "years" will be 0 so the year value won't be used. If "months" is greater than 0 then it will be used. But then if "days" is 0 because the date interval is an exact month away then "0 days" will still be included because months were included.
If there is less than a minute between the dates then only seconds will be used.
Custom formatted string
You can pass your own format for the date interval value by using the format option as described below. Doing so will override the default format and only show the values that you specify.
For example, to only show the month and days you can do this:
{{ myDate|date_diff({'format': 'Only [month] and [day] until our event'}) }}
The filter will replace "[month]" with the month value (e.g. "3 months") and "[day]" with the day value (e.g. "10 days").
Or, you can return just the total number of days.
{{ myDate|date_diff({'format': 'Only [totalDays] until our event'}) }}
Something like "Only 42 days until our event" will be returned.
An object holding the interval values
If you need more control over how you are using the interval values then an object containing the individual date range interval values can be returned. You can then use your own logic to show the date interval.
Set the return value to "object" to do this.
{% set interval = myDate|date_diff({'return': 'object'}) %}
The available values in the returned object are:
- years - the number of years
- months - the number of months
- days - the number of days
- hours - the number of hours
- minutes - the number of minutes
- seconds - the number of seconds
- microseconds - the number of microseconds
- negative - a boolean value of whether or not the date interval is negative (in the past) or not
- totalDays - the total number of days between the dates
- sign - the positive "+" or negative "-" sign depending on if the date interval is with a future date or past date
- negativeSign - the negative sign "-" if the date interval is with a date in the past or blank if the date interval is with a future date
Below is an example usage. As you can see it's quite a bit of code, but, it gives you full control over your logic.
{% set diff = myDate|date_diff({'return': 'object'}) %}
{# Start building the interval string #}
{% set interval = '' %}
{# Years #}
{% if diff.years > 0 %}
{% set interval = diff.years ~ ' year' ~ (diff.years != 1 ? 's' : '') %}
{% endif %}
{# Months #}
{% if diff.years > 0 or diff.months > 0 %}
{% if interval|length > 0 %}
{% set interval = interval ~ ', ' %}
{% endif %}
{% set interval = interval ~ diff.months ~ ' month' ~ (diff.months != 1 ? 's' : '') %}
{% endif %}
{# Days #}
{% set hasDays = false %}
{% if diff.years > 0 or diff.months or diff.days > 0 %}
{% set hasDays = true %}
{% if interval|length > 0 %}
{% set interval = interval ~ ', ' %}
{% endif %}
{% set interval = interval ~ diff.days ~ ' day' ~ (diff.days != 1 ? 's' : '') %}
{% endif %}
{# Hours #}
{% set hasHours = false %}
{% if diff.years > 0 or diff.months or diff.days > 0 or diff.hours > 0 %}
{% set hasHours = true %}
{% if interval|length > 0 %}
{% set interval = interval ~ ', ' %}
{% endif %}
{% set interval = interval ~ diff.hours ~ ' hour' ~ (diff.hours != 1 ? 's' : '') %}
{% endif %}
{# Minutes #}
{% if diff.years > 0 or diff.months or diff.days > 0 or diff.hours > 0 or diff.minutes > 0 %}
{% if interval|length > 0 %}
{% set interval = interval ~ ', ' %}
{% endif %}
{% if hasDays and hasHours %}
{% set interval = interval ~ 'and ' %}
{% endif %}
{% set interval = interval ~ diff.minutes ~ ' minute' ~ (diff.minutes != 1 ? 's' : '') %}
{% endif %}
{# Include seconds if there is less than one minute until the end date #}
{% if diff.years == 0 and diff.months == 0 and diff.days == 0 and diff.hours == 0 and diff.minutes == 0 %}
{# Show seconds #}
{% set interval = diff.seconds ~ ' second' ~ (diff.seconds != 1 ? 's' : '') %}
{% endif %}
<p>{{ interval }} until our event</p>Arguments
The date_diff filter has the following signature.
date_diff(options)
| Argument | Description |
|---|---|
| options | An optional array of options to change the default behavior of of the date_diff filter. Example: {{ myDate|date_diff({'return': 'object'}) }} The options are listed below. |
| Option | Description |
|---|---|
| date | The custom date value to compare with the date that the filter is applied to. By default it is the current date/time. You can override this by passing a date option. Example: {{ myDate|date_diff({'date': '11/20/2020 10:00'}) }} The date and time passed will use the timezone that is configured with the website. The date option can be just about any valid representation of a date. See the Date Input Formats page for more details. {{ 'November 15, 2019 8:32pm'|date_diff({'date': '2020-1-22 22:42'}) }} {{ myDate|date_diff({'date': 'next Monday'}) }} |
| daySingular | The value to use for the "day" singular value. By default it is "day". {{ myDate|date_diff({'daySingular': 'día'}) }} |
| dayPlural | The value to use for the plural version of "day". By default it is "days". {{ myDate|date_diff({'daySingular': 'días'}) }} |
| format | The custom format used to build the date interval response. This will override the default interval format and is used when you need more control over which interval values to output. You use placeholders and those placeholders are replaced with the actual numeric interval value and it's date period string. Below are the possible placeholder values. [year] - The year value. For example: "2 years", "1 year" or "0 years". [month] - The month value. It will be between 0 and 11. For example: "0 months", "5 months", or "1 month". [day] - The day value. It will be between 0 and 31. For example: "15 days", "1 day", or "0 days". [hour] - The hour value. It will be between 0 and 12. For example: "11 hours", "1 hour", or "0 hours". [minute] - The minute value. It will be between 0 and 59. For example: "20 minutes", "1 minute", or "0 minutes". [second] - The second value. It will be between 0 and 59. For example: "15 seconds", "1 second", or "0 seconds". [sign] - The positive or negative sign. It will be "+" if the date the filter is applied to is in the future relative to the compared date. It will be "-" if the date the filter is applied to is in the past relative to the compared date. [negativeSign] - The negative sign "-" if the date the filter is applied to is in the past relative to the compared date. If the date is in the future then nothing will be set. [totalDays] - The total number of days between the events. The value will be greater than 0. For example: "3 days", "63 days", "1 day", or "0 days". Examples To only show the month and days you can do this: {{ myDate|date_diff({'format': 'Only [month] and [day] until our event'}) }} The filter will replace "[month]" with the month value (e.g. "3 months") and "[day]" with the day value (e.g. "10 days") in the above format to be something like "Only 3 months and 10 days until our event.". Or, you can return just the total number of days. {{ myDate|date_diff({'format': 'Only [totalDays] until our event'}) }} Something like "Only 42 days until our event" will be returned. |
| hourSingular | The value to use for the "hour" singular value. By default it is "hour". {{ myDate|date_diff({'hourSingular': 'hora'}) }} |
| hourPlural | The value to use for the "hour" plural value. By default it is "hours". {{ myDate|date_diff({'hourPlural': 'horas'}) }} |
| leadingZero | A boolean option that sets whether or not the numeric interval values should have a leading zero if it's less than 10. By default this is set to false. Example: {{ myDate|date_diff({'leadingZero': true}) }} |
| minuteSingular | The value to use for the "minute" singular value. By default it is "minute". {{ myDate|date_diff({'minuteSingular': 'minuto'}) }} |
| minutePlural | The value to use for the "minute" plural value. By default it is "minutes". {{ myDate|date_diff({'minutePlural': 'minutos'}) }} |
| monthSingular | The value to use for the "month" singular value. By default it is "month". {{ myDate|date_diff({'monthSingular': 'mes'}) }} |
| monthPlural | The value to use for the "month" plural value. By default it is "months". {{ myDate|date_diff({'monthPlural': 'meses'}) }} |
| return | The type of value to return. The values that can be returned are:
Available values for this option are: string - The default value. With this either the default formatted string or a custom formatted string will be returned, depending on the format value. object - This will cause the object holding the interval values to be returned. Example: {% set interval = myDate|date_diff({'return': 'object'}) %} |
| secondSingular | The value to use for the "second" singular value. By default it is "second". {{ myDate|date_diff({'secondSingular': 'segundo'}) }} |
| secondPlural | The value to use for the "second" plural value. By default it is "seconds". {{ myDate|date_diff({'secondPlural': 'segundos'}) }} |
| yearSingular | The value to use for the "year" singular value. By default it is "year". {{ myDate|date_diff({'yearSingular': 'año'}) }} |
| yearPlural | The value to use for the "year" plural value. By default it is "years". {{ myDate|date_diff({'yearPlural': 'años'}) }} |