moodle_local_treestudyplan/classes/reportservice.php
2024-07-19 12:31:26 +02:00

226 lines
8.6 KiB
PHP

<?php
// This file is part of the Studyplan plugin for Moodle
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
* Webservice class for handling studyplan reports
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace local_treestudyplan;
defined('MOODLE_INTERNAL') || die();
use local_treestudyplan\local\helpers\webservicehelper;
use local_treestudyplan\period;
use local_treestudyplan\studyplan;
use local_treestudyplan\studyplanpage;
require_once($CFG->libdir.'/externallib.php');
/**
* Webservice class for handling studyplan reports
*/
class reportservice extends \external_api {
/**
* Capability required to view studyplans (for other users)
* @var string
*/
const CAP_VIEW = "local/treestudyplan:viewuserreports";
/**
* Parameter description for webservice function
*/
public static function get_report_structure_parameters(): \external_function_parameters {
return new \external_function_parameters([
"pageid" => new \external_value(PARAM_INT, 'id of studyplan page'),
"firstperiod" => new \external_value(PARAM_INT, 'first period to include in report', VALUE_DEFAULT),
"lastperiod" => new \external_value(PARAM_INT, 'last period to include in report', VALUE_DEFAULT),
]);
}
/**
* Return value description for webservice function list_user_studyplans
*/
public static function get_report_structure_returns(): \external_description {
return new \external_single_structure([
"periods" => new \external_multiple_structure(new \external_single_structure([
"period" => period::structure(),
"lines" => new \external_multiple_structure(new \external_single_structure([
"line" => studyline::simple_structure(),
"items" => new \external_multiple_structure(studyitem::editor_structure(), "Information per studyitem"),
])),
])),
"firstperiod" => new \external_value(PARAM_INT, 'first period included in report'),
"lastperiod" => new \external_value(PARAM_INT, 'last period included in report'),
"studyplan" => studyplan::simple_structure(),
"page" => studyplanpage::simple_structure(),
]);
}
/**
* Get studyplan page structure for a report
* @param int $pageid ID of user to check specific info for
* @param int|null $firstperiod First period to include in report
* @param int|null $lastperiod Last period to include in report
* @return object
*/
public static function get_report_structure($pageid, $firstperiod=null, $lastperiod=null) {
$page = studyplanpage::find_by_id($pageid);
webservicehelper::require_capabilities(self::CAP_VIEW, $page->studyplan()->context());
$plan = $page->studyplan();
if (empty($firstperiod)) {
$firstperiod = 1;
}
if (empty($lastperiod)) {
// Index for periods starts at 1, so the period count is same as length.
$lastperiod = $page->periods();
}
$model = [
"studyplan" => $plan->simple_model(),
"page" => $page->simple_model(),
"firstperiod" => $firstperiod,
"lastperiod" => $lastperiod,
"periods" => [],
];
// Find all relevant parts in this order.
for ($i = $firstperiod; $i <= $lastperiod; $i++) {
$period = period::find($page, $i);
$pmodel = [
'period' => $period->model(),
'lines' => [],
];
$lines = studyline::find_page_children($page);
foreach ($lines as $line) {
$lmodel = [
"line" => $line->simple_model(),
"items" => [],
];
$items = studyitem::search_studyline_children($line, $i, studyitem::COURSE);
if (count($items) > 0) {
foreach ($items as $item) {
$lmodel["items"][] = $item->editor_model();
}
// Only include the line if it has actual children - saves us from muddying up the report.
$pmodel['lines'][] = $lmodel;
}
}
$model["periods"][] = $pmodel;
}
return $model;
}
/**
* Parameter description for webservice function
*/
public static function get_report_data_parameters(): \external_function_parameters {
return new \external_function_parameters([
"pageid" => new \external_value(PARAM_INT, 'id of studyplan page'),
"userid" => new \external_value(PARAM_INT, 'id of user'),
"firstperiod" => new \external_value(PARAM_INT, 'first period to include in report', VALUE_DEFAULT),
"lastperiod" => new \external_value(PARAM_INT, 'last period to include in report', VALUE_DEFAULT),
]);
}
/**
* Return value description for webservice function list_user_studyplans
*/
public static function get_report_data_returns(): \external_description {
return new \external_multiple_structure(studyitem::user_structure(), "Information per studyitem");
}
/**
* Webservice function get_report data
* @param int $pageid Id of the studyplan page to build the report for
* @param int $userid ID ofthe user to gather the report for
* @param int|null $firstperiod First period of the page to include in the report (first of page if left empty)
* @param int|null $lastperiod Last period of the page to include in the report (last of page if left empty)
*/
public static function get_report_data($pageid, $userid, $firstperiod=null, $lastperiod=null) {
$page = studyplanpage::find_by_id($pageid);
webservicehelper::require_capabilities(self::CAP_VIEW, $page->studyplan()->context());
$plan = $page->studyplan();
if (!$plan->has_linked_user($userid)) {
throw new \moodle_exception("error:usernotassociated", "local_treestudyplan");
}
if (empty($firstperiod)) {
$firstperiod = 1;
}
if (empty($lastperiod)) {
// Index for periods starts at 1, so the period count is same as length.
$lastperiod = $page->periods();
}
$model = [];
for ($i = $firstperiod; $i <= $lastperiod; $i++) {
$lines = studyline::find_page_children($page);
foreach ($lines as $line) {
$items = studyitem::search_studyline_children($line, $i, studyitem::COURSE);
if (count($items) > 0) {
foreach ($items as $item) {
$model[] = $item->user_model($userid);
}
}
}
}
return $model;
}
/**
* Parameter description for webservice function
*/
public static function get_report_details_parameters(): \external_function_parameters {
return new \external_function_parameters([
"itemid" => new \external_value(PARAM_INT, 'id of studyitem'),
"userid" => new \external_value(PARAM_INT, 'id of user'),
]);
}
/**
* Return value description for webservice function list_user_studyplans
*/
public static function get_report_details_returns(): \external_description {
return studyitem::user_structure();
}
/**
* Get study item details for a user
* @param int $itemid ID of study item
* @param int $userid ID of user to check specific info for
* @return array
*/
public static function get_report_details($itemid, $userid) {
$item = studyitem::find_by_id($itemid);
$plan = $item->studyline()->studyplan();
webservicehelper::require_capabilities(self::CAP_VIEW, $plan->context());
if (!$plan->has_linked_user($userid)) {
throw new \moodle_exception("error:usernotassociated", "local_treestudyplan");
}
return $item->user_model($userid);
}
}