dolibarr 25.0.0-alpha
ICal Class Reference

Class to read/parse ICal calendars. More...

Public Member Functions

 __construct ()
 Constructor.
 
 read_file ($file)
 Read text file, icalender text file.
 
 convertToUtf8 ($text, $contenttype='')
 Convert a text to UTF-8.
 
 getTodoAndJournalAsEvents ()
 Return the to do (VTODO) and the journal entries (VJOURNAL) as events, so they can be shown in an agenda.
 
 get_event_count ()
 Returns the number of calendar events.
 
 get_todo_count ()
 Returns the number of to do.
 
 parse ($uri, $usecachefile='', $delaycache=3600)
 Translate Calendar.
 
 add_to_array ($type, $key, $value)
 Add to $this->ical array one value and key.
 
 retun_key_value ($text)
 Parse text "XXXX:value text some with : " and return array($key = "XXXX", $value="value");.
 
 ical_rrule ($value)
 Parse RRULE return array.
 
 isRRuleSupported ($rrule)
 Return if a recurrence rule can be expanded by expandRRule(): FREQ MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY or YEARLY with, as parts, BYDAY, BYMONTHDAY, BYMONTH, BYYEARDAY, BYWEEKNO, BYSETPOS, BYHOUR, BYMINUTE, BYSECOND, WKST (some of them only for some FREQ).
 
 expandRRule ($rrule, $dtstart, $to, $until=0, $from=0)
 Return the starts of the occurrences of a recurrence rule (see isRRuleSupported()), the first one being always DTSTART: RFC 5545 defines DTSTART as the first instance of the recurrence set, even if it does not match the rule (the event is then still shown at its start date, and it counts for COUNT).
 
 ical_duration_to_seconds ($duration)
 Return the number of seconds of an iCal duration (RFC 5545: P1W, P1D, PT1H30M, -PT15M, P1DT2H...)
 
 ical_date_to_unix ($ical_date, $floating=false, $timezone='')
 Return Unix time from ical date time format (YYYYMMDD[T]HHMMSS[Z] or YYYYMMDD[T]HHMMSS)
 
 getCalendarTimezone ()
 Return the time zone of the calendar, declared by the property X-WR-TIMEZONE (not standard but written by Google, Apple, Outlook...).
 
 getPhpTimezone ($tzid)
 Return the name of the PHP time zone that matches the TZID of a date.
 
 isTzidKnown ($tzid)
 Tell if the dates of a TZID can be converted by tzidToTimestamp(): name known by PHP, or time zone with rules declared in the file.
 
 tzidToTimestamp ($localtime, $tzid)
 Convert a local date and time of a time zone (TZID) into a real time, taking into account the daylight saving time of this date.
 
 ical_dt_date ($key, $value)
 Return unix date from iCal date format.
 
 hasStartDate ($event)
 Check whether a parsed calendar component has a usable start date.
 
 getKeyParams ($key)
 Return the parameters of a property key (for 'DTSTART;VALUE=DATE-TIME;TZID=Europe/Paris', array('VALUE' => 'DATE-TIME', 'TZID' => 'Europe/Paris')).
 
 get_sort_event_list ()
 Return sorted eventlist as array or false if calendar is empty.
 
 ical_dtstart_compare ($a, $b)
 Compare two unix timestamp.
 
 get_event_list ()
 Return eventlist array (not sorted eventlist array)
 
 get_freebusy_list ()
 Return freebusy array (not sort eventlist array)
 
 get_todo_list ()
 Return to do array (not sorted todo array)
 
 get_calender_data ()
 Return base calendar data.
 
 get_all_data ()
 Return array with all data.
 

Private Member Functions

 isIcalText ($text)
 Return if a text looks like an iCal file (it starts, after a BOM and blank lines, with BEGIN:VCALENDAR)
 
 parseByDay ($value)
 Decode a BYDAY value ("MO,TU", "2MO", "-1FR"...)
 
 getDaysOfMonth ($year, $month, $byday, $bymonthday, $defaultday)
 Return the days (midnight, as GMT timestamps) of a month that match BYDAY and BYMONTHDAY.
 
 getFirstWeekOfYear ($year, $wkst)
 Return the start (as GMT timestamp of the date and time written in the file) of the first week of a year.
 
 getWallStart ($event)
 Return the start of an event as GMT timestamp of the date and time written in the file.
 
 expandRRuleOccurrences ($rrule, $dtstart, $to, $until=0, $from=0)
 Return the starts of the occurrences of a recurrence rule (see isRRuleSupported()).
 
 getCalendarProperties ()
 Return the properties of the calendar itself (VCALENDAR: PRODID, X-WR-TIMEZONE...).
 
 getVtimezones ()
 Return the time zones (VTIMEZONE) declared in the file, by TZID.
 
 parseUtcOffset ($offset)
 Convert an offset of a time zone written by iCal ('+0100', '-053000') into seconds.
 
 getVtimezoneOffset ($localtime, $tzid)
 Return the offset from UTC (in seconds) of a local date and time of a time zone declared in the file (VTIMEZONE), from its rules.
 

