Documentation

Horde_SyncMl_Backend_Sql extends Horde_SyncMl_Backend
in package

SyncMl

A SyncML Backend provides the interface between the SyncML protocol and an actual calendar or address book application. This "actual application" is called the "data store" in this description.

LOGFILE_CLIENTMESSAGE = 1: Types of logfiles. See logFile() method.
LOGFILE_DATA = 4
LOGFILE_DEVINF = 3
LOGFILE_SERVERMESSAGE = 2
MODE_CLIENT = 2
MODE_SERVER = 1: Backend modes.
MODE_TEST = 3
$state : Horde_SyncMl_State: The State object.
$_backendMode : int: The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.
$_charset : string: The charset used in the SyncML messages.
$_db : MDB2: A PEAR MDB2 instance.
$_debugDir : string: The directory where debugging information is stored.
$_debugFiles : bool: Whether to save SyncML messages in the debug directory.
$_logLevel : string: The log level.
$_logtext : string: The concatenated log messages.
$_syncDeviceID : string: The ID of the client device.
$_user : string: The current user.
__construct() : mixed: Constructor.
addEntry() : array<string|int, mixed>: Adds an entry into the server database.
addEntry_backend() : array<string|int, mixed>: Adds an entry into the server database.
checkAuthentication() : bool|string: Authenticates the user at the backend.
close() : mixed: Cleanup public function called after all message processing is finished.
createUidMap() : mixed: Creates a map entry to map between server and client IDs.
deleteEntry() : bool: Deletes an entry from the server database.
deleteEntry_backend() : bool: Deletes an entry from the server database.
eraseMap() : mixed: Erases all mapping entries for one combination of user, device ID.
factory() : Horde_SyncMl_Backend: Attempts to return a concrete Horde_SyncMl_Backend instance based on $driver.
getCharset() : string: Returns the charset.
getCurrentTimeStamp() : mixed: Returns the current timestamp in the same format as used by getServerChanges().
getParameter() : mixed: Extracts an HTTP GET like parameter from an URL.
getServerChanges() : mixed: Returns entries that have been modified in the server database.
getSyncDeviceID() : string: Returns the current device's ID.
getUser() : string: Returns the current user.
isValidDatabaseURI() : bool: Returns whether a database URI is valid to be synced with this backend.
logFile() : mixed: Logs data to a file in the debug directory.
logMessage() : mixed: Logs a message in the backend.
normalize() : string: Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.
readSyncAnchors() : mixed: Reads the previously written sync anchors from the database.
replaceEntry() : string: Replaces an entry in the server database.
replaceEntry_backend() : string: Replaces an entry in the server database.
retrieveEntry() : mixed: Retrieves an entry from the backend.
sessionClose() : mixed: Closes the PHP session.
sessionStart() : mixed: Starts a PHP session.
setCharset() : mixed: Sets the charset.
setupState() : mixed: Is called after the Horde_SyncMl_State object has been set up, either restored from the session, or freshly created.
setUser() : mixed: Sets the user used for this session.
testSetup() : mixed: Creates a clean test environment in the backend.
testStart() : mixed: Prepares the test start.
testTearDown() : mixed: Tears down the test environment after the test is run.
writeSyncAnchors() : mixed: Stores Sync anchors after a successful synchronization to allow two-way synchronization next time.
_checkAuthentication() : bool|string: Authenticates the user at the backend.
_checkForError() : mixed: Checks if the parameter is a PEAR_Error object and if so logs the error.
_cleanUser() : mixed
_getChangeTS() : mixed: Returns a timestamp stored in the map for a given Server ID.
_getCuid() : mixed: Retrieves the Client ID for a given Server ID from the map.
_getSuid() : mixed: Retrieves the Server ID for a given Client ID from the map.
_removeFromSuidList() : mixed: Removes a suid from the suidlist.
_setAuthenticated() : string: Sets a user as being authenticated at the backend.
_trackDeletes() : array<string|int, mixed>: Returns a list of item IDs that have been deleted since the last sync run and stores a complete list of IDs for next sync run.

LOGFILE_CLIENTMESSAGE

Types of logfiles. See logFile() method.


    public
    mixed
    LOGFILE_CLIENTMESSAGE
    = 1

LOGFILE_DATA


    public
    mixed
    LOGFILE_DATA
    = 4

