tool_policy\api Class Reference

Provides the API of the policies plugin. More...

Static Public Member Functions
static	accept_policies ($policyversionid, $userid=null, $note=null, $lang=null)
	Mark the given policy versions as accepted by the user.
static	can_accept_policies (array $versionids, $userid=null, $throwexception=false)
	Check if given policies can be accepted by the current user (eventually on behalf of the other user)
static	can_decline_policies (array $versionids, $userid=null, $throwexception=false)
	Check if given policies can be declined by the current user (eventually on behalf of the other user)
static	can_delete_version ($version)
	Can the current version be deleted.
static	can_revoke_policies (array $versionids, $userid=null, $throwexception=false)
	Check if acceptances to given policies can be revoked by the current user (eventually on behalf of the other user)
static	can_user_view_policy_version ($policy, $behalfid=null, $userid=null)
	Can the user view the given policy version document?
static	count_total_users ()
	Returns total number of users who are expected to accept site policy.
static	create_acceptances_user_created (\core\event\user_created $event)
	Create user policy acceptances when the user is created.
static	decline_policies ($policyversionid, $userid=null, $note=null, $lang=null)
	Mark the given policy versions as declined by the user.
static	delete ($versionid)
	Delete the given version (if it is a draft).
static	fix_revision_values (array $versions)
	Make sure that each version has a unique revision value.
static	form_policydoc_add (stdClass $form)
	Save the data from the policydoc form as a new policy document.
static	form_policydoc_data (policy_version $version)
	Prepare data for the tool_policy::form::policydoc form.
static	form_policydoc_update_new (stdClass $form)
	Save the data from the policydoc form as a new policy document version.
static	form_policydoc_update_overwrite (stdClass $form)
	Save the data from the policydoc form, overwriting the existing policy document version.
static	get_agreement_optional ($versionid)
	Returns the value of the optional flag for the given policy version.
static	get_current_versions_ids ($audience=null)
	Checks if there are any current policies defined and returns their ids only.
static	get_policies_with_acceptances ($userid)
	Get the list of policies and versions that current user is able to see and the respective acceptance records for the selected user.
static	get_policy_version ($versionid, $policies=null)
	Load a particular policy document version.
static	get_user_acceptances ($userid, $versions=null)
	Returns list of acceptances for this user.
static	get_user_minors ($userid, array $extrafields=null)
	Return the user's minors - other users on which behalf we can accept policies.
static	get_user_version_acceptance ($userid, $versionid, $acceptances=null)
	Returns version acceptance for this user.
static	inactivate ($policyid)
	Inactivate the policy document - no version marked as current and the document does not apply.
static	is_user_version_accepted ($userid, $versionid, $acceptances=null)
	Did the user accept the given policy version?
static	list_current_versions ($audience=null)
	Return current (active) policies versions.
static	list_policies ($ids=null, $countacceptances=false)
	Returns a list of all policy documents and their versions.
static	make_current ($versionid)
	Make the given version the current active one.
static	move_down ($policyid)
	Move the given policy document down in the list.
static	move_up ($policyid)
	Move the given policy document up in the list.
static	policy_content_field_options ()
	Editor field options for the policy content text.
static	policy_summary_field_options ()
	Editor field options for the policy summary text.
static	revert_to_draft ($versionid)
	Create a new draft policy document from an archived version.
static	revoke_acceptance ($policyversionid, $userid, $note=null)
	May be used to revert accidentally granted acceptance for another user.
static	update_policyagreed ($user=null)
	Make sure that $user->policyagreed matches the agreement to the policies.

Static Protected Member Functions
static	distribute_policy_document_sortorder ()
	Re-sets the sortorder field of the policy documents to even values.
static	move_policy_document ($policyid, $step)
	Change the policy document's sortorder.
static	set_acceptances_status ($policyversionid, $userid=null, $note=null, $lang=null, $status=1)
	Mark the given policy versions as accepted or declined by the user.

Detailed Description

Provides the API of the policies plugin.

Copyright

2018 David Mudrak david.nosp@m.@moo.nosp@m.dle.c.nosp@m.om

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

accept_policies()

static tool_policy\api::accept_policies ( $policyversionid, $userid = null, $note = null, $lang = null )

static

Mark the given policy versions as accepted by the user.

Parameters

array | int	$policyversionid	Policy version id(s) to set acceptance status for.
int | null	$userid	Id of the user accepting the policy version, defaults to the current one.
string | null	$note	Note to be recorded.
string | null	$lang	Language in which the policy was shown, defaults to the current one.

can_accept_policies()

static tool_policy\api::can_accept_policies ( array $versionids, $userid = null, $throwexception = false )

static

Check if given policies can be accepted by the current user (eventually on behalf of the other user)

Currently, the version ids are not relevant and the check is based on permissions only. In the future, additional conditions can be added (such as policies applying to certain users only).

Parameters

array	$versionids	int[] List of policy version ids to check
int	$userid	Accepting policies on this user's behalf (defaults to accepting on self)
bool	$throwexception	Throw exception instead of returning false

