iCalcreator v2.24

iCalcreator v2.24
Copyright (c) 2007-2017 Kjell-Inge Gustafsson, kigkonsult, All rights reserved.
kigkonsult.se iCalcreator
kigkonsult.se contact

Preface

This document describes a short summary usage of iCalcreator, a PHP software implementation of standards rfc5545/rfc5546 (rfc2445/rfc2446) to manage iCal formatted files.

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 agreement.

This document makes previous versions obsolete.

The software

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

For iCalcreator 2.24 version (and later), PHP version >= 5.4 is required.

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.

xCal

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

SUPPORT

For previous iCalcreator releases support upon (paid) request only.

Use the contact page for queries, improvement/development issues or professional support and development. Please note that paid support or consulting service has the highest priority.

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 GPL/LGPL projects.

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

Contact

Use the contact page for queries, improvement/development issues or professional support and development. Please note that paid support or consulting service has the highest priority.

Downloads and usage examples

At kigkonsult.se you can download the complete manual and review and explore iCalcreator usage at the coding and test pages.

INSTALL

Composer (https://getcomposer.org/)

 

composer require kigkonsult/iCalcreator

 

or

include the (download) iCalcreator folder to your include-path

or unpack to your application-(include)-folder

Add

require_once "[path/]autoload.php";

to your PHP-script.

The iCalcreator invoker has changed since previous version!

You may also need to set the default timezone.

Notes

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

You will find a complete iCalcreator function list (ex. getProperty, deleteProperty) in iCalcreator manual.

Note, to ease up usage, you will find convenient holders for component names, properties, config keys etc in top of the "util" class file (src/util/util.php).

CREATE

// define time zone $tz = "Europe/Stockholm"; // set Your unique id, // required if any component UID is missing $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se", // opt. set "calendar" timezone kigkonsult\iCalcreator\util\util::$TZID => $tz ); // create a new calendar object instance $calendar= new kigkonsult\iCalcreator\vcalendar( $config ); // required of some calendar software $calendar->setProperty( kigkonsult\iCalcreator\util\util::$METHOD, "PUBLISH" ); $calendar->setProperty( "x-wr-calname", "Calendar Sample" ); $calendar->setProperty( "X-WR-CALDESC", "Calendar Description" ); $calendar->setProperty( "X-WR-TIMEZONE", $tz ); // create an calendar event component $vevent = $calendar->newVevent(); // set event start $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DTSTART, array( "year" => 2017, "month" => 4, "day" => 1, "hour" => 19, "min" => 0, "sec" => 0 )); // set event end $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DTEND, array( "year" => 2017, "month" => 4, "day" => 1, "hour" => 22, "min" => 30, "sec" => 0 )); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$LOCATION, "Central Placa" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$SUMMARY, "PHP summit" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION, "This is a description" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$COMMENT, "This is a comment" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$ATTENDEE, "attendee1@icaldomain.net" ); // create an event alarm $valarm = $vevent->newValarm(); $valarm->setProperty( kigkonsult\iCalcreator\util\util::$ACTION, "DISPLAY" ); // reuse the event description $valarm->setProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION, $vevent->getProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION ) ); // a local date $d = sprintf( '%04d%02d%02d %02d%02d%02d', 2017, 3, 31, 15, 0, 0 ); // create alarm trigger (in UTC datetime) kigkonsult\iCalcreator\timezoneHandler::transformDateTime( $d, $tz, "UTC", "Ymd\THis\Z" ); $valarm->setProperty( kigkonsult\iCalcreator\util\util::$TRIGGER, $d ); // create another calendar event component $vevent = $calendar->newVevent(); // alt. date format, here for an all-day event $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DTSTART, "20170401", array("VALUE" => "DATE")); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$ORGANIZER, "boss@icaldomain.com" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$SUMMARY, "ALL-DAY event" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION, "This is a description for an all-day event" ); $vevent->setProperty( kigkonsult\iCalcreator\util\util::$RESOURCES, "Full attension" ); // weekly, four occasions $vevent->setProperty( kigkonsult\iCalcreator\util\util::$RRULE, array( "FREQ" => "WEEKLY", "count" => 4)); // supporting parse of strict rfc5545 formatted text $vevent->parse( "LOCATION:1CP Conference Room 4350" ); // all calendar components are described in rfc5545 // a complete iCalcreator function list (ex. setProperty) in iCalcreator manual // create timezone component(-s) // based on all start dates in events (i.e. all dtstarts) // X-LIC-LOCATION required of some calendar software $xprops = array( "X-LIC-LOCATION" => $tz ); kigkonsult\iCalcreator\timezoneHandler::createTimezone( $v, $tz, $xprops );

PARSE

iCal, rfc5545 / rfc2445

How to create iCalcreator object instance

// set Your unique id, // required if any component UID is missing $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se" ); // create a new calendar object instance $calendar= new kigkonsult\iCalcreator\vcalendar( $config );

and then parse a local iCal file

// set directory and file name $config = array( kigkonsult\iCalcreator\util\util::$DIRECTORY => "calendars", kigkonsult\iCalcreator\util\util::$FILENAME => "file.ics" ); $calendar->setConfig( $config ); $calendar->parse(); // continue process (edit, parse, select) $calendar

or parse a remote iCal file (resource)

// support parse of remote files $calendar->setConfig( kigkonsult\iCalcreator\util\util::$URL, "http://www.aDomain.net/file.ics" ); $calendar->parse(); // ensure start date order // (opt., NOT required after parse) $calendar->sort(); // continue process (edit, parse, select) $calendar

On error

the setConfig method returns FALSE (ex. unvalid directory/filename).

the parse method returns FALSE.

xCal, rfc6321 (XML)

How to convert (file) XML resource to an iCalcreator object instance.

// set Your unique id, // required if any component UID is missing $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se" ); // use a local xCal file $filename = "xmlfile.xml"; // or a remote xCal resource /* $filename = 'http://kigkonsult.se/xcal.php?a=1&b=2&c=3'; */ if( ! ( $calendar = kigkonsult\iCalcreator\iCalXML::XMLfile2iCal( $filename, $config ))) exit( "Error when parsing $filename" ); // continue process (edit, parse, select) $calendar

EDIT

// create a new calendar object instance $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se" ); $calendar = new kigkonsult\iCalcreator\vcalendar( $config ); // parse a calendar file $config = array( kigkonsult\iCalcreator\util\util::$DIRECTORY => "calendars", kigkonsult\iCalcreator\util\util::$FILENAME => "file.ics" ); $calendar->setConfig( $config ); $calendar->parse(); // required of some calendar software $calendar->setProperty( kigkonsult\iCalcreator\util\util::$METHOD, "PUBLISH" ); $calendar->setProperty( "x-wr-calname", "Calendar Sample" ); $calendar->setProperty( "X-WR-CALDESC", "Calendar Description" ); $calendar->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // read events, one by one while( $vevent = $calendar->getComponent( kigkonsult\iCalcreator\util\util::$LCVEVENT )) { // uid (unique id/key for component), required, one occurrence $uid = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$UID ); // dtstart required, one occurrence $dtstart = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$DTSTART ); // opt. description if( $description = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION, 1 )) { // edit the description // update/replace the description $vevent->setProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION, $description, FALSE, 1 ); } // optional comments while( $comment = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$COMMENT )) { .. . } // remove all ATTENDEE properties .. . while( $vevent->deleteProperty( kigkonsult\iCalcreator\util\util::$ATTENDEE )) continue; // update/replace event in calendar // with UID as key $calendar->setComponent ( $vevent, $uid ); }

SELECT

(setup)

// create a new calendar object instance $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se" ); $calendar = new kigkonsult\iCalcreator\vcalendar( $config ); // iCalcreator also support remote files $calendar->setConfig( kigkonsult\iCalcreator\util\util::$URL, "http://www.aDomain.net/file.ics" ); $calendar->parse(); // required of some calendar software $calendar->setProperty( kigkonsult\iCalcreator\util\util::$METHOD, "PUBLISH" ); $calendar->setProperty( "x-wr-calname", "Calendar Sample" ); $calendar->setProperty( "X-WR-CALDESC", "Calendar Description" ); $calendar->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" );

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 array( // "x-current-dtstart" // , (string) date( // "Y-m-d [H:i:s][timezone/UTC offset]")) $currddate = $event->getProperty( kigkonsult\iCalcreator\util\util::$X_CURRENT_DTSTART ); // orig. dtstart $dtstart = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$DTSTART ); $summary = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$SUMMARY ); $description = $vevent->getProperty( kigkonsult\iCalcreator\util\util::$DESCRIPTION ); .. . .. . } } } }

Ex. calendar select specific property values

// 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( kigkonsult\iCalcreator\util\util::$RESOURCES ); foreach( $valueOccur as $uniqueValue => $occurCnt ) { echo "The RESOURCES value <b>$uniqueValue</b> occurs <b>$occurCnt</b> times<br />"; }

^*) Using the non-standard directive "GEOLOCATION", iCalcreator returns output supporting ISO6709 "Standard representation of geographic point location by coordinates", by combining the "LOCATION" and "GEO" property values (only if "GEO" is set).

Ex. select calendar components based on specific property value

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

OUTPUT

(setup)

// create a new calendar object instance $config = array( kigkonsult\iCalcreator\util\util::$UNIQUE_ID => "kigkonsult.se" ); $calendar= new kigkonsult\iCalcreator\vcalendar( $config ); // required of some calendar software $calendar->setProperty( kigkonsult\iCalcreator\util\util::$METHOD, "PUBLISH" ); $calendar->setProperty( "x-wr-calname", "Calendar Sample" ); $calendar->setProperty( "X-WR-CALDESC", "Calendar Description" ); $calendar->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // continue process (edit, parse, select) $calendar

opt 1

Redirect calendar file to browser.

$calendar->returnCalendar(); exit;

opt 2

Save calendar to file.

// set output directory and file name $config = array( kigkonsult\iCalcreator\util\util::$DIRECTORY => "depot", kigkonsult\iCalcreator\util\util::$FILENAME => "calendar.ics" ); $calendar->setConfig( $config ); $calendar->saveCalendar();

opt 3, xCal

Create well-formed XML, rfc6321 (as string).

$xmlstr = kigkonsult\iCalcreator\iCalXML::iCal2XML( $calendar);

opt 4, json

Create a json string.

$xmlstr = kigkonsult\iCalcreator\iCalXML::iCal2XML( $calendar); $json = json_encode( simplexml_load_string( $xmlstr ));

COPYRIGHT AND LICENSE