smtech / stmarks-reflexive-canvas-lti

src/Toolbox.php

<?php

namespace smtech\StMarksReflexiveCanvasLTI;

use LTI_Tool_Consumer;
use LTI_Data_Connector;

use Battis\HierarchicalSimpleCache;
use Battis\DataUtilities;
use Battis\BootstrapSmarty\NotificationMessage;

use smtech\StMarksSmarty\StMarksSmarty;
use smtech\ReflexiveCanvasLTI\Exception\ConfigurationException;

/**
 * Add HTML templating and basic caching to the ReflexiveCanvasLTI Toolbox
 *
 * @author Seth Battis <SethBattis@stmarksschool.org>
 * @version v0.1
 */
class Toolbox extends \smtech\ReflexiveCanvasLTI\Toolbox
{

    /**
     * Cache manager
     * @var HierarchicalSimpleCache
     */
    protected $cache;

    /**
     * St. Mark's-styled HTML templating
     * @var StMarksSmarty
     */
    protected $smarty;

    /**
     * Update a Toolbox instance from a configuration file
     *
     * Extends the inherited `Toolbox::loadConfiguration()` to add two
     * additional pieces of configuration metadata:
     *
     *   - `APP_PATH` is the path to the Tool Provider app
     *   - `APP_URL` is the URL of the Tool Provider app
     *
     * Also stores the API access token acquired by `interactiveGetAccessToken()`.
     *
     * @see interactiveGetAccessToken() `interactiveGetAccessToken()`
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/smtech/reflexive-canvas-lti/master/doc/classes/smtech.ReflexiveCanvasLTI.Toolbox.html#method_loadConfiguration `smtech\ReflexiveCanvasLTI\Toolbox::loadConfiguration()`
     *
     * @param string $configFilePath
     * @param boolean $forceRecache (Optional, default `false`)
     * @return void
     */
    protected function loadConfiguration($configFilePath, $forceRecache = false)
    {
        parent::loadConfiguration($configFilePath, $forceRecache);

        /* patch in passed back API access token, if present */
        if (!empty($_SESSION['TOOL_CANVAS_API'])) {
            $this->metadata['TOOL_CANVAS_API'] = $_SESSION['TOOL_CANVAS_API'];
            unset($_SESSION['TOOL_CANVAS_API']);
        }

        if ($forceRecache || empty($this->config('APP_PATH'))) {
            $this->config('APP_PATH', dirname($this->config('TOOL_CONFIG_FILE')));
        }

        if ($forceRecache || empty($this->config('APP_URL'))) {
            $this->config('APP_URL', DataUtilities::URLfromPath($this->config('APP_PATH')));
        }
    }

    /**
     * Interactively acquire an API access token
     *
     * `/config/canvas/key` and `/config/canvas/secret` must be defined in
     * `config.xml` for this to work!
     *
     * @param string $reason Explanation of why an API access token is necessary
     * @param string $redirectURL (Optional, defaults to
     *     `$_SERVER['REQUEST_URI']`) URL of page to redirect to after
     *     acquiring access token
     * @param string $errorURL (Optional) URL of page to redirect to on error
     * @return void
     */
    public function interactiveGetAccessToken($reason = null, $redirectURL = null, $errorURL = null)
    {
        $redirectURL = (
            empty($redirectURL) ?
                $_SERVER['REQUEST_URI'] :
                $redirectURL
        );
        $errorURL = (
            empty($errorURL) ?
                DataUtilities::URLfromPath(__DIR__ . '/../error.php') :
                $errorURL
        );
        $canvas = $this->metadata['TOOL_CANVAS_API'];
        if (!empty($canvas['key']) && !empty($canvas['secret'])) {
            /* if so, request an API access token interactively */
            if (session_status() !== PHP_SESSION_ACTIVE) {
                session_start();
            }
            $_SESSION['oauth'] = [
                'purpose' => $this->metadata['TOOL_NAME'],
                'key' => $canvas['key'],
                'secret' => $canvas['secret']
            ];
            header(
                'Location: ' . DataUtilities::URLfromPath(__DIR__ . '/../oauth.php') .
                '?' . http_build_query([
                    'oauth-return' => $redirectURL,
                    'oauth-error' => $errorURL,
                    'reason' => $reason
                ])
            );
            return;
        } else { /* no (understandable) API credentials available -- doh! */
            throw new ConfigurationException(
                'Missing OAuth key/secret pair in configuration, which is ' .
                'required to interactively acquire an API access token',
                ConfigurationException::CANVAS_API_MISSING
            );
        }
    }

