Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.

Class: api  - X-Ref

Provides the API of the policies plugin.

list_current_versions($audience = null)   X-Ref
Return current (active) policies versions.

param: array $audience If defined, filter against the given audience (AUDIENCE_ALL always included)
return: array of stdClass - exported {@link tool_policy\policy_version_exporter} instances

get_current_versions_ids($audience = null)   X-Ref
Checks if there are any current policies defined and returns their ids only

param: array $audience If defined, filter against the given audience (AUDIENCE_ALL always included)
return: array of version ids indexed by policies ids

list_policies($ids = null, $countacceptances = false)   X-Ref
Returns a list of all policy documents and their versions.

param: array|int|null $ids Load only the given policies, defaults to all.
param: int $countacceptances return number of user acceptances for each version
return: array of stdClass - exported {@link tool_policy\policy_exporter} instances

count_total_users()   X-Ref
Returns total number of users who are expected to accept site policy

return: int|null

get_policy_version($versionid, $policies = null)   X-Ref
Load a particular policy document version.

param: int $versionid ID of the policy document version.
param: array $policies cached result of self::list_policies() in case this function needs to be called in a loop
return: stdClass - exported {@link tool_policy\policy_exporter} instance

fix_revision_values(array $versions)   X-Ref
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.

param: array $versions List of objects with id, timecreated and revision properties

can_user_view_policy_version($policy, $behalfid = null, $userid = null)   X-Ref
Can the user view the given policy version document?

param: stdClass $policy - exported {@link tool_policy\policy_exporter} instance
param: int $behalfid The id of user on whose behalf the user is viewing the policy
param: int $userid The user whom access is evaluated, defaults to the current one
return: bool

get_user_minors($userid, array $extrafields = null)   X-Ref
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.

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

form_policydoc_data(policy_version $version)   X-Ref
Prepare data for the {@link \tool_policy\form\policydoc} form.

param: \tool_policy\policy_version $version persistent representing the version.
return: stdClass form data

form_policydoc_add(stdClass $form)   X-Ref
Save the data from the policydoc form as a new policy document.

param: stdClass $form data submitted from the {@link \tool_policy\form\policydoc} form.
return: \tool_policy\policy_version persistent

form_policydoc_update_new(stdClass $form)   X-Ref
Save the data from the policydoc form as a new policy document version.

param: stdClass $form data submitted from the {@link \tool_policy\form\policydoc} form.
return: \tool_policy\policy_version persistent

form_policydoc_update_overwrite(stdClass $form)   X-Ref
Save the data from the policydoc form, overwriting the existing policy document version.

param: stdClass $form data submitted from the {@link \tool_policy\form\policydoc} form.
return: \tool_policy\policy_version persistent

make_current($versionid)   X-Ref
Make the given version the current active one.

param: int $versionid

inactivate($policyid)   X-Ref
Inactivate the policy document - no version marked as current and the document does not apply.

param: int $policyid

revert_to_draft($versionid)   X-Ref
Create a new draft policy document from an archived version.

param: int $versionid
return: \tool_policy\policy_version persistent

can_delete_version($version)   X-Ref
Can the current version be deleted

param: stdClass $version object describing version, contains fields policyid, id, status, archived, audience, ...

delete($versionid)   X-Ref
Delete the given version (if it is a draft). Also delete policy if this is the only version.

param: int $versionid

policy_summary_field_options()   X-Ref
Editor field options for the policy summary text.

return: array

policy_content_field_options()   X-Ref
Editor field options for the policy content text.

return: array

distribute_policy_document_sortorder()   X-Ref
Re-sets the sortorder field of the policy documents to even values.


move_policy_document($policyid, $step)   X-Ref
Change the policy document's sortorder.

param: int $policyid
param: int $step

move_up($policyid)   X-Ref
Move the given policy document up in the list.

param: id $policyid

move_down($policyid)   X-Ref
Move the given policy document down in the list.

param: id $policyid

get_user_acceptances($userid, $versions = null)   X-Ref
Returns list of acceptances for this user.

param: int $userid id of a user.
param: int|array $versions list of policy versions.
return: array list of acceptances indexed by versionid.

get_user_version_acceptance($userid, $versionid, $acceptances = null)   X-Ref
Returns version acceptance for this user.

param: int $userid User identifier.
param: int $versionid Policy version identifier.
param: array|null $acceptances List of policy version acceptances indexed by versionid.
return: stdClass|null Acceptance object if the user has ever accepted this version or null if not.

is_user_version_accepted($userid, $versionid, $acceptances = null)   X-Ref
Did the user accept the given policy version?

param: int $userid User identifier.
param: int $versionid Policy version identifier.
param: array|null $acceptances Pre-loaded list of policy version acceptances indexed by versionid.
return: bool|null True/false if this user accepted/declined the policy; null otherwise.

get_policies_with_acceptances($userid)   X-Ref
Get the list of policies and versions that current user is able to see and the respective acceptance records for
the selected user.

param: int $userid
return: array array with the same structure that list_policies() returns with additional attribute acceptance for versions

can_accept_policies(array $versionids, $userid = null, $throwexception = false)   X-Ref
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).

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

can_decline_policies(array $versionids, $userid = null, $throwexception = false)   X-Ref
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.

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

can_revoke_policies(array $versionids, $userid = null, $throwexception = false)   X-Ref
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).

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

accept_policies($policyversionid, $userid = null, $note = null, $lang = null)   X-Ref
Mark the given policy versions as accepted by the user.

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

decline_policies($policyversionid, $userid = null, $note = null, $lang = null)   X-Ref
Mark the given policy versions as declined by the user.

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

set_acceptances_status($policyversionid, $userid = null, $note = null, $lang = null, $status = 1)   X-Ref
Mark the given policy versions as accepted or declined by the user.

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

update_policyagreed($user = null)   X-Ref
Make sure that $user->policyagreed matches the agreement to the policies

param: int|stdClass|null $user user to check (null for current user)

revoke_acceptance($policyversionid, $userid, $note = null)   X-Ref
May be used to revert accidentally granted acceptance for another user

param: int $policyversionid
param: int $userid
param: null $note

create_acceptances_user_created(\core\event\user_created $event)   X-Ref
Create user policy acceptances when the user is created.

param: \core\event\user_created $event

get_agreement_optional($versionid)   X-Ref
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 {@link self::list_policies()} and in most cases should be warm enough for hits.

param: int $versionid
return: int policy_version::AGREEMENT_COMPULSORY | policy_version::AGREEMENT_OPTIONAL