1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
4 <title>iCalcreator 2.12 summary</title>
5 <meta name="author" content="Kjell-Inge Gustafsson - kigkonsult" />
6 <meta name="copyright" content="2007-2012 Kjell-Inge Gustafsson - kigkonsult" />
7 <meta name="keywords" content="ical, calendar, calender, xcal, xml, icalender, rfc2445, rfc5545, vcalender, php, create" />
8 <meta name="description" content="iCalcreator summary" />
9 <style type="text/css">
11 FONT-FAMILY : "Lucida Grande","Lucida Sans Unicode", "Bitstream Vera Sans", Lucida, Arial, Geneva, Helvetica, sans-serif;
17 FONT-FAMILY : "Lucida Grande","Lucida Sans Unicode", "Bitstream Vera Sans", Lucida, Arial, Geneva, Helvetica, sans-serif;
21 FONT-FAMILY : "Lucida Grande","Lucida Sans Unicode", "Bitstream Vera Sans", Lucida, Arial, Geneva, Helvetica, sans-serif;
25 FONT-FAMILY : "Lucida Grande","Lucida Sans Unicode", "Bitstream Vera Sans", Lucida, Arial, Geneva, Helvetica, sans-serif;
30 FONT-FAMILY : monospace;
43 <h1>iCalcreator v2.12</h1>
44 iCalcreator v2.12<br />
45 copyright (c) 2007-2012 Kjell-Inge Gustafsson, kigkonsult<br />
46 <a href="http://kigkonsult.se/iCalcreator/index.php" title="kigkonsult.se/iCalcreator" target="_blank">kigkonsult.se iCalcreator</a><br>
47 <a href="http://kigkonsult.se/contact/index.php" title="kigkonsult.se/contact" target="_blank">kigkonsult.se contact</a><br>
49 iCalcreator is a <em>PHP</em> class package managing iCal files, supporting (non-)<strong>calendar</strong>
50 systems and applications to process and communicate <strong>calendar</strong> information like
51 events, agendas, tasks, reports, totos and journaling information.
53 This is a <b>short summary</b> how to use iCalcreator; create, parse, edit, select and output functionality.
55 The iCalcreator package, built of a <strong>calendar</strong> class with support of a function class and helper functions, are <strong>calendar</strong>
56 component property oriented. Development environment is <em>PHP</em> version 5.x but coding is done
57 to meet 4.x backward compatibility and may work. Some functions requires <em>PHP</em> >= 5.2.0.
59 The iCalcreator main class, utility class and helper functions are included in the "iCalcreator.class.php" file.
61 More iCalcreator supplementary and "howto" information will be found at
62 kigkonsult.se iCalcreator implement examples and test <a href="http://kigkonsult.se/test/index.php" title="kigkonsult.se iCalcreator implement and test examples" target="_blank">pages</a>.
63 A strong recommendation is to have the document <a href="http://kigkonsult.se/iCalcreator/docs/using.html" title="iCalcreator user's Manual" target="_blank">user's manual</a>
64 open in parallell when exploiting the link.
67 A short iCal description is found at <a href="http://en.wikipedia.org/wiki/ICalendar#Core_object" title="iCalendar From Wikipedia, the free encyclopedia" target="_blank">Wikipedia</a>. If You are not familiar with iCal, read this first!<br />
68 Knowledge of <strong>calendar</strong> protocol rfc5545/rfc5546 is to recommend;<br />
69 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc5545" title="RFC5545" target="_blank">rfc5545</a>
70 - Internet Calendaring and Scheduling Core Object Specification (iCalendar)<br />
71 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc5546" title="RFC5546" target="_blank">rfc5546</a>
72 - iCalendar Transport-Independent Interoperability Protocol (iTIP) Scheduling Events, BusyTime, To-dos and Journal Entries <br />
73 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc5545" title="Download RFC5545 in text format">rfc5545</a> and
74 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc5546" title="Download RFC5546 in text format">rfc5546</a>
75 obsoletes, respectively,
76 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc2445" title="Download RFC2445 in text format">rfc2445</a> and
77 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc2446" title="Download RFC2446 in text format">rfc2446</a>.
81 iCalcreator also supports xCal (iCal xml)<br />
82 <a href="http://kigkonsult.se/downloads/dl.php?f=rfc6321" title="Download RFC6321 in text format" target="_blank">rfc6321</a>
83 - "xCal: The XML Format for <strong>iCalendar</strong>"
87 The main support channel is using iCalcreator
88 <a title="Sourceforge" href="http://sourceforge.net/projects/icalcreator/forums/" target="_blank">Sourceforge</a> forum.
91 kigkonsult offer services for software support, design and development of customizations and adaptations of <em>PHP</em>/<em>MySQL</em> solutions
92 with a special focus on software long term utility and reliability,
93 supported through our agile acquire/design/transition process model.
97 You can show your appreciation for our free software,
98 and can support future development by making a donation to the kigkonsult GPL/LGPL projects.
101 Make a donation of any size by clicking <a href="http://kigkonsult.se/contact/index.php#Donate" title="Donate" target="_blank">here</a>.
106 Use the contact <a href="http://kigkonsult.se/contact/index.php" title="kigkonsult.se/contact" target="_blank">page</a>
107 for queries, improvement/development issues or professional support and development.
108 Please note that paid support or consulting service has the highest priority.
111 <h4>Downloads and usage examples</h4>
112 On <a href="http://kigkonsult.se/iCalcreator/index.php" title="kigkonsult iCalcreator" target="_blank">kigkonsult.se</a> can you download the
113 <a href="http://kigkonsult.se/downloads/index.php#iCalcreator" title="iCalcreator complete manual" target="_blank"><b>complete manual</b></a>
115 <a href="http://kigkonsult.se/test/index.php" title="kigkonsult.se iCalcreator implement and test examples" target="_blank">coding and test examples</b></a>.
119 Unpack to any folder<br />
120 - add this folder to your include-path<br />
121 - or unpack to your application-(include)-folder<br />
122 Add "require_once '[folder/]iCalcreator.class.php';" to your php-script.
125 If using <em>PHP</em> version 5.1 or higher, the default timezone need to be set/altered, now "Europe/Stockholm",
126 line 50 in the iCalcreator.class.php file.
128 When creating a new calendar/component instance, review config settings.
131 To really boost performance, visit kigkonsult.se contact <a href="http://kigkonsult.se/contact/index.php"><u>page</u></a> for information.
138 <p class="code">require_once( "iCalcreator.class.php" );
139 $config = array( "unique_id" => "kigkonsult.se" ); // <span class="comment">set a (site) unique id</span>
140 $v = new vcalendar( $config ); // <span class="comment">create a new calendar instance</span>
141 $tz = "Europe/Stockholm"; // <span class="comment">define time zone</span>
143 $v->setProperty( "method", "PUBLISH" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
144 $v->setProperty( "x-wr-calname", "Calendar Sample" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
145 $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
146 $v->setProperty( "X-WR-TIMEZONE", $tz ); // <span class="comment">required of some <strong>calendar</strong> software</span>
148 $xprops = array( "X-LIC-LOCATION" => $tz ); // <span class="comment">required of some <strong>calendar</strong> software</span>
149 iCalUtilityFunctions::createTimezone( $v, $tz, $xprops ); // <span class="comment">create timezone component(-s) <b>opt. 1</b></span>
150 .. . // <span class="comment">based on present date</span>
152 $vevent = & $v->newComponent( "vevent" ); // <span class="comment">create an event <strong>calendar</strong> component</span>
153 $vevent->setProperty( "dtstart", array( "year"=>2007, "month"=>4, "day"=>1, "hour"=>19, "min"=>0, "sec"=>0 ));
154 $vevent->setProperty( "dtend", array( "year"=>2007, "month"=>4, "day"=>1, "hour"=>22, "min"=>30, "sec"=>0 ));
155 $vevent->setProperty( "LOCATION", "Central Placa" ); // <span class="comment">property name - case independent</span>
156 $vevent->setProperty( "summary", "PHP summit" );
157 $vevent->setProperty( "description", "This is a description" );
158 $vevent->setProperty( "comment", "This is a comment" );
159 $vevent->setProperty( "attendee", "attendee1@icaldomain.net" );
161 $valarm = & $vevent->newComponent( "valarm" ); // <span class="comment">create an event alarm</span>
162 $valarm->setProperty("action", "DISPLAY" );
163 $valarm->setProperty("description", $vevent->getProperty( "description" );
164 .. . // <span class="comment">reuse the event description</span>
166 $d = sprintf( '%04d%02d%02d %02d%02d%02d', 2007, 3, 31, 15, 0, 0 );
167 iCalUtilityFunctions::transformDateTime( $d, $tz, "UTC", "Ymd\THis\Z");
168 $valarm->setProperty( "trigger", $d ); // <span class="comment">create alarm trigger (in UTC datetime)</span>
170 $vevent = & $v->newComponent( "vevent" ); // <span class="comment">create next event calendar component</span>
171 $vevent->setProperty( "dtstart", "20070401", array("VALUE" => "DATE"));// <span class="comment">alt. date format, now for an all-day event</span>
172 $vevent->setProperty( "organizer" , "boss@icaldomain.com" );
173 $vevent->setProperty( "summary", "ALL-DAY event" );
174 $vevent->setProperty( "description", "This is a description for an all-day event" );
175 $vevent->setProperty( "resources", "COMPUTER PROJECTOR" );
176 $vevent->setProperty( "rrule", array( "FREQ" => "WEEKLY", "count" => 4));// <span class="comment">weekly, four occasions</span>
177 $vevent->parse( "LOCATION:1CP Conference Room 4350" ); // <span class="comment">supporting parse of strict rfc5545 formatted text</span>
179 .. .// <span class="comment">all calendar components are described in <a href="http://kigkonsult.se/downloads/dl.php?f=rfc5545" title="RFC5545" target="_blank">rfc5545</a></span>
180 .. .// <span class="comment">a complete iCalcreator function list (ex. setProperty) in <a href="http://kigkonsult.se/downloads/index.php#iCalcreator" title="iCalcreator complete manual" target="_blank">iCalcreator manual</a></span>
182 iCalUtilityFunctions::createTimezone( $v, $tz, $xprops); // <span class="comment">create timezone component(-s) <b>opt. 2</b></span>
183 .. . // <span class="comment">based on all start dates in events (i.e. dtstart)</span>
191 <h4>iCal, rfc5545 / rfc2445 </h4>
192 <p class="code">require_once( "iCalcreator.class.php" );
193 $config = array( "unique_id" => "kigkonsult.se" ); // <span class="comment">set a (site) unique id, required if any component UID is missing</span>
194 $v = new vcalendar( $config ); // <span class="comment">create a new <strong>calendar</strong> instance</span>
196 /* start parse of local iCal file */
197 $config = array( "directory" => "calendar", "filename" => "file.ics" );
198 $v->setConfig( $config ); // <span class="comment">set directory and file name</span>
201 /* start parse of remote iCal file */
202 $v->setConfig( "url", "http://www.aDomain.net/file.ics" ); // <span class="comment">iCalcreator also support parse of remote files</span>
205 $v->setProperty( "method", "PUBLISH" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
206 $v->setProperty( "x-wr-calname", "Calendar Sample" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
207 $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
208 $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
211 $v->sort(); // <span class="comment">ensure start date order</span>
213 .. . // <span class="comment">continue process (edit, parse,select) the iCalcreator instance</span>
217 <h4>xCal, rfc6321 (XML)</h4>
218 <p class="code">require_once( "iCalcreator.class.php" );
219 $config = array( "unique_id" => "kigkonsult.se" ); // <span class="comment">set a (site) unique id, required if any component UID is missing</span>
221 $filename = 'xmlfile.xml'; // <span class="comment">use a local xCal file</span>
222 // $filename = 'http://kigkonsult.se/xcal.php?a=1&b=2&c=3';// <span class="comment">or a remote xCal resource</span>
223 if( FALSE === ( $v = XMLfile2iCal( $filename, $config ))) // <span class="comment">convert the XML resource to an iCalcreator instance</span>
224 exit( "Error when parsing $filename" );
226 .. . // <span class="comment">continue process (edit, parse,select) the iCalcreator instance</span>
232 <p class="code">require_once( "iCalcreator.class.php" );
233 $config = array( "unique_id" => "kigkonsult.se", "directory" => "calendar", "filename" => "file.ics" );
234 // <span class="comment">set the (site) unique id, the import directory and file name</span>
235 $v = new vcalendar( $config ); // <span class="comment">create a new calendar instance</span>
239 $v->setProperty( "method", "PUBLISH" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
240 $v->setProperty( "x-wr-calname", "Calendar Sample" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
241 $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
242 $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
244 while( $vevent = $v->getComponent( "vevent" )) { // <span class="comment">read events, one by one</span>
245 $uid = $vevent->getProperty( "uid" ); // <span class="comment">uid required, one occurrence (unique id/key for component)</span>
247 $dtstart = $vevent->getProperty( "dtstart" ); // <span class="comment">dtstart required, one occurrence</span>
249 if( $description = $vevent->getProperty( "description", 1 )) { // <span class="comment">description optional, first occurrence</span>
250 .. . // <span class="comment">edit the description</span>
251 $vevent->setProperty( "description", $description, FALSE, 1 ); // <span class="comment">update/replace the description</span>
253 while( $comment = $vevent->getProperty( "comment" )) { // <span class="comment">comment optional, may occur more than once </span>
254 .. . // <span class="comment">manage comments</span>
257 while( $vevent->deleteProperty( "attendee" ))
258 continue; // <span class="comment">remove all ATTENDEE properties .. .</span>
260 $v->setComponent ( $vevent, $uid ); // <span class="comment">update/replace event in calendar with <b>UID</b> as key </span>
263 .. .// <span class="comment">a complete iCalcreator function list (ex. getProperty, deleteProperty) in <a href="http://kigkonsult.se/downloads/index.php#iCalcreator" title="iCalcreator complete manual" target="_blank">iCalcreator manual</a></span>
270 <p class="code">require_once( "iCalcreator.class.php" );
271 $config = array( "unique_id" => "kigkonsult.se" ); // <span class="comment">set a (site) unique id</span>
272 $v = new vcalendar( $config ); // <span class="comment">create a new <strong>calendar</strong> instance</span>
274 $v->setConfig( "url", "http://www.aDomain.net/file.ics" ); // <span class="comment">iCalcreator also support remote files</span>
276 $v->sort(); // <span class="comment">ensure start date order</span>
278 $v->setProperty( "method", "PUBLISH" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
279 $v->setProperty( "x-wr-calname", "Calendar Sample" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
280 $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
281 $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
283 <h4>Select components based on specific date period</h4>
284 <p class="code">$eventArray = $v->selectComponents(); // <span class="comment">select components occurring <b>today</b></span>
285 // <span class="comment">(including components with recurrence pattern)</span>
286 foreach( $eventArray as $year => $yearArray) {
287 foreach( $yearArray as $month => $monthArray ) {
288 foreach( $monthArray as $day => $dailyEventsArray ) {
289 foreach( $dailyEventsArray as $vevent ) {
290 $currddate = $event->getProperty( "x-current-dtstart" );
291 // <span class="comment">if member of a recurrence set (2nd occurrence etc)</span>
292 // <span class="comment">returns array( "x-current-dtstart"</span>
293 // <span class="comment"> , <(string) date("Y-m-d [H:i:s][timezone/UTC offset]")>)</span>
294 $dtstart = $vevent->getProperty( "dtstart" ); // <span class="comment">dtstart required, one occurrence, (orig. start date)</span>
295 $summary = $vevent->getProperty( "summary" );
296 $description = $vevent->getProperty( "description" );
304 <h4>Select specific property values</h4>
305 <p class="code">$valueOccur = $v->getProperty( "RESOURCES" ); // <span class="comment">fetch specific property (unique) values and occurrences</span>
306 // <span class="comment">ATTENDEE, CATEGORIES, DTSTART, LOCATION,</span>
307 // <span class="comment">ORGANIZER, PRIORITY, RESOURCES, STATUS,</span>
308 // <span class="comment">SUMMARY, UID</span>
309 foreach( $valueOccur as $uniqueValue => $occurCnt ) {
310 echo "The RESOURCES value <b>$uniqueValue</b> occurs <b>$occurCnt</b> times<br />";
314 <h4>Select components based on specific property value</h4>
315 <p class="code">$selectSpec = array( "CATEGORIES" => "course1" );
316 $specComps = $v->selectComponents( $selectSpec ); // <span class="comment">selects components based on specific property value(-s)</span>
317 // <span class="comment">ATTENDEE, CATEGORIES, LOCATION, ORGANIZER,</span>
318 // <span class="comment">PRIORITY, RESOURCES, STATUS, SUMMARY, UID</span>
319 foreach( $specComps as $comp ) {
327 <p class="code">require_once( "iCalcreator.class.php" );
328 $config = array( "unique_id" => "kigkonsult.se" ); // <span class="comment">set a (site) unique id</span>
329 $v = new vcalendar( $config ); // <span class="comment">create a new calendar instance</span>
331 $v->setProperty( "method", "PUBLISH" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
332 $v->setProperty( "x-wr-calname", "Calendar Sample" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
333 $v->setProperty( "X-WR-CALDESC", "Calendar Description" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
334 $v->setProperty( "X-WR-TIMEZONE", "Europe/Stockholm" ); // <span class="comment">required of some <strong>calendar</strong> software</span>
336 .. . // <span class="comment">continue process (edit, parse,select) the iCalcreator instance</span>
341 $v->returnCalendar(); // <span class="comment">redirect calendar file to browser</span>
346 $config = array( "directory" => "depot", "filename" => "calendar.ics" );
347 $v->setConfig( $config ); // <span class="comment">set output directory and file name</span>
348 $v->saveCalendar(); // <span class="comment">save calendar to (local) file</span>
354 $xmlstr = iCal2XML( $v ); // <span class="comment">create well-formed XML, rfc6321</span>
361 <h2>COPYRIGHT AND LICENSE</h2>
364 iCalcreator v2.12<br />
365 copyright (c) 2007-2012 Kjell-Inge Gustafsson, kigkonsult<br />
366 <a href="http://kigkonsult.se/iCalcreator/index.php" title="kigkonsult.se/iCalcreator" target="_blank">kigkonsult.se iCalcreator</a><br>
367 <a href="http://kigkonsult.se/contact/index.php" title="kigkonsult.se/contact" target="_blank">kigkonsult.se contact</a><br>
372 This library is free software; you can redistribute it and/or
373 modify it under the terms of the GNU Lesser General Public
374 License as published by the Free Software Foundation; either
375 version 2.1 of the License, or (at your option) any later version.
377 This library is distributed in the hope that it will be useful,
378 but WITHOUT ANY WARRANTY; without even the implied warranty of
379 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
380 Lesser General Public License for more details.
382 You should have received a copy of the GNU Lesser General Public
383 License along with this library; if not, write to the Free Software
384 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
385 or download it <a href="http://kigkonsult.se/downloads/dl.php?f=LGPL" target="_blank">here</a>.