class.ilPlugin.php

Go to the documentation of this file.

<?php
use ILIAS\GlobalScreen\Provider\PluginProviderCollection;
use ILIAS\GlobalScreen\Provider\ProviderCollection;
use ILIAS\GlobalScreen\Scope\MainMenu\Provider\AbstractStaticPluginMainMenuProvider;
use ILIAS\Setup\Environment;
use ILIAS\Setup\ArrayEnvironment;
use ILIAS\Data\Version;

abstract class ilPlugin
{
    protected ilDBInterface $db;
    protected ilComponentRepositoryWrite $component_repository;
    protected string $id;
    protected ?ilPluginLanguage $language_handler = null;
    protected bool $lang_initialised = false;
    protected ProviderCollection $provider_collection;
    protected string $message = '';

    public function getMessage(): string
    {
        return $this->message;
    }

    // ------------------------------------------
    // Initialisation
    // ------------------------------------------

    public function __construct(
        \ilDBInterface $db,
        \ilComponentRepositoryWrite $component_repository,
        string $id
    ) {
        if (!$component_repository->hasPluginId($id)) {
            throw new \LogicException(
                "You tried to instantiate a plugin with an inexisting id '$id'." .
                "This is odd... Please use ilComponentFactory to instantiate plugins."
            );
        }

        $this->db = $db;
        $this->component_repository = $component_repository;
        $this->id = $id;

        $this->provider_collection = new PluginProviderCollection();

        // Fix for authentication plugins
        $this->loadLanguageModule();

        // Custom initialisation for plugin.
        $this->init();
    }

    protected function init(): void
    {
    }


    // ------------------------------------------
    // General Information About Plugin
    // ------------------------------------------

    public function getPluginName(): string
    {
        return $this->getPluginInfo()->getName();
    }

    public function getId(): string
    {
        return $this->getPluginInfo()->getId();
    }

    public function getVersion(): string
    {
        return (string) $this->getPluginInfo()->getAvailableVersion();
    }

    public function getDirectory(): string
    {
        return $this->getPluginInfo()->getPath();
    }

    public function isActive(): bool
    {
        return $this->getPluginInfo()->isActive();
    }

    public function needsUpdate(): bool
    {
        return $this->getPluginInfo()->isUpdateRequired();
    }

    protected function getPluginInfo(): ilPluginInfo
    {
        return $this->component_repository
            ->getPluginById(
                $this->id
            );
    }

    protected function getComponentInfo(): ilComponentInfo
    {
        return $this->getPluginInfo()->getComponent();
    }

    protected function getPluginSlotInfo(): ilPluginSlotInfo
    {
        return $this->getPluginInfo()->getPluginSlot();
    }


    // ------------------------------------------
    // (De-)Installation
    // ------------------------------------------

    public function install(): void
    {
        $this->afterInstall();
    }

    public function uninstall(): bool
    {
        if (!$this->beforeUninstall()) {
            return false;
        }

        $this->getLanguageHandler()->uninstall();
        $this->clearEventListening();
        $this->component_repository->removeStateInformationOf($this->getId());
        $this->afterUninstall();
        return true;
    }

    protected function afterInstall(): void
    {
    }

    protected function beforeUninstall(): bool
    {
        return true;
    }

    protected function afterUninstall(): void
    {
    }


    // ------------------------------------------
    // (De-)Activation
    // ------------------------------------------

    public function activate(): bool
    {
        if ($this->needsUpdate() && !$this->update()) {
            return false;
        }

        if (!$this->beforeActivation()) {
            return false;
        }

        $this->component_repository->setActivation($this->getId(), true);
        $this->afterActivation();

        return true;
    }

    public function deactivate(): bool
    {
        $this->component_repository->setActivation($this->getId(), false);
        $this->afterDeactivation();

        return true;
    }

    protected function beforeActivation(): bool
    {
        return true;
    }

    protected function afterActivation(): void
    {
    }

    protected function afterDeactivation(): void
    {
    }


    // ------------------------------------------
    // Update
    // ------------------------------------------

