iCalcreator v2.28.2

iCalcreator v2.28.2
Copyright © 2007-2019 Kjell-Inge Gustafsson, kigkonsult, All rights reserved.
Copyright_and_Licence
kigkonsult.se
Contact iCal_at_kigkonsult_dot_se

Preface

This document describes usage of iCalcreator, the PHP software implementation of standards rfc5545/ rfc5546 (rfc2445/rfc2446) to manage calendar information.

This document is provided by kigkonsult for informational purposes and is provided on an "as is" basis without any warranties expressed or implied.

Information in this document is subject to change without notice and does not represent a commitment on the part of kigkonsult. The software described in this document is provided under a license agreement. The software may be used only in accordance with the terms of that license agreement. It is against the law to copy or use the software except as specifically allowed in the license agreement.

It is the users responsibility to ensure the suitability of the software before using it. In no circumstances will kigkonsult be responsible for the use of the software's outcomes or results or any loss or damage of data or programs as a result of using the software.

The use of the software implies acceptance of these terms and the license.

This document makes previous versions obsolete.

[index]

1 INTRO

iCalcreator is the PHP class package managing iCal calendar information, supporting (non-)calendar systems and applications to process and communicate calendar information like events, agendas, tasks, reports, totos and journaling information.

The iCal standards are rfc5545/rfc5546 (rfc2445/rfc2446).

iCalcreator features create, parse, edit and select calendar and calendar components.

For iCalcreator 2.28.2 version (and later), PHP version >= 5.6 is required.


[index] [top]

1.1 Standards

iCal

A short iCal description is found at Wikipedia. If You are not familiar with iCal, read this first!

The iCalendar format, iCal, are described in

rfc5545
"Internet Calendaring and Scheduling Core Object Specification (iCalendar)"
rfc5546
"iCalendar Transport-Independent Interoperability Protocol (iTIP)"
Scheduling Events, BusyTime, To-dos and Journal Entries

. ..allows for the capture and exchange of information normally stored within a calendaring and scheduling application.

and

. ..is an exchange format between applications or systems.

rfc5545 and rfc5546 obsoletes, respectively, rfc2445 and rfc2446.

Any references to rfc2445, below, corresponds to rfc5545.

xCal

iCalcreator also supports xCal (iCal xml), rfc6321, The XML Format for iCalendar.

A short xCal description is found at Wikipedia.


[index] [top]

1.2 This manual

This style is used for text.

This style is used for formats.

This style is used for PHP coding examples. // this style is used for coding comments.

This style is used for content details.

This style is used for RFC2445/5545 quotes.


[index] [top]

1.3 Versioning

The release numbering convention used is major.minor(.micro / suffix).

Major
Indicates a very large change in the core package. Rewrites or major milestones.
Minor
Significant amount of feature addition/modification.
odd number - development/experimental release
even number - production release
Micro
Primarily bug fix and maintenance number.
Suffix (opt)
rc1 for first release candidate etc.

The release plan is based on yearly releases with exception of emergency releases.


[index] [top]

1.4 Support

For support report, use github issues.

For non emergency issues, support upon (paid) request only.

kigkonsult offer professional services for software support, design and new/re-development and unit tests of PHP/MySQL solutions with focus on software lifecycle management, including long term utility, reliability and maintainability.


[index] [top]

1.5 Donate

You can show your appreciation for our free software, and can support future development by making a donation to the kigkonsult project iCalcreator.

Make a donation of any size by clicking here. Thanks in advance!


[index] [top]

1.6 Install

Composer (https://getcomposer.org/)
 
composer require kigkonsult/icalcreator
 
Or
include the (download) iCalcreator folder to your include-path
Add
require_once "[path/]iCalcreator-2.28.2/autoload.php";
to your PHP-script.

iCalcreator 2.28.2 is using namespace "Kigkonsult\Icalcreator".


[index] [top]

1.7 Major changes

Here are updates in this version.

2.27.1
Deprecated Vcalendar/::deleteProperty/getProperty()/setProperty methods,
replaced by property delete-/get-/set-methods
2.27.2
Exception error management
2.27.3
Method chaining, ex. set-, parse and sort-methods
2.27.4
Final-izing Vcalendar, Vevent etc
2.27.5
Alter config keys to constants, removed config TZID
2.27.6
Refine class hierarchy etc
2.27.7
TimezoneHandler::createTimezone return Vcalendar instance
2.27.8
Renamed/reworked Util classes
2.27.9
TimezoneHandler::createTimezone arg timezone no longer required
(fetched from X_WR_TIMEZONE, if set, otherwise UTC)
input args from/to accepts DateTime
2.27.10
Misc, changed all date property set-methods first arg name etc
2.27.11
static property name variables replaced by constants in IcalInterface
Property parameter Ical keys (and some values) constants in IcalInterface
2.27.12
The value type of the "DTEND" or "DUE" properties will now match the value type of "DTSTART" property.
2.27.13
Recur UNTIL, the value of the UNTIL rule part will now have the same value type as the "DTSTART" property.
2.27.14
PHPUnit testcases and derived (date) rewrites
2.27.15
Timezonhandler::createTimezone method moved to Vtimezone::populate, Timezonehandler removal
2.27.16
Major improved performance for Vcalendar::selectComponents() (i.e RecurFactory) on more simple recurs patterns
2.27.17
bug - also HTAB "\t" can be used as line separator (StringFactory::concatRows/convEolChar)
2.27.18
bugs - SelectFactory::selectComponents args calendar, cType reviewing
2.27.19
bug - typo in DateTimeFactory::dateTimeHasOffset
2.27.20
bug - Break/Continue mixup in RecurFactory::recurWeeklySimple2: split up tests, minor code clean up
2.27.21
bug - Break/Continue mixup in Vcalendar.php
2.27.22
CalendarComponent::parse() rewrite

Note, date/duration array set-property methods arguments are objects for removal in next version as well as date/duration arrays returned from property get-methods, replaced by DateTime/DateInterval


[index] [top]

1.8 Release plan

A brief release plan for 2.30, changable...
Bugs are fixed as soon as possible upon priority or severity.

v2.29.1
Removal of all set-methods date(time)/interval array arguments as well as get-methods return date(time)/interval array formats DTSTART, DTEND, DUE, RECURRENCE_ID,
CREATED, COMPLETED, DTSTAMP, LAST_MODIFIED
v2.29.2
Removal of all set-methods DateInterval array arguments as well as get-methods return array formats, now DateInterval
REFRESH_INTERVAL, DURATION, TRIGGER
RDATE, EXDATE
FREEBUSY, RRULE, EXRULE
v2.29.3
Rewrite Vcalendar::parse()
only input string allowed, removing internal iCal file/url parse method
v2.29.4
Removing deprecated methods



v2.29.5
Implement rfc7968, new properties, COLOR, IMAGE etc
replace rfc5545 (date+unique_id) UID by rfc7986 guid UID
v2.29.6
alter RRULE/EXRULE to single occurence
v2.29.7
Allow iana-token (Other IANA-registered type) property PARAMETER names
For ACTION and CLASS, iana-token / x-name VALUES are allowed
However, IANA Properties are not supported
v2.28.8
Vcalendar::sort() order adjustment

[index] [top]

1.9 Additional descriptors

Some properties (ex. as described in wikipedia:iCal) may be required when importing iCal formatted data into some calendaring software (MS etc). Also X-properties may appear in exports. Below are examples

on calendar level
METHOD property (value PUBLISH etc.)
X-WR-CALNAME x-property
X-WR-CALDESC x-property
X-WR-RELCALID x-property (Read more info about UUID.)
X-WR-TIMEZONE x-property
on component level
DTSTAMP *
UID *
on component level in a vtimezone component
X-LIC-LOCATION x-property

* Created automatically in iCalcreator, if not set.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::METHOD,
- Kigkonsult\Icalcreator\Vcalendar::X_WR_CALNAME,
- Kigkonsult\Icalcreator\Vcalendar::X_WR_CALDESC,
- Kigkonsult\Icalcreator\Vcalendar::X_WR_RELCALID,
- Kigkonsult\Icalcreator\Vcalendar::X_WR_TIMEZONE,
- Kigkonsult\Icalcreator\Vcalendar::X_LIC_LOCATION
are available.

Example

A strong recommendation is also to set config unique_id when creating a new Vcalendar/component instance, to ensure accurate setting of all components UID property, also before parse. Also setting "X-WR-TIMEZONE" (below) is to recommend.

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vcalendar->setMethod( "PUBLISH" ) ->setXprop( Vcalendar::X_WR_CALNAME, "Calendar Sample" ) ->setXprop( Vcalendar::X_WR_CALDESC, "Calendar Description" ) ->setXProp( Vcalendar::X_WR_RELCALID, "3E26604A-50F4-4449-8B3E-E4F4932D05B5" ) ->setXprop( Vcalendar::X_WR_TIMEZONE, "Europe/Stockholm" );


[index] [top]

1.10 INDEX

1 INTRO

1.1 Standards
1.2 This manual
1.3 Versioning
1.4 Support
1.5 Donate
1.6 Install
1.7 Major changes
1.8 Release plan
1.9 Additional descriptors
1.10 INDEX

2 Calendar Component list

2.1 VCALENDAR
2.2 VEVENT
2.3 VTODO
2.4 VJOURNAL
2.5 VFREEBUSY
2.6 VALARM
2.7 VTIMEZONE
2.8 Component Properties

3 Function list

3.1 Vcalendar methods

3.1.1 Constructors
3.1.1.1 Vcalendar
3.1.1.2 Vevent
3.1.1.3 Vtodo
3.1.1.4 Vjournal
3.1.1.5 Vfreebusy
3.1.1.6 Valarm
3.1.1.7 Vtimezone
3.1.1.7.1 populate
3.1.1.8 Standard / Daylight

3.1.2 Vcalendar property methods
3.1.2.1 deleteProperty
3.1.2.2 getProperty
3.1.2.3 setProperty
3.1.2.4 CALSCALE
3.1.2.5 METHOD
3.1.2.6 VERSION
3.1.2.7 X-PROPERTY

3.1.3 Vcalendar component object methods
3.1.3.1 deleteComponent
3.1.3.2 getComponent
3.1.3.3 newComponent
3.1.3.4 replaceComponent
3.1.3.5 selectComponents
3.1.3.6 setComponent

3.1.4 Vcalendar calendar methods
3.1.4.1 parse and merge
3.1.4.2 createCalendar
3.1.4.3 returnCalendar
3.1.4.4 saveCalendar
3.1.4.5 sort
3.1.4.6 useCachedCalendar
3.1.4.7 iCalcreatorVersion
3.1.4.8 vtimezonePopulate

3.1.5 Vcalendar configuration
3.1.5.1 configuration keys
3.1.5.2 getConfig
3.1.5.3 calendar/component initialization
3.1.5.4 setConfig
3.1.5.5 Allow empty components
3.1.5.6 Component information
3.1.5.7 Delimiter
3.1.5.8 Directory
3.1.5.9 Dirfile
3.1.5.10 Fileinfo
3.1.5.11 Filename
3.1.5.12 Filesize
3.1.5.13 Language
3.1.5.14 setPropertyNames
3.1.5.15 Unique_id
3.1.5.16 URL

3.2 Component property methods
3.2.1 deleteProperty
3.2.2 getProperty
3.2.3 parse
3.2.4 setProperty
Ascending property order
3.2.5 ACTION
3.2.6 ATTACH
3.2.7 ATTENDEE
3.2.8 CATEGORIES
3.2.9 CLASS
3.2.10 COMMENT
3.2.11 COMPLETED
3.2.12 CONTACT
3.2.13 CREATED
3.2.14 DESCRIPTION
3.2.15 DTEND
3.2.16 DTSTAMP
3.2.17 DTSTART
3.2.18 DUE
3.2.19 DURATION
3.2.20 EXDATE
3.2.21 EXRULE
3.2.22 FREEBUSY
3.2.23 GEO
3.2.24 LAST-MODIFIED
3.2.25 LOCATION
3.2.26 ORGANIZER
3.2.27 PERCENT-COMPLETE
3.2.28 PRIORITY
3.2.29 RDATE
3.2.30 RECURRENCE-ID
3.2.31 RELATED-TO
3.2.32 REPEAT
3.2.33 REQUEST-STATUS
3.2.34 RESOURCES
3.2.35 RRULE
3.2.36 SEQUENCE
3.2.37 STATUS
3.2.38 SUMMARY
3.2.39 TRANSP
3.2.40 TRIGGER
3.2.41 TZID
3.2.42 TZNAME
3.2.43 TZOFFSETFROM
3.2.44 TZOFFSETTO
3.2.45 TZURL
3.2.46 UID
3.2.47 URL
3.2.48 X-PROPERTY
Descriptive Component Properties
3.2.6 ATTACH
3.2.8 CATEGORIES
3.2.10 COMMENT
3.2.14 DESCRIPTION
3.2.23 GEO
3.2.25 LOCATION
3.2.27 PERCENT-COMPLETE
3.2.28 PRIORITY
3.2.34 RESOURCES
3.2.37 STATUS
3.2.38 SUMMARY
Date and Time Component Properties
3.2.11 COMPLETED
3.2.15 DTEND
3.2.18 DUE
3.2.17 DTSTART
3.2.19 DURATION
3.2.22 FREEBUSY
3.2.39 TRANSP
Time Zone Component Properties
3.2.41 TZID
3.2.42 TZNAME
3.2.43 TZOFFSETFROM
3.2.44 TZOFFSETTO
3.2.45 TZURL
Relationship Component Properties
3.2.7 ATTENDEE
3.2.12 CONTACT
3.2.26 ORGANIZER
3.2.30 RECURRENCE-ID
3.2.31 RELATED-TO
3.2.47 URL
3.2.46 UID
Recurrence Component Properties
3.2.20 EXDATE
3.2.29 RDATE
3.2.35 RRULE
Alarm Component Properties
3.2.5 ACTION
3.2.32 REPEAT
3.2.40 TRIGGER
Change Management Component Properties
3.2.13 CREATED
3.2.16 DTSTAMP
3.2.24 LAST-MODIFIED
3.2.36 SEQUENCE
Miscellaneous Component Properties
3.2.48 X-PROPERTY
3.2.33 REQUEST-STATUS
3.3 iCalcreator Component configuration methods
3.3.1 Language

3.4 iCalcreator component object misc. methods
3.4.1 deleteComponent
3.4.2 getComponent
3.4.3 newComponent
3.4.4 setComponent

4 Timezone, XML, json and vCard support
4.1 iCalcreator and timezoneHandler class
4.2 Timezone helper functions
4.2.1 getTzOffsetForDate
4.2.2 getTimezonesAsDateArrays
4.3 iCalcreator and iCalXMLFactory class
4.3.1 iCal2XML
4.3.2 XML2iCal
4.4 iCalcreator and json export
4.5 iCalcreator and iCalvCardFactory class
4.5.1 iCal2vCard
4.5.2 iCal2vCards

5 COPYRIGHT AND LICENSE

[index] [top]

2 Calendar Component list

Note, to ease up usage, you will find convenient constants for component names, properties, config keys etc in (src/)IcalInterface.

Quote from RFC2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar)!

2.1 VCALENDAR

icalobject = 1*("BEGIN" ":" "VCALENDAR" CRLF

icalbody

"END" ":" "VCALENDAR" CRLF)

icalbody = calprops component

calprops = 2*(

"prodid" and "version" are both REQUIRED, but MUST NOT occur more than once

prodid / version /

"calscale"and "method"are optional, but MUST NOT occur more than once

calscale / method /

x-prop

)

component = 1*(eventc / todoc / journalc / freebusyc / timezonec / iana-comp* / x-comp*)

iana-comp = "BEGIN" ":" iana-token CRLF

1*contentline

"END" ":" iana-token CRLF

x-comp = "BEGIN" ":" x-name CRLF

1*contentline

"END" ":" x-name CRLF

*) not supported by iCalcreator

[index] [top] [up]

2.2 VEVENT

"BEGIN" ":" "VEVENT" CRLF

eventprop *alarmc

"END" ":" "VEVENT" CRLF

eventprop = *(

The following are REQUIRED, but MUST NOT occur more than once.

dtstamp / uid

The following is REQUIRED
if the component appears in an iCalendar object
that doesn'tspecify the "METHOD" property;
otherwise, it is OPTIONAL; in any case, it MUST NOT occur more than once.

dtstart

The following are optional, but MUST NOT occur more than once

class / created / description / geo

/ last-mod / location / organizer / priority /

/ seq / status / summary / transp /

url / recurid /

The following is OPTIONAL, but SHOULD NOT occur more than once (impl. as single).

rrule / exrule (deprecated in rfc5545)

Either 'dtend' or 'duration' MAY appear in a 'eventprop',
but 'dtend' and 'duration' MUST NOT occur in the same 'eventprop'.

dtend / duration

The following are optional, and MAY occur more than once

attach / attendee / categories / comment /

contact / exdate / rstatus /

related / resources / rdate / x-prop

)

[index] [top] [up]

2.3 VTODO

"BEGIN" ":" "VTODO" CRLF

todoprop *alarmc

"END" ":" "VTODO" CRLF

todoprop = *(

The following are REQUIRED, but MUST NOT occur more than once.

dtstamp / uid

The following are optional, but MUST NOT occur more than once

class / completed / created / description / dtstamp /

dtstart / geo / last-mod / location / organizer /

percent / priority / recurid / seq / status /

summary /uid / url

The following is OPTIONAL, but SHOULD NOT occur more than once (impl. as single).

rrule / exrule (deprecated in rfc5545)

Either "due" or "duration" MAY appear in a 'todoprop', but "due" and "duration"
MUST NOT occur in the same 'todoprop'.
If 'duration' appear in a 'todoprop',
then "dtstart" MUST also appear in the same 'todoprop'.

due / duration /

The following are optional,and MAY occur more than once

attach / attendee / categories / comment /

contact / exdate / rstatus /

related / resources / rdate / x-prop

)

[index] [top] [up]

2.4 VJOURNAL

journalc = "BEGIN" ":" "VJOURNAL" CRLF

jourprop

"END" ":" "VJOURNAL" CRLF

jourprop = *(

The following are REQUIRED, but MUST NOT occur more than once.

dtstamp / uid

The following are optional, but MUST NOT occur more than once

class / created / dtstart /

last-mod / organizer / recurid /

seq / status / summary / url /

The following is OPTIONAL, but SHOULD NOT occur more than once (impl. as single).

rrule / exrule (deprecated in rfc5545)

The following are optional,and MAY occur more than once

attach / attendee / categories / comment /

contact / description / exdate / related /

rdate / rstatus / x-prop

)

[index] [top] [up]

2.5 VFREEBUSY

"BEGIN" ":" "VFREEBUSY" CRLF

fbprop

"END" ":" "VFREEBUSY" CRLF

fbprop = *(

The following are REQUIRED, but MUST NOT occur more than once.

dtstamp / uid

The following are optional, but MUST NOT occur more than once

contact / dtstart / dtend /

organizer / url /

The following are optional,and MAY occur more than once

attendee / comment / freebusy / rstatus / x-prop

)

[index] [top] [up]

2.6 VALARM

"BEGIN" ":" "VALARM" CRLF

(audioprop / dispprop / emailprop / procprop)

"END" ":" "VALARM" CRLF

audioprop = *(

"action" and "trigger" are both REQUIRED, but MUST NOT occur more than once

action / trigger /

"duration" and "repeat" are both optional,and MUST NOT occur more than once each,

but if one occurs, so MUST the other

duration / repeat /

The following is optional, but MUST NOT occur more than once

attach /

The following is optional, and MAY occur more than once

x-prop

)

dispprop = *(

The following are all REQUIRED, but MUST NOT occur more than once

action / description / trigger /

"duration" and "repeat" are both optional,and MUST NOT occur more than once each,

but if one occurs, so MUST the other

duration / repeat /

The following is optional, and MAY occur more than once

x-prop

)

emailprop = *(

The following are all REQUIRED, but MUST NOT occur more than once

action / description / trigger / summary

The following is REQUIRED, and MAY occur more than once

attendee /

"duration" and "repeat" are both optional, and MUST NOT occur more than once each,

but if one occurs, so MUST the other

duration / repeat /

The following are optional, and MAY occur more than once

attach / x-prop

)

procprop (deprecated in rfc5455) = *(

The following are all REQUIRED, but MUST NOT occur more than once

action / attach / trigger /

"duration" and "repeat" are both optional, and MUST NOT occur more than once each,

but if one occurs, so MUST the other

duration / repeat /

"description" is optional, and MUST NOT occur more than once

description /

The following is optional, and MAY occur more than once

x-prop

)

[index] [top] [up]

2.7 VTIMEZONE

"BEGIN" ":" "VTIMEZONE" CRLF

2*(

"tzid" is required, but MUST NOT occur more than once

tzid /

"last-mod" and "tzurl" are optional, but MUST NOT occur more than once

last-mod / tzurl /

one of "standardc" or "daylightc" MUST occur and each MAY occur more than once.

standardc / daylightc /

The following is optional, and MAY occur more than once

x-prop

)

"END" ":" "VTIMEZONE" CRLF

standardc = "BEGIN" ":" "STANDARD" CRLF

tzprop

"END" ":" "STANDARD" CRLF

daylightc = "BEGIN" ":" "DAYLIGHT" CRLF

tzprop

"END" ":" "DAYLIGHT" CRLF

tzprop = *(

The following are each REQUIRED, but MUST NOT occur more than once

dtstart / tzoffsetto / tzoffsetfrom /

The following is OPTIONAL, but SHOULD NOT occur more than once (impl. as single).

rrule

The following are optional, and MAY occur more than once

comment /rdate / tzname / x-prop

)

[index] [top] [up]

2.8 Component Properties

A comprehensive table showing relation between calendar components and properties. vtimezone properties are not included.

0-1 OPTIONAL property, MUST NOT occur more than once.
0-m OPTIONAL property, MAY occur more than once.
0 / 1=1 A pair of OPTIONAL properties, MUST NOT occur more than once each.
If one occurs, so MUST the other
0*1 A pair of OPTIONAL properties, MUST NOT occur more than once each.
If one occurs, so MUST NOT the other
1-m REQUIRED property, MAY occur more than once.
1 REQUIRED property, MUST NOT occur more than once.
 
  v
e
v
e
n
t
v
t
o
d
o
v
j
o
u
r
n
a
l
v
f
r
e
e
b
u
s
y
v a l a r m
 



a
u
d
i
o


d
i
s
p
l
a
y




