class.ilPlugin.php

Go to the documentation of this file.

<?php
/* Copyright (c) 1998-2009 ILIAS open source, Extended GPL, see docs/LICENSE */


include_once("./Services/Component/classes/class.ilComponent.php");
include_once("./Services/Component/exceptions/class.ilPluginException.php");

abstract class ilPlugin
{

        protected $lang_initialised = false;
        protected $id = '';

        public function __construct()
        {
                $this->__init();
        }

        abstract function getComponentType();

        abstract function getComponentName();
        abstract function getSlot();

        abstract function getSlotId();

        abstract function getPluginName();

        private function setId($a_id)
        {
                $this->id = $a_id;
        }

        function getId()
        {
                return $this->id;
        }

        private function setLastUpdateVersion($a_lastupdateversion)
        {
                $this->lastupdateversion = $a_lastupdateversion;
        }

        function getLastUpdateVersion()
        {
                return $this->lastupdateversion;
        }

        private function setVersion($a_version)
        {
                $this->version = $a_version;
        }

        function getVersion()
        {
                return $this->version;
        }

        private function setIliasMinVersion($a_iliasminversion)
        {
                $this->iliasminversion = $a_iliasminversion;
        }

        function getIliasMinVersion()
        {
                return $this->iliasminversion;
        }

        private function setIliasMaxVersion($a_iliasmaxversion)
        {
                $this->iliasmaxversion = $a_iliasmaxversion;
        }

        function getIliasMaxVersion()
        {
                return $this->iliasmaxversion;
        }

        private function setActive($a_active)
        {
                $this->active = $a_active;
        }

        function getActive()
        {
                return $this->active;
        }

        protected function setSlotObject($a_slot)
        {
                $this->slot = $a_slot;
        }

        protected function getSlotObject()
        {
                return $this->slot;
        }

        function setDBVersion($a_dbversion)
        {
                $this->dbversion = $a_dbversion;
        }

        function getDBVersion()
        {
                return $this->dbversion;
        }

        function writeDBVersion($a_dbversion)
        {
                global $ilDB;

                $this->setDBVersion($a_dbversion);

                $q = "UPDATE il_plugin SET db_version = ".$ilDB->quote((int) $this->getDBVersion(), "integer").
                        " WHERE component_type = ".$ilDB->quote($this->getComponentType(), "text").
                        " AND component_name = ".$ilDB->quote($this->getComponentName(), "text").
                        " AND slot_id = ".$ilDB->quote($this->getSlotId(), "text").
                        " AND name = ".$ilDB->quote($this->getPluginName(), "text");

                $ilDB->manipulate($q);
        }


        public function getDirectory()
        {
                return $this->getSlotObject()->getPluginsDirectory()."/".$this->getPluginName();
        }

        static public function _getDirectory($a_ctype, $a_cname, $a_slot_id, $a_pname)
        {
                include_once "Services/Component/classes/class.ilPluginSlot.php";
                return ilPluginSlot::_getPluginsDirectory($a_ctype, $a_cname, $a_slot_id)."/".$a_pname;
        }


        protected function getClassesDirectory()
        {
                return $this->getDirectory()."/classes";
        }

        public function includeClass($a_class_file_name)
        {
                include_once($this->getClassesDirectory()."/".$a_class_file_name);
        }

        protected function getLanguageDirectory()
        {
                return $this->getDirectory()."/lang";
        }

        static function getAvailableLangFiles($a_lang_directory)
        {
                $langs = array();

                if (!@is_dir($a_lang_directory))
                {
                        return array();
                }

                $dir = opendir($a_lang_directory);
                while($file = readdir($dir))
                {
                        if ($file != "." and
                                $file != "..")
                        {
                                // directories
                                if (@is_file($a_lang_directory."/".$file))
                                {
                                        if (substr($file, 0, 6) == "ilias_" &&
                                                substr($file, strlen($file) - 5) == ".lang")
                                        {
                                                $langs[] = array("key" => substr($file, 6, 2), "file" => $file,
                                                        "path" => $a_lang_directory."/".$file);
                                        }
                                }
                        }
                }

                return $langs;
        }

        static function hasConfigureClass($a_slot_dir, $a_name)
        {
                if (is_file($a_slot_dir."/".
                        $a_name."/classes/class.il".$a_name."ConfigGUI.php"))
                {
                        return true;
                }
                return false;
        }

        static function getConfigureClassName($a_name)
        {
                return "il".$a_name."ConfigGUI";
        }

        function getPrefix()
        {
                return $this->getSlotObject()->getPrefix()."_".$this->getId();
        }