LOGFILE_DEVINF


    public
    mixed
    LOGFILE_DEVINF
    = 3

LOGFILE_SERVERMESSAGE


    public
    mixed
    LOGFILE_SERVERMESSAGE
    = 2

MODE_CLIENT


    public
    mixed
    MODE_CLIENT
    = 2

MODE_SERVER

Backend modes.


    public
    mixed
    MODE_SERVER
    = 1

MODE_TEST


    public
    mixed
    MODE_TEST
    = 3

$state

The State object.


    public
        Horde_SyncMl_State
    $state

$_backendMode

The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.


    protected
        int
    $_backendMode

$_charset

The charset used in the SyncML messages.


    protected
        string
    $_charset

$_db

A PEAR MDB2 instance.


    protected
        MDB2
    $_db

$_debugDir

The directory where debugging information is stored.


    protected
        string
    $_debugDir

$_debugFiles

Whether to save SyncML messages in the debug directory.


    protected
        bool
    $_debugFiles

$_logLevel

The log level.


    protected
        string
    $_logLevel
     = 'INFO'

$_logtext

The concatenated log messages.


    protected
        string
    $_logtext
     = ''

$_syncDeviceID

The ID of the client device.


    protected
        string
    $_syncDeviceID

This is used for all data access as an ID to allow to distinguish between syncs with different devices. $this->_user together with $this->_syncDeviceID is used as an additional key for all persistence operations.

$_user

The current user.


    protected
        string
    $_user

__construct()

Constructor.


    public
                __construct(array<string|int, mixed> $params) : mixed

Parameters

$params : array<string|int, mixed>: A hash with parameters. In addition to those supported by the Horde_SyncMl_Backend class one more parameter is required for the database connection: 'dsn' => connection DSN.

Return values

mixed —

addEntry()

Adds an entry into the server database.


    public
                addEntry(string $databaseURI, string $content, string $contentType[, string $cuid = null ]) : array<string|int, mixed>

Parameters

$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$content : string: The actual data.
$contentType : string: MIME type of the content.
$cuid : string = null: Client ID of this entry.

Return values

array<string|int, mixed> —

PEAR_Error or suid (Horde guid) of new entry

addEntry_backend()

Adds an entry into the server database.


    public
                addEntry_backend(string $user, string $databaseURI, string $content, string $contentType) : array<string|int, mixed>

Parameters

$user : string: The username to use. Not strictly necessery to store this, but it helps for the test environment to clean up all entries for a test user.
$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$content : string: The actual data.
$contentType : string: MIME type of the content.

Return values

array<string|int, mixed> —

PEAR_Error or suid of new entry.

checkAuthentication()

Authenticates the user at the backend.


    public
                checkAuthentication(string &$username, string $credData, string $credFormat, string $credType) : bool|string

For some types of authentications (notably auth:basic) the username gets extracted from the authentication data and is then stored in username. For security reasons the caller must ensure that this is the username that is used for the session, overriding any username specified in .

Parameters

$username : string: Username as provided in the . May be overwritten by $credData.
$credData : string: Authentication data provided by in the .
$credFormat : string: Format of data as in the . Typically 'b64'.
$credType : string: Auth type as provided by in the . Typically 'syncml:auth-basic'.

Return values

bool|string —

The user name if authentication succeeded, false otherwise.

close()

Cleanup public function called after all message processing is finished.


    public
                close() : mixed

Allows for things like closing databases or flushing logs. When running in test mode, tearDown() must be called rather than close.

Return values

mixed —

createUidMap()

Creates a map entry to map between server and client IDs.


    public
                createUidMap(string $databaseURI, string $cuid, string $suid, int $timestamp) : mixed

If an entry already exists, it is overwritten.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$cuid : string: Client ID of the entry.
$suid : string: Server ID of the entry.
$timestamp : int: Optional timestamp. This can be used to 'tag' changes made in the backend during the sync process. This allows to identify these, and ensure that these changes are not replicated back to the client (and thus duplicated). See key concept "Changes and timestamps".

Return values

mixed —

deleteEntry()

Deletes an entry from the server database.


    public
                deleteEntry(string $databaseURI, string $cuid) : bool

Parameters

$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$cuid : string: Client ID of the entry.

Return values

bool —

True on success or false on failed (item not found).

deleteEntry_backend()

Deletes an entry from the server database.


    public
                deleteEntry_backend(string $user, string $databaseURI, string $suid) : bool