Detailed Description

Class to read/parse ICal calendars.

Definition at line 37 of file ical.class.php.

Member Function Documentation

◆ add_to_array()

ICal::add_to_array ( $type,
$key,
$value )

Add to $this->ical array one value and key.

Parameters
string$typeType ('VTODO', 'VEVENT', 'VFREEBUSY', 'VCALENDAR'...)
string$keyKey ('DTSTART', ...). Note: Field is never 'DTSTART;TZID=...' because ';...' was before removed and added as another property
string$valueValue
Returns
void

Definition at line 542 of file ical.class.php.

References convertToUtf8(), getKeyParams(), ical_date_to_unix(), ical_dt_date(), ical_rrule(), and quotedPrintDecode().

Referenced by parse().

◆ convertToUtf8()

ICal::convertToUtf8 ( $text,
$contenttype = '' )

Convert a text to UTF-8.

A text that is already valid UTF-8 is returned unchanged. The source charset is, in this order: the BOM of a UTF-16 file, the charset of the Content-Type (or "charset=xxx"), Windows-1252 (a superset of ISO-8859-1, the most common encoding of old calendars).

Parameters
string$textText
string$contenttypeContent-Type of the HTTP answer (for example 'text/calendar; charset=ISO-8859-1') or 'charset=xxx'
Returns
string Text in UTF-8

Definition at line 144 of file ical.class.php.

Referenced by add_to_array(), and read_file().

◆ expandRRule()

ICal::expandRRule ( $rrule,
$dtstart,
$to,
$until = 0,
$from = 0 )

Return the starts of the occurrences of a recurrence rule (see isRRuleSupported()), the first one being always DTSTART: RFC 5545 defines DTSTART as the first instance of the recurrence set, even if it does not match the rule (the event is then still shown at its start date, and it counts for COUNT).

The dates are handled as dates written in the file (GMT timestamps of the local date and time), the caller converts them.

Parameters
array<string,string>$rrule Rule decoded by ical_rrule()
int$dtstartStart of the first occurrence
int$toOccurrences starting from this date are not returned
int$untilOccurrences starting after this date are not returned (0 = no limit)
int$fromDate from which the occurrences are needed: when the rule has no COUNT, the periods before are skipped
Returns
array<int,int> Start of the occurrences, in ascending order, from $dtstart

Definition at line 944 of file ical.class.php.

References expandRRuleOccurrences().

Referenced by getVtimezoneOffset(), and parse().

◆ expandRRuleOccurrences()

ICal::expandRRuleOccurrences ( $rrule,
$dtstart,
$to,
$until = 0,
$from = 0 )
private

Return the starts of the occurrences of a recurrence rule (see isRRuleSupported()).

The dates are handled as dates written in the file (GMT timestamps of the local date and time), the caller converts them.

Parameters
array<string,string>$rrule Rule decoded by ical_rrule()
int$dtstartStart of the first occurrence
int$toOccurrences starting from this date are not returned
int$untilOccurrences starting after this date are not returned (0 = no limit)
int$fromDate from which the occurrences are needed: when the rule has no COUNT, the periods before are skipped
Returns
array<int,int> Start of the occurrences, in ascending order, from $dtstart

Definition at line 969 of file ical.class.php.

References getDaysOfMonth(), getFirstWeekOfYear(), and parseByDay().

Referenced by expandRRule().

◆ get_all_data()

ICal::get_all_data ( )

Return array with all data.

Returns
array<string,array<'VEVENT'|'VFREEBUSY'|'VTODO',array<int,array<string,string>>>>|array<string,array<int,array<string,array<string,int>>>>|array<string,array<int,array<string,int>>>|array<string,array<int,array<string,string>>>

Definition at line 1612 of file ical.class.php.

◆ get_calender_data()

