consent_functions.php
Table of Contents
Functions
- consentmanager_check_read() : bool
- Check if the user should have read access to a consent record
- consentmanager_check_write() : bool
- Check if the user should have write access to a consent record
- consentmanager_get_consents() : array<string|int, mixed>|bool
- Get a list of consents for a given resource
- consentmanager_delete_consent() : bool
- Delete a consent record
- consentmanager_create_consent() : int|bool
- Create a new consent record
- consentmanager_link_consent() : bool
- Link a consent record with a resource
- consentmanager_unlink_consent() : bool
- Unlink a consent record from a resource
- consentmanager_batch_link_unlink() : bool
- Link/unlink all resources in a collection with a consent record
- consentmanager_get_consent() : array<string|int, mixed>|bool
- Retrieve a consent record
- consentmanager_update_consent() : bool
- Update a consent record
- consentmanager_get_all_consents_by_collection() : array<string|int, mixed>|bool
- Fetch all consent records linked to resources in a collection
- consentmanager_get_all_consents() : array<string|int, mixed>|bool
- Fetch all consent records, optionally filtered by search text
- consentmanager_get_all_consents_grouped() : array<string|int, mixed>|bool
- Fetch all consent records grouped by if they are expiring or not
- consentmanager_save_file() : bool
- Save a file associated with a consent record
- consentmanager_get_expiring_consents() : array<string|int, mixed>|bool
- Fetch all expiring consent records
- consentmanager_set_consent_expiration_notice() : bool
- Sets expiration notice sent flag on consent records
- consentmanager_get_expired_consent_resources() : array<string|int, mixed>|bool
- Fetch expired consent records
- consentmanager_process_expiry_notifications() : bool
- Process expiring consent records and send a notification/email
- consentmanager_process_expired_auto_archive() : bool
- Process expired consent records and archive them
Functions
consentmanager_check_read()
Check if the user should have read access to a consent record
consentmanager_check_read([int|null $resource = null ]) : bool
Determines if the user has read access for a specific resource or general read permissions.
Parameters
- $resource : int|null = null
-
The ID of the resource to check read access for. If null, checks for general read permissions.
Return values
bool —Returns true if the user has the required permissions; false otherwise.
consentmanager_check_write()
Check if the user should have write access to a consent record
consentmanager_check_write([int|null $resource = null ]) : bool
Determines if the user has write access for a specific resource or general write permissions.
Parameters
- $resource : int|null = null
-
The ID of the resource to check write access for. If null, checks for general write permissions.
Return values
bool —Returns true if the user has the required permissions; false otherwise.
consentmanager_get_consents()
Get a list of consents for a given resource
consentmanager_get_consents(int $resource) : array<string|int, mixed>|bool
This function retrieves a list of consent records associated with a specified resource. Each record includes the consent ID, name, expiration date, and consent usage.
Parameters
- $resource : int
-
The ID of the resource for which to retrieve associated consents.
Return values
array<string|int, mixed>|bool —Returns an array of consents associated with the resource if the user has read access; otherwise, returns false.
consentmanager_delete_consent()
Delete a consent record
consentmanager_delete_consent(int $ref) : bool
This function deletes a consent record and its associations with resources
by removing entries from the consent and resource_consent tables.
Parameters
- $ref : int
-
The ID of the consent record to be deleted.
Return values
bool —Returns true if the consent record was successfully deleted, or false if the user does not have write access to the resource.
consentmanager_create_consent()
Create a new consent record
consentmanager_create_consent(string $name, string|null $date_of_birth, string|null $address, string|null $parent_guardian, string $email, string $telephone, string $consent_usage, string $notes, string|null $date_of_consent, string|null $expires, string $created_by) : int|bool
This function creates a new consent record by inserting the provided details
into the consent table. It returns the ID of the newly created consent
record if successful.
Parameters
- $name : string
-
The name of the individual giving consent.
- $date_of_birth : string|null
-
The DOB of the individual, formatted as a string. Optional.
- $address : string|null
-
The address of the individual. Optional.
- $parent_guardian : string|null
-
The parent or guardian of the individual. Optional.
- $email : string
-
The email address of the individual.
- $telephone : string
-
The telephone number of the individual.
- $consent_usage : string
-
Description of the intended usage for which consent is given.
- $notes : string
-
Any additional notes related to the consent record.
- $date_of_consent : string|null
-
The date the consent applies from.
- $expires : string|null
-
The expiry date of the consent, formatted as a string.
- $created_by : string
-
The ref of the user who created the consent record.
Return values
int|bool —Returns the ID of the new consent record on success, or false if the user does not have write access.
consentmanager_link_consent()
Link a consent record with a resource
consentmanager_link_consent(int $consent, int $resource) : bool
This function links a consent record to a specified resource by inserting
an entry in the resource_consent table. It also logs this action in the
resource's log.
Parameters
- $consent : int
-
The ID of the consent record to be linked to the resource.
- $resource : int
-
The ID of the resource to which the consent is being linked.
Return values
bool —Returns true if the consent was successfully linked, false if the user does not have write access to the resource.
consentmanager_unlink_consent()
Unlink a consent record from a resource
consentmanager_unlink_consent(int $consent, int $resource) : bool
This function removes the association between a specified consent record and a resource. The action is logged for the resource.
Parameters
- $consent : int
-
The ID of the consent record to unlink.
- $resource : int
-
The ID of the resource from which to unlink the consent.
Return values
bool —Returns true if the consent record is successfully unlinked; returns false if the user does not have write access to the resource.
consentmanager_batch_link_unlink()
Link/unlink all resources in a collection with a consent record
consentmanager_batch_link_unlink(int $consent, int $collection, bool $unlink) : bool
This function links or unlinks all resources in a specified collection to/from a given consent record. If unlinking, it removes existing relationships between the consent record and the resources. If linking, it creates new relationships. Each action is logged.
Parameters
- $consent : int
-
The ID of the consent record to link or unlink.
- $collection : int
-
The ID of the collection containing the resources to process.
- $unlink : bool
-
Set to true to unlink resources from the consent; set to false to link resources to the consent.
Return values
bool —Returns true if the process completes successfully; returns false if an invalid consent ID is provided.
consentmanager_get_consent()
Retrieve a consent record
consentmanager_get_consent(int $consent) : array<string|int, mixed>|bool
This function retrieves the details of a specified consent record, including the subject's name, email, telephone number, consent usage types, notes, expiry date, and file. It also fetches a list of resources associated with the consent.
Parameters
- $consent : int
-
The ID of the consent record to fetch.
Return values
array<string|int, mixed>|bool —Returns an associative array containing consent details and associated resources if the user has read access; returns false if access is denied or the consent record does not exist.
consentmanager_update_consent()
Update a consent record
consentmanager_update_consent(int $consent, string $name, string|null $date_of_birth, string|null $address, string|null $parent_guardian, string $email, string $telephone, string $consent_usage, string $notes, string|null $date_of_consent, string|null $expires) : bool
This function updates the details of an existing consent record with the provided information. It allows modification of the subject's name, DOB, address, parent/guardian name, email, telephone number, consent usage types, date of consent, notes, and expiry date. It also resets the expiration_notice_sent flag if the expiry date is modified.
Parameters
- $consent : int
-
The ID of the consent record to update.
- $name : string
-
The name of the individual giving consent.
- $date_of_birth : string|null
-
The DOB of the individual, formatted as a string. Optional.
- $address : string|null
-
The address of the individual. Optional.
- $parent_guardian : string|null
-
The parent or guardian of the individual. Optional.
- $email : string
-
The email address of the individual.
- $telephone : string
-
The telephone number of the individual.
- $consent_usage : string
-
A description of the permitted usage types for the consent.
- $notes : string
-
Additional notes related to the consent record.
- $date_of_consent : string|null
-
The date the consent applies from.
- $expires : string|null
-
The expiry date of the consent record, formatted as a string.
Return values
bool —Returns true if the consent record was successfully updated, or false if the user does not have write access.
consentmanager_get_all_consents_by_collection()
Fetch all consent records linked to resources in a collection
consentmanager_get_all_consents_by_collection(int $collection) : array<string|int, mixed>|bool
This function retrieves all consent records that are linked to resources within a specified collection. It returns an array of consents associated with the resources in the collection.
Parameters
- $collection : int
-
The ID of the collection containing the resources for which to retrieve consent records.
Return values
array<string|int, mixed>|bool —Returns an array of consent records if the user has read access; otherwise, returns false.
consentmanager_get_all_consents()
Fetch all consent records, optionally filtered by search text
consentmanager_get_all_consents([string $findtext = "" ][, string $consent_status = "all" ]) : array<string|int, mixed>|bool
This function retrieves all consent records from the database. If a search string is provided, it filters the results based on the name of the person associated with each consent record. It can also filter based on consent status e.g all, active (non-expired), expiring (expiring within a configured amount of days), expired. Defaults to returning all.
Parameters
- $findtext : string = ""
-
Optional. A search string to filter the results by the name of the person giving consent. If empty, returns all records.
- $consent_status : string = "all"
-
Status of consent records to return
Return values
array<string|int, mixed>|bool —Returns an array of consent records if the user has read access; otherwise, returns false.
consentmanager_get_all_consents_grouped()
Fetch all consent records grouped by if they are expiring or not
consentmanager_get_all_consents_grouped() : array<string|int, mixed>|bool
Return values
array<string|int, mixed>|bool —Returns an array of consent records if the user has read access; otherwise, returns false.
consentmanager_save_file()
Save a file associated with a consent record
consentmanager_save_file(int $consent, string $filename, string $filedata) : bool
This function saves a file (typically a consent form or related document) to the file system and updates the associated consent record in the database with the filename. The function checks user permissions and blocks the upload if the file extension is banned.
Parameters
- $consent : int
-
The ID of the consent record to associate the file with.
- $filename : string
-
The name of the file to be saved (including extension).
- $filedata : string
-
The raw file data (contents) to be written to disk.
Return values
bool —Returns true if the file was saved and the database updated successfully; returns false if the user lacks permission or the file extension is not allowed.
consentmanager_get_expiring_consents()
Fetch all expiring consent records
consentmanager_get_expiring_consents(int $expires_within[, bool $unsent_only = true ]) : array<string|int, mixed>|bool
This function returns an array of consent records that are expiring within so many days. It can optionally be filtered to include records that have not been flagged as having an expiration notification already sent
Parameters
- $expires_within : int
-
Number of days that the records are expiring within
- $unsent_only : bool = true
-
Include only records where an expiration notification hasn't been sent
Return values
array<string|int, mixed>|bool —Returns an array of expiring consent records if the user has read access; otherwise, returns false.
consentmanager_set_consent_expiration_notice()
Sets expiration notice sent flag on consent records
consentmanager_set_consent_expiration_notice(array<string|int, mixed> $consents) : bool
This function takes an array of consent record references and sets the expiration_notice_sent flag on each one.
Parameters
- $consents : array<string|int, mixed>
-
An array of consent references
Return values
bool —Returns true if the flags were set; otherwise, returns false
consentmanager_get_expired_consent_resources()
Fetch expired consent records
consentmanager_get_expired_consent_resources(int $archive_status) : array<string|int, mixed>|bool
This function returns expired consent records that are not deleted and are not in the passed archive_state
Parameters
- $archive_status : int
Return values
array<string|int, mixed>|bool —Returns an array of expired consent records; otherwise, returns false.
consentmanager_process_expiry_notifications()
Process expiring consent records and send a notification/email
consentmanager_process_expiry_notifications() : bool
Return values
bool —Returns true if the notification process completes
consentmanager_process_expired_auto_archive()
Process expired consent records and archive them
consentmanager_process_expired_auto_archive() : bool
Return values
bool —Returns true if the auto archiving process completes