e
m
a
i
l
p
r
o
c
e
d
u
r
e
action         1 1 1 1
attach 0-m 0-m 0-m   0-1   0-m 1
attendee 0-m 0-m 0-m 0-m     1-m  
categories 0-m 0-m 0-m          
class 0-1 0-1 0-1          
comment 0-m 0-m 0-m 0-m        
completed   0-1            
contact 0-m 0-m 0-m 0-1        
created 0-1 0-1 0-1          
description 0-1 0-1 0-m     1 1 0-1
dtend 0*1     0-1        
dtstamp 0-1 0-1 0-1 0-1        
dtstart 0-1 0-1 0-1 0-1        
due   0*1            
duration 0*1 0*1   0-1 0 / 1=1 0 / 1=1 0 / 1=1 0 / 1=1
exdate 0-m 0-m 0-m          
exrule 0-m 0-m 0-m          
freebusy       0-m        
geo 0-1 0-1            
last-mod 0-1 0-1 0-1        
location 0-1 0-1            
organizer 0-1 0-1 0-1 0-1        
percent   0-1            
priority 0-1 0-1            
rdate 0-m 0-m 0-m          
recurid 0-1 0-1 0-1          
related 0-m 0-m 0-m          
repeat         0 / 1=1 0 / 1=1 0 / 1=1 0 / 1=1
resources 0-m 0-m            
rrule 0-m 0-m 0-m          
rstatus 0-m 0-m 0-m 0-m        
sequence 0-1 0-1 0-1          
status 0-1 0-1 0-1          
summary 0-1 0-1 0-1       1  
transp 0-1              
trigger         1 1 1 1
uid 0-1 0-1 0-1 0-1        
url 0-1 0-1 0-1 0-1        
x-prop 0-m 0-m 0-m 0-m 0-m 0-m 0-m 0-m

If not set, the DTSTAMP and UID properties are automatically created by iCalcreator
for vevent, vtodo, vjournal and vfreebusy components
when using Vcalendar methods saveCalendar (or returnCalendar)
or using component::getDtstamp() (DTSTAMP) or component::getUid() (UID) methods.


[index] [top] [up]

3 Function list

3.1 Vcalendar methods

3.1.1 Constructors

3.1.1.1 Vcalendar

Create a new VCALENDAR object instance.

Constructor

Throws InvalidArgumentException on (set)config error.

Format

Vcalendar::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config );

The calendar PRODID property and the component UID property are AUTOMATICALLY generated in iCalcreator, if not set manually, and based on the configuration unique_id.

Example 2

use Kigkonsult\Icalcreator\Vcalendar; $tz = "Europe/Stockholm" $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vcalendar->setXProp( Vcalendar::X_WR_TIMEZONE, $tz ); // insert components or parse an iCal string calendar (and edit components) .. .

Some calendar software may also require calendar property X-WR-TIMEZONE and vtimezone component with property X-LIC-LOCATION, review VTIMEZONEmethod.

factory

Create a new Vcalendar object instance using a factory-method.

Throws InvalidArgumentException on (set)config error.

Format

