pleb/vcardio

Parse vCards from files (.vcf) or raw data. Build vCards from scratch. Export vCards as string or file.

1.1.1 2024-11-03 15:23 UTC

Requires

• php: ^8.1
• ramsey/uuid: ^3.0|^4.0

Requires (Dev)

• laravel/pint: ^v1.0
• pestphp/pest: ^v2.0|^v3.0
• symfony/var-dumper: ^v6.2|^7.0

MIT

• Pierre Lebedel

• vCard
• vcf

README

This package based on RFC 6350 is intended to simplify the parsing and the manipulation of vCard objects, coming from .vcf files or from raw data. It allows you to build vCard objects & export them to text or .vcf files.

Installation

Via composer:

composer require pleb/vcardio

Documentation

• Parsing data
• vCards collection
• vCard builder
• vCard object
• Exporting files

Usage

Parsing data

You can parse vCards objects from .vcf file or from raw data, and obtain an iterable collection of vCards.

$vCardsCollection = Pleb\VCardIO\VCardParser::parseFile('./contacts.vcf');

// OR

$vCardsRawData = 'BEGIN:VCARD
VERSION:4.0
FN:Jeffrey Lebowski
BDAY:19421204
X-MAIN-HOBBY:Bowling
END:VCARD';

$vCardsCollection = Pleb\VCardIO\VCardParser::parseRaw($vCardsRawData);

The vCards collection

The result of parsing is a collection of vCards:

Pleb\VCardIO\VCardsCollection {
    vCards: [
        Pleb\VCardIO\Models\VCardV40 {
            version: "4.0",
            relevantData: {
                version: "4.0",
                fn: "Jeffrey Lebowski",
                bday: DateTimeImmutable @-854466859,
                x: {
                    mainHobby: "Bowling"
                }
            },
            fn: [
                {
                    value: "Jeffrey Lebowski",
                    attributes: []
                }
            ],
            bday: {
                dateTime: DateTimeImmutable @-854466859,
                format: "Ymd",
                formatted: "19421204",
                extactYear: true,
                attributes: []
            },
            x: [
                {
                    name: "main-hobby",
                    formattedName: "mainHobby",
                    value: "Bowling",
                    attributes: []
                }
            ],
            ...
        },
    ],
}

Manually build a vCards collection

$vCardsCollection = (new Pleb\VCardIO\VCardsCollection())
    ->addVCard($vCard1)
    ->addVCard($vCard2);

// OR

$vCardsCollection = new Pleb\VCardIO\VCardsCollection([$vCard1, $vCard2]);

Manipulate collection

The VCardsCollection object implements ArrayAccess, Iterator and Countable interfaces, so you can loop on it.

foreach($vCardsCollection as $vCard){
    // ...
}
// OR
$vCard = $vCardsCollection->first();
// OR
$vCard = $vCardsCollection->getVCard(0); // 1,2,...

The vCard object

A huge set of methods is implemented to read the vCard properties. You can see all available getters methods on the vCard object documentation.

$vCard->getFullName();                      // :?string
$vCard->getLastName();                      // :?string
$vCard->getFirstName();                     // :?string
$vCard->getEmails();                        // :array<string>
$vCard->getPhones();                        // :array<string>
$vCard->getX('main-hobby', multiple:false); // :?string|array
$vCard->getX('main-hobby', multiple:true);  // :array
// ...

Note on "Pseudo-singular" properties

RFC 6350 allows most of properties to be present multiple times in a vCard. For example the FN (fullName) property can be present 1 or multiple times, and accompagnied by attributes to distinct them.

In this package, we assume that some of properties (like fullName) got a unique main value. The vCard's getProperty() methods will return this main value, as well as the sub-object $vCard->relevantData.

The complete set of value is stil available in the root of $vCard object.

Note on the old school AGENT property

The AGENT property is not longer supported by the vCard specification, but if you parse old data, you can see something like this, with nested vCards:

BEGIN:VCARD
VERSION:3.0
FN:Jeffrey Lebowski
AGENT:BEGIN:VCARD
 VERSION:3.0
 FN:Walter Sobchak
 END:VCARD
END:VCARD

This package will parse it as a VCard's agent property:

Pleb\VCardIO\Models\VCardV30 {
    version: '3.0'
    // ...,
    agent: Pleb\VCardIO\Models\VCardV30 {
        version: "3.0"
        // ...
    },
    // ...
}

The vCard builder

You can create your vCard objects from scratch fluently by using the large set of methods implemented on the vCard builder. You can see all available setters methods on the vCard builder documentation.

$vCard = Pleb\VCardIO\VCardBuilder::make()
    ->fullName('Jeffrey Lebowski')
    ->nickName('The Dude')
    ->birthday(new DateTime('1942-12-04'))
    ->x('main-hobby', 'Bowling')
    ->get();

Each method returns the builder instance, so you can chain them.

Use the get() method to get your vCard.

Print vCards

Print a single vCard

You can use (string) $vCard to display vCard contents:

echo nl2br((string) $vCard);

BEGIN:VCARD
VERSION:4.0
FN:Jeffrey Lebowski
NICKNAME:The Dude
BDAY:19421204
X-HOBBY:Bowling
REV:20241029
PRODID:-//Pleb//Pleb vCardIO 1.1.0 //EN
END:VCARD

Print vCards collection

The same is true for vCards collections, what will display the vCards serially:

echo nl2br((string) $vCardsCollection);

BEGIN:VCARD
VERSION:4.0
FN:Jeffrey Lebowski
END:VCARD
BEGIN:VCARD
VERSION:3.0
FN:Walter Sobchak
END:VCARD
...

Export vCards

Export a single vCard

The existing .vcf file will be overwritten.

$vCard->export('./file/export/destination.vcf');

Export vCards collection

The existing .vcf can be overwritten or appended.

// OVERWRITTEN
$vCardCollection->export('./file/export/destination.vcf', append:false); 

// APPENDED
$vCardCollection->export('./file/export/destination.vcf', append:true); 

Contribute

Code formatting

composer format

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.