iCalcreator v2.39

iCalcreator v2.39
Copyright © 2007-2021 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 rfc6321 rfc7986 to manage calendar information. The fc5545/rfc5546 obsoletes rfc2445/rfc2446.

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.

The software

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.

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

For iCalcreator 2.39 version (and later), PHP version >= 7.0 is required. v2.29.25 and later asserts PHP 7+ compability using PHPCompatibility and (v2.39+) PHPStan.

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.

rfc6321

xCal: The XML Format for iCalendar

rfc7986

New Properties for iCalendar,

may NOT be supported by all calendaring software

rfc5545 and rfc5546 obsoletes, respectively, rfc2445 and rfc2446.

A short xCal description is found at Wikipedia.

Support

For bug report or support request, use github issues.

For previous iCalcreator (master) releases or non-emergency issues, support upon (paid) request only.

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

Donate

You can show your appreciation for our free software, and can support future development by making a donation to the kigkonsult project iCalcreator using paypal.me/kigkonsult. For invoice, please e-mail.

Downloads and usage examples

At kigkonsult.se you can download a more complete manual and review and explore iCalcreator usage.

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.39/autoload.php";

to your PHP-script.

The iCalcreator invoker has changed since previous version!

iCalcreator 2.39 is using namespace "Kigkonsult\Icalcreator".

Notes

When creating a new Vcalendar(/component) instance, review config settings.

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

CREATE

<?php use Kigkonsult\Icalcreator\Vcalendar; use DateTime; use DateTimezone; // define time zone $tz = "Europe/Stockholm"; // set Your unique id, // site info for the Vcalendar PRODID property $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se", ]; // create a new Vcalendar instance $calendar = Vcalendar::factory( $config ) // required of some calendar software ->setMethod( Vcalendar::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, $tz ); // create an calendar event component $vevent1 = $calendar->newVevent() // set event start ->setDtstart( new DateTime( '2017-04-01 19:00:00', new DateTimezone( $tz ))) // set event end ->setDtend( new DateTime( '2017-04-01 22:30:00', new DateTimezone( $tz ))) // describe the event ->setSummary( 'Scheduled meeting with six occurrences' ) ->setDescription( 'Agenda for the the meeting...', [ Vcalendar::ALTREP => 'CID:<FFFF__=0ABBE548DFE235B58f9e8a93d@coffeebean.com>' ] ) ->setComment( 'It\'s going to be fun..' ) // place the event ->setLocation( 'Kafé Ekorren Stockholm' ) ->setGeo( '59.32206', '18.12485' ) // with recurrence rule ->setRrule( [ Vcalendar::FREQ => Vcalendar::WEEKLY, Vcalendar::COUNT => 5, ] ) // and set another using a recurrence date ->setRdate( [ new DateTime( '20190609T090000', new DateTimezone( $tz )), new DateTime( '20190609T110000', new DateTimezone( $tz )), ], [ Vcalendar::VALUE => Vcalendar::PERIOD ] ) // revoke a recurrence date ->setExdate( new DateTime( '2019-05-12 09:00:00', new DateTimezone( $tz ))) // organizer, chair and some participants ->setOrganizer( 'secretary@coffeebean.com', [ Vcalendar::CN => 'Secretary CoffeeBean' ] ) ->setAttendee( 'president@coffeebean.com', [ Vcalendar::ROLE => Vcalendar::CHAIR, Vcalendar::PARTSTAT => Vcalendar::ACCEPTED, Vcalendar::RSVP => Vcalendar::FALSE, Vcalendar::CN => 'President CoffeeBean', ] ) ->setAttendee( 'participant1@coffeebean.com', [ Vcalendar::ROLE => Vcalendar::REQ_PARTICIPANT, Vcalendar::PARTSTAT => Vcalendar::NEEDS_ACTION, Vcalendar::RSVP => Vcalendar::TRUE, Vcalendar::CN => 'Participant1 CoffeeBean', ] ) ->setAttendee( 'participant2@coffeebean.com', [ Vcalendar::ROLE => Vcalendar::REQ_PARTICIPANT, Vcalendar::PARTSTAT => Vcalendar::NEEDS_ACTION, Vcalendar::RSVP => Vcalendar::TRUE, Vcalendar::CN => 'Participant2 CoffeeBean', ] ); // add an alarm for the event $alarm = $event1->newValarm() ->setAction( Vcalendar::DISPLAY ) // copy description from event ->setDescription( $event1->getDescription()) // fire off the alarm one day before ->setTrigger( '-P1D' ); // alter day and time for one event in recurrence set $event2 = $vcalendar->newVevent() ->setTransp( Vcalendar::OPAQUE ) ->setClass( Vcalendar::P_BLIC ) // reference to one event in recurrence set ->setUid( $event1->getUid()) ->setSequence( 2 ) // pointer to event in the recurrence set ->setRecurrenceid( '20190505T090000 Europe/Stockholm' ) // opt. some description ->setDescription( 'Altered day and time for event 2019-05-05', [ Vcalendar::ALTREP => 'CID:<FFFF__=0ABBE548DFE235B58f9e8a93d@coffeebean.com>' ] ) // reason comment ->setComment( 'working hard for two hours...' ) // the altered day and time with duration ->setDtstart( new DateTime( '20190504T100000', new DateTimezone( $tz ))) ->setDuration( 'PT2H' ) // add alarm (copy from event1) ->setComponent( $event1->getComponent( Vcalendar::VALARM )); $calendarString = $vcalendar // apply appropriate Vtimezone with Standard/DayLight components ->vtimezonePopulate() // and create the (string) calendar ->createCalendar();

PARSE

iCal, rfc5545

