Documentation

VCard extends Document
in package

Application

The VCard component.

This component represents the BEGIN:VCARD and END:VCARD found in every vcard.

DEFAULT_VERSION

VCards with version 2.1, 3.0 and 4.0 are found.


    public
    mixed
    DEFAULT_VERSION
    = self::VCARD21

If the VCARD doesn't know its version, 2.1 is assumed.

ICALENDAR20

iCalendar 2.0.


    public
    mixed
    ICALENDAR20
    = 3

PROFILE_CALDAV

If this option is set, the validator will operate on iCalendar objects on the assumption that the vcards need to be valid for CalDAV.


    public
    mixed
    PROFILE_CALDAV
    = 4

This means for example that calendars can only contain objects with identical component types and UIDs.

PROFILE_CARDDAV

If this option is set, the validator will operate on the vcards on the assumption that the vcards need to be valid for CardDAV.


    public
    mixed
    PROFILE_CARDDAV
    = 2

This means for example that the UID is required, whereas it is not for regular vcards.

REPAIR

The following constants are used by the validate() method.


    public
    mixed
    REPAIR
    = 1

If REPAIR is set, the validator will attempt to repair any broken data (if possible).

UNKNOWN

Unknown document type.


    public
    mixed
    UNKNOWN
    = 1

VCALENDAR10

vCalendar 1.0.


    public
    mixed
    VCALENDAR10
    = 2

VCARD21

vCard 2.1.


    public
    mixed
    VCARD21
    = 4

VCARD30

vCard 3.0.


    public
    mixed
    VCARD30
    = 5

VCARD40

vCard 4.0.


    public
    mixed
    VCARD40
    = 6

$componentMap

This is a list of components, and which classes they should map to.


    public
    static    array<string|int, mixed>
    $componentMap
     = ['VCARD' => SabreVObjectComponentVCard::class]

$defaultName

The default name for this component.


    public
    static    string
    $defaultName
     = 'VCARD'

This should be 'VCALENDAR' or 'VCARD'.

$name

Component name.


    public
        string
    $name

This will contain a string such as VEVENT, VTODO, VCALENDAR, VCARD.

$parent

Reference to the parent object, if this is not the top object.


    public
        Node
    $parent

$propertyMap

