plugins/Irc/extlib/phergie/Phergie/Hostmask.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 a hostmask.
  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_Hostmask
  32 {
  33     /**
  34      * Host
  35      *
  36      * @var string
  37      */
  38     protected $host;
  39
  40     /**
  41      * Nick
  42      *
  43      * @var string
  44      */
  45     protected $nick;
  46
  47     /**
  48      * Username
  49      *
  50      * @var string
  51      */
  52     protected $username;
  53
  54     /**
  55      * Regular expression used to parse a hostmask
  56      *
  57      * @var string
  58      */
  59     protected static $regex = '/^([^!@]+)!(?:[ni]=)?([^@]+)@([^ ]+)/';
  60
  61     /**
  62      * Constructor to initialize components of the hostmask.
  63      *
  64      * @param string $nick     Nick component
  65      * @param string $username Username component
  66      * @param string $host     Host component
  67      *
  68      * @return void
  69      */
  70     public function __construct($nick, $username, $host)
  71     {
  72         $this->nick = $nick;
  73         $this->username = $username;
  74         $this->host = $host;
  75     }
  76
  77     /**
  78      * Returns whether a given string appears to be a valid hostmask.
  79      *
  80      * @param string $string Alleged hostmask string
  81      *
  82      * @return bool TRUE if the string appears to be a valid hostmask, FALSE
  83      *         otherwise
  84      */
  85     public static function isValid($string)
  86     {
  87         return (preg_match(self::$regex, $string) > 0);
  88     }
  89
  90     /**
  91      * Parses a string containing the entire hostmask into a new instance of
  92      * this class.
  93      *
  94      * @param string $hostmask Entire hostmask including the nick, username,
  95      *        and host components
  96      *
  97      * @return Phergie_Hostmask New instance populated with data parsed from
  98      *         the provided hostmask string
  99      * @throws Phergie_Hostmask_Exception
 100      */
 101     public static function fromString($hostmask)
 102     {
 103         if (preg_match(self::$regex, $hostmask, $match)) {
 104             list(, $nick, $username, $host) = $match;
 105             return new self($nick, $username, $host);
 106         }
 107
 108         throw new Phergie_Hostmask_Exception(
 109             'Invalid hostmask specified: "' . $hostmask . '"',
 110             Phergie_Hostmask_Exception::ERR_INVALID_HOSTMASK
 111         );
 112     }
 113
 114     /**
 115      * Sets the hostname.
 116      *
 117      * @param string $host Hostname
 118      *
 119      * @return Phergie_Hostmask Provides a fluent interface
 120      */
 121     public function setHost($host)
 122     {
 123         $this->host = $host;
 124
 125         return $this;
 126     }
 127
 128     /**
 129      * Returns the hostname.
 130      *
 131      * @return string
 132      */
 133     public function getHost()
 134     {
 135         return $this->host;
 136     }
 137
 138     /**
 139      * Sets the username of the user.
 140      *
 141      * @param string $username Username
 142      *
 143      * @return Phergie_Hostmask Provides a fluent interface
 144      */
 145     public function setUsername($username)
 146     {
 147         $this->username = $username;
 148
 149         return $this;
 150     }
 151
 152     /**
 153      * Returns the username of the user.
 154      *
 155      * @return string
 156      */
 157     public function getUsername()
 158     {
 159         return $this->username;
 160     }
 161
 162     /**
 163      * Sets the nick of the user.
 164      *
 165      * @param string $nick User nick
 166      *
 167      * @return Phergie_Hostmask Provides a fluent interface
 168      */
 169     public function setNick($nick)
 170     {
 171         $this->nick = $nick;
 172
 173         return $this;
 174     }
 175
 176     /**
 177      * Returns the nick of the user.
 178      *
 179      * @return string
 180      */
 181     public function getNick()
 182     {
 183         return $this->nick;
 184     }
 185
 186     /**
 187      * Returns the hostmask for the originating server or user.
 188      *
 189      * @return string
 190      */
 191     public function __toString()
 192     {
 193         return $this->nick . '!' . $this->username . '@' . $this->host;
 194     }
 195
 196     /**
 197      * Returns whether a given hostmask matches a given pattern.
 198      *
 199      * @param string $pattern  Pattern using conventions of a ban mask where
 200      *        represents a wildcard
 201      * @param string $hostmask Optional hostmask to match against, if not
 202      *        the current hostmask instance
 203      *
 204      * @return bool TRUE if the hostmask matches the pattern, FALSE otherwise
 205      * @link http://irchelp.org/irchelp/rfc/chapter4.html#c4_2_3 Examples
 206      */
 207     public function matches($pattern, $hostmask = null)
 208     {
 209         if (!$hostmask) {
 210             $hostmask = (string) $this;
 211         }
 212
 213         $pattern = str_replace('*', '.*', $pattern);
 214
 215         return (preg_match('#^' . $pattern . '$#', $hostmask) > 0);
 216     }
 217 }