    /**
     * Create a (potentially new) LTI_Tool_Consumer
     *
     * @param string $key (Optional)
     * @return LTI_Tool_Consumer
     */
    private function interactiveConsumersControlPanel_loadConsumer($key = null)
    {
        /*
         * load an existing consumer (if we have a consumer_key) or create a blank
         * that we will fill in
         */
        $consumer = new LTI_Tool_Consumer(
            (empty($key) ? LTI_Data_Connector::getRandomString(32) : $key),
            $this->getToolProvider()->data_connector,
            true // wicked confusing _not_ to autoenable
        );

        /* pre-fill secret if not editing an existing consumer */
        if (empty($key)) {
            $consumer->secret = LTI_Data_Connector::getRandomString(32);
        }

        return $consumer;
    }

    /**
     * Handle tool consumer management interactively
     *
     * Display and manage a control panel for managing Tool Consumers
     * interactively.
     *
     * @uses interactiveConsumersControlPanel_loadConsumer() `interactiveConsumersControlPanel_loadConsumer()`
     * @return void
     */
    public function interactiveConsumersControlPanel()
    {
        /* clean request values */
        $name = (empty($_POST['name']) ? null : trim($_POST['name']));
        $key = (empty($_POST['key']) ? null : trim($_POST['key']));
        $secret = (empty($_POST['secret']) ? null : trim($_POST['secret']));
        $enabled = (empty($_POST['enabled']) ? false : (boolean) $_POST['enabled']);
        $action = (empty($_POST['action']) ? false : strtolower(trim($_POST['action'])));

        /* load requested consumer (or create new if none requested) */
        $consumer = $this->interactiveConsumersControlPanel_loadConsumer($key);

        /* what are we asked to do with this consumer? */
        switch ($action) {
            case 'update':
            case 'insert':
                $consumer->name = $name;
                $consumer->secret = $secret;
                $consumer->enabled = $enabled;
                if (!$consumer->save()) {
                    $this->smarty_addMessage(
                        'Error saving consumer',
                        'There was an error attempting to save your new or ' .
                        'updated consumer information to the database.',
                        NotificationMessage::DANGER
                    );
                }
                break;
            case 'delete':
                $consumer->delete();
                break;
            case 'select':
                $this->smarty_assign('key', $key);
                break;
        }

        /*
         * if action was anything other than 'select', create a new empty
         * consumer to fill the form with
         */
        if ($action && $action !== 'select') {
            $consumer = $this->interactiveConsumersControlPanel_loadConsumer();
        }

        /* display a list of consumers */
        $consumers = $this->lti_getConsumers();
        $this->smarty_assign([

array('name' => 'Consumers', 'category' => 'Control Panel', 'consumers' => $consumers, 'consumer' => $consumer, 'formAction' => $_SERVER['PHP_SELF'], 'appUrl' => $this->metadata['APP_URL']) is of type array<string,?,{"name":"string","category":"string","consumers":"array<integer,object<smtech\\ReflexiveCanvasLTI\\LTI_Consumer>>","consumer":"object<LTI_Tool_Consumer>","formAction":"?","appUrl":"?"}>, but the function expects a string.

            'name' => 'Consumers',
            'category' => 'Control Panel',
            'consumers' => $consumers,
            'consumer' => $consumer,
            'formAction' => $_SERVER['PHP_SELF'],
            'appUrl' => $this->metadata['APP_URL']
        ]);
        $this->smarty_display('consumers-control-panel.tpl');
    }

    /**
     * Update the cache manager
     *
     * @param HierarchicalSimpleCache $cache
     */
    public function setCache(HierarchicalSimpleCache $cache)
    {
        $this->cache = $cache;
    }

    /**
     * Get the cache manager
     *
     * @return HierarchicalSimpleCache
     */
    public function getCache()
    {
        if (empty($this->cache)) {
            $this->cache = new HierarchicalSimpleCache($this->getMySQL(), basename(__FILE__, '.php'));
        }
        return $this->cache;
    }

    /**
     * Push a hierarchical layer to the cache
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/simplecache/master/doc/classes/Battis.HierarchicalSimpleCache.html#method_pushKey Pass-through to `HierarchicalSimpleCache::pushKey()`
     *
     * @param  string $layer
     * @return string
     */
    public function cache_pushKey($layer)
    {
        return $this->getCache()->pushKey($layer);
    }

