Class VCardContact - Stefanius67/VCard GitHub Wiki

Full name: \SKien\VCard\VCardContact

Class representing all data to one contact.

Each contact may contains multiple

addresses
communication numbers
e-mail addresses
homepages
categories

Add a contact to a VCard for writing:

Create a new instance of a VCardContact, set all properties and add the contact to a vcard using VCard::addContact()

Retrieve a contact after read VCard file:

Use VCard::getContactList() to retrieve list (array) of all contacts within the vcard. Use VCard::getContact() to retrieve existing contact within vcard.

See Also:

Constants

Constant	Description
`MS_FEMALE`	gender: female (Microsoft specific)
`MS_MALE`	gender: male (Microsoft specific)
`DT_STRING`	Date type: string
`DT_UNIX_TIMESTAMP`	Date type: unix timestamp
`DT_OBJECT`	Date type: DateTime - Object

Overview

Method	Description
addAddress	Add address.
addCategory	Add a category.
addEMail	Add mail address.
addHomepage	Add homepage
addPhone	Add phone number.
getAddress	Get address.
getAddressCount	Number of addresses the contact contains.
getCategories	Return Categories separated by comma.
getCategoriesCount	Number of categories contained.
getCategory	Get category for given index.
getDateOfBirth	Get date of birth.
getEMail	Get EMail addres at given index.
getEMailCount	Number of email addresses contained.
getFirstName	Get firstname.
getGender	Get gender.
getHomepage	Get homepage for given index.
getHomepageCount	Number of homepages contained.
getLastName	Get lastname.
getName	Get full name.
getNickName	Get nickname.
getNote	Get annotation.
getOrganisation	Get name of the organisation.
getPhone	Get phone number.
getPhoneCount	Count of phone numbers.
getPortraitBlob	Get the image as base64 encoded string.
getPosition	Get position, job title or function within the organisation.
getPrefix	Get (honorific) name prefix.
getRole	Get role, occupation or business category within the organisation.
getSection	Get section or organizational unit within the organisation.
getSuffix	Get (honorific) name suffix.
savePortrait	Save portrait as file.
setDateOfBirth	Set date of birth.
setGender	Set the gender.
setHomepage	Set homepage
setName	Set the full name.
setNickName	Set nickname.
setNote	Set annotation.
setOrganisation	Set name of the organisation.
setPortraitBlob	Set portrait from base64 encoded image data.
setPortraitFile	Set portrait from image file.
setPosition	Set position, job title or function within the organisation.
setPrefix	Set (honorific) name prefix.
setRole	Set role, occupation or business category within the organisation.
setSection	Set section or organizational unit within the organisation.
setSuffix	Set (honorific) name suffix.

Methods

addAddress

Add address.

public VCardContact::addAddress(\SKien\VCard\VCardAddress $oAddress, bool $bPreferred) : void

Only one address should be marked as preferred.

Parameters:

Parameter	Type	Description
`oAddress`	\SKien\VCard\VCardAddress
`bPreferred`	bool	mark address as preferred.

[go to top]

addCategory

Add a category.

public VCardContact::addCategory(string $strCategory) : void

Parameters:

Parameter	Type	Description
`strCategory`	string

[go to top]

addEMail

Add mail address.

public VCardContact::addEMail(string $strEMail, bool $bPreferred) : void

Parameters:

Parameter	Type	Description
`strEMail`	string	valid e-mail address
`bPreferred`	bool	mark e-mail as preferred

See Also:

https://datatracker.ietf.org/doc/html/rfc2426#section-3.3.2

[go to top]

addHomepage

Add homepage

public VCardContact::addHomepage(string $strHomepage) : void

Parameters:

Parameter	Type	Description
`strHomepage`	string

[go to top]

addPhone

Add phone number.

public VCardContact::addPhone(string $strPhone, string|string[] $type, bool $bPreferred) : void

Use to set a communication number (phone, mobile, FAX, ...).
Any combination of the predefined communication number constants plus the definition HOME or WORK can be specified as the type.
Multiple numbers of the same type can be set within one contact.

Parameters:

Parameter	Type	Description
`strPhone`	string	the number (SHOULD conform to the semantics of E.164 / X.121)
`type`	string \| string[]	one single type or an array of multiple types
`bPreferred`	bool	mark number as preferred

See Also:

[go to top]

getAddress

Get address.

public VCardContact::getAddress(int|string $i) : \SKien\VCard\VCardAddress|null

An address can be referenced by index or by type.
For Type requests (=> $i non numeric value):

The first address matches specified type is used (contact may contains multiple addresses of same type)
If VCard::PREF is requested, the first preferred address in contact used (even if more than one is defined as preferred), if no preferred address found, the first address within the contact will be returned!

