class.ilStudyProgrammeUserProgress.php

Go to the documentation of this file.

<?php
 
/* Copyright (c) 2015 Richard Klees <richard.klees@concepts-and-training.de> Extended GPL, see docs/LICENSE */
 
require_once("./Modules/StudyProgramme/classes/model/class.ilStudyProgrammeProgress.php");
 
class ilStudyProgrammeUserProgress
{
    protected $progress; // ilStudyProgrammeProgress
 
    public function __construct($a_ids_or_model)
    {
        if ($a_ids_or_model instanceof ilStudyProgrammeProgress) {
            $this->progress = $a_ids_or_model;
        } else {
            if (count($a_ids_or_model) != 3) {
                throw new ilException("ilStudyProgrammeUserProgress::__construct: "
                                     . "expected array with 3 items.");
            }
 
            // TODO: ActiveRecord won't be caching the model objects, since
            // we are not using find. Maybe we should do this ourselves??
            // Or should we instead cache in getInstance?
            $this->progress = array_shift(
                ilStudyProgrammeProgress::where(array( "assignment_id" => $a_ids_or_model[0]
                            , "prg_id" => $a_ids_or_model[1]
                            , "usr_id" => $a_ids_or_model[2]
                            ))->get()
            );
        }
        if ($this->progress === null) {
            throw new ilException("ilStudyProgrammeUserProgress::__construct: Could not find progress.");
        }
    }
 
    public function getStudyProgramme()
    {
        require_once("./Modules/StudyProgramme/classes/class.ilObjStudyProgramme.php");
        $refs = ilObject::_getAllReferences($this->progress->getNodeId());
        if (!count($refs)) {
            throw new ilException("ilStudyProgrammeUserAssignment::getStudyProgramme: "
                                 . "could not find ref_id for program '"
                                 . $this->progress->getNodeId() . "'.");
        }
        return ilObjStudyProgramme::getInstanceByRefId(array_shift($refs));
    }
 
    public function getAssignment()
    {
        require_once("Modules/StudyProgramme/classes/class.ilStudyProgrammeUserAssignment.php");
        return ilStudyProgrammeUserAssignment::getInstance($this->progress->getAssignmentId());
    }
 
    public function getId()
    {
        return $this->progress->getId();
    }
 
    public function getNodeId()
    {
        return $this->progress->getNodeId();
    }
 
    public function getUserId()
    {
        return $this->progress->getUserId();
    }
 
    public function getStatus()
    {
        return $this->progress->getStatus();
    }
 
    public function getAmountOfPoints()
    {
        return $this->progress->getAmountOfPoints();
    }
 
    public function getCurrentAmountOfPoints()
    {
        if ($this->isAccredited()
            || ($this->isSuccessful() && $this->getStudyProgramme()->hasLPChildren())) {
            return $this->getAmountOfPoints();
        }
        return $this->progress->getCurrentAmountOfPoints();
    }
 
    public function getLastChange()
    {
        return $this->progress->getLastChange();
    }
 
    public function getLastChangeBy()
    {
        return $this->progress->getLastChangeBy();
    }
 
    public function getCompletionBy()
    {
        return $this->progress->getCompletionBy();
    }
 
    public function getDeadline()
    {
        return $this->progress->getDeadline();
    }
 
    public function setDeadline($deadline)
    {
        return $this->progress->setDeadline($deadline);
    }
 
    public function delete()
    {
        $this->progress->delete();
    }
 
 
    public function markAccredited($a_user_id)
    {
        if ($this->getStatus() == ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
            $prg = $this->getStudyProgramme();
            if ($prg->getStatus() == ilStudyProgramme::STATUS_OUTDATED) {
                throw new ilException("ilStudyProgrammeUserProgress::markAccredited: "
                                     . "Can't mark as accredited since program is outdated.");
            }
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_ACCREDITED)
                       ->setCompletionBy($a_user_id)
                       ->update();
 
        require_once("Modules/StudyProgramme/classes/class.ilStudyProgrammeEvents.php");
        ilStudyProgrammeEvents::userSuccessful($this);
 
        $this->updateParentStatus();
        return $this;
    }
 
