plugins/Irc/extlib/phergie/Phergie/Plugin/Abstract.php

   1 <?php
   2 /**
   3  * Phergie
   4  *
   5  * PHP version 5
   6  *
   7  * LICENSE
   8  *
   9  * This source file is subject to the new BSD license that is bundled
  10  * with this package in the file LICENSE.
  11  * It is also available through the world-wide-web at this URL:
  12  * http://phergie.org/license
  13  *
  14  * @category  Phergie
  15  * @package   Phergie
  16  * @author    Phergie Development Team <team@phergie.org>
  17  * @copyright 2008-2010 Phergie Development Team (http://phergie.org)
  18  * @license   http://phergie.org/license New BSD License
  19  * @link      http://pear.phergie.org/package/Phergie
  20  */
  21
  22 /**
  23  * Base class for plugins to provide event handler stubs and commonly needed
  24  * functionality.
  25  *
  26  * @category Phergie
  27  * @package  Phergie
  28  * @author   Phergie Development Team <team@phergie.org>
  29  * @license  http://phergie.org/license New BSD License
  30  * @link     http://pear.phergie.org/package/Phergie
  31  */
  32 abstract class Phergie_Plugin_Abstract
  33 {
  34     /**
  35      * Current configuration handler
  36      *
  37      * @var Phergie_Config
  38      */
  39     protected $config;
  40
  41     /**
  42      * Plugin handler used to provide access to other plugins
  43      *
  44      * @var Phergie_Plugin_Handler
  45      */
  46     protected $plugins;
  47
  48     /**
  49      * Current event handler instance for outgoing events
  50      *
  51      * @var Phergie_Event_Handler
  52      */
  53     protected $events;
  54
  55     /**
  56      * Current connection instance
  57      *
  58      * @var Phergie_Connection
  59      */
  60     protected $connection;
  61
  62     /**
  63      * Current incoming event being handled
  64      *
  65      * @var Phergie_Event_Request|Phergie_Event_Response
  66      */
  67     protected $event;
  68
  69     /**
  70      * Returns the short name for the plugin based on its class name.
  71      *
  72      * @return string
  73      */
  74     public function getName()
  75     {
  76         return substr(strrchr(get_class($this), '_'), 1);
  77     }
  78
  79     /**
  80      * Indicates that the plugin failed to load due to an unsatisfied
  81      * runtime requirement, such as a missing dependency.
  82      *
  83      * @param string $message Error message to provide more information
  84      *        about the reason for the failure
  85      *
  86      * @return Phergie_Plugin_Abstract Provides a fluent interface
  87      * @throws Phergie_Plugin_Exception Always
  88      */
  89     protected function fail($message)
  90     {
  91         throw new Phergie_Plugin_Exception(
  92             $message,
  93             Phergie_Plugin_Exception::ERR_REQUIREMENT_UNSATISFIED
  94         );
  95     }
  96
  97     /**
  98      * Sets the current configuration handler.
  99      *
 100      * @param Phergie_Config $config Configuration handler
 101      *
 102      * @return Phergie_Plugin_Abstract Provides a fluent interface
 103      */
 104     public function setConfig(Phergie_Config $config)
 105     {
 106         $this->config = $config;
 107         return $this;
 108     }
 109
 110     /**
 111      * Returns the current configuration handler or the value of a single
 112      * setting from it.
 113      *
 114      * @param string $name    Optional name of a setting for which the value
 115      *        should be returned instead of the entire configuration handler
 116      * @param mixed  $default Optional default value to return if no value
 117      *        is set for the setting indicated by $name
 118      *
 119      * @return Phergie_Config|mixed Configuration handler or value of the
 120      *         setting specified by $name
 121      * @throws Phergie_Plugin_Exception No configuration handler has been set
 122      */
 123     public function getConfig($name = null, $default = null)
 124     {
 125         if (empty($this->config)) {
 126             throw new Phergie_Plugin_Exception(
 127                 'Configuration handler cannot be accessed before one is set',
 128                 Phergie_Plugin_Exception::ERR_NO_CONFIG_HANDLER
 129             );
 130         }
 131         if (!is_null($name)) {
 132             if (!isset($this->config[$name])) {
 133                 return $default;
 134             }
 135             return $this->config[$name];
 136         }
 137         return $this->config;
 138     }
 139
 140     /**
 141      * Sets the current plugin handler.
 142      *
 143      * @param Phergie_Plugin_Handler $handler Plugin handler
 144      *
 145      * @return Phergie_Plugin_Abstract Provides a fluent interface
 146      */
 147     public function setPluginHandler(Phergie_Plugin_Handler $handler)
 148     {
 149         $this->plugins = $handler;
 150         return $this;
 151     }
 152
 153     /**
 154      * Returns the current plugin handler.
 155      *
 156      * @return Phergie_Plugin_Handler
 157      * @throws Phergie_Plugin_Exception No plugin handler has been set
 158      */
 159     public function getPluginHandler()
 160     {
 161         if (empty($this->plugins)) {
 162             throw new Phergie_Plugin_Exception(
 163                 'Plugin handler cannot be accessed before one is set',
 164                 Phergie_Plugin_Exception::ERR_NO_PLUGIN_HANDLER
 165             );
 166         }
 167         return $this->plugins;
 168     }
 169
 170     /**
 171      * Sets the current event handler.
 172      *
 173      * @param Phergie_Event_Handler $handler Event handler
 174      *
 175      * @return Phergie_Plugin_Abstract Provides a fluent interface
 176      */
 177     public function setEventHandler(Phergie_Event_Handler $handler)
 178     {
 179         $this->events = $handler;
 180         return $this;
 181     }
 182
 183     /**
 184      * Returns the current event handler.
 185      *
 186      * @return Phergie_Event_Handler
 187      * @throws Phergie_Plugin_Exception No event handler has been set
 188      */
 189     public function getEventHandler()
 190     {
 191         if (empty($this->events)) {
 192             throw new Phergie_Plugin_Exception(
 193                 'Event handler cannot be accessed before one is set',
 194                 Phergie_Plugin_Exception::ERR_NO_EVENT_HANDLER
 195             );
 196         }
 197         return $this->events;
 198     }
 199
 200     /**
 201      * Sets the current connection.
 202      *
 203      * @param Phergie_Connection $connection Connection
 204      *
 205      * @return Phergie_Plugin_Abstract Provides a fluent interface
 206      */
 207     public function setConnection(Phergie_Connection $connection)
 208     {
 209         $this->connection = $connection;
 210         return $this;
 211     }
 212
 213     /**
 214      * Returns the current event connection.
 215      *
 216      * @return Phergie_Connection
 217      * @throws Phergie_Plugin_Exception No connection has been set
 218      */
 219     public function getConnection()
 220     {
 221         if (empty($this->connection)) {
 222             throw new Phergie_Plugin_Exception(
 223                 'Connection cannot be accessed before one is set',
 224                 Phergie_Plugin_Exception::ERR_NO_CONNECTION
 225             );
 226         }
 227         return $this->connection;
 228     }
 229
 230     /**
 231      * Sets the current incoming event to be handled.
 232      *
 233      * @param Phergie_Event_Request|Phergie_Event_Response $event Event
 234      *
 235      * @return Phergie_Plugin_Abstract Provides a fluent interface
 236      */
 237     public function setEvent($event)
 238     {
 239         $this->event = $event;
 240         return $this;
 241     }
 242
 243     /**
 244      * Returns the current incoming event to be handled.
 245      *
 246      * @return Phergie_Event_Request|Phergie_Event_Response
 247      */
 248     public function getEvent()
 249     {
 250         if (empty($this->connection)) {
 251             throw new Phergie_Plugin_Exception(
 252                 'Event cannot be accessed before one is set',
 253                 Phergie_Plugin_Exception::ERR_NO_EVENT
 254             );
 255         }
 256         return $this->event;
 257     }
 258
 259     /**
 260      * Provides do* methods with signatures identical to those of
 261      * Phergie_Driver_Abstract but that queue up events to be dispatched
 262      * later.
 263      *
 264      * @param string $name Name of the method called
 265      * @param array  $args Arguments passed in the call
 266      *
 267      * @return mixed
 268      */
 269     public function __call($name, array $args)
 270     {
 271         $subcmd = substr($name, 0, 2);
 272         if ($subcmd == 'do') {
 273             $type = strtolower(substr($name, 2));
 274             $this->getEventHandler()->addEvent($this, $type, $args);
 275         } else if ($subcmd != 'on') {
 276             throw new Phergie_Plugin_Exception(
 277                 'Called invalid method ' . $name . ' in ' . get_class($this),
 278                 Phergie_Plugin_Exception::ERR_INVALID_CALL
 279             );
 280         }
 281     }
 282
 283     /**
 284      * Handler for when the plugin is initially loaded - useful for checking
 285      * runtime dependencies or performing any setup necessary for the plugin
 286      * to function properly such as initializing a database.
 287      *
 288      * @return void
 289      */
 290     public function onLoad()
 291     {
 292     }
 293
 294     /**
 295      * Handler for when the bot initially connects to a server.
 296      *
 297      * @return void
 298      */
 299     public function onConnect()
 300     {
 301     }
 302
 303     /**
 304      * Handler for each tick, a single iteration of the continuous loop
 305      * executed by the bot to receive, handle, and send events - useful for
 306      * repeated execution of tasks on a time interval.
 307      *
 308      * @return void
 309      */
 310     public function onTick()
 311     {
 312     }
 313
 314     /**
 315      * Handler for when any event is received but has not yet been dispatched
 316      * to the plugin handler method specific to its event type.
 317      *
 318      * @return bool|null|void FALSE to short-circuit further event
 319      *         processing, TRUE or NULL otherwise
 320      */
 321     public function preEvent()
 322     {
 323     }
 324
 325     /**
 326      * Handler for after plugin processing of an event has concluded but
 327      * before any events triggered in response by plugins are sent to the
 328      * server - useful for modifying outgoing events before they are sent.
 329      *
 330      * @return void
 331      */
 332     public function preDispatch()
 333     {
 334     }
 335
 336     /**
 337      * Handler for after any events triggered by plugins in response to a
 338      * received event are sent to the server.
 339      *
 340      * @return void
 341      */
 342     public function postDispatch()
 343     {
 344     }
 345
 346     /**
 347      * Handler for when the server prompts the client for a nick.
 348      *
 349      * @return void
 350      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_2
 351      */
 352     public function onNick()
 353     {
 354     }
 355
 356     /**
 357      * Handler for when a user obtains operator privileges.
 358      *
 359      * @return void
 360      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_5
 361      */
 362     public function onOper()
 363     {
 364     }
 365
 366     /**
 367      * Handler for when the client session is about to be terminated.
 368      *
 369      * @return void
 370      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_6
 371      */
 372     public function onQuit()
 373     {
 374     }
 375
 376     /**
 377      * Handler for when a user joins a channel.
 378      *
 379      * @return void
 380      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_1
 381      */
 382     public function onJoin()
 383     {
 384     }
 385
 386     /**
 387      * Handler for when a user leaves a channel.
 388      *
 389      * @return void
 390      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_2
 391      */
 392     public function onPart()
 393     {
 394     }
 395
 396     /**
 397      * Handler for when a user or channel mode is changed.
 398      *
 399      * @return void
 400      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_3
 401      */
 402     public function onMode()
 403     {
 404     }
 405
 406     /**
 407      * Handler for when a channel topic is viewed or changed.
 408      *
 409      * @return void
 410      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_4
 411      */
 412     public function onTopic()
 413     {
 414     }
 415
 416     /**
 417      * Handler for when a message is received from a channel or user.
 418      *
 419      * @return void
 420      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_4_1
 421      */
 422     public function onPrivmsg()
 423     {
 424     }
 425
 426     /**
 427      * Handler for when the bot receives a CTCP ACTION request.
 428      *
 429      * @return void
 430      * @link http://www.invlogic.com/irc/ctcp.html#4.4
 431      */
 432     public function onAction()
 433     {
 434     }
 435
 436     /**
 437      * Handler for when a notice is received.
 438      *
 439      * @return void
 440      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_4_2
 441      */
 442     public function onNotice()
 443     {
 444     }
 445
 446     /**
 447      * Handler for when a user is kicked from a channel.
 448      *
 449      * @return void
 450      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_8
 451      */
 452     public function onKick()
 453     {
 454     }
 455
 456     /**
 457      * Handler for when the bot receives a ping event from a server, at
 458      * which point it is expected to respond with a pong request within
 459      * a short period else the server may terminate its connection.
 460      *
 461      * @return void
 462      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_6_2
 463      */
 464     public function onPing()
 465     {
 466     }
 467
 468     /**
 469      * Handler for when the bot receives a CTCP TIME request.
 470      *
 471      * @return void
 472      * @link http://www.invlogic.com/irc/ctcp.html#4.6
 473      */
 474     public function onTime()
 475     {
 476     }
 477
 478     /**
 479      * Handler for when the bot receives a CTCP VERSION request.
 480      *
 481      * @return void
 482      * @link http://www.invlogic.com/irc/ctcp.html#4.1
 483      */
 484     public function onVersion()
 485     {
 486     }
 487
 488     /**
 489      * Handler for when the bot receives a CTCP PING request.
 490      *
 491      * @return void
 492      * @link http://www.invlogic.com/irc/ctcp.html#4.2
 493      */
 494     public function onCtcpPing()
 495     {
 496     }
 497
 498     /**
 499      * Handler for when the bot receives a CTCP request of an unknown type.
 500      *
 501      * @return void
 502      * @link http://www.invlogic.com/irc/ctcp.html
 503      */
 504     public function onCtcp()
 505     {
 506     }
 507
 508     /**
 509      * Handler for when a reply is received for a CTCP PING request sent by
 510      * the bot.
 511      *
 512      * @return void
 513      * @link http://www.invlogic.com/irc/ctcp.html#4.2
 514      */
 515     public function onPingReply()
 516     {
 517     }
 518
 519     /**
 520      * Handler for when a reply is received for a CTCP TIME request sent by
 521      * the bot.
 522      *
 523      * @return void
 524      * @link http://www.invlogic.com/irc/ctcp.html#4.6
 525      */
 526     public function onTimeReply()
 527     {
 528     }
 529
 530     /**
 531      * Handler for when a reply is received for a CTCP VERSION request sent
 532      * by the bot.
 533      *
 534      * @return void
 535      * @link http://www.invlogic.com/irc/ctcp.html#4.1
 536      */
 537     public function onVersionReply()
 538     {
 539     }
 540
 541     /**
 542      * Handler for when a reply received for a CTCP request of an unknown
 543      * type.
 544      *
 545      * @return void
 546      * @link http://www.invlogic.com/irc/ctcp.html
 547      */
 548     public function onCtcpReply()
 549     {
 550     }
 551
 552     /**
 553      * Handler for when the bot receives a kill request from a server.
 554      *
 555      * @return void
 556      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_6_1
 557      */
 558     public function onKill()
 559     {
 560     }
 561
 562     /**
 563      * Handler for when the bot receives an invitation to join a channel.
 564      *
 565      * @return void
 566      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_7
 567      */
 568     public function onInvite()
 569     {
 570     }
 571
 572     /**
 573      * Handler for when a server response is received to a command issued by
 574      * the bot.
 575      *
 576      * @return void
 577      * @link http://irchelp.org/irchelp/rfc/chapter6.html
 578      */
 579     public function onResponse()
 580     {
 581     }
 582 }