[PROPOSAL] File_IMC

Proposal: File_IMC Sept. 25, 2003 Paul M. Jones and Marshall Roch Overview -------- We would like to propose a new package, File_IMC, to handle parsing and building of Internet Mail Consortium files, such as vCard and vCalendar. Although Contact_Vcard exists, the original author (Paul M. Jones) is willing to deprecate it in favor of the usability gains we expect from the File_IMC package. Background ---------- vCard and vCalendar are specifications from the Internet Mail Consortium (IMC) [1] regarding Personal Data Interchange (PDI). According to the IMC, PDI "occurs every time two or more individuals communicate, in either a business or personal context, face-to-face, or across space and time." vCard and vCalendar are used in many programs, including Outlook, Mozilla Mail, Mozilla Calendar, Evolution, and Palm Desktop. iCalendar is vCalendar 2.0, and is defined by IETF RFC 2445. [2] The Problem ----------- vCard and vCalendar formats are very similar. PEAR's Contact_Vcard_Parse [3] and Contact_Vcard_Build [4] already contain much of the code needed to create and parse vCalendar files. Copying the relevant parts of the Contact_Vcard packages to a new vCalendar package would fork development and make it harder to improve both. The Proposed Solution --------------------- To avoid reinventing the wheel, the Contact_Vcard packages by Paul M. Jones will be refactored into a new package called File_IMC by Marshall Roch. As File_IMC nears completion, Contact_Vcard will be marked as deprecated in favor of the new File_IMC package, although bugs discovered during File_IMC development will be fixed in the Contact_Vcard source package. Methods that can be used by both vCard and vCalendar have been split into common classes. The parser has been modified to allow it to support the more complicated vCalendar format in addition to vCard. File_IMC currently supports: - Parsing vCard 2.1 and 3.0 files and strings (based on Contact_Vcard) - Building vCard 2.1 and 3.0 files and strings (based on Contact_Vcard) - Parsing vCalendar 1.0 files and strings (new for File_IMC) Planned for development: - Building of vCalendar 1.0 files and strings - Parsing of iCalendar (vCal 2.0) files - Building of iCalendar (vCal 2.0) files Backwards Compatibility Issues ------------------------------ There are three minor BC breaks compared to Contact_Vcard's API, but this is not a problem, since File_IMC is a new package. 1) To support vCalendar, the resulting array structure has changed slightly ($info[0]... to $info['VCARD'][0]...). This way the different IMC events can be incorporated into the existing data structure (e.g., $cardinfo['VEVENT'][0], $info['VTODO'][0], and so on). 2) The new factory pattern will require a simple search/replace on existing code.

    $parse = new Contact_Vcard_Parse();

would become:

    $parse = File_IMC::parse('vCard');

3) The initial vCard 2.1 spec notes that "groups" should be supported as well. A group is identified by a text-and-dot prefix to any vCard typedef (e.g., "HOME.ADR" would be the HOME group for the ADR typedef, not to be confused with the "type=HOME" parameter on the typedef). The current Contact_Vcard_* packages do not support groups, but File_IMC will, and the changes will be ported back to Contact_Vcard_*. While this is not strictly a backwards comaptibility issue, we include it here in the interest of full disclosure. Files ----- Package: http://www.exclupen.com/misc/pear/File_IMC/File_IMC-0.2.tgz Source and examples: http://www.exclupen.com/misc/pear/File_IMC/ Call For Votes -------------- We are not calling for votes on the File_IMC proposal at this time; we want to get a feel from the PEAR community on how this package might be received. If response is mostly positive, we will call for votes at a later time. -- [1] http://www.imc.org/pdi/ [2] http://www.ietf.org/rfc/rfc2445.txt [3] http://pear.php.net/package/Contact_Vcard_Parse [4] http://pear.php.net/package/Contact_Vcard_Build