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 * Data structure for connection metadata.
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
31 class Phergie_Connection
34 * Host to which the client will connect
41 * Port on which the client will connect, defaults to the standard IRC
49 * Transport for the connection, defaults to tcp but can be set to ssl
50 * or variations thereof to connect over SSL
57 * Encoding method for the connection, defaults to ISO-8859-1 but can
58 * be set to UTF8 if necessary
65 * Nick that the client will use
72 * Username that the client will use
79 * Realname that the client will use
86 * Password that the client will use
93 * Hostmask for the connection
95 * @var Phergie_Hostmask
100 * Constructor to initialize instance properties.
102 * @param array $options Optional associative array of property values
107 public function __construct(array $options = array())
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
114 $this->setOptions($options);
118 * Emits an error related to a required connection setting does not have
121 * @param string $setting Name of the setting
125 protected function checkSetting($setting)
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
136 * Returns a hostmask that uniquely identifies the connection.
140 public function getHostmask()
142 if (empty($this->hostmask)) {
143 $this->hostmask = new Phergie_Hostmask(
145 $this->getUsername(),
150 return $this->hostmask;
154 * Sets the host to which the client will connect.
156 * @param string $host Hostname
158 * @return Phergie_Connection Provides a fluent interface
160 public function setHost($host)
162 if (empty($this->host)) {
163 $this->host = (string) $host;
170 * Returns the host to which the client will connect if it is set or
171 * emits an error if it is not set.
175 public function getHost()
177 $this->checkSetting('host');
183 * Sets the port on which the client will connect.
185 * @param int $port Port
187 * @return Phergie_Connection Provides a fluent interface
189 public function setPort($port)
191 if (empty($this->port)) {
192 $this->port = (int) $port;
199 * Returns the port on which the client will connect.
203 public function getPort()
205 if (empty($this->port)) {
213 * Sets the transport for the connection to use.
215 * @param string $transport Transport (ex: tcp, ssl, etc.)
217 * @return Phergie_Connection Provides a fluent interface
219 public function setTransport($transport)
221 $this->transport = (string) $transport;
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::ERR_TRANSPORT_NOT_SUPPORTED
234 * Returns the transport in use by the connection.
236 * @return string Transport (ex: tcp, ssl, etc.)
238 public function getTransport()
240 return $this->transport;
244 * Sets the encoding for the connection to use.
246 * @param string $encoding Encoding to use (ex: ASCII, ISO-8859-1, UTF8, etc.)
248 * @return Phergie_Connection Provides a fluent interface
250 public function setEncoding($encoding)
252 $this->encoding = (string) $encoding;
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::ERR_ENCODING_NOT_SUPPORTED
265 * Returns the encoding in use by the connection.
267 * @return string Encoding (ex: ASCII, ISO-8859-1, UTF8, etc.)
269 public function getEncoding()
271 return $this->encoding;
275 * Sets the nick that the client will use.
277 * @param string $nick Nickname
279 * @return Phergie_Connection Provides a fluent interface
281 public function setNick($nick)
283 if (empty($this->nick)) {
284 $this->nick = (string) $nick;
291 * Returns the nick that the client will use.
295 public function getNick()
297 $this->checkSetting('nick');
303 * Sets the username that the client will use.
305 * @param string $username Username
307 * @return Phergie_Connection Provides a fluent interface
309 public function setUsername($username)
311 if (empty($this->username)) {
312 $this->username = (string) $username;
319 * Returns the username that the client will use.
323 public function getUsername()
325 $this->checkSetting('username');
327 return $this->username;
331 * Sets the realname that the client will use.
333 * @param string $realname Real name
335 * @return Phergie_Connection Provides a fluent interface
337 public function setRealname($realname)
339 if (empty($this->realname)) {
340 $this->realname = (string) $realname;
347 * Returns the realname that the client will use.
351 public function getRealname()
353 $this->checkSetting('realname');
355 return $this->realname;
359 * Sets the password that the client will use.
361 * @param string $password Password
363 * @return Phergie_Connection Provides a fluent interface
365 public function setPassword($password)
367 if (empty($this->password)) {
368 $this->password = (string) $password;
375 * Returns the password that the client will use.
379 public function getPassword()
381 return $this->password;
385 * Sets multiple connection settings using an array.
387 * @param array $options Associative array of setting names mapped to
388 * corresponding values
390 * @return Phergie_Connection Provides a fluent interface
392 public function setOptions(array $options)
394 foreach ($options as $option => $value) {
395 $method = 'set' . ucfirst($option);
396 if (method_exists($this, $method)) {
397 $this->$method($value);