moodle_local_treestudyplan/classes/period.php

376 lines
13 KiB
PHP
Raw Normal View History

2023-07-27 15:49:59 +02:00
<?php
2023-08-24 23:02:41 +02:00
// 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/>.
/**
2023-08-28 08:51:52 +02:00
* Model class for period descriptions
2023-08-24 23:02:41 +02:00
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
2023-07-27 15:49:59 +02:00
namespace local_treestudyplan;
2023-09-03 15:21:30 +02:00
use DateInterval;
2023-08-25 12:04:27 +02:00
defined('MOODLE_INTERNAL') || die();
2023-07-27 15:49:59 +02:00
require_once($CFG->libdir.'/externallib.php');
2023-08-28 08:51:52 +02:00
/**
* Model class for period descriptions
*/
2023-07-27 15:49:59 +02:00
class period {
2023-08-27 21:23:39 +02:00
/** @var string */
2023-07-27 15:49:59 +02:00
const TABLE = "local_treestudyplan_period";
2023-08-28 11:26:14 +02:00
/**
2023-08-28 08:51:52 +02:00
* Cache all retrieved periods in this session
* @var array */
2023-08-25 17:33:20 +02:00
private static $cache = [];
2023-08-28 11:26:14 +02:00
/**
2023-08-28 08:51:52 +02:00
* Cache the collection of periods per page retrieved this session
* @var array */
2023-08-25 17:33:20 +02:00
private static $pagecache = [];
2023-07-27 16:58:23 +02:00
2023-08-27 21:23:39 +02:00
/**
2023-08-27 22:20:17 +02:00
* Holds database record
2023-08-27 21:23:39 +02:00
* @var stdClass
*/
2023-08-27 23:27:07 +02:00
private $r;
2023-08-27 21:23:39 +02:00
/** @var int */
2023-07-27 15:49:59 +02:00
private $id;
2023-08-27 21:23:39 +02:00
/** @var studyplanpage */
2023-07-27 15:49:59 +02:00
private $page;
2023-08-28 08:51:52 +02:00
/**
* Shortcut to studyplan (page)'s aggregator
*/
2024-06-02 19:23:40 +02:00
public function aggregator(): aggregator {
2023-08-28 08:51:52 +02:00
return $this->page->aggregator();
2023-07-27 15:49:59 +02:00
}
2023-08-27 23:27:07 +02:00
/**
* Find record in database and return management object
2023-08-28 08:51:52 +02:00
* *Caches to avoid multiple creation events in one session.
2023-08-27 23:27:07 +02:00
* @param int $id Id of database record
*/
2023-08-25 17:33:20 +02:00
public static function find_by_id($id): self {
if (!array_key_exists($id, self::$cache)) {
self::$cache[$id] = new self($id);
2023-08-24 23:02:41 +02:00
}
2023-08-25 17:33:20 +02:00
return self::$cache[$id];
2023-07-27 15:49:59 +02:00
}
2023-07-27 16:58:23 +02:00
/**
* Find a period by page and period number [1..$page->periods()]
2023-08-28 08:51:52 +02:00
* @param studyplanpage $page Studyplan page to find period for
* @param int $periodnr Period sequence nr [1..$page->periods()]
2023-07-27 16:58:23 +02:00
*/
2023-08-25 17:33:20 +02:00
public static function find(studyplanpage $page, $periodnr): self {
2023-07-27 16:58:23 +02:00
global $DB;
2023-08-24 23:02:41 +02:00
if ($periodnr < 1) {
// Clamp period index .
2023-07-27 16:58:23 +02:00
$periodnr = 1;
}
2023-08-24 23:09:20 +02:00
try {
2023-08-25 10:41:56 +02:00
$id = $DB->get_field(self::TABLE, "id", ["page_id" => $page->id(), "period" => $periodnr], MUST_EXIST);
2023-08-25 17:33:20 +02:00
$period = self::find_by_id($id);
2023-08-25 10:41:56 +02:00
} catch (\dml_missing_record_exception $x) {
2023-07-27 16:58:23 +02:00
// Period does not exist - create one ...
2024-06-02 19:23:40 +02:00
// Make a best guess estimate of the start and end date, based on surrounding periods, .
2023-08-25 09:44:34 +02:00
// Or specified duration of the page and the sequence of the periods .
2023-07-27 16:58:23 +02:00
$pcount = $page->periods();
$ystart = $page->startdate()->getTimestamp();
$yend = $page->enddate()->getTimestamp();
2023-08-24 23:02:41 +02:00
// Estimate the period's timing to make a reasonable first guess.
$ydelta = $yend - $ystart;
2023-07-27 16:58:23 +02:00
$ptime = $ydelta / $pcount;
2023-08-24 23:02:41 +02:00
2023-08-24 23:09:20 +02:00
try {
2023-08-24 23:02:41 +02:00
// Check if we have a previous period to glance the end date of as a reference.
2023-08-25 11:52:05 +02:00
$startdate = $DB->get_field(self::TABLE, "enddate",
2023-08-25 17:33:20 +02:00
["page_id" => $page->id(), "period" => $periodnr - 1], MUST_EXIST);
$pstart = strtotime($startdate) + (24 * 60 * 60); // Add one day.
2023-08-25 10:41:56 +02:00
} catch (\dml_missing_record_exception $x2) {
2023-08-24 23:02:41 +02:00
// If not, do a fair guess.
2023-08-25 17:33:20 +02:00
$pstart = $ystart + (($periodnr - 1) * $ptime);
2023-07-27 16:58:23 +02:00
}
2023-08-24 23:09:20 +02:00
try {
2023-08-24 23:02:41 +02:00
// Check if we have a next period to glance the start date of as a reference.
2023-08-25 17:33:20 +02:00
$enddate = $DB->get_field(self::TABLE, "startdate",
["page_id" => $page->id(), "period" => $periodnr + 1], MUST_EXIST);
$pstart = strtotime($enddate) - (24 * 60 * 60); // Subtract one day.
} catch (\dml_missing_record_exception $x) {
// If not, do a fair guess.
2023-07-27 16:58:23 +02:00
$pend = $pstart + $ptime;
}
2024-06-02 23:23:32 +02:00
// Continue period numbers if so configured.
2024-06-02 19:23:40 +02:00
if (get_config("local_treestudyplan", "continueperiodnumberingnewpage")) {
2024-06-01 14:00:32 +02:00
$offset = 0;
foreach (studyplanpage::find_studyplan_children($page->studyplan()) as $p) {
if ($p->id() != $page->id()) {
$offset += $p->periods();
}
}
$displaynr = $periodnr + $offset;
} else {
$displaynr = $periodnr;
}
2023-08-24 23:02:41 +02:00
// And create the period.
2023-07-27 16:58:23 +02:00
$period = self::add([
'page_id' => $page->id(),
'period' => $periodnr,
2024-06-01 14:00:32 +02:00
'fullname' => \get_string("period_default_fullname", "local_treestudyplan", $displaynr),
'shortname' => \get_string("period_default_shortname", "local_treestudyplan", $displaynr),
2023-08-24 23:02:41 +02:00
'startdate' => date("Y-m-d", $pstart),
'enddate' => date("Y-m-d", $pend),
2023-07-27 16:58:23 +02:00
]);
}
return $period;
}
2023-08-28 08:51:52 +02:00
/**
* Find all periods registered to a studyplan in sequence
* @param studyplanpage $page Studyplan page to find periods for
* @return period[]
*/
2023-08-25 17:33:20 +02:00
public static function find_for_page(studyplanpage $page): array {
$periods = [];
// Find and add the periods to an array with the period sequence as a key.
for ($i = 1; $i <= $page->periods(); $i++) {
$period = self::find($page, $i);
$periods[$i] = $period;
2023-08-24 23:02:41 +02:00
}
return $periods;
2023-07-27 16:58:23 +02:00
}
2023-08-27 23:27:07 +02:00
/**
* Construct new instance from DB record
* @param int $id Id of database record
*/
2023-07-27 15:49:59 +02:00
private function __construct($id) {
global $DB;
$this->id = $id;
2023-08-24 23:02:41 +02:00
$this->r = $DB->get_record(self::TABLE, ['id' => $id]);
2023-08-25 17:33:20 +02:00
$this->page = studyplanpage::find_by_id($this->r->page_id);
2023-07-27 15:49:59 +02:00
}
2023-08-27 22:20:17 +02:00
/**
* Return database identifier
* @return int
*/
2023-08-24 23:02:41 +02:00
public function id() {
2023-07-27 15:49:59 +02:00
return $this->id;
}
2023-08-28 11:26:14 +02:00
/**
2023-08-28 08:51:52 +02:00
* Return associated studyplan
* @return studyplan
*/
2024-06-02 19:23:40 +02:00
public function studyplan(): studyplan {
2023-07-27 15:49:59 +02:00
return $this->page->studyplan();
}
2023-08-28 11:26:14 +02:00
/**
2023-08-28 08:51:52 +02:00
* Return associated studyplan page
* @return studyplanpage
*/
2023-08-24 23:02:41 +02:00
public function page() {
2023-07-27 15:49:59 +02:00
return $this->page;
}
2023-08-27 22:20:17 +02:00
/**
* Return short name
* @return string
*/
2023-08-24 23:02:41 +02:00
public function shortname() {
2023-07-27 15:49:59 +02:00
return $this->r->shortname;
}
2023-08-27 22:20:17 +02:00
/**
* Return full name
* @return string
*/
2023-08-24 23:02:41 +02:00
public function fullname() {
2023-07-27 15:49:59 +02:00
return $this->r->fullname;
}
2023-08-28 08:51:52 +02:00
/**
* Return period sequence number
* @return int
*/
2023-08-24 23:02:41 +02:00
public function period() {
2023-07-27 15:49:59 +02:00
return $this->r->period;
}
2023-08-27 23:27:07 +02:00
/**
* Start date
* @return \DateTime
*/
2023-08-24 23:02:41 +02:00
public function startdate() {
2023-07-27 15:49:59 +02:00
return new \DateTime($this->r->startdate);
}
2023-08-27 23:27:07 +02:00
/**
* End date
* @return \DateTime
*/
2023-08-24 23:02:41 +02:00
public function enddate() {
if ($this->r->enddate && strlen($this->r->enddate) > 0) {
2023-07-27 15:49:59 +02:00
return new \DateTime($this->r->enddate);
2023-08-25 10:41:56 +02:00
} else {
2023-09-03 15:21:30 +02:00
// Return a date 2 months into the future if not set.... Yes, it needs to be set.
return (new \DateTime($this->r->startdate))->add(new \DateInterval("P2M"));
2023-07-27 15:49:59 +02:00
}
}
2023-08-28 08:51:52 +02:00
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
*/
2024-06-02 19:23:40 +02:00
public static function structure($value = VALUE_REQUIRED): \external_description {
2023-07-27 15:49:59 +02:00
return new \external_single_structure([
2023-07-27 16:58:23 +02:00
"id" => new \external_value(PARAM_INT, 'id of period'),
"fullname" => new \external_value(PARAM_TEXT, 'Full name of period'),
2023-08-25 10:41:56 +02:00
"shortname" => new \external_value(PARAM_TEXT, 'Short name of period'),
2023-07-27 15:49:59 +02:00
"period" => new \external_value(PARAM_INT, 'period sequence'),
2023-07-27 16:58:23 +02:00
"startdate" => new \external_value(PARAM_TEXT, 'start date of period'),
"enddate" => new \external_value(PARAM_TEXT, 'end date of period'),
"timeless" => new \external_value(PARAM_BOOL, 'Page does not include time information'),
2023-08-24 23:02:41 +02:00
], 'Period info', $value);
2023-07-27 15:49:59 +02:00
}
2023-08-28 08:51:52 +02:00
/**
* Webservice model for basic info
* @return array Webservice data model
*/
2023-08-24 23:02:41 +02:00
public function model() {
2024-06-02 19:23:40 +02:00
$timeless = get_config("local_treestudyplan", "timelessperiods");
2023-07-27 15:49:59 +02:00
return [
'id' => $this->r->id,
'fullname' => $this->r->fullname,
'shortname' => $this->r->shortname,
'period' => $this->r->period,
2024-06-02 19:23:40 +02:00
'startdate' => ($timeless) ? 0 : $this->r->startdate,
'enddate' => ($timeless) ? 0 : $this->r->enddate,
'timeless' => $timeless,
2023-07-27 15:49:59 +02:00
];
}
2023-07-27 16:58:23 +02:00
/**
2023-08-28 11:26:14 +02:00
* Add a new period for a studyplan page
2023-08-28 08:51:52 +02:00
* Use only when performing import! The static find() and find_for_page() functions create the period during normal operation
* @param array $fields Properties for ['page_id', 'fullname', 'shortname', 'period', 'startdate', 'enddate']
2023-07-27 16:58:23 +02:00
*/
2024-06-02 19:23:40 +02:00
public static function add($fields): self {
2023-07-27 16:58:23 +02:00
global $DB;
2023-08-24 23:02:41 +02:00
if (!isset($fields['page_id'])) {
2023-07-27 16:58:23 +02:00
throw new \InvalidArgumentException("parameter 'page_id' missing");
}
2023-08-24 23:02:41 +02:00
if (!isset($fields['period'])) {
2023-07-27 16:58:23 +02:00
throw new \InvalidArgumentException("parameter 'period' missing");
}
2023-08-25 10:41:56 +02:00
if ($DB->record_exists(self::TABLE, ["page_id" => $fields["page_id"], "period" => $fields["period"]])) {
2023-07-27 16:58:23 +02:00
throw new \InvalidArgumentException("record already exists for specified page and period");
2023-07-27 15:49:59 +02:00
}
2023-08-24 23:02:41 +02:00
$addable = ['page_id', 'fullname', 'shortname', 'period', 'startdate', 'enddate'];
2023-07-27 16:58:23 +02:00
$info = [ ];
2023-08-24 23:02:41 +02:00
foreach ($addable as $f) {
if (array_key_exists($f, $fields)) {
2023-07-27 15:49:59 +02:00
$info[$f] = $fields[$f];
}
}
$id = $DB->insert_record(self::TABLE, $info);
2023-08-25 17:33:20 +02:00
return self::find_by_id($id); // Make sure the new page is immediately cached.
2023-07-27 15:49:59 +02:00
}
2023-08-28 08:51:52 +02:00
/**
* Edit period properties
* @param array $fields Properties for ['fullname', 'shortname', 'startdate', 'enddate']
*/
2024-06-02 19:23:40 +02:00
public function edit($fields): self {
2023-07-27 15:49:59 +02:00
global $DB;
2023-09-03 15:21:30 +02:00
$pages = self::find_for_page($this->page());
$prev = (count($pages) > 2 && $this->period() >= 1) ? $pages[$this->period() - 1] : null;
$next = (count($pages) > $this->period()) ? $pages[$this->period() + 1] : null;
2023-08-24 23:02:41 +02:00
$editable = ['fullname', 'shortname', 'startdate', 'enddate'];
2024-06-02 19:23:40 +02:00
$info = ['id' => $this->id ];
2023-08-24 23:02:41 +02:00
foreach ($editable as $f) {
if (array_key_exists($f, $fields)) {
2023-07-27 15:49:59 +02:00
$info[$f] = $fields[$f];
}
}
$DB->update_record(self::TABLE, $info);
2023-09-03 15:21:30 +02:00
// Reload record after edit and ensure end dates of previous period are adjusted if needed.
2023-08-24 23:02:41 +02:00
$this->r = $DB->get_record(self::TABLE, ['id' => $this->id], "*", MUST_EXIST);
2023-09-03 15:21:30 +02:00
2023-09-08 12:47:29 +02:00
// Adjust end date of previous period if needed.
2023-09-03 15:21:30 +02:00
if (isset($prev) && !empty($fields['startdate'])) {
$maxdate = $this->startdate()->sub(new DateInterval("P1D")); // Subtract 1 day, since periods include the end day.
$rqdate = $prev->enddate();
if ($maxdate < $rqdate) {
$prev->edit(["enddate" => $maxdate->format("Y-m-d")]);
}
}
2023-09-08 12:47:29 +02:00
// Adjust start date of next period if needed.
2023-09-03 15:21:30 +02:00
if (isset($next) && !empty($fields['enddate'])) {
$mindate = $this->enddate()->add(new DateInterval("P1D")); // Subtract 1 day, since periods include the end day.
$rqdate = $next->startdate();
if ($mindate > $rqdate) {
$next->edit(["startdate" => $mindate->format("Y-m-d")]);
}
}
2023-07-27 15:49:59 +02:00
return $this;
}
2023-08-28 08:51:52 +02:00
/**
* Delete period
*/
2024-06-02 19:23:40 +02:00
public function delete(): success {
2023-07-27 15:49:59 +02:00
global $DB;
2023-07-27 16:58:23 +02:00
$DB->delete_records(self::TABLE, ['id' => $this->id]);
return success::success();
2023-07-27 15:49:59 +02:00
}
2023-08-28 08:51:52 +02:00
/**
* Webservice structure for list of periods in page
* @param int $value Webservice requirement constant
*/
2024-06-02 19:23:40 +02:00
public static function page_structure($value = VALUE_REQUIRED): \external_description {
2023-08-24 23:02:41 +02:00
return new \external_multiple_structure(self::structure(), "The periods in the page", $value);
2023-07-27 15:49:59 +02:00
}
2023-08-28 08:51:52 +02:00
/**
* Webservice model list of periods in page
* @param studyplanpage $page The page to create the model for
* @return array Webservice data model
*/
2024-06-02 19:23:40 +02:00
public static function page_model(studyplanpage $page): array {
2023-07-27 16:58:23 +02:00
$model = [];
2024-06-02 19:23:40 +02:00
foreach (self::find_for_page($page, true) as $p) {
2023-07-27 16:58:23 +02:00
$model[] = $p->model();
2023-07-27 15:49:59 +02:00
}
return $model;
}
2023-08-25 11:52:05 +02:00
}