        static public function getDBUpdateScriptName($a_ctype, $a_cname, $a_slot_name, $a_pname)
        {
                return "Customizing/global/plugins/".$a_ctype."/".$a_cname."/".
                $a_slot_name."/".$a_pname."/sql/dbupdate.php";
        }

        function getTablePrefix()
        {
                return $this->getPrefix();
        }

        public function updateLanguages($a_lang_keys = null)
        {
                ilGlobalCache::flushAll();
                include_once("./Services/Language/classes/class.ilObjLanguage.php");

                // get the keys of all installed languages if keys are not provided
                if(!isset($a_lang_keys))
                {
                        $a_lang_keys = array();
                        foreach (ilObjLanguage::getInstalledLanguages() as $langObj)
                        {
                                if ($langObj->isInstalled())
                                {
                                        $a_lang_keys[] = $langObj->getKey();
                                }
                        }
                }

                $langs = $this->getAvailableLangFiles($this->getLanguageDirectory());

                $prefix = $this->getPrefix();

                foreach($langs as $lang)
                {
                        // check if the language should be updated, otherwise skip it
                        if (!in_array($lang['key'], $a_lang_keys) )
                        {
                                continue;
                        }

                        $txt = file($this->getLanguageDirectory()."/".$lang["file"]);
                        $lang_array = array();

                        // get locally changed variables of the module (these should be kept)
                        $local_changes = ilObjLanguage::_getLocalChangesByModule($lang['key'], $prefix);

                        // get language data
                        if (is_array($txt))
                        {
                                foreach ($txt as $row)
                                {
                                        if ($row[0] != "#" && strpos($row, "#:#") > 0)
                                        {
                                                $a = explode("#:#",trim($row));
                                                $identifier = $prefix."_".trim($a[0]);
                                                $value = trim($a[1]);

                                                if (isset($local_changes[$identifier]))
                                                {
                                                        $lang_array[$identifier] = $local_changes[$identifier];
                                                }
                                                else
                                                {
                                                        $lang_array[$identifier] = $value;
                                                        ilObjLanguage::replaceLangEntry($prefix, $identifier, $lang["key"], $value);
                                                }
                                                //echo "<br>-$prefix-".$prefix."_".trim($a[0])."-".$lang["key"]."-";
                                        }
                                }
                        }

                        ilObjLanguage::replaceLangModule($lang["key"], $prefix, $lang_array);
                }
        }

        function updateDatabase()
        {
                global $ilDB, $lng;

                ilCachedComponentData::flush();

                include_once("./Services/Component/classes/class.ilPluginDBUpdate.php");
                $dbupdate = new ilPluginDBUpdate($this->getComponentType(),
                        $this->getComponentName(), $this->getSlotId(),
                        $this->getPluginName(), $ilDB, true, $this->getTablePrefix());

                //$dbupdate->getDBVersionStatus();
                //$dbupdate->getCurrentVersion();

                $result = $dbupdate->applyUpdate();
                $message = '';
                if ($dbupdate->updateMsg == "no_changes")
                {
                        $message = $lng->txt("no_changes").". ".$lng->txt("database_is_uptodate");
                }
                else
                {
                        foreach ($dbupdate->updateMsg as $row)
                        {
                                $message .= $lng->txt($row["msg"]).": ".$row["nr"]."<br/>";
                        }
                }

                $this->message.= $message;

                return $result;
        }

        public function loadLanguageModule()
        {
                global $lng;

                if (!$this->lang_initialised && is_object($lng))
                {
                        $lng->loadLanguageModule($this->getPrefix());
                        $this->lang_initialised = true;
                }
        }

        public function txt($a_var)
        {
                global $lng;
                $this->loadLanguageModule();
                return $lng->txt($this->getPrefix()."_".$a_var, $this->getPrefix());
        }

        static function lookupTxt($a_mod_prefix, $a_pl_id, $a_lang_var)
        {
                global $lng;

                // this enables default language fallback
                $prefix = $a_mod_prefix."_".$a_pl_id;
                return $lng->txt($prefix."_".$a_lang_var, $prefix);
        }


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

