contactimporter/php/vcf/class.vCard.php

690 lines
18 KiB
PHP
Raw Normal View History

<?php
/**
* vCard class for parsing a vCard and/or creating one
*
* @link https://github.com/nuovo/vCard-parser
* @author Martins Pilsetnieks, Roberts Bruveris
* @see RFC 2426, RFC 2425
* @version 0.4.8
*/
class vCard implements Countable, Iterator
{
const MODE_ERROR = 'error';
const MODE_SINGLE = 'single';
const MODE_MULTIPLE = 'multiple';
const endl = "\n";
/**
* @var string Current object mode - error, single or multiple (for a single vCard within a file and multiple combined vCards)
*/
private $Mode; //single, multiple, error
private $Path = '';
private $RawData = '';
/**
* @var array Internal options container. Options:
* bool Collapse: If true, elements that can have multiple values but have only a single value are returned as that value instead of an array
* If false, an array is returned even if it has only one value.
*/
private $Options = array(
'Collapse' => false
);
/**
* @var array Internal data container. Contains vCard objects for multiple vCards and just the data for single vCards.
*/
private $Data = array();
/**
* @static Parts of structured elements according to the spec.
*/
private static $Spec_StructuredElements = array(
'n' => array('LastName', 'FirstName', 'AdditionalNames', 'Prefixes', 'Suffixes'),
'adr' => array('POBox', 'ExtendedAddress', 'StreetAddress', 'Locality', 'Region', 'PostalCode', 'Country'),
'geo' => array('Latitude', 'Longitude'),
'org' => array('Name', 'Unit1', 'Unit2')
);
private static $Spec_MultipleValueElements = array('nickname', 'categories');
private static $Spec_ElementTypes = array(
'email' => array('internet', 'x400', 'pref'),
'adr' => array('dom', 'intl', 'postal', 'parcel', 'home', 'work', 'pref'),
'label' => array('dom', 'intl', 'postal', 'parcel', 'home', 'work', 'pref'),
'tel' => array('home', 'msg', 'work', 'pref', 'voice', 'fax', 'cell', 'video', 'pager', 'bbs', 'modem', 'car', 'isdn', 'pcs'),
'impp' => array('personal', 'business', 'home', 'work', 'mobile', 'pref')
);
private static $Spec_FileElements = array('photo', 'logo', 'sound');
/**
* vCard constructor
*
* @param string Path to file, optional.
* @param string Raw data, optional.
* @param array Additional options, optional. Currently supported options:
* bool Collapse: If true, elements that can have multiple values but have only a single value are returned as that value instead of an array
* If false, an array is returned even if it has only one value.
*
* One of these parameters must be provided, otherwise an exception is thrown.
*/
public function __construct($Path = false, $RawData = false, array $Options = null)
{
// Checking preconditions for the parser.
// If path is given, the file should be accessible.
// If raw data is given, it is taken as it is.
// In both cases the real content is put in $this -> RawData
if ($Path)
{
if (!is_readable($Path))
{
throw new Exception('vCard: Path not accessible ('.$Path.')');
}
$this -> Path = $Path;
$this -> RawData = file_get_contents($this -> Path);
}
elseif ($RawData)
{
$this -> RawData = $RawData;
}
else
{
//throw new Exception('vCard: No content provided');
// Not necessary anymore as possibility to create vCards is added
}
if (!$this -> Path && !$this -> RawData)
{
return true;
}
if ($Options)
{
$this -> Options = array_merge($this -> Options, $Options);
}
// Counting the begin/end separators. If there aren't any or the count doesn't match, there is a problem with the file.
// If there is only one, this is a single vCard, if more, multiple vCards are combined.
$Matches = array();
$vCardBeginCount = preg_match_all('{^BEGIN\:VCARD}miS', $this -> RawData, $Matches);
$vCardEndCount = preg_match_all('{^END\:VCARD}miS', $this -> RawData, $Matches);
if (($vCardBeginCount != $vCardEndCount) || !$vCardBeginCount)
{
$this -> Mode = vCard::MODE_ERROR;
throw new Exception('vCard: invalid vCard');
}
$this -> Mode = $vCardBeginCount == 1 ? vCard::MODE_SINGLE : vCard::MODE_MULTIPLE;
// Removing/changing inappropriate newlines, i.e., all CRs or multiple newlines are changed to a single newline
$this -> RawData = str_replace("\r", "\n", $this -> RawData);
$this -> RawData = preg_replace('{(\n+)}', "\n", $this -> RawData);
// In multiple card mode the raw text is split at card beginning markers and each
// fragment is parsed in a separate vCard object.
if ($this -> Mode == self::MODE_MULTIPLE)
{
$this -> RawData = explode('BEGIN:VCARD', $this -> RawData);
$this -> RawData = array_filter($this -> RawData);
foreach ($this -> RawData as $SinglevCardRawData)
{
// Prepending "BEGIN:VCARD" to the raw string because we exploded on that one.
// If there won't be the BEGIN marker in the new object, it will fail.
$SinglevCardRawData = 'BEGIN:VCARD'."\n".$SinglevCardRawData;
$ClassName = get_class($this);
$this -> Data[] = new $ClassName(false, $SinglevCardRawData);
}
}
else
{
// Protect the BASE64 final = sign (detected by the line beginning with whitespace), otherwise the next replace will get rid of it
$this -> RawData = preg_replace('{(\n\s.+)=(\n)}', '$1-base64=-$2', $this -> RawData);
// Joining multiple lines that are split with a hard wrap and indicated by an equals sign at the end of line
// (quoted-printable-encoded values in v2.1 vCards)
$this -> RawData = str_replace("=\n", '', $this -> RawData);
// Joining multiple lines that are split with a soft wrap (space or tab on the beginning of the next line
$this -> RawData = str_replace(array("\n ", "\n\t"), '-wrap-', $this -> RawData);
// Restoring the BASE64 final equals sign (see a few lines above)
$this -> RawData = str_replace("-base64=-\n", "=\n", $this -> RawData);
$Lines = explode("\n", $this -> RawData);
foreach ($Lines as $Line)
{
// Lines without colons are skipped because, most likely, they contain no data.
if (strpos($Line, ':') === false)
{
continue;
}
// Each line is split into two parts. The key contains the element name and additional parameters, if present,
// value is just the value
list($Key, $Value) = explode(':', $Line, 2);
// Key is transformed to lowercase because, even though the element and parameter names are written in uppercase,
// it is quite possible that they will be in lower- or mixed case.
// The key is trimmed to allow for non-significant WSP characters as allowed by v2.1
$Key = strtolower(trim(self::Unescape($Key)));
// These two lines can be skipped as they aren't necessary at all.
if ($Key == 'begin' || $Key == 'end')
{
continue;
}
if ((strpos($Key, 'agent') === 0) && (stripos($Value, 'begin:vcard') !== false))
{
$ClassName = get_class($this);
$Value = new $ClassName(false, str_replace('-wrap-', "\n", $Value));
if (!isset($this -> Data[$Key]))
{
$this -> Data[$Key] = array();
}
$this -> Data[$Key][] = $Value;
continue;
}
else
{
$Value = str_replace('-wrap-', '', $Value);
}
$Value = trim(self::Unescape($Value));
$Type = array();
// Here additional parameters are parsed
$KeyParts = explode(';', $Key);
$Key = $KeyParts[0];
$Encoding = false;
if (strpos($Key, 'item') === 0)
{
$TmpKey = explode('.', $Key, 2);
$Key = $TmpKey[1];
$ItemIndex = (int)str_ireplace('item', '', $TmpKey[0]);
}
if (count($KeyParts) > 1)
{
$Parameters = self::ParseParameters($Key, array_slice($KeyParts, 1));
foreach ($Parameters as $ParamKey => $ParamValue)
{
switch ($ParamKey)
{
case 'encoding':
$Encoding = $ParamValue;
if (in_array($ParamValue, array('b', 'base64')))
{
//$Value = base64_decode($Value);
}
elseif ($ParamValue == 'quoted-printable') // v2.1
{
$Value = quoted_printable_decode($Value);
}
break;
case 'charset': // v2.1
if ($ParamValue != 'utf-8' && $ParamValue != 'utf8')
{
$Value = mb_convert_encoding($Value, 'UTF-8', $ParamValue);
}
break;
case 'type':
$Type = $ParamValue;
break;
}
}
}
// Checking files for colon-separated additional parameters (Apple's Address Book does this), for example, "X-ABCROP-RECTANGLE" for photos
if (in_array($Key, self::$Spec_FileElements) && isset($Parameters['encoding']) && in_array($Parameters['encoding'], array('b', 'base64')))
{
// If colon is present in the value, it must contain Address Book parameters
// (colon is an invalid character for base64 so it shouldn't appear in valid files)
if (strpos($Value, ':') !== false)
{
$Value = explode(':', $Value);
$Value = array_pop($Value);
}
}
// Values are parsed according to their type
if (isset(self::$Spec_StructuredElements[$Key]))
{
$Value = self::ParseStructuredValue($Value, $Key);
if ($Type)
{
$Value['Type'] = $Type;
}
}
else
{
if (in_array($Key, self::$Spec_MultipleValueElements))
{
$Value = self::ParseMultipleTextValue($Value, $Key);
}
if ($Type)
{
$Value = array(
'Value' => $Value,
'Type' => $Type
);
}
}
if (is_array($Value) && $Encoding)
{
$Value['Encoding'] = $Encoding;
}
if (!isset($this -> Data[$Key]))
{
$this -> Data[$Key] = array();
}
$this -> Data[$Key][] = $Value;
}
}
}
/**
* Magic method to get the various vCard values as object members, e.g.
* a call to $vCard -> N gets the "N" value
*
* @param string Key
*
* @return mixed Value
*/
public function __get($Key)
{
$Key = strtolower($Key);
if (isset($this -> Data[$Key]))
{
if ($Key == 'agent')
{
return $this -> Data[$Key];
}
elseif (in_array($Key, self::$Spec_FileElements))
{
$Value = $this -> Data[$Key];
foreach ($Value as $K => $V)
{
if (stripos($V['Value'], 'uri:') === 0)
{
$Value[$K]['Value'] = substr($V, 4);
$Value[$K]['Encoding'] = 'uri';
}
}
return $Value;
}
if ($this -> Options['Collapse'] && is_array($this -> Data[$Key]) && (count($this -> Data[$Key]) == 1))
{
return $this -> Data[$Key][0];
}
return $this -> Data[$Key];
}
elseif ($Key == 'Mode')
{
return $this -> Mode;
}
return array();
}
/**
* Saves an embedded file
*
* @param string Key
* @param int Index of the file, defaults to 0
* @param string Target path where the file should be saved, including the filename
*
* @return bool Operation status
*/
public function SaveFile($Key, $Index = 0, $TargetPath = '')
{
if (!isset($this -> Data[$Key]))
{
return false;
}
if (!isset($this -> Data[$Key][$Index]))
{
return false;
}
// Returing false if it is an image URL
if (stripos($this -> Data[$Key][$Index]['Value'], 'uri:') === 0)
{
return false;
}
if (is_writable($TargetPath) || (!file_exists($TargetPath) && is_writable(dirname($TargetPath))))
{
$RawContent = $this -> Data[$Key][$Index]['Value'];
if (isset($this -> Data[$Key][$Index]['Encoding']) && $this -> Data[$Key][$Index]['Encoding'] == 'b')
{
$RawContent = base64_decode($RawContent);
}
$Status = file_put_contents($TargetPath, $RawContent);
return (bool)$Status;
}
else
{
throw new Exception('vCard: Cannot save file ('.$Key.'), target path not writable ('.$TargetPath.')');
}
return false;
}
/**
* Magic method for adding data to the vCard
*
* @param string Key
* @param string Method call arguments. First element is value.
*
* @return vCard Current object for method chaining
*/
public function __call($Key, $Arguments)
{
$Key = strtolower($Key);
if (!isset($this -> Data[$Key]))
{
$this -> Data[$Key] = array();
}
$Value = isset($Arguments[0]) ? $Arguments[0] : false;
if (count($Arguments) > 1)
{
$Types = array_values(array_slice($Arguments, 1));
if (isset(self::$Spec_StructuredElements[$Key]) &&
in_array($Arguments[1], self::$Spec_StructuredElements[$Key])
)
{
$LastElementIndex = 0;
if (count($this -> Data[$Key]))
{
$LastElementIndex = count($this -> Data[$Key]) - 1;
}
if (isset($this -> Data[$Key][$LastElementIndex]))
{
if (empty($this -> Data[$Key][$LastElementIndex][$Types[0]]))
{
$this -> Data[$Key][$LastElementIndex][$Types[0]] = $Value;
}
else
{
$LastElementIndex++;
}
}
if (!isset($this -> Data[$Key][$LastElementIndex]))
{
$this -> Data[$Key][$LastElementIndex] = array(
$Types[0] => $Value
);
}
}
elseif (isset(self::$Spec_ElementTypes[$Key]))
{
$this -> Data[$Key][] = array(
'Value' => $Value,
'Type' => $Types
);
}
}
elseif ($Value)
{
$this -> Data[$Key][] = $Value;
}
return $this;
}
/**
* Magic method for getting vCard content out
*
* @return string Raw vCard content
*/
public function __toString()
{
$Text = 'BEGIN:VCARD'.self::endl;
$Text .= 'VERSION:3.0'.self::endl;
foreach ($this -> Data as $Key => $Values)
{
$KeyUC = strtoupper($Key);
$Key = strtolower($Key);
if (in_array($KeyUC, array('PHOTO', 'VERSION')))
{
continue;
}
foreach ($Values as $Index => $Value)
{
$Text .= $KeyUC;
if (is_array($Value) && isset($Value['Type']))
{
$Text .= ';TYPE='.self::PrepareTypeStrForOutput($Value['Type']);
}
$Text .= ':';
if (isset(self::$Spec_StructuredElements[$Key]))
{
$PartArray = array();
foreach (self::$Spec_StructuredElements[$Key] as $Part)
{
$PartArray[] = isset($Value[$Part]) ? $Value[$Part] : '';
}
$Text .= implode(';', $PartArray);
}
elseif (is_array($Value) && isset(self::$Spec_ElementTypes[$Key]))
{
$Text .= $Value['Value'];
}
else
{
$Text .= $Value;
}
$Text .= self::endl;
}
}
$Text .= 'END:VCARD'.self::endl;
return $Text;
}
// !Helper methods
private static function PrepareTypeStrForOutput($Type)
{
return implode(',', array_map('strtoupper', $Type));
}
/**
* Removes the escaping slashes from the text.
*
* @access private
*
* @param string Text to prepare.
*
* @return string Resulting text.
*/
private static function Unescape($Text)
{
return str_replace(array('\:', '\;', '\,', "\n"), array(':', ';', ',', ''), $Text);
}
/**
* Separates the various parts of a structured value according to the spec.
*
* @access private
*
* @param string Raw text string
* @param string Key (e.g., N, ADR, ORG, etc.)
*
* @return array Parts in an associative array.
*/
private static function ParseStructuredValue($Text, $Key)
{
$Text = array_map('trim', explode(';', $Text));
$Result = array();
$Ctr = 0;
foreach (self::$Spec_StructuredElements[$Key] as $Index => $StructurePart)
{
$Result[$StructurePart] = isset($Text[$Index]) ? $Text[$Index] : null;
}
return $Result;
}
/**
* @access private
*/
private static function ParseMultipleTextValue($Text)
{
return explode(',', $Text);
}
/**
* @access private
*/
private static function ParseParameters($Key, array $RawParams = null)
{
if (!$RawParams)
{
return array();
}
// Parameters are split into (key, value) pairs
$Parameters = array();
foreach ($RawParams as $Item)
{
$Parameters[] = explode('=', strtolower($Item));
}
$Type = array();
$Result = array();
// And each parameter is checked whether anything can/should be done because of it
foreach ($Parameters as $Index => $Parameter)
{
// Skipping empty elements
if (!$Parameter)
{
continue;
}
// Handling type parameters without the explicit TYPE parameter name (2.1 valid)
if (count($Parameter) == 1)
{
// Checks if the type value is allowed for the specific element
// The second part of the "if" statement means that email elements can have non-standard types (see the spec)
if (
(isset(self::$Spec_ElementTypes[$Key]) && in_array($Parameter[0], self::$Spec_ElementTypes[$Key])) ||
($Key == 'email' && is_scalar($Parameter[0]))
)
{
$Type[] = $Parameter[0];
}
}
elseif (count($Parameter) > 2)
{
$TempTypeParams = self::ParseParameters($Key, explode(',', $RawParams[$Index]));
if ($TempTypeParams['type'])
{
$Type = array_merge($Type, $TempTypeParams['type']);
}
}
else
{
switch ($Parameter[0])
{
case 'encoding':
if (in_array($Parameter[1], array('quoted-printable', 'b', 'base64')))
{
$Result['encoding'] = $Parameter[1] == 'base64' ? 'b' : $Parameter[1];
}
break;
case 'charset':
$Result['charset'] = $Parameter[1];
break;
case 'type':
$Type = array_merge($Type, explode(',', $Parameter[1]));
break;
case 'value':
if (strtolower($Parameter[1]) == 'url')
{
$Result['encoding'] = 'uri';
}
break;
}
}
}
$Result['type'] = $Type;
return $Result;
}
// !Interface methods
// Countable interface
public function count()
{
switch ($this -> Mode)
{
case self::MODE_ERROR:
return 0;
break;
case self::MODE_SINGLE:
return 1;
break;
case self::MODE_MULTIPLE:
return count($this -> Data);
break;
}
return 0;
}
// Iterator interface
public function rewind()
{
reset($this -> Data);
}
public function current()
{
return current($this -> Data);
}
public function next()
{
return next($this -> Data);
}
public function valid()
{
return ($this -> current() !== false);
}
public function key()
{
return key($this -> Data);
}
}
?>