cultuurnet/calendar-summary-v3

Library to convert cultuurnet dates to a readable summary

v4.1.1 2026-08-20 05:56 UTC

Requires

• php: ^7.4 || ^8.0
• ext-intl: *
• ext-json: *
• nesbot/carbon: ^2.63

Requires (Dev)

• phpstan/phpstan: ^1.8 || ^2.0
• phpunit/phpunit: ^9.5
• publiq/php-cs-fixer-config: ^2.0

Apache-2.0

• Publiq vzw

Published on Packagist.org on 2026-08-20 05:57 UTC

README

Installation

composer require cultuurnet/calendar-summary-v3

How it works

This library helps with formatting calendar information as HTML or plain text for events or places from Uitdatabank. We do this by parsing an Offer instance from JSONLD.

Types

The Offer object has a calendarType property which can have one of the four following options:

• single
• multiple
• periodic
• permanent

Parameters

There are 3 (optional) parameters which can be used on the initialisation of the formatters. Those are

• langCode
• hidePastDates
• timeZone

langCode

(string) Default value: 'nl_BE'. You can use this parameter to change the language of the output that the formatter will produce. Currently works in nl, fr, de and en. The format here is standard PHP locales. For example 'fr_BE' or 'de_BE'.

hidePastDates

(boolean) Default value: false. This parameter (when true) will only be used on offers with a calendarType 'multiple'. When true, dates in the past won't be in the formatter's output.

timeZone

(string) Default value: 'Europe/Brussels' You can set a different timezone with this parameter. Supported timezones can be found in this list.

Formats

After initializing the formatter, you call the format method with the following 2 parameters:

• Instance of the Offer object provided by this library
• The desired output format ('xs', 'sm', 'md', 'lg' or 'xl')

Using an unsupported format will throw an exception.

Only the periodic and permanent calendar types have an 'xl' output of their own: on top of the 'lg' output it lists the adjusted days and the closed days. For the single and multiple calendar types 'xl' is the same as 'lg'.

The large output mentions the childcare for every calendar type, and the overnight stay for the single and multiple ones, which are the only types that have one. For the periodic and permanent types it does not list the adjusted days, but it does warn that the hours can differ while they are going on.

Example

<?php

// Make sure to either deserialize the Event/Place from JSON, or set the necessary properties through setCalendarType() etc.
$offer = new \CultuurNet\CalendarSummaryV3\Offer\Offer::fromJsonLd('JSONLD_STRING');
    
// This will format the calendar info of `$offer` in a medium HTML output 
$calendarHTML = new \CultuurNet\CalendarSummaryV3\CalendarHTMLFormatter('nl_BE', true, 'Europe/Brussels');
$calendarHTML->format($offer, 'md');
    
// This will format the calendar info of `$offer` in a large plain text output
$calendarPlainText = new \CultuurNet\CalendarSummaryV3\CalendarPlainTextFormatter('fr_BE', true, 'Europe/Paris');
$calendarPlainText->format($offer, 'lg');