class.ilObjLTITool.php

Go to the documentation of this file.

<?php
 
declare(strict_types=1);
 
class ilObjLTITool extends ilObject2
{
    public const string TABLE_NAME = 'lti_consumer_settings';
 
    public const string LAUNCH_METHOD_OWN_WIN = 'ownWin';
    public const string LAUNCH_METHOD_NEW_WIN = 'newWin';
    public const string LAUNCH_METHOD_EMBEDDED = 'embedded';
 
    public const int HIGHSCORE_SHOW_ALL_TABLES = 1;
    public const int HIGHSCORE_SHOW_TOP_TABLE = 2;
    public const int HIGHSCORE_SHOW_OWN_TABLE = 3;
 
    private int $tool_id = 0;
    private ?ilLTITool $tool = null;
    private string $launch_method = self::LAUNCH_METHOD_NEW_WIN;
    private string $custom_params = '';
    private ?ilLTI1p1ConsumerObjectCredentials $lti_1p1_credentials = null;
    private float $mastery_score = 0.5;
    private float $score_maximum = 1.0;
    private bool $use_xapi = false;
    private string $custom_activity_id = '';
    private bool $statements_report_enabled = false;
    private bool $highscore_enabled = false;
    private bool $highscore_achieved_ts = true;
    private bool $highscore_percentage = true;
    private bool $highscore_wtime = true;
    private bool $highscore_own_table = true;
    private bool $highscore_top_table = true;
    private int $highscore_top_num = 10;
 
    protected function initType(): void
    {
        $this->type = 'lti';
    }
 
    public function getToolId(): int
    {
        return $this->tool_id;
    }
 
    public function setToolId(int $tool_id): void
    {
        $this->tool_id = $tool_id;
        $this->tool = null;
    }
 
    public function getTool(): ilLTITool
    {
        return $this->tool ??= new ilLTITool($this->getToolId());
    }
 
    public function getLaunchMethod(): string
    {
        return $this->launch_method;
    }
 
    public function setLaunchMethod(string $launch_method): void
    {
        $this->launch_method = $launch_method;
    }
 
    public function isLaunchMethodOwnWin(): bool
    {
        return $this->launch_method === self::LAUNCH_METHOD_OWN_WIN;
    }
 
    public function isLaunchMethodEmbedded(): bool
    {
        return $this->launch_method === self::LAUNCH_METHOD_EMBEDDED;
    }
 
    public function getCustomParams(): string
    {
        return $this->custom_params;
    }
 
    public function setCustomParams(string $custom_params): void
    {
        $this->custom_params = $custom_params;
    }
 
    public function getMasteryScore(): float
    {
        return $this->mastery_score;
    }
 
    public function setMasteryScore(float $mastery_score): void
    {
        $this->mastery_score = $mastery_score;
    }
 
    public function getScoreMaximum(): float
    {
        return $this->score_maximum;
    }
 
    public function setScoreMaximum(float $score_maximum): void
    {
        $this->score_maximum = $score_maximum;
    }
 
    public function getUseXapi(): bool
    {
        return $this->use_xapi && $this->getTool()->getUseXapi();
    }
 
    public function setUseXapi(bool $use_xapi): void
    {
        $this->use_xapi = $use_xapi;
    }
 
    public function getCustomActivityId(): string
    {
        return $this->custom_activity_id;
    }
 
    public function setCustomActivityId(string $custom_activity_id): void
    {
        $this->custom_activity_id = $custom_activity_id;
    }
 
    public function getActivityId(): string
    {
        $tool_activity_id = $this->getTool()->getXapiActivityId();
 
        return $tool_activity_id !== '' ? $tool_activity_id : $this->custom_activity_id;
    }
 
    public function isStatementsReportEnabled(): bool
    {
        return $this->statements_report_enabled;
    }
 
    public function setStatementsReportEnabled(bool $enabled): void
    {
        $this->statements_report_enabled = $enabled;
    }
 
    public function getHighscoreEnabled(): bool
    {
        return $this->highscore_enabled;
    }
 
