# iCalcreator v2.18

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

#### Preface

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, GNU Lesser General Public License. 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.

This document makes previous versions obsolete.

#### The software

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

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.

The iCalcreator package, built of a calendar class with support of a function class and helper functions, are calendar component property oriented. Development environment is PHP version 5.x but coding is done to meet 4.x backward compatibility and may work. Some functions requires PHP >= 5.2.0.

The iCalcreator main class, utility class and helper functions are included in the "iCalcreator.class.php" file.

More iCalcreator supplementary, usage and "howto" information will be found at kigkonsult.se iCalcreator coding and test pages. A strong recommendation is to have the document user's manual open in parallel when exploiting the link.

#### iCal

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

Knowledge of calendar protocol rfc5545/rfc5546 is to recommend;

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

#### xCal

iCalcreator also supports xCal (iCal xml).

rfc6321
  xCal: The XML Format for iCalendar

#### SUPPORT

The main support channel is using iCalcreator Sourceforge forum.

Support and development is now focused on iCalcreator (Pro) 3.x versions, which, in turn, will affect future releases of iCalcreator 2.x.

kigkonsult offer services for software support, design and development of customizations and adaptations of PHP/MySQL solutions with a special focus on software long term utility and reliability, supported through our agile acquire/design/transition process model.

#### 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

Unpack to any folder
  add this folder to your include-path
  or unpack to your application-(include)-folder

Add

    <?php
    .. .
    require_once './iCalcreator.class.php';
    .. .
    ?>

to your php-script.

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

To really boost performance, visit kigkonsult.se contact page for information.

