How FreeITSM reads a CardDAV address book and turns its contacts into rows in users. Shipped in 1.8.0, asked for in #133.

This page covers the transport and the mapping — connecting, reading, and turning a vCard into a person. The import itself, the scope rules and the run lifecycle are on CardDAV import internals.

🔑 Reading only. Sending a change the other way — surgical vCard editing, folding, escaping and the conflict rule — is a separate file (includes/carddav_write.php) and a separate page: CardDAV write-back internals. The split is deliberate, so that "the import issues PROPFIND and REPORT and nothing else" stays a fact about the code.

For the administrator's view, see CardDAV contact sync.

Directory sync already knew how to bring people into users safely. What it did not know was how to speak anything but LDAP.

includes/directory_sync.php owns the policy: nobody is ever deleted, a run that returns far fewer people than last time changes nothing, missing once is noise. None of that is about LDAP — and none of it was rebuilt.

What is about LDAP is every extension point around it: the columns are named ldap_attr_*, paging uses LDAP_CONTROL_PAGEDRESULTS, identity is objectGUID or entryUUID, and a manager is a distinguished name. CardDAV is HTTP and vCard — no DNs, no paged controls, identity is a URL plus an ETag.

So this is a fetch-and-map layer bolted under an existing policy layer, deliberately narrow:

        ┌──────────────── CardDAV ────────────────┐   ┌──── LDAP ────┐
        │  includes/carddav.php      (transport)  │   │  ldap_*()    │
        │  includes/carddav_sync.php (map + run)  │   │              │
        └────────────────────┬────────────────────┘   └──────┬───────┘
                             │                              │
                             └──────────────┬───────────────┘
                                            ▼
                        includes/directory_sync.php  (the policy layer)
                        dsyncFindExisting / dsyncCreate / dsyncApplyToExisting
                        dsyncHandleMissing / syncBrakeTripped / dsyncGetRun
                                            ▼
                                    users, directory_sync_runs

🔑 The policy layer turned out to be genuinely transport-agnostic, which was not a given — it was written with only LDAP in mind. The import calls ten of its functions and nine are used exactly as the LDAP path uses them. The one change needed was cosmetic: syncBrakeTripped() gained an optional $words parameter so its message can say "the wrong address book, or a group renamed on the server" instead of naming a base DN. LDAP's defaults are untouched, so that path behaves identically.

Colour key: 🗄️ schema · ⚙️ engine · 🔌 API · 🖥️ UI · 🌍 i18n · 🐳 test rig

Read this before changing anything in carddav.php.

A stock Baïkal — the standard sabre/dav server, and what the reporter runs — ships dav_auth_type: Digest. Measured against 0.12.1:

Basic is the obvious choice and what almost every REST integration reaches for, and against a default install it fails outright. The operator then sees "authentication failed", checks a password that is correct, and concludes FreeITSM is broken.

$authMode = CURLAUTH_ANY;
if (($cfg['auth'] ?? 'auto') === 'digest') $authMode = CURLAUTH_DIGEST;
if (($cfg['auth'] ?? 'auto') === 'basic')  $authMode = CURLAUTH_BASIC;

So: CURLAUTH_ANY by default, an explicit override for the rare server that needs one, and the connection test reports which scheme actually won — because that is the one thing the operator cannot discover for themselves.

Three smaller things in cardDavRequest() that exist for a reason:

• It sends a real User-Agent. PHP's cURL sends none by default, and something in front of a server will read that as a bot and block it. That exact mistake once cost an afternoon of chasing a phantom WAF.
• It follows redirects. http:// → https://, or a path gaining a trailing slash, are both routine.
• cardDavExplainStatus() turns a status code into a sentence. 405 in particular is worth a real explanation: it means the address is reachable but is not a CardDAV endpoint — almost always a web page rather than the DAV path. A bare "HTTP 405" sends somebody to check their password.

$body = '<?xml version="1.0" encoding="utf-8"?>' .
        '<d:propfind xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav" …>' .
        '<d:prop><d:displayname/><d:resourcetype/><cs:getctag/></d:prop>' .
        '</d:propfind>';

A collection carrying the {urn:ietf:params:xml:ns:carddav}addressbook resource type is an address book. Everything else in the response — including the container you asked about — is not, which is how the parent gets excluded without special-casing it by URL.

⚠️ Namespaces are not optional. Servers use different prefixes for the same namespaces: Baïkal answers with d: and card:, others with D: and C:. Anything matching on prefixes works against one server and silently finds nothing against the next. cardDavParseAddressBooks() registers the URIs and queries those:

