API Documentation
\

\Horde_Alarm

The Horde_Alarm class provides an interface to deal with reminders, alarms and notifications through a standardized API.

Summary

Methods
Properties
Constants
__construct()
listAlarms()
globalAlarms()
get()
set()
internal()
exists()
snooze()
isSnoozed()
delete()
notify()
addHandler()
handlers()
getErrors()
gc()
initialize()
No public properties found
No constants found
_list()
_global()
_get()
_add()
_update()
_exists()
_snooze()
_isSnoozed()
_dismiss()
_delete()
_gc()
_fromDriver()
_toDriver()
$_logger
$_loader
$_params
$_handlers
$_handlersLoaded
$_errors
N/A
No private methods found
No private properties found
N/A

Properties

$_logger

$_logger : \Horde_Log_Logger

Logger.

Type

\Horde_Log_Logger

$_loader

$_loader : mixed

Alarm loader callback.

Type

mixed

$_params

$_params : array

Hash containing connection parameters.

Type

array

$_handlers

$_handlers : array

All registered notification handlers.

Type

array

$_handlersLoaded

$_handlersLoaded : boolean

Whether handler classes have been dynamically loaded already.

Type

boolean

$_errors

$_errors : array

A list of errors, exceptions etc. that occured during notify() calls.

Type

array

Methods

__construct()

__construct(array  $params = array())

Constructor.

Parameters

array $params

Configuration parameters:

'logger' - (Horde_Log_Logger) A logger instance.
'ttl' - (integer) Time to live value, in seconds.

listAlarms()

listAlarms(string  $user = null, \Horde_Date  $time = null, boolean  $load = false, boolean  $preload = true) : array

Returns a list of alarms from the backend.

Parameters

string $user

Return alarms for this user, all users if null, or global alarms if empty.
\Horde_Date $time

The time when the alarms should be active. Defaults to now.
boolean $load

Update active alarms from all applications?
boolean $preload

Preload alarms that go off within the next ttl time span?

Throws

\Horde_Alarm_Exception

Returns

array —

A list of alarm hashes.

globalAlarms()

globalAlarms() : array

Returns a list of all global alarms from the backend.

Throws

\Horde_Alarm_Exception

Returns

array —

A list of alarm hashes.

get()

get(string  $id, string  $user) : array

Returns an alarm hash from the backend.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user

Throws

\Horde_Alarm_Exception

Returns

array —

An alarm hash. Contains the following:

id: Unique alarm id.
user: The alarm's user. Empty if a global alarm.
start: The alarm start as a Horde_Date.
end: The alarm end as a Horde_Date.
methods: The notification methods for this alarm.
params: The paramters for the notification methods.
title: The alarm title.
text: An optional alarm description.
snooze: The snooze time (next time) of the alarm as a Horde_Date.
internal: Holds internally used data.
instanceid: Holds an instance identifier for recurring alarms.
            (@since 2.2.0)

set()

set(array  $alarm, boolean  $keep = false)

Stores an alarm hash in the backend.

The alarm will be added if it doesn't exist, and updated otherwise.

Parameters

array $alarm

An alarm hash. See self::get() for format.
boolean $keep

Whether to keep the snooze value and notification status unchanged. If true, the alarm will get "un-snoozed", and notifications (like mails) are sent again.

Throws

\Horde_Alarm_Exception

internal()

internal(string  $id, string  $user, array  $internal)

Updates internal alarm properties, i.e. properties not determined by the application setting the alarm.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
array $internal

A hash with the internal data.

Throws

\Horde_Alarm_Exception

exists()

exists(string  $id, string  $user, string  $instanceid = null) : boolean

Returns whether an alarm with the given id exists already.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
string $instanceid

An optional instanceid to check for. @since 2.2.0

Returns

boolean —

True if the specified alarm exists.

snooze()

snooze(string  $id, string  $user, integer  $minutes)

Delays (snoozes) an alarm for a certain period.

Parameters

string $id

The alarm's unique id.
string $user

The notified user.
integer $minutes

The delay in minutes. A negative value dismisses the alarm completely.

Throws

\Horde_Alarm_Exception

isSnoozed()

isSnoozed(string  $id, string  $user, \Horde_Date  $time = null) : boolean

Returns whether an alarm is snoozed.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
\Horde_Date $time

The time when the alarm may be snoozed. Defaults to now.

Throws

\Horde_Alarm_Exception

Returns

boolean —