List of properties, and which classes they map to.


    public
    static    array<string|int, mixed>
    $propertyMap
     = [
    // vCard 2.1 properties and up
    'N' => SabreVObjectPropertyText::class,
    'FN' => SabreVObjectPropertyFlatText::class,
    'PHOTO' => SabreVObjectPropertyBinary::class,
    'BDAY' => SabreVObjectPropertyVCardDateAndOrTime::class,
    'ADR' => SabreVObjectPropertyText::class,
    'LABEL' => SabreVObjectPropertyFlatText::class,
    // Removed in vCard 4.0
    'TEL' => SabreVObjectPropertyFlatText::class,
    'EMAIL' => SabreVObjectPropertyFlatText::class,
    'MAILER' => SabreVObjectPropertyFlatText::class,
    // Removed in vCard 4.0
    'GEO' => SabreVObjectPropertyFlatText::class,
    'TITLE' => SabreVObjectPropertyFlatText::class,
    'ROLE' => SabreVObjectPropertyFlatText::class,
    'LOGO' => SabreVObjectPropertyBinary::class,
    // 'AGENT'   => 'Sabre\VObject\Property\',      // Todo: is an embedded vCard. Probably rare, so
    // not supported at the moment
    'ORG' => SabreVObjectPropertyText::class,
    'NOTE' => SabreVObjectPropertyFlatText::class,
    'REV' => SabreVObjectPropertyVCardTimeStamp::class,
    'SOUND' => SabreVObjectPropertyFlatText::class,
    'URL' => SabreVObjectPropertyUri::class,
    'UID' => SabreVObjectPropertyFlatText::class,
    'VERSION' => SabreVObjectPropertyFlatText::class,
    'KEY' => SabreVObjectPropertyFlatText::class,
    'TZ' => SabreVObjectPropertyText::class,
    // vCard 3.0 properties
    'CATEGORIES' => SabreVObjectPropertyText::class,
    'SORT-STRING' => SabreVObjectPropertyFlatText::class,
    'PRODID' => SabreVObjectPropertyFlatText::class,
    'NICKNAME' => SabreVObjectPropertyText::class,
    'CLASS' => SabreVObjectPropertyFlatText::class,
    // Removed in vCard 4.0
    // rfc2739 properties
    'FBURL' => SabreVObjectPropertyUri::class,
    'CAPURI' => SabreVObjectPropertyUri::class,
    'CALURI' => SabreVObjectPropertyUri::class,
    'CALADRURI' => SabreVObjectPropertyUri::class,
    // rfc4770 properties
    'IMPP' => SabreVObjectPropertyUri::class,
    // vCard 4.0 properties
    'SOURCE' => SabreVObjectPropertyUri::class,
    'XML' => SabreVObjectPropertyFlatText::class,
    'ANNIVERSARY' => SabreVObjectPropertyVCardDateAndOrTime::class,
    'CLIENTPIDMAP' => SabreVObjectPropertyText::class,
    'LANG' => SabreVObjectPropertyVCardLanguageTag::class,
    'GENDER' => SabreVObjectPropertyText::class,
    'KIND' => SabreVObjectPropertyFlatText::class,
    'MEMBER' => SabreVObjectPropertyUri::class,
    'RELATED' => SabreVObjectPropertyUri::class,
    // rfc6474 properties
    'BIRTHPLACE' => SabreVObjectPropertyFlatText::class,
    'DEATHPLACE' => SabreVObjectPropertyFlatText::class,
    'DEATHDATE' => SabreVObjectPropertyVCardDateAndOrTime::class,
    // rfc6715 properties
    'EXPERTISE' => SabreVObjectPropertyFlatText::class,
    'HOBBY' => SabreVObjectPropertyFlatText::class,
    'INTEREST' => SabreVObjectPropertyFlatText::class,
    'ORG-DIRECTORY' => SabreVObjectPropertyFlatText::class,
]

$valueMap

List of value-types, and which classes they map to.


    public
    static    array<string|int, mixed>
    $valueMap
     = [
    'BINARY' => SabreVObjectPropertyBinary::class,
    'BOOLEAN' => SabreVObjectPropertyBoolean::class,
    'CONTENT-ID' => SabreVObjectPropertyFlatText::class,
    // vCard 2.1 only
    'DATE' => SabreVObjectPropertyVCardDate::class,
    'DATE-TIME' => SabreVObjectPropertyVCardDateTime::class,
    'DATE-AND-OR-TIME' => SabreVObjectPropertyVCardDateAndOrTime::class,
    // vCard only
    'FLOAT' => SabreVObjectPropertyFloatValue::class,
    'INTEGER' => SabreVObjectPropertyIntegerValue::class,
    'LANGUAGE-TAG' => SabreVObjectPropertyVCardLanguageTag::class,
    'PHONE-NUMBER' => SabreVObjectPropertyVCardPhoneNumber::class,
    // vCard 3.0 only
    'TIMESTAMP' => SabreVObjectPropertyVCardTimeStamp::class,
    'TEXT' => SabreVObjectPropertyText::class,
    'TIME' => SabreVObjectPropertyTime::class,
    'UNKNOWN' => SabreVObjectPropertyUnknown::class,
    // jCard / jCal-only.
    'URI' => SabreVObjectPropertyUri::class,
    'URL' => SabreVObjectPropertyUri::class,
    // vCard 2.1 only
    'UTC-OFFSET' => SabreVObjectPropertyUtcOffset::class,
]

$children

A list of properties and/or sub-components.


    protected
        array<string|int, mixed>
    $children
     = []

$iterator

Iterator override.


    protected
        ElementList
    $iterator
     = null

$root

The root document.


    protected
        Component
    $root

$version

Caching the version number.


    private
        int
    $version
     = null

__clone()

This method is automatically called when the object is cloned.


    public
                __clone() : mixed

Specifically, this will ensure all child elements are also cloned.

Return values

mixed —

__construct()

Creates a new component.


    public
                __construct(Document $root, string $name[, array<string|int, mixed> $children = [] ][, bool $defaults = true ]) : mixed

