<?php
/**
* CardDAV PHP
*
* Simple CardDAV query
* --------------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* echo $carddav->get();
*
*
* Simple vCard query
* ------------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* echo $carddav->get_vcard('0126FFB4-2EB74D0A-302EA17F');
*
*
* XML vCard query
* ------------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* echo $carddav->get_xml_vcard('0126FFB4-2EB74D0A-302EA17F');
*
*
* Check CardDAV server connection
* -------------------------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* var_dump($carddav->check_connection());
*
*
* CardDAV delete query
* --------------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* $carddav->delete('0126FFB4-2EB74D0A-302EA17F');
*
*
* CardDAV add query
* --------------------
* $vcard = 'BEGIN:VCARD
* VERSION:3.0
* UID:1f5ea45f-b28a-4b96-25as-ed4f10edf57b
* FN:Christian Putzke
* N:Christian;Putzke;;;
* EMAIL;TYPE=OTHER:christian.putzke@graviox.de
* END:VCARD';
*
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* $vcard_id = $carddav->add($vcard);
*
*
* CardDAV update query
* --------------------
* $vcard = 'BEGIN:VCARD
* VERSION:3.0
* UID:1f5ea45f-b28a-4b96-25as-ed4f10edf57b
* FN:Christian Putzke
* N:Christian;Putzke;;;
* EMAIL;TYPE=OTHER:christian.putzke@graviox.de
* END:VCARD';
*
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->set_auth('username', 'password');
* $carddav->update($vcard, '0126FFB4-2EB74D0A-302EA17F');
*
*
* CardDAV debug
* -------------
* $carddav = new carddav_backend('https://davical.example.com/user/contacts/');
* $carddav->enable_debug();
* $carddav->set_auth('username', 'password');
* $carddav->get();
* var_dump($carddav->get_debug());
*
*
* CardDAV server list
* -------------------
* DAViCal: https://example.com/{resource|principal|username}/{collection}/
* Apple Addressbook Server: https://example.com/addressbooks/users/{resource|principal|username}/{collection}/
* memotoo: https://sync.memotoo.com/cardDAV/
* SabreDAV: https://example.com/addressbooks/{resource|principal|username}/{collection}/
* ownCloud: https://example.com/apps/contacts/carddav.php/addressbooks/{resource|principal|username}/{collection}/
* SOGo: https://example.com/SOGo/dav/{resource|principal|username}/Contacts/{collection}/
*
*
* @author Christian Putzke <christian.putzke@graviox.de>
* @copyright Christian Putzke
* @link http://www.graviox.de/
* @link https://twitter.com/cputzke/
* @since 20.07.2011
* @version 0.6
* @license http://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
*
*/
class carddav_backend
{
/**
* CardDAV PHP Version
*
* @constant string
*/
const VERSION = '0.6';
/**
* User agent displayed in http requests
*
* @constant string
*/
const USERAGENT = 'CardDAV PHP/';
/**
* CardDAV server url
*
* @var string
*/
private $url = null;
/**
* CardDAV server url_parts
*
* @var array
*/
private $url_parts = null;
/**
* Authentication string
*
* @var string
*/
private $auth = null;
/**
* Authentication: username
*
* @var string
*/
private $username = null;
/**
* Authentication: password
*
* @var string
*/
private $password = null;
/**
* Characters used for vCard id generation
*
* @var array
*/
private $vcard_id_chars = array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 'C', 'D', 'E', 'F');
/**
* CardDAV server connection (curl handle)
*
* @var resource
*/
private $curl;
/**
* Debug on or off
*
* @var boolean
*/
private $debug = false;
/**
* All available debug information
*
* @var array
*/
private $debug_information = array();
/**
* Exception codes
*/
const EXCEPTION_WRONG_HTTP_STATUS_CODE_GET = 1000;
const EXCEPTION_WRONG_HTTP_STATUS_CODE_GET_VCARD = 1001;
const EXCEPTION_WRONG_HTTP_STATUS_CODE_GET_XML_VCARD = 1002;
const EXCEPTION_WRONG_HTTP_STATUS_CODE_DELETE = 1003;
const EXCEPTION_WRONG_HTTP_STATUS_CODE_ADD = 1004;
const EXCEPTION_WRONG_HTTP_STATUS_CODE_UPDATE = 1005;
const EXCEPTION_MALFORMED_XML_RESPONSE = 1006;
const EXCEPTION_COULD_NOT_GENERATE_NEW_VCARD_ID = 1007;
/**
* Constructor
* Sets the CardDAV server url
*
* @param string $url CardDAV server url
*/
public function __construct($url = null)
{
if ($url !== null)
{
$this->set_url($url);
}
}
/**
* Sets debug information
*
* @param array $debug_information Debug information
* @return void
*/
public function set_debug(array $debug_information)
{
$this->debug_information[] = $debug_information;
}
/**
* Sets the CardDAV server url
*
* @param string $url CardDAV server url
* @return void
*/
public function set_url($url)
{
$this->url = $url;
if (substr($this->url, -1, 1) !== '/')
{
$this->url = $this->url . '/';
}
$this->url_parts = parse_url($this->url);
}
/**
* Sets authentication information
*
* @param string $username CardDAV server username
* @param string $password CardDAV server password
* @return void
*/
public function set_auth($username, $password)
{
$this->username = $username;
$this->password = $password;
$this->auth = $username . ':' . $password;
}
/**
* Gets all available debug information
*
* @return array $this->debug_information All available debug information
*/
public function get_debug()
{
return $this->debug_information;
}
/**
* Gets all vCards including additional information from the CardDAV server
*
* @param boolean $include_vcards Include vCards within the response (simplified only)
* @param boolean $raw Get response raw or simplified
* @return string Raw or simplified XML response
*/
public function get($include_vcards = true, $raw = false)
{
$result = $this->query($this->url, 'PROPFIND');
switch ($result['http_code'])
{
case 200:
case 207:
if ($raw === true)
{
return $result['response'];
}
else
{
return $this->simplify($result['response'], $include_vcards);
}
break;
default:
throw new Exception('Woops, something\'s gone wrong! The CardDAV server returned the http status code ' . $result['http_code'] . '.', self::EXCEPTION_WRONG_HTTP_STATUS_CODE_GET);
break;
}
}
/**
* Gets a clean vCard from the CardDAV server
*
* @param string $vcard_id vCard id on the CardDAV server
* @return string vCard (text/vcard)
*/
public function get_vcard($vcard_id)
{
$vcard_id = str_replace('.vcf', null, $vcard_id);
$result = $this->query($this->url . $vcard_id . '.vcf', 'GET');
switch ($result['http_code'])
{
case 200:
case 207:
return $result['response'];
break;
default:
throw new Exception('Woops, something\'s gone wrong! The CardDAV server returned the http status code ' . $result['http_code'] . '.', self::EXCEPTION_WRONG_HTTP_STATUS_CODE_GET_VCARD);
break;
}
}
/**
* Gets a vCard + XML from the CardDAV Server
*
* @param string $vcard_id vCard id on the CardDAV Server
* @return string Raw or simplified vCard (text/xml)
*/
public function get_xml_vcard($vcard_id)
{
$vcard_id = str_replace('.vcf', null, $vcard_id);
$xml = new XMLWriter();
$xml->openMemory();
$xml->setIndent(4);
$xml->startDocument('1.0', 'utf-8');
$xml->startElement('C:addressbook-multiget');
$xml->writeAttribute('xmlns:D', 'DAV:');
$xml->writeAttribute('xmlns:C', 'urn:ietf:params:xml:ns:carddav');
$xml->startElement('D:prop');
$xml->writeElement('D:getetag');
$xml->writeElement('D:getlastmodified');
$xml->endElement();
$xml->writeElement('D:href', $this->url_parts['path'] . $vcard_id . '.vcf');
$xml->endElement();
$xml->endDocument();
$result = $this->query($this->url, 'REPORT', $xml->outputMemory(), 'text/xml');
switch ($result['http_code'])
{
case 200:
case 207:
return $this->simplify($result['response'], true);
break;
default:
throw new Exception('Woops, something\'s gone wrong! The CardDAV server returned the http status code ' . $result['http_code'] . '.', self::EXCEPTION_WRONG_HTTP_STATUS_CODE_GET_XML_VCARD);
break;
}
}
/**
* Enables the debug mode
*
* @return void
*/
public function enable_debug()
{
$this->debug = true;
}
/**
* Checks if the CardDAV server is reachable
*
* @return boolean
*/
public function check_connection()
{
$result = $this->query($this->url, 'OPTIONS');
if ($result['http_code'] === 200)
{
return true;
}
else
{
return false;
}
}
/**
* Cleans the vCard
*
* @param string $vcard vCard
* @return string $vcard vCard
*/
private function clean_vcard($vcard)
{
$vcard = str_replace("\t", null, $vcard);
return $vcard;
}
/**
* Deletes an entry from the CardDAV server
*
* @param string $vcard_id vCard id on the CardDAV server
* @return boolean
*/
public function delete($vcard_id)
{
$result = $this->query($this->url . $vcard_id . '.vcf', 'DELETE');
switch ($result['http_code'])
{
case 204:
return true;
break;
default:
throw new Exception('Woops, something\'s gone wrong! The CardDAV server returned the http status code ' . $result['http_code'] . '.', self::EXCEPTION_WRONG_HTTP_STATUS_CODE_DELETE);
break;
}
}
/**
* Adds an entry to the CardDAV server
*
* @param string $vcard vCard
* @param string $vcard_id vCard id on the CardDAV server
* @return string The new vCard id
*/
public function add($vcard, $vcard_id = null)
{
if ($vcard_id === null)
{
$vcard_id = $this->generate_vcard_id();
}
$vcard = $this->clean_vcard($vcard);
$result = $this->query($this->url . $vcard_id . '.vcf', 'PUT', $vcard, 'text/vcard');
switch($result['http_code'])
{
case 201:
return $vcard_id;
break;
default:
throw new Exception('Woops, something\'s gone wrong! The CardDAV server returned the http status code ' . $result['http_code'] . '.', self::EXCEPTION_WRONG_HTTP_STATUS_CODE_ADD);
break;
}
}
/**
* Updates an entry to the CardDAV server
*
* @param string $vcard vCard
* @param string $vcard_id vCard id on the CardDAV server
* @return boolean
*/
public function update($vcard, $vcard_id)
{
try
{
return $this->add($vcard, $vcard_id);
}
catch (Exception $e)
{
throw new Exception($e->getMessage(), self::EXCEPTION_WRONG_HTTP_STATUS_CODE_UPDATE);
}
}
/**
* Simplify CardDAV XML response
*
* @param string $response CardDAV XML response
* @param boolean $include_vcards Include vCards or not
* @return string Simplified CardDAV XML response
*/
private function simplify($response, $include_vcards = true)
{
$response = $this->clean_response($response);
try
{
$xml = new SimpleXMLElement($response);
}
catch(Exception $e)
{
throw new Exception('The XML response seems to be malformed and can\'t be simplified!', self::EXCEPTION_MALFORMED_XML_RESPONSE, $e);
}
$simplified_xml = new XMLWriter();
$simplified_xml->openMemory();
$simplified_xml->setIndent(4);
$simplified_xml->startDocument('1.0', 'utf-8');
$simplified_xml->startElement('response');
if (!empty($xml->response))
{
foreach ($xml->response as $response)
{
if (preg_match('/vcard/', $response->propstat->prop->getcontenttype) || preg_match('/vcf/', $response->href))
{
$id = basename($response->href);
$id = str_replace('.vcf', null, $id);
if (!empty($id))
{
$simplified_xml->startElement('element');
$simplified_xml->writeElement('id', $id);
$simplified_xml->writeElement('etag', str_replace('"', null, $response->propstat->prop->getetag));
$simplified_xml->writeElement('last_modified', $response->propstat->prop->getlastmodified);
if ($include_vcards === true)
{
$simplified_xml->writeElement('vcard', $this->get_vcard($id));
}
$simplified_xml->endElement();
}
}
else if (preg_match('/unix-directory/', $response->propstat->prop->getcontenttype))
{
if (isset($response->propstat->prop->href))
{
$href = $response->propstat->prop->href;
}
else if (isset($response->href))
{
$href = $response->href;
}
else
{
$href = null;
}
$url = str_replace($this->url_parts['path'], null, $this->url) . $href;
$simplified_xml->startElement('addressbook_element');
$simplified_xml->writeElement('display_name', $response->propstat->prop->displayname);
$simplified_xml->writeElement('url', $url);
$simplified_xml->writeElement('last_modified', $response->propstat->prop->getlastmodified);
$simplified_xml->endElement();
}
}
}
$simplified_xml->endElement();
$simplified_xml->endDocument();
return $simplified_xml->outputMemory();
}
/**
* Cleans CardDAV XML response
*
* @param string $response CardDAV XML response
* @return string $response Cleaned CardDAV XML response
*/
private function clean_response($response)
{
$response = utf8_encode($response);
$response = str_replace('D:', null, $response);
$response = str_replace('d:', null, $response);
$response = str_replace('C:', null, $response);
$response = str_replace('c:', null, $response);
return $response;
}
/**
* Curl initialization
*
* @return void
*/
public function curl_init()
{
if (empty($this->curl))
{
$this->curl = curl_init();
curl_setopt($this->curl, CURLOPT_HEADER, true);
curl_setopt($this->curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($this->curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($this->curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($this->curl, CURLOPT_USERAGENT, self::USERAGENT.self::VERSION);
if ($this->auth !== null)
{
curl_setopt($this->curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_setopt($this->curl, CURLOPT_USERPWD, $this->auth);
}
}
}
/**
* Query the CardDAV server via curl and returns the response
*
* @param string $url CardDAV server URL
* @param string $method HTTP method like (OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE)
* @param string $content Content for CardDAV queries
* @param string $content_type Set content type
* @return array Raw CardDAV Response and http status code
*/
private function query($url, $method, $content = null, $content_type = null)
{
$this->curl_init();
curl_setopt($this->curl, CURLOPT_URL, $url);
curl_setopt($this->curl, CURLOPT_CUSTOMREQUEST, $method);
if ($content !== null)
{
curl_setopt($this->curl, CURLOPT_POST, true);
curl_setopt($this->curl, CURLOPT_POSTFIELDS, $content);
}
else
{
curl_setopt($this->curl, CURLOPT_POST, false);
curl_setopt($this->curl, CURLOPT_POSTFIELDS, null);
}
if ($content_type !== null)
{
curl_setopt($this->curl, CURLOPT_HTTPHEADER, array('Content-type: '.$content_type));
}
else
{
curl_setopt($this->curl, CURLOPT_HTTPHEADER, array());
}
$complete_response = curl_exec($this->curl);
$header_size = curl_getinfo($this->curl, CURLINFO_HEADER_SIZE);
$http_code = curl_getinfo($this->curl, CURLINFO_HTTP_CODE);
$header = trim(substr($complete_response, 0, $header_size));
$response = substr($complete_response, $header_size);
$return = array(
'response' => $response,
'http_code' => $http_code
);
if ($this->debug === true)
{
$debug = $return;
$debug['url'] = $url;
$debug['method'] = $method;
$debug['content'] = $content;
$debug['content_type'] = $content_type;
$debug['header'] = $header;
$this->set_debug($debug);
}
return $return;
}
/**
* Returns a valid and unused vCard id
*
* @return string $vcard_id Valid vCard id
*/
private function generate_vcard_id()
{
$vcard_id = null;
for ($number = 0; $number <= 25; $number ++)
{
if ($number == 8 || $number == 17)
{
$vcard_id .= '-';
}
else
{
$vcard_id .= $this->vcard_id_chars[mt_rand(0, (count($this->vcard_id_chars) - 1))];
}
}
try
{
$carddav = new carddav_backend($this->url);
$carddav->set_auth($this->username, $this->password);
$result = $carddav->query($this->url . $vcard_id . '.vcf', 'GET');
if ($result['http_code'] !== 404)
{
$vcard_id = $this->generate_vcard_id();
}
return $vcard_id;
}
catch (Exception $e)
{
throw new Exception($e->getMessage(), self::EXCEPTION_COULD_NOT_GENERATE_NEW_VCARD_ID);
}
}
/**
* Destructor
* Close curl connection if it's open
*
* @return void
*/
public function __destruct()
{
if (!empty($this->curl))
{
curl_close($this->curl);
}
}
}