Net_Socket Class Reference

Generalized Socket class. More...

Inheritance diagram for Net_Socket:

Collaboration diagram for Net_Socket:

Public Member Functions
	connect ($addr, $port=0, $persistent=null, $timeout=null, $options=null)
	Connect to the specified port.
	disconnect ()
	Disconnects from the peer, closes the socket.
	isBlocking ()
	Find out if the socket is in blocking mode.
	setBlocking ($mode)
	Sets whether the socket connection should be blocking or not.
	setTimeout ($seconds, $microseconds)
	Sets the timeout value on socket descriptor, expressed in the sum of seconds and microseconds.
	setWriteBuffer ($size)
	Sets the file buffering size on the stream.
	getStatus ()
	Returns information about an existing socket resource.
	gets ($size)
	Get a specified line of data.
	read ($size)
	Read a specified amount of data.
	write ($data, $blocksize=null)
	Write a specified amount of data.
	writeLine ($data)
	Write a line of data to the socket, followed by a trailing "\r\n".
	eof ()
	Tests for end-of-file on a socket descriptor.
	readByte ()
	Reads a byte of data.
	readWord ()
	Reads a word of data.
	readInt ()
	Reads an int of data.
	readString ()
	Reads a zero-terminated string of data.
	readIPAddress ()
	Reads an IP Address and returns it in a dot formatted string.
	readLine ()
	Read until either the end of the socket or a newline, whichever comes first.
	readAll ()
	Read until the socket closes, or until there is no more data in the inner PHP buffer.
	select ($state, $tv_sec, $tv_usec=0)
	Runs the equivalent of the select() system call on the socket with a timeout specified by tv_sec and tv_usec.
	enableCrypto ($enabled, $type)
	Turns encryption on/off on a connected socket.
Public Member Functions inherited from PEAR
	PEAR ($error_class=null)
	Constructor.
	_PEAR ()
	Destructor (the emulated type of...).
&	getStaticProperty ($class, $var)
	If you have a class that's mostly/entirely static, and you need static properties, you can use this method to simulate them.
	registerShutdownFunc ($func, $args=array())
	Use this function to register a shutdown method for static classes.
	isError ($data, $code=null)
	Tell whether a value is a PEAR error.
	setErrorHandling ($mode=null, $options=null)
	Sets how errors generated by this object should be handled.
	expectError ($code= '*')
	This method is used to tell which errors you expect to get.
	popExpect ()
	This method pops one element off the expected error codes stack.
	_checkDelExpect ($error_code)
	This method checks unsets an error code if available.
	delExpect ($error_code)
	This method deletes all occurences of the specified element from the expected error codes stack.
&	raiseError ($message=null, $code=null, $mode=null, $options=null, $userinfo=null, $error_class=null, $skipmsg=false)
	This method is a wrapper that returns an instance of the configured error class with this object's default error handling applied.
&	throwError ($message=null, $code=null, $userinfo=null)
	Simpler form of raiseError with fewer options.
	staticPushErrorHandling ($mode, $options=null)
	staticPopErrorHandling ()
	pushErrorHandling ($mode, $options=null)
	Push a new error handler on top of the error handler options stack.
	popErrorHandling ()
	Pop the last error handler used.
	loadExtension ($ext)
	OS independant PHP extension load.

Data Fields
	$fp = null
	Socket file pointer.
	$blocking = true
	Whether the socket is blocking.
	$persistent = false
	Whether the socket is persistent.
	$addr = ''
	The IP address to connect to.
	$port = 0
	The port number to connect to.
	$timeout = false
	Number of seconds to wait on socket connections before assuming there's no more data.
	$lineLength = 2048
	Number of bytes to read at a time in readLine() and readAll().
Data Fields inherited from PEAR
	$_debug = false
	$_default_error_mode = null
	$_default_error_options = null
	$_default_error_handler = ''
	$_error_class = 'PEAR_Error'
	$_expected_errors = array()

Detailed Description

Generalized Socket class.

Version

1.1

Author

Stig Bakken ssb@p.nosp@m.hp.n.nosp@m.et

Chuck Hagenbuch chuck.nosp@m.@hor.nosp@m.de.or.nosp@m.g

Definition at line 35 of file Socket.php.

Member Function Documentation

Net_Socket::connect	(		$addr,
			$port = 0,
			$persistent = null,
			$timeout = null,
			$options = null
	)

Connect to the specified port.

If called when the socket is already connected, it disconnects and connects again.

Parameters

string	$addr	IP address or host name.
integer	$port	TCP port number.
boolean	$persistent	(optional) Whether the connection is persistent (kept open between requests by the web server).
integer	$timeout	(optional) How long to wait for data.
array	$options	See options for stream_context_create.

