Documentation · ViewHelper reference

XSD schema file | vhs 1.8.3

Format / DateRangeViewHelper

Date range calculation/formatting ViewHelper

Uses DateTime and DateInterval operations to calculate a range between two DateTimes.


  • As formatter, the ViewHelper can output a string value such as "2013-04-30 - 2013-05-30" where you can configure both the start and end date (or their common) formats as well as the "glue" which binds the two dates together.
  • As interval calculator, the ViewHelper can be used with a special "intervalFormat" which is a string used in the constructor method for the DateInterval class - for example, "P3M" to add three months. Used this way, you can specify the start date (or rely on the default "now" DateTime) and specify the "intervalFormat" to add your desired duration to your starting date and use that as end date. Without the "return" attribute, this mode simply outputs the formatted dates with interval deciding the end date.
  • When used with the "return" attribute you can specify which type of data to return:
    • if "return" is "DateTime", a single DateTime instance is returned (which is the end date). Use this with a start date to return the DateTime corresponding to "intervalFormat" into the future/past.
    • if "return" is a string such as "w", "d", "h" etc. the corresponding counter value (weeks, days, hours etc.) is returned.
    • if "return" is an array of counter IDs, for example Array("w", "d"), the corresponding counters from the range are returned as an array.

Note about LLL support and array consumers

When used with the "return" attribute and when this attribute is an array, the output becomes suitable for consumption by f:translate, v:l or f:format.sprintf for example - as the "arguments" attribute:

<f:translate key="myDateDisplay"
    arguments="{v:format.dateRange(intervalFormat: 'P3W', return: {0: 'w', 1: 'd'})}"

Which if "myDateDisplay" is a string such as "Deadline: %d week(s) and %d day(s)" would output a result such as "Deadline: 4 week(s) and 2 day(s)".

Tip: the values returned by this ViewHelper in both array and single value return modes, are also nicely consumable by the "math" suite of ViewHelpers, for example v:math.division would be able to divide number of days by two, three etc. to further divide the date range.

  • Tag usage example

    <v:format.dateRange start="[mixed]" end="[mixed]" intervalFormat="NULL" format="'Y-m-d'" startFormat="NULL" endFormat="NULL" glue="'-'" spaceGlue="1" return="[mixed]">
    	<!-- tag content - may be ignored! -->
  • Inline usage example

    {v:format.dateRange(start: [mixed], end: [mixed], intervalFormat: 'NULL', format: ''Y-m-d'', startFormat: 'NULL', endFormat: 'NULL', glue: ''-'', spaceGlue: 1, return: [mixed])}


Argument Description Type

End date which can be a DateTime object or a string consumable by DateTime constructor


Date format to apply to end date


Date format to apply to both start and end date


Glue string to concatenate dates with


Interval format consumable by DateInterval


Return type; can be exactly "DateTime" to return a DateTime instance, a string like "w" or "d" to return weeks, days between the two dates - or an array of w, d, etc. strings to return the corresponding range count values as an array.


If TRUE glue string is surrounded with whitespace


Start date which can be a DateTime object or a string consumable by DateTime constructor


Date format to apply to start date

Required attribute

Revision history

commit b8c86d90ee4062d16081dbb250dbb9797fbbe947
Author: Björn Fromme <*****>
Date:   Sun May 26 08:27:38 2013 +0200

    [TASK] Refactor viewhelper
    These changes should reflect the discussion in #154

commit aa5bed67637a3350b4cabbb4fdc91b79b6b1048b
Author: Claus Due <*****>
Date:   Sun May 26 14:32:05 2013 +0200

    [TASK] Rename attribute "dateFormat" to "format" on Format / DateRange ViewHelper
    In addition, expand a chained variable assignment for better clarity.

commit b64b4f8787b60f49f159a97d768d01e54fc7dc82
Author: Claus Due <*****>
Date:   Sun May 26 14:50:17 2013 +0200

    [DOC] Add doc block for Format / DateRange ViewHelper

commit 7b740c0ee044e6de05b68bc39567c85aba956f99
Author: Björn Fromme <*****>
Date:   Sun May 26 15:02:48 2013 +0200

    [TASK] Correct package namespace

commit e6880caafaae3c899689bd9f927cbc5c29a0b66b
Author: Björn Fromme <*****>
Date:   Sun May 26 15:03:58 2013 +0200

    [TASK] Remove superfluous properties

commit db3cd7ddbffc430b6a108159cfc70dbe141e5410
Author: Claus Due <*****>
Date:   Fri Sep 13 03:08:34 2013 +0200

    [TASK] Improve test suite

commit da31bad1d9bb058c072ddb5591e8ed907a1ae8e1
Author: Claus Due <*****>
Date:   Tue Dec 31 23:08:37 2013 +0100

    [TASK] Happy new year!

commit d2e531da034976e6db1478eef5a8478595fd16fe
Author: Claus Due <*****>
Date:   Sun Jan 5 00:45:10 2014 +0100

    [TASK] Migrate to using namespace core class names

commit de77e3e35d7f87aeb1d38b305426ecca707e0028
Author: ste101 <stephan_*****>
Date:   Fri Apr 4 09:53:42 2014 +0200

    [BUGFIX] DateRange does not respect timezone

commit 52bd6e41ccfef3d8193b350153912a9716e6a087
Author: Benjamin Rau <*****>
Date:   Tue Apr 1 21:09:00 2014 +0200

    [TASK] CGL compliance

commit da7677bc74f14e9a9300e4ba4487e52c3cb97642
Author: Claus Due <*****>
Date:   Sun Apr 20 01:13:33 2014 +0200

    [TASK] Switch to namespaces

commit 8bb2fc5ee124ba19b0a0ab8e061c9a153fc4651f
Author: Xaver Maierhofer <*****>
Date:   Sun Jan 18 17:56:13 2015 +0100

    [TASK] Reference Copyright to file