## CREATE

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $tz = "Europe/Stockholm";                                  // define time zone
    $config = array( "unique_id" => "kigkonsult.se",           // set Your unique id,
                                                               // required if any component UID is missing
                     "TZID"      => $tz );                     // opt. set "calendar" timezone
    $v = new vcalendar( $config );                             // create a new calendar object instance

    $v->setProperty( "method", "PUBLISH" );                    // required of some calendar software
    $v->setProperty( "x-wr-calname", "Calendar Sample" );      // required of some calendar software
    $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // required of some calendar software
    $v->setProperty( "X-WR-TIMEZONE", $tz );                   // required of some calendar software
    .. .
    $xprops = array( "X-LIC-LOCATION" => $tz );                // required of some calendar software
    iCalUtilityFunctions::createTimezone( $v, $tz, $xprops );  // create timezone component(-s) opt. 1
    .. .                                                       // based on present date
    .. .
    $vevent = & $v->newComponent( "vevent" );                  // create an event calendar component
    $vevent->setProperty( "dtstart", array( "year"  => 2007
                                          , "month" =>    4
                                          , "day"   =>    1
                                          , "hour"  =>   19
                                          , "min"   =>    0
                                          , "sec"   =>    0 ));
    $vevent->setProperty( "dtend",   array( "year"  => 2007
                                          , "month" =>    4
                                          , "day"   =>    1
                                          , "hour"  =>   22
                                          , "min"   =>   30
                                          , "sec"   =>    0 ));
    $vevent->setProperty( "LOCATION", "Central Placa" );       // property name - case independent
    $vevent->setProperty( "summary", "PHP summit" );
    $vevent->setProperty( "description", "This is a description" );
    $vevent->setProperty( "comment", "This is a comment" );
    $vevent->setProperty( "attendee", "attendee1@icaldomain.net" );
    .. .
    $valarm = & $vevent->newComponent( "valarm" );             // create an event alarm
    $valarm->setProperty("action", "DISPLAY" );
    $valarm->setProperty("description", $vevent->getProperty( "description" );
    .. .                                                       // reuse the event description
    $d = sprintf( '%04d%02d%02d %02d%02d%02d', 2007, 3, 31, 15, 0, 0 );
    iCalUtilityFunctions::transformDateTime( $d, $tz, "UTC", "Ymd\THis\Z");
    $valarm->setProperty( "trigger", $d );                     // create alarm trigger (in UTC datetime)
    .. .
    $vevent = & $v->newComponent( "vevent" );                  // create next event calendar component
    $vevent->setProperty( "dtstart", "20070401", array("VALUE" => "DATE"));// alt. date format,
                                                               //  now for an all-day event
    $vevent->setProperty( "organizer" , "boss@icaldomain.com" );
    $vevent->setProperty( "summary", "ALL-DAY event" );
    $vevent->setProperty( "description", "This is a description for an all-day event" );
    $vevent->setProperty( "resources", "COMPUTER PROJECTOR" );
    $vevent->setProperty( "rrule", array( "FREQ" => "WEEKLY", "count" => 4));// weekly, four occasions
    $vevent->parse( "LOCATION:1CP Conference Room 4350" );     // supporting parse of
                                                               //  strict rfc5545 formatted text
    .. .
    .. .// all calendar components are described in rfc5545
    .. .// a complete iCalcreator function list (ex. setProperty) in iCalcreator manual
    .. .
    iCalUtilityFunctions::createTimezone( $v, $tz, $xprops);   // create timezone component(-s) opt. 2
                                                               // based on all start dates in events
                                                               // (i.e. dtstart)
    .. .
    ?>

## PARSE

#### iCal, rfc5545 / rfc2445

##### create iCalcreator object instance

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $config = array( "unique_id" => "kigkonsult.se" );         // set Your unique id,
    .. .                                                       // required if any component UID is missing
    $v = new vcalendar( $config );                             // create a new calendar object instance
    .. .

##### when parse a local iCal file

    .. .
    $config = array( "directory" => "calendar", "filename" => "file.ics" );
    $v->setConfig( $config );                                  // set directory and file name
    $v->parse();
    .. .                                                       // continue process (edit, parse,select)
    .. .                                                       //  the iCalcreator object instance
    .. .
    ?>

##### or parse a remote iCal file (resource)

    .. .
    $v->setConfig( "url", "http://www.aDomain.net/file.ics" ); // supporting parse of remote files
    $v->parse();
    .. .
    $v->sort();                                                // ensure start date order
    .. .                                                       // (opt., NOT required after parse)
    .. .
    .. .                                                       // continue process (edit, parse,select)
    .. .                                                       //  the iCalcreator object instance
    .. .
    ?>

On error, the parse method returns FALSE.

#### xCal, rfc6321 (XML)

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $config = array( "unique_id" => "kigkonsult.se" );         // set Your unique id,
    .. .                                                       // required if any component UID is missing
    .. .
    $filename = 'xmlfile.xml';                                 // use a local xCal file
    // $filename = 'http://kigkonsult.se/xcal.php?a=1&b=2&c=3';//  or a remote xCal resource
    if( FALSE === ( $v = XMLfile2iCal(  $filename, $config ))) // convert the XML resource
      exit( "Error when parsing $filename" );                  //  to an iCalcreator object instance
    .. .                                                       // continue process (edit, parse,select)
    .. .                                                       //  the iCalcreator object instance
    .. .
    ?>

## EDIT

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $config = array( "unique_id" => "kigkonsult.se"            // set Your unique id,
                   , "directory" => "calendar"                 // import directory
                   , "filename" => "file.ics" );               //  and file name

    $v = new vcalendar( $config );                             // create a new calendar object instance

    $v->parse();

    $v->setProperty( "method", "PUBLISH" );                    // required of some calendar software
    $v->setProperty( "x-wr-calname", "Calendar Sample" );      // required of some calendar software
    $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // required of some calendar software
    $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" );    // required of some calendar software

    while( $vevent = $v->getComponent( "vevent" )) {           // read events, one by one
      $uid = $vevent->getProperty( "uid" );                    // uid required, one occurrence
      .. .                                                     //   (unique id/key for component)
      $dtstart = $vevent->getProperty( "dtstart" );            // dtstart required, one occurrence
      .. .
      if( $description = $vevent->getProperty( "description", 1 )) { // opt. description, 1st occurrence
        .. .                                                   // edit the description
        $vevent->setProperty( "description", $description, FALSE, 1 ); // update/replace the description
      }
      while( $comment = $vevent->getProperty( "comment" )) {   // optional comments
        .. .                                                   // manage comments
      }
      .. .
      while( $vevent->deleteProperty( "attendee" ))
        continue;                                              // remove all ATTENDEE properties .. .
      .. .
      $v->setComponent ( $vevent, $uid );                      // update/replace event in calendar
                                                               //  with UID as key
    }
    .. .
    .. .// a complete iCalcreator function list (ex. getProperty, deleteProperty) in iCalcreator manual
    .. .
    ?>

## SELECT

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $config = array( "unique_id" => "kigkonsult.se" );         // set Your unique id
    $v = new vcalendar( $config );                             // create a new calendar object instance

    $v->setConfig( "url", "http://www.aDomain.net/file.ics" ); // iCalcreator also support remote files
    $v->parse();

    $v->setProperty( "method", "PUBLISH" );                    // required of some calendar software
    $v->setProperty( "x-wr-calname", "Calendar Sample" );      // required of some calendar software
    $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // required of some calendar software
    $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" );    // required of some calendar software
    .. .
    ?>

#### Date based select

    <?php
    .. .
    $eventArray = $v->selectComponents();                      // select components occurring today
                                                               // (including components
                                                               // with recurrence pattern)
    foreach( $eventArray as $year => $yearArray) {
     foreach( $yearArray as $month => $monthArray ) {
      foreach( $monthArray as $day => $dailyEventsArray ) {
       foreach( $dailyEventsArray as $vevent ) {
        $currddate = $event->getProperty( "x-current-dtstart" );
                                                               // if member of a recurrence set
                                                               // (2nd occurrence etc)
                                                               // returns array(
                                                               //     "x-current-dtstart"
                                                               //   , (string) date(
                                                               //     "Y-m-d [H:i:s][timezone/UTC offset]"))
        $dtstart = $vevent->getProperty( "dtstart" );          // dtstart required, one occurrence,
                                                               //  (orig. start date)
        $summary = $vevent->getProperty( "summary" );
        $description = $vevent->getProperty( "description" );
        .. .
        .. .
       }
      }
     }
    }
    .. .
    ?>

#### Select specific property values

    <?php
    .. .
    $valueOccur = $v->getProperty( "RESOURCES" );              // fetch specific property
                                                               // (unique) values and occurrences
                                                               // ATTENDEE, CATEGORIES, CONTACT,
                                                               // DTSTART, LOCATION, ORGANIZER,
                                                               // PRIORITY, RESOURCES, STATUS,
                                                               // SUMMARY, UID, URL,
                                                               // GEOLOCATION*
    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).

