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.");
                }
        }
        
        static public function getInstance($a_assignment_id, $a_program_id, $a_user_id) {
                return new ilStudyProgrammeUserProgress(array($a_assignment_id, $a_program_id, $a_user_id));
        }
        
        static public function getInstanceById($a_prgrs_id) {
                $prgrs = ilStudyProgrammeProgress::find($a_prgrs_id);
                if ($prgrs === null) {
                        throw new ilException("Unknown progress id $a_prgrs_id.");
                }
                return new ilStudyProgrammeUserProgress($prgrs);
        }
        
        static public function getInstancesForUser($a_program_id, $a_user_id) {
                $progresses = ilStudyProgrammeProgress::where(array
                                                        ( "prg_id" => $a_program_id
                                                        , "usr_id" => $a_user_id
                                                        ))->get();
                return array_values(array_map(function($dat) {
                        return new ilStudyProgrammeUserProgress($dat);
                }, $progresses));
        }
        
        static public function getInstanceForAssignment($a_program_id, $a_assignment_id) {
                $progresses = ilStudyProgrammeProgress::where(array
                                                        ( "prg_id" => $a_program_id
                                                        , "assignment_id" => $a_assignment_id
                                                        ))->get();
                if (count($progresses) == 0) {
                        require_once("Modules/StudyProgramme/classes/exceptions/class.ilStudyProgrammeNoProgressForAssignmentException.php");
                        throw new ilStudyProgrammeNoProgressForAssignmentException
                                                                ("ilStudyProgrammeUserProgress::getInstanceForAssignment: "
                                                                ."Assignment '$a_assignment_id' does not belong to program "
                                                                ."'$a_program_id'");
                }
                return new ilStudyProgrammeUserProgress(array_shift($progresses));
        }
        
        static public function getInstancesForAssignment($a_assignment_id) {
                $progresses = ilStudyProgrammeProgress::where(array
                                                        ( "assignment_id" => $a_assignment_id
                                                        ))->get();
                if (count($progresses) == 0) {
                        require_once("Modules/StudyProgramme/classes/exceptions/class.ilStudyProgrammeNoProgressForAssignmentException.php");
                        throw new ilStudyProgrammeNoProgressForAssignmentException
                                                                ("ilStudyProgrammeUserProgress::getInstancesForAssignment: "
                                                                ."Can't find progresses for assignment '$a_assignment_id'.");
                }
                return array_map(function($dat) {
                        return new ilStudyProgrammeUserProgress($dat);
                }, $progresses);
        }
        
        static public function getInstancesForProgram($a_program_id) {
                $progresses = ilStudyProgrammeProgress::where(array
                                                        ( "prg_id" => $a_program_id
                                                        ))->get();
                return array_values(array_map(function($dat) {
                        return new ilStudyProgrammeUserProgress($dat);
                }, $progresses));
        }
        
        static public function statusToRepr($a_status) {
                global $lng;
                $lng->loadLanguageModule("prg");
                
                if ($a_status == ilStudyProgrammeProgress::STATUS_IN_PROGRESS) {
                        return $lng->txt("prg_status_in_progress");
                }
                if ($a_status == ilStudyProgrammeProgress::STATUS_COMPLETED) {
                        return $lng->txt("prg_status_completed");
                }
                if ($a_status == ilStudyProgrammeProgress::STATUS_ACCREDITED) {
                        return $lng->txt("prg_status_accredited");
                }
                if ($a_status == ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
                        return $lng->txt("prg_status_not_relevant");
                }
                throw new ilException("Unknown status: '$a_status'");
        }
        
        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 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 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 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";
        
        static public 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;
                }
                else if ($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()));
        }
}

?>