Usage

Using the library for reading vCards

First, you need to actually create the vCard object to read the vCard. Include the library, e.g., include('vCard.php'); and create the vCard object:

$vCard = new vCard('Example.3.0.vcf');

This will create object you can use to access the data in the vCard. Now, as vCard files can actually contain multiple vCards, you need to check for that. Fortunately, it is easy to get the count of vCards in the file - count($vCard) returns the number of vCards in the file. If there is just one vCard in the file, you can use this object to get any element from this vCard, otherwise you have to go over this object with foreach to get every individual vCard. Example:

if (count($vCard) == 1)
{
    print_vcard($vCard);
}
else
{
    foreach ($vCard as $vCardPart)
    {
        print_vcard($vCardPart);
    }
}

Now that you can get to each vCard, you can access the vCard elements as object properties, for example:

print_r($vCard -> n);
print_r($vCard -> tel);

You have to use the element names that are used in the vCard specification, e.g., n, tel, add, org, fn. You can read more about the vCard elements here (Warning: the list is not finished). You do have to take into account that with vCards from different sources, some can deviate from the standard. This library tries to do its best in such situations but it may fail sometimes. In such cases it's best to report the issue here.

Q&A

1. Can I parse raw vCard text instead of a file? Yes, it can be passed as the second parameter to the constructor. For example:

$RawvCardText = '[..]';
$vCard = new vCard(false, $RawvCardText);

2. What's with all the arrays? Every element will be returned as an array containing the values because there can be multiple values for almost every element of the vCard. If you want a single value returned when there is only a single value there, you can specify it with an option to the constructor, e.g.:

$vCard = new vCard('Example.3.0.vcf', false, array('Collapse' => true));

The array with the Collapse key is the options array. Collapse means that arrays with single value will be returned as that one value instead of the array. The default behavior is to return the array because it might be easier for any kind of automated data extraction (i.e., the element will always be an array, you won't have to check the types and number of values on your side, etc.)