Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
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.

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$policyversionidPolicy version id(s) to set acceptance status for.
int | null$useridId of the user accepting the policy version, defaults to the current one.
string | null$noteNote to be recorded.
string | null$langLanguage 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$versionidsint[] List of policy version ids to check
int$useridAccepting policies on this user's behalf (defaults to accepting on self)
bool$throwexceptionThrow 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$versionidsint[] List of policy version ids to check
int$useridDeclining policies on this user's behalf (defaults to declining by self)
bool$throwexceptionThrow 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$versionobject 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$versionidsint[] List of policy version ids to check
int$useridRevoking policies on this user's behalf (defaults to revoking by self)
bool$throwexceptionThrow 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$behalfidThe id of user on whose behalf the user is viewing the policy
int$useridThe 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$policyversionidPolicy version id(s) to set acceptance status for.
int | null$useridId of the user accepting the policy version, defaults to the current one.
string | null$noteNote to be recorded.
string | null$langLanguage 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$versionsList 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$formdata submitted from the tool_policy::form::policydoc form.
Return values
tool_policy\policy_versionpersistent

◆ 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$versionpersistent representing the version.
Return values
stdClassform 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$formdata submitted from the tool_policy::form::policydoc form.
Return values
tool_policy\policy_versionpersistent

◆ 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$formdata submitted from the tool_policy::form::policydoc form.
Return values
tool_policy\policy_versionpersistent

◆ 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
intpolicy_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$audienceIf defined, filter against the given audience (AUDIENCE_ALL always included)
Return values
arrayof 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
arrayarray 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$versionidID of the policy document version.
array$policiescached 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$useridid of a user.
int | array$versionslist of policy versions.
Return values
arraylist 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$useridThe id if the user with parental responsibility
array$extrafieldsExtra fields to be included in result
Return values
arrayof 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$useridUser identifier.
int$versionidPolicy version identifier.
array | null$acceptancesList of policy version acceptances indexed by versionid.
Return values
stdClass|nullAcceptance 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$useridUser identifier.
int$versionidPolicy version identifier.
array | null$acceptancesPre-loaded list of policy version acceptances indexed by versionid.
Return values
bool|nullTrue/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$audienceIf defined, filter against the given audience (AUDIENCE_ALL always included)
Return values
arrayof 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$idsLoad only the given policies, defaults to all.
int$countacceptancesreturn number of user acceptances for each version
Return values
arrayof 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_versionpersistent

◆ 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$policyversionidPolicy version id(s) to set acceptance status for.
int | null$useridId of the user accepting the policy version, defaults to the current one.
string | null$noteNote to be recorded.
string | null$langLanguage in which the policy was shown, defaults to the current one.
int$statusThe 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$useruser to check (null for current user)

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