plugins/Irc/extlib/phergie/Phergie/Event/Request.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  * Autonomous event originating from a user or the server.
  24  *
  25  * @category Phergie
  26  * @package  Phergie
  27  * @author   Phergie Development Team <team@phergie.org>
  28  * @license  http://phergie.org/license New BSD License
  29  * @link     http://pear.phergie.org/package/Phergie
  30  * @link     http://www.irchelp.org/irchelp/rfc/chapter4.html
  31  */
  32 class Phergie_Event_Request
  33     extends Phergie_Event_Abstract
  34     implements ArrayAccess
  35 {
  36     /**
  37      * Nick message event type
  38      */
  39     const TYPE_NICK = 'nick';
  40
  41     /**
  42      * Whois message event type
  43      */
  44     const TYPE_WHOIS = 'whois';
  45
  46     /**
  47      * Quit command event type
  48      */
  49     const TYPE_QUIT = 'quit';
  50
  51     /**
  52      * Join message event type
  53      */
  54     const TYPE_JOIN = 'join';
  55
  56     /**
  57      * Kick message event type
  58      */
  59     const TYPE_KICK = 'kick';
  60
  61     /**
  62      * Part message event type
  63      */
  64     const TYPE_PART = 'part';
  65
  66     /**
  67      * Invite message event type
  68      */
  69     const TYPE_INVITE = 'invite';
  70
  71     /**
  72      * Mode message event type
  73      */
  74     const TYPE_MODE = 'mode';
  75
  76     /**
  77      * Topic message event type
  78      */
  79     const TYPE_TOPIC = 'topic';
  80
  81     /**
  82      * Private message command event type
  83      */
  84     const TYPE_PRIVMSG = 'privmsg';
  85
  86     /**
  87      * Notice message event type
  88      */
  89     const TYPE_NOTICE = 'notice';
  90
  91     /**
  92      * Pong message event type
  93      */
  94     const TYPE_PONG = 'pong';
  95
  96     /**
  97      * CTCP ACTION command event type
  98      */
  99     const TYPE_ACTION = 'action';
 100
 101     /**
 102      * CTCP PING command event type
 103      */
 104     const TYPE_PING = 'ping';
 105
 106     /**
 107      * CTCP TIME command event type
 108      */
 109     const TYPE_TIME = 'time';
 110
 111     /**
 112      * CTCP VERSION command event type
 113      */
 114     const TYPE_VERSION = 'version';
 115
 116     /**
 117      * RAW message event type
 118      */
 119     const TYPE_RAW = 'raw';
 120
 121     /**
 122      * Mapping of event types to their named parameters
 123      *
 124      * @var array
 125      */
 126     protected static $map = array(
 127
 128         self::TYPE_QUIT => array(
 129             'message' => 0
 130         ),
 131
 132         self::TYPE_JOIN => array(
 133             'channel' => 0
 134         ),
 135
 136         self::TYPE_KICK => array(
 137             'channel' => 0,
 138             'user'    => 1,
 139             'comment' => 2
 140         ),
 141
 142         self::TYPE_PART => array(
 143             'channel' => 0,
 144             'message' => 1
 145         ),
 146
 147         self::TYPE_INVITE => array(
 148             'nickname' => 0,
 149             'channel'  => 1
 150         ),
 151
 152         self::TYPE_MODE => array(
 153             'target'  => 0,
 154             'mode'    => 1,
 155             'limit'   => 2,
 156             'user'    => 3,
 157             'banmask' => 4
 158         ),
 159
 160         self::TYPE_TOPIC => array(
 161             'channel' => 0,
 162             'topic'   => 1
 163         ),
 164
 165         self::TYPE_PRIVMSG => array(
 166             'receiver' => 0,
 167             'text'     => 1
 168         ),
 169
 170         self::TYPE_NOTICE => array(
 171             'nickname' => 0,
 172             'text'     => 1
 173         ),
 174
 175         self::TYPE_ACTION => array(
 176             'target' => 0,
 177             'action' => 1
 178         ),
 179
 180         self::TYPE_RAW => array(
 181             'message' => 0
 182         )
 183
 184     );
 185
 186     /**
 187      * Hostmask representing the originating user, if applicable
 188      *
 189      * @var Phergie_Hostmask
 190      */
 191     protected $hostmask;
 192
 193     /**
 194      * Arguments included with the message
 195      *
 196      * @var array
 197      */
 198     protected $arguments;
 199
 200     /**
 201      * Raw data sent by the server
 202      *
 203      * @var string
 204      */
 205     protected $rawData;
 206
 207     /**
 208      * Sets the hostmask representing the originating user.
 209      *
 210      * @param Phergie_Hostmask $hostmask User hostmask
 211      *
 212      * @return Phergie_Event_Request Provides a fluent interface
 213      */
 214     public function setHostmask(Phergie_Hostmask $hostmask)
 215     {
 216         $this->hostmask = $hostmask;
 217         return $this;
 218     }
 219
 220     /**
 221      * Returns the hostmask representing the originating user.
 222      *
 223      * @return Phergie_Event_Request|null Hostmask or NULL if none was set
 224      */
 225     public function getHostmask()
 226     {
 227         return $this->hostmask;
 228     }
 229
 230     /**
 231      * Sets the arguments for the request.
 232      *
 233      * @param array $arguments Request arguments
 234      *
 235      * @return Phergie_Event_Request Provides a fluent interface
 236      */
 237     public function setArguments($arguments)
 238     {
 239         $this->arguments = $arguments;
 240         return $this;
 241     }
 242
 243     /**
 244      * Returns the arguments for the request.
 245      *
 246      * @return array
 247      */
 248     public function getArguments()
 249     {
 250         return $this->arguments;
 251     }
 252
 253     /**
 254      * Resolves an argument specification to an integer position.
 255      *
 256      * @param mixed $argument Integer position (starting from 0) or the
 257      *        equivalent string name of the argument from self::$map
 258      *
 259      * @return int|null Integer position of the argument or NULL if no
 260      *         corresponding argument was found
 261      */
 262     protected function resolveArgument($argument)
 263     {
 264         if (isset($this->arguments[$argument])) {
 265             return $argument;
 266         } else {
 267             $argument = strtolower($argument);
 268             if (isset(self::$map[$this->type][$argument])
 269                 && isset($this->arguments[self::$map[$this->type][$argument]])
 270             ) {
 271                 return self::$map[$this->type][$argument];
 272             }
 273         }
 274         return null;
 275     }
 276
 277     /**
 278      * Returns a single specified argument for the request.
 279      *
 280      * @param mixed $argument Integer position (starting from 0) or the
 281      *        equivalent string name of the argument from self::$map
 282      *
 283      * @return string|null Argument value or NULL if none is set
 284      */
 285     public function getArgument($argument)
 286     {
 287         $argument = $this->resolveArgument($argument);
 288         if ($argument !== null) {
 289             return $this->arguments[$argument];
 290         }
 291         return null;
 292     }
 293
 294     /**
 295      * Sets the raw buffer for the event.
 296      *
 297      * @param string $buffer Raw event buffer
 298      *
 299      * @return Phergie_Event_Request Provides a fluent interface
 300      */
 301     public function setRawData($buffer)
 302     {
 303         $this->rawData = $buffer;
 304         return $this;
 305     }
 306
 307     /**
 308      * Returns the raw buffer sent from the server for the event.
 309      *
 310      * @return string
 311      */
 312     public function getRawData()
 313     {
 314         return $this->rawData;
 315     }
 316
 317     /**
 318      * Returns the nick of the user who originated the event.
 319      *
 320      * @return string
 321      */
 322     public function getNick()
 323     {
 324         return $this->hostmask->getNick();
 325     }
 326
 327     /**
 328      * Returns the channel name if the event occurred in a channel or the
 329      * user nick if the event was a private message directed at the bot by a
 330      * user.
 331      *
 332      * @return string
 333      */
 334     public function getSource()
 335     {
 336         if (substr($this->arguments[0], 0, 1) == '#') {
 337             return $this->arguments[0];
 338         }
 339         return $this->hostmask->getNick();
 340     }
 341
 342     /**
 343      * Returns whether or not the event occurred within a channel.
 344      *
 345      * @return TRUE if the event is in a channel, FALSE otherwise
 346      */
 347     public function isInChannel()
 348     {
 349         return (substr($this->getSource(), 0, 1) == '#');
 350     }
 351
 352     /**
 353      * Returns whether or not the event originated from a user.
 354      *
 355      * @return TRUE if the event is from a user, FALSE otherwise
 356      */
 357     public function isFromUser()
 358     {
 359         if (empty($this->hostmask)) {
 360             return false;
 361         }
 362         $username = $this->hostmask->getUsername();
 363         return !empty($username);
 364     }
 365
 366     /**
 367      * Returns whether or not the event originated from the server.
 368      *
 369      * @return TRUE if the event is from the server, FALSE otherwise
 370      */
 371     public function isFromServer()
 372     {
 373         $username = $this->hostmask->getUsername();
 374         return empty($username);
 375     }
 376
 377     /**
 378      * Provides access to named parameters via virtual "getter" methods.
 379      *
 380      * @param string $name      Name of the method called
 381      * @param array  $arguments Arguments passed to the method (should always
 382      *        be empty)
 383      *
 384      * @return mixed Method return value
 385      */
 386     public function __call($name, array $arguments)
 387     {
 388         if (!count($arguments) && substr($name, 0, 3) == 'get') {
 389             return $this->getArgument(substr($name, 3));
 390         }
 391     }
 392
 393     /**
 394      * Checks to see if an event argument is assigned a value.
 395      *
 396      * @param string|int $offset Argument name or position beginning from 0
 397      *
 398      * @return bool TRUE if the argument has a value, FALSE otherwise
 399      * @see ArrayAccess::offsetExists()
 400      */
 401     public function offsetExists($offset)
 402     {
 403         return ($this->resolveArgument($offset) !== null);
 404     }
 405
 406     /**
 407      * Returns the value of an event argument.
 408      *
 409      * @param string|int $offset Argument name or position beginning from 0
 410      *
 411      * @return string|null Argument value or NULL if none is set
 412      * @see ArrayAccess::offsetGet()
 413      */
 414     public function offsetGet($offset)
 415     {
 416         return $this->getArgument($offset);
 417     }
 418
 419     /**
 420      * Sets the value of an event argument.
 421      *
 422      * @param string|int $offset Argument name or position beginning from 0
 423      * @param string     $value  New argument value
 424      *
 425      * @return void
 426      * @see ArrayAccess::offsetSet()
 427      */
 428     public function offsetSet($offset, $value)
 429     {
 430         $offset = $this->resolveArgument($offset);
 431         if ($offset !== null) {
 432             $this->arguments[$offset] = $value;
 433         }
 434     }
 435
 436     /**
 437      * Removes the value set for an event argument.
 438      *
 439      * @param string|int $offset Argument name or position beginning from 0
 440      *
 441      * @return void
 442      * @see ArrayAccess::offsetUnset()
 443      */
 444     public function offsetUnset($offset)
 445     {
 446         if ($offset = $this->resolveArgument($offset)) {
 447             unset($this->arguments[$offset]);
 448         }
 449     }
 450 }