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 = array(
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => 'ge'
    );

    private $depsStructPriority = array(
        'type' => '',
        'priority' => '',
        'plugin' => ''
    );

    /*
     * The expected structure of elgg_version and elgg_release requires element
     */
    private $depsStructElgg = array(
        'type' => '',
        'version' => '',
        'comparison' => 'ge'
    );
    
    private $depsStructPhpVersion = array(
        'type' => '',
        'version' => '',
        'comparison' => 'ge'
    );

    private $depsStructPhpIni = array(
        'type' => '',
        'name' => '',
        'value' => '',
        'comparison' => '='
    );

    private $depsStructPhpExtension = array(
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => '='
    );

    private $depsConflictsStruct = array(
        'type' => '',
        'name' => '',
        'version' => '',
        'comparison' => '='
    );

    private $depsProvidesStruct = array(
        'type' => '',
        'name' => '',
        'version' => ''
    );

    private $screenshotStruct = array(
        'description' => '',
        'path' => ''
    );
    
    private $contributorStruct = array(
        '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) {
            throw new \PluginException(_elgg_services()->translator->translate('PluginException:InvalidManifest',
                        array($this->getPluginID())));
        }

        // 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 {
            throw new \PluginException(_elgg_services()->translator->translate('PluginException:NoAvailableParser',
                            array($this->apiVersion, $this->getPluginID())));
        }

        if (!$this->parser->parse()) {
            throw new \PluginException(_elgg_services()->translator->translate('PluginException:ParserError',
                        array($this->apiVersion, $this->getPluginID())));
        }
    }

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

    public function getPluginID() {
        if ($this->pluginID) {
            return $this->pluginID;
        } else {
            return _elgg_services()->translator->translate('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 $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');
        if ($en_us) {
            return $en_us;
        } else {
            return $this->parser->getAttribute('licence');
        }
    }

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

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

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

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

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

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

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

    public function getCategories() {
        $bundled_plugins = array(
            'aalborg_theme',
            'blog',
            'bookmarks',
            'categories',
            'ckeditor',
            'custom_index',
            'dashboard',
            'developers',
            'diagnostics',
            'embed',
            'externalpages',
            'file',
            'garbagecollector',
            'groups',
            'htmlawed',
            'invitefriends',
            'legacy_urls',
            'likes',
            'logbrowser',
            'login_as',
            'logrotate',
            'members',
            'messageboard',
            'messages',
            'notifications',
            'pages',
            'profile',
            'reportedcontent',
            'search',
            'site_notifications',
            'tagcloud',
            'thewire',
            'twitter_api',
            'uservalidationbyemail',
            'web_services',
            'zaudio',
        );

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

        if (!$cats) {
            $cats = array();
        }

        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 = array();
        }

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

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

        if (!$ss) {
            $ss = array();
        }

        $normalized = array();
        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 = array();
        } else {
            $provides = $this->parser->getAttribute('provides');
        }

        if (!$provides) {
            $provides = array();
        }

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

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

        return $normalized;
    }

    public function getRequires() {
        // rewrite the 1.7 style elgg_version as a real requires.
        if ($this->apiVersion < 1.8) {
            $elgg_version = $this->parser->getAttribute('elgg_version');
            if ($elgg_version) {
                $reqs = array(
                    array(
                        'type' => 'elgg_version',
                        'version' => $elgg_version,
                        'comparison' => 'ge'
                    )
                );
            } else {
                $reqs = array();
            }
        } else {
            $reqs = $this->parser->getAttribute('requires');
        }

        if (!$reqs) {
            $reqs = array();
        }

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

        return $normalized;
    }

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

        if (!$suggests) {
            $suggests = array();
        }

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

        return $normalized;
    }

    private function normalizeDep($dep) {
        switch ($dep['type']) {
            case 'elgg_version':
            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;
        }

        // @todo $struct may not have been defined...
        $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 = array();
        } else {
            $conflicts = $this->parser->getAttribute('conflicts');
        }

        if (!$conflicts) {
            $conflicts = array();
        }

        $normalized = array();

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

        return $normalized;
    }

    public function getActivateOnInstall() {
        $activate = $this->parser->getAttribute('activate_on_install');
        switch (strtolower($activate)) {
            case 'yes':
            case 'true':
            case 'on':
            case 1:
                return true;

            case 'no':
            case 'false':
            case 'off':
            case 0:
            case '':
                return false;
        }
    }

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

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

        return $return;
    }

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