#### Select components based on specific property value

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

## OUTPUT

##### create iCalcreator object instance

    <?php
    .. .
    require_once( "iCalcreator.class.php" );
    $config = array( "unique_id" => "kigkonsult.se" );         // set Your unique id
    $v = new vcalendar( $config );                             // create a new calendar object instance

    $v->setProperty( "method", "PUBLISH" );                    // required of some calendar software
    $v->setProperty( "x-wr-calname", "Calendar Sample" );      // required of some calendar software
    $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // required of some calendar software
    $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" );    // required of some calendar software
    .. .
    .. .                                                       // continue process (edit, parse,select)
    .. .                                                       //  the iCalcreator object instance
    .. .
    ?>

##### opt 1

    <?php
    .. .
    $v->returnCalendar();                                      // redirect calendar file to browser
    ?>

##### opt 2

    <?php
    .. .
    $config = array( "directory" => "depot", "filename" => "calendar.ics" );
    $v->setConfig( $config );                                  // set output directory and file name
    $v->saveCalendar();                                        // save calendar to (local) file
    .. .
    ?>

##### opt 3, xCal

    <?php
    .. .
    $mlstr = iCal2XML( $v );                                   // create well-formed XML, rfc6321
    .. .
    ?>

## COPYRIGHT AND LICENSE

#### Copyright

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

#### License

This library 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 2.1 of the License, or (at your option) any later version.

This library 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 this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA or download it here.