ElggPluginManifest.php

Go to the documentation of this file.

<?php

class ElggPluginManifest {

    protected $parser;

    protected $namespace_root = 'http://www.elgg.org/plugin_manifest/';

    private $depsStructPlugin = [
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => 'ge'
    ];

    private $depsStructPriority = [
        'type' => '',
        'priority' => '',
        'plugin' => ''
    ];

    /*
     * The expected structure of elgg_release requires element
     */
    private $depsStructElgg = [
        'type' => '',
        'version' => '',
        'comparison' => 'ge'
    ];

    private $depsStructPhpVersion = [
        'type' => '',
        'version' => '',
        'comparison' => 'ge'
    ];

    private $depsStructPhpIni = [
        'type' => '',
        'name' => '',
        'value' => '',
        'comparison' => '='
    ];

    private $depsStructPhpExtension = [
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => '='
    ];

    private $depsConflictsStruct = [
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => '='
    ];

    private $depsProvidesStruct = [
        'type' => '',
        'name' => '',
        'version' => ''
    ];

    private $screenshotStruct = [
        'description' => '',
        'path' => ''
    ];

    private $contributorStruct = [
        'name' => '',
        'email' => '',
        'website' => '',
        'username' => '',
        'description' => '',
    ];

    protected $apiVersion;

    protected $pluginID;

    public function __construct($manifest, $plugin_id = null) {
        if ($plugin_id) {
            $this->pluginID = $plugin_id;
        }

        // see if we need to construct the xml object.
        if ($manifest instanceof \ElggXMLElement) {
            $manifest_obj = $manifest;
        } else {
            $raw_xml = '';
            if (substr(trim($manifest), 0, 1) == '<') {
                // this is a string
                $raw_xml = $manifest;
            } elseif (is_file($manifest)) {
                // this is a file
                $raw_xml = file_get_contents($manifest);
            }
            if ($raw_xml) {
                $manifest_obj = new \ElggXMLElement($raw_xml);
            } else {
                $manifest_obj = null;
            }
        }

        if (!$manifest_obj) {
            $msg = elgg_echo('PluginException:InvalidManifest', [$this->getPluginID()]);
            throw PluginException::factory('InvalidManifest', null, $msg);
        }

        // set manifest api version
        if (isset($manifest_obj->attributes['xmlns'])) {
            $namespace = $manifest_obj->attributes['xmlns'];
            $version = str_replace($this->namespace_root, '', $namespace);
        } else {
            $version = '1.7';
        }

        $this->apiVersion = $version;

        $parser_class_name = '\ElggPluginManifestParser' . str_replace('.', '', $this->apiVersion);

        // @todo currently the autoloader freaks out if a class doesn't exist.
        try {
            $class_exists = class_exists($parser_class_name);
        } catch (Exception $e) {
            $class_exists = false;
        }

        if ($class_exists) {
            $this->parser = new $parser_class_name($manifest_obj, $this);
        } else {
            $msg = elgg_echo('PluginException:NoAvailableParser', [$this->apiVersion, $this->getPluginID()]);
            throw PluginException::factory('NoAvailableParser', null, $msg);
        }

        if (!$this->parser->parse()) {
            $msg = elgg_echo('PluginException:ParserError', [$this->apiVersion, $this->getPluginID()]);
            throw PluginException::factory('ParseError', null, $msg);
        }
    }

    public function getApiVersion() {
        return $this->apiVersion;
    }

    public function getPluginID() {
        if ($this->pluginID) {
            return $this->pluginID;
        } else {
            return elgg_echo('unknown');
        }
    }

    public function getManifest() {
        return $this->parser->getManifest();
    }

    /***************************************
     * Parsed and Normalized Manifest Data *
     ***************************************/

    public function getName() {
        $name = $this->parser->getAttribute('name');

        if (!$name && $this->pluginID) {
            $name = ucwords(str_replace('_', ' ', $this->pluginID));
        }

        return $name;
    }

    public function getID() {
        return trim((string) $this->parser->getAttribute('id'));
    }


    public function getDescription() {
        return (string) $this->parser->getAttribute('description');
    }

    public function getBlurb() {
        $blurb = $this->parser->getAttribute('blurb');

        if (!$blurb) {
            $blurb = elgg_get_excerpt($this->getDescription());
        }

        return $blurb;
    }

    public function getLicense() {
        // license vs licence.  Use license.
        $en_us = $this->parser->getAttribute('license');
        
        return (string) ($en_us ?: $this->parser->getAttribute('licence'));
    }

    public function getRepositoryURL() {
        return (string) $this->parser->getAttribute('repository');
    }

    public function getBugTrackerURL() {
        return (string) $this->parser->getAttribute('bugtracker');
    }

    public function getDonationsPageURL() {
        return (string) $this->parser->getAttribute('donations');
    }

    public function getVersion() {
        return $this->parser->getAttribute('version');
    }

    public function getAuthor() {
        return (string) $this->parser->getAttribute('author');
    }

    public function getCopyright() {
        return (string) $this->parser->getAttribute('copyright');
    }

    public function getWebsite() {
        return (string) $this->parser->getAttribute('website');
    }

