iCalcnv v3.0 copyright (c) 2009-11 Kjell-Inge Gustafsson, kigkonsult kigkonsult.se ical@kigkonsult.se DESCRIPTION =========== iCalcnv is a PHP utility class converting iCal RFC5545(RFC2445) to xls and csv format and from csv format to iCal. iCalcnv requires iCalcreator class, to be downloaded from "http://kigkonsult.se/downloads/index.php#iCalcreator". iCalcnv support local and remote iCal/csv input files as well as an iCalcreator vcalendar instance. The iCal2csv method converts from iCal to csv format and output is redirected to browser (default) or saved to disc. The iCal2xls method converts iCal to spreadsheet xls file format and requires PHP PEAR Spreadsheet_Excel_Writer-0.9.2 and OLE-1.0.0RC1. Output is redirected to browser (default) or saved to disc. The csv2iCal method converts from csv file format to iCal format and makes it also possible to create a time schedule or plan in a spreadsheet, "save'as" a csv file, convert file to iCal format and update a calendar application. Output is an iCal file, redirected to browser (default) or saved to disc, or an iCalcreator vcalendar instance. iCalcnv may use PEAR Log (or eClog package, to be downloaded from "http://kigkonsult.se/downloads/index.php#eClog"). Definition of csv can be found at "http://en.wikipedia.org/wiki/Comma-separated_values". To get a proper understanding of iCal, explore the RFC5545(RFC2445), download from "http://kigkonsult.se/downloads#rfc". ICAL TO XLS/CSV =============== Input file format to iCal2xls and iCal2csv methods are an iCal RFC2445/5545 file (*.ics) or an iCalcreator vcalendar instance. Output file format are xls/csv formatted and row oriented. Using the 'setConfig' method allows setting input directory/filename alt. url or iCalcreator vcalendare instance output directory (opt) and filename define of csv field delimiter and separator as well as new line characters mapping from iCal property names to user friendly (column) names order output columns iCal properties to skip from output In top of output comes rows with product, date and file information, then opt. calendar properties like METHOD, CALSCALE and X-PROPerties with name and value. Next comes opt. timezone/standard/daylight components in row order, with a leading header row, every component in a separate row, every property in a separate column, starting with columns for component type and order. The event components (vevent/vtodo/vfreebusy/vjournal and corresponding valarms) are also presented in row order, with a leading header row, like the timezone part above, components in rows and their properties in separate columns, also starting with columns for component type and order. Alarms, if any, comes right after corresponding vevent/vtodo component row. CSV TO ICAL =============== Input csv file format to method csv2iCal is actually output csv file format above. Output file format is an iCal RFC2445/5545 file (*.ics) or an iCalcreator vcalendar instance. When converting from xls format to iCal, use spreadsheet application function 'save'as' a CSV file (extension csv) and select, if possible, field separator comma ',', field delimiter double quote '"' and, if selectable and also depending on PHP configuration and platform, 'UTF-8' as character set. Using the 'setConfig' method allows setting input directory and filename alt. url output directory/filename or iCalcreator vcalendare instance define of other field delimiter and separator characters (setConfig below) mapping to iCal property names from user friendly (column) names When parsing the csv file, empty rows or empty property values are skipped. If exist, the product, date and file information are skipped. Any opt. rows containing calendar properties like METHOD, CALSCALE and X-PROPerties updates the calendar. (METHOD property as well as x-properties "X-WR-CALNAME", "X-WR-CALDESC" and "X-WR-TIMEZONE" may be required later when importing iCal files into some calendaring software (MS etc.).) This part may be missing in the csv file when converting to iCal format. The timezone part, if exist, MUST start with a leading header row. The header row MUST have a "TYPE" column header in first column and the "TZID" property header MUST exist in header row. Any standard/daylight components, if exist, MUST appear directly after corresponding timezone component. This part may be missing in the csv file. The event components (vevent/vtodo/vfreebusy/vjournal and corresponding valarms) part MUST start with a leading header row and MUST have a "TYPE" column in the first column. Any alarms, if exist, MUST appear directly after corresponding component. The event part MUST exist in the csv file. The content in the both header row (as well as for calendar properties) columns are case and, except for "TYPE" (col 1), order independent, but MUST contain strict RFC2445 property names or, using config setting, user fiendly mapped names. The values in the "TYPE" column MUST use strict RFC2445 component name: VTIMEZONE, STANDARD, DAYLIGHT, VEVENT, VTODO, VJOURNAL, VFREEBUSY and VALARM. The "ORDER" column in csv(/xls) input file is ignored when parsed, used only for information. Opt. X-PROPerties in calendar, timezone, event (etc) or alarm components are supported. Each property contents (within a row-column 'cell') are assumed to be in a strict RFC2445/5545 format, ex. dates (DTSTART, DTEND, DUE) may be prefixed by TZID or VALUE DATETIME/DATE parameters, RELATED-TO by RELTYP parameter, RECURRENCE-ID by RANGE parameter, FREEBUSY by FBTYPE parameter, COMMENT by LANGUAGE parameter etc. Properties with multiple occurence within a component like ATTENDEE, COMMENT etc. are assumed to be in one "field" (i.e. a cell, content within (default) double quote as field delimiters) separated by newline character(-s). INSTALL ======= Unpack to any () directory within a webserver document root. Download iCalcreator from "http://kigkonsult.se/downloads/index.php#iCalcreator", unzip and place iCalcreator package files in the directory. Include "require_once '/iCalcreator.class.php';" "require_once '/iCalcnv.class.php';" where appropriate. The iCal2xls method requires install of PHP PEAR packages Spreadsheet_Excel_Writer-0.9.2 (and OLE-1.0.0RC1), to be installed as "pear install channel://pear.php.net/OLE-1.0.0RC1" "pear install channel://pear.php.net/Spreadsheet_Excel_Writer-0.9.2" If using PHP PEAR LOG package (optional), please examine 'http://pear.php.net' for install and configuration. Include "require_once 'Log.php';" where appropriate. Another log option is eClog, to be downloaded from "http://kigkonsult.se/downloads#index.php#eClog". METHODS ======= ----------- constructor ----------- $iCalcnv = new iCalcnv( [log] ); log: (opt) PHP PEAR log instance (alt. eClog) --------- setConfig --------- setConfig() Using setConfig with no arguments resets all config to defaults. setConfig( string/int key, mixed value ) Single config setting (keys below). setConfig( configs ) configs: array( *[ string/int key => mixed value ] ) Multiple config setting. key value 'inputdirectory' directory for input file, default '.' readablility is checked when setting ignored if using an iCalcreator vcalendar instance as input 'inputfilename' filename for input file for iCal2csv/iCal2xls, file extension 'ics' required for csv2iCal, file extension 'csv' required readablility is checked when setting MUST be set after 'inputdirectory' ignored if using an iCalcreator vcalendar instance as input 'inputurl' url for input file (or web resource) ignored if using an iCalcreator vcalendar instance as input also ignored if 'inputfilename' is set 'save' true/FALSE (default) save output to disc or redirect to browser MUST be set before 'outputdirectory' 'outputdirectory' directory for output file, default '.' required when 'save' is set to true (if NOT default '.') writeablility is checked when setting 'outputfilename' filename for output file writeablility is checked when setting, if 'save' is set to true MUST be set after 'outputdirectory' (or not) (if missing, 'inputfilename' is used with altered extension) 'backup' true/FALSE (default) to backup previous version of output file if set, it requires 'save' set to true and 'outputfilename' specified backup filename suffixed by '..old' (date:YmdHis from filemtime) MUST be set after 'save' (or not) 'outputobj' true/FALSE (default) for csv2iCal, if true, an iCalcreator vcalendar instance is returned (ignores any 'save' setting) 'unique_id' site unique id, used in iCalcreator creating component UID, if missing default $_SERVER['SERVER_NAME'] or 'localhost' 'del' field delimiter, default '"' (double quote) (iCal2csv/csv2iCal) 'sep' field separator, default ',' (comma) (iCal2csv/csv2iCal) 'nl' iCal2csv new line character(-s) default PHP_EOL (iCal2csv) 'skip' array, iCal property (names) to skip in output, (iCal2csv/iCal2xls) a numeric key, pointing to an iCal property name, allocate column number for property (iCal2csv/iCal2xls) An iCal property name as key, pointing to an alias, using user friendly (column) names instead of iCal property names in output (iCal2csv/iCal2xls) (re-)mapping user friendly (column) names to iCal property names (csv2iCal) On single config setting, note configuration key order! On multiple config setting, order is controlled and reordered. Returns FALSE on error (details in (opt.) log file), otherwise TRUE. --------- getConfig --------- getConfig( string/int key [, int subkey] ) key any key above subkey any 'skip' subkey, above Returns key value or FALSE if not found (error details in (opt.) log file). -------- iCal2csv -------- $iCalcnv->iCal2csv( [iCalObj] ); iCalObj: Input iCalcreator vcalendar instance (opt) 'inputfilename' is fetched from iCalcreator vcalendar instance If not set, 'outputfilename' is generated from 'inputfilename' with altered extension. When config 'save' is set (TRUE) (saving output file on disc), TRUE is returned on success, FALSE on error. When 'save' is NOT set (FALSE), output file is redirected to browser and TRUE is returned. If error occurs, FALSE is returned. Execution and error details (if any) in (opt.) log file. -------- csv2iCal -------- $iCalcnv->csv2iCal(); If not set, 'outputfilename' is generated from 'inputfilename' with altered extension. When config 'outputobj' is set (TRUE), an iCalcreator vcalendar instance is returned on success. If error occurs, FALSE is returned. Or, when config 'save' is set (TRUE) (saving output file on disc), TRUE is returned on success, FALSE on error. Last option, when config 'save' is NOT set (FALSE), output file is redirected to browser and TRUE is returned. If error occurs, FALSE is returned. Execution and error details (if any) in (opt.) log file. -------- iCal2xls -------- $iCalcnv->iCal2xls( [iCalObj] ); iCalObj: Input iCalcreator vcalendar instance (opt) 'inputfilename' is fetched from iCalcreator vcalendar instance If not set, 'outputfilename' is generated from 'inputfilename' with altered extension. When config 'save' is set (TRUE) (saving output file on disc), TRUE is returned on success, FALSE on error. When config 'save' is NOT set (FALSE), output is redirected to browser and TRUE is returned. If error occurs, FALSE is returned. Execution and error details (if any) in (opt.) log file. TEST ==== The kigkonsult package 'tiCalFile' is creating a valid calendar file (using current date and time), usable when testing calendar software etc, download the package from "http://kigkonsult.se/downloads/index.php#tiCalFile" OR download a valid iCal test file, produced with the package, from "http://kigkonsult.se/tiCalFile/index.php" and place in the 'calendars' directory. FILE LIST ========= calendars/ directory(*), calendar file storage (r+w access) csvxlsStorage/ directory(*), cvs and xls storage (r+w access) encoded/ directory(**), iCalcnv and iCalcreator encoded class files iCalcnv.class.php iCalcnv class file images/ free iCal/xls/csv images to use iCalcnvTest.php test script testcases.txt test cases executed in iCalcnvTest.php LGPL.txt licence README.txt this file (*) proposal and/or for testing (**) Boost performance, below SUPPORT ======= Use 'http://kigkonsult.se/contact/index.php' page for queries, improvement or development issues or professional support and development. Please note that paid support or consulting service has the highest priority. Our services are available for support and designing and developing iCalcnv, iCalcreator etc. customizations, adaptations and other PHP/MySQL solutions with a special focus on software utility and reliability, supported through our agile acquire/design/transition process modell. Donate ====== You can show your appreciation for our free software, and can support future development by making a donation to the kigkonsult project iCalcnv. Make a donation of any size at 'http://kigkonsult.se/contact/index.php#Donate'. Thanks in advance! Boost performance ================= To really boost performance, kigkonsult can offer PHP packages (iCalcnv, iCalcreator etc) in byte coded files, using ionCube (http://www.ioncube.com/?xp=SRLGBR) encoder. Encoded files use a platform independent file format, and can be run on any platform for which ionCube supply a (free) Loader. Currently supported platforms are Windows (e.g. NT, XP, W2K), Intel Linux, FreeBSD, NetBSD, OpenBSD, OS X, and Sparc Solaris. Visit 'http://kigkonsult.se/contact/index.php#Boost' for information and/or purchase. COPYRIGHT & LICENCE =================== COPYRIGHT iCalcnv v3.0 copyright (c) 2009-11 Kjell-Inge Gustafsson, kigkonsult kigkonsult.se ical@kigkonsult.se LICENCE 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