Return values

bool

can_decline_policies()

static tool_policy\api::can_decline_policies ( array $versionids, $userid = null, $throwexception = false )

static

Check if given policies can be declined by the current user (eventually on behalf of the other user)

Only optional policies can be declined. Otherwise, the permissions are same as for accepting policies.

Parameters

array	$versionids	int[] List of policy version ids to check
int	$userid	Declining policies on this user's behalf (defaults to declining by self)
bool	$throwexception	Throw exception instead of returning false

Return values

bool

can_delete_version()

static tool_policy\api::can_delete_version ( $version )

static

Can the current version be deleted.

Parameters

stdClass

$version

object describing version, contains fields policyid, id, status, archived, audience, ...

can_revoke_policies()

static tool_policy\api::can_revoke_policies ( array $versionids, $userid = null, $throwexception = false )

static

Check if acceptances to given policies can be revoked by the current user (eventually on behalf of the other user)

Revoking optional policies is controlled by the same rules as declining them. Compulsory policies can be revoked only by users with the permission to accept policies on other's behalf. The reasoning behind this is to make sure the user communicates with the site's privacy officer and is well aware of all consequences of the decision (such as losing right to access the site).

Parameters

array	$versionids	int[] List of policy version ids to check
int	$userid	Revoking policies on this user's behalf (defaults to revoking by self)
bool	$throwexception	Throw exception instead of returning false

Return values

bool

can_user_view_policy_version()

static tool_policy\api::can_user_view_policy_version ( $policy, $behalfid = null, $userid = null )

static

Can the user view the given policy version document?

Parameters

stdClass	$policy	- exported tool_policy::policy_exporter instance
int	$behalfid	The id of user on whose behalf the user is viewing the policy
int	$userid	The user whom access is evaluated, defaults to the current one

Return values

bool

count_total_users()

static tool_policy\api::count_total_users ( )

static

Returns total number of users who are expected to accept site policy.

Return values

int|null

create_acceptances_user_created()

static tool_policy\api::create_acceptances_user_created ( \core\event\user_created $event )

static

Create user policy acceptances when the user is created.

Parameters

core\event\user_created

$event

decline_policies()

static tool_policy\api::decline_policies ( $policyversionid, $userid = null, $note = null, $lang = null )

static

Mark the given policy versions as declined by the user.

Parameters

array | int	$policyversionid	Policy version id(s) to set acceptance status for.
int | null	$userid	Id of the user accepting the policy version, defaults to the current one.
string | null	$note	Note to be recorded.
string | null	$lang	Language in which the policy was shown, defaults to the current one.

delete()

static tool_policy\api::delete ( $versionid )

static

Delete the given version (if it is a draft).

Also delete policy if this is the only version.

Parameters

int

$versionid

fix_revision_values()

static tool_policy\api::fix_revision_values ( array $versions )

static

Make sure that each version has a unique revision value.

Empty value are replaced with a timecreated date. Duplicates are suffixed with v1, v2, v3, ... etc.

Parameters

array

$versions

List of objects with id, timecreated and revision properties

form_policydoc_add()

static tool_policy\api::form_policydoc_add ( stdClass $form )

static

Save the data from the policydoc form as a new policy document.

Parameters

stdClass

$form

data submitted from the tool_policy::form::policydoc form.

Return values

tool_policy\policy_version

persistent

form_policydoc_data()

static tool_policy\api::form_policydoc_data ( policy_version $version )

static

Prepare data for the tool_policy::form::policydoc form.

Parameters

tool_policy\policy_version

$version

persistent representing the version.

Return values

stdClass

form data

form_policydoc_update_new()

static tool_policy\api::form_policydoc_update_new ( stdClass $form )

static

Save the data from the policydoc form as a new policy document version.

Parameters

stdClass

$form

data submitted from the tool_policy::form::policydoc form.

Return values

tool_policy\policy_version

persistent

form_policydoc_update_overwrite()

static tool_policy\api::form_policydoc_update_overwrite ( stdClass $form )

static

Save the data from the policydoc form, overwriting the existing policy document version.

Parameters

stdClass

$form

data submitted from the tool_policy::form::policydoc form.

Return values

tool_policy\policy_version

persistent

get_agreement_optional()

static tool_policy\api::get_agreement_optional ( $versionid )

static

Returns the value of the optional flag for the given policy version.

Optimised for being called multiple times by making use of a request cache. The cache is normally populated as a side effect of calling self::list_policies() and in most cases should be warm enough for hits.

Parameters

int

$versionid

Return values

int	policy_version\AGREEMENT_COMPULSORY | policy_version\AGREEMENT_OPTIONAL

get_current_versions_ids()

static tool_policy\api::get_current_versions_ids ( $audience = null )

static

Checks if there are any current policies defined and returns their ids only.

Parameters

array

$audience

If defined, filter against the given audience (AUDIENCE_ALL always included)

Return values

array

of version ids indexed by policies ids

get_policies_with_acceptances()