Vcalendar::factory( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = Vcalendar::factory( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ) ->setMethod( "PUBLIC" );


[index] [top] [up]

3.1.1.2 Vevent

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VEVENT is available.

Format 1

Create a new VEVENT object instance using an Vcalendar component factory-method.

Throws InvalidArgumentException on (set)config error.

Vcalendar::newVevent()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vevent = $vcalendar->newVevent() ->setDtstart( ...

Format 2

Create a new VEVENT object instance.

Throws InvalidArgumentException on (set)config error.

vevent::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vevent; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $config = $vcalendar->getConfig(); $vevent = new Vevent( $config ); .. . $vcalendar->setComponent( $vevent );


[index] [top] [up]

3.1.1.3 Vtodo

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VTODO is available.

Format 1

Create a new VTODO object instance using an Vcalendar component factory-method.

Throws InvalidArgumentException on (set)config error.

Vcalendar::newVtodo()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtodo = $vcalendar->newVtodo() ->setDtstart( ...

Format 2

Create a new VTODO object instance.

Throws InvalidArgumentException on (set)config error.

vtodo::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vtodo; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtodo = new Vtodo( $vcalendar->getConfig()); .. . $vcalendar->setComponent( $vtodo );


[index] [top] [up]

3.1.1.4 Vjournal

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VJOURNAL is available.

Format 1

Create a new VJOURNAL object instance using an Vcalendar factory-method.

Throws InvalidArgumentException on (set)config error.

Vcalendar::newVjournal()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vjournal = $vcalendar->newVjournal() ->setDtstart( .. .

Format 2

Create a new VJOURNAL object instance.

Throws InvalidArgumentException on (set)config error.

vjournal::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vjournal; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vjournal = new Vjournal( $vcalendar->getConfig()); .. . $vcalendar->setComponent( $vjournal );


[index] [top] [up]

3.1.1.5 Vfreebusy

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VFREEBUSY is available.

Format 1

Create a new VFREEBUSY object instance using an Vcalendar factory-method, returning a reference to the new component.

Throws InvalidArgumentException on (set)config error.

Vcalendar::newVfreebusy()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vfreebusy = $vcalendar->newVfreebusy() ->setFreebusy(...

Format 2

Create a new VFREEBUSY object instance.

Throws InvalidArgumentException on (set)config error.

vfreebusy::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vfreebusy; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vfreebusy = new Vfreebusy( $vcalendar->getConfig()); .. . $vcalendar->setComponent( $vfreebusy );


[index] [top] [up]

3.1.1.6 Valarm

Format 1

Create a new VALARM object instance using an Vcalendar component factory-method. The VALARM calendar component MUST only appear (one or more) in either a VEVENT or VTODO calendar component.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VALARM is available.

calendarComponent::newValarm()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vevent = $vcalendar->newVevent() ->setDtstart( .. . $valarm = $vevent->newValarm() ->setTrigger( .. . $vtodo = $vcalendar->newVtodo() ->setDtstart( .. . $valarm = $vtodo->newValarm() ->setTrigger( .. .

Format 2

Create a new VALARM object instance.

Throws InvalidArgumentException on (set)config error.

valarm::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vevent; use Kigkonsult\Icalcreator\Valarm; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vevent = new Vevent( $vcalendar->getConfig()); .. . $valarm = new Valarm( $vevent->getConfig()); .. . $vevent->setComponent( $valarm ); $vcalendar->setComponent( $vevent );


[index] [top] [up]

3.1.1.7 Vtimezone

The vtimezone component describe, at a minimum, the base offset from UTC for the time zone. For dates with UTC DATE-TIME, read this!

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VTIMEZONE is available.

Throws InvalidArgumentException on (set)config error.

Format 1

Vcalendar::newVtimezone()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone() ->setTzname(...

Format 2

Create a new VTIMEZONE object instance.

Throws InvalidArgumentException on (set)config error.

vtimezone::__construct( [ config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vtimezone; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = new Vtimezone( $vcalendar->getConfig()); .. . $vcalendar->setComponent( $vtimezone );


[index] [top] [up]

3.1.1.7.1 populate

The (static) method, applied on a Vcalendar instance and using a PHP valid (string) timezone, return the Vcalendar instance with Vtimezone, Standard and Daylight components, based on PHP DateTimeZone class and time zone transition (UTC) timestamps.

Recommendation is to call the method after editing components (and without (period) from/to arguments, below), it will automatically create timezone components, using components DTSTART values.

If no argument timezone, the calendar "X-WR-TIMEZONE" property and argument xProps and key "X-LIC-LOCATION" are searched (in order) for timezone. If still none found, "UTC" is used.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::X_WR_TIMEZONE
- Kigkonsult\Icalcreator\Vcalendar::X_LIC_LOCATION
are available.

Throws Exception on invalid (PHP) timezone.

Format

Vtimezone::populate( calendar, [ timezone [, xprops, [, from [, to ]]]] )

calendar = (object) Vcalendar instance timezone = (string) valid timezone, acceptable by PHP DateTimeZone xprops = (array) ( *[ x-propName => value ] ), timezone non-standard properties from = Datime | (int) timestamp, period start date* to = Datime | (int) timestamp, period end date* * if empty "from" and "to" arguments, the calendar components "DTSTART" values are used to get the lowest (modified, minus 7 month) and highest (modified, plus 15 month) dates.

Example 1

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vtimezone; $tz = "Europe/Stockholm"; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $c = new Vcalendar( $config ); // opt $c->setXProp( Vcalendar::X_WR_TIMEZONE, $tz ); .. . // insert components or parse an iCal string .. . // opt $xprops = [ Vcalendar::X_LIC_LOCATION => $tz ]; Vtimezone::populate( $c, $tz, $xprops );

Example 2

Using the shortcut The Vcalendar::vtimezonePopulate() method.

use Kigkonsult\Icalcreator\Vcalendar; $tz = "Europe/Stockholm"; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $c = new Vcalendar( $config ); // opt $c->setXProp( "X-WR-TIMEZONE", $tz ); .. . // insert components or parse an iCal string .. . // opt $xprops = [ "X-LIC-LOCATION" => $tz ]; $c->VtimezonePopulate( $tz, $xprops );

Output example (when using Vcalendar createCalendar or returnCalendar methods):

BEGIN:VTIMEZONE TZID:Europe/Stockholm X-LIC-LOCATION:Europe/Stockholm BEGIN:STANDARD DTSTART:20111030T003000 TZOFFSETFROM:+0200 TZOFFSETTO:+0100 TZNAME:CET END:STANDARD BEGIN:DAYLIGHT DTSTART:20110327T002000 TZOFFSETFROM:+0100 TZOFFSETTO:+0200 TZNAME:CEST END:DAYLIGHT END:VTIMEZONE


[index] [top] [up]

3.1.1.8 Standard / Daylight

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::STANDARD
- Kigkonsult\Icalcreator\Vcalendar::DAYLIGHT
are available.

Format 1

Create a new VTIMEZONE standard / daylight object instances using an VTIMEZONE component factory-method.

vtimezone::newStandard()

vtimezone::newDaylight()

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone(); .. . $standard = $vtimezone->newStandard(); .. . $daylight = $vtimezone->newDaylight(); .. .

Format 2

Create a new VTIMEZONE STANDARD object.

vtimezone::__construct( "standard" [, config ] )

config = array, review configuration options.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vtimezone; use Kigkonsult\Icalcreator\Standard; use Kigkonsult\Icalcreator\Daylight; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = new Vtimezone( $vcalendar->getConfig()); .. . $standard = new Standard( $vtimezone->getConfig()); .. . $vtimezone->setComponent( $standard ); $daylight = new Daylight( $vtimezone->getConfig()); .. . $vtimezone->setComponent( $daylight ); $vcalendar->setComponent( $vtimezone );


[index] [top] [up]

3.1.2 Vcalendar property methods

3.1.2.1 deleteProperty

The Vcalendar deleteProperty method is deprecated in favor of property delete-methods.


[index] [top] [up]

3.1.2.2 getProperty

Format

Fetch specific calendar component property (unique) value(-s) and number of occurrence(-s). The search includes ALL components in the Vcalendar instance.

Outputs an array( *[ (string) unique-property-value => (int) number_of_occurrence ] ) or an empty array if no hits. The array is sorted by (asc.) key. If a property contains multiple values (like "CATAGORIES:course1,courseB" or "RESOURCES:pc,camera"), they are split into unique values.

Supported Descriptive Component Properties
CATEGORIES
LOCATION
GEOLOCATION *1
PRIORITY
RESOURCES
STATUS
SUMMARY
Supported Date and Time Component Property
DTSTART *2
Supported Relationship Component Properties
ATTENDEE *3
CONTACT
ORGANIZER *3
RECURRENCE-ID *4 (alt. "R-UID")
RELATED-TO
URL
UID
*1
Using the non-standard directive "GEOLOCATION", iCalcreator returns output by combining the LOCATION and GEO property values, (separated by "/") and only if GEO is set)
*2
Using DTSTART as argument returns dates in format "YYYYMMDD" (please note, dates within a RDATE/RRULE recurrence set are NOT included, only the origin start date (DTSTART)).
*3
The ATTENDEE and ORGANIZER output values are prefixed by "protocol" like "MAILTO:chair@kigkonsult.se".
*4
Using "RECURRENCE-ID-UID" returns UID values for component(-s) where RECURRENCE-ID is set.

Note, to ease up usage, you will find convenient constants for component names, properties, config keys etc in (src/)IcalInterface.

To select components based on property values, use selectComponents (Format 2).

To get components based on property values, use getComponent (Format 5).

Vcalendar::getProperty( PropName )

propName = (string) case independent, property name

Example 1

Fetch all attendees in the Vcalendar instance.

$attendees = $vcalendar->getProperty( Vcalendar::ATTENDEE ); foreach( $attendees as $attendee => $occurrCount ) { .. .

Example 2

Fetch all DTSTARTs in the Vcalendar instance.

$startDates = $vcalendar->getProperty( Vcalendar::DTSTART ); foreach( $startDates as $startDate => $occurrCount ) { .. .


[index] [top] [up]

3.1.2.3 setProperty

The the Vcalendar setProperty method deprecated in favour of properties set-method.

[index] [top] [up]

3.1.2.4 CALSCALE

This property defines the calendar scale used for the calendar information specified in the iCalendar object.

The default (pre-set) value is "GREGORIAN".

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::CALSCALE is available.

Create CALSCALE

If set, returns [RFC5545] formatted string, otherwise null.

Format

Vcalendar::createCalscale()

Example

$str = $vcalendar->createCalscale();

Delete CALSCALE

Remove CALSCALE from calendar.

Format

Vcalendar::deleteCalscale()

Example

$vcalendar->deleteCalscale();

Get Calscale

If set, returns property value, otherwise bool false.

Format

Vcalendar::getCalscale()

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $calscale = $vcalendar->getCalscale();

Set CALSCALE

Set property value. The default value is "GREGORIAN", it is pre-set.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

Vcalendar::setCalscale()

value = (string) calscale value

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); // initiate new CALENDAR $vcalendar->setCalscale( "GREGORIAN" );


[index] [top] [up]

3.1.2.5 METHOD

This property defines the iCalendar object method associated with the calendar object.

METHOD property (value PUBLISH etc.) may be required when importing iCal formatted information into some calendaring software (MS etc.), as well as x-properties "X-WR-CALNAME", "X-WR-CALDESC" and "X-WR-TIMEZONE" and the (automatically created) DTSTAMP and UID properties.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::METHOD
- Kigkonsult\Icalcreator\Vcalendar::PUBLISH
- Kigkonsult\Icalcreator\Vcalendar::REQUEST
- Kigkonsult\Icalcreator\Vcalendar::REPLY
- Kigkonsult\Icalcreator\Vcalendar::ADD
- Kigkonsult\Icalcreator\Vcalendar::CANCEL
- Kigkonsult\Icalcreator\Vcalendar::REFRESH
- Kigkonsult\Icalcreator\Vcalendar::COUNTER
- Kigkonsult\Icalcreator\Vcalendar::DECLINECOUNTER
are available.

Create METHOD

If set, returns [RFC5545] formatted string, otherwise null.

Format

Vcalendar::createMethod()

Example

$str = $vcalendar->createMethod();

Delete METHOD

Remove METHOD from calendar.

Format

Vcalendar::deleteMethod()

Example

$vcalendar->deleteMethod();

Get METHOD

If set, returns property value, otherwise bool false.

Format

Vcalendar::getMethod();

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vcalendar->parse(); $method = $vcalendar->getMethod();

Set METHOD

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

Vcalendar::setMethod( value )

value = (string) method value

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); // initiate new CALENDAR $vcalendar->setMethod( Vcalendar::PUBLISH );


[index] [top] [up]

3.1.2.6 VERSION

This property specifies the identifier corresponding to the version number of the iCalendar specification. This property is always placed first in the formatted calendar.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::VERSION is available.

Create Version

If set, returns [RFC5545] formatted string, otherwise null.

Format

Vcalendar::createVersion()

Example

$str = $vcalendar->createVersion();

Get Version

Fetch property value.

Format

Vcalendar::getVersion()

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $version = $vcalendar->getVersion()

Set Version

Set property value. Only version 2.0 valid, version is AUTO generated at calendar creation.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

Vcalendar::setVersion( version )

version = (string) iCal version

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); // initiate new CALENDAR $vcalendar->setVersion("2.0" );


[index] [top] [up]

3.1.2.7 X-PROPERTY

A calendar, non-standard property with a TEXT value and a name with an "X-" prefix. In a calendar, an x-property, with an unique name, can occur only once but the number of x-properties are unlimited.

X-properties "X-WR-CALNAME", "X-WR-CALDESC" and "X-WR-TIMEZONE" may be required when importing iCal formatted information into some calendaring software (MS etc.), as well as METHOD property (value PUBLISH etc.) and the (automatically created) DTSTAMP and UID properties.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::X_WR_CALNAME
- Kigkonsult\Icalcreator\Vcalendar::X_WR_CALDESC
- Kigkonsult\Icalcreator\Vcalendar::X_WR_RELCALID
- Kigkonsult\Icalcreator\Vcalendar::X_WR_TIMEZONE
- Kigkonsult\Icalcreator\Vcalendar::X_LIC_LOCATION
are available.

The value type is TEXT.

Create X-property

If set, returns [RFC5545] formatted string, otherwise null.

Format

Vcalendar::createXprop()

Example

$str = $vcalendar->createXprop();

Delete X-PROPERTY

Remove X-PROPERTY from calendar.

Format

Vcalendar::deleteXprop( "X-PROPERTY" )

Example 1

Delete the x-property named "X-PROPERTY".

$vcalendar->deleteCprop( "X-PROPERTY" );

Example 2

Delete all x-properties.

while( $vcalendar->deleteXprop()) continue;

Get X-PROPERTY

If set, returns property (name and) value, bool otherwise false.

Format

Vcalendar::getXprop()

Vcalendar::getXprop( "X-PROPERTY" )

output = array( propertyName1, value2 )

Vcalendar::getXprop( null, propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( propertyName1 , array( "value" => value2 ) , "params" => params3))

propertyName1, value2 and params3 specs below.

Example 1

Read all x-prop values in a loop. Output in detail below.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $xprop = $vcalendar->getXprop()) { // $xprop = array( propertyName1, value2 ) .. .

Example 2

If exists, read the X-WR-TIMEZONE x-prop

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); if( $xprop = $vcalendar->getXprop( Vcalendar::X_WR_TIMEZONE )) { // $xprop = [ Vcalendar::X_WR_TIMEZONE, value2 ] .. .

Example 3

Read all x-prop values/parameters in a loop.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $xprop = $vcalendar->getXprop( null, null, true )) { /* $xprop = [ propertyName1, [ "value" => value2, "params" => params3 ] ] */ .. .

Set X-PROPERTY

Insert property name and value. If an x-prop with the same name already exists, it will be replaced. PropertyNames are always stored upperCase, ex. x-wr-calname => X-WR-CALNAME.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

Vcalendar::setXprop( propertyName, propertyData [, params ] )

propertyName1 = (string) Any property name with a "X-" prefix value2 = (string) Value type TEXT params3 = (array) ( [Vcalendar::LANGUAGE => (string) "lang*"] *[, xparams] ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = Vcalendar:::factory( $config ) // initiate new CALENDAR // set some X-properties ->setXprop( Vcalendar::X_WR_CALNAME, "Calendar Sample" ) ->setXprop( Vcalendar::X-WR-CALDESC, "Calendar Description" ) ->setXprop( Vcalendar::X-WR-TIMEZONE, "Europe/Stockholm" );


[index] [top] [up]

3.1.3 Vcalendar component object methods

3.1.3.1 deleteComponent

Remove component from the Vcalendar instance.

Bool false is returned if no component exists or at end-of-components invoking the method consecutive.

format 1

Remove component with order number (1st=1, 2nd=2).

Vcalendar::deleteComponent( orderNumber )

orderNumber = (int) order number

format 2

Remove component with component type (e.g. "vevent") and order 1 alt. suborder number.

Vcalendar::deleteComponent( componentType [, componentSuborderNumber])

componentType = (string) component type componentSuborderNumber = (int) order number

format 3

Remove component with UID. N.B UID is NOT set for ALARM / TIMEZONE components.

Vcalendar::deleteComponent( UID )

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $vcalendar->deleteComponent( 1 ); $vcalendar->deleteComponent( Vcalendar::VTODO, 2 ); $vcalendar->deleteComponent( "20070803T194810CEST-0123U3PXiX@kigkonsult.se");

Example 2

Deleting all components, using format 2 without order number.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $vcalendar->deleteComponent( Vcalendar::VEVENT)) { continue; } $vtodo = $vcalendar->getComponent( Vcalendar::VTODO ); while( $vtodo->deleteComponent( Vcalendar::VALARM)) { continue; }


[index] [top] [up]

3.1.3.2 getComponent

Get (next) component from the Vcalendar instance.

Bool false is returned if no component exists or at end-of-components invoking the method consecutive.

format 1

Get next component, until end-of-components.

Vcalendar::getComponent()

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $comp = $vcalendar->getComponent()) { .. . }

format 2

Get specific component with order number (1st=1, 2nd=2).

Vcalendar::getComponent( orderNumber )

orderNumber = (int) order number

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); if( $comp = $vcalendar->getComponent( 1 )) { .. . }

format 3

Get (first/next) component with component type (until end-of-components) alt. get specific component with component type and suborder number (1st=1, 2nd=2).

Vcalendar::getComponent( componentType [, componentSuborderNumber])

componentType = (string) component type componentSuborderNumber = (int) order number

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); if( $comp = $vcalendar->getComponent( Vcalendar::VTODO, 2 )) { .. . }

format 4

Get (first/next) component with UID as key. (UID is NOT set for ALARM / TIMEZONE components.) May be used when trying to find (base) component and corresponding RECURRENCE-ID components.

Vcalendar::getComponent( UID )

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $uid = "20070803T194810CEST-0123U3PXiX@kigkonsult.se"; if( $comp = $vcalendar->getComponent( $uid )) { .. . }

format 5

Get (first/next) component based on specific property contents:

Note, to ease up usage, you will find convenient constants for component names, properties, config keys etc in (src/)IcalInterface.

Supported Descriptive Component Properties
CATEGORIES
LOCATION
PRIORITY
RESOURCES
STATUS
SUMMARY
Date and Time Component Properties
COMPLETED
DTEND
DUE
DTSTART
SupportedRelationship Component Properties
ATTENDEE *1
CONTACT
ORGANIZER *1
RECURRENCE-ID
RELATED-TO
URL
UID
Change Management Component Properties
CREATED
DTSTAMP
LAST-MODIFIED
*1
ATTENDEE and ORGANIZER search values must be prefixed by protocol ex. "MAILTO:chair@ical.net".

For the property "SUMMARY" ,if a search value (any case) exists within property value, a hit exists. For the other, non-date, properties an exact (strict case) match is required.

To select components based on property values, use selectComponents (Format 2).

To retrieve specific Vcalendar instance property values, searching ALL components, use getProperty (Format 2).

Vcalendar::getComponent( search )

search = (array) ( *[ propertyName => uniqueValue ]), multiple array elements are combined by "OR" propertyName = (string) property name, above propertyData = (string) unique property value (strict case), date format "YYYYMMDD" (if any side is DATE, only dates are used), datetime format "YYYYMMDDTHHMMSS"

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $comp = $vcalendar->getComponent( [ Vcalendar::RESOURCES => "PC" ]) { .. . }


[index] [top] [up]

3.1.3.3 newComponent

Create component (VEVENT / VTODO / VJOURNAL / VFREEBUSY / VTIMEZONE) using a Vcalendar factory-method, returning a reference to the new component.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::VEVENT,
- Kigkonsult\Icalcreator\Vcalendar::VTODO,
- Kigkonsult\Icalcreator\Vcalendar::VJOURNAL,
- Kigkonsult\Icalcreator\Vcalendar::VFREEBUSY,
- Kigkonsult\Icalcreator\Vcalendar::VTIMEZONE
are available.

The method is deprecated in favor of components factory-method.


[index] [top] [up]

3.1.3.4 replaceComponent

Replace calendar component in vcalendar based on component property UID (EVENT / VTODO / VJOURNAL / VFREEBUSY). If not found, inserted last in component chain.

In case of multiple components sharing the same UID (ex. a RECURRENCE-ID property altering a recurrence pattern), the first found is replaced and it may lead to unpredictable result, to use with care.

For a VTIMEZONE component, a TZID match is required.

A successfull replace returns bool true otherwise bool false.

Throws InvalidArgumentException/UnexpectedValueException on unknown or not-found component error.

Format

Vcalendar::replaceComponent( component )

component = (object) component instance

Example

$vcalendar->replaceComponent( $component );


[index] [top] [up]

3.1.3.5 selectComponents

Format 1

Selects EVENT / VTODO / VJOURNAL / VFREEBUSY components from the Vcalendar instance on based on dates (notice date restraints), based on the initial DTSTART property along with the RRULE, RDATE, EXDATE and EXRULE properties in the component and UID-matched component(s) with RECURRENCE-ID.

Requirement:

Limitations:

Returns an array with components (events) or bool false is returned if no found component(s) exists. Replacing (RECURRENCE-ID) components has (if missing) updated COMMENT, DESCRIPTION and COMMENTs properties.

Added X-properties in recurrent instances of a calendar component:

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::X_CURRENT_DTSTART,
- Kigkonsult\Icalcreator\Vcalendar::X_CURRENT_DTEND,
- Kigkonsult\Icalcreator\Vcalendar::X_CURRENT_DUE,
- Kigkonsult\Icalcreator\Vcalendar::X_RECURRENCE,
- Kigkonsult\Icalcreator\Vcalendar::X_OCCURENCE
are available.

Throws InvalidArgumentException on argument error, Exception on DateTime/DateInterval error.

Vcalendar::selectComponents([ startYear, startMonth, startDay [, endYear, endMonth, endDay [, cType [, flat [, any [, split]]]]]])

startYear : (int) start year (4*digit), default current year (object) DateTime, start date* startMonth : (int) start month (1-2*digit), default current month (object) DateTime, end date* startDay : (int) start day (1-2*digit), default current day endYear : (int) end year (4*digit), default startYear endMonth : (int) end month (1-2*digit), default startMonth endDay : (int) end day (1-2*digit), default startDay cType : (mixed) calendar component type(-s), (string/array) ("vevent", "vtodo", "vjournal", "vfreebusy") (bool) false (default) => all flat : (bool) true => output : array[] (ignores split) component where recurrence pattern exists within period false (default) => output : array[Year][Month][Day][] any : (bool) true (default) => select components with recurrence within period false => only components that starts (DTSTART) within period split : (bool) true (default) => one component copy for every day it occurs within the period false => one occurrence of component in output array, start date/recurrence (start) date *When using datetime objects, other start/end arguments are ignored. valid flat any split combinations (defaults in upper case) 1 false true true 2 false true false 3 false false [false] (split set to false if flat=false and any=false) 4 true true [false] (split set to false if flat=true) 5 true false [false] (split set to false if flat=true) If flat is set to false, output array is sorted in 'Y-m-d h-i-s' asc. order.

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $events_arr = $vcalendar->selectComponents( 2007, 11, 1, 2007, 11, 30, Vcalendar::VEVENT ); // select all events occurring 1-30 nov. 2007 foreach( $events_arr as $year => $year_arr ) { foreach( $year_arr as $month => $month_arr ) { foreach( $month_arr as $day => $day_arr ) { foreach( $day_arr as $event ) { $currddate = $event->getDtstart(); // if member of a recurrence set, returns // array(" x-current-dtstart", // <(string) date("Y-m-d [H:i:s][timezone/UTC offset]")>) $startDate = $event->getDtstart(; $summary = $event->getSummary(); $description = $event->getDescription(); .. .

format 2

Using this format, the Vcalendar method selects components based on specific property value(-s).

Supported Descriptive Component Properties
CATEGORIES
LOCATION
PRIORITY
RESOURCES
STATUS
SUMMARY
Supported Relationship Component Properties
ATTENDEE *1
CONTACT
ORGANIZER *1
RELATED-TO
URL
UID
*1
ATTENDEE and ORGANIZER search values must be prefixed by (upper case) protocol like "MAILTO:chair@ical.net".

Note, to ease up usage, you will find convenient constants for component names, properties, config keys etc in (src/)IcalInterface.

For the property SUMMARY, if a search value (any case) exists within property value, a hit is found. For the other properties an exact (strict case) match is required. Multiple search properties may coexist.

To retrieve specific Vcalendar instance property values, searching ALL components, use getProperty (Format 2).

To get components based on property values, use getComponent (Format 5).

Vcalendar::selectComponents( searchArray )

Outputs an array of matched (unique) components in UID order.

searchArray : (array) *( propertyName => propertyValue ) propertyName : (string) above (any case) propertyValue : (string) value / (array) ( *[ (string) value] )

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $searchArray = [ Vcalendar::PRIORITY => [ 1, 2, 3, 4 ]]; $highPrioArr = $vcalendar->selectComponents( $searchArray ); // select all components with PRIORITY set to high (1-4) if( ! empty( $highPrioArr )) { $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $highPrioCal = new Vcalendar( $config ); $highPrioCal->setXProp( Vcalendar::X_WR_CALDESC, "High priority events" ); foreach( $highPrioArr as $highPrioComponent ) { $highPrioCal->setComponent( $highPrioComponent ); } $highPrioCal->returnCalendar(); } exit;


[index] [top] [up]

3.1.3.6 setComponent

Replace or update component in the Vcalendar instance. Also add a calendar component to the Vcalendar instance when calendar component is created with the procedural (non-factory) method, see example VEVENT, format 2.

A successful update returns true.

The method throws InvalidArgumentException on unknown component.

format 1

Insert last in component chain.

Vcalendar::setComponent( component ) Vcalendar::addComponent( component ) // alias

component = (object) Vcalendar component instance

addComponent, deprecated, removal in next major version.

format 2

Insert/replace component with order number (1st=1, 2nd=2). If replace and orderNumber is not found, component is inserted last in chain.

Vcalendar::setComponent( component, orderNumber )

component = (object) Vcalendar component instance int = (int) order numder

format 3

Replace component with component type and 1st alt. component order number. If orderNumber is not found, component is inserted last in chain.

Vcalendar::setComponent( component, componentType [, componentSuborderNo])

component = (object) Vcalendar component instance componentType = (string) component type componentSuborderNo = (int) component Suborder Number

format 4

Replace component with UID. N.B UID is NOT set for ALARM / TIMEZONE components. If UID is not found, component is inserted last in chain.

Vcalendar::setComponent( component, UID )

component = (object) Vcalendar component instance

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $vevent = vcalendar->getComponent( 1 ); // fetch first EVENT $vevent->setDtstart( new DateTime( "2006-12-24 19:30:00" ) ); // update DTSTART property $vcalendar->setComponent( $vevent, 1 ); // replace first component


[index] [top] [up]

3.1.4 Vcalendar calendar methods

3.1.4.1 parse and merge

Parse string/array calendar content (or iCal file(-s)) into a single Vcalendar instance (components, properties and parameters), including multiple vcalendars (within a single iCal calendar) parse, e.g. Oracle Calendar exports.

As for now, you can use (local) filename as argument and, as long as php.ini directive "allow_url_fopen" is enabled, also remote resources using URLs; protocol "http" ("webcal"). A remote file, URL, must be prefixed by "http://" ("webcal://") and suffixed by a valid filename!

Note, the config Directory, Delimiter, Filename, Dirfile and URL keys are objects for removal in next major version. Indicates all file (external resources) read/write methods will be placed outside iCalcreator. A strong recommendation now is placing iCal file/url content acquire functionality outside iCalcreator, this will also offer better acquire control.

If missing, component property UID is created when parsing. For that reason UNIQUE_ID might need to be set before parsing, Se examples below.

Minor errors like non-standard line-endings, initial and trailing empty lines as well as files without proper end line(-s) (i.e. missing component end and/or "END:CALENDAR" iCal directives) are managed.

Throws InvalidArgumentException on argument error, UnexpectedValueException on parse error.

Non-standard iCal properties (except the X-properties) are ignored.

Format

The method returns the class instance (static).

Vcalendar::parse( [ textToParse ] )

textToParse = (string) calendarContent ex. result from - file_get_contents( "filename") (array) calendarContent ex. result from - file( "filename", FILE_IGNORE_NEW_LINES )

parse example 1

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "file.ics" ); $vcalendar->parse( $iCalContent );

parse example 2

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "http://www.ical.net/calendars/calendar.ics" ); $vcalendar->parse( $iCalContent );

parse example 3

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $str = [ "BEGIN:VCALENDAR", "PRODID:-//kigkonsult.se//NONSGML kigkonsult.se iCalcreator 2.28.2//", "VERSION:2.0", "BEGIN:VEVENT", "DTSTART:20101224T190000Z", "DTEND:20101224T200000Z", "DTSTAMP:20101020T103827Z", "UID:20101020T113827-1234GkdhFR@test.org", "DESCRIPTION:example", "END:VEVENT", "END:VCALENDAR" ]; $vcalendar->parse( $str );

parse example 4

Subject for removal in next major version.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $vcalendar->parse( "file.ics" );

merge example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "file1.ics" ); $vcalendar->parse( $iCalContent ); $iCalContent = file_get_contents( "file2.ics" ); $vcalendar->parse( $iCalContent ); file_put_contents( "icalmerge.ics", $vcalendar->createCalendar(), LOCK_EX );


[index] [top] [up]

3.1.4.2 createCalendar

Generate and return (string) calendar.

Format

Vcalendar::createCalendar()

Example

$str = $vcalendar->createCalendar(); echo $str;


[index] [top] [up]

3.1.4.3 returnCalendar

Redirect the Vcalendar instance content to user browser. Filename, addressed to browser, is automatically generated if missing or not set and the filename will look like it is set using

$filename = date( "YmdHis" ).".ics"

The method do not stop PHP script (exit), returns (bool) true on success.

Note, the returnCalendar method is subject for removal in next major version.

Format

Vcalendar::returnCalendar( [ utf8Encode [, gzip [, cdType ]]] )

utf8Encode = (bool) true: utf8 encoded output, false: (default) no encoding gzip = (bool) true: gzip compressed output Header "Content-Length" only sent when gzip=true false: (default) no compressing cdType = (bool) true: (default) Content-Disposition: attachment false: Content-Disposition: inline

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vevent = $vcalendar->newVevent() ->setDtstart( new DateTime( "2007-04-01 19:00:00", new DateTimezone( "Europe/Stockholm" ) ) ) ->setDuration( new DateInterval( "PT1H" )) ->setLocation( "Central Plaza" ) ->setSummary( "PHP summit" ); $vcalendar->returnCalendar(); exit;

Example 2

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $utf8Encode = true; if( isset( $_SERVER["HTTP_ACCEPT_ENCODING"] ) && ( false !== strpos( strtolower( $_SERVER["HTTP_ACCEPT_ENCODING"] ), "gzip" ))) { $gzip = true; } else { $gzip = false; } $vcalendar->returnCalendar( $utf8Encode, $gzip ); exit;


[index] [top] [up]

3.1.4.4 saveCalendar

Save the Vcalendar instance in a file, using preset directory and filename. Filename is automatically generated if missing or not set and the filename will look like it is set using

$filename = date( "YmdHis" ).".ics"

Return bool true on success, on error false.

Note, the saveCalendar method is subject for removal in next major version.

Format

Vcalendar::saveCalendar()

Example

use Kigkonsult\Icalcreator\Vcalendar; try { $vcalendar->setConfig( [ Vcalendar::DIRECTORY => "depot", Vcalendar::FILENAME => "calendar.ics" ]); } catch( Exception $e ) { echo $e->getMessage(); exit(); } $vcalendar->saveCalendar();


[index] [top] [up]

3.1.4.5 sort

Format 1

Sort created/parsed calendar components on The following (prioritized) keys:
1 - X-CURRENT-DTSTART - X-CURRENT-DTEND/X-CURRENT-DUE
    (if created in Vcalendar method selectComponents)
1 - DTSTART - DTEND alt. DURATION (VEVENT and VFREEBUSY components)
1 - DTSTART - DUE alt. DURATION (VTODO components)
1 - DTSTART (VJOURNAL components)
2 - CREATED / DTSTAMP
3 - UID
A date value, like "DTSTART;VALUE=DATE:20120717", are sorted before a datetime value.
VTIMEZONE component(-s) is always placed first (ordered by TZID). The STANDARD / DAYLIGHT  sub-components are sorted (on asc. key DTSTART) when calling createCalendar (or returnCalendar).
ALARM sub-components, if exists, are not sorted.

Vcalendar::sort()

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $vcalendar->sort(); $vcalendar->returnCalendar(); exit;

Format 2

Sort created/parsed calendar components based on specific property values and ascending order. If a property is not set in component, an empty sort key is used (i.e. sorted first).

Vcalendar::sort( sortArgument )

sortArgument: (string) "ATTENDEE" * / "CATEGORIES" * / "CONTACT" * / "DTSTAMP" / "LOCATION"" / "ORGANIZER" / "PRIORITY" / "RESOURCES" * / "STATUS" / "SUMMARY" / "URL" / "UID" **.

*) For a property where multiple occurrence may exist (ATTENDEE, CATEGORIES, CONTACT, RESOURCES) lowest (alphabetic) value is used as sort key.

**) For multiple components with the same UID, components with RECURRENCE-ID / SEQUENCE set are sorted first (on asc. values) and components without RECURRENCE-ID last.

Note, to ease up usage, you will find convenient constants for component names, properties, config keys etc in (src/)IcalInterface.


[index] [top] [up]

3.1.4.6 useCachedCalendar

If a recent version of (non-empty and saved) calendar file exists, an HTTP redirect is sent otherwise bool false is returned.

NOTE, the method no longer stops PHP script (exit), returns bool true on success, false on error.

Note, the useCachedCalendar method is subject for removal in next major version.

Format

Vcalendar::useCachedCalendar( [ timeout [, cdType ]] )

timeout = (int) default 3600 sec cdType = (bool) true: (default) Content-Disposition: attachment false: Content-Disposition: inline

Example

use Kigkonsult\Icalcreator\Vcalendar; try { $vcalendar->setConfig( Vcalendar::DIRECTORY, "depot" ); $vcalendar->setConfig( Vcalendar::FILENAME, "calendar.ics" ); } catch( Exception $e ) { die( $e->getMessage()); } $vcalendar->useCachedCalendar();


[index] [top] [up]

3.1.4.7 iCalcreatorVersion

This static class method returns the iCalcreator class version number.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::ICALCREATOR_VERSION is available.

Format

Vcalendar::iCalcreatorVersion()


[index] [top] [up]

3.1.4.8 vtimezonePopulate

An shortcut using Vtimezone::populate, return Vcalendar.

Throws Exception on error, ex. invalid (PHP) timezone.

Format

Vcalendar::vtimezonePopulate( [ timezone [, xprops, [ start [, end ]]]] )

timezone = (string) valid timezone, acceptable by PHP DateTimeZone xprops = (array) ( *[ x-propName => value ] ), timezone non-standard properties from = DateTime | (int) timestamp, period start date* to = DateTime | (int) timestamp, period end date*


[index] [top] [up]

3.1.5 Vcalendar configuration

3.1.5.1 configuration keys

Note, to ease up usage, you will find convenient constants for config keys etc in (src/)IcalInterface.

key calendar component remark
allowEmpty * *  
Compsinfo * * getConfig only
Delimiter1 *    
Directory1 *    
Filename1 *    
Dirfile1 *   getConfig only
Filesize1 *   getConfig only
Language * *  
setPropertyNames   * getConfig only
Unique_id * *  
URL1 *    

1 objects for removal in next major version.



[index] [top] [up]

3.1.5.2 getConfig

Vcalendar::getConfig( [ key ] )

key = (string) config key

Example 1

use Kigkonsult\Icalcreator\Vcalendar; .. . $uniqueId = $vcalendar->getConfig( Vcalendar::UNIQUE_ID ); .. .

Example 2

.. . $config = $vcalendar->getConfig(); .. .

Output= array( string key => mixed value *[, string key => mixed value] )


[index] [top] [up]

3.1.5.3 calendar/component initialization

Format

Create a new Vcalendar instance.

Vcalendar::vcalendar( [ config ] )

config = (array) ( *[, key => value] ) key = (string) config key value = (mixed) config value

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config );

Create a new calendar component.

Vcalendar::component( [ config ] )

config = (array) ( key => value *[, key => value] ) key = (string) config key value = (mixed) config value

Example 2

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vevent; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vevent = new Kigkonsult\Icalcreator\Vevent( $config );

Example 3

$config = $vcalendar->getConfig(); $vevent = new Kigkonsult\Icalcreator\Vevent( $config );

Only component relevant configuration are set. If using a component factory method, configuration is set automatically.


[index] [top] [up]

3.1.5.4 setConfig

A successful "setConfig" returns true.

Format 1

Vcalendar::setConfig( [ config ] )

config = (array) ( key => value *[, key => value] ) key = (string) config key value = (mixed) config value

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar(); $vcalendar->setConfig( $config );

Format 2

Vcalendar::setConfig( key, value )

key = (string) config key value = (mixed) config value

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar(); $vcalendar->setConfig( Vcalendar::UNIQUE_ID, "kigkonsult.se" );


[index] [top] [up]

3.1.5.5 Allow empty components

Allow or reject empty calendar properties. Used in createCalendar, returnCalendar or create<Property> methods, creating [RFC5545] formats.

Default true (allow).

There is a convenient config key constant available: Vcalendar::ALLOWEMPTY.


[index] [top] [up]

3.1.5.6 Component information

Only to use with Vcalendar method getConfig.

Get information about the Vcalendar instance components. Returns array with basic information about all components (in array format) within the Vcalendar instance.

Output = array ( *compinfo ) compinfo = array ( "ordno" => int ordno, // order number (1st=1, 2nd=2..) , "type" => string type // component type (vevent, vtodo , "uid" => string uid // component UID (not for ALARM / TIMEZONE) , "props" => array( *[ propertyName => Property count ]) // for every set property , "sub" => array( *compinfo )) // if subcomponents exists, an array for each subcomponent

There is a convenient config key constant available: Vcalendar::COMPSINFO.

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $compsinfo = $vcalendar->getConfig( Vcalendar::COMPSINFO ); foreach( $compsinfo as compinfo) { echo " order number : " . $compinfo["ordno"]."<br/>"; echo " type : " . $compinfo["type"]."<br/>"; echo " UID : " . $compinfo["uid"]."<br/>"; foreach( $compinfo["props"] as $propertyName => $propertyCount ) { echo " $propertyName = $propertyCount"; if( is_array( $compinfo["sub"] )) { foreach( $compinfo["sub"] as $subcompinfo ) { echo " order number : " . $subcompinfo["ordno"]."<br/>"; /* .. dito if subcomponents exists */ } } // end foreach } // end foreach


[index] [top] [up]

3.1.5.7 Delimiter

Directory/filename delimiter.

Default PHP constant DIRECTORY_SEPARATOR. If used, it must be set BEFORE filename!

There is a convenient config key constant available: Vcalendar::DELIMITER.

Note, the delimiter config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.


[index] [top] [up]

3.1.5.8 Directory

Local directory to store/read iCal files.

Default ".".

Directory must be set BEFORE filename and must exist and be writeable. The setConfig method throws InvalidArgumentException on directory error. If set using an config array and together with Filename, Directory are set automatically first. When setting directory, the PHP realpath function is applied to speed up parse/saveCalendar methods. When setting Directory, any previously set URL is removed.

There is a convenient config key constant available: Vcalendar::DIRECTORY.

Note, the directory config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.

Example

use Kigkonsult\Icalcreator\Vcalendar; $dir = 'test'; $config = [ Vcalendar::DIRECTORY => $dir ]; try { $vcalendar->setConfig( $config ); } catch( InvalidArgumentException $e ) { die( "Error on directory $dir, " . $e->getMessage()); }

For temporary calendar files, you may set directory/filename using PHP functions sys_get_temp_dir() and tempnam().


[index] [top] [up]

3.1.5.9 Dirfile

Only available in Vcalendar method getConfig, returning (string) directory, delimiter and filename.

There is a convenient config key constant available: Vcalendar::DIRFILE.

Note, the dirfile config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.


[index] [top] [up]

3.1.5.10 Fileinfo

Only available in Vcalendar method getConfig, giving information in array format about directory, filename and filesize.

There is a convenient config key constant available: Vcalendar::FILEINFO.

Note, the fileinfo config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.

Example

use Kigkonsult\Icalcreator\Vcalendar; $fileinfo = $vcalendar->getConfig( Vcalendar::FILEINFO );

output = array( <directory>, <filename>, <filesize> )


[index] [top] [up]

3.1.5.11 Filename

Calendar local file name, default created like (if not set) as

$filename = date( "YmdHis" ).".ics";

If not set, filename is created when requested, ex. in Vcalendar methods saveCalendar or getConfig(Vcalendar::FILENAME).

Local filename must be set AFTER setting directory (and opt. delimiter)! Filename (and opt. directory) must be readable/writeable. The setConfig method throws InvalidArgumentException on file error.

There is a convenient config key constant available: Vcalendar::FILENAME.

Note, the filename config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.

Example

use Kigkonsult\Icalcreator\Vcalendar; $dir = 'test'; $config = [ Vcalendar::DIRECTORY => $dir ]; try { $vcalendar->setConfig( $config ); } catch( InvalidArgumentException $e ) { die( "Error on directory $dir, " . $e->getMessage()); } $file = 'temp.ics'; $config = [ Vcalendar::FILENAME => $file ]; try { $vcalendar->setConfig( $config ); } catch( InvalidArgumentException $e ) { die( "Error on file $file, " . $e->getMessage()); }

For temporary calendar files, you may set directory/filename using PHP functions sys_get_temp_dir() and tempnam().

Do NOT set directory/filename in vcalendar constructor, due to inability to detect error (bool false) config return.


[index] [top] [up]

3.1.5.12 Filesize

Only when getting configuration (using Vcalendar method getConfig).
Returns the size of the file in bytes, to be invoked
- after "saveCalendar()"
or
- after a "setConfig( "directory" / "filename" )" and before/after "parse()".
Getting the filesize for a remote file (URL) will always return zero.

There is a convenient config key constant available: Vcalendar::FILESIZE.

Note, the filesize config key is subject for removal in next major version. A strong recommendation is placing iCal file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.


[index] [top] [up]

3.1.5.13 Language

Language for the Vcalendar instance and component TEXT value properties as defined in [RFC5546].

Default empty.

If NOT set in TEXT property parameters, language from component instance "setConfig( "language", ..)" method will be used, if set, otherwise language from calendar method "setConfig( "language", ..)" will be used, if set.

The calendar property PRODID is always recreated when setting (calendar) language (, note Unique_id, below).

There is a convenient config key constant available: Vcalendar::LANGUAGE.


[index] [top] [up]

3.1.5.14 setPropertyNames

Returns array of property names for all set properties in component. "X-PROP" will be used when X-properties are set.


[index] [top] [up]

3.1.5.15 Unique_id

"Unique_id" is used in calendar property PRODID and component property UID, both created automatically (, if not setting UID manually.

PRODID The identifier is RECOMMENDED to be the identical syntax to the [RFC 822] addr-spec. A good method to assure uniqueness is to put the domain name or a domain literal IP address of the host on which

Default AUTOMATICALLY generated by using PHP function gethostbyname( $_SERVER["SERVER_NAME"] ) when running in a web server environment or "localhost" when using command line interface. Used when setting other (domain) name than server name.

The calendar property PRODID is always recreated when setting unique_id.

If missing, the component property UID is created at first use of Vcalendar methods createCalendar, returnCalendar or saveCalendar

A strong recommendation is always to set unique_id, creating a new Vcalendar or component instance, to ensure accurate creation of all components UID property, also before parse, in case of missing UID.

There is a convenient config key constant available: Vcalendar::UNIQUE_ID.


[index] [top] [up]

3.1.5.16 URL

When reading remote files or resources with URL (using the parse() method), protocol "http" ("webcal") and "https" are supported.

When setting URL, the previously set Directory is removed. The setConfig method throws InvalidArgumentException on url error.

A remote file is identified by the file suffix ".ics", otherwise the URL is classified as a resource. When setting URL to a remote iCal file, only directory need to be (re-)set, filename remains unchanged (i.e. 1. set URL, 2. parse, 3. set directory, 4. saveCalendar). The URL remote file file part can be retrieved by the vcalendar method
getConfig( "filename" ). When using a resource, filename is unset (note filename, above).

There is a convenient config key constant available: Vcalendar::URL.

Note, the URL config key as well as (internal) URL-parse and (file) save methods are subjects for removal in next major version. A strong recommendation is placing iCal url content acquire functionality outside iCalcreator, this will also offer better acquire control.

Example

Parse of remote file, then local save in "depot" folder, using original filename

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = Vcalendar::factory( [ Vcalendar::UNIQUE_ID => "kigkonsult.se", ]); $url = "http://www.iCal.net/depot/calendar.ics"; try { $vcalendar->setConfig( Vcalendar::URL, $url ); } catch( InvalidArgumentException $e ) { die( "Error on url $url, " . $e->getMessage()); } $vcalendar->parse() ->sort(); $dir = "depot"; try { $vcalendar->setConfig( Vcalendar::DIRECTORY, $dir ) } catch( InvalidArgumentException $e ) { die( "Error on directory $dir, " . $e->getMessage()); } $vcalendar->saveCalendar();


[index] [top] [up]

3.2 Component property methods

All iCalcreator component object property methods for get/set data.
For property format in detail, see RFC5545 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).

Date restraints

Notice: for properties and VALUE=DATE-TIME in UTC timezone.

RFC2445: The date with UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC designator, appended to the time value. For example, The following represents January 19, 1998, at 0700 UTC:

DTSTART:19980119T070000Z

The TZID property parameter MUST NOT be applied to DATE-TIME properties whose time values are specified in UTC timezone.

Due to a limitation in PHP date functions (on 32 bit systems), a date (ex. while setting DTSTART property) before 1970 or after GMT may force a PHP date function to generate an error or set date to "January 1 1970". Timezones need to be PHP complient!

Recommended string date(time) formats: "20110625", "2011-06-25", "2011/06/26" "20110625051015", "20110625 051015" "20110625T051015", "20110625t051015" "2011-06-25 05:10:15", "2011-06-25T05:10:15", "2011-06-25t05:10:15" "2011/06/25 05:10:15", "2011/06/25T05:10:15", "2011/06/25t05:10:15" Any trailing characters (digits), if exists, will be interpreted as offset/timezone. Other string formats, acceptable by PHP strtotime function, may work.

3.2.1 deleteProperty

Generic Vcalendar instance delete property method,simplifying removal of calendar properties.
Bool false is returned if no property exists or when end-of-properties at consecutive function calls.

Deprecated in favour of properties delete method, subject for removal in next major version.


[index] [top] [up]

3.2.2 getProperty

Generic iCalcreator component get property method, simplifying fetch of properties.

Bool false is returned if no property exists or when end-of-properties at consecutive function calls.

Using the non-standard directive "GEOLOCATION", iCalcreator returns output by combining the LOCATION and GEO property values, (separated by "/") and only if GEO is set).

Deprecated in favour of properties get-method, subject for removal in next major version.

To get Vcalendar instance property values, use getProperty.


[index] [top] [up]

3.2.3 parse

Parse iCal component property text from a string or an array. Each string/array row must be strict RFC5545 formatted, i.e. begin with a property name.

You can also parse complete ALARMs, all properties included, in array format and first array row as "BEGIN:VALARM", last as "END:VALARM" as well as TIMEZONE and standard/daylight subcomponents. Empty lines in a text property must be replaced by "\n".

If major parse error occurs (like invalid calendar structure or no calendar components), bool false is returned.

Minor errors like non-standard line-endings, initial and trailing empty lines as well as files without proper end line(-s) (i.e. missing component end iCal directives) are managed.

Throws UnexpectedValueException on parse error.

Except for the X-properties, non-standard properties are ignored.

Format

calendarComponent::parse( propertyText )

propertyText = (string) [RFC5545] formatted property, (array) [RFC5545] formatted properties, property name must start string / rows(-s) // For a property array MUST all, but first row, be prefixed by space.

example

$e = $vcalendar->newVevent(); $e->parse( "DTSTAMP:19970324T1200Z" ); $e->parse( "SEQUENCE:0" ); $e->parse( "ORGANIZER:MAILTO:jdoe@host1.com" ); $e->parse( [ "ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host1.com", "ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host2.com", "ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host3.com", "ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host4.com" ]); $e->parse( "DTSTART:19970324T123000Z" ); $e->parse( "DTEND:19970324T210000Z" ); $e->parse( "CATEGORIES:MEETING,PROJECT" ); $e->parse( "CLASS:PUBLIC" ); $e->parse( "SUMMARY:Calendaring Interoperability Planning Meeting" ); $e->parse( "STATUS:DRAFT" ); $e->parse( "DESCRIPTION:Project xyz Review Meeting Minutes\\n " . "Agenda\\n " . "1. Review of project version 1.0 requirements.\\n " . "2. Definition of project processes.\\n " . "3. Review of project schedule.\\n " . "Participants: John Smith, Jane Doe, Jim Dandy\\n " . "- It was decided that the requirements need to be signed off by \\n " . "product marketing.\\n " . "- Project processes were accepted.\\n " . "- Project schedule needs to account for scheduled holidays and employee\\n " . " vacation time. Check with HR for specific dates.\\n " . "- New schedule will be distributed by Friday.\\n " . "- Next weeks meeting is cancelled. No meeting until 3/23." ); $e->parse( "LOCATION:LDB Lobby" ); $e->parse( "ATTACH;FMTTYPE=application/postscript:ftp://xyz.com/pub/conf/bkgrnd.ps" ); $e->parse( [ "BEGIN:VALARM", "ACTION:AUDIO", "TRIGGER;VALUE=DATE-TIME:19970224T070000Z", "ATTACH;FMTTYPE=audio/basic:http://host.com/pub/audio-files/ssbanner.aud", "REPEAT:4", "DURATION:PT1H", "X-alarm:non-standard ALARM property", "END:VALARM" ]); $e->parse( "X-xomment:non-standard property will be displayed, comma escaped");


[index] [top] [up]

3.2.4 setProperty

Generic iCalcreator component object set property method, simplifying insert of properties. For properties where multiple occurrences are allowed, last parameter is an index, implementing replaceProperty functionality.

A successful update returns bool true.

Deprecated in favour of properties set-method, subject for removal in next major version.


[index] [top] [up]

3.2.5 ACTION

This property defines the action to be invoked when an VALARM is triggered,
"AUDIO" / "DISPLAY" / "EMAIL" / "PROCEDURE". This property is REQUIRED and MUST NOT occur more than once. ("PROCEDURE" is deprecated in [RFC5545].)

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::ACTION
- Kigkonsult\Icalcreator\Vcalendar::AUDIO
- Kigkonsult\Icalcreator\Vcalendar::DISPLAY
- Kigkonsult\Icalcreator\Vcalendar::EMAIL
- Kigkonsult\Icalcreator\Vcalendar::PROCEDURE // Deprecated in rfc5545
are available.

Create ACTION

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createAction()

Example

$str = $component->createAction();

Delete ACTION

Remove ACTION from component.

Format

calendarComponent::deleteAction()

Example

$valarm->deleteAction();

Get ACTION

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getAction()

output = actionValue1

Format 2

calendarComponent::getAction( true )

output = array( "value" => actionValue1 , "params" => xparams2 )

Example

$action = $valarm->getAction();

Set ACTION

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setAction( actionValue [, xparams ] )

actionValue1 = (string) one of Vcalendar::AUDIO / Vcalendar::DISPLAY / Vcalendar::EMAIL / Vcalendar::PROCEDURE xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$valarm->setAction( "DISPLAY" );


[index] [top] [up]

3.2.6 ATTACH

The property provides the capability to associate a document object with a calendar component. The property is is REQUIRED and MUST NOT occur more than once in an "ALARM" ("ACTION" "procedure"), OPTIONAL and MUST NOT occur more than once in an "ALARM" ("ACTION" "audio") and OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL and VALARM ("ACTION" "email") components.

The default value type for ATTACH is URI. The value type can also be set to BINARY to indicate inline binary encoded content (params2).

If using other parameters than the recommended "FMTTYPE" and the mandatory "ENCODING" (="BASE64")and "VALUE" (="BINARY") for an inline binary encoded attachment, please use only characters within the ASCII character set in parameter name and content, to ensure proper line folding when using createCalendar and/or returnCalendar.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::ATTACH
- Kigkonsult\Icalcreator\Vcalendar::ENCODING
- Kigkonsult\Icalcreator\Vcalendar::FMTTYPE
- Kigkonsult\Icalcreator\Vcalendar::EIGHTBIT // e.i 8BIT
- Kigkonsult\Icalcreator\Vcalendar::BASE64
are available.

Create ATTACH

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createAttach()

Example

$str = $component->createAttach();

Delete ATTACH

Remove ATTACH from component.

Format

calendarComponent::deleteAttach()

Example 1

$valarm->deleteAttach();

Example 2

Delete ATTACH property no 2.

$valarm->deleteAttach( 2 );

Example 3

Deleting all ATTACH properties.

while( $valarm->deleteAttach()) { continue; }

Get ATTACH

If set, returns property value(-s), otherwise bool false.

Format 1

calendarComponent::getAttach()

output = attachValue1

Format 2

calendarComponent::getAttach( propOrderNo/null , true )

propOrderNo = (int) specific property value,

output = array( "value" => attachValue1 , "params" => params2 )

Format 3

calendarComponent::getAttach( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo ATTACH

Example

$attach = $valarm->getAttach();

Set ATTACH

Set property value. Parameters will be ordered as prescribed in [RFC5545].

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setAttach( attachValue1 [, params [, propOrderNo ]] )

attachValue1 = (string) URI / inline binary encoded content params2 = (array ) ( [ "ENCODING" => "BASE64", "VALUE" => "BINARY" ] [, "FMTTYPE" => contentType ] *[, xparams ] ) contentType = (string) The parameter value MUST be the TEXT for either an IANA registered content type or a non-standard content type. xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc

Example

$vevent->setAttach( "ftp://domain.com/pub/docs/agenda.doc", [ Vcalendar::FMTTYPE => "application/binary" ] );


[index] [top] [up]

3.2.7 ATTENDEE

The property defines an "Attendee" within a calendar component and is OPTIONAL and MUST NOT occur more than once in a VALARM ("ACTION" "email"), OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components.

This value type for ATTENDEE is URI, a calendar user address.

You can SORT calendar (components) on (asc) ATTENDEE values.

You can export calendar ATTENDEE values as vCards.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::ATTENDEE
- Kigkonsult\Icalcreator\Vcalendar::CUTYPE
- Kigkonsult\Icalcreator\Vcalendar::MEMBER
- Kigkonsult\Icalcreator\Vcalendar::ROLE
- Kigkonsult\Icalcreator\Vcalendar::PARTSTAT
- Kigkonsult\Icalcreator\Vcalendar::RSVP
- Kigkonsult\Icalcreator\Vcalendar::DELEGATED_TO
- Kigkonsult\Icalcreator\Vcalendar::DELEGATED_FROM
- Kigkonsult\Icalcreator\Vcalendar::SENT_BY
- Kigkonsult\Icalcreator\Vcalendar::CN
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
- Kigkonsult\Icalcreator\Vcalendar::DIR
- Kigkonsult\Icalcreator\Vcalendar::GROUP
- Kigkonsult\Icalcreator\Vcalendar::INDIVIDUAL
- Kigkonsult\Icalcreator\Vcalendar::RESOURCE
- Kigkonsult\Icalcreator\Vcalendar::ROOM
- Kigkonsult\Icalcreator\Vcalendar::UNKNOWN
- Kigkonsult\Icalcreator\Vcalendar::COMPLETED
- Kigkonsult\Icalcreator\Vcalendar::NEEDS_ACTION
- Kigkonsult\Icalcreator\Vcalendar::ACCEPTED
- Kigkonsult\Icalcreator\Vcalendar::DECLINED
- Kigkonsult\Icalcreator\Vcalendar::TENTATIVE
- Kigkonsult\Icalcreator\Vcalendar::DELEGATED
- Kigkonsult\Icalcreator\Vcalendar::IN_PROCESS
- Kigkonsult\Icalcreator\Vcalendar::CHAIR
- Kigkonsult\Icalcreator\Vcalendar::REQ_PARTICIPANT
- Kigkonsult\Icalcreator\Vcalendar::OPT_PARTICIPANT
- Kigkonsult\Icalcreator\Vcalendar::NON_PARTICIPANT
- Kigkonsult\Icalcreator\Vcalendar::FALSE
- Kigkonsult\Icalcreator\Vcalendar::TRUE
are available.

Create ATTENDEE

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createAttendee()

Example

$str = $component->createAttendee();

Delete ATTENDEE

Remove ATTENDEE from component.

Format

calendarComponent::deleteAttendee()

Example 1

Delete (single/first) ATTENDEE property

$valarm->deleteAttendee();

Example 2

Delete ATTENDEE property no 2.

$valarm->deleteAttendee();

Example 3

Deleting all ATTENDEE properties.

while( $valarm->deleteAttendee()) { continue; }

Get ATTENDEE

If set, returns property value(-s), otherwise bool false.

Format 1

calendarComponent::getAttendee()

output = attendeeValue1

Format 2

calendarComponent::getAttendee( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => attendeeValue1 , "params" => array( params2 ))

Format 3

calendarComponent::getAttendee( propOrderNo )

propOrderNo = (int) specific property value

output = attendeeValue1

Example

$attendee = $valarm->getAttendee();

Set ATTENDEE

Set property value. If exist, default parameter values are removed after input (params2). Property value must be prefixed by protocol (ftp://, http://,mailto:, file:// ref. rfc 1738 ), if missing, "mailto:" is set (indicating an internet mail address). Also MEMBER and DIR parameters must be prefixed by protocol. DELEGATED-TO, DELEGATED-FROM, SENT-BY parameters must use protocol "mailto:", prefixed if missing (indicating an internet mail address).

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

The CN, ROLE, PARTSTAT, RSVP, CUTYPE, MEMBER, DELEGATED-TO,DELEGATED-FROM, SENT-BY and DIR properties are not accepted (i.e. removed) in a "VFREEBUSY" or "VALARM" "ATTENDEE" property content.

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setAttendee( attendeeValue [, params [, propOrderNo ]] )

attendeeValue1 = (string) a calendar user address, a URI as defined by [RFC 1738] or any other IANA registered form for a URI. params2 = (array) ( [CUTYPE] [,MEMBER] [,ROLE] [,PARTSTAT] [,RVSP] [,DELEGATED-TO] [,DELEGATED-FROM] [,SENT-BY] [,CN] [,DIR] [,LANGUAGE] *[,xparams] ) CUTYPE = "CUTYPE" => "INDIVIDUAL" (An individual, Default) / "GROUP" (A group of individuals) / "RESOURCE" (A physical resource) / "ROOM" (A room resource) / "UNKNOWN" (Otherwise not known) / (string) x-name (Experimental type) / iana-token (string) (Other IANA registered type) MEMBER = "MEMBER" => array( *[ (string) "single member of the group or list membership"]) ROLE = "ROLE" => "CHAIR" (Indicates chair of the calendar entity) / "REQ-PARTICIPANT" (required participation, Default) / "OPT-PARTICIPANT" (optional participation) / "NON-PARTICIPANT" (information purposes only) / (string) x-name (Experimental role) / (string) iana-token (Other IANA role) PARTSTAT = Vcalendar::PARTSTAT => "NEEDS-ACTION" (Event needs action, Default) / "ACCEPTED" (Event accepted) / "DECLINED" (Event declined) / "TENTATIVE" (Event tentatively accepted) / "DELEGATED" (Event delegated) / "NEEDS-ACTION" (To-do needs action, Default) / "ACCEPTED" (To-do accepted) / "DECLINED" (To-do declined) / "TENTATIVE" (To-do tentatively accepted) / "DELEGATED" (To-do delegated) / "COMPLETED" (To-do completed. COMPLETED property has date/time completed) / "IN-PROCESS" (To-do in process of being completed) / "NEEDS-ACTION" (Journal needs action, Default) / "ACCEPTED" (Journal accepted) / "DECLINED" (Journal declined) / (string) x-name (Experimental status) / (string) iana-token (Other IANA registered status) RSVP = Vcalendar::RSVP => (string) "TRUE" / "FALSE", Default (reply expectation) DELEGATED-TO = "DELEGATED-TO" => array(*[(string) "single calendar user to specified by the property has delegated participation"]) DELEGATED-FROM = "DELEGATED-FROM" => array( *[ (string) "single calendar user that have delegated their participation to the calendar user specified by the property" ] ) SENT-BY = Vcalendar::SENT_BY => (string) single calendar user that is acting on behalf of the calendar user specified by the property" LANGUAGE = Vcalendar::LANGUAGE => (string) "lang*" (applies to the CN parameter value) CN = Vcalendar::CN => (string) "common name to be associated with the calendar user specified by the property" DIR = Vcalendar::DIR => (string) "reference to a directory entry associated with the calendar user specified by the property" xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

See rules in detail in RFC2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).

Example

$vevent->setAttendee( "attendee1@ical.net" ); $vevent->setAttendee( "attendee2@ical.net", [ Vcalendar::CUTYPE => "INDIVIDUAL", Vcalendar::MEMBER => [ "member1@ical.net", "member2@ical.net", "member3@ical.net" ], Vcalendar::ROLE => "CHAIR", Vcalendar::PARTSTAT => "ACCEPTED", Vcalendar::RSVP => "TRUE", Vcalendar::DELEGATED_TO => [ "part1@ical.net", "part2@ical.net", "part3@ical.net" ], Vcalendar::DELEGATED_FROM => [ "cio@ical.net", "vice.cio@ical.net" ], Vcalendar::SENT_BY => "secretary@ical.net", Vcalendar::LANGUAGE => "us-EN", Vcalendar::CN => "John Doe", Vcalendar::DIR => "http://www.ical.net/info.doc", "x-agenda" => "status reports", // xparam "x-time" => "15 min" // xparam ] );


[index] [top] [up]

3.2.8 CATEGORIES

This property defines the categories for a calendar component and is OPTIONAL and MAY occur more than once in VEVENT, VTODO and VJOURNAL components.

The value type for CATEGORIES is TEXT.

You can SORT calendar (components) on (asc) CATEGORIES values.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::CATEGORIES is available.

Create CATEGORIES

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createCategories()

Example

$str = $component->createCategories();

Delete CATEGORIES

Remove CATEGORIES from component.

Format

calendarComponent::deleteCategories()

Example 1

Delete (single/first) CATEGORIES property

$vevent->deleteCategories();

Example 2

Delete CATEGORIES property no 2.

$vevent->deleteCategories();

Example 3

Deleting all CATEGORIES properties.

while( $vevent->deleteCategories()) { continue; }

Get CATEGORIES

If set, returns property value(-s), otherwise bool false.

Format 1

calendarComponent::getCategories()

output = categoryValue1

Format 2

calendarComponent::getCategories( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => categories1 , "params" => params3 )

Format 3

calendarComponent::getCategories( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo CATEGORIES

Example

$categories = $valarm->getCategories();

Set CATEGORIES

Set property value.

In spite of the fact that CATEGORIES may contain a (comma separated) list of values, a strong recommendation is to split a CATEGORIES "list" into multiple single CATEGORIES entries.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setCategories( categories [, params [, propOrderNo ]] )

categories1 = (string) categoryValue / (array) ( *categoryValue ) categoryValue2 = (string) textual categories or subtypes of the calendar component, can be specified as a list of categories separated by the COMMA character params3 = (array) ( [Vcalendar::LANGUAGE => (string) "<lang*>"] *[, xparams] ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$vevent->setCategories( "project_x" );


[index] [top] [up]

3.2.9 CLASS

This property defines the access classification for a calendar component and is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO and VJOURNAL components.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::KLASS // note CLASS
- Kigkonsult\Icalcreator\Vcalendar::P_BLIC // note PUBLIC
- Kigkonsult\Icalcreator\Vcalendar::P_IVATE // note PRIVATE
- Kigkonsult\Icalcreator\Vcalendar::CONFIDENTIAL
are available.

Create CLASS

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createClass()

Example

$str = $component->createClass();

Delete CLASS

Remove CLASS from component.

Format

calendarComponent::deleteClass()

Example

$vjournal->deleteClass();

Get CLASS

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getClass()

output = classValue1

Format 2

calendarComponent::getClass( true )

output = array "value" => classValue1 , "params" => xparams2 )

Example

$class = $valarm->getClass();

Set CLASS

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setClass( classvalue [, xparams ] )

classvalue1 = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / (string) iana-token / (string) x-name xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$vevent->setClass( Vcalendar::CONFIDENTIAL );


[index] [top] [up]

3.2.10 COMMENT

This property specifies non-processing information intended to provide a comment to the calendar user and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL, VFREEBUSY, STANDARD and DAYLIGHT components.

The value type for COMMENT is TEXT.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::COMMENT
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create COMMENT

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createComment()

Example

$str = $component->createComment();

Delete COMMENT

Remove COMMENT from component.

Format

calendarComponent::deleteComment()

Example 1

Delete (single/first) COMMENT property

$vevent->deleteComment();

Example 2

Delete COMMENT property no 2.

$vevent->deleteComment( 2 );

Example 3

Deleting all COMMENT properties.

while( $vevent->deleteComment()) { continue; }

Get COMMENT

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getComment()

output = commentValue1

Format 2

calendarComponent::getComment( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => commentValue1 , "params" => params2 )

Format 3

calendarComponent::getComment( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo COMMENT

Example

$comment = $vevent->getComment();

Set COMMENT

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setComment( commentValue [, params [, propOrderNo ]] )

commentValue1 = (string) Value type Text params2 = array( Vcalendar::ALTREP => (string) "<an alternate text representation, URI>"], Vcalendar::LANGUAGE => (string) "lang*"] *(xparams ) ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$vevent->setComment( "this is a comment" );


[index] [top] [up]

3.2.11 COMPLETED

This property defines the date and time that a VTODO was actually completed and is OPTIONAL and MUST NOT occur more than once.

The value type for COMPLETED is UTC timezone DATE-TIME.

For methods and formatting, explore the CREATED property.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::CREATED is available.


[index] [top] [up]

3.2.12 CONTACT

The property is used to represent textual contact information or alternately a reference to textual contact information associated with the calendar component. The property is OPTIONAL and MUST NOT occur more than once in a VFREEBUSY or MAY occur more than once in VEVENT, VTODO and VJOURNAL components.

The value type for CONTACT is TEXT.

You can SORT calendar (components) on (asc) CONTACT values.

You can export calendar CONTACT values as vCards.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::CONTACT
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create CONTACT

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createContact()

Example

$str = $component->createContact();

Delete CONTACT

Remove CONTACT from component.

Format

calendarComponent::deleteContact()

Example 1

Delete (single/first) CONTACT property

$vevent->deleteContact();

Example 2

Delete CONTACT property no 2.

$vevent->deleteContact( 2 );

Example 3

Deleting all CONTACT properties.

while( $vevent->deleteContact()) { continue; }

Get CONTACT

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getContact()

output = contactValue1

Format 2

calendarComponent::getContact( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => contactValue1 , "params" => params2 )

Format 3

calendarComponent::getContact( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo CONTACT

Example

$contact = $vevent->getContact();

Set CONTACT

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setContact( contactValue [, params [, propOrderNo ]] )

contactValue1 = (string) Value type TEXT params2 = array( Vcalendar::ALTREP => (string) "<an alternate text representation, URI>"], Vcalendar::LANGUAGE => (string) "lang*"] *(xparams ) ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$c->setContact( "tel 012-34 56 789" )


[index] [top] [up]

3.2.13 CREATED

This property specifies the date and time that the calendar information was created by the calendar user agent in the calendar store. Note: This is analogous to the creation date and time for a file in the file system. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO and VJOURNAL components.

The value type for CREATED is UTC timezone DATE-TIME.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::CREATED is available.

Create CREATED

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createCreated()

Example

$str = $component->createCreated();

Delete CREATED

Remove CREATED from component.

Format

calendarComponent::deleteCreated()

Example

$vevent->deleteCreated();

Get CREATED

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getCreated()

output = createdDate1

Format 2

calendarComponent::getCreated( true )

output = array( "value" => createdDate1 , "params" => xparams2 )

Example

$created = $vevent->getCreated();

Set CREATED

Set property value. Input date is always a UTC timezone DATE-TIME or, if "offset" parameter is used, timezone is set to first found matching timezone.

The current UTC date-time is set if invoked without or empty value.

The method returns the class instance (static).

The method throws Exception on DateTime error.

Format

calendarComponent::setCreated( [ createdDate [, xparams ]] )

// Recommended formats createdDate = (object) DateTime class instance, will be set to UTC if not UTC timezone createdDate = (string) date/datetime string* // Supported but are objects for removal in next version createdDate1 = (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec , "tz" => timezone/offset ]] ) createdDate = (int) year , (int) month , (int) day [, (int) hour , (int) min , (int) sec ] createdDate = (array) ( (int) year , (int) month , (int) month , (int) day [, (int) hour , (int) min , (int) sec [, timezone/offset ]] ) // results in a UTC timezone DATE-TIME createdDate = (array) ( "timestamp" => (int) timestamp ) offset = (int) (+/-)HHmm[ss] // key prefix "X-" xparams2 = array( *[ (string) key => (string) value ] )
date/datetime string* please notice date restraints.

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtodo = $vcalendar->newVtodo(); try { $vtodo->setCreated( new DateTime( '2006-08-11 14:30:35 UTC' )); // 11 august 2006 14.30.35 UTC } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.14 DESCRIPTION

This property provides a more complete textual description of the calendar component, than that provided by the SUMMARY property (, analogous to a mail BODY). The property is OPTIONAL, MUST NOT occur more than once within VEVENT, VTODO or VALARM (PROCEDURE) but can be specified multiple times within a VJOURNAL calendar component. The property is REQUIRED in VALARM (DISPLAY, EMAIL) component.

The value type for DESCRIPTION is TEXT.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::DESCRIPTION
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create DESCRIPTION

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createDescription()

Example

$str = $component->createDescription();

Delete DESCRIPTION

Remove DESCRIPTION from component.

Format

calendarComponent::deleteDescription()

Example 1

Delete (single/first) DESCRIPTION property.

$vevent->deleteDescription();

Example 2

Delete DESCRIPTION property no 2.

$vjournal->deleteDescription( 2 );

Example 3

Deleting all DESCRIPTION properties.

while( $vjournal->deleteDescription()) { continue; }

Get DESCRIPTION

If set, returns property value(-s), otherwise bool false.

Format 1

calendarComponent::getDescription()

output = descriptionValue1

Format 2

calendarComponent::getDescription( null , true )

output = array( "value" => descriptionValue1 , "params" => params2 )

Example

$description = $vevent->getDescription();

Set DESCRIPTION

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setDescription( descriptionValue [, params [, propOrderNo ]] )

descriptionValue1 = (string) Value type TEXT params2 = array( Vcalendar::ALTREP => (string) "<an alternate text representation, URI>"], Vcalendar::LANGUAGE => (string) "lang*"] *(xparams ) ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$vevent->setDescription( "This is a description" );


[index] [top] [up]

3.2.15 DTEND

This property specifies the date and time that a calendar component ends. The property is OPTIONAL and MUST NOT occur more than once in VFREEBUSY and VEVENT. In VEVENT, it only occurs if DURATION NOT occurs.

The default value type for DTEND is DATE-TIME, can be set to a DATE value type.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::DTEND
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::TZID
are available.

The value type of the "DTEND" or "DUE" properties MUST match the value type of "DTSTART" property as defined in [RFC5545])

Notice that an end date without a time is in effect midnight of the day before the date, so for timeless dates, use the date following the event date for it to be correct. For an "all-day event" and using timeless dates, the DTEND is equal DTSTART plus one day, example all-day event (2007-12-01)
DTSTART;VALUE=DATE:20071201
DTEND;VALUE=DATE:20071202.

Create DTEND

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createDtend()

Example

$str = $component->createDtend();

Delete DTEND

Remove DTEND from component.

Format

calendarComponent::deleteDtend()

Example

$vevent->deleteDtend();

Get DTEND

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getDtend()

output = dtendDate1

Format 2

calendarComponent::getDtend( true )

output = array( "value" => dtendDate1 , "params" => params2 )

Example

$dtend = $vevent->getDtend();

Set DTEND

Set property value. If DATE value type is expected, "VALUE" = "DATE" must be set (in params2) otherwise DATE-TIME (default) value type is set.

Within the "VFREEBUSY" calendar component, the time MUST be specified in the UTC datetime zone.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateTime error.

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setDtend( dtendDate [, params2 ] )

// Recommended formats dtendDate = (object) DateTime class instance dtendDate = (string) date/datetime string* // Supported but are objects for removal in next version dtendDate1 = (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec [, "tz" => tz ]] ) dtendDate = (int) year , (int) month , (int) day [, (int) hour , (int) min , (int) sec [, tz ]] dtendDate = array( (int) year , (int) month , (int) day [, (int) hour , (int) min , (int) sec [, tz ]] ) dtendDate = (array) ( "timestamp" => (int) timestamp [,"tz" => tz]) // timestamp without tz will result in a UTC timezone tz = (string) <timezone identifier> / offset // timezone will be used as tzidparam (below), if tzidparam not set offset = (int) (+/-)HHmm[ss] params2 = (array) ([ tzidparam/datetimeparam/dateparam ] *[,xparams]) tzidparam = Vcalendar::TZID => (string) <timezone identifier> // output as local date-time with timezone identifier // if tzidparam="GMT"/"UTC" then // output date-time is suffixed by 'Z' datetimeparam = [ Vcalendar::VALUE => Vcalendar::DATE_TIME ] // default, output as date-time dateparam = [ Vcalendar::VALUE => Vcalendar::DATE ] // output as DATE, ex. all-day event xparams = [ (string) key => (string) value ] // key prefix "X-"
* please notice date restraints.

Example 1

try { $vevent->setDtend( new DateTime( '2006-08-11 16:30:00' )); // 11 august 2006 16.30.00 local date } catch( Exception $e ) { die( $e->getMessage()); }

Example 2

End of an all-day event.

use Kigkonsult\Icalcreator\Vcalendar; try { $vevent->setDtend( '20060811', [ Vcalendar::VALUE => Vcalendar::DATE ] ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 3

Will output: DTEND;TZID=Europe/Stockholm:20060811T093000

try { $vevent->setDtend( new DateTime( '2006-08-11 09:30:00', new DateTImeZone( 'Europe/Stockholm' )); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.16 DTSTAMP

The property indicates the date/time the Vcalendar instance was created and is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components. However, DTSTAMP is AUTOMATICALL§Y GENERATED in iCalcreator when creating a component.

DTSTAMP may be required when importing iCal formatted information into some calendar software
(MS etc.), as well as (calendar) x-properties "X-WR-CALNAME", "X-WR-CALDESC" and
"X-WR-TIMEZONE", METHOD property (value PUBLISH etc.) and the (also auto created) UID property.

The value type for DTSTAMP is UTC timezone DATE-TIME.

For methods and formatting, explore the CREATED property.

You can SORT calendar (components) on (asc) DTSTAMP values.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::DTSTAMP is available.


[index] [top] [up]

3.2.17 DTSTART

This property specifies when the calendar component begins. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components. The property is REQUIRED, but MUST NOT occur more than once in STANDARD and DAYLIGHT components.

The default value type for DTSTART is DATE-TIME, can be set to a DATE value type.

For an "all-day event" and using timeless dates, example (2007-12-01)
DTSTART;VALUE=DATE:20071201
DTEND;VALUE=DATE:20071202. // opt., in effect midnight of the day before the date!!

For methods and formatting, explore the DTEND property.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::DTSTART
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::TZID
are available.


[index] [top] [up]

3.2.18 DUE

This property defines the date and time when a VTODO is expected to be completed and is OPTIONAL and MUST NOT occur more than once and only if DURATION NOT occurs.

The default value type for DUE is DATE-TIME, can be set to a DATE value type.

The value type of the "DTEND" or "DUE" properties MUST match the value type of "DTSTART" property as defined in [RFC5545])

For methods and formatting, explore the DTEND property.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::DUE
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::TZID
are available.


[index] [top] [up]

3.2.19 DURATION

The property specifies a positive duration of time.

In a VEVENT
it is OPTIONAL and MUST NOT occur more than once and MUST NOT occur in pair with DTEND. If one occurs, so MUST NOT the other.
In a VTODO
it is OPTIONAL and MUST NOT occur more than once and MUST NOT occur in pair with DUE. If one occurs, so MUST NOT the other.
In a VFREEBUSY
it is OPTIONAL and MUST NOT occur more than once. ([RFC2445])
it can not appear. ([RFC5545])
In a VALARM
it is OPTIONAL and MUST NOT occur more than once and MUST occur in pair with TRIGGER. If one occurs, so MUST the other.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::DURATION is available.

Create DURATION

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createDuration()

Example

$str = $component->createDuration();

Delete DURATION

Remove DURATION from component.

Format

calendarComponent::deleteDuration()

Example

$valarm->deleteDuration();

Get DURATION

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getDuration()

output = duration1

Format 2

calendarComponent::getDuration( true )

output = array( "value" => duration1 , "params" => xparams2 )

Example

$duration = $vtodo->getDuration();

option

If (1st) argument is true and a 2nd is used and set to true, returned output is in a DATE-TIME output format (like DTEND / DUE), based on DTSTART value with the added DURATION value (incl. opt. timezone).

Set DURATION

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateInterval error.

Format

calendarComponent::setDuration( duration [, xparams ] )

// Recommended formats duration = (object) DateInterval class instance duration = (string) dur-value = ["+"] "P" (dur-date/dur-time/dur-week) like "P15DT5H0M20S" dur-date = dur-day [dur-time] dur-time = "T" (dur-hour / dur-minute / dur-second) dur-week = 1*DIGIT "W" dur-hour = 1*DIGIT "H" [dur-minute] dur-minute = 1*DIGIT "M" [dur-second] dur-second = 1*DIGIT "S" dur-day = 1*DIGIT "D" // Supported but are objects for removal in next version duration1 = (array) ( "week" => (int) week ) duration1 = array ( "day" => (int) day ) [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec ]) duration = (array) ( "sec" => (int) sec ) duration = (array) ( (int) week/false [, (int) day/false [, (int) hour , (int) min , (int) sec ]] ) duration = (int) week/false [, (int) day/false [, (int) hour , (int) min , (int) sec ]] xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example 1

One day duration.

try { $vtodo->setDuration( new DateInterval( "P1D" )); } catch( Exception $e ) { die( $e->getMessage()); }

Example 2

Four hours duration.

try { $vtodo->setDuration( "PT4H" ); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.20 EXDATE

This property defines the list of date/time exceptions for a recurring calendar component and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL components.

The default value type for EXDATE is DATE-TIME, can be set to a DATE value type.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::EXDATE
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
are available.

Create EXDATE

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createExdate()

Example

$str = $component->createExdate();

Delete EXDATE

Remove EXDATE from component.

Format

calendarComponent::deleteExdate()

Example 1

$vtodo->deleteExdate();

Example 2

Delete EXDATE property no 2.

$vjournal->deleteExdate( 2 );

Example 3

Deleting all EXDATE properties.

while( $vjournal->deleteExdate()) { continue; }

Get EXDATE

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getExdate()

output = exdates1 (with date1)

Format 2

calendarComponent::getExdate( propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( "value" => exdates1 (with date1) , "params" => xparams2 )

Example

$exdate = $vtodo->getExdate();

Set EXDATE

Set property value.

The value type for EXDATE should match the DTSTART value type.

If no "VALUE" value type is set, DATE-TIME (default) value type is set.

If timezone in 1st date, all remaining dates are within this timezone and param "TZID" is set.

EXDATEs are automatically sorted in ascending order (Y-m-d[-H-i-s]).

In spite of the fact that EXDATE may contain a (comma separated) list of values, a strong recommendation is to split an EXDATE "list" into multiple single EXDATE entries. (But if you do, don't mix timezones, may result in incorrect date values.)

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateTime error.

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setExdate( exdates [, params [, propOrderNo ]] )

exdates1 = date / (array) ( date *[, date ] ) // Recommended formats date = (object) DateTime class instance date = (string) date/datetime string* // Supported but are objects for removal in next version date = array( (int) year , (int) month , (int) day [, (int) hour , (int) min , (int) sec [, tz ]] ) date1 = (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec [, "tz" => tz ]] ) date = (array) ( "timestamp" => (int) timestamp [, "tz" => tz]) // timestamp without tz will result in a UTC timezone DATE-TIME tz = (string) <timezone identifier> / offset // offset will be replace by first found matching timezone // timezone will be used as tzidparam (below), if tzidparam not set offset = (int) (+/-)HHmm[ss] params2 = (array) ([(datetimeparam/dateparam) / tzidparam] *[,xparams]) datetimeparam = [ Vcalendar::VALUE => Vcalendar::DATE_TIME ] // default, date-time output dateparam = [ Vcalendar::VALUE => Vcalendar::DATE ] // output as DATE tzidparam = [ Vcalendar::TZID => (string) <timezone identifier> ] xparams = [ (string) key => (string) value ] // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc
* please notice date restraints.

Example

Exclude 2006-08-11 from the recurrence pattern.

use Kigkonsult\Icalcreator\Vcalendar; try { $vevent->setExdate( [ new DateTime( '2006-08-11' ) ], [ Vcalendar::VALUE => Vcalendar::DATE ] ); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.21 EXRULE

This property defines a rule or repeating pattern for an exception to a recurrence set and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL components.

EXRULE is deprecated in [RFC5545]!

Uses the methods and formats as RRULE.


[index] [top] [up]

3.2.22 FREEBUSY

The property defines one or more free or busy time intervals in a VFREEBUSY calendar component.

The value type for FREEBUSY is PERIOD. A PERIOD is DATE-TIME/DATE-TIME or DATE-TIME/duration and in the UTC timezone

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::FREEBUSY
- Kigkonsult\Icalcreator\Vcalendar::FBTYPE
- Kigkonsult\Icalcreator\Vcalendar::FREE
- Kigkonsult\Icalcreator\Vcalendar::BUSY
- Kigkonsult\Icalcreator\Vcalendar::BUSY_UNAVAILABLE
- Kigkonsult\Icalcreator\Vcalendar::BUSY_TENTATIVE
are available.

Create FREEBUSY

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createFreebusy()

Example

$str = $component->createfreebusy();

Delete FREEBUSY

Remove FREEBUSY from component.

Format

calendarComponent::deleteFreebusy()

Example 1

Delete (single/first) FREEBUSY property

$vfreebusy->deleteFreebusy();

Example 2

Delete FREEBUSY property no 2.

$vfreebusy->deleteFreebusy( 2 );

Example 3

Deleting all FREEBUSY properties.

while( $vfreebusy->deleteFreebusy()) { continue; }

Get FREEBUSY

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getFreebusy()

output = array( "fbtype" => freebusytype1 , periods ) periods = periods2 with startdate/enddate2 below

Format 3

calendarComponent::getFreebusy( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => array("fbtype" => freebusytype1 ,periods) , "params" => xparams3 ) periods = periods2 with startdate/enddate2 below

Example

$freebusy = $vfreebusy->getFreebusy();

Set FREEBUSY

Set property value. FREEBUSY date is always a UTC timezone DATE-TIME in pair with another UTC timezone DATE-TIME or a DateInteval. Set dates within the same timezone, otherwise it may lead to unpredictable result;

In spite of the fact that FREEBUSYs may contain a (comma separated) list of values, a strong recommendation is to split a FREEBUSYs "list" into multiple single FREEBUSY entries.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateTime/DateInterval error.

Format

calendarComponent::setFreebusy( freebusytype,fbperiods [,xparams [,propOrderNo ]] )

freebusytype1 = one of Vcalendar::FREE / Vcalendar::BUSY // Default / Vcalendar::BUSY-UNAVAILABLE / Vcalendar::BUSY-TENTATIVE / x-name fbperiods = (array) ( periods2 )  periods2 = (array) ( startdate, enddate/duration ) / (array) ( *[, (array) ( startdate, enddate/duration )] ) // Recommended formats startdate/enddate = (object) DateTime class instance, will be set to UTC if not UTC timezone startdate/enddate = (string) datetime string* // Supported but are objects for removal in next version // startdate/enddate MUST be an UTC timezone DATE-TIME startdate/enddate = (array) ( (int) year , (int) month , (int) day , (int) hour , (int) min , (int) sec ) startdate/enddate2 = (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day , "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec ) // also output format startdate/enddate = (array) ( "timestamp" => (int) timestamp ) // results in a UTC timezone DATE-TIME // Recommended formats duration = (object) DateInterval class instance duration = (string) dur-value = ("+")"P"(dur-date/dur-time/dur-week) like "P15DT5H0M20S" dur-date = dur-day [dur-time] dur-time = "T" (dur-hour / dur-minute / dur-second) dur-week = 1*DIGIT "W" dur-hour = 1*DIGIT "H" [dur-minute] dur-minute = 1*DIGIT "M" [dur-second] dur-second = 1*DIGIT "S" dur-day = 1*DIGIT "D" // Supported but are objects for removal in next version duration = (array) ( (int) week / false [, (int) day / false , (int) hour , (int) min , (int) sec] ) duration = (array) ( "week" => (int) week / false [, "day" => (int) day / false [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec ]] ); // output format duration = (array) ( "sec" => (int) sec ) xparams3 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc
* please notice date restraints.

Example 1

See rules in detail in RFC2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar). The recommended way.

try { $freebusy->setFreebusy( Vcalendar::FREE, [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) [ ) $freebusy->setFreebusy( Vcalendar::FREE, [ new DateTime( "2003-03-03 03:03:03 UTC" ), new DateInterval( "P5DT5H5M5S" ) ], ) $freebusy->setFreebusy( Vcalendar::FREE, [ "4 April 2005 4:4:4 UTC", "P2D" ] ) ->setFreebusy( Vcalendar::BUSY, [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], ) ->setFreebusy( Vcalendar::BUSY, [ new DateTime( "2003-03-03 03:03:03 UTC" ), "P2D" ], ) ->setFreebusy( Vcalendar::BUSY, [ "4 April 2005 4:4:4 UTC", new DateInterval( "PT5H" ) ], ) ->setFreebusy( Vcalendar::BUSY, [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2003-03-03 03:03:03 UTC" ) ] ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 1

Works, but...

try { $freebusy->setFreebusy( Vcalendar::FREE, [ [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], [ new DateTime( "2003-03-03 03:03:03 UTC" ), new DateInterval( "P5DT5H5M5S" ) ], [ "4 April 2005 4:4:4 UTC", "P2D" ] ] ) ->setFreebusy( Vcalendar::BUSY, [ [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], [ new DateTime( "2003-03-03 03:03:03 UTC" ), "P2D" ], [ "4 April 2005 4:4:4 UTC", new DateInterval( "PT5H" ) ], [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2003-03-03 03:03:03 UTC" ) ] ] ); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.23 GEO

This property specifies information related to the global position for the activity specified by VEVENT and VTODO components and is OPTIONAL and MUST NOT occur more than once.

Value type for latitude and longitude is FLOAT.

Values for latitude and longitude shall be expressed as decimal fractions of degrees. Whole degrees of latitude shall be represented by a two-digit decimal number ranging from 0 through 90. Whole degrees of longitude shall be represented by a decimal number ranging from 0 through 180. When a decimal fraction of a degree is specified, it shall be separated from the whole number of degrees by a decimal point.

The output (float) latitude and longitude values are presented up to six decimals.

Using the non-standard directive "GEOLOCATION", iCalcreator returns output by combining the LOCATION and GEO property values, (separated by "/") and only if GEO is set).

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::GEO
- Kigkonsult\Icalcreator\Vcalendar::LATITUDE
- Kigkonsult\Icalcreator\Vcalendar::LONGITUDE
are available.

Create GEO

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createGeo()

Example

$str = $component->createGeo();

Delete GEO

Remove GEO from component.

Format

calendarComponent::deleteGeo()

Example

$vevent->deleteGeo();

Get GEO

If set, returns GEO property value (latitude/longitude) as prescribed in [RFC5545], otherwise bool false.

Format 1

calendarComponent::getGeo()

output = array( "latitude" => <latitude> , "longitude" => <longitude>))

Format 2

calendarComponent::getGeo( true )

output = array( "value" => array ( "latitude" => <latitude> , "longitude" => <longitude>)) , "params" => xparams1 )

Example

$geo = $vevent->getGeo();

Set GEO

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty values and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setGeo( latitude, longitude [, xparams ] )

latitude = (float) latitude longitude = (float) longitude xparams1 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$vevent->setGeo( 11.23456, -23.45678 );


[index] [top] [up]

3.2.24 LAST-MODIFIED

The property specifies the date and time that the information associated with the calendar component was last revised in the calendar store. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VTIMEZONE components.

The value type for LAST-MODIFIED is UTC timezone DATE-TIME.

For methods and formatting, explore the CREATED property.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::LAST_MODIFIED is available.


[index] [top] [up]

3.2.25 LOCATION

The property defines the intended venue for the activity defined by a calendar component. The property is OPTIONAL and MUST NOT occur more than once in VEVENT and VTODO components.

The value type for LOCATION is TEXT.

You can SORT calendar (components) on (asc) LOCATION values.

Using the non-standard directive "GEOLOCATION", iCalcreator returns output by combining the LOCATION and GEO property values, (separated by "/") and only if GEO is set).

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::LOCATION
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create LOCATION

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createLocation()

Example

$str = $component->createLocation();

Delete LOCATION

Remove LOCATION from component.

Format

calendarComponent::deleteLocation()

Example

$vevent->deleteLocation();

Get LOCATION

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getLocation()

output = location1

Format 2

calendarComponent::getLocation( true )

output = array( "value" => location1 , "params" => param2 )

Example

$location = $vevent->getLocation();

Set LOCATION

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setLocation( location [, param] )

location1 = (string) Value type TEXT params2 = (array) ( [ Vcalendar::ALTREP => (string) "<an alternate text representation, URI>"] [, Vcalendar::LANGUAGE => (string) "lang*"] *[, xparams ] ) xparams = (string) key => (string) value // key prefix "X-" lang* = as defined in [RFC5546]

Example

$vevent->setLocation( "Buckingham Palace" );


[index] [top] [up]

3.2.26 ORGANIZER

The property defines the organizer for a calendar component and is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components.

This value type for ORGANIZER is URI, a calendar user address.

You can SORT calendar (components) on (asc) ORGANIZER values.

You can export calendar ORGANIZER values as vCards.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::ORGANIZER
- Kigkonsult\Icalcreator\Vcalendar::CN
- Kigkonsult\Icalcreator\Vcalendar::DIR
- Kigkonsult\Icalcreator\Vcalendar::SENT_BY
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE

Create ORGANIZER

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createOrganizer()

Example

$str = $component->createOrganizer();

Delete ORGANIZER

Remove ORGANIZER from component.

Format

calendarComponent::deleteOrganizer()

Example

$vevent->deleteOrganizer();

Get ORGANIZER

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getOrganizer()

output = organizer1

Format 2

calendarComponent::getOrganizer( true )

output = array( "value" => organizer1 , "params" => params2 )

Example

$organizer = $vevent->getOrganizer();

Set ORGANIZER

Set property value. Property value must be prefixed by protocol ("ftp://", "http://, mailto:", "file://" etc, ref. rfc 1738), "mailto:" is prefixed if missing. Also DIR parameter must be prefixed by protocol. SENT-BY parameter must use protocol "mailto:", prefixed if missing.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setOrganizer( organizer [, params] )

organizer1 = (string) a calendar user address (cal-address), a URI as defined by [RFC 1738] or any other IANA registered form for a URI. params2 = (array) Vcalendar::LANGUAGE => (string) "lang*", // applies to the CN parameter value Vcalendar::CN => (string) "common name to be associated with the calendar user specified by the property", Vcalendar::DIR => (string) "reference to a directory entry associated with the calendar user specified by the property", Vcalendar::SENT_BY => (string) (cal-address, above) "single calendar user that is acting on behalf of the calendar user specified by the property", *xparams xparams = (string) key => (string) value // key prefix "X-" lang* = as defined in [RFC5546]

Example

$dir = "ldap://domain.com:6666/o=3DDC%20Comp,c=3DUS??(cn=3DJohn%20Doe)"; $vevent->setOrganizer( "ical@domain.com", [ Vcalendar::CN => "John Doe", Vcalendar::DIR => $dir, Vcalendar::SENT_BY => "secretary@domain.com", "X-Key1" => "X-Value1", "X-Key2" => "X-Value2" ] );


[index] [top] [up]

3.2.27 PERCENT-COMPLETE

This property is used by an assignee or delegatee of a VTODO to convey the percent completion of a VTODO to the Organizer and is OPTIONAL and MUST NOT occur more than once.

The property value is a positive integer between zero and one hundred. A value of "0" indicates the VTODO has not yet been started. A value of "100" indicates that the VTODO has been completed. Integer values in between indicate the percent partially complete.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::PERCENT_COMPLETE is available.

Create PERCENT-COMPLETE

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createPercentComplete()

Example

$str = $component->createPercentComplete();

Delete PERCENT-COMPLETE

Remove PERCENT-COMPLETE from component.

Format

calendarComponent::deletePercentcomplete()

Example

$vtodo->deletePercentcomplete()

Get PERCENT-COMPLETE

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getPercentcomplete()

output = percent1

Format 2

calendarComponent::getPercentcomplete( true )

output = array( "value" => percent1 , "params" => xparams2 )

Example

$percent = $vtodo->getPercentcomplete();

Set PERCENT-COMPLETE

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty (non-zero) value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setPercentcomplete( percent [, xparams ] )

percent1 = (int) Value type INTEGER xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$vtodo->setPercentcomplete( 90 );


[index] [top] [up]

3.2.28 PRIORITY

The property defines the relative priority for a calendar component and is OPTIONAL and MUST NOT occur more than once in VEVENT and VTODO components.

The priority is specified as an integer in the range zero to nine.
A value of zero (US-ASCII decimal 48) specifies an undefined priority.
A value of one (US-ASCII decimal 49) is the highest priority.
A value of two (US-ASCII decimal 50) is the second highest priority.
Subsequent numbers specify a decreasing ordinal priority.
A value of nine (US-ASCII decimal 58) is the lowest priority.

You can SORT calendar (components) on (asc) PRIORITY values.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::PRIORITY is available.

Create PRIORITY

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createPriority()

Example

$str = $component->createPriority();

Delete PRIORITY

Remove PRIORITY from component.

Format

calendarComponent::deletePriority()

Example

$vevent->deletePriority();

Get PRIORITY

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getPriority()

output = priority1

Format 2

calendarComponent::getPriority( true )

output = array( "value" => priority1 , "params" => xparams2 )

Example

$priority = $vevent->getPriority();

Set PRIORITY

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and if value is not an integer.

Format

calendarComponent::setPriority( priority [, xparams ] )

priority1 = (int) Value type INTEGER xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$vevent->setPriority( 3 );


[index] [top] [up]

3.2.29 RDATE

This property defines the list of date/times for a recurrence set and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL, STANDARD and DAYLIGHT components.

The default value type for RDATE is DATE-TIME, can be set to DATE or PERIOD (params2). In STANDARD and DAYLIGHT components, RDATE MUST be specified as a date-time value type with local time value.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::RDATE
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::PERIOD
are available.

Create RDATE

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createRdate()

Example

$str = $component->createRdate();

Delete RDATE

Remove RDATE from component.

Format

calendarComponent::deleteRdate()

Example 1

Delete (single/first) RDATE property.

$vtodo->deleteRdate();

Example 2

Delete RDATE property no 2.

$vjournal->deleteRdate( 2 );

Example 3

Delete all RDATE properties.

while( $vjournal->deleteRdate()) { continue; }

Get RDATE

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getRdate()

output = dates1

Format 2

calendarComponent::getRdate( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => dates1 , "params" => params2 )

Format 3

calendarComponent::getRdate( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo RDATE

Example

$rdates = $vevent->getRdate();

Set RDATE

Set property value.

The value type for RDATE should match the DTSTART value type.

If no "VALUE" value type is set, DATE-TIME (default) value type is set.

If no "TZID" is set in params and timezone in 1st date, all remaining dates are within this timezone and param "TZID" is set.

RDATEs are automatically sorted in ascending order (Y-m-d[-H-i-s]).

A RDATE may contain a (comma separated) list of date values, BUT, a strong recommendation is to split a RDATE "list" into multiple single RDATE entries. (But if you do, don't mix timezones, may result in incorrect date values.)

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateTime/DateInterval error.

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setRdate( dates [, params [, propOrderNo ]] )

dates1 = singledate / (array) ( *singledate ) / (array) ( date2 *[, date2 ] ) date2 = (array) ( startdate, enddate/duration ) singledate = date startdate = date enddate = date // Recommended formats date = (object) DateTime class instance date = (string) date/datetime string* // Supported but are objects for removal in next version date = (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec [, "tz" => tz ]] ) // output format date = (array) ( (int) year , (int) month , (int) day [, (int) int hour , (int) min , (int) day , tz ] ) date = (array) ( "timestamp" => (int) timestamp [, "tz" => tz ] ) // timestamp without tz will result in a UTC timezone DATE-TIME tz = <timezone identifier> / offset // offset will be replace by first found matching timezone // timezone will be used as tzidparam, if tzidparam not set offset = (int) (+/-)HHmm[ss] // Recommended formats duration = (object) DateInterval class instance duration = (string) dur-value = ("+")"P"(dur-date/dur-time/dur-week) like "P15DT5H0M20S" dur-date = dur-day [dur-time] dur-time = "T" (dur-hour / dur-minute / dur-second) dur-week = 1*DIGIT "W" dur-day = 1*DIGIT "D" dur-hour = 1*DIGIT "H" [dur-minute] dur-minute = 1*DIGIT "M" [dur-second] dur-second = 1*DIGIT "S" // Supported but are objects for removal in next version duration = (array) ( (int) week/false [, (int) day/false , (int) hour , (int) min , (int) sec] ) duration = (array) ([ "week" => (int) week / false ,] / [ "day" => (int) day / false [, "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec ]] ); // output format, only used keys duration = (array) ( "sec" => (int) sec ); params2 = ([tzidparam ( / datetimeparam / dateparam / periodparam )] *[, xparams ] ) tzidparam = [ Vcalendar::TZID => (string) <timezone identifier> ] // output as local DATE-TIME with timezone identifier // if tzidparam="GMT"/"UTC" then // output date-time is suffixed by 'Z' datetimeparam = [ Vcalendar::VALUE => Vcalendar::DATE_TIME ] // default, DATE-TIME dateparam = [ Vcalendar::VALUE => Vcalendar::DATE ] // required if DATE // required if PERIOD (datetime - datetime/duration) periodparam = [ Vcalendar::VALUE => Vcalendar::PERIOD ] xparams = [ (string) key => (string) value ] // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc
* please notice date restraints.

Example

See rules in detail in RFC5545 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).

use Kigkonsult\Icalcreator\Vcalendar; try { $vevent = $vcalendar->newVevent() // one recurrence date, if param VALUE is missing, DATE-TIME default ->setRdate( new DateTime( "2001-01-01 01:01:01 UTC" ) ) // two or more recurrence dates ->setRdate( [ new DateTime( "2001-01-01 01:01:01 UTC" ) new DateTime( "2002-02-02 02:02:02 UTC" ) ] [ Vcalendar::VALUE => Vcalendar::DATE_TIME ] ) // one PERIOD, startdate-duration, VALUE "PERIOD" required ->setRdate( [ [ new DateTime( "2002-02-02 02:02:02 UTC" ), new DateInterval( "PT5H5M5S" ) ] ], [ Vcalendar::VALUE => Vcalendar::PERIOD ] ) // one PERIOD, start- and endDate (accepted format for ONE period) ->setRdate( [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], [ Vcalendar::VALUE => Vcalendar::PERIOD ] ) // PERIOD, pairs of start- and endDates ->setRdate( [ [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], [ "3 March 2003 03.03.03 UTC", new DateTime( "2004-04-04 04:04:04 UTC" ) ] ], [ Vcalendar::VALUE => Vcalendar::PERIOD ] ) // PERIOD, pairs of start-/enddate and startdate-duration ->setRdate( [ [ new DateTime( "2001-01-01 01:01:01 UTC" ), new DateTime( "2002-02-02 02:02:02 UTC" ) ], [ "3 March 2003 03.03.03 UTC", new DateInterval( "PT7H" ) ] ], [ Vcalendar::VALUE => Vcalendar::PERIOD ] ) // start- and enddate as DATE ->setRdate( [ [ new DateTime( "2005-10-05 05:05:05 UTC" ), "2008-08-08 08:08:08 UTC" ) ] ], [ Vcalendar::VALUE => Vcalendar::DATE ] ); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.30 RECURRENCE-ID

This property is used in conjunction with the UID and SEQUENCE property to identify a specific instance of a recurring VEVENT, VTODO or VJOURNAL calendar component and is OPTIONAL and MAY NOT occur more than once.

The property value is the effective value of the DTSTART property of the recurrence instance. The default value type is DATE-TIME, can be set to DATE (params2).

For methods and formatting, explore the DTEND property.

The calendar method SORT with argument UID also use RECURRENCE-ID / SEQUENCE as sort parameters.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::RECURRENCE_ID
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DATE
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::TZID
are available.


[index] [top] [up]

3.2.31 RELATED-TO

The property is used to represent a relationship or reference between one calendar component and another and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL components.

The property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the UID property.

The value type for RELATED-TO is TEXT.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::RELATED_TO
- Kigkonsult\Icalcreator\Vcalendar::RELTYPE
- Kigkonsult\Icalcreator\Vcalendar::PARENT
- Kigkonsult\Icalcreator\Vcalendar::CHILD
- Kigkonsult\Icalcreator\Vcalendar::SIBLING
- available.

Create RELATED-TO

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createRelatedTo()

Example

$str = $component->createRelatedTo();

Delete RELATED-TO

Remove RELATED-TO from component.

Format

calendarComponent::deleteRelatedto()

Example 1

Delete /single/first) RELATED-TO property

$vtodo->deleteRelatedto()

Example 2

Delete RELATED-TO property no 2.

$vjournal->deleteRelatedto( 2 );

Example 3

Deleting all RELATED-TO properties.

while( $vjournal->deleteRelatedto()) { continue; }

Get RELATED-TO

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getRelatedto()

output = relid1

Format 2

calendarComponent::getRelatedto( propOrderNo/null , true )

propOrderNo = (int) specific property value

output = array( "value" => relid1 , "params" => params2 )

Format 3

calendarComponent::getRelatedto(propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo RELATED-TO

Example

$relatedId = $vtodo->getRelatedto();

Set RELATED-TO

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Set property value.

The method returns the class instance (static).

Format

calendarComponent::setRelatedto( relid [, params [, propOrderNo ]] )

relid1 = (string) Value type TEXT. params2 = (array) ( [ reltype ] *[, xparams] ) reltype = Vcalendar::RELTYPE => Vcalendar::PARENT (Default) / Vcalendar::CHILD / Vcalendar::SIBLING / (string) iana-token / (string) x-name xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc

Example

$vtodo->setRelatedto( "19960401-080045-4000F192713@host.com" );


[index] [top] [up]

3.2.32 REPEAT

This property defines the number of time the ALARM should be repeated, after the initial trigger. If the ALARM triggers more than once, then this property MUST be specified along with the DURATION property.

The value type for REPEAT is INTEGER.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::REPEAT is available.

Create REPEAT

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createRepeat()

Example

$str = $component->createRepeat();

Delete REPEAT

Remove REPEAT from component.

Format

calendarComponent::deleteRepeat()

Example

$valarm->deleteRepeat();

Get REPEAT

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getRepeat()

output = repeatTimes1

Format 2

calendarComponent::getRepeat( true )

output = array( "value" => repeatTimes1 , "params" => xparams2 )

Example

$repeat = $valarm->getRepeat();

Set REPEAT

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and if value is not an integer.

Format

calendarComponent::setRepeat( , repeatTimes [, xparams ] )

repeatTimes1 = (int) Value type INTEGER xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example

$valarm->setRepeat( 2 );


[index] [top] [up]

3.2.33 REQUEST-STATUS

This property defines the status code returned for a scheduling request and is OPTIONAL and MAY occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components.

The value type for REQUEST-STATUS is TEXT and consists of

a short return status component,
(in output) a PERIOD character separated 3-tuple of integers, ex 3.11
a longer return status description component
optionally a statusspecific data component

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::REQUEST_STATUS
- Kigkonsult\Icalcreator\Vcalendar::STATCODE
- Kigkonsult\Icalcreator\Vcalendar::STATDESC
- Kigkonsult\Icalcreator\Vcalendar::EXTDATA
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create REQUEST-STATUS

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createRequestStatus()

Example

$str = $component->createRequestStatus();

Delete REQUEST-STATUS

Remove REQUEST-STATUS from component.

Format

calendarComponent::deleteRequeststatus()

Example 1

Delete (single/first) REQUEST-STATUS property.

$vtodo->deleteRequeststatus();

Example 2

Delete REQUEST-STATUS property no 2.

$vjournal->deleteRequeststatus( 2 );

Example 3

Deleting all REQUEST-STATUS properties.

while( $vjournal->deleteRequeststatus()) { continue; }

Get REQUEST-STATUS

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getRequeststatus()

output = array( Vcalendar::STATCODE => statcode1, , Vcalendar::STATDESC => statdesc2 [ , Vcalendar::EXTDATA => extdata3 ] )

Format 2

calendarComponent::getRequeststatus( propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( "value" => array( Vcalendar::STATDESC => statcode1, Vcalendar::STATDESC => errtext2, [ Vcalendar::EXTDATA => extdata3 ] ), "params" => params4 )

Format 3

calendarComponent::getRequeststatus( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo REQUEST-STATUS

Example

$requestStatus = $vtodo->getRequeststatus();

Set REQUEST-STATUS

Set property value.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setRequeststatus( statcode, statdesc [,extdata/false [,params [,propOrderNo]]] )

statcode1 = (int) Hierarchical, numeric return status code (1*DIGIT "." 1*DIGIT 1*DIGIT) statdesc2 = (string) Textual status description extdata3 = (string) Textual exception data. For example, the offending property name and value or complete property line. params4 = (array) ( Vcalendar::LANGUAGE => (string) "lang*"] *xparams ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$vfreebusy->setRequeststatus( 2.00, "Invalid property value", "DTSTART:96-Apr-31" );


[index] [top] [up]

3.2.34 RESOURCES

This property defines the equipment or resources anticipated for an activity specified by a calendar entity and is OPTIONAL and MAY occur more than once in VEVENT and VTODO components.

The value type for RESOURCES is TEXT.

You can SORT calendar (components) on (asc) RESOURCES values.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::RESOURCES
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create RESOURCES

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createResources()

Example

$str = $component->createResources();

Delete RESOURCES

Remove RESOURCES from component.

Format

calendarComponent::deleteResources()

Example 1

Delete (single/first) RESOURCES property.

$vevent->deleteResources();

Example 2

Delete RESOURCES property no 2.

$vevent->deleteResources( 2 );

Example 3

Delete all RESOURCES properties.

while( $vevent->deleteResources()) { continue; }

Get RESOURCES

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getResources()

output = resources1

Format 2

calendarComponent::getResources( propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( "value" => resources1 , "params" => params2 )

Format 3

calendarComponent::getResources( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo RESOURCES

Example

$resources = $vtodo->getResources();

Set RESOURCES

Set property value.

In spite of the fact that RESOURCES may contain a (comma separated) list of values, a strong recommendation is to split a RESOURCES "list" into multiple single RESOURCES entries.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setResources( resources [, params [, propOrderNo ]] )

resources1 = (string) resource / (array) ( *resource ) resource = (string) textual resources or subtypes of the calendar component, can be specified as a list of resources separated by the COMMA character. params2 = (array) ( Vcalendar::ALTREP => (string) "<an alternate text representation, URI>", Vcalendar::LANGUAGE => (string) "lang*", *xparams ) xparams = (string) key => (string) value // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

$vevent->setResources( "COMPUTER PROJECTOR" );


[index] [top] [up]

3.2.35 RRULE

This property defines a rule or repeating pattern for recurring EVENTs, TODOs, STANDARD or DAYLIGHT definitions and is OPTIONAL and MAY occur more than once ([RFC2445]), SHOULD NOT occur more than once ([RFC5545]).

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::RRULE
- Kigkonsult\Icalcreator\Vcalendar::EXRULE
- Kigkonsult\Icalcreator\Vcalendar::FREQ
- Kigkonsult\Icalcreator\Vcalendar::UNTIL
- Kigkonsult\Icalcreator\Vcalendar::COUNT
- Kigkonsult\Icalcreator\Vcalendar::INTERVAL
- Kigkonsult\Icalcreator\Vcalendar::BYSECOND
- Kigkonsult\Icalcreator\Vcalendar::BYMINUTE
- Kigkonsult\Icalcreator\Vcalendar::BYHOUR
- Kigkonsult\Icalcreator\Vcalendar::BYDAY
- Kigkonsult\Icalcreator\Vcalendar::BYMONTHDAY
- Kigkonsult\Icalcreator\Vcalendar::BYYEARDAY
- Kigkonsult\Icalcreator\Vcalendar::BYWEEKNO
- Kigkonsult\Icalcreator\Vcalendar::BYMONTH
- Kigkonsult\Icalcreator\Vcalendar::BYSETPOS
- Kigkonsult\Icalcreator\Vcalendar::WKST
- Kigkonsult\Icalcreator\Vcalendar::SECONDLY
- Kigkonsult\Icalcreator\Vcalendar::MINUTELY
- Kigkonsult\Icalcreator\Vcalendar::HOURLY
- Kigkonsult\Icalcreator\Vcalendar::DAILY
- Kigkonsult\Icalcreator\Vcalendar::WEEKLY
- Kigkonsult\Icalcreator\Vcalendar::MONTHLY
- Kigkonsult\Icalcreator\Vcalendar::YEARLY
- Kigkonsult\Icalcreator\Vcalendar::DAY
- Kigkonsult\Icalcreator\Vcalendar::SU
- Kigkonsult\Icalcreator\Vcalendar::MO
- Kigkonsult\Icalcreator\Vcalendar::TU
- Kigkonsult\Icalcreator\Vcalendar::WE
- Kigkonsult\Icalcreator\Vcalendar::TH
- Kigkonsult\Icalcreator\Vcalendar::FR
- Kigkonsult\Icalcreator\Vcalendar::SA
are available.

Create RRULE

If set, returns iCal formatted string, otherwise null.

Format

calendarComponent::createRrule()

Example

$str = $component->createRrule();

Delete RRULE

Remove RRULE from component.

Format

calendarComponent::deleteRrule()

Example 1

Delete (single/first) RRULE property.

$vevent->deleteRrule();

Example 2

Delete RRULE property no 2.

$vevent->deleteRrule( 2 );

Example 3

Delete all RRULE properties.

while( $vevent->deleteRrule()) { continue; }

Get RRULE

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getRrule()

output = recur1

Format 2

calendarComponent::getRrule( propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( "value" => recur1 , "params" => xparams2 )

Format 3

calendarComponent::getRrule( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo RRULE

Example

$rrules = $vtodo->getRrule();

Set RRULE

Set property single value, "RECUR", multiple values not allowed.

The "RECUR" property SHOULD NOT occur more than once in a component.

The method returns the class instance (static).

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), Exception on DateTime error.

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setRrule( recur [, xparams [, propOrderNo ]] )

See rules in detail in RFC2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).

recur1 = (array) ( Vcalendar::FREQ => freq, // either UNTIL or COUNT may appear in a "recur", but UNTIL and COUNT MUST NOT occur in the same "recur" Vcalendar::UNTIL "=>" >enddate, Vcalendar::COUNT "=>" 1*DIGIT, // the rest of these keywords are optional, but MUST NOT occur more than once Vcalendar::INTERVAL "=>" 1*DIGIT, Vcalendar::BYSECOND "=>" byseclist, Vcalendar::BYMINUTE "=>" byminlist, Vcalendar::BYHOUR "=>" byhrlist, Vcalendar::BYDAY "=>" bywdaylist, Vcalendar::BYMONTHDAY "=>" bymodaylist, Vcalendar::BYYEARDAY "=>" byyrdaylist, Vcalendar::BYWEEKNO "=>" bywknolist, Vcalendar::BYMONTH "=>" bymolist, Vcalendar::BYSETPOS "=>" bysplist, Vcalendar::WKST "=>" weekday ] x-name "=>" (string) text ] ) freq = Vcalendar::SECONDLY" / Vcalendar::MINUTELY / Vcalendar::HOURLY / Vcalendar::DAILY / Vcalendar::WEEKLY / Vcalendar::MONTHLY / Vcalendar::YEARLY enddate = date // a DATE value or a UTC timezone DATE-TIME value // Recommended formats date = (object) DateTime class instance, will be set to UTC if not UTC timezone date = (string) date/datetime string* // Supported but are objects for removal in next version date = [ "year" => (int) year, "month" => (int) month, "day" => (int) day, [ "hour" => (int) hour, "min" => (int) min, "sec" => (int) sec ] ] date = [ "timestamp" => (int) timestamp ] // results in a UTC timezone DATE-TIME byseclist = seconds byseclist = (array) (seconds *(, seconds )) seconds = 1DIGIT / 2DIGIT ;0 to 59 byminlist = minutes byminlist = (array) ( minutes *(, minutes )) minutes = 1DIGIT / 2DIGIT ;0 to 59 byhrlist = hour byhrlist = (array) ( hour *(, hour )) hour = 1DIGIT / 2DIGIT ;0 to 23 bywdaylist = weekdaynum bywdaylist = (array) ( weekdaynum *("," weekdaynum )) weekdaynum = (array) ( [([plus] ordwk / minus ordwk)], "DAY" => weekday ) plus = "+" minus = "-" ordwk = 1DIGIT / 2DIGIT ;1 to 53 // Vcalander::SU etc available weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA" ; Corresponding to ; SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, ; FRIDAY and SATURDAY days of the week. bymodaylist = monthdaynum bymodaylist = (array) ( monthdaynum *(, monthdaynum )) monthdaynum = ( [plus] ordmoday ) / ( minus ordmoday ) ordmoday = 1DIGIT / 2DIGIT ;1 to 31 byyrdaylist = yeardaynum byyrdaylist = (array) ( yeardaynum *(, yeardaynum )) yeardaynum = ( [plus] ordyrday ) / ( minus ordyrday ) ordyrday = 1DIGIT / 2DIGIT / 3DIGIT ;1 to 366 bywknolist = weeknum bywknolist = (array) ( weeknum *(, weeknum )) weeknum = ( [plus] ordwk ) / ( minus ordwk ) bymolist = monthnum bymolist = (array) ( monthnum *(, monthnum )) monthnum = 1DIGIT / 2DIGIT ;1 to 12 bysplist = setposday bysplist = (array) ( setposday *(, setposday )) setposday = yeardaynum xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc
* please notice date restraints.

Example

try { $vevent->setRrule( [ Vcalendar::FREQ => Vcalendar::MONTHLY, Vcalendar::UNTIL => new DateTime( "20060831" ), // DATE, if DATE-TIME, UTC timezone Vcalendar::INTERVAL => 2, Vcalendar::WKST => Vcalendar::SU, Vcalendar::BYSECOND => 2, Vcalendar::BYMINUTE => [ 2, -4, 6 ], // (*) Vcalendar::BYHOUR => [ 2, 4, -6 ], // (*) Vcalendar::BYMONTHDAY => -2, // (*) Vcalendar::BYYEARDAY => 2, // (*) Vcalendar::BYWEEKNO => [ 2, -4, 6 ], // (*) Vcalendar::BYMONTH => 2, // (*) Vcalendar::BYSETPOS => [ 2, -4, 6 [, // (*) Vcalendar::BYDAY => [ // (**) [ -2, Vcalendar::DAY => Vcalendar::WE ], [ 3, Vcalendar::DAY => Vcalendar::TH ], [ 5, Vcalendar::DAY => Vcalendar::FR ], [ Vcalendar::DAY => Vcalendar::MO ] ], [ "x-key" => "xparamValue" ] ); } catch( Exception $e ) { die( $e->getMessage()); } $vtodo->setRrule( [ Vcalendar::FREQ => Vcalendar::WEEKLY, Vcalendar::COUNT => 2, Vcalendar::INTERVAL => 2, Vcalendar::WKST => Vcalendar::SU, Vcalendar::BYSECOND => [ -2, 4, 6 ], // (*) Vcalendar::BYMINUTE => -2, // (*) Vcalendar::BYHOUR => 2, // (*) Vcalendar::BYMONTHDAY => [ 2, -4, 6 ], // (*) Vcalendar::BYYEARDAY => [ -2, 4, 6 ], // (*) Vcalendar::BYWEEKNO => -2, // (*) Vcalendar::BYMONTH => [ 2, 4, -6 ], // (*) Vcalendar::BYSETPOS => -2, // (*) Vcalendar::BYday => [ 5, Vcalendar::DAY; => Vcalendar::WE ], // (**) ], [ "x-key" => "xparamValue" ] ); // (*) single value/array of values // (**) single value array /array of arrays


[index] [top] [up]

3.2.36 SEQUENCE

This property defines the revision sequence number of the calendar component within a sequence of revisions. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO and VJOURNAL components.

It is monotonically incremented by the ORGANIZER's CUA (Calendar User Agent) each time the ORGANIZER makes a significant revision to the calendar component.

When the ORGANIZER makes changes to one of The following properties, the sequence number MUST be incremented: DTSTART, DTEND, DUE, RDATE, RRULE, EXDATE, EXRULE, STATUS. In addition, changes made by the ORGANIZER to other properties can also force the sequence number to be incremented. The ORGANIZER CUA MUST increment the sequence number when ever it makes changes to properties in the calendar component that the ORGANIZER deems will jeopardize the validity of the participation status of the Attendees. For example, changing the location of a meeting from one locale to another distant locale could effectively impact the participation status of the Attendees.

The value type of SEQUENCE is INTEGER.

The calendar method SORT with argument UID also use RECURRENCE-ID / SEQUENCE as sort parameters.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::SEQUENCE is available.

Create SEQUENCE

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createSequence()

Example

$str = $component->createSequence();

Delete SEQUENCE

Remove SEQUENCE from component.

Format

calendarComponent::deleteSequence()

Example

$vtodo->deleteSequence();

Get SEQUENCE

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getSequence()

output = sequence1

Format 2

calendarComponent::getSequence( true )

output = array( "value" => sequence1 , "params" => xparams2 )

Example

$sequence = $vtodo->getSequence();

Set SEQUENCE

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and if value is not an integer.

Format

calendarComponent::setSequence( [, sequence [, xparams ]] )

sequence1 = (int) Value type INTEGER xparams2 = (array) ( *[ (string) key => (string) value ] ) // key prefix "X-"

Example 1

$vevent->setSequence( 2 ); // set sequence number to 2

Example 2

$vevent->setSequence(); // force sequence number to be set to 0 // or, if sequence exists, incremented by 1


[index] [top] [up]

3.2.37 STATUS

This property defines the overall status or confirmation for the calendar component. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO and VJOURNAL components.

You can SORT calendar (components) on (asc) STATUS values.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::STATUS
- Kigkonsult\Icalcreator\Vcalendar::COMPLETED
- Kigkonsult\Icalcreator\Vcalendar::CANCELLED
- Kigkonsult\Icalcreator\Vcalendar::CONFIRMED
- Kigkonsult\Icalcreator\Vcalendar::DRAFT
- Kigkonsult\Icalcreator\Vcalendar::F_NAL // note FINAL
- Kigkonsult\Icalcreator\Vcalendar::IN_PROCESS
- Kigkonsult\Icalcreator\Vcalendar::NEEDS_ACTION
- Kigkonsult\Icalcreator\Vcalendar::TENTATIVE
are available.

Create STATUS

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createStatus()

Example

$str = $component->createStatus();

Delete STATUS

Remove STATUS from component.

Format

calendarComponent::deleteStatus()

Example

$vtodo->deleteStatus();

Get STATUS

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getStatus()

output = status1

Format 2

calendarComponent::getStatus( true )

output = array( "value" => status1 , "params" => xparams2 )

Example

$status = $vtodo->getStatus();

Set STATUS

Set property value.

The method throws InvalidArgumentException on
- empty value and config ALLOWEMPTY is set to false (default true),
- invalid value (below).

Format

calendarComponent::setStatus( status [, xparams ] )

// Status values for a VEVENT status1 = Vcalendar::TENTATIVE // Indicates event is tentative / Vcalendar::CONFIRMED // Indicates event is definite / Vcalendar::CANCELLED // Indicates event was cancelled // Status values for VTODO status1 = Vcalendar::NEEDS_ACTION // Indicates to-do needs action / Vcalendar::COMPLETED // Indicates to-do completed / Vcalendar::IN_PROCESS // Indicates to-do in process of / Vcalendar::CANCELLED // Indicates to-do was cancelled // Status values for VJOURNAL status1 = Vcalendar::DRAFT // Indicates journal is draft / Vcalendar::F_NAL; // Indicates journal is final / Vcalendar::CANCELLED // Indicates journal is removed xparams2 = [ (string) key => (string) value ] // key(s) prefix "X-"

Example

$vevent->setStatus( "COMPLETED" );


[index] [top] [up]

3.2.38 SUMMARY

This property defines a short ("one line") summary or subject for the calendar component. (In "[RFC5545], Recommended Practices", up to 255 characters) (, analogous to a mail SUBJECT). The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO and VJOURNAL components. The property is REQUIRED and MUST occur once in VALARM (EMAIL) calendar component.

The value type for SUMMARY is TEXT.

You can SORT calendar (components) on (asc) SUMMARY values.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::SUMMARY
- Kigkonsult\Icalcreator\Vcalendar::ALTREP
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create SUMMARY

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createSummary()

Example

$str = $component->createSummary();

Delete SUMMARY

Remove SUMMARY from component.

Format

calendarComponent::deleteSummary()

Example

$vevent->deleteSummar();

Get SUMMARY

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getSummary()

output = summary1

Format 2

calendarComponent::getSummary( true )

output = array( "value" => summary1 , "params" => params2 )

Example

$summary = $vtodo->getSummary();

Set SUMMARY

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Parameters will be ordered as prescribed in [RFC5545].

Format

calendarComponent::setSummary( summary [, params ] )

summary1 = (string) Value type TEXT, a short, one line summary about the activity or journal entry. params2 = array( Vcalendar::ALTREP => (string) "<an alternate text representation, URI>", Vcalendar::LANGUAGE => (string) "lang*", *xparams ) xparams = (string) key => (string) value // key prefix "X-" lang* = as defined in [RFC5546]

Example

$vevent->setSummary( "This is a summary" );


[index] [top] [up]

3.2.39 TRANSP

This property defines whether an EVENT is transparent or not to busy time searches and is OPTIONAL and MUST NOT occur more than once.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::TRANSP
- Kigkonsult\Icalcreator\Vcalendar::OPAQUE
- Kigkonsult\Icalcreator\Vcalendar::TRANSPARENT
are available.

Create TRANSP

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createTransp()

Example

$str = $component->createTransp();

Delete TRANSP

Remove TRANSP from component.

Format

calendarComponent::deleteTransp()

Example

$vevent->deleteTransp();

Get TRANSP

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getTransp( )

output = transp1

Format 2

calendarComponent::getTransp( true )

output = array( "value" => transp1 , "params" => xparams2 )

Example

$transp = $vtodo->getTransp();

Set TRANSP

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setTransp( transp [, xparams ] )

transp1 = Vcalendar::OPAQUE / Vcalendar::TRANSPARENT xparams2 = (array) *( (string) key => (string) value ) // key prefix "X-"

Example

$vevent->setTransp( "TRANSPARENT" );


[index] [top] [up]

3.2.40 TRIGGER

This property specifies when an ALARM will trigger and is REQUIRED and MUST NOT occur more than once.

The default value type is DURATION. The value type can be set to a DATE-TIME value type, in which case the value MUST specify an UTC timezone DATE-TIME value.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::TRIGGER
- Kigkonsult\Icalcreator\Vcalendar::VALUE
- Kigkonsult\Icalcreator\Vcalendar::DURATION
- Kigkonsult\Icalcreator\Vcalendar::DATE_TIME
- Kigkonsult\Icalcreator\Vcalendar::RELATED
- Kigkonsult\Icalcreator\Vcalendar::START
- Kigkonsult\Icalcreator\Vcalendar::END
are available.

Create TRIGGER

If set, returns [RFC5545] formatted string, otherwise null.

Format

valarm::createTrigger()

Example

$str = $component->createTrigger();

Delete TRIGGER

Remove TRIGGER from component.

Format

valarm::deleteTrigger()

Example

$valarm->deleteTrigger();

Get TRIGGER

If set, returns property value, otherwise bool false.

Format 1

valarm::getTrigger()

output = duration1/date3

Format 2

valarm::getTrigger( true )

output = array( "value" => duration1/date3 ) , "params" => params4 )

Example

$trigger = $valarm->getTrigger();

Set TRIGGER

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and on DateTime/DateInterval error.

Format 1

valarm::setTrigger( duration1 [, params4 ] )

Format 2

valarm::setTrigger( duration2 [, params4 ] )

Format 3

valarm::setTrigger( date3 [, params4 ] )

Format 4

Note, subject for removal in next major version.

valarm::setTrigger( (int) year / null (int) month / null, (int) day / null, [ (int) week / null, [ (int) hour / null, (int) min / null, (int) sec / null, relatedStart, before, [ params4 ]]]]] )

// Recommended formats (opt used with params4, below) duration1 = (object) DateInterval class instance duration1 = (string) dur-value = (["+"]/"-")"P"(dur-date/dur-time/dur-week) like "P1DT2H3M4S" dur-date = dur-day [dur-time] dur-time = "T" (dur-hour / dur-minute / dur-second) dur-week = 1*DIGIT "W" dur-day = 1*DIGIT "D" dur-hour = 1*DIGIT "H" [dur-minute] dur-minute = 1*DIGIT "M" [dur-second] dur-second = 1*DIGIT "S" // Supported but are objects for removal in next version duration2 = [ "week" => (int) week, "relatedStart" => relatedStart, "before" => before ] duration2 = [ "day" => (int) day, "hour" => (int) hour, "min" => (int) min, "sec" => (int) sec, "relatedStart" => relatedStart, "before" => before ] relatedStart = (bool) true : related start (default), false : related end before = (bool) true : before relatedStart (default), false : after relatedStart // Recommended formats date3 = (object) DateTime class instance, will be set to UTC if not UTC timezone date3 = (string) datetime string* // Supported but are objects for removal in next version date3 = [ "year" => (int) year, // UTC timezone DATE-TIME "month" => (int) month, "day" => (int) day, [, "hour" => (int) hour, "min" => (int) min, "sec" => (int) sec ] ] date3 = (array) ( "timestamp" => (int) timestamp ) // UTC timezone DATE-TIME params4 = (array) ( [[ reltype [, trigRelparam ]] / datetimeparam ] *[, xparams ] ) reltyp = [ Vcalendar::RELATED => Vcalendar::START / Vcalendar::END ] // default Vcalendar::START trigRelparam = [ Vcalendar::VALUE => Vcalendar::DURATION ] // default Vcalendar::DURATION datetimeparam = [ Vcalendar::VALUE => Vcalendar::DATE_TIME ] // mandatory if DATE-TIME xparams = [ (string) key => (string) value ] // key(s) prefix "X-"
* please notice date restraints.

Example 1

A fix date duration

try { $valarm->setTrigger( new DateTime( '2007-06-05 02:02:03 UTC' )); } catch( Exception $e ) { die( $e->getMessage()); }

Example 2

A duration, 1 hour 2 min 3 sec, before start (before default)

try { $dateInterval = new DateInterval( "PT1H2M3S" ); $dateInterval->invert = 1; $valarm->setTrigger( $dateInterval ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 3

A duration, 1 week after end.

try { $valarm->setTrigger( "P1W", [ Vcalendar::RELATED => Vcalendar::END ] ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 4

A duration, 1 hour 2 min 3 sec, before start (before default)

try { $valarm->setTrigger( "-PT1H2M3S" ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 5

A duration, 1 hour 2 min 3 sec, before start (before default).
Subject for removal in next major version.

try { $valarm->setTrigger( null, null, null, null, 1, 2, 3 ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 6

A duration, 1 hour 2 min 3 sec, before start (before default).
Subject for removal in next major version.

try { $valarm->setTrigger( [ "hour"=> 1, "min"=> 2, "sec"=> 3 ] ); } catch( Exception $e ) { die( $e->getMessage()); }

Example 7

A duration, 1 week before start (before default).
Subject for removal in next major version.

try { $valarm->setTrigger( null, null, null, 1 ); } catch( Exception $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.41 TZID

This property specifies the text value that uniquely identifies the VTIMEZONE calendar component and is REQUIRED, but MUST NOT occur more than once.

The value type for TZID is TEXT.

To ease up usage, constant Vcalendar::TZID is available.

Create TZID

If set, returns [RFC5545] formatted string, otherwise null.

Format

vtimezone::createTzid()

Example

$str = $component->createTzid();

Delete TZID

Remove TZID from component.

Format

vtimezone::deleteTzid()

Example

$vtimezone->deleteTzid();

Get TZID

If set, returns property value, otherwise bool false.

Format 1

vtimezone::getTzid()

output = tzid1

Format 2

vtimezone::getTzid( true )

output = array( "value" => tzid1 , "params" => xparams2 )

Example

$tzid = $vtimezone->getTzid();

Set TZID

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

vtimezone::setTzid( tzid [, xparams ] )

tzid1 = (string) Value type TEXT xparams2 = (array)( *[ (string) key => (string) value ] ) // key(s) prefix "X-"

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone() ->setTzid( "US-Eastern" );


[index] [top] [up]

3.2.42 TZNAME

This property specifies the customary designation for a STANDARD or DAYLIGHT description and is OPTIONAL and MAY occur more than once.

The value type for TZNAME is TEXT.

To ease up usage, constants
- Kigkonsult\Icalcreator\Vcalendar::TZNAME
- Kigkonsult\Icalcreator\Vcalendar::LANGUAGE
are available.

Create TZNAME

If set, returns [RFC5545] formatted string, otherwise null.

Format

vtimezone::createTzname()

Example

$str = $component->createTzname();

Delete TZNAME

Remove TZNAME from component.

Format

vtimezone::deleteTzname()

Example 1

Delete (single/first) TZNAME property.

$vtimezonestd->deleteTzname();

Example 2

Delete TZNAME property no 2.

$vtimezonestd->deleteTzname( 2 );

Example 3

Deleting all TZNAME properties.

while( $vtimezonestd->deleteTzname()) { continue; }

Get TZNAME

If set, returns property value, otherwise bool false.

Format 1

vtimezone::getTzname()

output = tzname1

Format 2

vtimezone::getTzname( propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( "value" => tzname1 , "params" => params2 )

Format 3

vtimezone::getTzname( propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo TZNAME

Example

$tzname = $timezonestandard->getTzname();

Set TZNAME

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) or invalid offset value;.

Format

vtimezone::setTzname( tzname [, params [, propOrderNo ]] )

tzname1 = (string) Value type TEXT params2 = (array) ( Vcalendar::LANGUAGE => (string) "lang*", *xparams ) xparams = (string) key => (string) value // key(s) prefix "X-" propOrderNo = (int) order number // 1=1st, 2=2nd etc lang* = as defined in [RFC5546]

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone() ->setTzid( "AKST" ); $standard = $vtimezone->newStandard() ->setTzname( "AKST" ); $daylight = $vtimezone->newDaylight() ->setTzname( "AKDT" );


[index] [top] [up]

3.2.43 TZOFFSETFROM

This property specifies the offset which is in use prior to this TIMEZONE observance. The property is REQUIRED, but MUST NOT occur more than once in STANDARD and DAYLIGHT components.

The value type is UTC-OFFSET, "+" / "-" time-hour (2*DIGIT) time-minute (2*DIGIT) [time-second (2*DIGIT)].

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::TZOFFSETFROM is available.

Create TZOFFSETFROM

If set, returns [RFC5545] formatted string, otherwise null.

Format

vtimezone::createTzoffsetfrom()

Example

$str = $component->createTzoffsetfrom();

Delete TZOFFSETFROM

Remove TZOFFSETFROM from component.

Format

vtimezone::deleteTzoffsetfrom()

Example

$vtimezonestd->deleteTzoffsetfrom();

Get TZOFFSETFROM

If set, returns property value, otherwise bool false.

Format 1

vtimezone::getTzoffsetfrom()

output = tzoffsetfrom1

Format 2

vtimezone::getTzoffsetfrom( true )

output = array( "value" => tzoffsetfrom1 , "params" => xparams2 )

Example

$tzoffsetfrom = $tzstandard->getTzoffsetfrom();

Set TZOFFSETFROM

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and on invalid offset value.

Format

vtimezone::setTzoffsetfrom( tzoffsetfrom [, xparams ] )

tzoffsetfrom1 = (int) (+/-)HHmm[ss] // UTC offset xparams2 = (array) ( *[ /string) key => (string) value ] ) // key(s) prefix "X-"

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtinezone() ->setTzid( "US-Eastern" ) ->setLastmodified( "19870101" ); $standard = $vtimezone->newStandard() ->setTzname( "EST" ) ->setTzoffsetfrom( "-0500" );


[index] [top] [up]

3.2.44 TZOFFSETTO

This property specifies the offset which is in use in this TIMEZONE observance. The property is REQUIRED, but MUST NOT occur more than once in STANDARD and DAYLIGHT components.

The value type is UTC-OFFSET, "+" / "-" time-hour (2*DIGIT) time-minute (2*DIGIT) [time-second (2*DIGIT)].

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::TZOFFSETTO is available.

Create TZOFFSETTO

If set, returns [RFC5545] formatted string, otherwise null.

Format

vtimezone::createTzoffsetto()

Example

$str = $component->createTzoffsetto();

Delete TZOFFSETTO

Remove TZOFFSETTO from component.

Format

vtimezone::deleteTzoffsetto()

Example

$daylight->deleteTzoffsetto();

Get TZOFFSETTO

If set, returns property value, otherwise bool false.

Format 1

vtimezone::getTzoffsetto()

output = tzoffsetto1

Format 2

vtimezone::getTzoffsetto( true )

output = array( "value" => tzoffsetto1 , "params" => xparams2 )

Example

$tzoffsetto = $tztandard->getTzoffsetto();

Set TZOFFSETTO

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true) and on invalid offset value.

Format

vtimezone::setTzoffsetto(tzoffsetto [, xparams ] )

tzoffsetto1 = (int) (+/-)HHmm[ss] // UTC offset xparams2 = array( *[ (string) key => (string) value ] ) // key(s) prefix "X-"

Example

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone() ->setTzid( "US-Eastern" ) ->setLastmodified( "19870101" ); $standard = $vtimezone->newStandard(); .. . $daylight = $vtimezone->newDaylight() ->setTzoffsetto( "1345" );


[index] [top] [up]

3.2.45 TZURL

The TZURL provides a means for a VTIMEZONE component to point to a network location that can be used to retrieve an up-to-date version of itself. The property is OPTIONAL and MUST NOT occur more than once.

The value type is URI.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::TZURL is available.

Create TZURL

If set, returns [RFC5545] formatted string, otherwise null.

Format

vtimezone::createTzurl()

Example

$str = $component->createTzurl();

Delete TZURL

Remove TZURL from component.

Format

vtimezone::deleteTzurl()

Example

$vtimezone->deleteTzurl();

Get TZURL

If set, returns property value, otherwise bool false.

.

Format 1

vtimezone::getTzurl()

output = tzurl1

Format 2

vtimezone::getTzurl( true )

output = array( "value" => tzurl1 , "params" => xparams2 )

Example

$tzurl = $timezonestandard->getTzurl();

Set TZURL

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

The method throws InvalidArgumentException on url error.

Format

vtimezone::setTzurl(tzurl [, xparams ] )

tzurl1 = (string) Value type URI xparams2 = array( *[ (string) key => (string) value ] ) // key(s) prefix "X-"

Example

use Kigkonsult\Icalcreator\Vcalendar; $tz = "http://zones.stds_r_us.net/tz/US-Eastern" ); $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vtimezone = $vcalendar->newVtimezone() ->setTzid( "US-Eastern" ); try { $vtimezone->setLastmodified( "19870101T000000" ) } catch( Exception $e ) { die( $e->getMessage(); } try { $vtimezone->setTzurl( $tz ); } catch( InvalidArgumentException $e ) { die( $e->getMessage(); }


[index] [top] [up]

3.2.46 UID

The persistent, globally Unique IDentifier for the calendar component. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components.
However, UID is AUTOMATICALLY generated in iCalcreator and configuration unique_id is used when auto-creating component UID.

UID generated format :

date("Ymd\THisT") . "-" . [microSec][random] . "@" . unique_id

microSec = microseconds, 4 pos
random = 6 characters aA-zZ, 0-9

Example

"20070803T194810CEST-0123U3PXiX@kigkonsult.se"

UID may be required when importing iCal formatted information into some calendar software (MS etc.), as well as (calendar) properties x-properties "X-WR-CALNAME", "X-WR-CALDESC" and "X-WR-TIMEZONE", METHOD (value PUBLISH etc.) and the (also automatically created) DTSTAMP property.

The value type for UID is TEXT.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::UID is available.

You can SORT calendar (components) on (asc) UID values.

Create UID

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createUid()

Example

$str = $component->createUid();

Delete UID

If UID is remove from a component, UID will automatically be recreated when Vcalendar output methods like createCalendar, returnCalendar or saveCalendar is executed.

Format

calendarComponent::deleteUid()

Example

$vevent->deleteUid();

Get UID

If set, returns property, otherwise bool false.

Format 1

calendarComponent::getUid()

output = uid1

Format 2

calendarComponent::getUid( true )

output = array( "value" => uid1 , "params" => xparams2 )

Example

$uid = $vevent->getUid();

Set UID

Insert property value, overrides any previously set or auto-created UID.

Do NOT use an integer UID or only a component name as UID (ex. "vevent"), this may cause malfunction in Vcalendar method setComponent with index or UID argument.

The method throws InvalidArgumentException on empty (non-zero) value.

Format

calendarComponent::setUid( uid [, xparams ] )

uid1 = (string) Value type TEXT xparams2 = array( *[ (string) key => (string) value ] ) // key(s) prefix "X-"

Example

$vevent->setUid( "20070803T194810CEST-0123U3PXiX@kigkonsult.se" );

BUT, due to poorly created iCal formatted information, a numeric UID is accepted in the setUid() and parse() methods. Do check for component digit UIDs and remove it (will force a (auto) UID recreation) or (re-)set it manually.

if( ctype_digit( $vevent->getUid())) { $vevent->deleteUid(); }


[index] [top] [up]

3.2.47 URL

This property defines a Uniform Resource Locator (URL) associated with the iCalendar object. The property is OPTIONAL and MUST NOT occur more than once in VEVENT, VTODO, VJOURNAL and VFREEBUSY components.

The value type is URI.

You can SORT calendar (components) on (asc) URL values.

To ease up usage, constant Kigkonsult\Icalcreator\Vcalendar::URL is available.

Create URL

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createUrl()

Example

$str = $component->createUrl();

Delete URL

Remove URL from component.

Format

calendarComponent::deleteUrl()

Example

$vevent->deleteUrl();

Get URL

If set, returns property value, otherwise bool false.

Format 1

calendarComponent::getUrl()

output = url1

Format 2

calendarComponent::getUrl( true )

output = array "value" => url1 , "params" => xparams2 )

Example

$url = $vevent->getUrl();

Set URL

Set property value.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true), InvalidArgumentException on url error.

Format

calendarComponent::setUrl( url [, xparams ] )

url1 = (string) Value type URI xparams2 = (array) ( *[ (string) key => (string) value ] ) // key(s) prefix "X-"

Example

try { $vtodo->setUrl( "http://www.icaldomain.net" ); } catch( InvalidArgumentException $e ) { die( $e->getMessage()); }


[index] [top] [up]

3.2.48 X-PROPERTY

A component, non-standard property with a TEXT value and a name with an "X-" prefix. In a component, an x-property, with an unique name, can occur only once but the number of x-properties are unlimited.

The value type is TEXT.

Create X-PROPERTY

If set, returns [RFC5545] formatted string, otherwise null.

Format

calendarComponent::createXprop()

Example

$str = $component->createxProp();

Delete X-PROPERTY

Remove X-PROPERTY from component.

Format

calendarComponent::deleteXprop( "<X-PROPERTY>" )

Example 1

Deleting x-property named "X-PROPERTY".

$vevent->deleteXprop( "X-PROPERTY" );

Example 2

Deleting all x-properties.

while( $vevent->deleteXprop()) { continue; }

Get X-property

If set, returns property value, otherwise bool false.

Format 1

Get specific x-propery value.

calendarComponent::getXprop( "<X-PROPERTY-NANE>" )

output = array( propertyName1 , value2 )

Format 2

Get (next) x-property value.

calendarComponent::getXprop()

output = array( propertyName1 , value2 )

Format 3

calendarComponent::getXprop( null, propOrderNo/null, true )

propOrderNo = (int) specific property value

output = array( propertyName1 , array ( "value" => value2 ) , "params" => params3))

Format 4

calendarComponent::getXprop( null, propOrderNo )

propOrderNo = (int) specific property value

Get propOrderNo X-property

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); if( false !== ( $d = $vcalendar->getXprop( Vcalendar::X_WR_TIMEZONE ))) { echo $d[1]; // $d = array( "X-WR-TIMEZONE", value2 ) }

Example 2

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $xprop = $vcalendar->getXprop )) { // $xprop = array( propertyName1, value2 ) .. .

Example 3

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $xprop = $vcalendar->getXprop( "X-ABC-MMSUBJ" )) { // $xprop = array( "X-ABC-MMSUBJ", value2 ) .. . }

Example 4

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); while( $xprop = $vcalendar->getXprop( null, null, true )) { /* $xprop = [ propertyName1, [ "value" => value2 ], "params" => params3 ] */

Set X-property

Insert property name and value. If an x-prop with the same name already exists, it will be replaced.

The method throws InvalidArgumentException on empty value and config ALLOWEMPTY is set to false (default true).

Format

calendarComponent::setXprop( propertyName, propertyData [, params ] )

propertyName1 = (string) Any property name with a "X-" prefix value2 = (string) Value type TEXT params3 = (array) ( [Vcalendar::LANGUAGE => (string) "lang*"] *[, xparams] ) xparams = (string) key => (string) value // key(s) prefix "X-" lang* = as defined in [RFC5546]

Example

$component->setXprop("X-ABC-MMSUBJ","http://load.noise.org/mysubj.wav");


[index] [top] [up]

3.3 iCalcreator Component configuration methods

3.3.1 Language

Language for specific calendar component as defined in [RFC5546].
Language set at component level can be overridden by specific component property parameter.
A successful "setConfig" returns bool true.

There is a convenient config key constant available: Vcalendar::LANGUAGE.

Get language
Language for calendar (only if language is set at component level).

Format

calendarComponent::getConfig( "language" )

Example

$lang = $vevent->getConfig( Vcalendar::LANGUAGE );

Set LANGUAGE

Format

calendarComponent::setConfig( "language", lang )

lang = (string) language

Example

$vevent->setConfig( Vcalendar::LANGUAGE, "en" );


[index] [top] [up]

3.4 iCalcreator component object misc. methods

Calendar component subcomponent functions.

3.4.1 deleteComponent

Remove subcomponent from component.

Format

calendarComponent::deleteComponent( orderNumber )

orderNumber = (int) component order Number

Remove component with order number (1st=1, 2nd=2).

calendarComponent::deleteComponent( componentType [, componentSuborderNumber])

componentType = (string) component type componentSuborderNumber = (int) component suborder number

Remove component with component type (ex. "vevent") and order 1 alt. suborder number.

calendarComponent::deleteComponent( UID )

Remove component with UID. N.B UID is NOT set for ALARM / timezone components.

Example 1

Delete first subcomponent.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $comp1 = $vcalendar->getComponent(); $comp1->deleteComponent( 1 );

Example 2

Delete all subcomponents.

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $comp1 = $vcalendar->getComponent(); while( $comp1->deleteComponent( Vcalendar::VALARM ) { continue; }


[index] [top] [up]

3.4.2 getComponent

Get subComponent from component.

Format 1

calendarComponent::getComponent()

Get next component until end-of-components.

Format 2

calendarComponent::getComponent( int orderNumber )

orderNumber = (int) component order number

Get component with order number (1st=1, 2nd=2).

Format 3

calendarComponent::getComponent( string componentType [, int componentSuborderNumber])

componentType = (string) component type componentSuborderNumber = (int) component suborder number

Get (next) component with component type (until end-of-components) alt. component with component type and suborder number (1st=1, 2nd=2..).

Format 4

calendarComponent::getComponent( UID )

Get component with UID. N.B UID is NOT set for ALARM / timezone components.

Example

use Kigkonsult\Icalcreator\Vcalendar; $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); $iCalContent = file_get_contents( "calendar.ics" ); $vcalendar->parse( $iCalContent ); $comp1 = $vcalendar->getComponent()); while( $subComp = $comp1->getComponent()) { ...


[index] [top] [up]

3.4.3 newComponent

Create subcomponent (ALARN / VTIMEZONE STANDARD / VTIMEZONE DAYLIGHT) using a component factory-method, returning a reference to the new component.

The method is deprecated in favor of components factory-method.

Format

calendarComponent::newComponent( componentType )

componentType = (string) component type

Example 1

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); $vevent = $vcalendar->newComponent( Valendar::VEVENT ); // add some EVENT properties $vevent->setDtstart( new DateTime( "2006-12-24 19:30:00" ); $vevent->set...( ... ... $valarm = $vevent->newComponent( Vcalendar::VALARM ); $valarm->setTrigger( ...

Example 2

use Kigkonsult\Icalcreator\Vcalendar; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); .. . $vtimezone = $vcalendar->newComponent( Vcalendar::VTIMEZONE ); $vtimezone->setProperty( .. . .. . $standard = $vtimezone->newComponent( Vcalendar::STANDARD ); $standard->setProperty( .. . .. . $daylight = $vtimezone->newComponent( Vcalendar::DAYLIGHT ); $daylight->setProperty( .. .


[index] [top] [up]

3.4.4 setComponent

Add calendar component to the Vcalendar instance or replace/update component in the Vcalendar instance.

Format 1

calendarComponent::setComponent( component ) addSubComponent( component ) // alias

Insert last in component chain.

Format 2

calendarComponent::setComponent( component, int orderNumber )

orderNumber = (int) component order number

Replace component with order number(1st=1, 2nd=2). If orderNumber is not found, component is inserted last in chain.

Format 3

calendarComponent::setComponent( component, componentType [,componentSuborderNumber])

componentType = (string) component type componentSuborderNumber = (int) component suborder number

Replace component with component type and component order number. if orderNumber is not found, component is inserted last in chain.

Example

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Vevent; use Kigkonsult\Icalcreator\Valarm; $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; $vcalendar = new Vcalendar( $config ); // initiate new CALENDAR $vevent = new Vevent( $config ); // add some EVENT properties $vevent->setDtstart( new DateTime( "2006-12-24 19:30:00" ); $vevent->set...( ... ... $valarm = new Valarm( $config ); $valarm->setTrigger( ... $vevent->setComponent( $valarm ); $vcalendar->setComponent( $vevent );


[index] [top] [up]

4 Timezone, XML, json and vCard support

4.1 iCalcreator and timezoneHandler class

The class is revoked.

The TimezoneHandler::createTimezone() method is replaced by Vtimezone::VtimezonePopulate() or Vcalendar::vtimezonePopulate methods.

The (static) ms2phpTZ / transformDateTime methods are revoked.


[index] [top] [up]

4.2 Timezone helper functions

Additional functions to use with vtimezone components, placed in the "iCal.tz.inc.php" file.

Note, the methods is subject for removal in next major version.

Before calling the functions getTzOffsetForDate and getTimezonesAsDateArrays, set time zone 'GMT' (using 'date_default_timezone_set')!

4.2.1 getTzOffsetForDate

The getTzOffsetForDate function returns UTC offset information for specific date (timezone) based on output from getTimezonesAsDateArrays function.

Before calling the function, set time zone 'GMT' ('date_default_timezone_set')!

Returns array, time zone data for specific date (timestamp) with keys for

Format

getTzOffsetForDate( timezonesarray, tzid, timestamp )

timezonesarray = (array) output from getTimezonesAsDateArrays, below tzid = (string) time zone identifier timestamp = (mixed) the date in question (timestamp) or UTC datetime (array) ( "year" => (int) year , "month" => (int) month , "day" => (int) day , "hour" => (int) hour , "min" => (int) min , "sec" => (int) sec )


[index] [top] [up]

4.2.2 getTimezonesAsDateArrays

The function creates time zone transition information, based on vtimezone component contents in a Vcalendar instance, using sub-function expandTimezoneDates.

Before calling the function, set time zone 'GMT' ('date_default_timezone_set')!

Returns an array containing time zone data from Vtimezone Standard/Daylight instances (input to getTzOffsetForDate, above).

Format

getTimezonesAsDateArrays( iCalobj )

iCalobj= (object) Vcalendar instance


[index] [top] [up]

4.3 iCalcreator and iCalXMLFactory class

The Kigkonsult\Icalcreator\IcalXML class is moved to Kigkonsult\Icalcreator\Util\IcalXMLFactory.

The IcalXMLFactory class methods converts iCal into XML and parses XML into iCal. XML is defined by [RFC6321], "xCal: The XML Format for iCalendar".

4.3.1 iCal2XML

The (static) iCal2XML method converts an Vcalendar instance to XML.

The iCal2XML method uses the SimpleXML extension (and "libxml" PHP extension).

An rfc6321 XML string is returned.

Format

IcalXMLFactory::iCal2XML( iCalobj )

iCalobj = (object) Vcalendar instance

$xmlString = Kigkonsult\Icalcreator\Util\IcalXMLFactory::iCal2XML( $vcalendar );


[index] [top] [up]

4.3.2 XML2iCal

The two entry methods: XMLstr2iCal and XMLfile2iCal converts XML to iCal, i.e. parses an XML string/file into an Vcalendar instance. The methods are not using the PHP SimpleXML extension.

On success, an Vcalendar instance is returned.

On (XML parse) error, bool false is returned.

The method is deprecated and subject for removal in next major version. A strong recommendation is placing iCal XML file/url content acquire functionality outside iCalcreator, this will also offer better acquire control.

XMLstr2iCal

The (static) method accepts a well-formed (rfc6321) XML string as argument.

Format

IcalXMLFactory::XMLstr2iCal( xmlstr [, config] )

xmlstr = (string) rfc6321 XML config = (array) iCalcreator config array (opt)

XMLfile2iCal

The (static) method accepts an XML (rfc6321) local file or a remote URI, as argument.

Note, the method is subject for removal in next major version. A strong recommendation is placing file content acquire/dispose functionality outside iCalcreator, this will also offer better acquire/dispose control.

Format

IcalXMLFactory::XMLfile2iCal( xmlfile [, config] )

xmlfile = (string) rfc6321 XML file name or resource config = (array) iCalcreator config array (opt)

XML2iCal

This (static) method is doing the hard work in XMLstr2iCal/XMLfile2iCal methods.

Format

IcalXMLFactory::XML2iCal( xmlstr [, config] )

xmlstr = (string) rfc6321 XML config = (array) iCalcreator config array (opt)


[index] [top] [up]

4.4 iCalcreator and json export

You can export iCal (XML) as json using a Vcalendar instance, IcalXMLFactory::iCal2XML() (above), simplexml_load_string and json_encode as follows:

$xml = Kigkonsult\Icalcreator\Util\IcalXMLFactory::iCal2XML( $vcalendar ); $json = json_encode( simplexml_load_string( $xml ));


[index] [top] [up]

4.5 iCalcreator and iCalvCardFactory class

The former Kigkonsult\Icalcreator\IcalvCard class is move to Kigkonsult\Icalcreator\Util\IcalvCardFactory class which has methods to produce vCard string output.

4.5.1 iCal2vCard

The (static) method converts a single email (iCal "cal-address") into (string) vCard.

Returns vCard string.

Format

IcalvCard::iCal2vCard( email [, version ] )

email = (string) email, ATTENDEE, ORGANIZER and opt CONTACT "cal-address" version = (string) vCard version, "2.1" (default), "3.0", "4.0"


[index] [top] [up]

4.5.2 iCal2vCards

The (static) method collects and converts all ATTENDEEs and ORGANIZERs values (iCal "cal-address") and CONTACTs into simplified vCard (string) output using

Format

IcalvCard::iCal2vCards( vcalendar [, version [, inclParams [, count ]]] )

vcalendar = (object) Vcalendar instance version = (string) vCard version, "2.1" (default), "3.0", "4.0" inclParams = (bool) default true: search property values and parameters, false: values only count = (int) number of vCards in output

Return vCard(s) string.


[index] [top] [up]

5 COPYRIGHT AND LICENSE

Copyright(c) 2007-2019 Kjell-Inge Gustafsson, kigkonsult, All rights reserved
Link https://kigkonsult.se
Package iCalcreator
Version 2.28.2
License Subject matter of licence is the software iCalcreator.
The above copyright, link, package and version notices,
this licence notice and the invariant [rfc5545] PRODID result use
as implemented and invoked in iCalcreator shall be included in
all copies or substantial portions of the iCalcreator.

iCalcreator is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation, either version 3 of the License,
or (at your option) any later version.

iCalcreator is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with iCalcreator. If not, see <https://www.gnu.org/licenses/>.

[index] [top] [up]