Documentation

Horde_Alarm
in package

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

Tags
author

Jan Schneider jan@horde.org

category

Horde

copyright

2007-2017 Horde LLC

license

http://www.horde.org/licenses/lgpl21 LGPL-2.1

Table of Contents

$_errors  : array<string|int, mixed>
A list of errors, exceptions etc. that occured during notify() calls.
$_handlers  : array<string|int, mixed>
All registered notification handlers.
$_handlersLoaded  : bool
Whether handler classes have been dynamically loaded already.
$_loader  : mixed
Alarm loader callback.
$_logger  : Horde_Log_Logger
Logger.
$_params  : array<string|int, mixed>
Hash containing connection parameters.
__construct()  : mixed
Constructor.
addHandler()  : mixed
Registers a notification handler.
delete()  : mixed
Deletes an alarm from the backend.
exists()  : bool
Returns whether an alarm with the given id exists already.
gc()  : mixed
Garbage collects old alarms in the backend.
get()  : array<string|int, mixed>
Returns an alarm hash from the backend.
getErrors()  : array<string|int, mixed>
Returns a list of errors, exceptions etc. that occured during notify() calls.
globalAlarms()  : array<string|int, mixed>
Returns a list of all global alarms from the backend.
handlers()  : array<string|int, mixed>
Returns a list of available notification handlers and parameters.
initialize()  : mixed
Attempts to initialize the backend.
internal()  : mixed
Updates internal alarm properties, i.e. properties not determined by the application setting the alarm.
isSnoozed()  : bool
Returns whether an alarm is snoozed.
listAlarms()  : array<string|int, mixed>
Returns a list of alarms from the backend.
notify()  : mixed
Notifies the user about any active alarms.
set()  : mixed
Stores an alarm hash in the backend.
snooze()  : mixed
Delays (snoozes) an alarm for a certain period.
_add()  : mixed
Adds an alarm hash to the backend.
_delete()  : mixed
Deletes an alarm from the backend.
_dismiss()  : mixed
Dismisses an alarm.
_exists()  : bool
Returns whether an alarm with the given id exists already.
_fromDriver()  : mixed
Converts a value from the driver's charset.
_gc()  : mixed
Garbage collects old alarms in the backend.
_get()  : array<string|int, mixed>
Returns an alarm hash from the backend.
_global()  : array<string|int, mixed>
Returns a list of all global alarms from the backend.
_isSnoozed()  : bool
Returns whether an alarm is snoozed.
_list()  : array<string|int, mixed>
Returns a list of alarms from the backend.
_snooze()  : mixed
Delays (snoozes) an alarm for a certain period.
_toDriver()  : mixed
Converts a value to the driver's charset.
_update()  : mixed
Updates an alarm hash in the backend.

Properties

$_errors

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

protected array<string|int, mixed> $_errors = array()

$_handlers

All registered notification handlers.

protected array<string|int, mixed> $_handlers = array()

$_handlersLoaded

Whether handler classes have been dynamically loaded already.

protected bool $_handlersLoaded = \false

$_loader

Alarm loader callback.

protected mixed $_loader

$_logger

Logger.

protected Horde_Log_Logger $_logger

$_params

Hash containing connection parameters.

protected array<string|int, mixed> $_params = array('ttl' => 300)

Methods

__construct()

Constructor.

public __construct([array<string|int, mixed> $params = array() ]) : mixed
Parameters
$params : array<string|int, mixed> = array()

Configuration parameters:

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

addHandler()

Registers a notification handler.

public addHandler(string $name, Horde_Alarm_Handler $handler) : mixed
Parameters
$name : string

A handler name.

$handler : Horde_Alarm_Handler

A notification handler.

Return values
mixed

delete()

Deletes an alarm from the backend.

public delete(string $id[, string $user = null ]) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string = null

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

Tags
throws
Horde_Alarm_Exception
Return values
mixed

exists()

Returns whether an alarm with the given id exists already.

public exists(string $id, string $user[, string $instanceid = null ]) : bool
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$instanceid : string = null

An optional instanceid to check for. @since 2.2.0

Return values
bool

True if the specified alarm exists.

gc()

Garbage collects old alarms in the backend.

public gc([bool $force = false ]) : mixed
Parameters
$force : bool = false

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

Tags
throws
Horde_Alarm_Exception
Return values
mixed

get()

Returns an alarm hash from the backend.

public get(string $id, string $user) : array<string|int, mixed>
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

Tags
throws
Horde_Alarm_Exception
Return values
array<string|int, mixed>

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)

getErrors()

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

public getErrors() : array<string|int, mixed>
Tags
since

Horde_Alarm 2.1.0

since

Horde_Alarm 2.2.9 the keys consist of the alarm id concatenated with a NUL character and an alarm method key.

Return values
array<string|int, mixed>

Error list.

globalAlarms()

Returns a list of all global alarms from the backend.

public globalAlarms() : array<string|int, mixed>
Tags
throws
Horde_Alarm_Exception
Return values
array<string|int, mixed>

A list of alarm hashes.

handlers()

Returns a list of available notification handlers and parameters.

public handlers() : array<string|int, mixed>

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.

Return values
array<string|int, mixed>

List of methods and parameters.

initialize()

Attempts to initialize the backend.

public abstract initialize() : mixed
Tags
throws
Horde_Alarm_Exception
Return values
mixed

