ElggPlugin.php

Go to the documentation of this file.

<?php
 
use Elgg\Includer;
 
class ElggPlugin extends \ElggObject {
    private $package;
    private $manifest;
 
    private $static_config;
 
    private $path;
    private $errorMsg = '';
 
    protected function initializeAttributes() {
        parent::initializeAttributes();
 
        $this->attributes['subtype'] = "plugin";
 
        // plugins must be public.
        $this->access_id = ACCESS_PUBLIC;
    }
 
    public function __construct($path) {
        if (!$path) {
            throw new \PluginException("ElggPlugin cannot be null instantiated. You must pass a full path.");
        }
 
        if (is_object($path)) {
            // database object
            parent::__construct($path);
            $this->path = _elgg_services()->config->getPluginsPath() . $this->getID();
        } else if (is_numeric($path)) {
            // guid
            // @todo plugins with directory names of '12345'
            elgg_deprecated_notice("Use elgg_get_plugin_from_id() to load a plugin.", 1.9);
            parent::__construct($path);
            $this->path = _elgg_services()->config->getPluginsPath() . $this->getID();
        } else {
            $this->initializeAttributes();
            
            $mod_dir = _elgg_services()->config->getPluginsPath();
 
            // not a full path, so assume a directory name and use the default path
            if (strpos($path, $mod_dir) !== 0) {
                elgg_deprecated_notice("You should pass a full path to ElggPlugin.", 1.9);
                $path = $mod_dir . $path;
            }
 
            // path checking is done in the package
            $path = sanitise_filepath($path);
            $this->path = $path;
            $path_parts = explode('/', rtrim($path, '/'));
            $plugin_id = array_pop($path_parts);
            $this->title = $plugin_id;
 
            // check if we're loading an existing plugin
            $existing_plugin = elgg_get_plugin_from_id($plugin_id);
            
            if ($existing_plugin) {
                $this->load($existing_plugin->guid);
            }
        }
 
        _elgg_cache_plugin_by_id($this);
    }
 
    public function save() {
        // own by the current site so users can be deleted without affecting plugins
        $site = _elgg_services()->configTable->get('site');
        $this->attributes['site_guid'] = $site->guid;
        $this->attributes['owner_guid'] = $site->guid;
        $this->attributes['container_guid'] = $site->guid;
        
        if (parent::save()) {
            // make sure we have a priority
            $priority = $this->getPriority();
            if ($priority === false || $priority === null) {
                return $this->setPriority('last');
            }
        } else {
            return false;
        }
    }
 
 
    // Plugin ID and path
 
    public function getID() {
        return $this->title;
    }
 
    public function getFriendlyName() {
        $manifest = $this->getManifest();
        if ($manifest) {
            return $manifest->getName();
        }
 
        return $this->getID();
    }
 
    public function getPath() {
        return sanitise_filepath($this->path);
    }
 
    public function getStaticConfig($key, $default = null) {
        if ($this->static_config === null) {
            $this->static_config = [];
 
            if ($this->canReadFile(ElggPluginPackage::STATIC_CONFIG_FILENAME)) {
                $this->static_config = $this->includeFile(ElggPluginPackage::STATIC_CONFIG_FILENAME);
            }
        }
 
        if (array_key_exists($key, $this->static_config)) {
            return $this->static_config[$key];
        } else {
            return $default;
        }
    }
 
    public function setID($id) {
        return $this->attributes['title'] = $id;
    }
 
    public function getAvailableTextFiles() {
        $filenames = $this->getPackage()->getTextFilenames();
 
        $files = array();
        foreach ($filenames as $filename) {
            if ($this->canReadFile($filename)) {
                $files[$filename] = "$this->path/$filename";
            }
        }
 
        return $files;
    }
 
    // Load Priority
 
    public function getPriority() {
        $name = _elgg_namespace_plugin_private_setting('internal', 'priority');
        return $this->$name;
    }
 