Parameters

$user : string: The username to use. Not strictly necessery to store this, but it helps for the test environment to clean up all entries for a test user.
$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$suid : string: Server ID of the entry.

Return values

bool —

True on success or false on failed (item not found).

eraseMap()

Erases all mapping entries for one combination of user, device ID.


    public
                eraseMap(string $databaseURI) : mixed

This is used during SlowSync so that we really sync everything properly and no old mapping entries remain.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values

mixed —

factory()

Attempts to return a concrete Horde_SyncMl_Backend instance based on $driver.


    public
                factory(string $driver[, array<string|int, mixed> $params = null ]) : Horde_SyncMl_Backend

Parameters

$driver : string: The type of concrete Backend subclass to return. The code is dynamically included from Backend/$driver.php if no path is given or directly with "include_once $driver . '.php'" if a path is included. So make sure this parameter is "safe" and not directly taken from web input. The class in the file must be named 'Horde_SyncMl_Backend_' . basename($driver) and extend Horde_SyncMl_Backend.
$params : array<string|int, mixed> = null: A hash containing any additional configuration or connection parameters a subclass might need.

Return values

Horde_SyncMl_Backend —

The newly created concrete Horde_SyncMl_Backend instance, or false on an error.

getCharset()

Returns the charset.


    public
                getCharset() : string

Return values

string —

The charset used when talking to the backend.

getCurrentTimeStamp()

Returns the current timestamp in the same format as used by getServerChanges().


    public
                getCurrentTimeStamp() : mixed

Backends can use their own way to represent timestamps, like unix epoch integers or UTC Datetime strings.

Return values

mixed —

A timestamp of the current time.

getParameter()

Extracts an HTTP GET like parameter from an URL.


    public
                getParameter(string $url, string $parameter[, string $default = null ]) : mixed

Example: getParameter('test?q=1', 'q') == 1

Parameters

$url : string: The complete URL.
$parameter : string: The parameter name to extract.
$default : string = null: A default value to return if none has been provided in the URL.

Return values

mixed —

getServerChanges()

Returns entries that have been modified in the server database.


    public
                getServerChanges(string $databaseURI, int $from_ts, int $to_ts, array<string|int, mixed> &$adds, array<string|int, mixed> &$mods, array<string|int, mixed> &$dels) : mixed

Parameters

$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$from_ts : int: Start timestamp.
$to_ts : int: Exclusive end timestamp. Not yet implemented.
$adds : array<string|int, mixed>: Output array: hash of adds suid => 0
$mods : array<string|int, mixed>: Output array: hash of modifications suid => cuid
$dels : array<string|int, mixed>: Output array: hash of deletions suid => cuid

Return values

mixed —

True on success or a PEAR_Error object.

getSyncDeviceID()

Returns the current device's ID.


    public
                getSyncDeviceID() : string

Return values

string —

The device ID.

getUser()

Returns the current user.


    public
                getUser() : string

Return values

string —

The current user.

isValidDatabaseURI()

Returns whether a database URI is valid to be synced with this backend.


    public
                isValidDatabaseURI(string $databaseURI) : bool

Parameters

$databaseURI : string: URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values

bool —

True if a valid URI.

logFile()

Logs data to a file in the debug directory.


    public
                logFile(int $type, string $content[, bool $wbxml = false ][, bool $sessionClose = false ]) : mixed

Parameters

$type : int: The data type. One of the Horde_SyncMl_Backend::LOGFILE_* constants.
$content : string: The data content.
$wbxml : bool = false: Whether the data is wbxml encoded.
$sessionClose : bool = false: Whether this is the last SyncML message in a session. Bump the file number.

Return values

mixed —

logMessage()

Logs a message in the backend.


    public
                logMessage(mixed $message[, int $priority = 'INFO' ]) : mixed

TODO: This should be done via Horde_Log or the equivalent.

Parameters

$message : mixed

Either a string or a PEAR_Error object.

$priority : int = 'INFO'

The priority of the message. One of:

EMERG
ALERT
CRIT
ERR
WARN
NOTICE
INFO
DEBUG

Return values

mixed —

normalize()

Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.


    public
                normalize(string $databaseURI) : string

Parameters

$databaseURI : string: URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values

string —

The normalized database name.

readSyncAnchors()

