\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()
getAttributeValue()
beginFlushAttributes()
commitFlushAttributes()
flushAttributes()
addAttribute()
fetchRawDataByIndex()
isDataRestricted()
updateFreshness()
__destruct()
createTemporaryDirectory()
rrmdir()
downloadStats()
newIdP()
listIdentityProviders()
listFederationAdmins()
listExternalEntities()
determineIdPIdByRealm()
$identifier
$name
$tld
L_OK
L_REMARK
L_WARN
L_ERROR
UNKNOWN_IDP
AMBIGUOUS_IDP
retrieveOptionsFromDatabase()
$attributes
$databaseType
$entityOptionTable
$entityIdColumn
$databaseHandle
$loggerInstance
$languageInstance
N/A
getRelevantIdentifier()
downloadStatsCore()
findCandidates()
usortInstitution()
$frontendHandle
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

$attributes

$attributes : mixed|string|int

This variable gets initialised with the known IdP attributes in the constructor. It never gets updated until the object is destroyed. So if attributes change in the database, and IdP attributes are to be queried afterwards, the object needs to be re-instantiated to have current values in this variable.

Type

mixed|string|int — of entity's attributes

$databaseType

$databaseType : 

The database to query for attributes regarding this entity

Type

— DB type

$entityOptionTable

$entityOptionTable : 

This variable contains the name of the table that stores the entity's options

Type

— DB table name

$entityIdColumn

$entityIdColumn : 

column name to find entity in that table

Type

— DB column name of entity

$databaseHandle

$databaseHandle : \core\DBConnection

We need database access. Be sure to instantiate the singleton, and then use its instance (rather than always accessing everything statically)

Type

\core\DBConnection — the instance of the default database we talk to usually

$loggerInstance

$loggerInstance : \core\common\Logging

We occasionally log stuff (debug/audit). Have an initialised Logging instance nearby is sure helpful.

Type

\core\common\Logging —

$languageInstance

$languageInstance : \core\common\Language

access to language settings to be able to switch textDomain

Type

\core\common\Language —

$frontendHandle

$frontendHandle : \core\DBConnection

the handle to the FRONTEND database (only needed for some stats access)

Type

\core\DBConnection —

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)

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

getAttributeValue()

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

This is a helper fuction to retreave a value from two-dimmentional 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

\core\any —

value or NULL

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

flushAttributes()

flushAttributes() 

deletes all attributes of this entity from the database

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.

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

__destruct()

__destruct() 

destroys the entity.

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

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

downloadStats()

downloadStats(  format) : 

gets the download statistics for the federation

Parameters

format

either as an html table or XML

Returns

newIdP()

newIdP(  ownerId,   level,   mail) : 

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

retrieveOptionsFromDatabase()

retrieveOptionsFromDatabase(  query,   level) : mixed|string|int

retrieve attributes from a database. Only does SELECT queries.

Parameters

query

sub-classes set the query to execute to get to the options

level

the retrieved options get flagged with this "level" identifier

Returns

mixed|string|int —

the attributes in one array

getRelevantIdentifier()

getRelevantIdentifier() : string|int

How is the object identified in the database?

Throws

\Exception

Returns

string|int —

downloadStatsCore()

downloadStatsCore() : mixed|string|int

retrieve the statistics from the database in an internal array representation

Returns

mixed|string|int —

findCandidates()

findCandidates(\mysqli_result  dbResult,   country) : 

for a MySQL list of institutions, find an institution or find out that there is no single best match

Parameters

\mysqli_result dbResult
country

used to return the country of the inst, if can be found out

Returns

the identifier of the inst, or one of the special return values if unsuccessful

usortInstitution()

usortInstitution(mixed|string|int  a, mixed|string|int  b) : 

helper function to sort institutions by their name

Parameters

mixed|string|int a

an array with institution a's information

mixed|string|int b

an array with institution b's information

Returns

the comparison result