Documentation

reporting_functions.php

Table of Contents

Functions

get_report_name()  : string
Retrieves the name of a report
get_reports()  : array<string|int, mixed>
Retrieves an array of reports from the database.
do_report()  : void|string|array<string|int, mixed>
do_report - Runs the specified report. This is used in a number of ways:- 1) Outputs an HTML table to screen ($download = false) 2) Produces a CSV - for direct download from team_report.php - captured and saved as a CSV file if called by send_periodic_report_emails() and over 100 rows are returned
create_periodic_email()  : mixed
Creates a new automatic periodic e-mail report
send_periodic_report_emails()  : void
Sends periodic report emails to users based on configured schedules.
delete_periodic_report()  : bool
Deletes a periodic report for the current user.
unsubscribe_user_from_periodic_report()  : bool
Unsubscribes a user from a specified periodic report.
get_translated_activity_type()  : string
Retrieves the translated version of an activity type.
report_has_date()  : bool
Checks for the presence of date placeholders in a report's SQL query.
report_has_date_by_id()  : bool
Checks for the presence of date placeholders in a report's sql query using the report's id.
report_has_thumbnail()  : bool
Check if report has a "thumbnail" column in its SQL query.
report_process_period()  : array<string|int, mixed>
Get report date range based on user input
report_process_query_placeholders()  : string
Find and replace a reports' query placeholders with their values.
render_pie_graph()  : void
Output the Javascript to build a pie chart in the canvas denoted by $id $data must be in the following format $data = array( "slice_a label" => "slice_a value", "slice_b label" => "slice_b value", );
render_bar_graph()  : void
Output the Javascript to build a bar chart in the canvas denoted by $id $data must be in the following format $data = array( "point_a x value" => "point_a y value", "point_b x value" => "point_b y value",

Functions

get_report_name()

Retrieves the name of a report

get_report_name(array<string|int, mixed> $report) : string
Parameters
$report : array<string|int, mixed>

The report array containing at least a 'name' key.

Return values
string —

The translated report name.

get_reports()

Retrieves an array of reports from the database.

get_reports() : array<string|int, mixed>

This function queries the database for all reports and processes them by:

  1. Translating the report names using the get_report_name function.
  2. Checking if the reports contain date fields using report_has_date.
  3. Verifying if the reports have associated thumbnails using report_has_thumbnail.

The reports are always listed in the same order, regardless of the language used.

Return values
array<string|int, mixed> —

An array of processed reports, each containing 'ref', 'name', 'contains_date', and 'has_thumbnail' keys.

do_report()

do_report - Runs the specified report. This is used in a number of ways:- 1) Outputs an HTML table to screen ($download = false) 2) Produces a CSV - for direct download from team_report.php - captured and saved as a CSV file if called by send_periodic_report_emails() and over 100 rows are returned

do_report(int $ref, mixed $from_y, mixed $from_m, mixed $from_d, mixed $to_y, mixed $to_m, mixed $to_d[, mixed $download = true ][, mixed $add_border = false ][, mixed $foremail = false ][, array<string|int, mixed> $search_params = array() ][, bool $results_as_array = false ]) : void|string|array<string|int, mixed>
Parameters
$ref : int

Report ID

$from_y : mixed

Start year (used for reprts with date placholders)

$from_m : mixed

Start month

$from_d : mixed

Start day

$to_y : mixed

End year

$to_m : mixed

To month

$to_d : mixed

To day

$download : mixed = true

Output as CSV attachment (default)/output directly to client

$add_border : mixed = false

Optional table border (not for download)

$foremail : mixed = false

Sending as email?

$search_params : array<string|int, mixed> = array()

Search parameters - get_search_params() - will run the report on the search results and replace the '[non_correlated_sql]' placeholder with the search query.

$results_as_array : bool = false

Output is an array containing report rows. Will override other output modes. Useful for the API.

Return values
void|string|array<string|int, mixed> —

Outputs CSV file, array of report data, returns HTML table or returns an array with path to the CSV file, rows and filename

create_periodic_email()

Creates a new automatic periodic e-mail report

