PHPackages                             pleb/vcardio - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. pleb/vcardio

ActiveLibrary[Parsing & Serialization](/categories/parsing)

pleb/vcardio
============

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

1.1.6(1mo ago)026[1 PRs](https://github.com/PierreLebedel/vCardIO/pulls)MITPHPPHP ^8.2CI passing

Since Oct 29Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/PierreLebedel/vCardIO)[ Packagist](https://packagist.org/packages/pleb/vcardio)[ Docs](https://github.com/PierreLebedel/vCardIO)[ GitHub Sponsors](https://github.com/PierreLebedel)[ RSS](/packages/pleb-vcardio/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (8)Versions (13)Used By (0)

vCardIO - Parse, read, manipulate & write vCard (.vcf files)
================================================================

[](#vcardio---parse-read-manipulate--write-vcard-vcf-files)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4f4a9f62d7fd1e0657f8fb83cda05422a1ae7f6f7fd27e02a8c16a771e90e960/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706c65622f7663617264696f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pleb/vcardio)[![Tests](https://camo.githubusercontent.com/2433eb9a55fd031ef2901fd3af6e4cebe38d1499a8000f40bf00fd3122f04240/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f5069657272654c65626564656c2f7643617264494f2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/PierreLebedel/vCardIO/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/eda939e3c2eb2937285ceca9613dfe4300db56d03b305291ad34a7aedf084218/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706c65622f7663617264696f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pleb/vcardio)

This package based on [RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) 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
------------

[](#installation)

Via composer:

```
composer require pleb/vcardio
```

Documentation
-------------

[](#documentation)

- [Parsing data](docs/parsing.md)
- [vCards collection](docs/collection.md)
- [vCard builder](docs/builder.md)
- [vCard object](docs/vcard.md)
- [Exporting files](docs/export.md)

Usage
-----

[](#usage)

### Parsing data

[](#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-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

[](#manually-build-a-vcards-collection)

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

// OR

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

#### Manipulate collection

[](#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

[](#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](docs/vcard.md).

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

#### Note on "Pseudo-singular" properties

[](#note-on-pseudo-singular-properties)

[RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) 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

[](#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

[](#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](docs/builder.md).

```
$vCard = Pleb\VCardIO\VCardBuilder::make()
    ->fullName('Jeffrey Lebowski')
    ->nickName('The Dude')
    ->birthday(new DateTime('1942-12-04'))
    ->when(true, function($b){
        $b->x('main-hobby', 'Bowling');
    }, function($b){
        $b->x('main-hobby', 'White Russians');
    })
    ->get();
```

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

Use the `get()` method to get your vCard.

### Print vCards

[](#print-vcards)

#### Print a single vCard

[](#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

[](#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-vcards)

#### Export a single vCard

[](#export-a-single-vcard)

The existing .vcf file will be overwritten.

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

#### Export vCards collection

[](#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
----------

[](#contribute)

### Code formatting

[](#code-formatting)

```
composer format
```

### Testing

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance90

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 86% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~74 days

Recently: every ~2 days

Total

8

Last Release

46d ago

PHP version history (2 changes)1.0.0PHP ^8.1

v1.1.2PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/aa27681230c162b0a083869f11f78692d65c04b19c9a8cbe439ddc201869e949?d=identicon)[PierreLebedel](/maintainers/PierreLebedel)

---

Top Contributors

[![PierreLebedel](https://avatars.githubusercontent.com/u/3717168?v=4)](https://github.com/PierreLebedel "PierreLebedel (86 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (9 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")

---

Tags

vcardvcard-generatorvcard-parservcfvcf-filesvCardvcf

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/pleb-vcardio/health.svg)

```
[![Health](https://phpackages.com/badges/pleb-vcardio/health.svg)](https://phpackages.com/packages/pleb-vcardio)
```

###  Alternatives

[sabre/vobject

The VObject library for PHP allows you to easily parse and manipulate iCalendar and vCard objects

59723.5M41](/packages/sabre-vobject)[jeroendesloovere/vcard

This VCard PHP class can generate a vCard with some data. When using an iOS device it will export as a .ics file because iOS devices don't support the default .vcf files.

5193.6M12](/packages/jeroendesloovere-vcard)[protonlabs/vobject

The VObject library for PHP allows you to easily parse and manipulate iCalendar and vCard objects

1152.5k](/packages/protonlabs-vobject)[astrotomic/laravel-vcard

A fluent builder class for vCard files.

5330.0k](/packages/astrotomic-laravel-vcard)[jeroendesloovere/vcard-bundle

This Symfony 2 bundle can generate vCards with lots of data. When using an < iOS 7 device it will export as a .ics file because iOS devices don't support the default .vcf files.

1677.3k3](/packages/jeroendesloovere-vcard-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)