public

Returns

boolean | PEAR_Error True on success or a PEAR_Error on failure.

Definition at line 97 of file Socket.php.

References $addr, $fp, $persistent, $port, $timeout, PEAR\raiseError(), and setBlocking().

    {
        if (is_resource($this->fp)) {
            @fclose($this->fp);
            $this->fp = null;
        }

        if (!$addr) {
            return $this->raiseError('$addr cannot be empty');
        } elseif (strspn($addr, '.0123456789') == strlen($addr) ||
                  strstr($addr, '/') !== false) {
            $this->addr = $addr;
        } else {
            $this->addr = @gethostbyname($addr);
        }

        $this->port = $port % 65536;

        if ($persistent !== null) {
            $this->persistent = $persistent;
        }

        if ($timeout !== null) {
            $this->timeout = $timeout;
        }

        $openfunc = $this->persistent ? 'pfsockopen' : 'fsockopen';
        $errno = 0;
        $errstr = '';
        $old_track_errors = @ini_set('track_errors', 1);
        if ($options && function_exists('stream_context_create')) {
            if ($this->timeout) {
                $timeout = $this->timeout;
            } else {
                $timeout = 0;
            }
            $context = stream_context_create($options);

            // Since PHP 5 fsockopen doesn't allow context specification
            if (function_exists('stream_socket_client')) {
                $flags = $this->persistent ? STREAM_CLIENT_PERSISTENT : STREAM_CLIENT_CONNECT;
                $addr = $this->addr . ':' . $this->port;
                $fp = stream_socket_client($addr, $errno, $errstr, $timeout, $flags, $context);
            } else {
                $fp = @$openfunc($this->addr, $this->port, $errno, $errstr, $timeout, $context);
            }
        } else {
            if ($this->timeout) {
                $fp = @$openfunc($this->addr, $this->port, $errno, $errstr, $this->timeout);
            } else {
                $fp = @$openfunc($this->addr, $this->port, $errno, $errstr);
            }
        }

        if (!$fp) {
            if ($errno == 0 && isset($php_errormsg)) {
                $errstr = $php_errormsg;
            }
            @ini_set('track_errors', $old_track_errors);
            return $this->raiseError($errstr, $errno);
        }

        @ini_set('track_errors', $old_track_errors);
        $this->fp = $fp;

        return $this->setBlocking($this->blocking);
    }

Here is the call graph for this function:

Net_Socket::disconnect

(

)

Disconnects from the peer, closes the socket.

public

Returns

mixed true on success or a PEAR_Error instance otherwise

Definition at line 171 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        @fclose($this->fp);
        $this->fp = null;
        return true;
    }

Here is the call graph for this function:

Net_Socket::enableCrypto	(		$enabled,
			$type
	)

Turns encryption on/off on a connected socket.

Parameters

bool	$enabled	Set this parameter to true to enable encryption and false to disable encryption.
integer	$type	Type of encryption. See http://se.php.net/manual/en/function.stream-socket-enable-crypto.php for values.

public

Returns

false on error, true on success and 0 if there isn't enough data and the user should try again (non-blocking sockets only). A PEAR_Error object is returned if the socket is not connected

Definition at line 580 of file Socket.php.

References $type, and PEAR\raiseError().

    {
        if (version_compare(phpversion(), "5.1.0", ">=")) {
            if (!is_resource($this->fp)) {
                return $this->raiseError('not connected');
            }
            return @stream_socket_enable_crypto($this->fp, $enabled, $type);
        } else {
            return $this->raiseError('Net_Socket::enableCrypto() requires php version >= 5.1.0');
        }
    }

Here is the call graph for this function:

Net_Socket::eof

(

)

Tests for end-of-file on a socket descriptor.

Also returns true if the socket is disconnected.

public

Returns

bool

Definition at line 374 of file Socket.php.

    {
        return (!is_resource($this->fp) || feof($this->fp));
    }

Net_Socket::gets

(

$size

)

Get a specified line of data.

public

Returns

$size bytes of data from the socket, or a PEAR_Error if not connected.

Definition at line 283 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return @fgets($this->fp, $size);
    }

Here is the call graph for this function:

Net_Socket::getStatus

(

)

Returns information about an existing socket resource.

Currently returns four entries in the result array:

timed_out (bool) - The socket timed out waiting for data
blocked (bool) - The socket was blocked
eof (bool) - Indicates EOF event
unread_bytes (int) - Number of bytes left in the socket buffer

public

Returns

mixed Array containing information about existing socket resource or a PEAR_Error instance otherwise