                return $tpl;
        }

        public static function _getImagePath($a_ctype, $a_cname, $a_slot_id,
                $a_pname, $a_img)
        {
                $d2 = ilComponent::lookupId($a_ctype, $a_cname)."_".$a_slot_id."_".
                        ilPlugin::lookupIdForName($a_ctype, $a_cname, $a_slot_id, $a_pname);

                $img = ilUtil::getImagePath($d2."/".$a_img);
                if (is_int(strpos($img, "Customizing")))
                {
                        return $img;
                }

                $d = ilPlugin::_getDirectory($a_ctype, $a_cname, $a_slot_id, $a_pname);
                return $d."/templates/images/".$a_img;
        }

        public function getImagePath($a_img)
        {
                return self::_getImagePath($this->getComponentType(), $this->getComponentName(), $this->getSlotId(),
                        $this->getPluginName(), $a_img);
        }

        public function getStyleSheetLocation($a_css_file)
        {
                $d2 = ilComponent::lookupId($this->getComponentType(), $this->getComponentName())."_".$this->getSlotId()."_".
                        ilPlugin::lookupIdForName($this->getComponentType(), $this->getComponentName(), $this->getSlotId(), $this->getPluginName());

                $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)
        {
                $a_tpl->addBlockFile($a_var, $a_block,
                        $this->getDirectory()."/templates/".$a_tplname);
        }


        static public function createPluginRecord($a_ctype, $a_cname, $a_slot_id, $a_pname)
        {
                global $ilDB;

                ilCachedComponentData::flush();

                // check record existence record
                $q = "SELECT * FROM il_plugin".
                        " WHERE component_type = ".$ilDB->quote($a_ctype, "text").
                        " AND component_name = ".$ilDB->quote($a_cname, "text").
                        " AND slot_id = ".$ilDB->quote($a_slot_id, "text").
                        " AND name = ".$ilDB->quote($a_pname, "text");
                $set = $ilDB->query($q);
                if (!$rec = $ilDB->fetchAssoc($set))
                {
                        $q = "INSERT INTO il_plugin (component_type, component_name, slot_id, name)".
                                " VALUES (".$ilDB->quote($a_ctype, "text").",".
                                $ilDB->quote($a_cname, "text").",".
                                $ilDB->quote($a_slot_id, "text").",".
                                $ilDB->quote($a_pname, "text").")";
                        $ilDB->manipulate($q);
                }
        }


        static public function getPluginRecord($a_ctype, $a_cname, $a_slot_id, $a_pname)
        {
                $cached_component = ilCachedComponentData::getInstance();
                $rec = $cached_component->lookupPluginByName($a_pname);

                if ($rec['component_type'] == $a_ctype AND $rec['component_name'] == $a_cname AND $rec['slot_id'] == $a_slot_id) {
                        return $rec;
                } else {
                        include_once("./Services/Component/exceptions/class.ilPluginException.php");
                        throw (new ilPluginException("No plugin record found for '" . $a_ctype . "', '" . $a_cname . "', '" . $a_slot_id . "', '" . $a_pname
                                . "'."));

                }
        }

        private function __init()
        {
                global $ilDB, $lng, $ilPluginAdmin;

                // read/set basic data
                $rec = ilPlugin::getPluginRecord($this->getComponentType(),
                        $this->getComponentName(), $this->getSlotId(), $this->getPluginName());
                $this->setLastUpdateVersion($rec["last_update_version"]);
                $this->setDBVersion($rec["db_version"]);
                $this->setActive($rec["active"]);

                // get id
                $this->setId($ilPluginAdmin->getId($this->getComponentType(),
                        $this->getComponentName(),
                        $this->getSlotId(),
                        $this->getPluginName()));

                // get version
                $this->setVersion($ilPluginAdmin->getVersion($this->getComponentType(),
                        $this->getComponentName(),
                        $this->getSlotId(),
                        $this->getPluginName()));

                // get ilias min version
                $this->setIliasMinVersion($ilPluginAdmin->getIliasMinVersion($this->getComponentType(),
                        $this->getComponentName(),
                        $this->getSlotId(),
                        $this->getPluginName()));

                // get ilias max version
                $this->setIliasMaxVersion($ilPluginAdmin->getIliasMaxVersion($this->getComponentType(),
                        $this->getComponentName(),
                        $this->getSlotId(),
                        $this->getPluginName()));

                // get slot object
                $this->setSlotObject(new ilPluginSlot($this->getComponentType(),
                        $this->getComponentName(), $this->getSlotId()));

                // load language module

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

                // call slot and plugin init methods
                $this->slotInit();
                $this->init();
        }

        abstract protected function slotInit();

        protected function init()
        {
        }

        public function isActive()
        {
                global $ilPluginAdmin;

                return $ilPluginAdmin->isActive($this->getComponentType(),
                        $this->getComponentName(), $this->getSlotId(), $this->getPluginName());
        }

        public function needsUpdate()
        {
                global $ilPluginAdmin;

                return $ilPluginAdmin->needsUpdate($this->getComponentType(),
                        $this->getComponentName(), $this->getSlotId(), $this->getPluginName());
        }

        function activate()
        {
                global $lng, $ilDB;

                ilCachedComponentData::flush();

                $result = true;

                // check whether update is necessary
                if ($this->needsUpdate())
                {
                        //$result = $this->isUpdatePossible();

                        // do update
                        if ($result === true)
                        {
                                $result = $this->update();
                        }
                }
                if ($result === true)
                {
                        $result = $this->beforeActivation();
                        // activate plugin
                        if ($result === true)
                        {
                                $q = "UPDATE il_plugin SET active = ".$ilDB->quote(1, "integer").",".
                                        " plugin_id = ".$ilDB->quote($this->getId(), "text").
                                        " WHERE component_type = ".$ilDB->quote($this->getComponentType(), "text").
                                        " AND component_name = ".$ilDB->quote($this->getComponentName(), "text").
                                        " AND slot_id = ".$ilDB->quote($this->getSlotId(), "text").
                                        " AND name = ".$ilDB->quote($this->getPluginName(), "text");

                                $ilDB->manipulate($q);
                                $this->afterActivation();
                        }
                }
                ilCachedComponentData::flush();
                return $result;
        }

        protected function beforeActivation()
        {
                return true;    // false would indicate that anything went wrong
                // activation would not proceed
                // throw an exception in this case
                //throw new ilPluginException($lng->txt(""));
        }

        protected function afterActivation()
        {
        }

        function deactivate()
        {
                global $ilDB;

                ilCachedComponentData::flush();

                $result = true;

                $q = "UPDATE il_plugin SET active = ".$ilDB->quote(0, "integer").
                        " WHERE component_type = ".$ilDB->quote($this->getComponentType(), "text").
                        " AND component_name = ".$ilDB->quote($this->getComponentName(), "text").
                        " AND slot_id = ".$ilDB->quote($this->getSlotId(), "text").
                        " AND name = ".$ilDB->quote($this->getPluginName(), "text");

                $ilDB->manipulate($q);
                $this->afterDeactivation();

                return $result;
        }


        protected function afterDeactivation()
        {
        }
        
        
        protected function beforeUninstall()
        {
                // plugin-specific
                // false would indicate that anything went wrong
                return true; 
        }
        
        final function uninstall()
        {
                global $ilDB;
        
                if($this->beforeUninstall())
                {
                        // remove all language entries (see ilObjLanguage)
                        // see updateLanguages
                        $prefix = $this->getPrefix();
                        if($prefix)
                        {
                                $ilDB->manipulate("DELETE FROM lng_data".
                                        " WHERE module = ".$ilDB->quote($prefix, "text"));              
                                $ilDB->manipulate("DELETE FROM lng_modules".
                                        " WHERE module = ".$ilDB->quote($prefix, "text"));
                        }
                        
                        // db version is kept in il_plugin - will be deleted, too                                               
                        
                        $q = "DELETE FROM il_plugin".
                                " WHERE component_type = ".$ilDB->quote($this->getComponentType(), "text").
                                " AND component_name = ".$ilDB->quote($this->getComponentName(), "text").
                                " AND slot_id = ".$ilDB->quote($this->getSlotId(), "text").
                                " AND name = ".$ilDB->quote($this->getPluginName(), "text");
                        $ilDB->manipulate($q);

                        $this->afterUninstall();
                        
                        ilCachedComponentData::flush();
                        return true;
                }               

                return false;
        }
        
        protected function afterUninstall()
        {
                // plugin-specific
        }
                        
        function update()
        {
                global $ilDB, $ilCtrl;

                ilCachedComponentData::flush();

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

                // DB update
                if ($result === true)
                {
                        $result = $this->updateDatabase();
                }

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

                // load control structure
                include_once("./setup/classes/class.ilCtrlStructureReader.php");
                $structure_reader = new ilCtrlStructureReader();
                $structure_reader->readStructure(true, "./".$this->getDirectory(), $this->getPrefix(),
                        $this->getDirectory());
                //              $ilCtrl->storeCommonStructures();

                // add config gui to the ctrl calls
                $ilCtrl->insertCtrlCalls("ilobjcomponentsettingsgui", ilPlugin::getConfigureClassName($this->getPluginName()),
                        $this->getPrefix());

                // set last update version to current version
                if ($result === true)
                {
                        $q = "UPDATE il_plugin SET last_update_version = ".$ilDB->quote($this->getVersion(), "text").
                                " WHERE component_type = ".$ilDB->quote($this->getComponentType(), "text").
                                " AND component_name = ".$ilDB->quote($this->getComponentName(), "text").
                                " AND slot_id = ".$ilDB->quote($this->getSlotId(), "text").
                                " AND name = ".$ilDB->quote($this->getPluginName(), "text");

                        $ilDB->manipulate($q);
                        $this->afterUpdate();
                }

                return $result;
        }

        protected function beforeUpdate()
        {
                return true;    // false would indicate that anything went wrong
                // update would not proceed
                // throw an exception in this case
                //throw new ilPluginException($lng->txt(""));
        }

        protected function afterUpdate()
        {
        }

        static function getPluginObject($a_ctype, $a_cname, $a_slot_id, $a_pname)
        {
                include_once("./Services/Component/classes/class.ilPluginSlot.php");
                $slot_name = ilPluginSlot::lookupSlotName($a_ctype, $a_cname, $a_slot_id);

                $cached_component = ilCachedComponentData::getInstance();
                $rec = $cached_component->lookCompId($a_ctype, $a_cname);
                if (! $rec) {
                        return NULL;
                }

                $file = "./Customizing/global/plugins/".$a_ctype."/".
                        $a_cname."/".$slot_name."/".
                        $a_pname."/classes/class.il".$a_pname."Plugin.php";

                if (is_file($file))
                {
                        include_once($file);
                        $class = "il".$a_pname."Plugin";
                        $plugin = new $class();
                        return $plugin;
                }

                return null;
        }


        static function lookupStoredData($a_ctype, $a_cname, $a_slot_id, $a_pname)
        {
                global $ilDB;

                $q = "SELECT * FROM il_plugin WHERE ".
                        " component_type = ".$ilDB->quote($a_ctype, "text")." AND ".
                        " component_name = ".$ilDB->quote($a_cname, "text")." AND ".
                        " slot_id = ".$ilDB->quote($a_slot_id, "text")." AND ".
                        " name = ".$ilDB->quote($a_pname, "text");

                $set = $ilDB->query($q);

                $rec = $ilDB->fetchAssoc($set);

                return $rec;
        }

        static function getActivePluginsForSlot($a_ctype, $a_cname, $a_slot_id)
        {
                global $ilPluginAdmin;

                $plugins = array();

                $cached_component = ilCachedComponentData::getInstance();

                $lookupActivePluginsBySlotId = $cached_component->lookupActivePluginsBySlotId($a_slot_id);
                foreach($lookupActivePluginsBySlotId as $rec)
                {
                        if ($ilPluginAdmin->isActive($a_ctype, $a_cname, $a_slot_id, $rec["name"]))
                        {
                                $plugins[] = $rec["name"];
                        }
                }

                return $plugins;
        }

        public static function getActivePluginIdsForSlot($a_ctype, $a_cname, $a_slot_id) {
                global $ilPluginAdmin;

                $plugins = array();
                $cached_component = ilCachedComponentData::getInstance();
                $lookupActivePluginsBySlotId = $cached_component->lookupActivePluginsBySlotId($a_slot_id);
                foreach($lookupActivePluginsBySlotId as $rec)
                {
                        if ($ilPluginAdmin->isActive($a_ctype, $a_cname, $a_slot_id, $rec["name"]))
                        {
                                $plugins[] = $rec["plugin_id"];
                        }
                }

                return $plugins;
        }

        static function lookupNameForId($a_ctype, $a_cname, $a_slot_id, $a_plugin_id)
        {
                global $ilDB;

                $q = "SELECT name FROM il_plugin ".
                        " WHERE component_type = ".$ilDB->quote($a_ctype, "text").
                        " AND component_name = ".$ilDB->quote($a_cname, "text").
                        " AND slot_id = ".$ilDB->quote($a_slot_id, "text").
                        " AND plugin_id = ".$ilDB->quote($a_plugin_id, "text");

                $set = $ilDB->query($q);
                if ($rec = $ilDB->fetchAssoc($set))
                {
                        return $rec["name"];
                }
        }

        static function lookupIdForName($a_ctype, $a_cname, $a_slot_id, $a_plugin_name)
        {
                global $ilDB;

                $q = "SELECT plugin_id FROM il_plugin ".
                        " WHERE component_type = ".$ilDB->quote($a_ctype, "text").
                        " AND component_name = ".$ilDB->quote($a_cname, "text").
                        " AND slot_id = ".$ilDB->quote($a_slot_id, "text").
                        " AND name = ".$ilDB->quote($a_plugin_name, "text");

                $set = $ilDB->query($q);
                if ($rec = $ilDB->fetchAssoc($set))
                {
                        return $rec["plugin_id"];
                }
        }
}