ElggPlugin.php

Go to the documentation of this file.

<?php
class ElggPlugin extends ElggObject {
    private $package;
    private $manifest;

    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_get_plugins_path() . $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_get_plugins_path() . $this->getID();
        } else {
            $this->initializeAttributes();

            $mod_dir = elgg_get_plugins_path();

            // 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 = get_config('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 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 = get_config('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) {
        $val = $this->$name;
        return $val !== null ? $val : $default;
    }

    public function getAllSettings() {
        if (!$this->guid) {
            return false;
        }

        $db_prefix = elgg_get_config('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);
        
        return $this->setPrivateSetting($name, $value);
    }

    public function unsetSetting($name) {
        return remove_private_setting($this->guid, $name);
    }

    public function unsetAllSettings() {
        $db_prefix = get_config('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) {
        $user_guid = (int)$user_guid;

        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = elgg_get_logged_in_user_entity();
        }

        if (!($user instanceof ElggUser)) {
            return false;
        }

        $name = _elgg_namespace_plugin_private_setting('user_setting', $name, $this->getID());
        return get_private_setting($user->guid, $name);
    }

    public function getAllUserSettings($user_guid = 0) {
        $user_guid = (int)$user_guid;

        if ($user_guid) {
            $user = get_entity($user_guid);
        } else {
            $user = elgg_get_logged_in_user_entity();
        }

        if (!($user instanceof ElggUser)) {
            return false;
        }

        $db_prefix = elgg_get_config('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_get_logged_in_user_entity();
        }

        if (!($user instanceof ElggUser)) {
            return false;
        }

        // Hook to validate setting
        // note: this doesn't pass the namespaced name
        $value = elgg_trigger_plugin_hook('usersetting', 'plugin', array(
            'user' => $user,
            'plugin' => $this,
            'plugin_id' => $this->getID(),
            'name' => $name,
            'value' => $value
        ), $value);

        // 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_get_logged_in_user_entity();
        }

        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 = get_config('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 = get_config('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_echo('ElggPlugin:MissingID', array($this->guid));
            return false;
        }

        if (!$this->getPackage() instanceof ElggPluginPackage) {
            $this->errorMsg = elgg_echo('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 = get_config('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->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;
        }

        // set in the db, now perform tasks and emit events
        if ($this->setStatus(true, $site_guid)) {
            // 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_trigger_event('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;
        }

        return false;
    }

    public function deactivate($site_guid = null) {
        if (!$this->isActive($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_trigger_event('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 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') {
            global $CONFIG;
        }

        $filepath = "$this->path/$filename";

        if (!$this->canReadFile($filename)) {
            $msg = elgg_echo('ElggPlugin:Exception:CannotIncludeFile',
                            array($filename, $this->getID(), $this->guid, $this->path));
            throw new PluginException($msg);
        }

        return include $filepath;
    }

    protected function canReadFile($filename) {
        return is_readable($this->path . '/' . $filename);
    }

    protected function registerViews() {
        $view_dir = "$this->path/views/";

        // plugins don't have to have views.
        if (!is_dir($view_dir)) {
            return true;
        }

        // but if they do, they have to be readable
        $handle = opendir($view_dir);
        if (!$handle) {
            $msg = elgg_echo('ElggPlugin:Exception:CannotRegisterViews',
                            array($this->getID(), $this->guid, $view_dir));
            throw new PluginException($msg);
        }

        while (false !== ($view_type = readdir($handle))) {
            $view_type_dir = $view_dir . $view_type;

            if ('.' !== substr($view_type, 0, 1) && is_dir($view_type_dir)) {
                if (autoregister_views('', $view_type_dir, $view_dir, $view_type)) {
                    elgg_register_viewtype($view_type);
                } else {
                    $msg = elgg_echo('ElggPlugin:Exception:CannotRegisterViews',
                                    array($this->getID(), $view_type_dir));
                    throw new PluginException($msg);
                }
            }
        }

        return true;
    }

    protected function registerLanguages() {
        $languages_path = "$this->path/languages";

        // don't need to have classes
        if (!is_dir($languages_path)) {
            return true;
        }

        // but need to have working ones.
        if (!register_translations($languages_path)) {
            $msg = elgg_echo('ElggPlugin:Exception:CannotRegisterLanguages',
                            array($this->getID(), $this->guid, $languages_path));
            throw new PluginException($msg);
        }

        return true;
    }

    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) {
        // rewrite for old and inaccurate plugin:setting
        if (strstr($name, 'plugin:setting:')) {
            $msg = 'Direct access of user settings is deprecated. Use ElggPlugin->getUserSetting()';
            elgg_deprecated_notice($msg, 1.8);
            $name = str_replace('plugin:setting:', '', $name);
            $name = _elgg_namespace_plugin_private_setting('user_setting', $name, $this->getID());
        }

        // 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 = get_config('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();

        return $result;
    }

    public function getError() {
        return $this->errorMsg;
    }

    public function getManifest() {
        if ($this->manifest instanceof ElggPluginManifest) {
            return $this->manifest;
        }

        try {
            $this->manifest = $this->getPackage()->getManifest();
        } catch (Exception $e) {
            elgg_log("Failed to load manifest for plugin $this->guid. " . $e->getMessage(), 'WARNING');
            $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_log("Failed to load package for $this->guid. " . $e->getMessage(), 'WARNING');
            $this->errorMsg = $e->getmessage();
        }

        return $this->package;
    }
}