PHP Classes

IMC Objects 2: Parse and generate vCard and iCalendar files

Recommend this page to a friend!
  Info   View files View files (19)   DownloadInstall with Composer Download .zip   Reputation   Support forum (4)   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 447 All time: 6,171 This week: 339Up
Version License PHP version Categories
imc 1.1Public Domain5.3Text processing
Description Author

This package can parse and generate vCard and iCalendar files.

This is an enhanced version of another package originally written by Andreas Haberstroh.

This version makes extensive use of SPL classes for object decomposition.


Import vCard on my database
I want to import vCard file in my PostgreSQL database

Picture of CPK Smithies
  Performance   Level  
Name: CPK Smithies <contact>
Classes: 7 packages by
Country: United Kingdom
Age: 68
All time rank: 152369 in United Kingdom
Week rank: 544 Up21 in United Kingdom Up
Innovation award
Innovation award
Nominee: 4x

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

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

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

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
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

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

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.


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

by Andreas Haberstroh

Ever since I discovered the Internet Mail Consortium website ( 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 <> and Paul Jones <>. I've also borrowed
code from the vCard PHP project  <>, written by
Frank Hellwig <>.

These classes are broken into the following hierarchical tree:



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.
  Files folder image Files  
File Role Description
Files folder imagedoc (1 file)
Accessible without login Plain text file conv_maillist.php Example Example program to convert MS Outlook mailing list .txt files into Evolution-compatible vCards
Plain text file evolution_maillist.php Class Specialization of vCard to produce Evolution-compatible mailing list vCards
Plain text file imcComponent.php Class Base container and component classes
Plain text file imcProperty.php Class Base Property classes for both iCalendar and vCard
Plain text file imcPropertyADR.php Class Address Property for vCard ADR properties
Plain text file imcPropertydt.php Class Generic Date-Time Property for iCalendar DTSTART, DTEND, COMPLETED and similar records
Plain text file imcPropertyN.php Class Name Property for vCard N records
Plain text file imcPropertyPhoto.php Class Photo Property for vCard PHOTO records
Plain text file imcPropertyRRULE.php Class RRULE Property for iCalendar RRULE records
Plain text file imc_iCal.php Class iCalendar component
Plain text file imc_ptm.php Class Property Filter for masking out vCard properties of unwanted TYPE
Plain text file imc_vCard.php Class vCard component
Accessible without login Plain text file LICENCE Lic. Basic documentation
Accessible without login Plain text file outlook_ml.php Aux. Class to parse mailing-list data from a .txt file exported from MS Outlook
Accessible without login Plain text file phpdoc.dist.xml Conf. Control file for phpdoc documentation system
Accessible without login Plain text file README Doc. Basic documentation
Accessible without login Plain text file test_ml.txt Data Sample MS Outlook mailing list .txt export
Accessible without login Plain text file test_vcard.php Example Example code

  Files folder image Files  /  doc  
File Role Description
  Accessible without login HTML file manual.html Doc. Overview Documentation

 Version Control Reuses Unique User Downloads Download Rankings  
This week:0
All time:6,171
This week:339Up
For more information send a message to info at phpclasses dot org.