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      * Sets the value of a single argument for the request.
 245      *
 246      * @param mixed  $argument Integer position (starting from 0) or the
 247      *        equivalent string name of the argument from self::$map
 248      * @param string $value    Value to assign to the argument
 249      *
 250      * @return Phergie_Event_Request Provides a fluent interface
 251      */
 252     public function setArgument($argument, $value)
 253     {
 254         $argument = $this->resolveArgument($argument);
 255         if ($argument !== null) {
 256             $this->arguments[$argument] = (string) $value;
 257         }
 258         return $this;
 259     }
 260
 261     /**
 262      * Returns the arguments for the request.
 263      *
 264      * @return array
 265      */
 266     public function getArguments()
 267     {
 268         return $this->arguments;
 269     }
 270
 271     /**
 272      * Resolves an argument specification to an integer position.
 273      *
 274      * @param mixed $argument Integer position (starting from 0) or the
 275      *        equivalent string name of the argument from self::$map
 276      *
 277      * @return int|null Integer position of the argument or NULL if no
 278      *         corresponding argument was found
 279      */
 280     protected function resolveArgument($argument)
 281     {
 282         if (isset($this->arguments[$argument])) {
 283             return $argument;
 284         } else {
 285             $argument = strtolower($argument);
 286             if (isset(self::$map[$this->type][$argument])
 287                 && isset($this->arguments[self::$map[$this->type][$argument]])
 288             ) {
 289                 return self::$map[$this->type][$argument];
 290             }
 291         }
 292         return null;
 293     }
 294
 295     /**
 296      * Returns a single specified argument for the request.
 297      *
 298      * @param mixed $argument Integer position (starting from 0) or the
 299      *        equivalent string name of the argument from self::$map
 300      *
 301      * @return string|null Argument value or NULL if none is set
 302      */
 303     public function getArgument($argument)
 304     {
 305         $argument = $this->resolveArgument($argument);
 306         if ($argument !== null) {
 307             return $this->arguments[$argument];
 308         }
 309         return null;
 310     }
 311
 312     /**
 313      * Sets the raw buffer for the event.
 314      *
 315      * @param string $buffer Raw event buffer
 316      *
 317      * @return Phergie_Event_Request Provides a fluent interface
 318      */
 319     public function setRawData($buffer)
 320     {
 321         $this->rawData = $buffer;
 322         return $this;
 323     }
 324
 325     /**
 326      * Returns the raw buffer sent from the server for the event.
 327      *
 328      * @return string
 329      */
 330     public function getRawData()
 331     {
 332         return $this->rawData;
 333     }
 334
 335     /**
 336      * Returns the nick of the user who originated the event.
 337      *
 338      * @return string
 339      */
 340     public function getNick()
 341     {
 342         return $this->hostmask->getNick();
 343     }
 344
 345     /**
 346      * Returns the channel name if the event occurred in a channel or the
 347      * user nick if the event was a private message directed at the bot by a
 348      * user.
 349      *
 350      * @return string
 351      */
 352     public function getSource()
 353     {
 354         if (substr($this->arguments[0], 0, 1) == '#') {
 355             return $this->arguments[0];
 356         }
 357         return $this->hostmask->getNick();
 358     }
 359
 360     /**
 361      * Returns whether or not the event occurred within a channel.
 362      *
 363      * @return TRUE if the event is in a channel, FALSE otherwise
 364      */
 365     public function isInChannel()
 366     {
 367         return (substr($this->getSource(), 0, 1) == '#');
 368     }
 369
 370     /**
 371      * Returns whether or not the event originated from a user.
 372      *
 373      * @return TRUE if the event is from a user, FALSE otherwise
 374      */
 375     public function isFromUser()
 376     {
 377         if (empty($this->hostmask)) {
 378             return false;
 379         }
 380         $username = $this->hostmask->getUsername();
 381         return !empty($username);
 382     }
 383
 384     /**
 385      * Returns whether or not the event originated from the server.
 386      *
 387      * @return TRUE if the event is from the server, FALSE otherwise
 388      */
 389     public function isFromServer()
 390     {
 391         $username = $this->hostmask->getUsername();
 392         return empty($username);
 393     }
 394
 395     /**
 396      * Provides access to named parameters via virtual "getter" methods.
 397      *
 398      * @param string $name      Name of the method called
 399      * @param array  $arguments Arguments passed to the method (should always
 400      *        be empty)
 401      *
 402      * @return mixed Method return value
 403      */
 404     public function __call($name, array $arguments)
 405     {
 406         if (!count($arguments) && substr($name, 0, 3) == 'get') {
 407             return $this->getArgument(substr($name, 3));
 408         }
 409     }
 410
 411     /**
 412      * Checks to see if an event argument is assigned a value.
 413      *
 414      * @param string|int $offset Argument name or position beginning from 0
 415      *
 416      * @return bool TRUE if the argument has a value, FALSE otherwise
 417      * @see ArrayAccess::offsetExists()
 418      */
 419     public function offsetExists($offset)
 420     {
 421         return ($this->resolveArgument($offset) !== null);
 422     }
 423
 424     /**
 425      * Returns the value of an event argument.
 426      *
 427      * @param string|int $offset Argument name or position beginning from 0
 428      *
 429      * @return string|null Argument value or NULL if none is set
 430      * @see ArrayAccess::offsetGet()
 431      */
 432     public function offsetGet($offset)
 433     {
 434         return $this->getArgument($offset);
 435     }
 436
 437     /**
 438      * Sets the value of an event argument.
 439      *
 440      * @param string|int $offset Argument name or position beginning from 0
 441      * @param string     $value  New argument value
 442      *
 443      * @return void
 444      * @see ArrayAccess::offsetSet()
 445      */
 446     public function offsetSet($offset, $value)
 447     {
 448         $offset = $this->resolveArgument($offset);
 449         if ($offset !== null) {
 450             $this->arguments[$offset] = $value;
 451         }
 452     }
 453
 454     /**
 455      * Removes the value set for an event argument.
 456      *
 457      * @param string|int $offset Argument name or position beginning from 0
 458      *
 459      * @return void
 460      * @see ArrayAccess::offsetUnset()
 461      */
 462     public function offsetUnset($offset)
 463     {
 464         if ($offset = $this->resolveArgument($offset)) {
 465             unset($this->arguments[$offset]);
 466         }
 467     }
 468 }