ICal::get_calender_data ( )

Return base calendar data.

Returns
array<int,array<string,string|array<int|string,string>>>

Definition at line 1600 of file ical.class.php.

◆ get_event_count()

ICal::get_event_count ( )

Returns the number of calendar events.

Returns
int

Definition at line 231 of file ical.class.php.

◆ get_event_list()

ICal::get_event_list ( )

Return eventlist array (not sorted eventlist array)

Returns
array<int,array<string,string|array<int|string,string>>>

Definition at line 1564 of file ical.class.php.

Referenced by get_sort_event_list(), and parse().

◆ get_freebusy_list()

ICal::get_freebusy_list ( )

Return freebusy array (not sort eventlist array)

Returns
array<int,array<string,string|array<int|string,string>>>

Definition at line 1576 of file ical.class.php.

◆ get_sort_event_list()

ICal::get_sort_event_list ( )

Return sorted eventlist as array or false if calendar is empty.

Returns
array<int,array<string,string|array<int|string,string>>>|false

Definition at line 1532 of file ical.class.php.

References get_event_list().

◆ get_todo_count()

ICal::get_todo_count ( )

Returns the number of to do.

Returns
int

Definition at line 243 of file ical.class.php.

◆ get_todo_list()

ICal::get_todo_list ( )

Return to do array (not sorted todo array)

Returns
array<int,array<string,string|array<int|string,string>>>

Definition at line 1588 of file ical.class.php.

◆ getCalendarProperties()

ICal::getCalendarProperties ( )
private

Return the properties of the calendar itself (VCALENDAR: PRODID, X-WR-TIMEZONE...).

Returns
array<string,mixed>

Definition at line 1220 of file ical.class.php.

Referenced by getCalendarTimezone().

◆ getCalendarTimezone()

ICal::getCalendarTimezone ( )

Return the time zone of the calendar, declared by the property X-WR-TIMEZONE (not standard but written by Google, Apple, Outlook...).

It is the time zone of the "floating" times (date and time with no Z and no TZID) of the file.

Returns
string Name of the time zone (for example 'Europe/Paris'), or '' if there is none or if it is not a valid time zone

Definition at line 1231 of file ical.class.php.

References getCalendarProperties().

Referenced by ical_dt_date().

◆ getDaysOfMonth()

ICal::getDaysOfMonth ( $year,
$month,
$byday,
$bymonthday,
$defaultday )
private

Return the days (midnight, as GMT timestamps) of a month that match BYDAY and BYMONTHDAY.

Parameters
int$yearYear
int$monthMonth (1-12)
array<int,array{0:int,1:int}>$byday Decoded BYDAY
array<int,int>$bymonthday BYMONTHDAY (negative values count from the end of the month)
int$defaultdayDay to use when there is no BYDAY and no BYMONTHDAY (day of the start)
Returns
array<int,int> Timestamps of the days, sorted

Definition at line 847 of file ical.class.php.

Referenced by expandRRuleOccurrences().

◆ getFirstWeekOfYear()

ICal::getFirstWeekOfYear ( $year,
$wkst )
private

Return the start (as GMT timestamp of the date and time written in the file) of the first week of a year.

Parameters
int$yearYear
int$wkstFirst day of the week (0=Sunday...6=Saturday)
Returns
int Timestamp of the first day of the week number 1 (the first week with at least 4 days in the year)

Definition at line 900 of file ical.class.php.

Referenced by expandRRuleOccurrences().

◆ getKeyParams()

ICal::getKeyParams ( $key)

Return the parameters of a property key (for 'DTSTART;VALUE=DATE-TIME;TZID=Europe/Paris', array('VALUE' => 'DATE-TIME', 'TZID' => 'Europe/Paris')).

Parameters
string$keyKey of the property, with its parameters
Returns
array<string,string> Parameters (names in upper case)

Definition at line 1512 of file ical.class.php.

Referenced by add_to_array(), and ical_dt_date().

◆ getPhpTimezone()

ICal::getPhpTimezone ( $tzid)

Return the name of the PHP time zone that matches the TZID of a date.

The TZID can be a name of the IANA database ('Europe/Paris'), written in any case, or a Windows name written by Outlook ('Romance Standard Time').

Parameters
string$tzidTZID of a date
Returns
string Name of a time zone known by PHP, or '' if the TZID is not known

Definition at line 1248 of file ical.class.php.

References getVtimezones().

Referenced by isTzidKnown(), and tzidToTimestamp().