    /**
     * Pop a hierarchical layer off of the cache
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/simplecache/master/doc/classes/Battis.HierarchicalSimpleCache.html#method_popKey Pass-through to `HierarchicalSimpleCache::popKey()`
     *
     * @return string|null
     */
    public function cache_popKey()
    {
        return $this->getCache()->popKey();
    }

    /**
     * Retrieve a cached value
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/simplecache/master/doc/classes/Battis.HierarchicalSimpleCache.html#method_getCache Pass-through to `HierarchicalSimpleCache::getCache()`
     *
     * @param string $key
     * @return mixed
     */
    public function cache_get($key)
    {
        return $this->getCache()->getCache($key);
    }

    /**
     * Set a cached value
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/simplecache/master/doc/classes/Battis.HierarchicalSimpleCache.html#method_setCache Pass-through to `HierarchicalSimpleCache::setCache()`
     *
     * @param string $key
     * @param mixed $data
     * @return boolean
     */
    public function cache_set($key, $data)
    {
        return $this->getCache()->setCache($key, $data);
    }

    /**
     * Update the HTML templating engine
     *
     * @param StMarksSmarty $smarty
     */
    public function setSmarty(StMarksSmarty $smarty)
    {
        $this->smarty = $smarty;
    }

    /**
     * Get the HTML templating engine
     *
     * @return StMarksSmarty
     */
    public function getSmarty()
    {
        if (empty($this->smarty)) {
            $this->smarty = StMarksSmarty::getSmarty();
            $this->smarty->prependTemplateDir(realpath(__DIR__ . '/../templates'), __CLASS__);
            $this->smarty->setFramed(true);
        }
        return $this->smarty;
    }

    /**
     * Assign a value to a template variables
     *
     * @link http://www.smarty.net/docs/en/api.assign.tpl Pass-through to `Smarty::assign()`
     *
     * @param string $varname
     * @param mixed $var
     * @param boolean $noCache (Optional, default `false`)
     * @return void
     */
    public function smarty_assign($varname, $var = null, $noCache = false)
    {
        return $this->getSmarty()->assign($varname, $var, $noCache);
    }

    /**
     * Register another template directory
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/BootstrapSmarty/master/doc/classes/Battis.BootstrapSmarty.BootstrapSmarty.html#method_addTemplateDir Pass-through to `BootstrapSmarty::addTemplateDir()`
     *
     * @param string $template
     * @param string $key (Optional, default `null`)
     * @param boolean $isConfig (Optional, default `false`)
     */
    public function smarty_addTemplateDir($template, $key = null, $isConfig = false)
    {
        return $this->getSmarty()->addTemplateDir($template, $key, $isConfig);
    }

    /**
     * Prepend an over-riding template directory to Smarty
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/BootstrapSmarty/master/doc/classes/Battis.BootstrapSmarty.BootstrapSmarty.html#method_prependTemplateDir Pass-through to `BootstrapSmarty::prependTemplateDir()`
     *
     * @param string $template
     * @param string $key (Optional)
     */
    public function smarty_prependTemplateDir($template, $key = null) {
        return $this->getSmarty()->prependTemplateDir($template, $key);
    }

    /**
     * Add a message to be displayed to the user
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/BootstrapSmarty/master/doc/classes/Battis.BootstrapSmarty.BootstrapSmarty.html#method_addMessage Pass-through to `BootstrapSmarty::addMessage()`
     *
     * @param string $title
     * @param string $content
     * @param string $class (Optional, default `NotificationMessage::INFO`)
     */
    public function smarty_addMessage($title, $content, $class = NotificationMessage::INFO)
    {
        return $this->getSmarty()->addMessage($title, $content, $class);
    }

    /**
     * Display an HTML template
     *
     * @link https://htmlpreview.github.io/?https://raw.githubusercontent.com/battis/BootstrapSmarty/master/doc/classes/Battis.BootstrapSmarty.BootstrapSmarty.html#method_display Pass-through to `BootstrapSmarty::display()`
     *
     * @param string $template (Optional, default `page.tpl`)
     * @param string $cache_id (Optional, default `null`)
     * @param string $compile_id (Optional, default, `null`)
     * @param string $parent (Optional, default `null`)
     * @return void
     */
    public function smarty_display($template = 'page.tpl', $cache_id = null, $compile_id = null, $parent = null)
    {
        return $this->getSmarty()->display($template, $cache_id, $compile_id, $parent);
    }
}