[WIP] VCard library

This VCard PHP class can generate a vCard version 4.0. .vcf file with one or more vCards in it. Parsing is also possible. OOP is our goal-focus, so every property has its own class.

Documentation about vCard 4.0:

• vCard 4.0 specification: RFC6350
• vCard 4.0 versus vCard 3.0

Installation

composer require jeroendesloovere/vcard:dev-2.0.0-dev

This will install the 2.0 WIP development version of vcard with Composer

Examples

Since this is a WIP, we refer to the test class to view multiple examples.

Basic example

use JeroenDesloovere\VCard\VCard;
use JeroenDesloovere\VCard\Property\Name;
use JeroenDesloovere\VCard\Formatter\Formatter;
use JeroenDesloovere\VCard\Formatter\VcfFormatter;

$lastname = "Berg";
$firstname = "Melroy";
$additional = "van den";
$prefix = "Mr.";
$suffix = "";

$vcard = new VCard();
$vcard->add(new Name($lastname, $firstname, $additional, $prefix, $suffix));

$formatter = new Formatter(new VcfFormatter(), 'vcard-export');
$formatter->addVCard($vcard);
$formatter->download();

Properties

Identification Properties:

• FN = Full name - The full name of the object (as a single string). This is the only mandatory property.
• N = Name - The name of the object represented in structured parts
• NICKNAME - A nickname for the object
• PHOTO
• BDAY - Birth date of the object. Should only apply to Individual
• ANNIVERSARY - Should only apply to Individual
• GENDER - Should only apply to Individual

Delivery Addressing Properties:

• ADDRESS - The address of the object represented in structured parts

Communications Properties:

• TEL - The telephone number(s) as a tel URI
• EMAIL - The email address(es) as a mailto URI
• IMPP - The IMPP instant messaging contact information
• LANG - The language of the object

Geographical Properties:

• TZ - The timezone of the object
• GEO - The geographical coordinates of the object (geo URI)

Organizational Properties:

• TITLE - The title of the object
• ROLE - The role of the object
• LOGO - The logo of the object (data URI)
• ORG - The organisation related to the object
• ORGUNIT - The organisational unit related to the object
• MEMBER - Can only be used for Group Kind objects. Must point to other Individual or Organization objects.
• RELATED - Link to related objects.

Explanatory Properties:

• CATEGORIES - The categories of the object
• NOTE - Notes about the object
• PRODID - The identifier of the product that created the vCard object
• REV - The revision datetime of the vCard object
• SOUND - Audio related to the object (data URI)
• UID - A unique identifier for the object
• CLIENTPIDMAP - Not required
• URL - Any URL related to the object
• VERSION - Is mandatory for 4.0

Security Properties:

• KEY - The security key of the object

Calendar Properties:

• FBURL - Calendar Busy Time of the object
• CALADURI - Calendar Request of the object
• CALURI - Calendar Link of the object

Documentation

The class is well documented inline. If you use a decent IDE you'll see that each method is documented with PHPDoc.

Contributing

Contributions are welcome and will be fully credited.

Pull Requests

To add or update code

• Coding Syntax - Please keep the code syntax consistent with the rest of the package.
• Add unit tests! - Your patch won't be accepted if it doesn't have tests.
• Document any change in behavior - Make sure the README and any other relevant documentation are kept up-to-date.
• Consider our release cycle - We try to follow semver. Randomly breaking public APIs is not an option.
• Create topic branches - Don't ask us to pull from your master branch.
• One pull request per feature - If you want to do more than one thing, send multiple pull requests.
• Send coherent history - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.

Issues

For bug reporting or code discussions.

More info on how to work with GitHub on help.github.com.

Coding Syntax

We use squizlabs/php_codesniffer to maintain the code standards. Type the following to execute them:

# To view the code errors
vendor/bin/phpcs --standard=psr2 --extensions=php --warning-severity=0 --report=full "src"

# OR to fix the code errors
vendor/bin/phpcbf --standard=psr2 --extensions=php --warning-severity=0 --report=full "src"

Read documentation about the code standards

Unit Tests

We have build in tests, type the following to execute them:

vendor/bin/phpunit tests

Credits

• Jeroen Desloovere
• All Contributors

License

The module is licensed under MIT. In short, this license allows you to do everything as long as the copyright statement stays present.