$xp->registerNamespace('d', 'DAV:');
$xp->registerNamespace('card', 'urn:ietf:params:xml:ns:carddav');

🔑 null and [] are different answers and must not be collapsed. cardDavParseAddressBooks() returns null when the body will not parse as DAV at all, and [] when it parsed fine and held no address books. The first is a wrong URL; the second is an empty account. Merging them produces "no address books found" for somebody who typed their web interface by mistake, and they will check their address books rather than their URL.

$body = '<?xml version="1.0" encoding="utf-8"?>' .
        '<card:addressbook-query xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">' .
        '<d:prop><d:getetag/><card:address-data/></d:prop>' .
        '</card:addressbook-query>';

address-data returns the vCards inline, so this is one round trip. The obvious alternative — PROPFIND for the hrefs then a GET per card — is, on an address book of a few thousand contacts, the difference between one request and a few thousand.

⚠️ A server may answer with an absolute URL, a root-relative path, or a bare segment, and all three are legal. Concatenating blindly gives you https://host/dav.php/addressbooks/jsmith//dav.php/addressbooks/jsmith/itsm/ — a 404 that reads like a missing address book rather than a client bug. cardDavAbsoluteUrl() handles the three cases.

RFC 6350 folds any line longer than 75 octets by inserting CRLF followed by a single space or tab. Servers really do this, and a long CATEGORIES list is exactly the kind of property that gets folded.

Parse the raw text line by line and you read:

CATEGORIES:customer,supplier,pa
 rtner

as two lines — so the last value in a long list silently goes missing and everything still looks like it worked. One line prevents it:

$norm = str_replace(["\r\n", "\r"], "\n", $vcard);
$norm = preg_replace("/\n[ \t]/", '', $norm);   // a continuation is \n + exactly one space or tab

CATEGORIES:a,b and CATEGORIES;TYPE=x:a,b are the same property. An implementation looking for the literal CATEGORIES: misses the second. cardDavProperty() strips parameters, then compares case-insensitively because the spec says property names are case-insensitive:

$left = substr($line, 0, $colon);
$semi = strpos($left, ';');
$prop = strtoupper(trim($semi === false ? $left : substr($left, 0, $semi)));

A comma inside a value is escaped, so splitting on a bare comma breaks it. Every split in this code uses a negative lookbehind:

preg_split('/(?<!\\\\),/', $rawCategories)   // commas, but not \,
preg_split('/(?<!\\\\);/', $rawOrg)          // semicolons, but not \;

cdsyncMapCard() returns the array the policy layer expects, or null to skip the card.

return [
    'guid'        => $uid,          // the policy layer's name; for LDAP it is objectGUID
    'username'    => '',            // a contact has no sign-in name
    'email'       => $email ?: null,
    'name'        => $name,
    'job_title'   => trim(cardDavProperty($lines, 'TITLE')[0] ?? '') ?: null,
    'department'  => $org['department'],
    'office'      => cdsyncLocality($lines),
    'phone'       => $phone,
    'mobile'      => $mobile,
    'employee_id' => null,          // vCard has nowhere to keep one
    'manager_dn'  => null,          // RELATED;TYPE=manager exists, almost nothing writes it
    'dn'          => $href,         // for logging: the display equivalent of a DN
];

// A KIND:group card is a container, not a person. "ITSM" is not somebody
// called ITSM, and importing one creates a contact nobody can explain.
if (strtolower(trim(cardDavProperty($lines, 'KIND')[0] ?? '')) === 'group') return null;

// ⚠️ The UID is the identity. Without one there is nothing stable to match on
// across runs — the next run would create a second copy of the same person.
if ($uid === '') return null;

🔑 Skipping on a missing UID rather than falling back to the name is the important one. A name is not unique and not stable, so matching on it would either merge two different people or duplicate one person every run. Skipping is visible and recoverable; a duplicate every night is neither.

Why username is '' and not the email. A contact has no sign-in. The policy layer already stores NULL rather than an empty string for it, so contacts do not pile up against a unique index.

• CardDAV import internals — scope resolution, the run lifecycle, the counts bug, the CLI, and the Docker test rig
• Directory sync developer guide — the policy layer this sits under
• Extending directory sync — §2, the extension points this deliberately does NOT use
• CalDAV and CardDAV — §5 priced this work before it was done, and was right
• CardDAV contact sync — the administrator's view
• CardDAV write-back internals — the other direction, and the reason it is a separate file
• CalDAV and CardDAV — the original analysis, and CalDAV, which is still not built