How Data Is Returned
Description
Contact_Vcard_Parse reads a file or block of text for vCard data, then converts that data into a series of nested arrays. I used to present a detailed prose explanation of the array, but I think it's easier to just give a generic outline of the array:
$parse_result = array (
[int_cardnumber] => array (
[string_datatype] => array (
["param"] => array (
[string_paramname] => array (
[int_repetitionnumber] => string_paramtext
)
)
["value"] => array (
[int_partnumber] => array (
[int_repetitionnumber] => string_valuetext
)
)
)
)
)
By way of example, let's take a look at the vCard of my friend Bolivar Shagnasty.
BEGIN:VCARD
VERSION:3.0
N:Shagnasty;Bolivar;Odysseus;Mr.;III,B.S.
FN:Bolivar Shagnasty
ADR;TYPE=HOME,WORK:;;123 Main,Apartment 101;Beverly Hills;CA;90210
EMAIL;TYPE=HOME;TYPE=WORK:boshag@example.com
EMAIL;TYPE=PREF:boshag@ciaweb.net
END:VCARD
This is a pretty simple vCard: my buddy Bolivar's name, one address (looks like Bolivar works from home), two email addresses (one for work and home, and one as his "preferred" address). This simple vCard, when it gets parsed, looks like this:
(
[0] => Array
(
[VERSION] => Array
(
[0] => Array
(
[param] => Array
(
)
[value] => Array
(
[0] => Array
(
[0] => 3.0
)
)
)
)
[N] => Array
(
[0] => Array
(
[param] => Array
(
)
[value] => Array
(
[0] => Array // family
(
[0] => Shagnasty
)
[1] => Array // first
(
[0] => Bolivar
)
[2] => Array // additional or middle
(
[0] => Odysseus
)
[3] => Array // honorifix prefix
(
[0] => Mr.
)
[4] => Array // honorifix suffix
(
[0] => III
[1] => B.S.
)
)
)
)
[FN] => Array
(
[0] => Array
(
[param] => Array
(
)
[value] => Array
(
[0] => Array
(
[0] => Bolivar Shagnasty
)
)
)
)
[ADR] => Array
(
[0] => Array
(
[param] => Array
(
[TYPE] => Array
(
[0] => HOME
[1] => WORK
)
)
[value] => Array
(
[0] => Array // p.o. box
(
[0] =>
)
[1] => Array // extended
(
[0] =>
)
[2] => Array // street
(
[0] => 123 Main
[1] => Apartment 101
)
[3] => Array // locality or city
(
[0] => Beverly Hills
)
[4] => Array // region, state, or province
(
[0] => CA
)
[5] => Array // postal code
(
[0] => 90210
)
[6] => Array // country
(
[0] =>
)
)
)
)
[EMAIL] => Array
(
[0] => Array
(
[param] => Array
(
[TYPE] => Array
(
[0] => HOME
[1] => WORK
)
)
[value] => Array
(
[0] => Array
(
[0] => boshag@example.com
)
)
)
[1] => Array
(
[param] => Array
(
[TYPE] => Array
(
[0] => PREF
)
)
[value] => Array
(
[0] => Array
(
[0] => boshag@ciaweb.net
)
)
)
)
)
)
Sweet Jebus! That's an ugly mess. But it retains every bit of info about the vCard so you can do what you like with it. It keeps (separately) every element and component so you can see the underlying structure of the vCard.
Yes, I know it's a deeply-nested array set, and is ugly and probably inefficient. The problem (or genius?) of the vCard format is that just about every part of a vCard element can have multiple values. While this makes the vCard format very flexible, it makes it a little difficult to parse and interpret in a simple fashion. The easiest way I could think of was a series of nested arrays. An object-oriented approach might be better, but even then you're going to have nested objects or nested arrays within the vCard object to represent multiple values of a vCard data element.