Download the PHP package rondeto/jscontact without Composer

On this page you can find all versions of the php package rondeto/jscontact. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package jscontact

rondeto/jscontact

A PHP library for JSContact, the JSON format for contact data, and for converting between vCard and JSContact.

Status: early development (0.x). The public API may change in any release until 1.0.

Why JSContact?

vCard (.vcf files) is how address books have exchanged contacts for decades. It is a line-based text format that has grown through three versions, and every address book reads and writes it a little differently.

JSContact is its successor, standardized by the IETF in 2024: the same contact data as plain JSON, with a precise model and an official mapping from and to vCard. JMAP, the JSON-based protocol meant to replace IMAP and CardDAV, uses it for contacts.

This library gives you:

It is useful to import contacts from anywhere into a clean model, to expose contacts as JSON, or to export them as vCards for a given address book.

Installation

Quick start

@type and version are always written for you. TYPE=INTERNET has no JSContact equivalent, so it is kept in vCardParams and comes back when the Card is written to vCard again.

Usage

The model

A contact is a Rondeto\JSContact\Model\Card, a plain object whose properties follow the JSContact specification: name, emails, phones, addresses, organizations, relatedTo, and so on. Every class lives in src/Model.

A few things differ from vCard, and may surprise you at first:

JSON

vCard

Editing a Card

Model objects are plain PHP objects: change their properties directly.

Choose the key of a new entry ('work' above): $card->phones[] = … would give it the key 0. Keys identify an entry across versions of a Card, see Identifiers.

Changes are not checked when they are made: the encoders validate the Card when they write it, or call CardValidator yourself.

Copying a Card

clone $card copies the Card, not the objects inside it: changing $copy->name->full also changes the original. To get an independent copy, use myclabs/deep-copy:

Issues and strict mode

Contact data found in the wild is often slightly broken. Every decoder and encoder returns a Result: the converted value, and the issues met on the way. Each Issue has a path, a JSON Pointer into the Card, and a message.

By default, reading is lenient and writing is strict:

Default Other mode
JsonDecoder Skips or corrects invalid values, and reports them strict: true throws an InvalidCardException on any issue
VCardDecoder Keeps what it cannot convert in vCardProps, and reports it strict: true throws an InvalidCardException on any issue
JsonEncoder Throws an InvalidCardException for an invalid Card validate: false writes it anyway
VCardEncoder Throws an InvalidCardException for an invalid Card; reports what vCard, or the version asked for, cannot hold validate: false writes it anyway

The validation rules are Symfony Validator constraints on the model classes: a Symfony application can validate a Card with its own validator, like any other object.

Address book dialects

Address books also write properties of their own that no specification defines. Apple's Address Book, for example, writes a spouse as X-ABRELATEDNAMES with the label _$!<Spouse>!$_, where vCard 4.0 has RELATED;TYPE=spouse. By default, such properties are kept verbatim in vCardProps, but not understood.

A Dialect teaches the converter one family of these properties: it rewrites them as the standard properties they mean before reading, and back after writing. Dialects are opt-in.

To read, pass the dialects to the decoder. The address book a vCard comes from is seldom known, and each dialect reads only its own properties: Dialects::all() reads them all.

To write, the address book the vCard is for is known: pass a Target to encode(), the vCard version and the dialects that address book reads. Target::apple() and Target::android() are ready-made.

Dialect For
Apple Apple's Address Book, whose properties other address books, such as Google Contacts, also export: related names, dates, addresses, social profiles, groups, built-in labels, dates without a year
Android The Android contacts app: relations, anniversaries and nicknames in X-ANDROID-CUSTOM, dates without a year in vCard 3.0
LegacyMessaging Instant messaging properties from before vCard had IMPP: X-AIM, X-ICQ, X-JABBER, X-SKYPE…
Target Writes
Target::apple() vCard 3.0 with LegacyMessaging and Apple, for Apple Contacts and iCloud, and Google Contacts
Target::android() vCard 3.0 with LegacyMessaging and Android: Android exports vCard 2.1, which the encoder does not write

For any other combination, build one: new Target(VCardVersion::V30, [new LegacyMessaging()]). Dialects write in the order given, each rewriting what the previous ones left: LegacyMessaging comes before Apple, or Apple's X-SOCIALPROFILE would take the AIM user names that address books expect as X-AIM.

Localizations

A Card can carry versions of itself in other languages, for example a name in Japanese script and its Latin transcription. JSContact stores them in localizations, as patches to apply to the Card, one per language. In vCard, they are the versions of a property that share an ALTID with another LANGUAGE; the converter maps one to the other.

A localization vCard cannot hold, such as a translated label, is written as a JSPROP property, which vCard 4.0 defines to carry JSContact data, and reported as an issue.

How it works

Specifications

RFC What it defines In this library
RFC 9553 JSContact: the JSON model Model, Json, Localization
RFC 9554 New vCard properties and parameters, to match JSContact VCard
RFC 9555 Conversion between vCard and JSContact VCard
RFC 9982 JSContact 2.0: updates to the three above Everywhere: the model is version 2.0

vCard text is parsed and serialized with sabre/vobject.

Principles

Identifiers

Converting the same vCard twice gives the same keys: the vCard PROP-ID parameter when there is one, otherwise a key named after the vCard property and its position (EMAIL-1, PHONE-2…), as in the RFC 9555 examples. Writing a Card to vCard sets PROP-ID on every property, so keys survive a round trip. Labels are written as X-ABLabel, as RFC 9555 specifies.

Out of scope

Contributing

See CONTRIBUTING.md.

License

MIT

Acknowledgements

The test suite reuses examples from other works. Their origin, license and any changes are detailed in tests/Fixtures/SOURCES.md.


All versions of jscontact with dependencies

PHP Build Version
Package Version
Requires php Version >=8.4
sabre/vobject Version ^4.5.6 || ^5.0
symfony/validator Version ^7.4 || ^8.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package rondeto/jscontact contains the following files

Loading the files please wait ...