    public function unmarkAccredited()
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_ACCREDITED) {
            throw new ilException("Expected status ACCREDITED.");
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                       ->setCompletionBy(null)
                       ->update();
 
        $this->refreshLPStatus();
 
        $this->updateParentStatus();
        return $this;
    }
 
    public function markFailed($a_user_id)
    {
        $status = array(ilStudyProgrammeProgress::STATUS_COMPLETED
            , ilStudyProgrammeProgress::STATUS_ACCREDITED
            , ilStudyProgrammeProgress::STATUS_NOT_RELEVANT
        );
 
        if (in_array($this->getStatus(), $status)) {
            throw new ilException("Can't mark as failed since program is passed.");
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_FAILED)
            ->setLastChangeBy($a_user_id)
            ->update();
 
        $this->refreshLPStatus();
 
        return $this;
    }
 
    public function markNotFailed()
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_FAILED) {
            throw new ilException("Expected status FAILED.");
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                       ->setCompletionBy(null)
                       ->setLastChangeBy($a_user_id)
                       ->update();
 
        $this->refreshLPStatus();
 
        return $this;
    }
 
    public function markNotRelevant($a_user_id)
    {
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_NOT_RELEVANT)
                       ->setCompletionBy($a_user_id)
                       ->setLastChangeBy($a_user_id)
                       ->update();
 
        $this->updateStatus();
        return $this;
    }
 
    public function markRelevant($a_user_id)
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
            throw new ilException("Expected status IN_PROGRESS.");
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                       ->setCompletionBy($a_user_id)
                       ->setLastChangeBy($a_user_id)
                       ->update();
 
        $this->updateStatus();
        return $this;
    }
 
    public function setRequiredAmountOfPoints($a_points, $a_user_id)
    {
        $this->progress->setAmountOfPoints($a_points)
                       ->setLastChangeBy($a_user_id)
                       ->update();
 
        $this->updateStatus();
        return $this;
    }
 
    public function getMaximumPossibleAmountOfPoints($only_relevant = false)
    {
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() == ilStudyProgramme::MODE_LP_COMPLETED) {
            return $this->getAmountOfPoints();
        }
        $children = $prg->getChildren();
        $ass = $this->progress->getAssignmentId();
        $points = array_map(function ($child) use ($ass, $only_relevant) {
            $relevant = $child->getProgressForAssignment($ass)->isRelevant();
            if ($only_relevant) {
                if ($relevant) {
                    return $child->getProgressForAssignment($ass)->getAmountOfPoints();
                } else {
                    return 0;
                }
            } else {
                return $child->getProgressForAssignment($ass)->getAmountOfPoints();
            }
        }, $children);
 
        return array_reduce($points, function ($a, $b) {
            return $a + $b;
        }, 0);
    }
 
    public function canBeCompleted()
    {
        $prg = $this->getStudyProgramme();
 
        if ($prg->getLPMode() == ilStudyProgramme::MODE_LP_COMPLETED) {
            return true;
        }
 
        if ($this->getMaximumPossibleAmountOfPoints(true) < $this->getAmountOfPoints()) {
            // Fast track
            return false;
        }
 
        $children_progress = $this->getChildrenProgress();
        foreach ($children_progress as $progress) {
            if ($progress->isRelevant() && !$progress->canBeCompleted()) {
                return false;
            }
        }
        return true;
    }
 
    public function hasIndividualModifications()
    {
        return $this->getLastChangeBy() !== null;
    }
 
    public function isSuccessful()
    {
        $status = $this->getStatus();
 
        return $status == ilStudyProgrammeProgress::STATUS_ACCREDITED
            || $status == ilStudyProgrammeProgress::STATUS_COMPLETED;
    }
 
    public function isFailed()
    {
        $status = $this->getStatus();
 
        return $status == ilStudyProgrammeProgress::STATUS_FAILED;
    }
 
    public function recalculateFailedToDeadline()
    {
        $deadline = $this->getDeadline();
        $today = date("Y-m-d");
 
        if ($deadline && $deadline->get(IL_CAL_DATE) < $today) {
            $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_FAILED)
                ->update();
        }
    }
 
    public function isAccredited()
    {
        $status = $this->getStatus();
 
        return $status == ilStudyProgrammeProgress::STATUS_ACCREDITED;
    }
 
    public function isRelevant()
    {
        return $this->getStatus() != ilStudyProgrammeProgress::STATUS_NOT_RELEVANT;
    }
 
    public function updateFromProgramNode()
    {
        if ($this->hasIndividualModifications()) {
            return false;
        }
        if ($this->getStatus() == ilStudyProgrammeProgress::STATUS_COMPLETED) {
            return false;
        }
 
        $prg = $this->getStudyProgramme();
        $this->progress->setAmountOfPoints($prg->getPoints())
                       ->setStatus(
                           $prg->getStatus() == ilStudyProgramme::STATUS_ACTIVE
                                    ? ilStudyProgrammeProgress::STATUS_IN_PROGRESS
                                    : ilStudyProgrammeProgress::STATUS_NOT_RELEVANT
                       )
                       ->update();
 
        $this->updateStatus();
    }
 
    protected function updateStatus()
    {
        $prg = $this->getStudyProgramme();
        if (($prg->getLPMode() == ilStudyProgramme::MODE_LP_COMPLETED
            && $this->getStatus() != ilStudyProgrammeProgress::STATUS_ACCREDITED)
            || $this->getStatus() == ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
            // Nothing to do here, as the status will be set by LP.
            // OR current status is NOT RELEVANT
            return;
        }
 
        $add = function ($a, $b) {
            return $a + $b;
        };
        $get_points = function ($child) {
            if (!$child->isSuccessful()) {
                return 0;
            }
            return $child->getAmountOfPoints();
        };
 
        $achieved_points = array_reduce(array_map($get_points, $this->getChildrenProgress()), $add);
        if (!$achieved_points) {
            $achieved_points = 0;
        }
        $successful = $achieved_points >= $this->getAmountOfPoints() && $this->hasSuccessfullChildren();
        $status = $this->getStatus();
 
        $this->progress->setCurrentAmountOfPoints($achieved_points);
        if ($successful) {
            $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_COMPLETED);
            require_once("Modules/StudyProgramme/classes/class.ilStudyProgrammeEvents.php");
            ilStudyProgrammeEvents::userSuccessful($this);
        } else {
            $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS);
        }
 
        $this->progress->update();
        $this->refreshLPStatus();
        $this->updateParentStatus();
    }
 
    protected function hasSuccessfullChildren()
    {
        foreach ($this->getChildrenProgress() as $child) {
            if ($child->isSuccessful()) {
                return true;
            }
        }
        return false;
    }
 
    protected function updateParentStatus()
    {
        $parent = $this->getParentProgress();
        if ($parent) {
            $parent->updateStatus();
        }
    }
 
    public function setLPCompleted($a_obj_id, $a_usr_id)
    {
        if ($this->isSuccessful() || !$this->isRelevant()) {
            return true;
        }
 
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() != ilStudyProgramme::MODE_LP_COMPLETED) {
            throw new ilException("ilStudyProgrammeUserProgress::setLPCompleted: "
                                 . "The node '" . $prg->getId() . "' is not in LP_COMPLETED mode.");
        }
        if ($this->getUserId() != $a_usr_id) {
            throw new ilException("ilStudyProgrammeUserProgress::setLPCompleted: "
                                 . "This progress does belong to user '" . $this->getUserId()
                                 . "' and not to user '$a_usr_id'");
        }
        if (!in_array($a_obj_id, $prg->getLPChildrenIds())) {
            throw new ilException("ilStudyProgrammeUserProgress::setLPCompleted: "
                                 . "Object '$a_obj_id' is no child of node '" . $prg->getId() . "'.");
        }
 
        $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_COMPLETED)
                       ->setCompletionBy($a_obj_id)
                       ->update();
 
        require_once("Modules/StudyProgramme/classes/class.ilStudyProgrammeEvents.php");
        ilStudyProgrammeEvents::userSuccessful($this);
 
        $this->refreshLPStatus();
        $this->updateParentStatus();
    }
 
    protected function getParentProgress()
    {
        $prg = $this->getStudyProgramme();
        $parent = $prg->getParent();
        if (!$parent) {
            return null;
        }
 
        if ($this->getStudyProgramme()->getId() == $this->getAssignment()->getStudyProgramme()->getId()) {
            return null;
        }
 
        return $parent->getProgressForAssignment($this->progress->getAssignmentId());
    }
 
    public function getChildrenProgress()
    {
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() == ilStudyProgramme::MODE_LP_COMPLETED) {
            throw new ilException("ilStudyProgrammeUserProgress::getChildrenProgress: "
                                 . "There is some problem in the implementation. This "
                                 . "method should only be callled for nodes in points "
                                 . "mode.");
        }
 
        $ass_id = $this->progress->getAssignmentId();
        return array_map(function ($child) use ($ass_id) {
            return $child->getProgressForAssignment($ass_id);
        }, $prg->getChildren());
    }
 
    public function getNamesOfCompletedOrAccreditedChildren()
    {
        $prg = $this->getStudyProgramme();
        $children = $prg->getChildren();
        $ass_id = $this->progress->getAssignmentId();
        $names = array();
        foreach ($children as $child) {
            $prgrs = $child->getProgressForAssignment($ass_id);
            if (!$prgrs->isSuccessful()) {
                continue;
            }
            $names[] = $child->getTitle();
        }
        return $names;
    }
 
    const ACTION_MARK_ACCREDITED = "mark_accredited";
    const ACTION_UNMARK_ACCREDITED = "unmark_accredited";
    const ACTION_SHOW_INDIVIDUAL_PLAN = "show_individual_plan";
    const ACTION_REMOVE_USER = "remove_user";
    public static function getPossibleActions($a_node_id, $a_root_prg_id, $a_status)
    {
        $actions = array();
        if ($a_node_id == $a_root_prg_id) {
            $actions[] = self::ACTION_SHOW_INDIVIDUAL_PLAN;
            $actions[] = self::ACTION_REMOVE_USER;
        }
        if ($a_status == ilStudyProgrammeProgress::STATUS_ACCREDITED) {
            $actions[] = self::ACTION_UNMARK_ACCREDITED;
        } elseif ($a_status == ilStudyProgrammeProgress::STATUS_IN_PROGRESS) {
            $actions[] = self::ACTION_MARK_ACCREDITED;
        }
        return $actions;
    }
 
    protected function refreshLPStatus()
    {
        require_once("Services/Tracking/classes/class.ilLPStatusWrapper.php");
        ilLPStatusWrapper::_refreshStatus($this->getStudyProgramme()->getId(), array($this->getUserId()));
    }
 
    public function updateProgress($user_id)
    {
        $this->progress->setLastChangeBy($user_id)
            ->update();
    }
}