    public function setHighscoreEnabled(bool $enabled): void
    {
        $this->highscore_enabled = $enabled;
    }
 
    public function getHighscoreAchievedTS(): bool
    {
        return $this->highscore_achieved_ts;
    }
 
    public function setHighscoreAchievedTS(bool $shown): void
    {
        $this->highscore_achieved_ts = $shown;
    }
 
    public function getHighscorePercentage(): bool
    {
        return $this->highscore_percentage;
    }
 
    public function setHighscorePercentage(bool $shown): void
    {
        $this->highscore_percentage = $shown;
    }
 
    public function getHighscoreWTime(): bool
    {
        return $this->highscore_wtime;
    }
 
    public function setHighscoreWTime(bool $shown): void
    {
        $this->highscore_wtime = $shown;
    }
 
    public function getHighscoreOwnTable(): bool
    {
        return $this->highscore_own_table;
    }
 
    public function getHighscoreTopTable(): bool
    {
        return $this->highscore_top_table;
    }
 
    public function getHighscoreMode(): int
    {
        return match (true) {
            $this->highscore_own_table && $this->highscore_top_table => self::HIGHSCORE_SHOW_ALL_TABLES,
            $this->highscore_top_table => self::HIGHSCORE_SHOW_TOP_TABLE,
            default => self::HIGHSCORE_SHOW_OWN_TABLE,
        };
    }
 
    public function setHighscoreMode(int $mode): void
    {
        $this->highscore_own_table = $mode !== self::HIGHSCORE_SHOW_TOP_TABLE;
        $this->highscore_top_table = $mode !== self::HIGHSCORE_SHOW_OWN_TABLE;
    }
 
    public function getHighscoreTopNum(): int
    {
        return $this->highscore_top_num > 0 ? $this->highscore_top_num : 10;
    }
 
    public function setHighscoreTopNum(int $top_num): void
    {
        $this->highscore_top_num = $top_num;
    }
 
    public function isMixedContentType(): bool
    {
        return true;
    }
 
    public function getContentType(): string
    {
        return ilObjCmiXapi::CONT_TYPE_GENERIC;
    }
 
    public function getProvider(): ilLTITool
    {
        return $this->getTool();
    }
 
    public static function getInstance(int $id = 0, bool $reference = true): self
    {
        return new self($id, $reference);
    }
 
    public function getLti1p1Credentials(): ilLTI1p1ConsumerObjectCredentials
    {
        return $this->lti_1p1_credentials ??= new ilLTI1p1ConsumerObjectCredentials();
    }
 
    public function getCustomParamsArray(): array
    {
        return self::parseCustomParams($this->getCustomParams());
    }
 
    public function syncKeywordsFromTool(): void
    {
        global $DIC;
 
        $lom = $DIC->learningObjectMetadata();
        $lom->manipulate($this->getId(), 0, $this->getType())
            ->prepareDelete($lom->paths()->keywords())
            ->execute();
 
        $keywords = $this->getTool()->getKeywords();
        if ($keywords !== []) {
            $lom->manipulate($this->getId(), 0, $this->getType())
                ->prepareCreateOrUpdate($lom->paths()->keywords(), ...$keywords)
                ->execute();
        }
    }
 
