Location: PHPKode > projects > Nucleus CMS Weblog > nucleus3.64/nucleus/libs/PLUGIN.php
<?php
	/*
	 * Nucleus: PHP/MySQL Weblog CMS (http://nucleuscms.org/)
	 * Copyright (C) 2002-2009 The Nucleus Group
	 *
	 * This program is free software; you can redistribute it and/or
	 * modify it under the terms of the GNU General Public License
	 * as published by the Free Software Foundation; either version 2
	 * of the License, or (at your option) any later version.
	 * (see nucleus/documentation/index.html#license for more info)
	 */
	/**
	 * This is an (abstract) class of which all Nucleus Plugins must inherit
	 *
	 * for more information on plugins and how to write your own, see the
	 * plugins.html file that is included with the Nucleus documenation
	 *
	 * @license http://nucleuscms.org/license.txt GNU General Public License
	 * @copyright Copyright (C) 2002-2009 The Nucleus Group
	 * @version $Id: PLUGIN.php 1470 2010-11-29 22:10:16Z ftruscot $
	 */
	class NucleusPlugin {

		// these functions _have_ to be redefined in your plugin

		function getName() { return 'Undefined'; }
		function getAuthor()  { return 'Undefined'; }
		function getURL()  { return 'Undefined'; }
		function getVersion() { return '0.0'; }
		function getDescription() { return 'Undefined';}

		// these function _may_ be redefined in your plugin

		function getMinNucleusVersion() { return 150; }
		function getMinNucleusPatchLevel() { return 0; }
		function getEventList() { return array(); }
		function getTableList() { return array(); }
		function hasAdminArea() { return 0; }

		function install() {}
		function unInstall() {}

		function init() {}

		function doSkinVar($skinType) {}
		function doTemplateVar(&$item) {
			$args = func_get_args();
			array_shift($args);
			array_unshift($args, 'template');
			call_user_func_array(array(&$this,'doSkinVar'),$args);
		}
		function doTemplateCommentsVar(&$item, &$comment) {
			$args = func_get_args();
			array_shift($args);
			array_shift($args);
			array_unshift($args, 'template');
			call_user_func_array(array(&$this,'doSkinVar'),$args);
		}
		function doAction($type) { return _ERROR_PLUGIN_NOSUCHACTION; }
		function doIf($key,$value) { return false; }
		function doItemVar (&$item) {}

		/**
		 * Checks if a plugin supports a certain feature.
		 *
		 * @returns 1 if the feature is reported, 0 if not
		 * @param $feature
		 *		Name of the feature. See plugin documentation for more info
		 *			'SqlTablePrefix' -> if the plugin uses the sql_table() method to get table names
		 *			'HelpPage' -> if the plugin provides a helppage
		 *                              'SqlApi' -> if the plugin uses the complete sql_* api (must also require nucleuscms 3.5)
		 */
		function supportsFeature($feature) {
			return 0;
		}

		/**
		 * Report a list of plugin that is required to function
		 *
		 * @returns an array of names of plugin, an empty array indicates no dependency
		 */
		function getPluginDep() { return array(); }

		// these helper functions should not be redefined in your plugin

		/**
		  * Creates a new option for this plugin
		  *
		  * @param name
		  *		A string uniquely identifying your option. (max. length is 20 characters)
		  * @param description
		  *		A description that will show up in the nucleus admin area (max. length: 255 characters)
		  * @param type
		  *		Either 'text', 'yesno' or 'password'
		  *		This info is used when showing 'edit plugin options' screens
		  * @param value
		  *		Initial value for the option (max. value length is 128 characters)
		  */
		function createOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
			return $this->_createOption('global', $name, $desc, $type, $defValue, $typeExtras);
		}
		function createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
			return $this->_createOption('blog', $name, $desc, $type, $defValue, $typeExtras);
		}
		function createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
			return $this->_createOption('member', $name, $desc, $type, $defValue, $typeExtras);
		}
		function createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
			return $this->_createOption('category', $name, $desc, $type, $defValue, $typeExtras);
		}
		function createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
			return $this->_createOption('item', $name, $desc, $type, $defValue, $typeExtras);
		}

		/**
		  * Removes the option from the database
		  *
		  * Note: Options get erased automatically on plugin uninstall
		  */
		function deleteOption($name) {
			return $this->_deleteOption('global', $name);
		}
		function deleteBlogOption($name) {
			return $this->_deleteOption('blog', $name);
		}
		function deleteMemberOption($name) {
			return $this->_deleteOption('member', $name);
		}
		function deleteCategoryOption($name) {
			return $this->_deleteOption('category', $name);
		}
		function deleteItemOption($name) {
			return $this->_deleteOption('item', $name);
		}

		/**
		  * Sets the value of an option to something new
		  */
		function setOption($name, $value) {
			return $this->_setOption('global', 0, $name, $value);
		}
		function setBlogOption($blogid, $name, $value) {
			return $this->_setOption('blog', $blogid, $name, $value);
		}
		function setMemberOption($memberid, $name, $value) {
			return $this->_setOption('member', $memberid, $name, $value);
		}
		function setCategoryOption($catid, $name, $value) {
			return $this->_setOption('category', $catid, $name, $value);
		}
		function setItemOption($itemid, $name, $value) {
			return $this->_setOption('item', $itemid, $name, $value);
		}

		/**
		  * Retrieves the current value for an option
		  */
		function getOption($name)
		{
			// only request the options the very first time. On subsequent requests
			// the static collection is used to save SQL queries.
			if ($this->plugin_options == 0)
			{
				$this->plugin_options = array();
				$query = sql_query(
					 'SELECT d.oname as name, o.ovalue as value '.
					 'FROM '.
					 sql_table('plugin_option').' o, '.
					 sql_table('plugin_option_desc').' d '.
					 'WHERE d.opid='. intval($this->getID()).' AND d.oid=o.oid'
				);
				while ($row = sql_fetch_object($query))
					$this->plugin_options[strtolower($row->name)] = $row->value;
		  }
		  if (isset($this->plugin_options[strtolower($name)]))
				return $this->plugin_options[strtolower($name)];
		  else
				return $this->_getOption('global', 0, $name);
		}

		function getBlogOption($blogid, $name) {
			return $this->_getOption('blog', $blogid, $name);
		}
		function getMemberOption($memberid, $name) {
			return $this->_getOption('member', $memberid, $name);
		}
		function getCategoryOption($catid, $name) {
			return $this->_getOption('category', $catid, $name);
		}
		function getItemOption($itemid, $name) {
			return $this->_getOption('item', $itemid, $name);
		}

		/**
		 * Retrieves an associative array with the option value for each
		 * context id
		 */
		function getAllBlogOptions($name) {
			return $this->_getAllOptions('blog', $name);
		}
		function getAllMemberOptions($name) {
			return $this->_getAllOptions('member', $name);
		}
		function getAllCategoryOptions($name) {
			return $this->_getAllOptions('category', $name);
		}
		function getAllItemOptions($name) {
			return $this->_getAllOptions('item', $name);
		}

		/**
		 * Retrieves an indexed array with the top (or bottom) of an option
		 * (delegates to _getOptionTop())
		 */
		function getBlogOptionTop($name, $amount = 10, $sort = 'desc') {
			return $this->_getOptionTop('blog', $name, $amount, $sort);
		}
		function getMemberOptionTop($name, $amount = 10, $sort = 'desc') {
			return $this->_getOptionTop('member', $name, $amount, $sort);
		}
		function getCategoryOptionTop($name, $amount = 10, $sort = 'desc') {
			return $this->_getOptionTop('category', $name, $amount, $sort);
		}
		function getItemOptionTop($name, $amount = 10, $sort = 'desc') {
			return $this->_getOptionTop('item', $name, $amount, $sort);
		}

		/**
		  * Returns the plugin ID
		  * 
		  * public		  		  
		  */
		function getID() {
			return $this->plugid;
		}

		/**
		  * Returns the URL of the admin area for this plugin (in case there's
		  * no such area, the returned information is invalid)
		  * 
		  * public		  		  
		  */
		function getAdminURL() {
			global $CONF;
			return $CONF['PluginURL'] . $this->getShortName() . '/';
		}

		/**
		  * Returns the directory where the admin directory is located and
		  * where the plugin can maintain his extra files
		  * 
		  * public		  		  
		  */
		function getDirectory() {
			global $DIR_PLUGINS;
			return $DIR_PLUGINS . $this->getShortName() . '/';
		}

		/**
		  * Derives the short name for the plugin from the classname (all 
		  * lowercase)
		  * 
		  * public		  		  
		  */
		function getShortName() {
			return str_replace('np_','',strtolower(get_class($this)));
		}

		/**
		 *	Clears the option value cache which saves the option values during
		 *	the plugin execution. This function is usefull if the options has 
		 *	changed during the plugin execution (especially in association with
		 *	the PrePluginOptionsUpdate and the PostPluginOptionsUpdate events)
		 *	
		 *  public		 		 
		 **/		 		
		function clearOptionValueCache(){
			$this->_aOptionValues = array();
			$this->plugin_options = 0;
		}

		// internal functions of the class starts here

		var $_aOptionValues;	// oid_contextid => value
		var $_aOptionToInfo;	// context_name => array('oid' => ..., 'default' => ...)
		var $plugin_options;	// see getOption()
		var $plugid;			// plugin id


		/**
		 * Class constructor: Initializes some internal data
		 */		 		 		
		function NucleusPlugin() {
			$this->_aOptionValues = array();	// oid_contextid => value
			$this->_aOptionToInfo = array();	// context_name => array('oid' => ..., 'default' => ...)
			$this->plugin_options = 0;
		}

		/**
		 * Retrieves an array of the top (or bottom) of an option from a plugin.
		 * @author TeRanEX
		 * @param  string $context the context for the option: item, blog, member,...
		 * @param  string $name    the name of the option
		 * @param  int    $amount  how many rows must be returned
		 * @param  string $sort    desc or asc
		 * @return array           array with both values and contextid's
		 * @access private
		 */
		function _getOptionTop($context, $name, $amount = 10, $sort = 'desc') {
			if (($sort != 'desc') && ($sort != 'asc')) {
				$sort= 'desc';
			}

			$oid = $this->_getOID($context, $name);

			// retrieve the data and return
			$q = 'SELECT otype, oextra FROM '.sql_table('plugin_option_desc').' WHERE oid = '.$oid;
			$query = sql_query($q);

			$o = sql_fetch_array($query);

			if (($this->optionCanBeNumeric($o['otype'])) && ($o['oextra'] == 'number' )) {
				$orderby = 'CAST(ovalue AS SIGNED)';
			} else {
				$orderby = 'ovalue';
			}
			$q = 'SELECT ovalue value, ocontextid id FROM '.sql_table('plugin_option').' WHERE oid = '.$oid.' ORDER BY '.$orderby.' '.$sort.' LIMIT 0,'.intval($amount);
			$query = sql_query($q);

			// create the array
			$i = 0;
			$top = array();
			while($row = sql_fetch_array($query)) {
				$top[$i++] = $row;
			}

			// return the array (duh!)
			return $top;
		}

		/**
		 * Creates an option in the database table plugin_option_desc
		 *		 
		 * private
		 */		 		 		
		function _createOption($context, $name, $desc, $type, $defValue, $typeExtras = '') {
			// create in plugin_option_desc
			$query = 'INSERT INTO ' . sql_table('plugin_option_desc')
				   .' (opid, oname, ocontext, odesc, otype, odef, oextra)'
				   .' VALUES ('.intval($this->plugid)
							 .', \''.sql_real_escape_string($name).'\''
							 .', \''.sql_real_escape_string($context).'\''
							 .', \''.sql_real_escape_string($desc).'\''
							 .', \''.sql_real_escape_string($type).'\''
							 .', \''.sql_real_escape_string($defValue).'\''
							 .', \''.sql_real_escape_string($typeExtras).'\')';
			sql_query($query);
			$oid = sql_insert_id();

			$key = $context . '_' . $name;
			$this->_aOptionToInfo[$key] = array('oid' => $oid, 'default' => $defValue);
			return 1;
		}


		/**
		 * Deletes an option from the database tables
		 * plugin_option and plugin_option_desc 
		 *
		 * private		 
		 */		 		 		
		function _deleteOption($context, $name) {
			$oid = $this->_getOID($context, $name);
			if (!$oid) return 0; // no such option

			// delete all things from plugin_option
			sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);

			// delete entry from plugin_option_desc
			sql_query('DELETE FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . $oid);

			// clear from cache
			unset($this->_aOptionToInfo[$context . '_' . $name]);
			$this->_aOptionValues = array();
			return 1;
		}

		/**
		 * Update an option in the database table plugin_option
		 * 		 
		 * returns: 1 on success, 0 on failure
		 * private
		 */
		function _setOption($context, $contextid, $name, $value) {
			global $manager;

			$oid = $this->_getOID($context, $name);
			if (!$oid) return 0;

			// check if context id exists
			switch ($context) {
				case 'member':
					if (!MEMBER::existsID($contextid)) return 0;
					break;
				case 'blog':
					if (!$manager->existsBlogID($contextid)) return 0;
					break;
				case 'category':
					if (!$manager->existsCategory($contextid)) return 0;
					break;
				case 'item':
					if (!$manager->existsItem($contextid, true, true)) return 0;
					break;
				case 'global':
					if ($contextid != 0) return 0;
					break;
			}


			// update plugin_option
			sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid) . ' and ocontextid='. intval($contextid));
			sql_query('INSERT INTO ' . sql_table('plugin_option') . ' (ovalue, oid, ocontextid) VALUES (\''.sql_real_escape_string($value).'\', '. intval($oid) . ', ' . intval($contextid) . ')');

			// update cache
			$this->_aOptionValues[$oid . '_' . $contextid] = $value;

			return 1;
		}

		/**
		 * Get an option from Cache or database
		 * 	 - if not in the option Cache read it from the database
		 *   - if not in the database write default values into the database
		 *   		  
		 * private		 
		 */		 		 		
		function _getOption($context, $contextid, $name) {
			$oid = $this->_getOID($context, $name);
			if (!$oid) return '';


			$key = $oid . '_' . $contextid;

			if (isset($this->_aOptionValues[$key]))
				return $this->_aOptionValues[$key];

			// get from DB
			$res = sql_query('SELECT ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid).' and ocontextid=' . intval($contextid));

			if (!$res || (sql_num_rows($res) == 0)) {
				$defVal = $this->_getDefVal($context, $name);
				$this->_aOptionValues[$key] = $defVal;

				// fill DB with default value
				$query = 'INSERT INTO ' . sql_table('plugin_option') . ' (oid,ocontextid,ovalue)'
					   .' VALUES ('.intval($oid).', '.intval($contextid).', \''.sql_real_escape_string($defVal).'\')';
				sql_query($query);
			}
			else {
				$o = sql_fetch_object($res);
				$this->_aOptionValues[$key] = $o->ovalue;
			}

			return $this->_aOptionValues[$key];
		}

		/**
		 * Returns assoc array with all values for a given option 
		 * (one option per possible context id)
		 * 
		 * private		 		 
		 */
		function _getAllOptions($context, $name) {
			$oid = $this->_getOID($context, $name);
			if (!$oid) return array();
			$defVal = $this->_getDefVal($context, $name);

			$aOptions = array();
			switch ($context) {
				case 'blog':
					$r = sql_query('SELECT bnumber as contextid FROM ' . sql_table('blog'));
					break;
				case 'category':
					$r = sql_query('SELECT catid as contextid FROM ' . sql_table('category'));
					break;
				case 'member':
					$r = sql_query('SELECT mnumber as contextid FROM ' . sql_table('member'));
					break;
				case 'item':
					$r = sql_query('SELECT inumber as contextid FROM ' . sql_table('item'));
					break;
			}
			if ($r) {
				while ($o = sql_fetch_object($r))
					$aOptions[$o->contextid] = $defVal;
			}

			$res = sql_query('SELECT ocontextid, ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);
			while ($o = sql_fetch_object($res))
				$aOptions[$o->ocontextid] = $o->ovalue;

			return $aOptions;
		}

		/**
		 * Gets the 'option identifier' that corresponds to a given option name.
		 * When this method is called for the first time, all the OIDs for the plugin
		 * are loaded into memory, to avoid re-doing the same query all over.
		 */
		function _getOID($context, $name) {
			$key = $context . '_' . $name;
			$info = $this->_aOptionToInfo[$key];
			if (is_array($info)) return $info['oid'];

			// load all OIDs for this plugin from the database
			$this->_aOptionToInfo = array();
			$query = 'SELECT oid, oname, ocontext, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE opid=' . intval($this->plugid);
			$res = sql_query($query);
			while ($o = sql_fetch_object($res)) {
				$k = $o->ocontext . '_' . $o->oname;
				$this->_aOptionToInfo[$k] = array('oid' => $o->oid, 'default' => $o->odef);
			}
			sql_free_result($res);

			return $this->_aOptionToInfo[$key]['oid'];
		}
		function _getDefVal($context, $name) {
			$key = $context . '_' . $name;
			$info = $this->_aOptionToInfo[$key];
			if (is_array($info)) return $info['default'];
		}


		/**
		 * Deletes all option values for a given context and contextid
		 * (used when e.g. a blog, member or category is deleted)
		 *
		 * (static method)
		 */
		function _deleteOptionValues($context, $contextid) {
			// delete all associated plugin options
			$aOIDs = array();
				// find ids
			$query = 'SELECT oid FROM '.sql_table('plugin_option_desc') . ' WHERE ocontext=\''.sql_real_escape_string($context).'\'';
			$res = sql_query($query);
			while ($o = sql_fetch_object($res))
				array_push($aOIDs, $o->oid);
			sql_free_result($res);
				// delete those options. go go go
			if (count($aOIDs) > 0) {
				$query = 'DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid in ('.implode(',',$aOIDs).') and ocontextid=' . intval($contextid);
				sql_query($query);
			}
		}

		/**
		 * splits the option's typeextra field (at ;'s) to split the meta collection
		 * @param string $typeExtra the value of the typeExtra field of an option
		 * @return array array of the meta-key/value-pairs
		 * @author TeRanEX
		 * @static
		 */
		function getOptionMeta($typeExtra) {
			$tmpMeta = explode(';', $typeExtra);
			$meta = array();
			for ($i = 0; $i < count($tmpMeta); $i++) {
				if (($i == 0) && (!strstr($tmpMeta[0], '='))) {
					// we have the select-list
					$meta['select'] = $tmpMeta[0];
				} else {
					$tmp = explode('=', $tmpMeta[$i]);
					$meta[$tmp[0]] = $tmp[1];
				}
			}
			return $meta;
		}

		/**
		 * filters the selectlists out of the meta collection
		 * @param string $typeExtra the value of the typeExtra field of an option
		 * @return string the selectlist
		 * @author TeRanEX
		 */
		function getOptionSelectValues($typeExtra) {
			$meta = NucleusPlugin::getOptionMeta($typeExtra);
			//the select list must always be the first part
			return $meta['select'];
		}

		/**
		 * checks if the eventlist in the database is up-to-date
		 * @return bool if it is up-to-date it return true, else false
		 * @author TeRanEX
		 */
		function subscribtionListIsUptodate() {
			$res = sql_query('SELECT event FROM '.sql_table('plugin_event').' WHERE pid = '.$this->getID());
			$ev = array();
			while($a = sql_fetch_array($res)) {
				array_push($ev, $a['event']);
			}
			if (count($ev) != count($this->getEventList())) {
				return false;
			}
			$d = array_diff($ev, $this->getEventList());
			if (count($d) > 0) {
				// there are differences so the db is not up-to-date
				return false;
			}
			return true;
		}

		/**
		 * @param $aOptions: array ( 'oid' => array( 'contextid' => 'value'))
		 *        (taken from request using requestVar())
		 * @param $newContextid: integer (accepts a contextid when it is for a new
		 *        contextid there was no id available at the moment of writing the
		 *        formcontrols into the page (by ex: itemOptions for new item)
		 * @static
		 */
		function _applyPluginOptions(&$aOptions, $newContextid = 0) {
			global $manager;
			if (!is_array($aOptions)) return;

			foreach ($aOptions as $oid => $values) {

				// get option type info
				$query = 'SELECT opid, oname, ocontext, otype, oextra, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . intval($oid);
				$res = sql_query($query);
				if ($o = sql_fetch_object($res))
				{
					foreach ($values as $key => $value) {
						// avoid overriding the key used by foreach statement
						$contextid=$key;

						// retreive any metadata
						$meta = NucleusPlugin::getOptionMeta($o->oextra);

						// if the option is readonly or hidden it may not be saved
						if (($meta['access'] != 'readonly') && ($meta['access'] != 'hidden')) {

							$value = undoMagic($value);	// value comes from request

							switch($o->otype) {
								case 'yesno':
									if (($value != 'yes') && ($value != 'no')) $value = 'no';
									break;
								default:
									break;
							}

							// check the validity of numerical options
							if (($meta['datatype'] == 'numerical') && (!is_numeric($value))) {
								//the option must be numeric, but the it isn't
								//use the default for this option
								$value = $o->odef;
							}

							// decide wether we are using the contextid of newContextid
							if ($newContextid != 0) {
								$contextid = $newContextid;
							}

							//trigger event PrePluginOptionsUpdate to give the plugin the
							//possibility to change/validate the new value for the option
							$manager->notify('PrePluginOptionsUpdate',array('context' => $o->ocontext, 'plugid' => $o->opid, 'optionname' => $o->oname, 'contextid' => $contextid, 'value' => &$value));

							// delete the old value for the option
							sql_query('DELETE FROM '.sql_table('plugin_option').' WHERE oid='.intval($oid).' AND ocontextid='.intval($contextid));
							sql_query('INSERT INTO '.sql_table('plugin_option')." (oid, ocontextid, ovalue) VALUES (".intval($oid).",".intval($contextid).",'" . sql_real_escape_string($value) . "')");
						}
					}
				}
				// clear option value cache if the plugin object is already loaded
				if (is_object($o)) {
					$plugin=& $manager->pidLoaded($o->opid);
					if ($plugin) $plugin->clearOptionValueCache();
				}
			}
		}
	}
?>
Return current item: Nucleus CMS Weblog