◆ getTodoAndJournalAsEvents()

ICal::getTodoAndJournalAsEvents ( )

Return the to do (VTODO) and the journal entries (VJOURNAL) as events, so they can be shown in an agenda.

A to do is an event from its DTSTART (or its due date) to its due date, a journal entry is an event on its date. A to do or journal entry without date, or cancelled, is not returned. The title starts with a symbol (to do, done, journal).

Returns
array<int,array<string,string|int|array<string,int|string>>>

Definition at line 184 of file ical.class.php.

◆ getVtimezoneOffset()

ICal::getVtimezoneOffset ( $localtime,
$tzid )
private

Return the offset from UTC (in seconds) of a local date and time of a time zone declared in the file (VTIMEZONE), from its rules.

Parameters
int$localtimeLocal date and time written as GMT timestamp
string$tzidTZID of the date
Returns
int|null Offset in seconds, or null if the file has no usable rules for this TZID

Definition at line 1381 of file ical.class.php.

References expandRRule(), and getVtimezones().

Referenced by tzidToTimestamp().

◆ getVtimezones()

ICal::getVtimezones ( )
private

Return the time zones (VTIMEZONE) declared in the file, by TZID.

For each one: the name of the PHP time zone given by X-LIC-LOCATION ('' if none or unknown by PHP), and the changes of offset of its STANDARD and DAYLIGHT parts (start as written in the file, offsets before and after in seconds, recurrence rule, RDATE).

Returns
array<string,array{location:string,changes:array<int,array{start:int,before:int,after:int,rrule:array<string,string>,rdates:array<int,int>}>}>

Definition at line 1290 of file ical.class.php.

References ical_rrule(), isRRuleSupported(), and parseUtcOffset().

Referenced by getPhpTimezone(), getVtimezoneOffset(), and isTzidKnown().

◆ getWallStart()

ICal::getWallStart ( $event)
private

Return the start of an event as GMT timestamp of the date and time written in the file.

Parameters
array<string,mixed>$event Event
Returns
int|null Timestamp, or null if the event has no start

Definition at line 917 of file ical.class.php.

Referenced by parse().

◆ hasStartDate()

ICal::hasStartDate ( $event)

Check whether a parsed calendar component has a usable start date.

Parameters
array<string,mixed>$event Parsed calendar component
Returns
bool

Definition at line 1489 of file ical.class.php.

◆ ical_date_to_unix()

ICal::ical_date_to_unix ( $ical_date,
$floating = false,
$timezone = '' )

Return Unix time from ical date time format (YYYYMMDD[T]HHMMSS[Z] or YYYYMMDD[T]HHMMSS)

Parameters
string$ical_dateString date
bool$floatingTrue if the date is a "floating" time (no Z and no TZID), so a local time and not a GMT time
string$timezoneTime zone of a floating time (the one of the calendar). If empty, the time zone of the user is used.
Returns
int

Definition at line 1197 of file ical.class.php.

References dol_mktime().

Referenced by add_to_array(), and ical_dt_date().

◆ ical_dt_date()

ICal::ical_dt_date ( $key,
$value )

Return unix date from iCal date format.

Parameters
string$keyKey. Example: 'DTSTART', 'DTSTART;TZID=US-Eastern'
string$valueValue. Example: '19970714T133000', '19970714T173000Z', '19970714T133000'
Returns
array{0:string,1:int}|array{0:string,1:array<string,int|string>}

Definition at line 1459 of file ical.class.php.

References getCalendarTimezone(), getKeyParams(), and ical_date_to_unix().

Referenced by add_to_array().

◆ ical_dtstart_compare()

ICal::ical_dtstart_compare ( $a,
$b )

Compare two unix timestamp.

Parameters
array{DTSTART:array{unixtime:string}}$a Operand a
array{DTSTART:array{unixtime:string}}$b Operand b
Returns
int

Definition at line 1552 of file ical.class.php.

◆ ical_duration_to_seconds()

ICal::ical_duration_to_seconds ( $duration)

Return the number of seconds of an iCal duration (RFC 5545: P1W, P1D, PT1H30M, -PT15M, P1DT2H...)

Parameters
string$durationDuration
Returns
int|null Number of seconds, or null if the value is not a valid duration

Definition at line 1177 of file ical.class.php.

Referenced by parse().

◆ ical_rrule()

ICal::ical_rrule ( $value)

Parse RRULE return array.