static tool_policy\api::get_policies_with_acceptances ( $userid )

static

Get the list of policies and versions that current user is able to see and the respective acceptance records for the selected user.

Parameters

int

$userid

Return values

array

array with the same structure that list_policies() returns with additional attribute acceptance for versions

get_policy_version()

static tool_policy\api::get_policy_version ( $versionid, $policies = null )

static

Load a particular policy document version.

Parameters

int	$versionid	ID of the policy document version.
array	$policies	cached result of self\list_policies() in case this function needs to be called in a loop

Return values

stdClass

- exported tool_policy::policy_exporter instance

get_user_acceptances()

static tool_policy\api::get_user_acceptances ( $userid, $versions = null )

static

Returns list of acceptances for this user.

Parameters

int	$userid	id of a user.
int | array	$versions	list of policy versions.

Return values

array

list of acceptances indexed by versionid.

get_user_minors()

static tool_policy\api::get_user_minors ( $userid, array $extrafields = null )

static

Return the user's minors - other users on which behalf we can accept policies.

Returned objects contain all the standard user name and picture fields as well as the context instanceid.

Parameters

int	$userid	The id if the user with parental responsibility
array	$extrafields	Extra fields to be included in result

Return values

array

of objects

get_user_version_acceptance()

static tool_policy\api::get_user_version_acceptance ( $userid, $versionid, $acceptances = null )

static

Returns version acceptance for this user.

Parameters

int	$userid	User identifier.
int	$versionid	Policy version identifier.
array | null	$acceptances	List of policy version acceptances indexed by versionid.

Return values

stdClass|null

Acceptance object if the user has ever accepted this version or null if not.

inactivate()

static tool_policy\api::inactivate ( $policyid )

static

Inactivate the policy document - no version marked as current and the document does not apply.

Parameters

int

$policyid

is_user_version_accepted()

static tool_policy\api::is_user_version_accepted ( $userid, $versionid, $acceptances = null )

static

Did the user accept the given policy version?

Parameters

int	$userid	User identifier.
int	$versionid	Policy version identifier.
array | null	$acceptances	Pre-loaded list of policy version acceptances indexed by versionid.

Return values

bool|null

True/false if this user accepted/declined the policy; null otherwise.

list_current_versions()

static tool_policy\api::list_current_versions ( $audience = null )

static

Return current (active) policies versions.

Parameters

array

$audience

If defined, filter against the given audience (AUDIENCE_ALL always included)

Return values

array

of stdClass - exported tool_policy::policy_version_exporter instances

list_policies()

static tool_policy\api::list_policies ( $ids = null, $countacceptances = false )

static

Returns a list of all policy documents and their versions.

Parameters

array | int | null	$ids	Load only the given policies, defaults to all.
int	$countacceptances	return number of user acceptances for each version

Return values

array

of stdClass - exported tool_policy::policy_exporter instances

make_current()

static tool_policy\api::make_current ( $versionid )

static

Make the given version the current active one.

Parameters

int

$versionid

move_down()

static tool_policy\api::move_down ( $policyid )

static

Move the given policy document down in the list.

Parameters

id

$policyid

move_policy_document()

static tool_policy\api::move_policy_document ( $policyid, $step )

staticprotected

Change the policy document's sortorder.

Parameters

int	$policyid
int	$step

move_up()

static tool_policy\api::move_up ( $policyid )

static

Move the given policy document up in the list.

Parameters

id

$policyid

policy_content_field_options()

static tool_policy\api::policy_content_field_options ( )

static

Editor field options for the policy content text.

Return values

array

policy_summary_field_options()

static tool_policy\api::policy_summary_field_options ( )

static

Editor field options for the policy summary text.

Return values

array

revert_to_draft()

static tool_policy\api::revert_to_draft ( $versionid )

static

Create a new draft policy document from an archived version.

Parameters

int

$versionid

Return values

tool_policy\policy_version

persistent

revoke_acceptance()

static tool_policy\api::revoke_acceptance ( $policyversionid, $userid, $note = null )

static

May be used to revert accidentally granted acceptance for another user.

Parameters

int	$policyversionid
int	$userid
null	$note

set_acceptances_status()

static tool_policy\api::set_acceptances_status ( $policyversionid, $userid = null, $note = null, $lang = null, $status = 1 )

staticprotected

Mark the given policy versions as accepted or declined by the user.

Parameters

array | int	$policyversionid	Policy version id(s) to set acceptance status for.
int | null	$userid	Id of the user accepting the policy version, defaults to the current one.
string | null	$note	Note to be recorded.
string | null	$lang	Language in which the policy was shown, defaults to the current one.
int	$status	The acceptance status, defaults to 1 = accepted

update_policyagreed()

static tool_policy\api::update_policyagreed ( $user = null )

static

Make sure that $user->policyagreed matches the agreement to the policies.

Parameters

int | stdClass | null

$user

user to check (null for current user)

---

The documentation for this class was generated from the following file:

• admin/tool/policy/classes/api.php