Definition at line 267 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return socket_get_status($this->fp);
    }

Here is the call graph for this function:

Net_Socket::isBlocking

(

)

Find out if the socket is in blocking mode.

public

Returns

boolean The current blocking mode.

Definition at line 188 of file Socket.php.

References $blocking.

    {
        return $this->blocking;
    }

Net_Socket::read

(

$size

)

Read a specified amount of data.

This is guaranteed to return, and has the added benefit of getting everything in one fread() chunk; if you know the size of the data you're getting beforehand, this is definitely the way to go.

Parameters

integer

$size

The number of bytes to read from the socket. public

Returns

$size bytes of data from the socket, or a PEAR_Error if not connected.

Definition at line 303 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return @fread($this->fp, $size);
    }

Here is the call graph for this function:

Net_Socket::readAll

(

)

Read until the socket closes, or until there is no more data in the inner PHP buffer.

If the inner buffer is empty, in blocking mode we wait for at least 1 byte of data. Therefore, in blocking mode, if there is no data at all to be read, this function will never exit (unless the socket is closed on the remote end).

public

Returns

string All data until the socket closes, or a PEAR_Error if not connected.

Definition at line 507 of file Socket.php.

References $data, and PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $data = '';
        while (!feof($this->fp)) {
            $data .= @fread($this->fp, $this->lineLength);
        }
        return $data;
    }

Here is the call graph for this function:

Net_Socket::readByte

(

)

Reads a byte of data.

public

Returns

1 byte of data from the socket, or a PEAR_Error if not connected.

Definition at line 386 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return ord(@fread($this->fp, 1));
    }

Here is the call graph for this function:

Net_Socket::readInt

(

)

Reads an int of data.

public

Returns

integer 1 int of data from the socket, or a PEAR_Error if not connected.

Definition at line 419 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $buf = @fread($this->fp, 4);
        return (ord($buf[0]) + (ord($buf[1]) << 8) +
                (ord($buf[2]) << 16) + (ord($buf[3]) << 24));
    }

Here is the call graph for this function:

Net_Socket::readIPAddress

(

)

Reads an IP Address and returns it in a dot formatted string.

public

Returns

Dot formatted string, or a PEAR_Error if not connected.

Definition at line 457 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $buf = @fread($this->fp, 4);
        return sprintf('%d.%d.%d.%d', ord($buf[0]), ord($buf[1]),
                       ord($buf[2]), ord($buf[3]));
    }

Here is the call graph for this function:

Net_Socket::readLine

(

)

Read until either the end of the socket or a newline, whichever comes first.

Strips the trailing newline from the returned data.

public

Returns

All available data up to a newline, without that newline, or until the end of the socket, or a PEAR_Error if not connected.

Definition at line 477 of file Socket.php.

References $timeout, and PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $line = '';
        $timeout = time() + $this->timeout;
        while (!feof($this->fp) && (!$this->timeout || time() < $timeout)) {
            $line .= @fgets($this->fp, $this->lineLength);
            if (substr($line, -1) == "\n") {
                return rtrim($line, "\r\n");
            }
        }
        return $line;
    }

Here is the call graph for this function:

Net_Socket::readString

(

)

Reads a zero-terminated string of data.

public

Returns

string, or a PEAR_Error if not connected.

Definition at line 437 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $string = '';
        while (($char = @fread($this->fp, 1)) != "\x00")  {
            $string .= $char;
        }
        return $string;
    }

Here is the call graph for this function:

Net_Socket::readWord

(

)

Reads a word of data.

public

Returns

1 word of data from the socket, or a PEAR_Error if not connected.

Definition at line 402 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $buf = @fread($this->fp, 2);
        return (ord($buf[0]) + (ord($buf[1]) << 8));
    }

Here is the call graph for this function:

Net_Socket::select	(		$state,
			$tv_sec,
			$tv_usec = 0
	)

Runs the equivalent of the select() system call on the socket with a timeout specified by tv_sec and tv_usec.

Parameters

integer	$state	Which of read/write/error to check for.
integer	$tv_sec	Number of seconds for timeout.
integer	$tv_usec	Number of microseconds for timeout.

public

Returns

False if select fails, integer describing which of read/write/error are ready, or PEAR_Error if not connected.

Definition at line 532 of file Socket.php.

