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
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
23 * Base class for plugins to provide event handler stubs and commonly needed
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
32 abstract class Phergie_Plugin_Abstract
35 * Current configuration handler
42 * Plugin handler used to provide access to other plugins
44 * @var Phergie_Plugin_Handler
49 * Current event handler instance for outgoing events
51 * @var Phergie_Event_Handler
56 * Current connection instance
58 * @var Phergie_Connection
60 protected $connection;
63 * Current incoming event being handled
65 * @var Phergie_Event_Request|Phergie_Event_Response
77 * Returns the short name for the plugin based on its class name.
81 public function getName()
83 if (empty($this->name)) {
84 $this->name = substr(strrchr(get_class($this), '_'), 1);
90 * Sets the short name for the plugin.
92 * @param string $name Plugin short name
94 * @return Phergie_Plugin_Abstract Provides a fluent interface
96 public function setName($name)
98 $this->name = (string) $name;
103 * Indicates that the plugin failed to load due to an unsatisfied
104 * runtime requirement, such as a missing dependency.
106 * @param string $message Error message to provide more information
107 * about the reason for the failure
109 * @return Phergie_Plugin_Abstract Provides a fluent interface
110 * @throws Phergie_Plugin_Exception Always
112 protected function fail($message)
114 throw new Phergie_Plugin_Exception(
116 Phergie_Plugin_Exception::ERR_REQUIREMENT_UNSATISFIED
121 * Sets the current configuration handler.
123 * @param Phergie_Config $config Configuration handler
125 * @return Phergie_Plugin_Abstract Provides a fluent interface
127 public function setConfig(Phergie_Config $config)
129 $this->config = $config;
134 * Returns the current configuration handler or the value of a single
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
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
146 public function getConfig($name = null, $default = null)
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
154 if (!is_null($name)) {
155 if (!isset($this->config[$name])) {
158 return $this->config[$name];
160 return $this->config;
164 * Sets the current plugin handler.
166 * @param Phergie_Plugin_Handler $handler Plugin handler
168 * @return Phergie_Plugin_Abstract Provides a fluent interface
170 public function setPluginHandler(Phergie_Plugin_Handler $handler)
172 $this->plugins = $handler;
177 * Returns the current plugin handler.
179 * @return Phergie_Plugin_Handler
180 * @throws Phergie_Plugin_Exception No plugin handler has been set
182 public function getPluginHandler()
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
190 return $this->plugins;
194 * Sets the current event handler.
196 * @param Phergie_Event_Handler $handler Event handler
198 * @return Phergie_Plugin_Abstract Provides a fluent interface
200 public function setEventHandler(Phergie_Event_Handler $handler)
202 $this->events = $handler;
207 * Returns the current event handler.
209 * @return Phergie_Event_Handler
210 * @throws Phergie_Plugin_Exception No event handler has been set
212 public function getEventHandler()
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
220 return $this->events;
224 * Sets the current connection.
226 * @param Phergie_Connection $connection Connection
228 * @return Phergie_Plugin_Abstract Provides a fluent interface
230 public function setConnection(Phergie_Connection $connection)
232 $this->connection = $connection;
237 * Returns the current event connection.
239 * @return Phergie_Connection
240 * @throws Phergie_Plugin_Exception No connection has been set
242 public function getConnection()
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
250 return $this->connection;
254 * Sets the current incoming event to be handled.
256 * @param Phergie_Event_Request|Phergie_Event_Response $event Event
258 * @return Phergie_Plugin_Abstract Provides a fluent interface
260 public function setEvent($event)
262 $this->event = $event;
267 * Returns the current incoming event to be handled.
269 * @return Phergie_Event_Request|Phergie_Event_Response
271 public function getEvent()
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
283 * Provides do* methods with signatures identical to those of
284 * Phergie_Driver_Abstract but that queue up events to be dispatched
287 * @param string $name Name of the method called
288 * @param array $args Arguments passed in the call
292 public function __call($name, array $args)
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
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.
313 public function onLoad()
318 * Handler for when the bot initially connects to a server.
322 public function onConnect()
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.
333 public function onTick()
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.
341 * @return bool|null|void FALSE to short-circuit further event
342 * processing, TRUE or NULL otherwise
344 public function preEvent()
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.
355 public function preDispatch()
360 * Handler for after any events triggered by plugins in response to a
361 * received event are sent to the server.
365 public function postDispatch()
370 * Handler for when the server prompts the client for a nick.
373 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_2
375 public function onNick()
380 * Handler for when a user obtains operator privileges.
383 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_5
385 public function onOper()
390 * Handler for when the client session is about to be terminated.
393 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_1_6
395 public function onQuit()
400 * Handler for when a user joins a channel.
403 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_1
405 public function onJoin()
410 * Handler for when a user leaves a channel.
413 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_2
415 public function onPart()
420 * Handler for when a user or channel mode is changed.
423 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_3
425 public function onMode()
430 * Handler for when a channel topic is viewed or changed.
433 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_4
435 public function onTopic()
440 * Handler for when a message is received from a channel or user.
443 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_4_1
445 public function onPrivmsg()
450 * Handler for when the bot receives a CTCP ACTION request.
453 * @link http://www.invlogic.com/irc/ctcp.html#4.4
455 public function onAction()
460 * Handler for when a notice is received.
463 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_4_2
465 public function onNotice()
470 * Handler for when a user is kicked from a channel.
473 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_8
475 public function onKick()
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.
485 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_6_2
487 public function onPing()
492 * Handler for when the bot receives a CTCP TIME request.
495 * @link http://www.invlogic.com/irc/ctcp.html#4.6
497 public function onTime()
502 * Handler for when the bot receives a CTCP VERSION request.
505 * @link http://www.invlogic.com/irc/ctcp.html#4.1
507 public function onVersion()
512 * Handler for when the bot receives a CTCP PING request.
515 * @link http://www.invlogic.com/irc/ctcp.html#4.2
517 public function onCtcpPing()
522 * Handler for when the bot receives a CTCP request of an unknown type.
525 * @link http://www.invlogic.com/irc/ctcp.html
527 public function onCtcp()
532 * Handler for when a reply is received for a CTCP PING request sent by
536 * @link http://www.invlogic.com/irc/ctcp.html#4.2
538 public function onPingReply()
543 * Handler for when a reply is received for a CTCP TIME request sent by
547 * @link http://www.invlogic.com/irc/ctcp.html#4.6
549 public function onTimeReply()
554 * Handler for when a reply is received for a CTCP VERSION request sent
558 * @link http://www.invlogic.com/irc/ctcp.html#4.1
560 public function onVersionReply()
565 * Handler for when a reply received for a CTCP request of an unknown
569 * @link http://www.invlogic.com/irc/ctcp.html
571 public function onCtcpReply()
576 * Handler for when the bot receives a kill request from a server.
579 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_6_1
581 public function onKill()
586 * Handler for when the bot receives an invitation to join a channel.
589 * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_7
591 public function onInvite()
596 * Handler for when a server response is received to a command issued by
600 * @link http://irchelp.org/irchelp/rfc/chapter6.html
602 public function onResponse()