\coreFederation

This class represents an consortium federation.

It is semantically a country(!). Do not confuse this with a TLD; a federation may span more than one TLD, and a TLD may be distributed across multiple federations.

Example: a federation "fr" => "France" may also contain other TLDs which belong to France in spite of their different TLD Example 2: Domains ending in .edu are present in multiple different federations

Summary

Methods
Properties
Constants
__construct()
getAttributes()
beginFlushAttributes()
commitFlushAttributes()
flushAttributes()
addAttribute()
fetchRawDataByIndex()
isDataRestricted()
updateFreshness()
__destruct()
getAttributeValue()
createTemporaryDirectory()
rrmdir()
uuid()
randomString()
downloadStats()
newIdP()
listIdentityProviders()
listFederationAdmins()
listExternalEntities()
determineIdPIdByRealm()
$identifier
$name
$tld
L_OK
L_REMARK
L_WARN
L_ERROR
UNKNOWN_IDP
AMBIGUOUS_IDP
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

L_OK

L_OK = 0

L_REMARK

L_REMARK = 4

L_WARN

L_WARN = 32

L_ERROR

L_ERROR = 256

UNKNOWN_IDP

UNKNOWN_IDP = -1

AMBIGUOUS_IDP

AMBIGUOUS_IDP = -2

Properties

$identifier

$identifier : 

the unique identifier of this entity instance refers to the integer row name in the DB -> int; Federation has no own DB, so the identifier is of no use there -> use Fedearation->$tld

Type

— identifier of the entity instance

$name

$name : 

the name of the entity in the current locale

Type

$tld

$tld : 

the top-level domain of the Federation

Type

Methods

__construct()

__construct(  fedname) : 

Constructs a Federation object.

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

Parameters

fedname
  • textual representation of the Federation object Example: "lu" (for Luxembourg)

Returns

getAttributes()

getAttributes(  optionName = NULL) : mixed|string|int

This function retrieves the entity's attributes.

If called with the optional parameter, only attribute values for the attribute name in $optionName are retrieved; otherwise, all attributes are retrieved. The retrieval is in-memory from the internal attributes class member - no DB callback, so changes in the database during the class instance lifetime are not considered.

Parameters

optionName

optionally, the name of the attribute that is to be retrieved

Returns

mixed|string|int —

of arrays of attributes which were set for this IdP

beginFlushAttributes()

beginFlushAttributes() : mixed|string|int

deletes all attributes in this profile except the _file ones, these are reported as array

Returns

mixed|string|int —

list of row id's of file-based attributes which weren't deleted

commitFlushAttributes()

commitFlushAttributes(mixed|string|int  tobedeleted) : 

after a beginFlushAttributes, deletes all attributes which are in the tobedeleted array.

Parameters

mixed|string|int tobedeleted

array of database rows which are to be deleted

Returns

flushAttributes()

flushAttributes() : 

deletes all attributes of this entity from the database

Returns

addAttribute()

addAttribute(  attrName,   attrLang,   attrValue) : 

Adds an attribute for the entity instance into the database. Multiple instances of the same attribute are supported.

Parameters

attrName

Name of the attribute. This must be a well-known value from the profile_option_dict table in the DB.

attrLang

language of the attribute. Can be NULL.

attrValue

Value of the attribute. Can be anything; will be stored in the DB as-is.

Returns

fetchRawDataByIndex()

fetchRawDataByIndex(  table,   row) : string|bool

Retrieves data from the underlying tables, for situations where instantiating the IdP or Profile object is inappropriate

Parameters

table

institution_option or profile_option

row

rowindex

Returns

string|bool —

the data, or FALSE if something went wrong

isDataRestricted()

isDataRestricted(  table,   row) : 

Checks if a raw data pointer is public data (return value FALSE) or if yes who the authorised admins to view it are (return array of user IDs)

Parameters

table

which database table is this about

row

row index of the table

Returns

FALSE if the data is public, an array of owners of the data if it is NOT public

updateFreshness()

updateFreshness() : 

NOOP on Federations, but have to override the abstract parent method

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

downloadStats()

downloadStats(  format) : string|array

gets the download statistics for the federation

Parameters

format

either as an html table or XML or JSON

Returns

string|array —

newIdP()

newIdP(  ownerId,   level,   mail = NULL) : 

Creates a new IdP inside the federation.

Parameters

ownerId

Persistent identifier of the user for whom this IdP is created (first administrator)

level

Privilege level of the first administrator (was he blessed by a federation admin or a peer?)

mail

e-mail address with which the user was invited to administer (useful for later user identification if the user chooses a "funny" real name)

Returns

identifier of the new IdP

listIdentityProviders()

listIdentityProviders(  activeOnly) : mixed|string|int

Lists all Identity Providers in this federation

Parameters

activeOnly

if set to non-zero will list only those institutions which have some valid profiles defined.

Returns

mixed|string|int —

(Array of IdP instances)

listFederationAdmins()

listFederationAdmins() : mixed|string|int

returns an array with information about the authorised administrators of the federation

Returns

mixed|string|int —

listExternalEntities()

listExternalEntities(  unmappedOnly) : mixed|string|int

cross-checks in the EXTERNAL customer DB which institutions exist there for the federations

Parameters

unmappedOnly

if set to TRUE, only returns those which do not have a known mapping to our internally known institutions

Returns

mixed|string|int —

determineIdPIdByRealm()

determineIdPIdByRealm(  realm) : mixed|string|int

If we are running diagnostics, our input from the user is the realm. We need to find out which IdP this realm belongs to.

Parameters

realm

the realm to search for

Returns

mixed|string|int —

an array with two entries, CAT ID and DB ID, with either the respective ID of the IdP in the system, or UNKNOWN_IDP or AMBIGUOUS_IDP