Parameters:

Parameter	Type	Description
`i`	int \| string	reference to address (int => index, string => type)

Return Type: \SKien\VCard\VCardAddress|null

valid address object or null, if not found

[go to top]

getAddressCount

Number of addresses the contact contains.

public VCardContact::getAddressCount() : int

Return Type: int

[go to top]

getCategories

Return Categories separated by comma.

public VCardContact::getCategories() : string

Return Type: string

[go to top]

getCategoriesCount

Number of categories contained.

public VCardContact::getCategoriesCount() : int

Return Type: int

[go to top]

getCategory

Get category for given index.

public VCardContact::getCategory(int $i) : string

Parameters:

Parameter	Type	Description
`i`	int	index (`0 <= $i < self::getCategoriesCount()`)

Return Type: string

[go to top]

getDateOfBirth

Get date of birth.

public VCardContact::getDateOfBirth(int $iType = self::DT_STRING, string $strFormat = 'Y-m-d') : string|int|\DateTime

The return type can be specified in the $iTypeparameter:

self::DT_STRING (default): Date as String in f´the format set with `$strFormat`param (default = 'Y-m-d')
self::DT_UNIX_TIMESTAMP: Date as unix timestamp
self::DT_OBJECT: Date as DateTime object

if the property is not set in the contact method returns:

self::DT_STRING: empty string
self::DT_UNIX_TIMESTAMP: integer 0
self::DT_OBJECT: null

Parameters:

Parameter	Type	Description
`iType`	int	self::DT_STRING (default), self::DT_UNIX_TIMESTAMP or self::DT_OBJECT
`strFormat`	string	Date format compliant to DateTime::format() (default 'Y-m-d')

Return Type: string|int|\DateTime

See Also:

[go to top]

getEMail

Get EMail addres at given index.

public VCardContact::getEMail(int $i) : string

Parameters:

Parameter	Type	Description
`i`	int	index (`0 <= $i < self::getEMailCount()`)

Return Type: string

[go to top]

getEMailCount

Number of email addresses contained.

public VCardContact::getEMailCount() : int

Return Type: int

[go to top]

getFirstName

Get firstname.

public VCardContact::getFirstName() : string

Return Type: string

[go to top]

getGender

Get gender.

public VCardContact::getGender() : string

M: "male" F: "female" O: "other" N: "none or not applicable" U: "unknown"

Return Type: string

[go to top]

getHomepage

Get homepage for given index.

public VCardContact::getHomepage(int $i = -1) : string

Parameters:

Parameter	Type	Description
`i`	int	index (`0 <= $i < self::getHomepageCount()`)

Return Type: string

[go to top]

getHomepageCount

Number of homepages contained.

public VCardContact::getHomepageCount() : int

Return Type: int

[go to top]

getLastName

Get lastname.

public VCardContact::getLastName() : string

Return Type: string

[go to top]

getName

Get full name.

public VCardContact::getName() : string

$strFirstName followed by $strLastName separeted by blank.

Return Type: string

[go to top]

getNickName

Get nickname.

public VCardContact::getNickName() : string

Return Type: string

[go to top]

getNote

Get annotation.

public VCardContact::getNote() : string

Return Type: string

[go to top]

getOrganisation

Get name of the organisation.

public VCardContact::getOrganisation() : string

Return Type: string

[go to top]

getPhone

Get phone number.

public VCardContact::getPhone(int|string $i) : array<string,string>|null

Requested number can be referenced by index or type.
For index request: 0 <= $i < self::getPhoneCount()
For type requests (=> $i non numeric value):

first phone matches specified type is used (contact may contains multiple phone numbers of same type)
if VCard::PREF specified, first number in contact used, if no preferred item found

Parameters:

Parameter	Type	Description
`i`	int \| string	reference to address (int => index, string => type)

Return Type: array<string,string>|null

[go to top]

getPhoneCount

Count of phone numbers.

public VCardContact::getPhoneCount() : int

Return Type: int

[go to top]

getPortraitBlob

Get the image as base64 encoded string.

public VCardContact::getPortraitBlob() : string

Return Type: string

base64 encoded image

[go to top]

getPosition

Get position, job title or function within the organisation.

public VCardContact::getPosition() : string

Return Type: string

[go to top]

getPrefix

Get (honorific) name prefix.

public VCardContact::getPrefix() : string

i.E. 'Dr.', 'Prof.', ...

Return Type: string

[go to top]

getRole

Get role, occupation or business category within the organisation.

public VCardContact::getRole() : string

Return Type: string

[go to top]

getSection

Get section or organizational unit within the organisation.

public VCardContact::getSection() : string

Return Type: string

[go to top]

getSuffix

Get (honorific) name suffix.

