Constants

L_OK

L_OK = 0

L_REMARK

L_REMARK = 4

L_WARN

L_WARN = 32

L_ERROR

L_ERROR = 256

TOKENSTATUS_OK_NEW

TOKENSTATUS_OK_NEW = 1

TOKENSTATUS_OK_EXISTING

TOKENSTATUS_OK_EXISTING = 2

TOKENSTATUS_FAIL_ALREADYCONSUMED

TOKENSTATUS_FAIL_ALREADYCONSUMED = -1

TOKENSTATUS_FAIL_EXPIRED

TOKENSTATUS_FAIL_EXPIRED = -2

TOKENSTATUS_FAIL_NONEXISTING

TOKENSTATUS_FAIL_NONEXISTING = -3

Methods

__construct()

__construct() : 

Class constructor. Nothing special to be done when constructing.

Logs the start of lifetime of the entity to the debug log on levels 3 and higher.

Returns

__destruct()

__destruct() : 

destroys the entity.

Logs the end of lifetime of the entity to the debug log on level 5.

Returns

getAttributeValue()

getAttributeValue(mixed|string|int  attributeArray, string|int  index1, string|int  index2) : 

This is a helper fuction to retrieve a value from two-dimensional arrays The function tests if the value for the first indes is defined and then the same with the second and finally returns the value if something on the way is not defined, NULL is returned

Parameters

mixed|string|int attributeArray
string|int index1
string|int index2

Returns

createTemporaryDirectory()

createTemporaryDirectory(  purpose = installer,   failIsFatal = 1) : mixed|string|int

create a temporary directory and return the location

Parameters

purpose

one of 'installer', 'logo', 'test' defined the purpose of the directory

failIsFatal

decides if a creation failure should cause an error; defaults to true

Returns

mixed|string|int —

the tuple of: base path, absolute path for directory, directory name

rrmdir()

rrmdir(  dir) : 

this direcory delete function has been copied from PHP documentation

Parameters

dir

name of the directory to delete

Returns

uuid()

uuid(  prefix,  deterministicSource = NULL) : 

generates a UUID, for the devices which identify file contents by UUID

Parameters

prefix

an extra prefix to set before the UUID

deterministicSource

Returns

UUID (possibly prefixed)

randomString()

randomString(  length,   keyspace = 23456789abcdefghijkmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ) : 

produces a random string

Parameters

length

the length of the string to produce

keyspace

the pool of characters to use for producing the string

Throws

\Exception

Returns

checkTokenValidity()

checkTokenValidity(  token) : 

Checks if a given invitation token exists and is valid in the invitations database returns a string with the following values:

OK-NEW valid token exists, and is not attached to an existing institution. When consuming the token, a new inst will be created OK-EXISTING valid token exists, and is attached to an existing institution. When consuming the token, user will be added as an admin FAIL-NONEXISTINGTOKEN this token does not exist at all in the database FAIL-ALREADYCONSUMED the token exists, but has been used before FAIL-EXPIRED the token exists, but has expired

Parameters

token

Returns

createIdPFromToken()

createIdPFromToken(  token,   owner) : \core\IdP

This function creates a new IdP in the database based on a valid invitation token - or adds a new administrator to an existing one. The institution is created for the logged-in user (second argument) who presents the token (first argument). The tokens are created via createToken().

Parameters

token

The invitation token (must exist in the database and be valid).

owner

Persistent User ID who becomes the administrator of the institution

Returns

\core\IdP —

addAdminToIdp()

addAdminToIdp(\core\IdP  idp,   user) : 

Adds a new administrator to an existing IdP

Parameters

\core\IdP idp

institution to which the admin is to be added.

user

persistent user ID that is to be added as an admin.

Returns

This function always returns TRUE.

removeAdminFromIdP()

removeAdminFromIdP(\core\IdP  idp,   user) : 

Deletes an administrator from the IdP. If the IdP and user combination doesn't match, nothing happens.

Parameters

\core\IdP idp

institution from which the admin is to be deleted.

user

persistent user ID that is to be deleted as an admin.

Returns

This function always returns TRUE.

invalidateToken()

invalidateToken(  token) : 

Invalidates a token so that it can't be used any more. Tokens automatically expire after 24h, but can be invalidated earlier, e.g. after having been used to create an institution. If the token doesn't exist in the DB or is already invalidated, nothing happens.

Parameters

token

the token to invalidate

Returns

This function always returns TRUE.

createToken()

createToken(  isByFedadmin,   for,   instIdentifier,   externalId,   country) : 

Creates a new invitation token. The token's main purpose is to be sent out by mail. The function either can generate a token for a new administrator of an existing institution, or for a new institution. In the latter case, the institution only actually gets created in the DB if the token is actually consumed via createIdPFromToken().

Parameters

isByFedadmin

is the invitation token created for a federation admin (TRUE) or from an existing inst admin (FALSE)

for

identifier (typically email address) for which the invitation is created

instIdentifier

either an instance of the IdP class (for existing institutions to invite new admins) or a string (new institution - this is the inst name then)

externalId

if the IdP to be created is related to an external DB entity, this parameter contains that ID

country

if the institution is new (i.e. $inst is a string) this parameter needs to specify the federation of the new inst

Returns

The function returns either the token (as string) or FALSE if something went wrong

listPendingInvitations()

listPendingInvitations(  idpIdentifier) : mixed|string|int

Retrieves all pending invitations for an institution or for a federation.

Parameters

idpIdentifier

the identifier of the institution. If not set, returns invitations for not-yet-created insts

Returns

mixed|string|int —

if idp_identifier is set: an array of strings (mail addresses); otherwise an array of tuples (country;name;mail)

listRecentlyExpiredInvitations()

listRecentlyExpiredInvitations() : mixed|string|int

Retrieves all invitations which have expired in the last hour.

Returns

mixed|string|int —

of expired invitations

listInstitutionsByAdmin()

listInstitutionsByAdmin(  userid) : mixed|string|int

For a given persistent user identifier, returns an array of institution identifiers (not the actual objects!) for which this user is the/a administrator.

Parameters

userid

persistent user identifier

Returns

mixed|string|int —

array of institution IDs