How to parse an iCal (local file) resource

<?php use Kigkonsult\Icalcreator\Vcalendar; // set Your unique id, // site info for the Vcalendar PRODID property $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se", ] ); // get iCal contents from file $iCalContent = file_get_contents( "calendar.ics" ); // parse iCal contents $vcalendar->parse( $iCalContent );

parse example 2

Here using UrlRsrc to download an internet (URL) resource.

use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Http\UrlRsrc; // set Your unique id, // site info for the Vcalendar PRODID property $vcalendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); // get iCal contents from URL resource $iCalContent = UrlRsrc::getContent( "http://www.ical.net/calendars/calendar.ics" ); // parse iCal contents $vcalendar->parse( $iCalContent );

xCal, rfc6321 (XML)

How to convert an XML resource to an Vcalendar class instance.

<?php use Kigkonsult\Icalcreator\Vcalendar; use Kigkonsult\Icalcreator\Util\IcalXMLFactory; // set Your unique id, // site info for the Vcalendar PRODID property $config = [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ]; // use a local or remote xCal file $filename = "xmlfile.xml"; // get XML contents from file $iCalContent = file_get_contents( $filename ); // parse the XML contents to Vcalendar class instance try { $calendar = IcalXMLFactory::XML2iCal( $iCalContent, $config ); } catch( Exception $e ) { exit( "XML parse error" ); } // continue process (edit, parse, select) $calendar ... ...

EDIT

(setup)

<?php use Kigkonsult\Icalcreator\Vcalendar; // create a new Vcalendar instance $calendar = new Vcalendar( [ Vcalendar::UNIQUE_ID => "kigkonsult.se" ] ); // get iCal contents from file $iCalContent = file_get_contents( "calendar.ics" ); // parse iCal contents $calendar->parse( $iCalContent ) // required of some calendar software ->setMethod( Vcalendar::PUBLISH ) ->setXprop( Vcalendar::X_WR_CALNAME, "Calendar Sample" ) ->setXprop( Vcalendar::X_WR_CALDESC, "Calendar Description" ) ->setXprop( Vcalendar::X_WR_TIMEZONE, "Europe/Stockholm" );

Get and set values

// read events, one by one while( $vevent = $calendar->getComponent( Vcalendar::VEVENT )) { // get uid (unique id/key for component), required, one occurrence $uid = $vevent->getUid(); // get dtstart, required, one occurrence $dtstart = $vevent->getDtstart(); // opt. description if( false != ( $description = $vevent->getDescription())) { // edit the description ... // update/replace the description $vevent->setDescription( $description ); } // get optional comments, may occur multiple times while( $comment = $vevent->getComment() { .. . } // remove all ATTENDEE properties .. . while( $vevent->deleteAttendee()) { continue; } // update/replace event in calendar with UID as key $calendar->setComponent( $vevent, $uid ); } // end while

SELECT

(setup as above)

Ex. calendar date based select

// select components occurring today // (including components with recurrence pattern) $eventArray = $calendar->selectComponents(); foreach( $eventArray as $year => $yearArray) { foreach( $yearArray as $month => $monthArray ) { foreach( $monthArray as $day => $dailyEventsArray ) { foreach( $dailyEventsArray as $vevent ) { // if event is a member of a recurrence set // returns [ // "x-current-dtstart", // (string) date( "Y-m-d [H:i:s][timezone]" ) // ] $currDate = $event->getXprop( Vcalendar::X_CURRENT_DTSTART ); // orig. dtstart $dtstart = $vevent->getDtstart(); // event description $summary = $vevent->getSummary(); $description = $vevent->getDescription(); .. . .. . } // end foreach } // end foreach } // end foreach } // end foreach

Ex. calendar select specific property values

(setup as above)

// fetch specific property from calendar perspective // (unique) values and occurrences : // ATTENDEE, CATEGORIES, CONTACT, // DTSTART, LOCATION, ORGANIZER, // PRIORITY, RESOURCES, STATUS, // SUMMARY, UID, URL, // GEOLOCATION^* $valueOccur = $calendar->getProperty( Vcalendar::RESOURCES ); foreach( $valueOccur as $uniquePropertyValue => $occurCnt ) { echo 'The RESOURCES value ' . $uniquePropertyValue . ' occurs ' . $occurCnt . ' times'; }

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

Ex. select calendar components based on specific property value

(setup as above)

// selects components // based on specific property value(-s) // ATTENDEE, CATEGORIES, CONTACT, // LOCATION, ORGANIZER, // PRIORITY, RESOURCES, STATUS, // SUMMARY, URL, UID $selectSpec = [ Vcalendar::CATEGORIES => "course1" ]; $specComps = $calendar->selectComponents( $selectSpec ); foreach( $specComps as $component ) { .. . }

OUTPUT

opt 1

Get calendar as string

... $calendarStr = $calendar->createCalendar();

opt 2

Redirect calendar file to browser.

... $calendar->returnCalendar(); exit;

opt 3

Save calendar to file.

... // Get calendar as string $calendarStr = $calendar->createCalendar(); // Save string as file file_put_contents( "calendar.ics", $calendarStr );

opt 4, xCal

Create well-formed XML, rfc6321 (as string) from a Vcalendar class instance.

... $xmlstr = Kigkonsult\Icalcreator\Util\IcalXMLFactory::iCal2XML( $calendar);

opt 5, json

Create a json string from a Vcalendar class instance.

... $xmlstr = Kigkonsult\Icalcreator\Util\IcalXMLFactory::iCal2XML( $calendar); $json = json_encode( simplexml_load_string( $xmlstr ));

COPYRIGHT AND LICENSE