moodle_local_treestudyplan/classes/studyline.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/>.
/**
 * Model class for study lines
 * @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();

require_once($CFG->libdir.'/externallib.php');
/**
 * Model class for study lines
 */
class studyline {
    /**
     * Handle for course slots in the period for webservice export
     * @var string
     */
    public const SLOTSET_COURSES = 'courses';
    /**
     * Handle for filter slots around the periods for webservice export
     * @var string
     */
    public const SLOTSET_FILTER = 'filters';

    /**
     * List of item types allowed in the course slot
     * @var array
     */
    public const COURSE_TYPES = [
        studyitem::COURSE,
    ];
    /**
     * List of item types allowed in the filter slot
     * @var array
     */
    public const FILTER_TYPES = [
        studyitem::JUNCTION,
        studyitem::BADGE,
        studyitem::FINISH,
        studyitem::START,
    ];

    /**
     * List of item types allowed in the first filter slot
     * @var array
     */
    public const FILTER0_TYPES = [
        studyitem::START,
    ];

    /** @var string */
    public const TABLE = "local_treestudyplan_line";

    /**
     * Cache retrieved studylines for optimization
     * @var array
     */
    private static $cache = [];

    /**
     * Holds database record
     * @var stdClass
     */
    private $r;
    /** @var int */
    private $id;
    /** @var studyplanpage */
    private $page;
    /** @var studyplan*/
    private $studyplan;


    /**
     * Return the context the studyplan is associated to
     */
    public function context(): \context {
        return $this->studyplan->context();
    }

    /**
     * Return the studyplan for this line
     */
    public function studyplan() : studyplan {
        return $this->studyplan;
    }

    /**
     * Return the studyplan page for this line
     */
    public function page() : studyplanpage {
        return $this->page;
    }

    /**
     * Find record in database and return management object
     * @param int $id Id of database record
     */
    public static function find_by_id($id): self {
        if (!array_key_exists($id, self::$cache)) {
            self::$cache[$id] = new self($id);
        }
        return self::$cache[$id];
    }

    /**
     * Construct new instance from DB record
     * @param int $id Id of database record
     */
    private function __construct($id) {
        global $DB;
        $this->id = $id;
        $this->r = $DB->get_record(self::TABLE, ['id' => $id]);
        $this->page = studyplanpage::find_by_id($this->r->page_id);
        $this->studyplan = $this->page->studyplan();
    }

    /**
     * Return database identifier
     */
    public function id() : int {
        return $this->id;
    }

    /**
     * Return full name
     */
    public function name() : string {
        return $this->r->name;
    }

    /**
     * Return short name
     */
    public function shortname() : string {
        return $this->r->shortname;
    }

    /**
     * Webservice structure for editor info
     * @param int $value Webservice requirement constant
     */
    public static function editor_structure($value = VALUE_REQUIRED) : \external_description {
        return new \external_single_structure([
            "id" => new \external_value(PARAM_INT, 'id of studyline'),
            "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'),
            "shortname" => new \external_value(PARAM_TEXT, 'idnumber of studyline'),
            "color" => new \external_value(PARAM_TEXT, 'description of studyline'),
            "sequence" => new \external_value(PARAM_INT, 'order of studyline'),
            "slots" => new \external_multiple_structure(
                new \external_single_structure([
                    self::SLOTSET_COURSES => new \external_multiple_structure(
                                                    studyitem::editor_structure(), 'competency items', VALUE_OPTIONAL),
                    self::SLOTSET_FILTER => new \external_multiple_structure(
                                                    studyitem::editor_structure(), 'filter items'),
                ])
            )
        ]);
    }

    /**
     * Webservice model for editor info
     * @return array Webservice data model
     */
    public function editor_model() : array {
        return $this->generate_model("editor");
    }

