Location: PHPKode > projects > PhpiCalLib > doc/PhpiCalLib/tutorial_PhpiCalLib.pkg.html
```<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!-- template designed by Marco Von Ballmoos -->
<title>Introduction</title>
<link rel="stylesheet" href="../media/stylesheet.css" />
<meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'/>
<body>
<div class="page-body">

<table class="tutorial-nav-box">
<tr>
<td style="width: 30%">
<span class="nav-button-disabled">Previous</span>
</td>
<td style="text-align: center">
</td>
<td style="text-align: right; width: 30%">
<a href="../PhpiCalLib/tutorial_examples.pkg.html" class="nav-button">Next</a>
</td>
</tr>
<tr>
<td style="width: 30%">
</td>
<td style="text-align: center">
</td>
<td style="text-align: right; width: 30%">
<span class="detail">Examples</span>
</td>
</tr>
</table>

<div><a name=""></a><div class="ref-title-box"><h1 class="ref-title">Introduction</h1>
<h2 class="ref-purpose">An introduction to PhpiCalLib</h2></div>
<div class="ref-synopsis"><span class="author">Nigel Swinson
<ul class="toc">

<li><a href="../PhpiCalLib/tutorial_PhpiCalLib.pkg.html#description">Description</a></li>

<li><a href="../PhpiCalLib/tutorial_PhpiCalLib.pkg.html#why">Why choose PhpiCalLib</a></li>

<ul class="toc">

<li><a href="../PhpiCalLib/tutorial_PhpiCalLib.pkg.html#why.Alternatives">Alternatives</a></li>

</ul>

</ul>

<span><a name="description"></a><h2 class="title">Description</h2><p>PhpiCalLib is a PHP library that provides an iCalendar parser and object creator.
It is object orientated, unit tested, and conforms strictly to the latest iCalendar standard
(the successor to RFC2445).  The library would have two typical uses:</p>
<ol><li>Parsing an iCalendar file for analysis</li>
<li>Creating an iCalendar file for publication</li></ol>
<p>Note it is not intended that this project will ever provide an iCalendar viewer, rather the target audience
is developers who might want to interrogate iCalendar files for custom use in their application, or produce
iCalendar files using data from some other data sources like the contents of an sql database.</p></span>
<span><a name="why"></a><h2 class="title">Why choose PhpiCalLib</h2><p>There are a lot of software projects in the world now, and it's not always obvious when you should choose
to use one.  Some might be using the wrong technologies, or even no longer be maintained, others might not
be sufficiently complete.  Here's some information to help you consider whether to use this project.</p>
<span><a name="why.Advantages"></a><h3 class="title">Advantages</h3><ul><li><em>Written in Native PHP:</em> meaning it is easy to install, platform independant,
and easy to extend/debug.</li>
<li><em>No dependancies:</em> It is self contained, relying only on core PHP 5 functionality, not part of
PEAR or any other class library</li>
<li><em>Strict adherence to the standard:</em>  The implementation goes for a strict adherence to the
<a href="http://tools.ietf.org/html/draft-ietf-calsify-rfc2445bis-08">latest standard</a>,
soon to be published and obsolete <a href="http://tools.ietf.org/html/rfc2445">RFC2445</a>.  It is worth pointing out that the principle author
of PhpiCalLib contributed to the redrafting of RFC2445.</li>
<li><em>Mature design:</em>  The architect of the project has experience of writing
several parsers, including an iCalendar parser in C++, and has been able to draw from this experience when
implementating this one.</li>
<li><em>Extensible design:</em>  One specific attribute of the design worth highlighting
is that the project has an extensible design.  iCalendar has been designed in a way that makes it possible
to treat unrecognized entries in a generic way as you would a typically iana-prop or x-prop.  Clients can use
unrecognized entities using the generic classes, or choose to override the base classes to provide more robust
validation.</li>
<li><em>Unit tested:</em> The project has a substantial PHPUnit test suite.</li></ul></span>
<span><a name="why.Disadvantages"></a><h3 class="title">Disadvantages</h3><ul><li><em>Written in Native PHP:</em> PHP will ultimately have a core compiled extension
that provides iCalendar support.  This will be faster that a native PHP application ever will be.</li>
<li><em>Performance:</em> By taking a strict view of parsing, the object representation
will be larger than it might be with a less object orientated associative array based view of the data.  It
will also take longer to do all of the strict mostly regular expression based validation of the data.</li>
<li><em>Incomplete:</em> It is likely to remain incomplete, as the author only really
took this project on board due to lack of acceptable solutions already out there.  While shortcuts won't
be taken with the code which is actually needed by the author, until there's actually a need to support
VJOURNAL components there's very little chance explicit strict validation will be added.  As such many
properties/parameters/components are treated as iana-prop/iana-param/iana-comp (unrecognized) would be
which means it's pretty much generic validation, store and forward only.</li></ul></span>
<span><a name="why.Alternatives"></a><h3 class="title">Alternatives</h3><ul><li><a href="http://phpicalendar.net/">PhpiCalendar</a>: Provides an iCalendar viewer, including
parser and user interface.  The parser from V2.22 consisted of 1222 lines of php source containing precisely zero
functions and classes.  The whole thing is essentially a set of foreach/while/switch statements and it wasn't remotely
clear what the interface to the code was.  Presumably setting up various global state variables and then calling
include().</li>
<li><a href="https://sourceforge.net/projects/webcalendar/">WebCalendar</a>: Like PhpiCalendar, this also provides an iCalendar
parser and user interface, and like PhpiCalendar it's iCalendar parsing code is pretty difficult to work
with.  In version 1.2.b1 it is nested amongst a 3050 line file, not object orientated, but it did at least
separate the file into about 50 functions.  The code for constructing iCalendar files is tied to export from it's
own schema, rather than generic use, and the code for parsing an iCalendar file returns a poorly documented
array object.</li>
<li><a href="http://bennu.sourceforge.net/">bennu</a>: There was a lot to like about this project, as the
author shares a similar philosophy to PhpiCalLib, but it was last active July 2005, and is very incomplete.
There were a number of design flaws including global unscoped functions, and a reliance on calling
is_valid_value() on your objects frequently rather than overriding the set() methods to reduce the chance of
ending up with invalid values in the first place.</li>
<li><a href="http://pear.php.net/pepr/pepr-proposal-show.php?id=251">iCal</a> Again an excellent attitude
to standards compliance, and numerous encouraging comments from peer review, however it was just a PEAR
Package Proposal, the files are no longer available for download.  The last active comment was June 2005.</li>
<li><a href="http://pear.php.net/package/File_IMC">File_IMC</a> Proposed to parse vCalendar, the predecessor
to RFC2445, however downloading the source, for vCalendar it says &quot;nothing has needed parsing so far&quot; compared
to vCard, which is ludicrous, and clearly means the project didn't get far.</li>
<li><a href="http://php-flp.sourceforge.net/">FLP</a> Contains an iCalendar class, but it hasn't been updated
since July 2003.  Adding an event constituted a function call on the main calendar object that took 22 arguments.
It seems obvious to me that those arguments should really be attributes of some class, and an object passed in,
but clearly this wasn't obvious to the author of FLP. Likewise the interface was complete, but not extensible,
it supported a very specific set of properties, the common ones, but there was a real risk a project would
out-grow the capabilities of the class.</li>
<li><a href="http://sourceforge.net/projects/icalparser-php/">iCalendar PHP Parser</a> a soureforge
project, registered October 2004, yet to release any files</li></ul></span></span>
<span><a name="latestversion"></a><h2 class="title">Latest Version</h2><p>The latest version will be availabe from the project homepage at <a href="http://scripts.carrubbers.org">http://scripts.carrubbers.org</a></p></span></div>

<table class="tutorial-nav-box">
<tr>
<td style="width: 30%">
<span class="nav-button-disabled">Previous</span>
</td>
<td style="text-align: center">
</td>
<td style="text-align: right; width: 30%">
<a href="../PhpiCalLib/tutorial_examples.pkg.html" class="nav-button">Next</a>
</td>
</tr>
<tr>
<td style="width: 30%">
</td>
<td style="text-align: center">
</td>
<td style="text-align: right; width: 30%">
<span class="detail">Examples</span>
</td>
</tr>
</table>

<p class="notes" id="credit">
Documentation generated on Tue, 01 Apr 2008 01:07:01 +0100 by <a href="http://www.phpdoc.org" target="_blank">phpDocumentor 1.4.0</a>
</p>
</div></body>
</html>
```