    public function getCategories() {
        $bundled_plugins = [
            'activity',
            'blog',
            'bookmarks',
            'ckeditor',
            'custom_index',
            'dashboard',
            'developers',
            'diagnostics',
            'discussions',
            'embed',
            'externalpages',
            'file',
            'friends',
            'friends_collections',
            'garbagecollector',
            'groups',
            'invitefriends',
            'likes',
            'login_as',
            'members',
            'messageboard',
            'messages',
            'notifications',
            'pages',
            'profile',
            'reportedcontent',
            'search',
            'site_notifications',
            'system_log',
            'tagcloud',
            'thewire',
            'uservalidationbyemail',
            'web_services',
        ];

        $cats = $this->parser->getAttribute('category');

        if (!$cats) {
            $cats = [];
        }

        if (in_array('bundled', $cats) && !in_array($this->getPluginID(), $bundled_plugins)) {
            unset($cats[array_search('bundled', $cats)]);
        }

        return $cats;
    }

    public function getScreenshots() {
        $ss = $this->parser->getAttribute('screenshot');

        if (!$ss) {
            $ss = [];
        }

        $normalized = [];
        foreach ($ss as $s) {
            $normalized[] = $this->buildStruct($this->screenshotStruct, $s);
        }

        return $normalized;
    }

    public function getContributors() {
        $ss = $this->parser->getAttribute('contributor');

        if (!$ss) {
            $ss = [];
        }

        $normalized = [];
        foreach ($ss as $s) {
            $normalized[] = $this->buildStruct($this->contributorStruct, $s);
        }

        return $normalized;
    }

    public function getProvides() {
        // normalize for 1.7
        if ($this->getApiVersion() < 1.8) {
            $provides = [];
        } else {
            $provides = $this->parser->getAttribute('provides');
        }

        if (!$provides) {
            $provides = [];
        }

        // always provide ourself if we can
        if ($this->pluginID) {
            $provides[] = [
                'type' => 'plugin',
                'name' => $this->getPluginID(),
                'version' => $this->getVersion()
            ];
        }

        $normalized = [];
        foreach ($provides as $provide) {
            $normalized[] = $this->buildStruct($this->depsProvidesStruct, $provide);
        }

        return $normalized;
    }

    public function getRequires() {
        $reqs = $this->parser->getAttribute('requires');

        if (!$reqs) {
            $reqs = [];
        }

        $normalized = [];
        foreach ($reqs as $req) {
            $normalized[] = $this->normalizeDep($req);
        }

        return $normalized;
    }

    public function getSuggests() {
        $suggests = $this->parser->getAttribute('suggests');

        if (!$suggests) {
            $suggests = [];
        }

        $normalized = [];
        foreach ($suggests as $suggest) {
            $normalized[] = $this->normalizeDep($suggest);
        }

        return $normalized;
    }

    private function normalizeDep($dep) {
        
        $struct = [];
        
        switch ($dep['type']) {
            case 'elgg_release':
                $struct = $this->depsStructElgg;
                break;

            case 'plugin':
                $struct = $this->depsStructPlugin;
                break;

            case 'priority':
                $struct = $this->depsStructPriority;
                break;

            case 'php_version':
                $struct = $this->depsStructPhpVersion;
                break;

            case 'php_extension':
                $struct = $this->depsStructPhpExtension;
                break;

            case 'php_ini':
                $struct = $this->depsStructPhpIni;

                // also normalize boolean values
                if (isset($dep['value'])) {
                    switch (strtolower($dep['value'])) {
                        case 'yes':
                        case 'true':
                        case 'on':
                        case 1:
                            $dep['value'] = 1;
                            break;

                        case 'no':
                        case 'false':
                        case 'off':
                        case 0:
                        case '':
                            $dep['value'] = 0;
                            break;
                    }
                }
                break;
            default:
                // unrecognized so we just return the raw dependency
                return $dep;
        }
        
        $normalized_dep = $this->buildStruct($struct, $dep);

        // normalize comparison operators
        if (isset($normalized_dep['comparison'])) {
            switch ($normalized_dep['comparison']) {
                case '<':
                    $normalized_dep['comparison'] = 'lt';
                    break;

                case '<=':
                    $normalized_dep['comparison'] = 'le';
                    break;

                case '>':
                    $normalized_dep['comparison'] = 'gt';
                    break;

                case '>=':
                    $normalized_dep['comparison'] = 'ge';
                    break;

                case '==':
                case 'eq':
                    $normalized_dep['comparison'] = '=';
                    break;

                case '<>':
                case 'ne':
                    $normalized_dep['comparison'] = '!=';
                    break;
            }
        }

        return $normalized_dep;
    }

    public function getConflicts() {
        // normalize for 1.7
        if ($this->getApiVersion() < 1.8) {
            $conflicts = [];
        } else {
            $conflicts = $this->parser->getAttribute('conflicts');
        }

        if (!$conflicts) {
            $conflicts = [];
        }

        $normalized = [];

        foreach ($conflicts as $conflict) {
            $normalized[] = $this->buildStruct($this->depsConflictsStruct, $conflict);
        }

        return $normalized;
    }

    public function getActivateOnInstall() {
        $activate = $this->parser->getAttribute('activate_on_install');
        if ($activate === false) {
            return false;
        }
        
        // these are the truthy supported values, everything else will result in false
        switch (strtolower($activate)) {
            case 'yes':
            case 'true':
            case 'on':
            case 1:
                return true;
        }
        
        return false;
    }

    protected function buildStruct(array $struct, array $array) {
        $return = [];

        foreach ($struct as $index => $default) {
            $return[$index] = elgg_extract($index, $array, $default);
        }

        return $return;
    }

    public static function getFriendlyCategory($category) {
        $cat_raw_string = "admin:plugins:category:$category";
        if (_elgg_services()->translator->languageKeyExists($cat_raw_string)) {
            return elgg_echo($cat_raw_string);
        }
        
        $category = str_replace(['-', '_'], ' ', $category);
        return ucwords($category);
    }
}