    /**
     * Create a model for the given type of operation
     * @param string $mode One of [ 'editor', 'export']
     */
    protected function generate_model($mode) : array {
        // Mode parameter is used to geep this function for both editor model and export model.
        // (Export model results in fewer parameters on children, but is otherwise basically the same as this function).
        global $DB;

        $model = [
            'id' => $this->r->id,
            'name' => $this->r->name,
            'shortname' => $this->r->shortname,
            'color' => $this->r->color,
            'sequence' => $this->r->sequence,
            'slots' => [],
        ];
        if ($mode == "export") {
            // Id and sequence are not used in export model.
            unset($model["id"]);
            unset($model["sequence"]);
        }

        // TODO: Make this a little nicer.
        // Get the number of slots.
        // As a safety data integrity measure, if there are any items in a higher slot than currently allowed, .
        // Make sure there are enought slots to account for them.
        // Alternatively, we could ensure that on reduction of slots, the items that no longer have a slot will be removed.
        $maxslot = $DB->get_field_select(studyitem::TABLE, "MAX(slot)", "line_id = :lineid", ['lineid' => $this->id]);
        $numslots = max($this->page->periods(), $maxslot + 1);

        // Create the required amount of slots.
        for ($i = 0; $i < $numslots + 1; $i++) {
            if ($mode == "export") {
                // Export mode does not separate between filter or competency type, since that is determined automatically.
                $slots = [];
            } else {
                if ($i > 0) {
                    $slots = [self::SLOTSET_COURSES => [], self::SLOTSET_FILTER => []];
                } else {
                    $slots = [self::SLOTSET_FILTER => []];
                }
            }
            $model['slots'][$i] = $slots;
        }

        $children = studyitem::find_studyline_children($this);
        foreach ($children as $c) {
            if ($mode == "export") {
                $model['slots'][$c->slot()][] = $c->export_model();
            } else {
                $slotset = null;
                if ($c->slot() > 0) {
                    if (in_array($c->type(), self::COURSE_TYPES)) {
                        $slotset = self::SLOTSET_COURSES;
                    } else if (in_array($c->type(), self::FILTER_TYPES)) {
                        $slotset = self::SLOTSET_FILTER;
                    }
                } else if (in_array($c->type(), self::FILTER0_TYPES)) {
                    $slotset = self::SLOTSET_FILTER;
                }
                if (isset($slotset)) {
                    $model['slots'][$c->slot()][$slotset][] = $c->editor_model();
                }
            }
        }
        return $model;
    }


    /**
     * Add a new study line
     * @param array $fields Properties for study line ['page_id', 'name', 'shortname', 'color']
     */
    public static function add($fields) : self {
        global $DB;

        if (!isset($fields['page_id'])) {
            throw new \InvalidArgumentException("parameter 'page_id' missing");
        }

        $pageid = $fields['page_id'];
        $sqmax = $DB->get_field_select(self::TABLE, "MAX(sequence)", "page_id = :page_id", ['page_id' => $pageid]);
        $addable = ['page_id', 'name', 'shortname', 'color'];
        $info = ['sequence' => $sqmax + 1];
        foreach ($addable as $f) {
            if (array_key_exists($f, $fields)) {
                $info[$f] = $fields[$f];
            }
        }
        $id = $DB->insert_record(self::TABLE, $info);
        return self::find_by_id($id);
    }

    /**
     * Edit study line properties
     * @param array $fields Changed roperties for study line ['name', 'shortname', 'color']
     */
    public function edit($fields) : self {
        global $DB;
        $editable = ['name', 'shortname', 'color'];
        $info = ['id' => $this->id, ];
        foreach ($editable as $f) {
            if (array_key_exists($f, $fields)) {
                $info[$f] = $fields[$f];
            }
        }
        $DB->update_record(self::TABLE, $info);
        // Reload record after edit.
        $this->r = $DB->get_record(self::TABLE, ['id' => $this->id], "*", MUST_EXIST);
        return $this;
    }

    /**
     * Delete studyline
     * @param bool $force Force deletion even if study line contains items
     */
    public function delete($force = false) : success {
        global $DB;

        if ($force) {
            $children = studyitem::find_studyline_children($this);
            foreach ($children as $c) {
                $c->delete($force);
            }
        }
        // Check if this item has study items in it.
        if ($DB->count_records(studyitem::TABLE, ['line_id' => $this->id]) > 0) {
            return success::fail('cannot delete studyline with items');
        } else {
            $DB->delete_records(self::TABLE, ['id' => $this->id]);
            return success::success();
        }
    }

    /**
     * Reorder study lines
     * @param int[] $resequence New order of study lines by id
     */
    public static function reorder($resequence) : success {
        global $DB;

        foreach ($resequence as $sq) {
            $DB->update_record(self::TABLE, [
                'id' => $sq['id'],
                'sequence' => $sq['sequence'],
            ]);
        }

        return success::success();
    }

    /**
     * Find all studylines associated with a studyplan page
     * @param studyplanpage $page The studyplanpage to search for
     * @return studyline[]
     */
    public static function find_page_children(studyplanpage $page) : array {
        global $DB;
        $list = [];
        $ids = $DB->get_fieldset_select(self::TABLE, "id", "page_id = :page_id ORDER BY sequence",
                                        ['page_id' => $page->id()]);
        foreach ($ids as $id) {
            $list[] = self::find_by_id($id);
        }
        return $list;
    }

    /**
     * Webservice structure for userinfo
     * @param int $value Webservice requirement constant
     */
    public static function user_structure($value = VALUE_REQUIRED) : \external_description {
        return new \external_single_structure([
            "id" => new \external_value(PARAM_INT, 'id of studyline'),
            "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'),
            "shortname" => new \external_value(PARAM_TEXT, 'idnumber of studyline'),
            "color" => new \external_value(PARAM_TEXT, 'description of studyline'),
            "sequence" => new \external_value(PARAM_INT, 'order of studyline'),
            "slots" => new \external_multiple_structure(
                new \external_single_structure([
                    self::SLOTSET_COURSES => new \external_multiple_structure(
                                                        studyitem::user_structure(), 'competency items', VALUE_OPTIONAL),
                    self::SLOTSET_FILTER => new \external_multiple_structure(
                                                        studyitem::user_structure(), 'filter items'),
                ])
            )
        ], 'Studyline with user info', $value);
    }

