abook_carddav_squirrelmail/vendor/mstilkerich/carddavclient/README.md

CardDAV client library for PHP ("PHP-CardDavClient")

This is a library for PHP applications to interact with addressbooks stored on CardDAV servers.

Features

• CardDAV addressbook discovery as defined by RFC 6764 (using DNS SRV records and/or well-known URIs)
• Synchronization of the server-side addressbook and a local cache
  • Using efficient sync-collection (RFC 6578) and addressbook-multiget (RFC 6352) reports if supported by server
  • Falling back to synchronization via PROPFIND and comparison against the local cache state if the server does not support these reports
• Modification of addressbooks (adding/changing/deleting address objects)
• Uses Guzzle HTTP client library, including support for HTTP/2 and various authentication schemes
  • OAuth/OAuth2 is not supported at the moment
• Uses Sabre/VObject at the application-side interface to exchange VCards
• Uses any PSR-3 compliant logger object to record log messages and the HTTP traffic. A separate logger object is used for the HTTP traffic, which tends to be verbose and therefore logging for HTTP could be done to a separate location or disabled independent of the library's own log messages.

See the feature matrix for which services to my observations support which features; the file also contains a list of the known issues I am aware of with the different servers.

Tested Servers

Currently, this library has been tested to interoperate with:

• Nextcloud 18 and later (Basic Auth and GSSAPI/Kerberos 5)
• iCloud
• Google Contacts via CardDAV API (only HTTP Basic Authentication)
• Radicale 3 (also used by Synology as DSM CardDAV server)
• Owncloud 10
• Baïkal 0.7 (Digest Auth and GSSAPI/Kerberos 5)
• Davical 1.1.7

In theory, it should work with any CardDAV server. If it does not, please open an issue.

Note: For using any authentication mechanism other than Basic, you need to have the php-curl extension installed with support for the corresponding authentication mechanism.

Installation

This library is intended to be used with composer to install/update the library and its dependencies. It is intended to be used with a PSR-4 compliant autoloader (as provided by composer).

To add the library as a dependency to your project via composer:

1. Download composer (skip if you already have composer): Instructions

2. Add this library as a dependency to your project

php composer.phar require mstilkerich/carddavclient

3. To use the library in your application with composer, simply load composer's autoloader in your main php file:

require 'vendor/autoload.php';

The autoloader will take care of loading this and other PSR-0/PSR-4 autoloader-compliant libraries.

Documentation

Quickstart

Generally, an application using this library will want to do some or all of the following things:

1. Discover addressbooks from the information provided by a user: For this operation, the library provides a service class MStilkerich\CardDavClient\Services\Discovery. The service takes the account credentials and a partial URI (at the minimum a domain name) and with that attempts to discover the user's addressbooks. It returns an array of MStilkerich\CardDavClient\AddressbookCollection objects, each representing an addressbook.

2. Recreate addressbooks in known locations, discovered earlier. This is possible by simply creating instances of MStilkerich\CardDavClient\AddressbookCollection.

3. Initially and periodically synchronize the server-side addressbook with a local cache: For this operation, the library provides a service class MStilkerich\CardDavClient\Services\Sync. This service performs synchronization given MStilkerich\CardDavClient\AddressbookCollection object and optionally a synchronization token returned by the previous sync operation. A synchronization token is a server-side identification of the state of the addressbook at a certain time. When a synchronization token is given, the server will be asked to only report the delta between the state identified by the synchronization token and the current state. This may not work for various reasons, the most common being that synchronization tokens are not kept indefinitly by the server. In such cases, a full synchronization will be performed. At the end of the sync, the service returns the synchronization token reflecting the synchronized state of the addressbook, if provided by the server.

4. Perform changes to the server-side addressbook such as creating new address objects. These operations are directly provided as methods of the MStilkerich\CardDavClient\AddressbookCollection class.

5. Search the server-side addressbook to retrieve cards matching certain filter criteria. This operation is provided via the MStilkerich\CardDavClient\AddressbookCollection::query() API.

There is a demo script doc/quickstart.php distributed with the library that shows how to perform all the above operations.

Sample Applications

For a simple demo application that makes use of this library, see davshell. It shows how to use the library for the discovery and synchronization of addressbooks.

As a more complex real-world application, you can also take a look at the Roundcube CardDAV plugin, which also uses this library for the interaction with the CardDAV server.

API documentation

An overview of the API is available here.

The API documentation for the latest released version can be found here. The public API of the library can be found via the Public package in the navigation sidebar.

Documentation for the API can be generated from the source code using phpDocumentor by running make doc.