Introduction

Introduction – Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Contact_Vcard_Build Description

Allows you to programmatically create a vCard, version 2.1 or 3.0, and fetch the vCard text.

Quick Instructions

  • Download and un-compress Contact_Vcard_Build from the PEAR archive.

  • Include Contact_Vcard_Build.php in your PHP script.

  • Instantiate a new Contact_Vcard_Build object (by default, the vCard version is 3.0, but 2.1 vCards are also supported).

  • Set or add values and parameters that you want in the vCard.

  • Fetch the completed vCard, then use print_r() to view the results.

Example code:

<?php

    
// include the class file
    
require_once 'Contact/Vcard/Build.php';

    
// instantiate a builder object
    // (defaults to version 3.0)
    
$vcard = new Contact_Vcard_Build();

    
// set a formatted name
    
$vcard->setFormattedName('Bolivar Shagnasty');

    
// set the structured name parts
    
$vcard->setName('Shagnasty''Bolivar''Odysseus',
        
'Mr.''III');

    
// add a work email.  note that we add the value
    // first and the param after -- Contact_Vcard_Build
    // is smart enough to add the param in the correct
    // place.
    
$vcard->addEmail('boshag@example.com');
    
$vcard->addParam('TYPE''WORK');

    
// add a home/preferred email
    
$vcard->addEmail('bolivar@example.net');
    
$vcard->addParam('TYPE''HOME');
    
$vcard->addParam('TYPE''PREF');

    
// add a work address
    
$vcard->addAddress('POB 101''Suite 202''123 Main',
        
'Beverly Hills''CA''90210''US');
    
$vcard->addParam('TYPE''WORK');

    
// get back the vCard and print it
    
$text $vcard->fetch();
    echo 
'<pre>';
    
print_r($text);
    echo 
'</pre>';
?>

Differences Between vCard 2.1 and vCard 3.0

The 2.1 specification uses CRLF to terminate lines (\r\n). It allows the following components and parameters:

  • Parameters:

    • TYPE of DOM, INTL, POSTAL, PARCEL, HOME, WORK, PREF, VOICE, FAX, MSG, CELL, PAGER, BBS, MODEM, CAR, ISDN, VIDEO, AOL, APPLELINK, ATTMAIL, CIS, EWORLD, INTERNET, IBMMAIL, MCIMAIL, POWERSHARE, PRODIGY, TLX, X400, GIF, CGM, WMF, BMP, MET, PMB, DIB, PICT, TIFF, PDF, PS, JPEG, QTIME, MPEG, MPEG2, AVI, WAVE, AIFF, PCM, X509, or PGP.

    • ENCODING of 7BIT, 8BIT, BASE64, QUOTED-PRINTABLE

    • VALUE of INLINE, CONTENT-ID, CID, URL, VCARD

    • CHARSET of any ISO charset specification.

    • LANGUAGE is very lenient, basically anything so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).

  • Components and methods

    • VERSION (setVersion())

    • FN (setFormattedName())

    • N (setName())

    • PHOTO (setPhoto())

    • BDAY (setBirthday())

    • ADR (addAddress())

    • LABEL (addLabel())

    • TEL (addTelephone())

    • EMAIL (addEmail())

    • MAILER (setMailer())

    • TZ (setTZ())

    • GEO (setGeo())

    • TITLE (setTitle())

    • ROLE (setRole())

    • LOGO (setLogo())

    • AGENT (setAgent())

    • ORG (addOrganization())

    • NOTE (setNote())

    • REV (setRevision())

    • SOUND (setSound())

    • URL (setURL())

    • KEY (setKey())

The 3.0 specification uses LF to terminate lines (\n). It allows the following components and parameters:

  • Parameters:

    • TYPE of any of the 2.1 TYPE values, or any other value so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).

    • ENCODING of 8BIT and B ("binary").

    • VALUE of BINARY, PHONE-NUMBER, TEXT, URI, UTC-OFFSET, or VCARD.

  • Components and Methods:

    • VERSION (setVersion())

    • FN (setFormattedName())

    • N (setName())

    • NAME (setSourceName())

    • SOURCE (setSource())

    • NICKNAME (addNickname())

    • PHOTO (setPhoto())

    • BDAY (setBirthday())

    • ADR (addAddress())

    • LABEL (addLabel())

    • TEL (addTelephone())

    • EMAIL (addEmail())

    • MAILER (setMailer())

    • TZ (setTZ())

    • GEO (setGeo())

    • TITLE (setTitle())

    • ROLE (setRole())

    • LOGO (setLogo())

    • AGENT (setAgent())

    • ORG (addOrganization())

    • CATEGORIES (addCategories())

    • NOTE (setNote())

    • PRODID (setProductID())

    • REV (setRevision())

    • SORT-STRING (setSortString())

    • SOUND (setSound())

    • UID (setUniqueID())

    • URL (setURL())

    • CLASS (setClass())

    • KEY (setKey())