Sync
in package
Performs a synchronization of a local cache of the addressbook to the current state on the server.
If supported by the server, the synchronization uses the sync-collection (RFC 6578) report to efficiently request the changed cards and the addressbook-multiget (RFC 6352) report to fetch all changed cards in a single request. If the server does not support these operations, the service falls back to alternative methods transparently.
Table of Contents
- synchronize() : string
- Performs a synchronization of the given addressbook.
- determineChangesViaETags() : SyncResult
- Determines changes to the addressbook at the server side using PROPFIND.
- multiGetChanges() : void
- Downloads a set of cards from the server using addressbook-multiget.
- syncCollection() : SyncResult
- Determines changes to the addressbook at the server side using the sync-collection REPORT.
- synchronizeOneBatch() : SyncResult
- Performs a synchronization of the given addressbook for one synchronization chunk as dictated by the server.
Methods
synchronize()
Performs a synchronization of the given addressbook.
public
synchronize(AddressbookCollection $abook, SyncHandler $handler[, array<int, string> $requestedVCardProps = [] ][, string $prevSyncToken = "" ]) : string
Parameters
- $abook : AddressbookCollection
-
The addressbook to synchronize
- $handler : SyncHandler
-
A SyncHandler object that will be informed about new/changed and deleted cards.
- $requestedVCardProps : array<int, string> = []
-
List of VCard properties to request for retrieved VCards. If empty the full VCards are retrieved. Note that many servers do not support this and will always provide the full cards regardless of this parameter.
- $prevSyncToken : string = ""
-
Sync-token of a previous sync when performing an incremental sync. Empty string to perform a full sync (all cards of the addressbook will be reported as changed).
Tags
Return values
string —The sync token corresponding to the just synchronized (or slightly earlier) state of the collection.
determineChangesViaETags()
Determines changes to the addressbook at the server side using PROPFIND.
private
determineChangesViaETags(CardDavClient $client, AddressbookCollection $abook, SyncHandler $handler) : SyncResult
This performs a card-by-card ETag comparison of the current ETags reported by the server and the locally stored ETags corresponding to the state of the last retrieved cards.
Parameters
- $client : CardDavClient
-
The client to use for communicating with the server.
- $abook : AddressbookCollection
-
The addressbook that should be synchronized.
- $handler : SyncHandler
-
The application-side sync handler, that will have to provide the list of local cards and their ETags.
Return values
SyncResult —Changes to the addressbook reported by the server with respect to $prevSyncToken, including a new sync token.
multiGetChanges()
Downloads a set of cards from the server using addressbook-multiget.
private
multiGetChanges(CardDavClient $client, AddressbookCollection $abook, SyncResult $syncResult, array<int, string> $requestedVCardProps) : void
The downloaded cards are stored to SyncResult::$changedObjects along with the corresponding ETag. In case the data for a card cannot be retrieved, a warning is logged and the corresponding card will have no data associated.
Parameters
- $client : CardDavClient
-
The client to use for communicating with the server.
- $abook : AddressbookCollection
-
The addressbook to fetch the cards from.
- $syncResult : SyncResult
-
The SyncResult object to store the retrieved cards to, which already contains the URIs of the changed cards to fetch.
- $requestedVCardProps : array<int, string>
Tags
Return values
void —syncCollection()
Determines changes to the addressbook at the server side using the sync-collection REPORT.
private
syncCollection(CardDavClient $client, AddressbookCollection $abook, string $prevSyncToken) : SyncResult
Parameters
- $client : CardDavClient
-
The client to use for communicating with the server.
- $abook : AddressbookCollection
-
The addressbook that should be synchronized.
- $prevSyncToken : string
-
The sync token of the last sync, or empty string if this is the initial sync.
Return values
SyncResult —Changes to the addressbook reported by the server with respect to $prevSyncToken, including a new sync token.
synchronizeOneBatch()
Performs a synchronization of the given addressbook for one synchronization chunk as dictated by the server.
private
synchronizeOneBatch(AddressbookCollection $abook, SyncHandler $handler, array<int, string> $requestedVCardProps, string $prevSyncToken) : SyncResult
Parameters
- $abook : AddressbookCollection
- $handler : SyncHandler
- $requestedVCardProps : array<int, string>
- $prevSyncToken : string
Tags
Return values
SyncResult —The synchronization result object.