PHP Classes

File: README

Recommend this page to a friend!
  Classes of CPK Smithies   IMC Objects 2   README   Download  
File: README
Role: Documentation
Content type: text/plain
Description: Basic documentation
Class: IMC Objects 2
Parse and generate vCard and iCalendar files
Author: By
Last change: Correct instructions re documentation generator
Date: 11 years ago
Size: 8,744 bytes
 

Contents

Class file image Download
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.