True if the alarm is snoozed.

delete()

delete(string  $id, string  $user = null)

Deletes an alarm from the backend.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user. All users' alarms if null.

Throws

\Horde_Alarm_Exception

notify()

notify(string  $user = null, boolean  $load = true, boolean  $preload = true, array  $exclude = array())

Notifies the user about any active alarms.

Parameters

string $user

Notify this user, all users if null, or guest users if empty.
boolean $load

Update active alarms from all applications?
boolean $preload

Preload alarms that go off within the next ttl time span?
array $exclude

Don't notify with these methods.

Throws

\Horde_Alarm_Exception

if loading of alarms fails, but not if notifying of individual alarms fails.

addHandler()

addHandler(string  $name, \Horde_Alarm_Handler  $handler)

Registers a notification handler.

Parameters

string $name

A handler name.
\Horde_Alarm_Handler $handler

A notification handler.

handlers()

handlers() : array

Returns a list of available notification handlers and parameters.

The returned list is a hash with method names as the keys and optionally associated parameters as values. The parameters are hashes again with parameter names as keys and parameter information as values. The parameter information is hash with the following keys: 'desc' contains a parameter description; 'required' specifies whether this parameter is required.

Returns

array —

List of methods and parameters.

getErrors()

getErrors() : array

Returns a list of errors, exceptions etc. that occured during notify() calls.

Returns

array —

Error list.

gc()

gc(boolean  $force = false)

Garbage collects old alarms in the backend.

Parameters

boolean $force

Force garbace collection? If false, GC happens with a 1% chance.

Throws

\Horde_Alarm_Exception

initialize()

initialize()

Attempts to initialize the backend.

Throws

\Horde_Alarm_Exception

_list()

_list(string  $user, \Horde_Date  $time) : array

Returns a list of alarms from the backend.

Parameters

string $user

Return alarms for this user, all users if null, or global alarms if empty.
\Horde_Date $time

The time when the alarms should be active.

Throws

\Horde_Alarm_Exception

Returns

array —

A list of alarm hashes.

_global()

_global() : array

Returns a list of all global alarms from the backend.

Returns

array —

A list of alarm hashes.

_get()

_get(string  $id, string  $user) : array

Returns an alarm hash from the backend.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user

Throws

\Horde_Alarm_Exception

Returns

array —

An alarm hash.

_add()

_add(array  $alarm)

Adds an alarm hash to the backend.

Parameters

array $alarm

An alarm hash.

Throws

\Horde_Alarm_Exception

_update()

_update(array  $alarm, boolean  $keepsnooze = false)

Updates an alarm hash in the backend.

Parameters

array $alarm

An alarm hash.
boolean $keepsnooze

Whether to keep the snooze value unchanged.

Throws

\Horde_Alarm_Exception

_exists()

_exists(string  $id, string  $user, string  $instanceid = null) : boolean

Returns whether an alarm with the given id exists already.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
string $instanceid

An optional instanceid to match.

Throws

\Horde_Alarm_Exception

Returns

boolean —

True if the specified alarm exists.

_snooze()

_snooze(string  $id, string  $user, \Horde_Date  $snooze)

Delays (snoozes) an alarm for a certain period.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
\Horde_Date $snooze

The snooze time.

Throws

\Horde_Alarm_Exception

_isSnoozed()

_isSnoozed(string  $id, string  $user, \Horde_Date  $time) : boolean

Returns whether an alarm is snoozed.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user
\Horde_Date $time

The time when the alarm may be snoozed.

Throws

\Horde_Alarm_Exception

Returns

boolean —

True if the alarm is snoozed.

_dismiss()

_dismiss(string  $id, string  $user)

Dismisses an alarm.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user

Throws

\Horde_Alarm_Exception

_delete()

_delete(string  $id, string  $user = null)

Deletes an alarm from the backend.

Parameters

string $id

The alarm's unique id.
string $user

The alarm's user. All users' alarms if null.

Throws

\Horde_Alarm_Exception

_gc()

_gc()

Garbage collects old alarms in the backend.

Throws

\Horde_Alarm_Exception

_fromDriver()

_fromDriver(mixed  $value) : mixed

Converts a value from the driver's charset.

Parameters

mixed $value

Value to convert.

Returns

mixed —

Converted value.

_toDriver()

_toDriver(mixed  $value) : mixed

Converts a value to the driver's charset.

Parameters

mixed $value

Value to convert.

Returns

mixed —

Converted value.