    public function setPriority($priority, $site_guid = null) {
        if (!$this->guid) {
            return false;
        }
 
        $db_prefix = _elgg_services()->configTable->get('dbprefix');
        $name = _elgg_namespace_plugin_private_setting('internal', 'priority');
        // if no priority assume a priority of 1
        $old_priority = (int) $this->getPriority();
        $old_priority = (!$old_priority) ? 1 : $old_priority;
        $max_priority = _elgg_get_max_plugin_priority();
 
        // can't use switch here because it's not strict and
        // php evaluates +1 == 1
        if ($priority === '+1') {
            $priority = $old_priority + 1;
        } elseif ($priority === '-1') {
            $priority = $old_priority - 1;
        } elseif ($priority === 'first') {
            $priority = 1;
        } elseif ($priority === 'last') {
            $priority = $max_priority;
        }
 
        // should be a number by now
        if ($priority > 0) {
            if (!is_numeric($priority)) {
                return false;
            }
 
            // there's nothing above the max.
            if ($priority > $max_priority) {
                $priority = $max_priority;
            }
 
            // there's nothing below 1.
            if ($priority < 1) {
                $priority = 1;
            }
 
            if ($priority > $old_priority) {
                $op = '-';
                $where = "CAST(value as unsigned) BETWEEN $old_priority AND $priority";
            } else {
                $op = '+';
                $where = "CAST(value as unsigned) BETWEEN $priority AND $old_priority";
            }
 
            // displace the ones affected by this change
            $q = "UPDATE {$db_prefix}private_settings
                SET value = CAST(value as unsigned) $op 1
                WHERE entity_guid != $this->guid
                AND name = '$name'
                AND $where";
 
            if (!$this->getDatabase()->updateData($q)) {
                return false;
            }
 
            // set this priority
            if ($this->setPrivateSetting($name, $priority)) {
                return true;
            } else {
                return false;
            }
        }
 
        return false;
    }
 
 
    // Plugin settings
 
    public function getSetting($name, $default = null) {
        $values = _elgg_services()->pluginSettingsCache->getAll($this->guid);
 
        if ($values !== null) {
            return isset($values[$name]) ? $values[$name] : $default;
        }
 
        $val = $this->$name;
        return $val !== null ? $val : $default;
    }
 
    public function getAllSettings() {
        $values = _elgg_services()->pluginSettingsCache->getAll($this->guid);
        if ($values !== null) {
            return $values;
        }
 
        if (!$this->guid) {
            return false;
        }
 
        $db_prefix = _elgg_services()->config->get('dbprefix');
        // need to remove all namespaced private settings.
        $us_prefix = _elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
        $is_prefix = _elgg_namespace_plugin_private_setting('internal', '', $this->getID());
 
        // Get private settings for user
        $q = "SELECT * FROM {$db_prefix}private_settings
            WHERE entity_guid = $this->guid
            AND name NOT LIKE '$us_prefix%'
            AND name NOT LIKE '$is_prefix%'";
 
        $private_settings = $this->getDatabase()->getData($q);
 
        $return = array();
 
        if ($private_settings) {
            foreach ($private_settings as $setting) {
                $return[$setting->name] = $setting->value;
            }
        }
 
        return $return;
    }
 
    public function setSetting($name, $value) {
        if (!$this->guid) {
            return false;
        }
        
        // Hook to validate setting
        $value = elgg_trigger_plugin_hook('setting', 'plugin', array(
            'plugin_id' => $this->getID(),
            'plugin' => $this,
            'name' => $name,
            'value' => $value,
        ), $value);
        
        if (is_array($value)) {
            elgg_log('Plugin settings cannot store arrays.', 'ERROR');
            return false;
        }
        
        return $this->setPrivateSetting($name, $value);
    }
 
    public function unsetSetting($name) {
        return remove_private_setting($this->guid, $name);
    }
 
