plugins/Irc/extlib/phergie/Phergie/Connection.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  * Data structure for connection metadata.
  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  */
  31 class Phergie_Connection
  32 {
  33     /**
  34      * Host to which the client will connect
  35      *
  36      * @var string
  37      */
  38     protected $host;
  39
  40     /**
  41      * Port on which the client will connect, defaults to the standard IRC
  42      * port
  43      *
  44      * @var int
  45      */
  46     protected $port;
  47
  48     /**
  49      * Transport for the connection, defaults to tcp but can be set to ssl
  50      * or variations thereof to connect over SSL
  51      *
  52      * @var string
  53      */
  54     protected $transport;
  55
  56     /**
  57      * Encoding method for the connection, defaults to ISO-8859-1 but can
  58      * be set to UTF8 if necessary
  59      *
  60      * @var strng
  61      */
  62     protected $encoding;
  63
  64     /**
  65      * Nick that the client will use
  66      *
  67      * @var string
  68      */
  69     protected $nick;
  70
  71     /**
  72      * Username that the client will use
  73      *
  74      * @var string
  75      */
  76     protected $username;
  77
  78     /**
  79      * Realname that the client will use
  80      *
  81      * @var string
  82      */
  83     protected $realname;
  84
  85     /**
  86      * Password that the client will use
  87      *
  88      * @var string
  89      */
  90     protected $password;
  91
  92     /**
  93      * Hostmask for the connection
  94      *
  95      * @var Phergie_Hostmask
  96      */
  97     protected $hostmask;
  98
  99     /**
 100      * Constructor to initialize instance properties.
 101      *
 102      * @param array $options Optional associative array of property values
 103      *        to initialize
 104      *
 105      * @return void
 106      */
 107     public function __construct(array $options = array())
 108     {
 109         $this->transport = 'tcp';
 110         $this->encoding = 'ISO-8859-1';
 111         // @note this may need changed to something different, for broader support.
 112         // @note also may need to make use of http://us.php.net/manual/en/function.stream-encoding.php
 113
 114         $this->setOptions($options);
 115     }
 116
 117     /**
 118      * Emits an error related to a required connection setting does not have
 119      * value set for it.
 120      *
 121      * @param string $setting Name of the setting
 122      *
 123      * @return void
 124      */
 125     protected function checkSetting($setting)
 126     {
 127         if (empty($this->$setting)) {
 128             throw new Phergie_Connection_Exception(
 129                 'Required connection setting "' . $setting . '" missing',
 130                 Phergie_Connection_Exception::ERR_REQUIRED_SETTING_MISSING
 131             );
 132         }
 133     }
 134
 135     /**
 136      * Returns a hostmask that uniquely identifies the connection.
 137      *
 138      * @return string
 139      */
 140     public function getHostmask()
 141     {
 142         if (empty($this->hostmask)) {
 143             $this->hostmask = new Phergie_Hostmask(
 144                 $this->nick,
 145                 $this->username,
 146                 $this->host
 147             );
 148         }
 149
 150         return $this->hostmask;
 151     }
 152
 153     /**
 154      * Sets the host to which the client will connect.
 155      *
 156      * @param string $host Hostname
 157      *
 158      * @return Phergie_Connection Provides a fluent interface
 159      */
 160     public function setHost($host)
 161     {
 162         if (empty($this->host)) {
 163             $this->host = (string) $host;
 164         }
 165
 166         return $this;
 167     }
 168
 169     /**
 170      * Returns the host to which the client will connect if it is set or
 171      * emits an error if it is not set.
 172      *
 173      * @return string
 174      */
 175     public function getHost()
 176     {
 177         $this->checkSetting('host');
 178
 179         return $this->host;
 180     }
 181
 182     /**
 183      * Sets the port on which the client will connect.
 184      *
 185      * @param int $port Port
 186      *
 187      * @return Phergie_Connection Provides a fluent interface
 188      */
 189     public function setPort($port)
 190     {
 191         if (empty($this->port)) {
 192             $this->port = (int) $port;
 193         }
 194
 195         return $this;
 196     }
 197
 198     /**
 199      * Returns the port on which the client will connect.
 200      *
 201      * @return int
 202      */
 203     public function getPort()
 204     {
 205         if (empty($this->port)) {
 206             $this->port = 6667;
 207         }
 208
 209         return $this->port;
 210     }
 211
 212     /**
 213      * Sets the transport for the connection to use.
 214      *
 215      * @param string $transport Transport (ex: tcp, ssl, etc.)
 216      *
 217      * @return Phergie_Connection Provides a fluent interface
 218      */
 219     public function setTransport($transport)
 220     {
 221         $this->transport = (string) $transport;
 222
 223         if (!in_array($this->transport, stream_get_transports())) {
 224             throw new Phergie_Connection_Exception(
 225                 'Transport ' . $this->transport . ' is not supported',
 226                 Phergie_Connection_Exception::TRANSPORT_NOT_SUPPORTED
 227             );
 228         }
 229
 230         return $this;
 231     }
 232
 233     /**
 234      * Returns the transport in use by the connection.
 235      *
 236      * @return string Transport (ex: tcp, ssl, etc.)
 237      */
 238     public function getTransport()
 239     {
 240         return $this->transport;
 241     }
 242
 243     /**
 244      * Sets the encoding for the connection to use.
 245      *
 246      * @param string $encoding Encoding to use (ex: ASCII, ISO-8859-1, UTF8, etc.)
 247      *
 248      * @return Phergie_Connection Provides a fluent interface
 249      */
 250     public function setEncoding($encoding)
 251     {
 252         $this->encoding = (string) $encoding;
 253
 254         if (!in_array($this->encoding, mb_list_encodings())) {
 255             throw new Phergie_Connection_Exception(
 256                 'Encoding ' . $this->encoding . ' is not supported',
 257                 Phergie_Connection_Exception::ENCODING_NOT_SUPPORTED
 258             );
 259         }
 260
 261         return $this;
 262     }
 263
 264     /**
 265      * Returns the encoding in use by the connection.
 266      *
 267      * @return string Encoding (ex: ASCII, ISO-8859-1, UTF8, etc.)
 268      */
 269     public function getEncoding()
 270     {
 271         return $this->encoding;
 272     }
 273
 274     /**
 275      * Sets the nick that the client will use.
 276      *
 277      * @param string $nick Nickname
 278      *
 279      * @return Phergie_Connection Provides a fluent interface
 280      */
 281     public function setNick($nick)
 282     {
 283         if (empty($this->nick)) {
 284             $this->nick = (string) $nick;
 285         }
 286
 287         return $this;
 288     }
 289
 290     /**
 291      * Returns the nick that the client will use.
 292      *
 293      * @return string
 294      */
 295     public function getNick()
 296     {
 297         $this->checkSetting('nick');
 298
 299         return $this->nick;
 300     }
 301
 302     /**
 303      * Sets the username that the client will use.
 304      *
 305      * @param string $username Username
 306      *
 307      * @return Phergie_Connection Provides a fluent interface
 308      */
 309     public function setUsername($username)
 310     {
 311         if (empty($this->username)) {
 312             $this->username = (string) $username;
 313         }
 314
 315         return $this;
 316     }
 317
 318     /**
 319      * Returns the username that the client will use.
 320      *
 321      * @return string
 322      */
 323     public function getUsername()
 324     {
 325         $this->checkSetting('username');
 326
 327         return $this->username;
 328     }
 329
 330     /**
 331      * Sets the realname that the client will use.
 332      *
 333      * @param string $realname Real name
 334      *
 335      * @return Phergie_Connection Provides a fluent interface
 336      */
 337     public function setRealname($realname)
 338     {
 339         if (empty($this->realname)) {
 340             $this->realname = (string) $realname;
 341         }
 342
 343         return $this;
 344     }
 345
 346     /**
 347      * Returns the realname that the client will use.
 348      *
 349      * @return string
 350      */
 351     public function getRealname()
 352     {
 353         $this->checkSetting('realname');
 354
 355         return $this->realname;
 356     }
 357
 358     /**
 359      * Sets the password that the client will use.
 360      *
 361      * @param string $password Password
 362      *
 363      * @return Phergie_Connection Provides a fluent interface
 364      */
 365     public function setPassword($password)
 366     {
 367         if (empty($this->password)) {
 368             $this->password = (string) $password;
 369         }
 370
 371         return $this;
 372     }
 373
 374     /**
 375      * Returns the password that the client will use.
 376      *
 377      * @return string
 378      */
 379     public function getPassword()
 380     {
 381         return $this->password;
 382     }
 383
 384     /**
 385      * Sets multiple connection settings using an array.
 386      *
 387      * @param array $options Associative array of setting names mapped to
 388      *        corresponding values
 389      *
 390      * @return Phergie_Connection Provides a fluent interface
 391      */
 392     public function setOptions(array $options)
 393     {
 394         foreach ($options as $option => $value) {
 395             $method = 'set' . ucfirst($option);
 396             if (method_exists($this, $method)) {
 397                 $this->$method($value);
 398             }
 399         }
 400     }
 401 }