    protected function doRead(): void
    {
        global $DIC;
 
        $db = $DIC->database();
        $row = $db->fetchAssoc($db->queryF(
            'SELECT * FROM ' . self::TABLE_NAME . ' WHERE obj_id = %s',
            ['integer'],
            [$this->getId()]
        ));
        if ($row === null) {
            return;
        }
 
        $this->setToolId((int) $row['provider_id']);
        $this->setLaunchMethod((string) $row['launch_method']);
        $this->setCustomParams((string) $row['custom_params']);
        $this->mastery_score = (float) $row['mastery_score'];
        $this->score_maximum = (float) ($row['score_maximum'] ?? 0) > 0 ? (float) $row['score_maximum'] : 1.0;
        $this->use_xapi = (bool) $row['use_xapi'];
        $this->custom_activity_id = (string) $row['activity_id'];
        $this->statements_report_enabled = (bool) $row['show_statements'];
        $this->highscore_enabled = (bool) $row['highscore_enabled'];
        $this->highscore_achieved_ts = (bool) $row['highscore_achieved_ts'];
        $this->highscore_percentage = (bool) $row['highscore_percentage'];
        $this->highscore_wtime = (bool) $row['highscore_wtime'];
        $this->highscore_own_table = (bool) $row['highscore_own_table'];
        $this->highscore_top_table = (bool) $row['highscore_top_table'];
        $this->highscore_top_num = (int) $row['highscore_top_num'];
        $this->getLti1p1Credentials()->assignFromDbRow($row);
    }
 
    protected function doCreate(bool $clone_mode = false): void
    {
        global $DIC;
 
        $DIC->database()->insert(
            self::TABLE_NAME,
            ['obj_id' => ['integer', $this->getId()]] + $this->getDbFields()
        );
    }
 
    protected function doUpdate(): void
    {
        global $DIC;
 
        $DIC->database()->update(
            self::TABLE_NAME,
            $this->getDbFields(),
            ['obj_id' => ['integer', $this->getId()]]
        );
    }
 
    protected function doCloneObject(ilObject2 $new_obj, int $a_target_id, ?int $a_copy_id = null): void
    {
        global $DIC;
 
        $this->cloneMetaData($new_obj);
 
        $DIC->database()->update(
            self::TABLE_NAME,
            $this->getDbFields(),
            ['obj_id' => ['integer', $new_obj->getId()]]
        );
        $new_obj->read();
 
        (new ilLPObjSettings($this->getId()))->cloneSettings($new_obj->getId());
    }
 
    protected function doDelete(): void
    {
        global $DIC;
 
        $db = $DIC->database();
        // the scores and results of the users go with the object
        foreach ([self::TABLE_NAME, 'lti_consumer_results', 'lti_consumer_grades'] as $table) {
            $db->manipulateF(
                'DELETE FROM ' . $table . ' WHERE obj_id = %s',
                ['integer'],
                [$this->getId()]
            );
        }
    }
 
    private function getDbFields(): array
    {
        return $this->getLti1p1Credentials()->getDbFields() + [
            'provider_id' => ['integer', $this->getToolId()],
            'launch_method' => ['text', $this->getLaunchMethod()],
            'custom_params' => ['text', $this->getCustomParams()],
            'mastery_score' => ['float', $this->mastery_score],
            'score_maximum' => ['float', $this->score_maximum],
            'use_xapi' => ['integer', (int) $this->use_xapi],
            'activity_id' => ['text', $this->custom_activity_id],
            'show_statements' => ['integer', (int) $this->statements_report_enabled],
            'highscore_enabled' => ['integer', (int) $this->highscore_enabled],
            'highscore_achieved_ts' => ['integer', (int) $this->highscore_achieved_ts],
            'highscore_percentage' => ['integer', (int) $this->highscore_percentage],
            'highscore_wtime' => ['integer', (int) $this->highscore_wtime],
            'highscore_own_table' => ['integer', (int) $this->highscore_own_table],
            'highscore_top_table' => ['integer', (int) $this->highscore_top_table],
            'highscore_top_num' => ['integer', $this->highscore_top_num],
        ];
    }
 
    public static function buildCustomParams(array $params): string
    {
        $notation = [];
        foreach ($params as $name => $value) {
            if ((string) $name !== '' && is_scalar($value)) {
                $notation[] = $name . '=' . $value;
            }
        }
 
        return implode(';', $notation);
    }
 
    public static function parseCustomParams(string $params): array
    {
        $parsed = [];
        foreach (preg_split('/; ?/', $params) as $param) {
            $param = explode('=', $param, 2);
            if ($param[0] !== '') {
                $parsed[$param[0]] = $param[1] ?? '';
            }
        }
 
        return $parsed;
    }
}