    public function unsetAllSettings() {
        _elgg_services()->pluginSettingsCache->clear($this->guid);
        _elgg_services()->boot->invalidateCache();
 
        $db_prefix = _elgg_services()->configTable->get('dbprefix');
        $us_prefix = _elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
        $is_prefix = _elgg_namespace_plugin_private_setting('internal', '', $this->getID());
 
        $q = "DELETE FROM {$db_prefix}private_settings
            WHERE entity_guid = $this->guid
            AND name NOT LIKE '$us_prefix%'
            AND name NOT LIKE '$is_prefix%'";
 
        return $this->getDatabase()->deleteData($q);
    }
 
 
    // User settings
 
    public function getUserSetting($name, $user_guid = 0, $default = null) {
        $user_guid = (int)$user_guid;
 
        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = _elgg_services()->session->getLoggedInUser();
        }
 
        if (!($user instanceof \ElggUser)) {
            return false;
        }
 
        $name = _elgg_namespace_plugin_private_setting('user_setting', $name, $this->getID());
        
        $val = get_private_setting($user->guid, $name);
        return $val !== null ? $val : $default;
    }
 
    public function getAllUserSettings($user_guid = 0) {
        $user_guid = (int)$user_guid;
 
        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = _elgg_services()->session->getLoggedInUser();
        }
 
        if (!($user instanceof \ElggUser)) {
            return false;
        }
 
        $db_prefix = _elgg_services()->config->get('dbprefix');
        // send an empty name so we just get the first part of the namespace
        $ps_prefix = _elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
        $ps_prefix_len = strlen($ps_prefix);
 
        // Get private settings for user
        $q = "SELECT * FROM {$db_prefix}private_settings
            WHERE entity_guid = {$user->guid}
            AND name LIKE '$ps_prefix%'";
 
        $private_settings = $this->getDatabase()->getData($q);
 
        $return = array();
 
        if ($private_settings) {
            foreach ($private_settings as $setting) {
                $name = substr($setting->name, $ps_prefix_len);
                $value = $setting->value;
 
                $return[$name] = $value;
            }
        }
 
        return $return;
    }
 
    public function setUserSetting($name, $value, $user_guid = 0) {
        $user_guid = (int)$user_guid;
 
        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = _elgg_services()->session->getLoggedInUser();
        }
 
        if (!($user instanceof \ElggUser)) {
            return false;
        }
 
        // Hook to validate setting
        // note: this doesn't pass the namespaced name
        $value = _elgg_services()->hooks->trigger('usersetting', 'plugin', array(
            'user' => $user,
            'plugin' => $this,
            'plugin_id' => $this->getID(),
            'name' => $name,
            'value' => $value
        ), $value);
        
        if (is_array($value)) {
            elgg_log('Plugin user settings cannot store arrays.', 'ERROR');
            return false;
        }
        
        // set the namespaced name.
        $name = _elgg_namespace_plugin_private_setting('user_setting', $name, $this->getID());
 
        return set_private_setting($user->guid, $name, $value);
    }
 
    public function unsetUserSetting($name, $user_guid = 0) {
        $user_guid = (int)$user_guid;
 
        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = _elgg_services()->session->getLoggedInUser();
        }
 
        if (!($user instanceof \ElggUser)) {
            return false;
        }
 
        // set the namespaced name.
        $name = _elgg_namespace_plugin_private_setting('user_setting', $name, $this->getID());
 
        return remove_private_setting($user->guid, $name);
    }
 
    public function unsetAllUserSettings($user_guid) {
        $db_prefix = _elgg_services()->configTable->get('dbprefix');
        $ps_prefix = _elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
 
        $q = "DELETE FROM {$db_prefix}private_settings
            WHERE entity_guid = $user_guid
            AND name LIKE '$ps_prefix%'";
 
        return $this->getDatabase()->deleteData($q);
    }
 
    public function unsetAllUsersSettings() {
        $db_prefix = _elgg_services()->configTable->get('dbprefix');
        $ps_prefix = _elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
 
        $q = "DELETE FROM {$db_prefix}private_settings
            WHERE name LIKE '$ps_prefix%'";
 
        return $this->getDatabase()->deleteData($q);
    }
 
 
    // validation
 
    public function isValid() {
        if (!$this->getID()) {
            $this->errorMsg = _elgg_services()->translator->translate('ElggPlugin:MissingID', array($this->guid));
            return false;
        }
 
        if (!$this->getPackage() instanceof \ElggPluginPackage) {
            $this->errorMsg = _elgg_services()->translator->translate('ElggPlugin:NoPluginPackagePackage', array($this->getID(), $this->guid));
            return false;
        }
 
        if (!$this->getPackage()->isValid()) {
            $this->errorMsg = $this->getPackage()->getError();
            return false;
        }
 
        return true;
    }
 
    public function isActive($site_guid = null) {
        if (!$this->guid) {
            return false;
        }
 
        if ($site_guid) {
            $site = get_entity($site_guid);
        } else {
            $site = _elgg_services()->configTable->get('site');
        }
 
        if (!($site instanceof \ElggSite)) {
            return false;
        }
 
        return check_entity_relationship($this->guid, 'active_plugin', $site->guid);
    }
 
    public function canActivate($site_guid = null) {
        if ($this->isActive($site_guid)) {
            return false;
        }
 
        if ($this->getPackage()) {
            $result = $this->getPackage()->isValid() && $this->getPackage()->checkDependencies();
            if (!$result) {
                $this->errorMsg = $this->getPackage()->getError();
            }
 
            return $result;
        }
 
        return false;
    }
 
 
    // activating and deactivating
 
    public function activate($site_guid = null) {
        if ($this->isActive($site_guid)) {
            return false;
        }
 
        if (!$this->canActivate()) {
            return false;
        }
 
        // Check this before setting status because the file could potentially throw
        if (!$this->isStaticConfigValid()) {
            return false;
        }
 
        if (!$this->setStatus(true, $site_guid)) {
            return false;
        }
 
        // perform tasks and emit events
        // emit an event. returning false will make this not be activated.
        // we need to do this after it's been fully activated
        // or the deactivate will be confused.
        $params = array(
            'plugin_id' => $this->getID(),
            'plugin_entity' => $this,
        );
 
        $return = _elgg_services()->events->trigger('activate', 'plugin', $params);
 
        // if there are any on_enable functions, start the plugin now and run them
        // Note: this will not run re-run the init hooks!
        if ($return) {
            if ($this->canReadFile('activate.php')) {
                $flags = ELGG_PLUGIN_INCLUDE_START | ELGG_PLUGIN_REGISTER_CLASSES |
                        ELGG_PLUGIN_REGISTER_LANGUAGES | ELGG_PLUGIN_REGISTER_VIEWS;
 
                $this->start($flags);
 
                $return = $this->includeFile('activate.php');
            }
        }
 
        if ($return === false) {
            $this->deactivate($site_guid);
        }
 
        return $return;
    }
 
    public function canDeactivate($site_guid = null) {
        if (!$this->isActive($site_guid)) {
            return false;
        }
 
        $dependents = [];
 
        $active_plugins = elgg_get_plugins();
 
        foreach ($active_plugins as $plugin) {
            $manifest = $plugin->getManifest();
            if (!$manifest) {
                return true;
            }
            $requires = $manifest->getRequires();
 
            foreach ($requires as $required) {
                if ($required['type'] == 'plugin' && $required['name'] == $this->getID()) {
                    // there are active dependents
                    $dependents[$manifest->getPluginID()] = $plugin;
                }
            }
        }
 
        if (!empty($dependents)) {
            $list = array_map(function(\ElggPlugin $plugin) {
                $css_id = preg_replace('/[^a-z0-9-]/i', '-', $plugin->getManifest()->getID());
                return elgg_view('output/url', [
                    'text' => $plugin->getManifest()->getName(),
                    'href' => "#$css_id",
                ]);
            }, $dependents);
            $name = $this->getManifest()->getName();
            $list = implode(', ', $list);
            $this->errorMsg = elgg_echo('ElggPlugin:Dependencies:ActiveDependent', [$name, $list]);
            return false;
        }
 
        return true;
    }
 
    public function deactivate($site_guid = null) {
        if (!$this->isActive($site_guid)) {
            return false;
        }
 
        if (!$this->canDeactivate($site_guid)) {
            return false;
        }
        
        // emit an event. returning false will cause this to not be deactivated.
        $params = array(
            'plugin_id' => $this->getID(),
            'plugin_entity' => $this,
        );
 
        $return = _elgg_services()->events->trigger('deactivate', 'plugin', $params);
 
        // run any deactivate code
        if ($return) {
            if ($this->canReadFile('deactivate.php')) {
                $return = $this->includeFile('deactivate.php');
            }
        }
 
        if ($return === false) {
            return false;
        } else {
            return $this->setStatus(false, $site_guid);
        }
    }
 
    public function start($flags) {
        //if (!$this->canActivate()) {
        //  return false;
        //}
 
        // include classes
        if ($flags & ELGG_PLUGIN_REGISTER_CLASSES) {
            $this->registerClasses();
        }
        
        // include start file
        if ($flags & ELGG_PLUGIN_INCLUDE_START) {
            $this->includeFile('start.php');
        }
 
        // include views
        if ($flags & ELGG_PLUGIN_REGISTER_VIEWS) {
            $this->registerViews();
        }
 
        // include languages
        if ($flags & ELGG_PLUGIN_REGISTER_LANGUAGES) {
            $this->registerLanguages();
        }
 
        return true;
    }
 
 
    // start helpers
 
    protected static function getConfigWrapper() {
        static $wrapper;
        if (null === $wrapper) {
            global $CONFIG;
            $warning = 'Do not rely on local $CONFIG being available in start.php';
            $wrapper = new \Elgg\DeprecationWrapper($CONFIG, $warning, "1.10");
        }
        return $wrapper;
    }
 
    protected function includeFile($filename) {
        // This needs to be here to be backwards compatible for 1.0-1.7.
        // They expect the global config object to be available in start.php.
        if ($filename == 'start.php') {
            $CONFIG = self::getConfigWrapper();
        }
 
        $filepath = "$this->path/$filename";
 
        if (!$this->canReadFile($filename)) {
            $msg = _elgg_services()->translator->translate('ElggPlugin:Exception:CannotIncludeFile',
                            array($filename, $this->getID(), $this->guid, $this->path));
            throw new \PluginException($msg);
        }
 
        try {
            $ret = require_once $filepath;
        } catch (Exception $e) {
            $msg = _elgg_services()->translator->translate('ElggPlugin:Exception:IncludeFileThrew',
                array($filename, $this->getID(), $this->guid, $this->path));
            throw new \PluginException($msg, 0, $e);
        }
 
        return $ret;
    }
 
    protected function canReadFile($filename) {
        $path = "{$this->path}/$filename";
        return is_file($path) && is_readable($path);
    }
 
    private function isStaticConfigValid() {
        if (!$this->canReadFile(ElggPluginPackage::STATIC_CONFIG_FILENAME)) {
            return true;
        }
 
        ob_start();
        $value = $this->includeFile(ElggPluginPackage::STATIC_CONFIG_FILENAME);
        if (ob_get_clean() !== '') {
            $this->errorMsg = _elgg_services()->translator->translate('ElggPlugin:activate:ConfigSentOutput');
            return false;
        }
 
        // make sure can serialize
        $value = @unserialize(serialize($value));
        if (!is_array($value)) {
            $this->errorMsg = _elgg_services()->translator->translate('ElggPlugin:activate:BadConfigFormat');
            return false;
        }
 
        return true;
    }
 
    protected function registerViews() {
        $views = _elgg_services()->views;
 
        // Declared views first
        $file = "{$this->path}/views.php";
        if (is_file($file)) {
            $spec = Includer::includeFile($file);
            if (is_array($spec)) {
                $views->mergeViewsSpec($spec);
            }
        }
 
        $spec = $this->getStaticConfig('views');
        if ($spec) {
            $views->mergeViewsSpec($spec);
        }
 
        // Allow /views directory files to override
        if (!$views->registerPluginViews($this->path, $failed_dir)) {
            $key = 'ElggPlugin:Exception:CannotRegisterViews';
            $args = [$this->getID(), $this->guid, $failed_dir];
            $msg = _elgg_services()->translator->translate($key, $args);
            throw new \PluginException($msg);
        }
    }
 
    protected function registerLanguages() {
        return _elgg_services()->translator->registerPluginTranslations($this->path);
    }
 
    protected function registerClasses() {
        $classes_path = "$this->path/classes";
 
        if (is_dir($classes_path)) {
            _elgg_services()->autoloadManager->addClasses($classes_path);
        }
 
        return true;
    }
 
    public function __get($name) {
        // See if its in our base attribute
        if (array_key_exists($name, $this->attributes)) {
            return $this->attributes[$name];
        }
 
        // @todo clean below - getPrivateSetting() should return null now
        // No, so see if its in the private data store.
        // get_private_setting() returns false if it doesn't exist
        $meta = $this->getPrivateSetting($name);
 
        if ($meta === false) {
            // Can't find it, so return null
            return null;
        }
 
        return $meta;
    }
 
    public function get($name) {
        elgg_deprecated_notice("Use -> instead of get()", 1.9);
        return $this->__get($name);
    }
 
    public function __set($name, $value) {
        if (array_key_exists($name, $this->attributes)) {
            // Check that we're not trying to change the guid!
            if ((array_key_exists('guid', $this->attributes)) && ($name == 'guid')) {
                return;
            }
 
            $this->attributes[$name] = $value;
        } else {
            // to make sure we trigger the correct hooks
            $this->setSetting($name, $value);
        }
    }
 
    public function set($name, $value) {
        elgg_deprecated_notice("Use -> instead of set()", 1.9);
        $this->__set($name, $value);
 
        return true;
    }
 
    private function setStatus($active, $site_guid = null) {
        if (!$this->guid) {
            return false;
        }
 
        if ($site_guid) {
            $site = get_entity($site_guid);
 
            if (!($site instanceof \ElggSite)) {
                return false;
            }
        } else {
            $site = _elgg_services()->configTable->get('site');
        }
 
        if ($active) {
            $result = add_entity_relationship($this->guid, 'active_plugin', $site->guid);
        } else {
            $result = remove_entity_relationship($this->guid, 'active_plugin', $site->guid);
        }
 
        _elgg_invalidate_plugins_provides_cache();
        _elgg_services()->boot->invalidateCache();
 
        return $result;
    }
 
    public function getError() {
        return $this->errorMsg;
    }
 
    public function getManifest() {
        if ($this->manifest instanceof \ElggPluginManifest) {
            return $this->manifest;
        }
 
        try {
            $package = $this->getPackage();
            if (!$package) {
                throw new \Exception('Package cannot be loaded');
            }
            $this->manifest = $package->getManifest();
        } catch (Exception $e) {
            _elgg_services()->logger->warn("Failed to load manifest for plugin $this->guid. " . $e->getMessage());
            $this->errorMsg = $e->getmessage();
        }
 
        return $this->manifest;
    }
 
    public function getPackage() {
        if ($this->package instanceof \ElggPluginPackage) {
            return $this->package;
        }
 
        try {
            $this->package = new \ElggPluginPackage($this->path, false);
        } catch (Exception $e) {
            _elgg_services()->logger->warn("Failed to load package for $this->guid. " . $e->getMessage());
            $this->errorMsg = $e->getmessage();
        }
 
        return $this->package;
    }
}