Reads the previously written sync anchors from the database.


    public
                readSyncAnchors(string $databaseURI) : mixed

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values

mixed —

Two-element array with client anchor and server anchor as stored in previous writeSyncAnchor() calls. False if no data found.

replaceEntry()

Replaces an entry in the server database.


    public
                replaceEntry(string $databaseURI, string $content, string $contentType, string $cuid) : string

Parameters

$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$content : string: The actual data.
$contentType : string: MIME type of the content.
$cuid : string: Client ID of this entry.

Return values

string —

PEAR_Error or server ID (Horde GUID) of modified entry.

replaceEntry_backend()

Replaces an entry in the server database.


    public
                replaceEntry_backend(string $user, string $databaseURI, string $content, string $contentType, string $suid) : string

Parameters

$user : string: The username to use. Not strictly necessery to store this but, it helps for the test environment to clean up all entries for a test user.
$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$content : string: The actual data.
$contentType : string: MIME type of the content.
$suid : string: Server ID of this entry.

Return values

string —

PEAR_Error or suid of modified entry.

retrieveEntry()

Retrieves an entry from the backend.


    public
                retrieveEntry(string $databaseURI, string $suid, string $contentType, array<string|int, mixed> $fields) : mixed

Parameters

$databaseURI : string: URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$suid : string: Server unique id of the entry: for horde this is the guid.
$contentType : string: Content-Type: the MIME type in which the public function should return the data.
$fields : array<string|int, mixed>: Hash of field names and Horde_SyncMl_Property properties with the requested fields.

Return values

mixed —

A string with the data entry or a PEAR_Error object.

sessionClose()

Closes the PHP session.


    public
                sessionClose() : mixed

Return values

mixed —

sessionStart()

Starts a PHP session.


    public
                sessionStart(string $syncDeviceID, mixed $sessionId[, int $backendMode = Horde_SyncMl_Backend::MODE_SERVER ]) : mixed

Parameters

$syncDeviceID : string: The device ID.
$sessionId : mixed
$backendMode : int = Horde_SyncMl_Backend::MODE_SERVER: The backend mode, one of the Horde_SyncMl_Backend::MODE_* constants.

Return values

mixed —

setCharset()

Sets the charset.


    public
                setCharset(string $charset) : mixed

All data passed to the backend uses this charset and data returned from the backend must use this charset, too.

Parameters

$charset : string: A valid charset.

Return values

mixed —

setupState()

Is called after the Horde_SyncMl_State object has been set up, either restored from the session, or freshly created.


    public
                setupState() : mixed

Return values

mixed —

setUser()

Sets the user used for this session.


    public
                setUser(string $user) : mixed

This method is called by SyncML right after sessionStart() when either authentication is accepted via checkAuthentication() or a valid user has been retrieved from the state. $this->_user together with $this->_syncDeviceID is used as an additional key for all persistence operations. This method may have to force a "login", when the backend doesn't keep auth state within a session or when in test mode.

Parameters

$user : string: A user name.

Return values

mixed —

testSetup()

Creates a clean test environment in the backend.


    public
                testSetup(string $user, string $pwd) : mixed

Ensures there's a user with the given credentials and an empty data store.

Parameters

$user : string: This user accout has to be created in the backend.
$pwd : string: The password for user $user.

Return values

mixed —

testStart()

Prepares the test start.


    public
                testStart(string $user) : mixed

Parameters

$user : string: This user accout has to be created in the backend.

Return values

mixed —

testTearDown()

Tears down the test environment after the test is run.


    public
                testTearDown() : mixed

Should remove the testuser created during testSetup and all its data.

Return values

mixed —

writeSyncAnchors()

Stores Sync anchors after a successful synchronization to allow two-way synchronization next time.


    public
                writeSyncAnchors(string $databaseURI, string $clientAnchorNext, string $serverAnchorNext) : mixed

The backend has to store the parameters in its persistence engine where user, syncDeviceID and database are the keys while client and server anchor ar the payload. See readSyncAnchors() for retrieval.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$clientAnchorNext : string: The client anchor as sent by the client.
$serverAnchorNext : string: The anchor as used internally by the server.

Return values

mixed —

_checkAuthentication()

Authenticates the user at the backend.


    protected
                _checkAuthentication(string $username, string $password) : bool|string

Parameters

$username : string: A user name.
$password : string: A password.

Return values

bool|string —

