utf8/nucleus/libs/PLUGIN.php

   1 <?php   /**
   2           * Nucleus: PHP/MySQL Weblog CMS (http://nucleuscms.org/)
   3           * Copyright (C) 2002-2004 The Nucleus Group
   4           *
   5           * This program is free software; you can redistribute it and/or
   6           * modify it under the terms of the GNU General Public License
   7           * as published by the Free Software Foundation; either version 2
   8           * of the License, or (at your option) any later version.
   9           * (see nucleus/documentation/index.html#license for more info)
  10           *
  11           * This is an (abstract) class of which all Nucleus Plugins must inherit
  12           *
  13           * for more information on plugins and how to write your own, see the
  14           * plugins.html file that is included with the Nucleus documenation
  15           *
  16           * $Id: PLUGIN.php,v 1.1.1.1 2005-02-28 07:14:52 kimitake Exp $
  17           */
  18         class NucleusPlugin {
  19
  20                 // these functions _have_ to be redefined in your plugin
  21
  22                 function getName() { return 'Undefined'; }
  23                 function getAuthor()  { return 'Undefined'; }
  24                 function getURL()  { return 'Undefined'; }
  25                 function getVersion() { return '0.0'; }
  26                 function getDescription() { return 'Undefined';}
  27
  28                 // these function _may_ be redefined in your plugin
  29
  30                 function getMinNucleusVersion() { return 150; }
  31                 function getMinNucleusPatchLevel() { return 0; }
  32                 function getEventList() { return array(); }
  33                 function getTableList() { return array(); }
  34                 function hasAdminArea() { return 0; }
  35
  36                 function install() {}
  37                 function unInstall() {}
  38
  39                 function init() {}
  40
  41                 function doSkinVar($skinType) {}
  42                 function doTemplateVar(&$item) {
  43                         $args = func_get_args();
  44                         array_shift($args);
  45                         array_unshift($args, 'template');
  46                         call_user_func_array(array(&$this,'doSkinVar'),$args);
  47                 }
  48                 function doTemplateCommentsVar(&$item, &$comment) {
  49                         $args = func_get_args();
  50                         array_shift($args);
  51                         array_shift($args);
  52                         array_unshift($args, 'template');
  53                         call_user_func_array(array(&$this,'doSkinVar'),$args);
  54                 }
  55                 function doAction($type) { return 'No Such Action'; }
  56
  57                 /**
  58                  * Checks if a plugin supports a certain feature.
  59                  *
  60                  * @returns 1 if the feature is reported, 0 if not
  61                  * @param $feature
  62                  *              Name of the feature. See plugin documentation for more info
  63                  *                      'SqlTablePrefix' -> if the plugin uses the sql_table() method to get table names
  64                  *                      'HelpPage' -> if the plugin provides a helppage
  65                  */
  66                 function supportsFeature($feature) {
  67                         return 0;
  68                 }
  69
  70                 /**
  71                  * Report a list of plugin that is required to function
  72                  *
  73                  * @returns an array of names of plugin, an empty array indicates no dependency
  74                  */
  75                 function getPluginDep() { return array(); }
  76
  77                 // these helper functions should not be redefined in your plugin
  78
  79                 /**
  80                   * Creates a new option for this plugin
  81                   *
  82                   * @param name
  83                   *             A string uniquely identifying your option. (max. length is 20 characters)
  84                   * @param description
  85                   *             A description that will show up in the nucleus admin area (max. length: 255 characters)
  86                   * @param type
  87                   *             Either 'text', 'yesno' or 'password'
  88                   *             This info is used when showing 'edit plugin options' screens
  89                   * @param value
  90                   *             Initial value for the option (max. value length is 128 characters)
  91                   */
  92                 function createOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
  93                         return $this->_createOption('global', $name, $desc, $type, $defValue, $typeExtras);
  94                 }
  95                 function createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
  96                         return $this->_createOption('blog', $name, $desc, $type, $defValue, $typeExtras);
  97                 }
  98                 function createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
  99                         return $this->_createOption('member', $name, $desc, $type, $defValue, $typeExtras);
 100                 }
 101                 function createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
 102                         return $this->_createOption('category', $name, $desc, $type, $defValue, $typeExtras);
 103                 }
 104         function createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
 105                         return $this->_createOption('item', $name, $desc, $type, $defValue, $typeExtras);
 106                 }
 107
 108                 /**
 109                   * Removes the option from the database
 110                   *
 111                   * Note: Options get erased automatically on plugin uninstall
 112                   */
 113                 function deleteOption($name) {
 114                         return $this->_deleteOption('global', $name);
 115                 }
 116                 function deleteBlogOption($name) {
 117                         return $this->_deleteOption('blog', $name);
 118                 }
 119                 function deleteMemberOption($name) {
 120                         return $this->_deleteOption('member', $name);
 121                 }
 122                 function deleteCategoryOption($name) {
 123                         return $this->_deleteOption('category', $name);
 124                 }
 125         function deleteItemOption($name) {
 126                         return $this->_deleteOption('item', $name);
 127                 }
 128
 129                 /**
 130                   * Sets the value of an option to something new
 131                   */
 132                 function setOption($name, $value) {
 133                         return $this->_setOption('global', 0, $name, $value);
 134                 }
 135                 function setBlogOption($blogid, $name, $value) {
 136                         return $this->_setOption('blog', $blogid, $name, $value);
 137                 }
 138                 function setMemberOption($memberid, $name, $value) {
 139                         return $this->_setOption('member', $memberid, $name, $value);
 140                 }
 141                 function setCategoryOption($catid, $name, $value) {
 142                         return $this->_setOption('category', $catid, $name, $value);
 143                 }
 144         function setItemOption($itemid, $name, $value) {
 145                         return $this->_setOption('item', $itemid, $name, $value);
 146                 }
 147
 148                 /**
 149                   * Retrieves the current value for an option
 150                   */
 151                 function getOption($name)
 152                 {
 153                         // only request the options the very first time. On subsequent requests
 154                         // the static collection is used to save SQL queries.
 155                         if ($this->plugin_options == 0)
 156                         {
 157                                 $this->plugin_options = array();
 158                                 $query = mysql_query(
 159                                          'SELECT d.oname as name, o.ovalue as value '.
 160                                          'FROM '.
 161                                          sql_table('plugin_option').' o, '.
 162                                          sql_table('plugin_option_desc').' d '.
 163                                          'WHERE d.opid='. intval($this->getID()).' AND d.oid=o.oid'
 164                                 );
 165                                 while ($row = mysql_fetch_object($query))
 166                                         $this->plugin_options[strtolower($row->name)] = $row->value;
 167                   }
 168                   if (isset($this->plugin_options[strtolower($name)]))
 169                                 return $this->plugin_options[strtolower($name)];
 170                   else
 171                                 return $this->_getOption('global', 0, $name);
 172                 }
 173
 174                 function getBlogOption($blogid, $name) {
 175                         return $this->_getOption('blog', $blogid, $name);
 176                 }
 177                 function getMemberOption($memberid, $name) {
 178                         return $this->_getOption('member', $memberid, $name);
 179                 }
 180                 function getCategoryOption($catid, $name) {
 181                         return $this->_getOption('category', $catid, $name);
 182                 }
 183         function getItemOption($itemid, $name) {
 184                         return $this->_getOption('item', $itemid, $name);
 185                 }
 186
 187                 /**
 188                  * Retrieves an associative array with the option value for each
 189                  * context id
 190                  */
 191                 function getAllBlogOptions($name) {
 192                         return $this->_getAllOptions('blog', $name);
 193                 }
 194                 function getAllMemberOptions($name) {
 195                         return $this->_getAllOptions('member', $name);
 196                 }
 197                 function getAllCategoryOptions($name) {
 198                         return $this->_getAllOptions('category', $name);
 199                 }
 200         function getAllItemOptions($name) {
 201                         return $this->_getAllOptions('item', $name);
 202                 }
 203
 204                 /**
 205          * Retrieves an indexed array with the top (or bottom) of an option
 206                  * (delegates to _getOptionTop())
 207          */
 208                 function getBlogOptionTop($name, $amount = 10, $sort = 'desc') {
 209                         return $this->_getOptionTop('blog', $name, $amount, $sort);
 210                 }
 211                 function getMemberOptionTop($name, $amount = 10, $sort = 'desc') {
 212                         return $this->_getOptionTop('member', $name, $amount, $sort);
 213                 }
 214                 function getCategoryOptionTop($name, $amount = 10, $sort = 'desc') {
 215                         return $this->_getOptionTop('category', $name, $amount, $sort);
 216                 }
 217                 function getItemOptionTop($name, $amount = 10, $sort = 'desc') {
 218                         return $this->_getOptionTop('item', $name, $amount, $sort);
 219                 }
 220
 221                 /**
 222                  * Retrieves an array of the top (or bottom) of an option from a plugin.
 223                  * @author TeRanEX
 224                  * @param  string $context the context for the option: item, blog, member,...
 225                  * @param  string $name    the name of the option
 226                  * @param  int    $amount  how many rows must be returned
 227                  * @param  string $sort    desc or asc
 228                  * @return array           array with both values and contextid's
 229                  * @access private
 230                  */
 231         function _getOptionTop($context, $name, $amount = 10, $sort = 'desc') {
 232                         if (($sort != 'desc') && ($sort != 'asc')) {
 233                                 $sort= 'desc';
 234                         }
 235
 236                         $oid = $this->_getOID($context, $name);
 237
 238                         // retrieve the data and return
 239                         $q = 'SELECT otype, oextra FROM '.sql_table('plugin_option_desc').' WHERE oid = '.$oid;
 240                         $query = mysql_query($q);
 241
 242                         $o = mysql_fetch_array($query);
 243
 244                         if (($this->optionCanBeNumeric($o['otype'])) && ($o['oextra'] == 'number' )) {
 245                                 $orderby = 'CAST(ovalue AS SIGNED)';
 246                         } else {
 247                                 $orderby = 'ovalue';
 248                         }
 249                         $q = 'SELECT ovalue value, ocontextid id FROM '.sql_table('plugin_option').' WHERE oid = '.$oid.' ORDER BY '.$orderby.' '.$sort.' LIMIT 0,'.$amount;
 250                         $query = mysql_query($q);
 251
 252                         // create the array
 253                         $i = 0;
 254                         $top = array();
 255                         while($row = mysql_fetch_array($query)) {
 256                                 $top[$i++] = $row;
 257                         }
 258
 259                         // return the array (duh!)
 260                         return $top;
 261                 }
 262
 263                 /**
 264                   * Returns the plugin ID
 265                   */
 266                 function getID() {
 267                         return $this->plugid;
 268                 }
 269
 270                 /**
 271                   * returns the URL of the admin area for this plugin (in case there's
 272                   * no such area, the returned information is invalid)
 273                   */
 274                 function getAdminURL() {
 275                         global $CONF;
 276                         return $CONF['PluginURL'] . $this->getShortName() . '/';
 277                 }
 278
 279                 /**
 280                   * Returns the directory where the admin directory is located and
 281                   * where the plugin can maintain his extra files
 282                   */
 283                 function getDirectory() {
 284                         global $DIR_PLUGINS;
 285                         return $DIR_PLUGINS . $this->getShortName() . '/';
 286                 }
 287
 288                 /**
 289                   * Derives the short name for the plugin from the classname (all lowercase)
 290                   */
 291                 function getShortName() {
 292                         return str_replace('np_','',strtolower(get_class($this)));
 293                 }
 294
 295                 var $_aOptionValues;    // oid_contextid => value
 296                 var $_aOptionToInfo;    // context_name => array('oid' => ..., 'default' => ...)
 297                 var $plugin_options;    // see getOption()
 298                 var $plugid;                    // plugin id
 299
 300
 301                 // constructor. Initializes some internal data
 302                 function NucleusPlugin() {
 303                         $this->_aOptionValues = array();        // oid_contextid => value
 304                         $this->_aOptionToInfo = array();        // context_name => array('oid' => ..., 'default' => ...)
 305                         $this->plugin_options = 0;
 306                 }
 307
 308                 // private
 309                 function _createOption($context, $name, $desc, $type, $defValue, $typeExtras = '') {
 310                         // create in plugin_option_desc
 311                         $query = 'INSERT INTO ' . sql_table('plugin_option_desc')
 312                                .' (opid, oname, ocontext, odesc, otype, odef, oextra)'
 313                                .' VALUES ('.intval($this->plugid)
 314                              .', \''.addslashes($name).'\''
 315                              .', \''.addslashes($context).'\''
 316                              .', \''.addslashes($desc).'\''
 317                              .', \''.addslashes($type).'\''
 318                              .', \''.addslashes($defValue).'\''
 319                                          .', \''.addslashes($typeExtras).'\')';
 320                         sql_query($query);
 321                         $oid = mysql_insert_id();
 322
 323                         $key = $context . '_' . $name;
 324                         $this->_aOptionToInfo[$key] = array('oid' => $oid, 'default' => $defValue);
 325                         return 1;
 326                 }
 327
 328
 329                 // private
 330                 function _deleteOption($context, $name) {
 331                         $oid = $this->_getOID($context, $name);
 332                         if (!$oid) return 0; // no such option
 333
 334                         // delete all things from plugin_option
 335                         sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);
 336
 337                         // delete entry from plugin_option_desc
 338                         sql_query('DELETE FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . $oid);
 339
 340                         // clear from cache
 341                         unset($this->_aOptionToInfo[$context . '_' . $name]);
 342                         $this->_aOptionValues = array();
 343                         return 1;
 344                 }
 345
 346                 /**
 347                  * private
 348                  * returns: 1 on success, 0 on failure
 349                  */
 350                 function _setOption($context, $contextid, $name, $value) {
 351                         global $manager;
 352
 353                         $oid = $this->_getOID($context, $name);
 354                         if (!$oid) return 0;
 355
 356                         // check if context id exists
 357                         switch ($context) {
 358                                 case 'member':
 359                                         if (!MEMBER::existsID($contextid)) return 0;
 360                                         break;
 361                                 case 'blog':
 362                                         if (!$manager->existsBlogID($contextid)) return 0;
 363                                         break;
 364                                 case 'category':
 365                                         if (!$manager->existsCategory($contextid)) return 0;
 366                                         break;
 367                 case 'item':
 368                     if (!$manager->existsItem($contextid, true, true)) return 0;
 369                                         break;
 370                                 case 'global':
 371                                         if ($contextid != 0) return 0;
 372                                         break;
 373                         }
 374
 375
 376                         // update plugin_option
 377                         sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid) . ' and ocontextid='. intval($contextid));
 378                         sql_query('INSERT INTO ' . sql_table('plugin_option') . ' (ovalue, oid, ocontextid) VALUES (\''.addslashes($value).'\', '. intval($oid) . ', ' . intval($contextid) . ')');
 379
 380                         // update cache
 381                         $this->_aOptionValues[$oid . '_' . $contextid] = $value;
 382
 383                         return 1;
 384                 }
 385
 386                 // private
 387                 function _getOption($context, $contextid, $name) {
 388                         $oid = $this->_getOID($context, $name);
 389                         if (!$oid) return '';
 390
 391
 392                         $key = $oid . '_' . $contextid;
 393
 394                         if (isset($this->_aOptionValues[$key]))
 395                                 return $this->_aOptionValues[$key];
 396
 397                         // get from DB
 398                         $res = sql_query('SELECT ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid).' and ocontextid=' . intval($contextid));
 399
 400                         if (!$res || (mysql_num_rows($res) == 0)) {
 401                                 $defVal = $this->_getDefVal($context, $name);
 402                                 $this->_aOptionValues[$key] = $defVal;
 403
 404                                 // fill DB with default value
 405                                 $query = 'INSERT INTO ' . sql_table('plugin_option') . ' (oid,ocontextid,ovalue)'
 406                                        .' VALUES ('.intval($oid).', '.intval($contextid).', \''.addslashes($defVal).'\')';
 407                                 sql_query($query);
 408                         }
 409                         else {
 410                                 $o = mysql_fetch_object($res);
 411                                 $this->_aOptionValues[$key] = $o->ovalue;
 412                         }
 413
 414                         return $this->_aOptionValues[$key];
 415                 }
 416
 417                 /**
 418                  * Returns assoc array with all values for a given option (one option per
 419                  * possible context id)
 420                  */
 421                 function _getAllOptions($context, $name) {
 422                         $oid = $this->_getOID($context, $name);
 423                         if (!$oid) return array();
 424                         $defVal = $this->_getDefVal($context, $name);
 425
 426                         $aOptions = array();
 427                         switch ($context) {
 428                                 case 'blog':
 429                                         $r = sql_query('SELECT bnumber as contextid FROM ' . sql_table('blog'));
 430                                         break;
 431                                 case 'category':
 432                                         $r = sql_query('SELECT catid as contextid FROM ' . sql_table('category'));
 433                                         break;
 434                                 case 'member':
 435                                         $r = sql_query('SELECT mnumber as contextid FROM ' . sql_table('member'));
 436                                         break;
 437                         }
 438                         if ($r) {
 439                                 while ($o = mysql_fetch_object($r))
 440                                         $aOptions[$o->contextid] = $defVal;
 441                         }
 442
 443                         $res = sql_query('SELECT ocontextid, ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);
 444                         while ($o = mysql_fetch_object($res))
 445                                 $aOptions[$o->ocontextid] = $o->ovalue;
 446
 447                         return $aOptions;
 448                 }
 449
 450                 /**
 451                  * Gets the 'option identifier' that corresponds to a given option name.
 452                  * When this method is called for the first time, all the OIDs for the plugin
 453                  * are loaded into memory, to avoid re-doing the same query all over.
 454                  */
 455                 function _getOID($context, $name) {
 456                         $key = $context . '_' . $name;
 457                         $info = $this->_aOptionToInfo[$key];
 458                         if (is_array($info)) return $info['oid'];
 459
 460                         // load all OIDs for this plugin from the database
 461                         $this->_aOptionToInfo = array();
 462                         $query = 'SELECT oid, oname, ocontext, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE opid=' . intval($this->plugid);
 463                         $res = sql_query($query);
 464                         while ($o = mysql_fetch_object($res)) {
 465                                 $k = $o->ocontext . '_' . $o->oname;
 466                                 $this->_aOptionToInfo[$k] = array('oid' => $o->oid, 'default' => $o->odef);
 467                         }
 468                         mysql_free_result($res);
 469
 470                         return $this->_aOptionToInfo[$key]['oid'];
 471                 }
 472                 function _getDefVal($context, $name) {
 473                         $key = $context . '_' . $name;
 474                         $info = $this->_aOptionToInfo[$key];
 475                         if (is_array($info)) return $info['default'];
 476                 }
 477
 478
 479                 /**
 480                  * Deletes all option values for a given context and contextid
 481                  * (used when e.g. a blog, member or category is deleted)
 482                  *
 483                  * (static method)
 484                  */
 485                 function _deleteOptionValues($context, $contextid) {
 486                         // delete all associated plugin options
 487                         $aOIDs = array();
 488                                 // find ids
 489                         $query = 'SELECT oid FROM '.sql_table('plugin_option_desc') . ' WHERE ocontext=\''.addslashes($context).'\'';
 490                         $res = sql_query($query);
 491                         while ($o = mysql_fetch_object($res))
 492                                 array_push($aOIDs, $o->oid);
 493                         mysql_free_result($res);
 494                                 // delete those options. go go go
 495                         if (count($aOIDs) > 0) {
 496                                 $query = 'DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid in ('.implode(',',$aOIDs).') and ocontextid=' . intval($contextid);
 497                                 sql_query($query);
 498                         }
 499                 }
 500
 501                 /**
 502                  * splits the option's typeextra field (at ;'s) to split the meta collection
 503                  * @param string $typeExtra the value of the typeExtra field of an option
 504                  * @return array array of the meta-key/value-pairs
 505                  * @author TeRanEX
 506                  * @static
 507                  */
 508                 function getOptionMeta($typeExtra) {
 509                         $tmpMeta = explode(';', $typeExtra);
 510                         $meta = array();
 511                         for ($i = 0; $i < count($tmpMeta); $i++) {
 512                                 if (($i == 0) && (!strstr($tmpMeta[0], '='))) {
 513                                         // we have the select-list
 514                                         $meta['select'] = $tmpMeta[0];
 515                                 } else {
 516                                         $tmp = explode('=', $tmpMeta[$i]);
 517                                         $meta[$tmp[0]] = $tmp[1];
 518                                 }
 519                         }
 520                         return $meta;
 521                 }
 522
 523                 /**
 524                  * filters the selectlists out of the meta collection
 525                  * @param string $typeExtra the value of the typeExtra field of an option
 526                  * @return string the selectlist
 527                  * @author TeRanEX
 528                  */
 529                 function getOptionSelectValues($typeExtra) {
 530                         $meta = NucleusPlugin::getOptionMeta($typeExtra);
 531                         //the select list must always be the first part
 532                         return $meta['select'];
 533                 }
 534
 535                 /**
 536                  * @param $aOptions: array ( 'oid' => array( 'contextid' => 'value'))
 537                  *        (taken from request using requestVar())
 538                  * @param $newContextid: integer (accepts a contextid when it is for a new
 539                  *        contextid there was no id available at the moment of writing the
 540                  *        formcontrols into the page (by ex: itemOptions for new item)
 541                  * @static
 542                  */
 543                 function _applyPluginOptions(&$aOptions, $newContextid = 0) {
 544                         global $manager;
 545                         if (!is_array($aOptions)) return;
 546
 547                         foreach ($aOptions as $oid => $values) {
 548
 549                                 // get option type info
 550                                 $query = 'SELECT opid, oname, ocontext, otype, oextra, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . intval($oid);
 551                                 $res = sql_query($query);
 552                                 if ($o = mysql_fetch_object($res))
 553                                 {
 554                                         foreach ($values as $contextid => $value) {
 555                                                 // retreive any metadata
 556                                                 $meta = NucleusPlugin::getOptionMeta($o->oextra);
 557
 558                                                 // if the option is readonly or hidden it may not be saved
 559                                                 if (($meta['access'] != 'readonly') && ($meta['access'] != 'hidden')) {
 560
 561                                                         $value = undoMagic($value);     // value comes from request
 562
 563                                                         switch($o->otype) {
 564                                                                 case 'yesno':
 565                                                                         if (($value != 'yes') && ($value != 'no')) $value = 'no';
 566                                                                         break;
 567                                                                 default:
 568                                                                         break;
 569                                                         }
 570
 571                                                         // check the validity of numerical options
 572                                                         if (($meta['datatype'] == 'numerical') && (!is_numeric($value))) {
 573                                                                 //the option must be numeric, but the it isn't
 574                                                                 //use the default for this option
 575                                                                 $value = $o->odef;
 576                                                         }
 577
 578                                                         // decide wether we are using the contextid of newContextid
 579                                                         if ($newContextid != 0) {
 580                                                                 $contextid = $newContextid;
 581                                                         }
 582
 583                                                         //trigger event PrePluginOptionsUpdate to give the plugin the
 584                                                         //possibility to change/validate the new value for the option
 585                                                         $manager->notify('PrePluginOptionsUpdate',array('context' => $o->ocontext, 'plugid' => $o->opid, 'optionname' => $o->oname, 'contextid' => $contextid, 'value' => &$value));
 586
 587                                                         // delete the old value for the option
 588                                                         sql_query('DELETE FROM '.sql_table('plugin_option').' WHERE oid='.intval($oid).' AND ocontextid='.intval($contextid));
 589                                                         sql_query('INSERT INTO '.sql_table('plugin_option')." (oid, ocontextid, ovalue) VALUES (".intval($oid).",".intval($contextid).",'" . addslashes($value) . "')");
 590                                                 }
 591                                         }
 592                                 }
 593                         }
 594                 }
 595
 596         }
 597 ?>