You can specify the children either in key=>value syntax, in which case properties will automatically be created, or you can just pass a list of Component and Property object.

By default, a set of sensible values will be added to the component. For an iCalendar object, this may be something like CALSCALE:GREGORIAN. To ensure that this does not happen, set $defaults to false.

Parameters

$root : Document
$name : string: such as VCALENDAR, VEVENT
$children : array<string|int, mixed> = []
$defaults : bool = true

Return values

mixed —

__get()

Using 'get' you will either get a property or component.


    public
                __get(string $name) : Property

If there were no child-elements found with the specified name, null is returned.

To use this, this may look something like this:

$event = $calendar->VEVENT;

Parameters

$name : string

Return values

Property —

__isset()

This method checks if a sub-element with the specified name exists.


    public
                __isset(string $name) : bool

Parameters

$name : string

Return values

bool —

__set()

Using the setter method you can add properties or subcomponents.


    public
                __set(string $name, mixed $value) : mixed

You can either pass a Component, Property object, or a string to automatically create a Property.

If the item already exists, it will be removed. If you want to add a new item with the same name, always use the add() method.

Parameters

$name : string
$value : mixed

Return values

mixed —

__unset()

Removes all properties and components within this component with the specified name.


    public
                __unset(string $name) : mixed

Parameters

$name : string

Return values

mixed —

add()

Adds a new property or component, and returns the new item.


    public
                add() : Node

This method has 3 possible signatures:

add(Component $comp) // Adds a new component add(Property $prop) // Adds a new property add($name, $value, array $parameters = []) // Adds a new property add($name, array $children = []) // Adds a new component by name.

Return values

Node —

children()

Returns a flat list of all the properties and components in this component.


    public
                children() : array<string|int, mixed>

Return values

array<string|int, mixed> —

convert()

Converts the document to a different vcard version.


    public
                convert(int $target) : VCard

Use one of the VCARD constants for the target. This method will return a copy of the vcard in the new version.

At the moment the only supported conversion is from 3.0 to 4.0.

If input and output version are identical, a clone is returned.

Parameters

$target : int

Return values

VCard —

count()

Returns the number of elements.


    public
                count() : int

Return values

int —

create()

Creates a new component or property.


    public
                create(string $name) : mixed

If it's a known component, we will automatically call createComponent. otherwise, we'll assume it's a property and call createProperty instead.

Parameters

$name : string

Return values

mixed —

createComponent()

Creates a new component.


    public
                createComponent(string $name[, array<string|int, mixed> $children = null ][, bool $defaults = true ]) : Component

This method automatically searches for the correct component class, based on its name.

You can specify the children either in key=>value syntax, in which case properties will automatically be created, or you can just pass a list of Component and Property object.

Parameters

$name : string
$children : array<string|int, mixed> = null
$defaults : bool = true

Return values

Component —

createProperty()

Factory method for creating new properties.


    public
                createProperty(string $name[, mixed $value = null ][, array<string|int, mixed> $parameters = null ][, string $valueType = null ]) : Property

This method automatically searches for the correct property class, based on its name.

You can specify the parameters either in key=>value syntax, in which case parameters will automatically be created, or you can just pass a list of Parameter objects.

Parameters

$name : string
$value : mixed = null
$parameters : array<string|int, mixed> = null
$valueType : string = null: Force a specific valuetype, such as URI or TEXT

Return values

Property —

destroy()

Call this method on a document if you're done using it.


    public
                destroy() : mixed

It's intended to remove all circular references, so PHP can easily clean it up.

Return values

mixed —

getByType()

Returns a property with a specific TYPE value (ADR, TEL, or EMAIL).


    public
                getByType(string $propertyName, string $type) : Property|null

This function will return null if the property does not exist. If there are multiple properties with the same TYPE value, only one will be returned.

Parameters

$propertyName : string
$type : string

Return values

Property|null —

getClassNameForPropertyName()

Returns the default class for a property name.


    public
                getClassNameForPropertyName(string $propertyName) : string

Parameters

$propertyName : string

Return values

string —

getClassNameForPropertyValue()