internal()

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

public abstract internal(string $id, string $user, array<string|int, mixed> $internal) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$internal : array<string|int, mixed>

A hash with the internal data.

Tags
throws
Horde_Alarm_Exception
Return values
mixed

isSnoozed()

Returns whether an alarm is snoozed.

public isSnoozed(string $id, string $user[, Horde_Date $time = null ]) : bool
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$time : Horde_Date = null

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

Tags
throws
Horde_Alarm_Exception
Return values
bool

True if the alarm is snoozed.

listAlarms()

Returns a list of alarms from the backend.

public listAlarms([string $user = null ][, Horde_Date $time = null ][, bool $load = false ][, bool $preload = true ]) : array<string|int, mixed>
Parameters
$user : string = null

Return alarms for this user, all users if null, or global alarms if empty.

$time : Horde_Date = null

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

$load : bool = false

Update active alarms from all applications?

$preload : bool = true

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

Tags
throws
Horde_Alarm_Exception
Return values
array<string|int, mixed>

A list of alarm hashes.

notify()

Notifies the user about any active alarms.

public notify([string $user = null ][, bool $load = true ][, bool $preload = true ][, array<string|int, mixed> $exclude = array() ]) : mixed
Parameters
$user : string = null

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

$load : bool = true

Update active alarms from all applications?

$preload : bool = true

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

$exclude : array<string|int, mixed> = array()

Don't notify with these methods.

Tags
throws
Horde_Alarm_Exception

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

Return values
mixed

set()

Stores an alarm hash in the backend.

public set(array<string|int, mixed> $alarm[, bool $keep = false ]) : mixed

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

Parameters
$alarm : array<string|int, mixed>

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

$keep : bool = false

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.

Tags
throws
Horde_Alarm_Exception
Return values
mixed

snooze()

Delays (snoozes) an alarm for a certain period.

public snooze(string $id, string $user, int $minutes) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string

The notified user.

$minutes : int

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

Tags
throws
Horde_Alarm_Exception
Return values
mixed

_add()

Adds an alarm hash to the backend.

protected abstract _add(array<string|int, mixed> $alarm) : mixed
Parameters
$alarm : array<string|int, mixed>

An alarm hash.

Tags
throws
Horde_Alarm_Exception
Return values
mixed

_delete()

Deletes an alarm from the backend.

protected abstract _delete(string $id[, string $user = null ]) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string = null

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

Tags
throws
Horde_Alarm_Exception
Return values
mixed

_dismiss()

Dismisses an alarm.

protected abstract _dismiss(string $id, string $user) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

Tags
throws
Horde_Alarm_Exception
Return values
mixed

_exists()

Returns whether an alarm with the given id exists already.

protected abstract _exists(string $id, string $user[, string $instanceid = null ]) : bool
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$instanceid : string = null

An optional instanceid to match.

Tags
throws
Horde_Alarm_Exception
Return values
bool

True if the specified alarm exists.

_fromDriver()

Converts a value from the driver's charset.

protected abstract _fromDriver(mixed $value) : mixed
Parameters
$value : mixed

Value to convert.

Return values
mixed

Converted value.

_gc()

Garbage collects old alarms in the backend.

protected abstract _gc() : mixed
Tags
throws
Horde_Alarm_Exception
Return values
mixed

_get()

Returns an alarm hash from the backend.

protected abstract _get(string $id, string $user) : array<string|int, mixed>
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

Tags
throws
Horde_Alarm_Exception
Return values
array<string|int, mixed>

An alarm hash.

_global()

Returns a list of all global alarms from the backend.

protected abstract _global() : array<string|int, mixed>
Return values
array<string|int, mixed>

A list of alarm hashes.

_isSnoozed()

Returns whether an alarm is snoozed.

protected abstract _isSnoozed(string $id, string $user, Horde_Date $time) : bool
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$time : Horde_Date

The time when the alarm may be snoozed.

Tags
throws
Horde_Alarm_Exception
Return values
bool

True if the alarm is snoozed.

_list()

Returns a list of alarms from the backend.

protected abstract _list(string $user, Horde_Date $time) : array<string|int, mixed>
Parameters
$user : string

Return alarms for this user, all users if null, or global alarms if empty.

$time : Horde_Date

The time when the alarms should be active.

Tags
throws
Horde_Alarm_Exception
Return values
array<string|int, mixed>

A list of alarm hashes.

_snooze()

Delays (snoozes) an alarm for a certain period.

protected abstract _snooze(string $id, string $user, Horde_Date $snooze) : mixed
Parameters
$id : string

The alarm's unique id.

$user : string

The alarm's user

$snooze : Horde_Date

The snooze time.

Tags
throws
Horde_Alarm_Exception
Return values
mixed

_toDriver()

Converts a value to the driver's charset.

protected abstract _toDriver(mixed $value) : mixed
Parameters
$value : mixed

Value to convert.

Return values
mixed

Converted value.

_update()

Updates an alarm hash in the backend.

protected abstract _update(array<string|int, mixed> $alarm[, bool $keepsnooze = false ]) : mixed
Parameters
$alarm : array<string|int, mixed>

An alarm hash.

$keepsnooze : bool = false

Whether to keep the snooze value unchanged.

Tags
throws
Horde_Alarm_Exception
Return values
mixed

Search results