public VCardContact::getSuffix() : string

i.E. 'Jr.', 'M.D.', ...

Return Type: string

[go to top]

savePortrait

Save portrait as file.

public VCardContact::savePortrait(string $strFilename) : void

Supportet types are JPG, PNG, GIF and BMP The type depends on the fileextension. If no extensiomnm given, the type of the imported image will be used.

Parameters:

Parameter	Type	Description
`strFilename`	string

[go to top]

setDateOfBirth

Set date of birth.

public VCardContact::setDateOfBirth(string|int|\DateTime $DateOfBirth) : void

Accepts string (format YYYY-MM-DD), int (unixtimestamp) or DateTime - object

Parameters:

Parameter	Type	Description
`DateOfBirth`	string \| int \| \DateTime

[go to top]

setGender

Set the gender.

public VCardContact::setGender(string $strGender) : void

There are different posibilities: X-WAB-GENDER MS-extension '1':Female, '2':Male, '9':Unknown X-GENDER Extension 'Female', 'Male'

GENDER vCard v4.0 A single letter - M: "male" - F: "female" - O: "other" - N: "none or not applicable" - U: "unknown".

So we accept everything of this know variants and convert it to the v4.0 single letter when we build the data.

Parameters:

Parameter	Type	Description
`strGender`	string

[go to top]

setHomepage

Set homepage

public VCardContact::setHomepage(string $strHomepage) : void

Parameters:

Parameter	Type	Description
`strHomepage`	string

[go to top]

setName

Set the full name.

public VCardContact::setName(string $strLastName, string $strFirstName) : void

For companies just leave one of the params blank!

Parameters:

Parameter	Type	Description
`strLastName`	string
`strFirstName`	string

[go to top]

setNickName

Set nickname.

public VCardContact::setNickName(string $strNickName) : void

Parameters:

Parameter	Type	Description
`strNickName`	string

[go to top]

setNote

Set annotation.

public VCardContact::setNote(string $strNote) : void

Parameters:

Parameter	Type	Description
`strNote`	string

[go to top]

setOrganisation

Set name of the organisation.

public VCardContact::setOrganisation(string $strOrganisation) : void

Parameters:

Parameter	Type	Description
`strOrganisation`	string

[go to top]

setPortraitBlob

Set portrait from base64 encoded image data.

public VCardContact::setPortraitBlob(string $blobPortrait) : void

Parameters:

Parameter	Type	Description
`blobPortrait`	string	base64 encoded image

[go to top]

setPortraitFile

Set portrait from image file.

public VCardContact::setPortraitFile(string $strFilename) : void

Supported types are JPG, PNG, GIF and BMP.

Note: For transparency the image type itself MUST support transparency (PNG, GIF) and when reading a portrait, it MUST be saved in the same image format!

Parameters:

Parameter	Type	Description
`strFilename`	string

[go to top]

setPosition

Set position, job title or function within the organisation.

public VCardContact::setPosition(string $strPosition) : void

Parameters:

Parameter	Type	Description
`strPosition`	string

[go to top]

setPrefix

Set (honorific) name prefix.

public VCardContact::setPrefix(string $strPrefix) : void

i.E. 'Dr.', 'Prof.', ...

Parameters:

Parameter	Type	Description
`strPrefix`	string

[go to top]

setRole

Set role, occupation or business category within the organisation.

public VCardContact::setRole(string $strRole) : void

Parameters:

Parameter	Type	Description
`strRole`	string

[go to top]

setSection

Set section or organizational unit within the organisation.

public VCardContact::setSection(string $strSection) : void

Parameters:

Parameter	Type	Description
`strSection`	string

[go to top]

setSuffix

Set (honorific) name suffix.

public VCardContact::setSuffix(string $strSuffix) : void

i.E. 'Jr.', 'M.D.', ...

Parameters:

Parameter	Type	Description
`strSuffix`	string

[go to top]

Class VCardContact - Stefanius67/VCard GitHub Wiki

Class representing all data to one contact.

Add a contact to a VCard for writing:

Retrieve a contact after read VCard file:

Constants

Overview

Methods

addAddress

addCategory

addEMail

addHomepage

addPhone

getAddress

getAddressCount

getCategories

getCategoriesCount

getCategory

getDateOfBirth

getEMail

getEMailCount

getFirstName

getGender

getHomepage

getHomepageCount

getLastName

getName

getNickName

getNote

getOrganisation

getPhone

getPhoneCount

getPortraitBlob

getPosition

getPrefix

getRole

getSection

getSuffix

savePortrait

setDateOfBirth

setGender

setHomepage

setName

setNickName

setNote

setOrganisation

setPortraitBlob

setPortraitFile

setPosition

setPrefix

setRole

setSection

setSuffix

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️