    /**
     * Webservice model for user info
     * @param int $userid ID of user to check specific info for
     * @return array Webservice data model
     */
    public function user_model($userid) {
        // TODO: Integrate this function into generate_model() for ease of maintenance.

        global $DB;

        $model = [
            'id' => $this->r->id,
            'name' => $this->r->name,
            'shortname' => $this->r->shortname,
            'color' => $this->r->color,
            'sequence' => $this->r->sequence,
            'slots' => [],
        ];

        // Get the number of slots.
        // As a safety data integrity measure, if there are any items in a higher slot than currently allowed, .
        // Make sure there are enought slots to account for them.
        // Alternatively, we could ensure that on reduction of slots, the items that no longer have a slot will be removed.
        $maxslot = $DB->get_field_select(studyitem::TABLE, "MAX(slot)", "line_id = :lineid", ['lineid' => $this->id]);
        $numslots = max($this->page->periods(), $maxslot + 1);

        // Create the required amount of slots.
        for ($i = 0; $i < $numslots + 1; $i++) {
            if ($i > 0) {
                $slots = [self::SLOTSET_COURSES => [], self::SLOTSET_FILTER => []];
            } else {
                $slots = [self::SLOTSET_FILTER => []];
            }
            $model['slots'][$i] = $slots;
        }

        $children = studyitem::find_studyline_children($this);
        foreach ($children as $c) {
            if ($c->valid()) {
                $slotset = null;
                if ($c->slot() > 0) {
                    if (in_array($c->type(), self::COURSE_TYPES)) {
                        $slotset = self::SLOTSET_COURSES;
                    } else if (in_array($c->type(), self::FILTER_TYPES)) {
                        $slotset = self::SLOTSET_FILTER;
                    }
                } else if (in_array($c->type(), self::FILTER0_TYPES)) {
                    $slotset = self::SLOTSET_FILTER;
                }
                if (isset($slotset)) {
                    $model['slots'][$c->slot()][$slotset][] = $c->user_model($userid);
                }
            }
        }

        return $model;

    }

    /**
     * Duplicate this studyplan page
     * @param studyplan $newstudyplan Studyplan to copy the line into
     * @param array $translation Mapping array of old item ids to new item ids for connection matching
     */
    public function duplicate($newstudyplan, &$translation) : self {
        global $DB;

        // Clone the database fields.
        $fields = clone $this->r;
        // Set new studyplan id.
        unset($fields->id);
        $fields->studyplan_id = $newstudyplan->id();
        // Create new record with the new data.
        $id = $DB->insert_record(self::TABLE, (array)$fields);
        $new = self::find_by_id($id);

        // Next copy all the study items for this studyline.
        // And record the original and copy id's in the $translation array.
        // So the calling function can connect the new studyitems as required.
        $children = studyitem::find_studyline_children($this);
        $translation = [];
        foreach ($children as $c) {
            $newchild = $c->duplicate($new);
            $translation[$c->id()] = $newchild->id();
        }
        return $new;
    }

    /**
     * Export essential information for export
     * @return array information model
     */
    public function export_model() {
        return $this->generate_model("export");
    }

    /**
     * Import study items into line  from decoded array model
     * @param array $model Decoded array
     * @param array $itemtranslation Link to array to map old item ids to new item ids for connection matching
     * @param array $connections Link to array of connections between item
     * @return null
     */
    public function import_studyitems(array $model, array &$itemtranslation, array &$connections) {
        global $DB;
        foreach ($model as $slot => $slotmodel) {
            $courselayer = 0;
            $filterlayer = 0;
            foreach ($slotmodel as $itemmodel) {
                if ($itemmodel["type"] == "course") {
                    $itemmodel["layer"] = $courselayer;
                    $courselayer++;
                } else {
                    $itemmodel["layer"] = $filterlayer;
                    $filterlayer++;
                }

                $itemmodel["slot"] = $slot;
                $itemmodel["line_id"] = $this->id();
                $item = studyitem::import_item($itemmodel);

                if (!empty($item)) {
                    $itemtranslation[$itemmodel["id"]] = $item->id();

                    if (count($itemmodel["connections"]) > 0) {
                        if (! isset($connections[$item->id()]) || ! is_array($connections[$item->id()])) {
                            $connections[$item->id()] = [];
                        }
                        foreach ($itemmodel["connections"] as $toid) {
                            $connections[$item->id()][] = $toid;
                        }
                    }
                }
            }
        }
    }
}