References $fp, NET_SOCKET_ERROR, NET_SOCKET_READ, NET_SOCKET_WRITE, and PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $read = null;
        $write = null;
        $except = null;
        if ($state & NET_SOCKET_READ) {
            $read[] = $this->fp;
        }
        if ($state & NET_SOCKET_WRITE) {
            $write[] = $this->fp;
        }
        if ($state & NET_SOCKET_ERROR) {
            $except[] = $this->fp;
        }
        if (false === ($sr = stream_select($read, $write, $except, $tv_sec, $tv_usec))) {
            return false;
        }

        $result = 0;
        if (count($read)) {
            $result |= NET_SOCKET_READ;
        }
        if (count($write)) {
            $result |= NET_SOCKET_WRITE;
        }
        if (count($except)) {
            $result |= NET_SOCKET_ERROR;
        }
        return $result;
    }

Here is the call graph for this function:

Net_Socket::setBlocking

(

$mode

)

Sets whether the socket connection should be blocking or not.

A read call to a non-blocking socket will return immediately if there is no data available, whereas it will block until there is data for blocking sockets.

Parameters

boolean

$mode

True for blocking sockets, false for nonblocking. public

Returns

mixed true on success or a PEAR_Error instance otherwise

Definition at line 203 of file Socket.php.

References PEAR\raiseError().

Referenced by connect().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $this->blocking = $mode;
        socket_set_blocking($this->fp, $this->blocking);
        return true;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

Net_Socket::setTimeout	(		$seconds,
			$microseconds
	)

Sets the timeout value on socket descriptor, expressed in the sum of seconds and microseconds.

Parameters

integer	$seconds	Seconds.
integer	$microseconds	Microseconds. public

Returns

mixed true on success or a PEAR_Error instance otherwise

Definition at line 223 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return socket_set_timeout($this->fp, $seconds, $microseconds);
    }

Here is the call graph for this function:

Net_Socket::setWriteBuffer

(

$size

)

Sets the file buffering size on the stream.

See php's stream_set_write_buffer for more information.

Parameters

integer

$size

Write buffer size. public

Returns

mixed on success or an PEAR_Error object otherwise

Definition at line 240 of file Socket.php.

References PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        $returned = stream_set_write_buffer($this->fp, $size);
        if ($returned == 0) {
            return true;
        }
        return $this->raiseError('Cannot set write buffer.');
    }

Here is the call graph for this function:

Net_Socket::write	(		$data,
			$blocksize = null
	)

Write a specified amount of data.

Parameters

string	$data	Data to write.
integer	$blocksize	Amount of data to write at once. NULL means all at once.

public

Returns

mixed If the socket is not connected, returns an instance of PEAR_Error If the write succeeds, returns the number of bytes written If the write fails, returns false.

Definition at line 324 of file Socket.php.

References $data, $pos, and PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        if (is_null($blocksize) && !OS_WINDOWS) {
            return @fwrite($this->fp, $data);
        } else {
            if (is_null($blocksize)) {
                $blocksize = 1024;
            }

            $pos = 0;
            $size = strlen($data);
            while ($pos < $size) {
                $written = @fwrite($this->fp, substr($data, $pos, $blocksize));
                if ($written === false) {
                    return false;
                }
                $pos += $written;
            }

            return $pos;
        }
    }

Here is the call graph for this function:

Net_Socket::writeLine

(

$data

)

Write a line of data to the socket, followed by a trailing "\r\n".

public

Returns

mixed fputs result, or an error

Definition at line 357 of file Socket.php.

References $data, and PEAR\raiseError().

    {
        if (!is_resource($this->fp)) {
            return $this->raiseError('not connected');
        }

        return fwrite($this->fp, $data . "\r\n");
    }

Here is the call graph for this function:

Field Documentation

string Net_Socket::$addr = ''

The IP address to connect to.

Definition at line 59 of file Socket.php.

Referenced by connect().

boolean Net_Socket::$blocking = true

Whether the socket is blocking.

Defaults to true.

Definition at line 47 of file Socket.php.

Referenced by isBlocking().

resource Net_Socket::$fp = null

Socket file pointer.

Definition at line 41 of file Socket.php.

Referenced by connect(), and select().

integer Net_Socket::$lineLength = 2048

Number of bytes to read at a time in readLine() and readAll().

Defaults to 2048.

Definition at line 79 of file Socket.php.

boolean Net_Socket::$persistent = false

Whether the socket is persistent.

Defaults to false.

Definition at line 53 of file Socket.php.

Referenced by connect().

integer Net_Socket::$port = 0

The port number to connect to.

Definition at line 65 of file Socket.php.

Referenced by connect().

integer Net_Socket::$timeout = false

Number of seconds to wait on socket connections before assuming there's no more data.

Defaults to no timeout.

Definition at line 72 of file Socket.php.

Referenced by connect(), and readLine().

---

The documentation for this class was generated from the following file:

• Services/PEAR/lib/Net/Socket.php