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;
    }
}