create_periodic_email(mixed $user, mixed $report, mixed $period, mixed $email_days, array<string|int, mixed> $user_groups, array<string|int, mixed> $search_params) : mixed
Parameters
$user : mixed
$report : mixed
$period : mixed
$email_days : mixed
$user_groups : array<string|int, mixed>
$search_params : array<string|int, mixed>

send_periodic_report_emails()

Sends periodic report emails to users based on configured schedules.

send_periodic_report_emails([bool $echo_out = true ][, bool $toemail = true ]) : void

This function checks for any scheduled reports that need to be sent, either because they are pending or overdue. It gathers the necessary user email addresses, generates the reports, and sends them as emails with attachments if applicable.

Parameters
$echo_out : bool = true

Determines whether to output progress messages during processing.

$toemail : bool = true

Determines whether to send the reports via email.

delete_periodic_report()

Deletes a periodic report for the current user.

delete_periodic_report(int $ref) : bool

This function removes the specified periodic report from the database for the user and also clears any associated unsubscribe (opt out) records.

Parameters
$ref : int

The reference ID of the periodic report to delete.

Return values
bool —

Returns true upon successful deletion.

unsubscribe_user_from_periodic_report()

Unsubscribes a user from a specified periodic report.

unsubscribe_user_from_periodic_report(int $user_id, int $periodic_email_id) : bool

This function inserts a record into the unsubscribe table, preventing the specified user from receiving future emails related to the given periodic report.

Parameters
$user_id : int

The ID of the user to unsubscribe.

$periodic_email_id : int

The ID of the periodic email report to unsubscribe from.

Return values
bool —

Returns true upon successful unsubscription.

get_translated_activity_type()

Retrieves the translated version of an activity type.

get_translated_activity_type(string $activity_type) : string

This function takes an activity type string, checks if a corresponding translation exists in the global language array, and returns the translated string if available. If no translation is found, it returns the original activity type.

Parameters
$activity_type : string

The activity type in plain text English.

Return values
string —

The translated activity type if available; otherwise, the original activity type.

report_has_date()

Checks for the presence of date placeholders in a report's SQL query.

report_has_date(string $query) : bool
Parameters
$query : string

The report's SQL query.

Return values
bool —

Returns true if a date placeholder was found else false.

report_has_date_by_id()

Checks for the presence of date placeholders in a report's sql query using the report's id.

report_has_date_by_id(int $report) : bool
Parameters
$report : int

Report id of the report to retrieve the query data from the report table.

Return values
bool —

Returns true if a date placeholder was found else false.

report_has_thumbnail()

Check if report has a "thumbnail" column in its SQL query.

report_has_thumbnail(string|null $query) : bool
Parameters
$query : string|null

The reports' SQL query.

Return values
bool

report_process_period()

Get report date range based on user input

report_process_period(array<string|int, mixed> $info) : array<string|int, mixed>
Parameters
$info : array<string|int, mixed>

Information about the period selection. See unit test for example input

Return values
array<string|int, mixed>

report_process_query_placeholders()

Find and replace a reports' query placeholders with their values.

report_process_query_placeholders(string $query, array<string|int, mixed> $placeholders) : string
Parameters
$query : string

Reports' SQL query

$placeholders : array<string|int, mixed>

Map between a placeholder and its actual value

Return values
string

render_pie_graph()

Output the Javascript to build a pie chart in the canvas denoted by $id $data must be in the following format $data = array( "slice_a label" => "slice_a value", "slice_b label" => "slice_b value", );

render_pie_graph(string $id, array<string|int, mixed> $data[, string|null $total = null ]) : void
Parameters
$id : string

identifier for the canvas to render the chart in

$data : array<string|int, mixed>

data to be rendered in the chart

$total : string|null = null

null will mean that the data is complete and an extra field is not required a string can be used to denote the total value to pad the data to

render_bar_graph()

Output the Javascript to build a bar chart in the canvas denoted by $id $data must be in the following format $data = array( "point_a x value" => "point_a y value", "point_b x value" => "point_b y value",

render_bar_graph(string $id, array<string|int, mixed> $data) : void
Parameters
$id : string

identifier for the canvas to render the chart in

$data : array<string|int, mixed>

data to be rendered in the chart

On this page

Search results