This method returns a full class-name for a value parameter.


    public
                getClassNameForPropertyValue(string $valueParam) : string|null

For instance, DTSTART may have VALUE=DATE. In that case we will look in our valueMap table and return the appropriate class name.

This method returns null if we don't have a specialized class.

Parameters

$valueParam : string

Return values

string|null —

getComponents()

This method only returns a list of sub-components. Properties are ignored.


    public
                getComponents() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getDocumentType()

Returns the current document type.


    public
                getDocumentType() : int

Return values

int —

getIterator()

Returns the iterator for this object.


    public
                getIterator() : ElementList

Return values

ElementList —

getValidationRules()

A simple list of validation rules.


    public
                getValidationRules() : mixed

This is simply a list of properties, and how many times they either must or must not appear.

Possible values per property:

0 - Must not appear.
1 - Must appear exactly once.
- - Must appear at least once.
- - Can appear any number of times.
? - May appear, but not more than once.

Return values

mixed —

jsonSerialize()

This method returns an array, with the representation as it should be encoded in json. This is used to create jCard or jCal documents.


    public
                jsonSerialize() : array<string|int, mixed>

Return values

array<string|int, mixed> —

offsetExists()

Checks if an item exists through ArrayAccess.


    public
                offsetExists(int $offset) : bool

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

bool —

offsetGet()

Gets an item through ArrayAccess.


    public
                offsetGet(int $offset) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

mixed —

offsetSet()

Sets an item through ArrayAccess.


    public
                offsetSet(int $offset, mixed $value) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int
$value : mixed

Return values

mixed —

offsetUnset()

Sets an item through ArrayAccess.


    public
                offsetUnset(int $offset) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

mixed —

preferred()

Returns a preferred field.


    public
                preferred(mixed $propertyName) : Property|null

VCards can indicate wether a field such as ADR, TEL or EMAIL is preferred by specifying TYPE=PREF (vcard 2.1, 3) or PREF=x (vcard 4, x being a number between 1 and 100).

If neither of those parameters are specified, the first is returned, if a field with that name does not exist, null is returned.

Parameters

$propertyName : mixed

Return values

Property|null —

remove()

This method removes a component or property from this component.


    public
                remove(string|Property|Component $item) : mixed

You can either specify the item by name (like DTSTART), in which case all properties/components with that name will be removed, or you can pass an instance of a property or component, in which case only that exact item will be removed.

Parameters

$item : string|Property|Component

Return values

mixed —

select()

Returns an array with elements that match the specified name.


    public
                select(string $name) : array<string|int, mixed>

This function is also aware of MIME-Directory groups (as they appear in vcards). This means that if a property is grouped as "HOME.EMAIL", it will also be returned when searching for just "EMAIL". If you want to search for a property in a specific group, you can select on the entire string ("HOME.EMAIL"). If you want to search on a specific property that has not been assigned a group, specify ".EMAIL".

Parameters

$name : string

Return values

array<string|int, mixed> —

serialize()

Serializes the node into a mimedir format.


    public
    abstract            serialize() : string

Return values

string —

setIterator()

Sets the overridden iterator.


    public
                setIterator(ElementList $iterator) : mixed

Note that this is not actually part of the iterator interface

Parameters

$iterator : ElementList

Return values

mixed —

validate()

Validates the node for correctness.


    public
                validate(int $options) : array<string|int, mixed>

The following options are supported: Node::REPAIR - May attempt to automatically repair the problem.

This method returns an array with detected problems. Every element has the following properties:

level - problem level.
message - A human-readable string describing the issue.
node - A reference to the problematic node.

The level means: 1 - The issue was repaired (only happens if REPAIR was turned on) 2 - An inconsequential issue 3 - A severe issue.

Parameters

$options : int

Return values

array<string|int, mixed> —

xmlSerialize()

This method serializes the data into XML. This is used to create xCard or xCal documents.


    public
                xmlSerialize(Writer $writer) : mixed

Parameters

$writer : Writer: XML writer

Return values

mixed —

getDefaults()

This method should return a list of default property values.


    protected
                getDefaults() : array<string|int, mixed>

Return values

array<string|int, mixed> —