Location: PHPKode > scripts > iCalcnv > iCalcnv-3.0/README.txt
iCalcnv v3.0
copyright (c) 2009-11 Kjell-Inge Gustafsson, kigkonsult
kigkonsult.se
hide@address.com


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 (<includes>) directory within a webserver document root.

Download iCalcreator from
"http://kigkonsult.se/downloads/index.php#iCalcreator", unzip and place
iCalcreator package files in the <includes> directory.

Include
"require_once '<includes>/iCalcreator.class.php';"
"require_once '<includes>/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 '.<date>.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
hide@address.com

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
Return current item: iCalcnv