The user name if authentication succeeded, false otherwise.

_checkForError()

Checks if the parameter is a PEAR_Error object and if so logs the error.


    protected
                _checkForError(mixed $o) : mixed

Parameters

$o : mixed: An object or value to check.

Return values

mixed —

The error object if an error has been passed or false if no error has been passed.

_cleanUser()


    protected
                _cleanUser(mixed $user) : mixed

Parameters

$user : mixed

Return values

mixed —

_getChangeTS()

Returns a timestamp stored in the map for a given Server ID.


    protected
                _getChangeTS(string $databaseURI, string $suid) : mixed

The timestamp is the timestamp of the last change to this server ID that was done inside a sync session (as a result of a change received by the server). It's important to distinguish changes in the backend a) made by the user during normal operation and b) changes made by SyncML to reflect client updates. When the server is sending its changes it is only allowed to send type a). However the history feature in the backend my not know if a change is of type a) or type b). So the timestamp is used to differentiate between the two.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$suid : string: The server ID.

Return values

mixed —

The previously stored timestamp or false if no entry is found.

_getCuid()

Retrieves the Client ID for a given Server ID from the map.


    protected
                _getCuid(string $databaseURI, string $suid) : mixed

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$suid : string: The server ID.

Return values

mixed —

The client ID string or false if no entry is found.

_getSuid()

Retrieves the Server ID for a given Client ID from the map.


    protected
                _getSuid(string $databaseURI, string $cuid) : mixed

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$cuid : string: The client ID.

Return values

mixed —

The server ID string or false if no entry is found.

_removeFromSuidList()

Removes a suid from the suidlist.


    protected
                _removeFromSuidList(string $databaseURI, array<string|int, mixed> $suid) : mixed

Called by _trackDeletes() when updating the suidlist and deleteEntry() when removing an entry due to a client request.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$suid : array<string|int, mixed>: The suid to remove from the list.

Return values

mixed —

_setAuthenticated()

Sets a user as being authenticated at the backend.


    protected
                _setAuthenticated(string $username, string $credData) : string

Parameters

$username : string: A user name.
$credData : string: Authentication data provided by in the .

Return values

string —

The user name.

_trackDeletes()

Returns a list of item IDs that have been deleted since the last sync run and stores a complete list of IDs for next sync run.


    protected
                _trackDeletes(string $databaseURI, array<string|int, mixed> $currentSuids) : array<string|int, mixed>

Some backend datastores don't keep information about deleted entries. So we have to create a workaround that finds out what entries have been deleted since the last sync run. This method provides this functionality: it is called with a list of all IDs currently in the database. It then compares this list with its own previously stored list of IDs to identify those missing (and thus deleted). The passed list is then stored for the next invocation.

Parameters

$databaseURI : string: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$currentSuids : array<string|int, mixed>: Array of all SUIDs (primary keys) currently in the server datastore.

Return values

array<string|int, mixed> —

Array of all entries that have been deleted since the last call.

Horde_SyncMl_Backend_Sql extends Horde_SyncMl_Backend in package SyncMl

Table of Contents

Constants

LOGFILE_CLIENTMESSAGE

LOGFILE_DATA

LOGFILE_DEVINF

LOGFILE_SERVERMESSAGE

MODE_CLIENT

MODE_SERVER

MODE_TEST

Properties

$state

$_backendMode

$_charset

$_db

$_debugDir

Tags

$_debugFiles

Tags

$_logLevel

Tags

$_logtext

$_syncDeviceID

$_user

Methods

__construct()

Parameters

Return values

addEntry()

Parameters

Return values

addEntry_backend()

Parameters

Return values

checkAuthentication()

Parameters

Return values

close()

Return values

createUidMap()

Parameters

Return values

deleteEntry()

Parameters

Return values

deleteEntry_backend()

Parameters

Return values

eraseMap()

Parameters

Return values

factory()

Parameters

Return values

getCharset()

Return values

getCurrentTimeStamp()

Return values

getParameter()

Parameters

Tags

Return values

getServerChanges()

Parameters

Return values

getSyncDeviceID()

Return values

getUser()

Return values

isValidDatabaseURI()

Parameters

Return values

logFile()

Parameters

Return values

logMessage()

Parameters

Return values

normalize()

Parameters

Horde_SyncMl_Backend_Sql extends Horde_SyncMl_Backend
in package

SyncMl