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