    public function update(): bool
    {
        global $DIC;
        $ilDB = $DIC->database();

        $result = $this->beforeUpdate();
        if ($result === false) {
            return false;
        }

        // Load language files
        $this->getLanguageHandler()->updateLanguages();

        // DB update
        $db_version = $this->updateDatabase();

        $this->readEventListening();

        // set last update version to current version
        $this->component_repository->setCurrentPluginVersion(
            $this->getPluginInfo()->getId(),
            $this->getPluginInfo()->getAvailableVersion(),
            $db_version
        );
        $this->afterUpdate();

        return true;
    }

    protected function updateDatabase(): int
    {
        global $DIC;
        $ilDB = $DIC->database();
        $lng = $DIC->language();

        $dbupdate = new ilPluginDBUpdate(
            $this->db,
            $this->getPluginInfo()
        );

        $dbupdate->applyUpdate();

        return $dbupdate->getCurrentVersion();
    }

    protected function beforeUpdate(): bool
    {
        return true;
    }


    protected function afterUpdate(): void
    {
    }


    // ------------------------------------------
    // Language Handling
    // ------------------------------------------

    protected function getLanguageHandler(): ilPluginLanguage
    {
        if ($this->language_handler === null) {
            $this->language_handler = $this->buildLanguageHandler();
        }
        return $this->language_handler;
    }

    protected function buildLanguageHandler(): ilPluginLanguage
    {
        return new ilPluginLanguage($this->getPluginInfo());
    }

    public function loadLanguageModule(): void
    {
        $this->getLanguageHandler()->loadLanguageModule();
    }

    public function txt(string $a_var): string
    {
        return $this->getLanguageHandler()->txt($a_var);
    }


    // ------------------------------------------
    // Rendering and Style
    // ------------------------------------------

    public function getTemplate(string $a_template, bool $a_par1 = true, bool $a_par2 = true): ilTemplate
    {
        return new ilTemplate($this->getDirectory() . "/templates/" . $a_template, $a_par1, $a_par2);
    }

    public function getStyleSheetLocation(string $a_css_file): string
    {
        $d2 = $this->getComponentInfo()->getId() . "_" . $this->getPluginSlotInfo()->getId() . "_" . $this->getPluginInfo()->getId();

        $css = ilUtil::getStyleSheetLocation("output", $a_css_file, $d2);
        if (is_int(strpos($css, "Customizing"))) {
            return $css;
        }

        return $this->getDirectory() . "/templates/" . $a_css_file;
    }


    public function addBlockFile($a_tpl, $a_var, $a_block, $a_tplname): void
    {
        $a_tpl->addBlockFile(
            $a_var,
            $a_block,
            $this->getDirectory() . "/templates/" . $a_tplname
        );
    }


    // ------------------------------------------
    // Event Handling
    // ------------------------------------------

    protected function readEventListening(): void
    {
        $reader = new ilPluginReader(
            $this->getDirectory() . '/plugin.xml',
            $this->getComponentInfo()->getType(),
            $this->getComponentInfo()->getName(),
            $this->getPluginSlotInfo()->getId(),
            $this->getPluginInfo()->getName()
        );
        $reader->clearEvents();
        $reader->startParsing();
    }

    protected function clearEventListening(): void
    {
        $reader = new ilPluginReader(
            $this->getDirectory() . '/plugin.xml',
            $this->getComponentInfo()->getType(),
            $this->getComponentInfo()->getName(),
            $this->getPluginSlotInfo()->getId(),
            $this->getPluginInfo()->getName()
        );
        $reader->clearEvents();
    }


    // ------------------------------------------
    // Global Screen
    // ------------------------------------------

    final public function getGlobalScreenProviderCollection(): PluginProviderCollection
    {
        return $this->provider_collection;
    }


    // ------------------------------------------
    // Initialisation
    // ------------------------------------------

    public function exchangeUIRendererAfterInitialization(\ILIAS\DI\Container $dic): Closure
    {
        //This returns the callable of $c['ui.renderer'] without executing it.
        return $dic->raw('ui.renderer');
    }


    public function exchangeUIFactoryAfterInitialization(string $dic_key, \ILIAS\DI\Container $dic): Closure
    {
        //This returns the callable of $c[$key] without executing it.
        return $dic->raw($dic_key);
    }
}