Parameters
string$valuestring
Returns
array<string,string>

Definition at line 723 of file ical.class.php.

Referenced by add_to_array(), and getVtimezones().

◆ isIcalText()

ICal::isIcalText ( $text)
private

Return if a text looks like an iCal file (it starts, after a BOM and blank lines, with BEGIN:VCALENDAR)

Parameters
string$textText
Returns
bool True if it looks like an iCal file

Definition at line 255 of file ical.class.php.

Referenced by parse().

◆ isRRuleSupported()

ICal::isRRuleSupported ( $rrule)

Return if a recurrence rule can be expanded by expandRRule(): FREQ MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY or YEARLY with, as parts, BYDAY, BYMONTHDAY, BYMONTH, BYYEARDAY, BYWEEKNO, BYSETPOS, BYHOUR, BYMINUTE, BYSECOND, WKST (some of them only for some FREQ).

Parameters
array<string,string>$rrule Rule decoded by ical_rrule()
Returns
bool True if the rule can be expanded

Definition at line 768 of file ical.class.php.

References parseByDay().

Referenced by getVtimezones(), and parse().

◆ isTzidKnown()

ICal::isTzidKnown ( $tzid)

Tell if the dates of a TZID can be converted by tzidToTimestamp(): name known by PHP, or time zone with rules declared in the file.

Parameters
string$tzidTZID of a date
Returns
bool True if the TZID is known

Definition at line 1424 of file ical.class.php.

References getPhpTimezone(), and getVtimezones().

◆ parse()

ICal::parse ( $uri,
$usecachefile = '',
$delaycache = 3600 )

Translate Calendar.

Parameters
string$uriUrl
string$usecachefileFull path of a cache file to use a cache file
int$delaycacheDelay in seconds for cache (by default 3600 secondes)
Returns
string|array<string,array<'VEVENT'|'VFREEBUSY'|'VTODO',array<int,array<string,string>>>>|array<string,array<int,array<string,array<string,int>>>>|array<string,array<int,array<string,int>>>|array<string,array<int,array<string,string>>>

Definition at line 268 of file ical.class.php.

References add_to_array(), dol_delete_file(), dol_filemtime(), dol_now(), dol_string_nohtmltag(), dolChmod(), expandRRule(), get_event_list(), getWallStart(), ical_duration_to_seconds(), isIcalText(), isRRuleSupported(), quotedPrintDecode(), read_file(), and retun_key_value().

◆ parseByDay()

ICal::parseByDay ( $value)
private

Decode a BYDAY value ("MO,TU", "2MO", "-1FR"...)

Parameters
string$valueValue of BYDAY
Returns
array<int,array{0:int,1:int}>|null List of array(ordinal (0 if none), day of week (0=Sunday...6=Saturday)), or null if the value is not valid

Definition at line 743 of file ical.class.php.

Referenced by expandRRuleOccurrences(), and isRRuleSupported().

◆ parseUtcOffset()

ICal::parseUtcOffset ( $offset)
private

Convert an offset of a time zone written by iCal ('+0100', '-053000') into seconds.

Parameters
string$offsetOffset
Returns
int|null Offset in seconds, or null if it is not valid

Definition at line 1366 of file ical.class.php.

Referenced by getVtimezones().

◆ read_file()

ICal::read_file ( $file)

Read text file, icalender text file.

Parameters
string$fileFile
Returns
string|null Content of remote file read or null if error

Definition at line 104 of file ical.class.php.

References convertToUtf8(), dol_string_nohtmltag(), dol_trunc(), getDolGlobalString(), and getURLContent().

Referenced by parse().

◆ retun_key_value()

ICal::retun_key_value ( $text)

Parse text "XXXX:value text some with : " and return array($key = "XXXX", $value="value");.

Parameters
string$textText
Returns
array{0:string,1:string}

Definition at line 698 of file ical.class.php.

Referenced by parse().

◆ tzidToTimestamp()

ICal::tzidToTimestamp ( $localtime,
$tzid )

Convert a local date and time of a time zone (TZID) into a real time, taking into account the daylight saving time of this date.

Parameters
int$localtimeLocal date and time written as GMT timestamp (how ical_dt_date() returns a date with a TZID)
string$tzidTZID of the date
Returns
int|null Real timestamp, or null if the TZID is not known

Definition at line 1440 of file ical.class.php.

References dol_mktime(), getPhpTimezone(), and getVtimezoneOffset().


The documentation for this class was generated from the following file: