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 */
/* Copyright (c) 2019 Stefan Hecken <stefan.hecken@concepts-and-training.de> Extended GPL, see docs/LICENSE */
 
declare(strict_types=1);
 
class ilStudyProgrammeUserProgress
{
    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";
    const ACTION_CHANGE_EXPIRE_DATE = "change_expire_date";
    const ACTION_CHANGE_DEADLINE = "change_deadline";
 
    protected $progress;
 
    protected $progress_repository;
 
    protected $assignment_repository;
 
    protected $events;
 
    public function __construct(
        ilStudyProgrammeProgress $progress,
        ilStudyProgrammeProgressRepository $progress_repository,
        ilStudyProgrammeAssignmentRepository $assignment_repository,
        ilStudyProgrammeEvents $events
    ) {
        $this->progress = $progress;
        $this->progress_repository = $progress_repository;
        $this->assignment_repository = $assignment_repository;
        $this->events = $events;
    }
 
    public function getStudyProgramme() : ilObjStudyProgramme
    {
        $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 getAssignmentId() : int
    {
        return $this->progress->getAssignmentId();
    }
 
    public function getId() : int
    {
        return $this->progress->getId();
    }
 
    public function getNodeId() : int
    {
        return $this->progress->getNodeId();
    }
 
    public function getUserId() : int
    {
        return $this->progress->getUserId();
    }
 
    public function getStatus() : int
    {
        return $this->progress->getStatus();
    }
 
    public function getAmountOfPoints() : int
    {
        return $this->progress->getAmountOfPoints();
    }
 
    public function getCurrentAmountOfPoints() : int
    {
        if (
            $this->isAccredited() ||
            ($this->isSuccessful() && $this->getStudyProgramme()->hasLPChildren())
        ) {
            return $this->getAmountOfPoints();
        }
 
        return $this->progress->getCurrentAmountOfPoints();
    }
 
    public function getLastChange() : DateTime
    {
        return $this->progress->getLastChange();
    }
 
    public function getLastChangeBy() : ?int
    {
        return $this->progress->getLastChangeBy();
    }
 
    public function getCompletionBy()
    {
        return $this->progress->getCompletionBy();
    }
 
    public function getAssignmentDate() : DateTime
    {
        return $this->progress->getAssignmentDate();
    }
 
    public function getCompletionDate() : ?DateTime
    {
        return $this->progress->getCompletionDate();
    }
 
    public function getDeadline()
    {
        return $this->progress->getDeadline();
    }
 
    public function setDeadline(DateTime $deadline = null) : ilStudyProgrammeProgress
    {
        return $this->progress->setDeadline($deadline);
    }
 
    public function getValidityOfQualification() : ?DateTime
    {
        return $this->progress->getValidityOfQualification();
    }
 
    public function setValidityOfQualification(DateTime $date = null) : void
    {
        $this->progress->setValidityOfQualification($date);
    }
 
    public function storeProgress() : void
    {
        $this->progress_repository->update($this->progress);
    }
 
    public function delete() : void
    {
        $this->progress_repository->delete($this->progress);
    }
 
 
    public function markAccredited(int $user_id) : ilStudyProgrammeUserProgress
    {
        $prg = $this->getStudyProgramme();
        if ($this->getStatus() == ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
            if ($prg->getStatus() == ilStudyProgrammeSettings::STATUS_OUTDATED) {
                throw new ilException(
                    "ilStudyProgrammeUserProgress::markAccredited: "
                    . "Can't mark as accredited since program is outdated."
                );
            }
        }
        $progress = $this->progress
            ->setStatus(ilStudyProgrammeProgress::STATUS_ACCREDITED)
            ->setCompletionBy($user_id)
            ->setLastChangeBy($user_id)
            ->setLastChange(new DateTime())
            ->setCompletionDate(new DateTime())
        ;
 
        $this->progress_repository->update($progress);
 
        $assignment = $this->assignment_repository->read($this->getAssignmentId());
        if ((int) $prg->getId() === $assignment->getRootId()) {
            $this->maybeLimitProgressValidity($prg, $assignment);
        }
 
        $this->events->userSuccessful($this);
        $this->updateParentStatus();
 
        return $this;
    }
 
    public function unmarkAccredited() : ilStudyProgrammeUserProgress
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_ACCREDITED) {
            throw new ilException("Expected status ACCREDITED.");
        }
 
        $this->progress_repository->update(
            $this->progress
                ->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                ->setCompletionBy(null)
                ->setCompletionDate(null)
        );
 
        $this->refreshLPStatus();
        $this->updateParentStatus();
 
        return $this;
    }
 
    public function markFailed(int $a_user_id) : ilStudyProgrammeUserProgress
    {
        $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)
            ->setCompletionDate(null);
 
        $this->progress_repository->update($this->progress);
        $this->refreshLPStatus();
 
        return $this;
    }
 
    public function invalidate() : ilStudyProgrammeUserProgress
    {
        $status = array(
            ilStudyProgrammeProgress::STATUS_COMPLETED,
            ilStudyProgrammeProgress::STATUS_ACCREDITED,
            ilStudyProgrammeProgress::STATUS_NOT_RELEVANT
        );
 
        if (in_array($this->getStatus(), $status) && !$this->isSuccessfulExpired()) {
            throw new ilException("Can't mark as failed since program is passed.");
        }
 
        $this->progress_repository->update(
            $this->progress->invalidate()
        );
 
        $this->refreshLPStatus();
 
        return $this;
    }
 
    public function isInvalidated() : bool
    {
        return $this->progress->isInvalidated();
    }
 
    public function isSuccessfulExpired() : bool
    {
        if ($this->getValidityOfQualification() === null) {
            return false;
        }
 
        if (!$this->isSuccessful()) {
            return false;
        }
 
        if (
            $this->getValidityOfQualification()->format('Y-m-d') < (new DateTime())->format('Y-m-d')
        ) {
            return true;
        }
 
        return false;
    }
 
    public function markNotFailed(int $user_id) : ilStudyProgrammeUserProgress
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_FAILED) {
            throw new ilException("Expected status FAILED.");
        }
 
        $this->progress_repository->update(
            $this->progress
                ->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                ->setCompletionBy(null)
                ->setLastChangeBy($user_id)
        );
 
        $this->refreshLPStatus();
 
        return $this;
    }
 
    public function markNotRelevant(int $user_id) : ilStudyProgrammeUserProgress
    {
        $this->progress_repository->update(
            $this->progress
                ->setStatus(ilStudyProgrammeProgress::STATUS_NOT_RELEVANT)
                ->setCompletionBy($user_id)
                ->setLastChangeBy($user_id)
        );
 
        $this->updateStatus();
 
        return $this;
    }
 
    public function markRelevant(int $user_id) : ilStudyProgrammeUserProgress
    {
        if ($this->progress->getStatus() != ilStudyProgrammeProgress::STATUS_NOT_RELEVANT) {
            throw new ilException("Expected status IN_PROGRESS.");
        }
 
        $this->progress_repository->update(
            $this->progress
                ->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS)
                ->setCompletionBy($user_id)
                ->setLastChangeBy($user_id)
        );
 
        $this->updateStatus();
 
        return $this;
    }
 
    public function setRequiredAmountOfPoints(
        int $a_points,
        int $user_id
    ) : ilStudyProgrammeUserProgress {
        $this->progress_repository->update(
            $this->progress
                ->setAmountOfPoints($a_points)
                ->setLastChangeBy($user_id)
        );
 
        $this->updateStatus();
 
        return $this;
    }
 
    public function getMaximumPossibleAmountOfPoints(bool $only_relevant = false) : int
    {
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() == ilStudyProgrammeSettings::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() : bool
    {
        $prg = $this->getStudyProgramme();
 
        if ($prg->getLPMode() == ilStudyProgrammeSettings::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() : bool
    {
        return $this->getLastChangeBy() !== null;
    }
 
    public function isSuccessful() : bool
    {
        $status = $this->getStatus();
 
        return
            $status == ilStudyProgrammeProgress::STATUS_ACCREDITED ||
            $status == ilStudyProgrammeProgress::STATUS_COMPLETED
        ;
    }
 
    public function isFailed() : bool
    {
        $status = $this->getStatus();
 
        return $status == ilStudyProgrammeProgress::STATUS_FAILED;
    }
 
    public function recalculateFailedToDeadline() : void
    {
        $deadline = $this->getDeadline();
        $today = date(ilStudyProgrammeProgress::DATE_FORMAT);
 
        if ($deadline
            && $deadline->format(ilStudyProgrammeProgress::DATE_FORMAT) < $today
            && $this->progress->getStatus() === ilStudyProgrammeProgress::STATUS_IN_PROGRESS
        ) {
            $this->progress_repository->update(
                $this->progress
                    ->setStatus(ilStudyProgrammeProgress::STATUS_FAILED)
            );
        }
    }
 
    public function isAccredited() : bool
    {
        return $this->getStatus() == ilStudyProgrammeProgress::STATUS_ACCREDITED;
    }
 
    public function isRelevant() : bool
    {
        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();
 
        $status = ilStudyProgrammeProgress::STATUS_NOT_RELEVANT;
        if ($prg->getStatus() == ilStudyProgrammeSettings::STATUS_ACTIVE) {
            $status = ilStudyProgrammeProgress::STATUS_IN_PROGRESS;
        }
 
        $this->progress_repository->update(
            $this->progress
                ->setAmountOfPoints($prg->getPoints())
                ->setStatus($status)
        );
 
        $this->updateStatus();
    }
 
    protected function updateStatus()
    {
        $prg = $this->getStudyProgramme();
        if (
            ($prg->getLPMode() == ilStudyProgrammeSettings::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();
        $this->progress->setCurrentAmountOfPoints($achieved_points);
 
        if ($successful) {
            $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_COMPLETED);
            if (!$this->progress->getCompletionDate()) {
                $this->progress->setCompletionDate(new DateTime());
            }
 
            $assignment = $this->assignment_repository->read($this->getAssignmentId());
            if ((int) $prg->getId() === $assignment->getRootId()) {
                $this->maybeLimitProgressValidity($prg, $assignment);
            }
            $this->events->userSuccessful($this);
        } else {
            $this->progress->setStatus(ilStudyProgrammeProgress::STATUS_IN_PROGRESS);
            $this->progress->setCompletionDate(null);
        }
 
        $this->progress_repository->update(
            $this->progress
        );
 
        $this->refreshLPStatus();
        $this->updateParentStatus();
    }
 
    protected function hasSuccessfullChildren() : bool
    {
        foreach ($this->getChildrenProgress() as $child) {
            if ($child->isSuccessful()) {
                return true;
            }
        }
 
        return false;
    }
 
    protected function updateParentStatus() : void
    {
        foreach ($this->getParentProgresses() as $parent) {
            $parent->updateStatus();
        }
    }
 
    public function setLPCompleted(int $obj_id, int $usr_id)
    {
        if ($this->isSuccessful() || !$this->isRelevant()) {
            return true;
        }
 
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() != ilStudyProgrammeSettings::MODE_LP_COMPLETED) {
            throw new ilException(
                "ilStudyProgrammeUserProgress::setLPCompleted: "
                . "The node '" . $prg->getId() . "' is not in LP_COMPLETED mode."
            );
        }
 
        if ($this->getUserId() != $usr_id) {
            throw new ilException(
                "ilStudyProgrammeUserProgress::setLPCompleted: "
                . "This progress does belong to user '" . $this->getUserId()
                . "' and not to user '$usr_id'"
            );
        }
 
        if (!in_array($obj_id, $prg->getLPChildrenIds())) {
            throw new ilException(
                "ilStudyProgrammeUserProgress::setLPCompleted: "
                . "Object '$obj_id' is no child of node '" . $prg->getId() . "'."
            );
        }
 
        $this->progress_repository->update(
            $this->progress
                ->setStatus(ilStudyProgrammeProgress::STATUS_COMPLETED)
                ->setCompletionBy($obj_id)
                ->setCompletionDate(new DateTime())
        );
 
        $this->refreshLPStatus();
 
        $assignment = $this->assignment_repository->read($this->getAssignmentId());
        if ((int) $prg->getId() === $assignment->getRootId()) {
            $this->maybeLimitProgressValidity($prg, $assignment);
        }
 
        $this->events->userSuccessful($this);
        $this->updateParentStatus();
    }
 
    protected function maybeLimitProgressValidity(
        ilObjStudyProgramme $prg,
        ilStudyProgrammeAssignment $assignment
    ) : void {
        $qualification_date = $prg->getValidityOfQualificationSettings()->getQualificationDate();
        $qualification_period = $prg->getValidityOfQualificationSettings()->getQualificationPeriod();
        if (!is_null($qualification_date)) {
            $date = $qualification_date;
        } elseif (
            ilStudyProgrammeSettings::NO_VALIDITY_OF_QUALIFICATION_PERIOD !== $qualification_period
        ) {
            $date = new DateTime();
            $date->add(new DateInterval('P' . $qualification_period . 'D'));
        } else {
            // nothing to do
            return;
        }
 
        $this->progress_repository->update($this->progress->setValidityOfQualification($date));
 
        $restart_period = $prg->getValidityOfQualificationSettings()->getRestartPeriod();
        if (ilStudyProgrammeSettings::NO_RESTART !== $restart_period) {
            $date->sub(new DateInterval('P' . $restart_period . 'D'));
            $this->assignment_repository->update($assignment->setRestartDate($date));
        }
    }
 
    protected function getParentProgresses() : array
    {
        if ($this->getStudyProgramme()->getId() == $this->assignment_repository->read($this->getAssignmentId())->getRootId()) {
            return [];
        }
 
        $overall_parents = [];
        $prg = $this->getStudyProgramme();
        $parent = $prg->getParent();
 
        if ($parent) {
            $overall_parents[] = $parent;
        }
 
        foreach ($prg->getReferencesToSelf() as $ref) {
            $overall_parents[] = $ref->getParent();
        }
 
        return array_map(
            function ($parent) {
                return $parent->getProgressForAssignment($this->progress->getAssignmentId());
            },
            $overall_parents
        );
    }
 
    public function getChildrenProgress() : array
    {
        $prg = $this->getStudyProgramme();
        if ($prg->getLPMode() == ilStudyProgrammeSettings::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(true));
    }
 
    public function getNamesOfCompletedOrAccreditedChildren() : array
    {
        $prg = $this->getStudyProgramme();
        $children = $prg->getChildren(true);
        $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;
    }
 
    public static function getPossibleActions(
        int $node_id,
        int $root_prg_id,
        int $status
    ) : array {
        $actions = array();
 
        if ($node_id == $root_prg_id) {
            $actions[] = self::ACTION_SHOW_INDIVIDUAL_PLAN;
            $actions[] = self::ACTION_REMOVE_USER;
        }
 
        if ($status == ilStudyProgrammeProgress::STATUS_ACCREDITED) {
            $actions[] = self::ACTION_UNMARK_ACCREDITED;
        } elseif ($status == ilStudyProgrammeProgress::STATUS_IN_PROGRESS) {
            $actions[] = self::ACTION_MARK_ACCREDITED;
        }
 
        return $actions;
    }
 
    protected function refreshLPStatus() : void
    {
        // thanks to some caching within ilLPStatusWrapper
        // the status may not be read properly otherwise ...
        ilLPStatusWrapper::_resetInfoCaches($this->progress->getNodeId());
        ilLPStatusWrapper::_refreshStatus(
            $this->getStudyProgramme()->getId(),
            array($this->getUserId())
        );
    }
 
    public function updateProgress(int $user_id) : void
    {
        $this->progress_repository->update(
            $this->progress->setLastChangeBy($user_id)
        );
    }
 
    public function informUserForRiskToFail() : void
    {
        $this->events->userRiskyToFail($this);
    }
 
    public static function sendRiskyToFailMail(int $progress_id, int $usr_id) : void
    {
        global $DIC;
        $lng = $DIC['lng'];
        $log = $DIC['ilLog'];
        $lng->loadLanguageModule("prg");
        $lng->loadLanguageModule("mail");
 
        $usr_progress_db = ilStudyProgrammeDIC::dic()['ilStudyProgrammeUserProgressDB'];
        $usr_progress = $usr_progress_db->getInstanceById($progress_id);
        $prg = $usr_progress->getStudyProgramme();
 
        if (!$prg->shouldSendRiskyToFailMail()) {
            $log->write("Send risky to fail mail is deactivated in study programme settings");
            return;
        }
 
        $subject = $lng->txt("risky_to_fail_mail_subject");
        $gender = ilObjUser::_lookupGender($usr_id);
        $name = ilObjUser::_lookupFullname($usr_id);
        $body = sprintf(
            $lng->txt("risky_to_fail_mail_body"),
            $lng->txt("mail_salutation_" . $gender),
            $name,
            $prg->getTitle()
        );
 
        $send = true;
        $mail = new ilMail(ANONYMOUS_USER_ID);
        try {
            $mail->enqueue(
                ilObjUser::_lookupLogin($usr_id),
                '',
                '',
                $subject,
                $body,
                null
            );
        } catch (Exception $e) {
            $send = false;
        }
 
        if ($send) {
            $usr_progress_db->reminderSendFor($usr_progress->getId());
        }
    }
 
    public function hasSuccessStatus() : bool
    {
        return in_array(
            $this->getStatus(),
            [
                ilStudyProgrammeProgress::STATUS_COMPLETED,
                ilStudyProgrammeProgress::STATUS_ACCREDITED
            ]
        );
    }
}