Source for file plugins.php

Documentation is available at plugins.php

  1. <?php
  2. /**
  3. * Defines a library class for managing SLOODLE Plugins.
  4. * It is constructed and used through a SloodleSession object.
  5. *
  6. * @package sloodle
  7. * @copyright Copyright (c) 2009 Sloodle (various contributors)
  8. * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  9. *
  10. * @contributor Peter R. Bloomfield
  11. */
  12.  
  13.  
  14. // This library expects that the Sloodle config file has already been included
  15. //  (along with the Moodle libraries)
  16.  
  17. /** Include the general Sloodle functionality. */
  18. require_once(SLOODLE_DIRROOT.'/lib/general.php');
  19.  
  20.  
  21. /**
  22. * A class to load SLOODLE plugins, and provide a means to access them.
  23. * @package sloodle
  24. */
  25. class SloodlePluginManager
  26. {
  27. // DATA //
  28.  
  29.     /**
  30.     * Internal only - reference to the containing {@link SloodleSession} object.
  31.     * Note: always check that it is not null before use!
  32.     * @var object 
  33.     * @access protected
  34.     */
  35.     var $_session = null;
  36.  
  37.     /**
  38.     * Plugin instance cache.
  39.     * Stores the plugins which have already been created, to prevent new ones being instantiated unnecessarily.
  40.     * Is an associative array of plugin names to plugin objects.
  41.     * @var array 
  42.     * @access protected
  43.     */
  44.     var $plugin_cache = array();
  45.  
  46.     
  47. // FUNCTIONS //
  48.  
  49.     /**
  50.     * Class constructor.
  51.     * @param object &$_session Reference to the containing {@link SloodleSession} object, if available.
  52.     * @access public
  53.     */
  54.     function SloodlePluginManager(&$_session)
  55.     {
  56.         if (!is_null($_session)) $this->_session = &$_session;
  57.     }
  58.  
  59.     /**
  60.     * Loads all available plugins from the specified folder.
  61.     * @param string $folder Name of the folder to load plugins from. This is a sub-folder of the 'sloodle/plugin' folder. It will only load files which are directly contained inside it.
  62.     * @return bool True if successful, or false if it fails. (It will only report failure if the folder does not exist, or there is an error accessing it.)
  63.     */
  64.     function load_plugins($folder)
  65.     {
  66.         if (empty($folder)) return false;
  67.  
  68.         // Get a list of all the files in the specified folder
  69.         $pluginFolder = SLOODLE_DIRROOT.'/plugin/'.$folder;
  70.         $files = sloodle_get_files($pluginFolder, true);
  71.         if (!$files) return false;
  72.         if (count($files) == 0) return true;
  73.  
  74.         // Start by including the relevant base class files, if they are available
  75.         @include_once(SLOODLE_DIRROOT.'/plugin/_base.php');
  76.         @include_once($pluginFolder.'/_base.php');
  77.  
  78.         // Go through each filename
  79.         foreach ($files as $file) {
  80.             // Include the specified file
  81.             include_once($pluginFolder.'/'.$file);
  82.         }
  83.  
  84.         return true;
  85.     }
  86.     
  87.     /**
  88.     * Gets an array of the names of all SLOODLE plugins derived from the specified type.
  89.     * By default, this gets all plugins. Specify a different base class to get others.
  90.     * NOTE: this will search all plugins loaded by all plugin managers in the current PHP script.
  91.     * (There is no way to tell which manager loaded which plugins.)
  92.     * Plugin names correspond to class names, with the 'SloodlePlugin' prefix.
  93.     * @param string $type Name of a plugin base class.
  94.     * @return array Numeric array of plugin names. These names correspond to class names.
  95.     */
  96.     function get_plugin_names($type = 'SloodlePluginBase')
  97.     {
  98.         // We want to create an array of plugin names
  99.         $plugins = array();
  100.  
  101.         // Go through all declared classes
  102.         $classes = get_declared_classes();
  103.         foreach ($classes as $className) {
  104.             // Make sure this is a SLOODLE plugin by checking that it starts "SloodlePlugin" but not "SloodlePluginbase"
  105.             if (strpos($className, 'SloodlePlugin') !== 0 || strpos($className, 'SloodlePluginBase') === 0) continue;
  106.             // Make sure this is not one of the supporting classes
  107.             if ($className == 'SloodlePluginBase' || $className == 'SloodlePluginManager') continue;
  108.  
  109.             // Make sure it is in fact a plugin by ensuring it is appropriately derived from the given base plugin class
  110.             $tempPlugin = @new $className();
  111.             if (!is_subclass_of($tempPlugin, $type)) continue;
  112.  
  113.             // Remove the 'SloodlePlugin' prefix from the class name
  114.             $className = substr($className, 13);
  115.             $plugins[] = $className;
  116.         }
  117.  
  118.         return $plugins;
  119.     }
  120.  
  121.     /**
  122.     * Gets an instance of the specified plugin type.
  123.     * This only works if the plugin has been loaded, and if it is derived from SloodlePluginBase.
  124.     * @param string $name Name of the plugin type to get. If it does not start with "SloodlePlugin", then that is added to the start.
  125.     * @param bool $forcenew If false (default) then a cached instance of the plugin will be returned. Set this to true to force the manager to create a new plugin instance.
  126.     * @return object|boolAn object descended from SloodlePluginBase if successful, or false on failure.
  127.     */
  128.     function get_plugin($name, $forcenew = false)
  129.     {
  130.         // Prepend 'SloodlePlugin' if necessary
  131.         if (strpos($name, 'SloodlePlugin') !== 0) $name = 'SloodlePlugin'.$name;
  132.         // Make sure the specified class exists
  133.         if (!class_exists($name)) return false;
  134.         // Do we have a cached plugin of this type?
  135.         if ($forcenew == false && !empty($this->plugin_cache[$name]) && is_a($this->plugin_cache[$name], $name)) return $this->plugin_cache[$name];
  136.  
  137.         // Attempt to construct an instance of the plugin
  138.         $plugin = new $name();
  139.         // Make sure it is a valid plugin
  140.         if (is_subclass_of($plugin, 'SloodlePluginBase')) {
  141.             $this->plugin_cache[$name] = $plugin;
  142.             return $plugin;
  143.         }
  144.         return false;
  145.     }
  146.  
  147. }
  148.  
  149. ?>

Documentation generated on Fri, 17 Jul 2009 11:02:22 +0100 by phpDocumentor 1.4.0