IMC Objects 2: Parse and generate vCard and iCalendar files

PHP 5.3+ Based vCard and iCalendar Reader/Writer Classes
redesigned and largely rewritten by CPKS

1. Introduction:

The classes in this package are designed to read and write the IMC-defined files
used by vCard and iCalendar. They enable simple manipulations of blocks of
vCard and iCalendar data. The object hierarchy is designed to be extensible
enough to enable any application sufficient functionality to do what it needs
to do. A simple vCard-generation program has been supplied to demonstrate. The
package files have been split up so as to ensure that if you don't want to
rely on the vagaries of autoload, your life will be reasonably simple.

2. Acknowledgments:

Derived from a package compiled by

 Andreas Haberstroh

and borrowing from a package File_IMC on PEAR written by

 Marshall Roch and
 Paul Jones

and further borrowing from a sourceforge vCard PHP project by

 Frank Hellwig.

3. Licensing:

On licensing, please see the LICENCE file issued with this package.

4. Files in this package:

4.1 imcComponent.php:
This provides the base enclosing classes. It is included in imc_vCard.php.
It defines the class that reads .vcf files and the base functionality of
IMC-encoded components. It provides iterators to access the inner properties.

If you're working with vcards, include imc_vCard.php.

If you're working with iCalendars, include imc_iCal.php.

4.2 imc_vCard.php:
This provides vCard-specific IMC file parsing and a couple of utility methods.

4.3 imc_iCal.php
This provides iCalendar-specific IMC file parsing.

4.4 imcProperty.php:
Each Component has multiple properties; in the case of vCards, properties
comprise name, address, telephone number, e-mail address and so on.
This class manages them. In particular, it manages parsing file data and
encoding.

4.5 imcPropertyADR.php:
This specializes the Property class for vCard addresses. iCalendar people can
ignore this one.

4.6 imcPropertyN.php:
This specializes the Property class for names. iCalendar people can ignore this
one.

4.7 imcPropertyPhoto.php:
This specializes the Property class for vCard photographs. iCalendar people can
ignore this one.

4.8 imcPropertyRRULE.php
This specializes the Property class for iCalendar RRULE properties. vCard people
can ignore this one.

4.9 imc_ptm.php
This is a filter applicable to vCard Property iterators to weed out unwanted
TYPEs. iCalendar people can ignore this one.

4.10 imcPropertydt.php
This is a generic factory class for iCalendar DATE-TIME properties. It enables
modification of time and time zone. Its inclusion is completely optional: if
you don't need to modify these properties, it is more efficient not to include
this file.

4.11 test_vcard.php
Test script that demonstrates building a vCard object from code, parsing
a composite vCard and outputting a simple report (constituent vCards' names and
all work contact details excluding fax).

4.12 outlook_ml.php:
Parses the text file generated by Microsoft Outlook in respect of mailing-list
contacts.

4.13 evolution_maillist.php:
Generates a vCard for a mailing-list contact that can be imported into the
Evolution e-mail client.

4.14 conv_maillist.php:
Converts the text file generated by Microsoft Outlook for a mailing-list into
a vCard importable by the Evolution e-mail client.

4.15 phpdoc.dist.xml:
Assists the phpdoc documentation-generating package in producing documentation
for this package.

5. Documentation

I have elected to tailor this package to the PEAR phpdoc documentation system.
This produces good interactive HTML browsing capabilities together with an
SVG class diagram showing package and namespace relationships as well as
the object inheritance/implementation tree. See http://phpdoc.org/
for installation instructions.

There is also an introductory manual in doc/manual.html.

6. Historical remarks on this package

I've looked cursorily at the earlier sources but they seem old and out of touch
with modern PHP. I have therefore tried to present a newer, cleaner
version of these classes with better object decomposition. I have cheerfully
stolen many great ideas, but I have tested them all and thrown away
anything unworthy. I have tried to represent the original authors' intention
but better re-stated using modern PHP.

Like Andreas Haberstroh, I found myself consulting the original specification
documents. Hopefully I have complied with them.

As to the object design, I note what Andreas Haberstroh writes below about
classes needing to know one another's internals. In his own class design,
however, enclosing classes parsed their enclosed classes' data and fed them to
them using public setter methods. In the present design, constituent classes
parse their data themselves. I strongly recommend this principle to other
software authors.

I have dropped a great many functions from Andreas Haberstroh's design. In part
this is because we no longer need the awkwardnesses imposed on us by the
limitations of object handling in PHP 4. For example, the desire to avoid
referring to the (public) var parameters led to a profusion of getter/setter
functions, which (because they, too, were public) led to a massive confusion
about what should be public, and what private. (Perhaps some member variables
should be public!) The availability of public, private and protected, and
magic __get() and __set() functions, makes all this a lot clearer and drives a
far crisper and more intelligible object design. For another example, there
were the inelegancies forced on us by the use of references - but no, I won't go
there.

A more important concern was that in the old design, the container classes had
so much responsibility for their children. Every time a container class acquired
a new child, it seemed to need a gamut of new functions to pass on. This is a
flawed way to conceive of container classes, although I can sympathize with
Andreas Haberstroh's mistake. I suspect his aim was to insulate the programmer
from the internals of the child classes, by presenting all-singing, all-dancing
parent classes that did everything. Unfortunately, his parent classes were
destined to die, like me, from a surfeit of responsibility (and a lack of easy
extensibility).

Under the new regime, programmers can and must work closer to the class
hierarchy, understand how it interrelates and how it corresponds to the real
world. I hope that the separate documentation I have provided,
as well as the automatically-generated documentation, will provide sufficient
support. See docs/manual.html for more.

It will also be immediately obvious that many, many classes have been used
to simplify sub-problems and that a huge debt of gratitude is due to the author
of the PHP SPL classes. It is easy to define a class, but very hard to design
a class that will encourage everybody else to write better code! I claim only
to have taken up the invitation. My hope is to pass it on.

CPKS

7. README file for the original PHP v4 package (final paragraph omitted)

by Andreas Haberstroh

Ever since I discovered the Internet Mail Consortium website (imc.org) and learned
about vCard and iCalendar files, I've been waiting for a PHP library that could both
read and write these file formats, along with allowing access to the components and
properties in a functional manner. Unfortunately, many attempts that have popped up
on the Internet fall short of usefulness for me. Most classes that I've seen require
direct access to internal class variables. This requires intense knowledge of the
format for vCard and iCalendar. I'm a firm believer in encapsulation. So, I cracked
open the latest RFC's on vCard and iCalendar formats and decided, it's time to
roll my own.

My class library borrowed from a few of the libraries I found. Mostly, I borrowed
the parameter parsing code. I used stuff from File_IMC on PEAR, written by
Marshall Roch <mroch@php.net> and Paul Jones <pmjones@ciaweb.net>. I've also borrowed
code from the vCard PHP project  <http://vcardphp.sourceforge.net>, written by
Frank Hellwig <frank@hellwig.org>.

These classes are broken into the following hierarchical tree:

imcComponent
    imc_vCard

imcProperty
    imcPropertyAdr
    imcPropertyN

imcProperties live inside a imcComponent. The base imcComponent class can also parse
iCalendar files. I'm currently working on a library to deal with iCalendar files.

I've included a simple example application called test_vcard.php. This shows using
the vCard object as a stand alone object, and also parses a simple vcf file and
displays the results.