/vCard.php

<?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);
		}
	}
?>