\Hazaar
Socket
The PHP socket extensions class

The socket class implements a low-level interface to the socket communication functions based on the popular BSD sockets, providing the possibility to act as a socket server as well as a client.

When using this class, it is important to remember that while many of them have identical names to their C counterparts, they often have different declarations. Please be sure to read the descriptions to avoid confusion.

Those unfamiliar with socket programming can find a lot of useful material in the appropriate Unix man pages, and there is a great deal of tutorial information on socket programming in C on the web, much of which can be applied, with slight modifications, to socket programming in PHP. The ยป Unix Socket FAQ might be a good start.

Tags

Since

2.0.0

Summary
Methods Properties Constants
No constants
Properties
$resource
$resource
Methods
__construct()
__construct($domain = 'af_inet', $type = 'sock_stream', $protocol = 'sol_tcp')
Socket object constructor

Parameters

$domainstring

The domain parameter specifies the protocol family to be used by the socket.

Available address/protocol families: – AF_INET IPv4 Internet based protocols. TCP and UDP are common protocols of this protocol family. – AF_INET6 IPv6 Internet based protocols. TCP and UDP are common protocols of this protocol family. – AF_UNIX Local communication protocol family. High efficiency and low overhead make it a great form of IPC (Interprocess Communication).
$typestring

The type parameter selects the type of communication to be used by the socket.

Available socket types: – SOCK_STREAM Provides sequenced, reliable, full-duplex, connection-based byte streams. An out-of-band data transmission mechanism may be supported. The TCP protocol is based on this socket type. – SOCK_DGRAM Supports datagrams (connectionless, unreliable messages of a fixed maximum length). The UDP protocol is based on this socket type. – SOCK_SEQPACKET Provides a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer is required to read an entire packet with each read call. – SOCK_RAW Provides raw network protocol access. This special type of socket can be used to manually construct any type of protocol. A common use for this socket type is to perform ICMP requests (like ping). – SOCK_RDM Provides a reliable datagram layer that does not guarantee ordering. This is most likely not implemented on your operating system.
$protocolstring

The protocol parameter sets the specific protocol within the specified domain to be used when communicating on the returned socket. The proper value can be retrieved by name by using getprotobyname(). If the desired protocol is TCP, or UDP the corresponding constants SOL_TCP, and SOL_UDP can also be used.

Common protocols: – icmp The Internet Control Message Protocol is used primarily by gateways and hosts to report errors in datagram communication. The “ping” command (present in most modern operating systems) is an example application of ICMP. – udp The User Datagram Protocol is a connectionless, unreliable, protocol with fixed record lengths. Due to these aspects, UDP requires a minimum amount of protocol overhead. – tcp The Transmission Control Protocol is a reliable, connection based, stream oriented, full duplex protocol. TCP guarantees that all data packets will be received in the order in which they were sent. If any packet is somehow lost during communication, TCP will automatically retransmit the packet until the destination host acknowledges that packet. For reliability and performance reasons, the TCP implementation itself decides the appropriate octet boundaries of the underlying datagram communication layer. Therefore, TCP applications must allow for the possibility of partial record transmission.
__destruct()
__destruct()
accept()
accept() : Socket
Accepts a connection on a socket

After the socket socket has been created using Socket::create(), bound to a name with Socket::bind(), and told to listen for connections with Socket::listen(), this function will accept incoming connections on that socket. Once a successful connection is made, a new socket resource is returned, which may be used for communication. If there are multiple connections queued on the socket, the first will be used. If there are no pending connections, Socket::accept() will block until a connection becomes present. If socket has been made non-blocking using Socket::set_blocking() or Socket::setNonblock(), FALSE will be returned. The socket resource returned by Socket::accept() may not be used to accept new connections. The original listening socket socket, however, remains open and may be reused.

Returns

\Hazaar\Socket

A new socket resource on success, or FALSE on error. The actual error code can be retrieved by calling Socket::last_error(). This error code may be passed to Socket::strerror() to get a textual explanation of the error.

bind()
bind($address, $port = 0) : boolean
Binds a name to a socket

Parameters

$address

No description

$port

No description

Returns

boolean

Returns TRUE on success or FALSE on failure.

The error code can be retrieved with Socket::lastError(). This code may be passed to Socket::strerror() to get a textual explanation of the error.
clearError()
clearError()
Clears the error on the socket or the last error code

This function clears the error code on the given socket or the global last socket error if no socket is specified. This function allows explicitly resetting the error code value either of a socket or of the extension global last error code. This may be useful to detect within a part of the application if an error occurred or not.

close()
close()
Closes a socket resource

Socket::close() closes the socket resource. This function is specific to sockets and cannot be used on any other type of resources.

cmsgSpace()
cmsgSpace($level, $type)
Calculate message buffer size

Calculates the size of the buffer that should be allocated for receiving the ancillary data.

Parameters

$level

No description

$type

No description

connect()
connect($address, $port = 0) : boolean
Initiates a connection on a socket

Parameters

$address

No description

$port

No description

Returns

boolean

Returns TRUE on success or FALSE on failure. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.

getOption()
getOption($level, $optname)
Gets socket options for the socket

The Socket::getOption() function retrieves the value for the option specified by the optname parameter for the socket.

Parameters

$level

No description

$optname

No description

getPeerName()
getPeerName($address, $port) : boolean
Queries the remote side of the given socket which may either result in host/port or in a Unix filesystem path, dependent on its type

Parameters

$address

No description

$port

No description

Returns

boolean

Returns TRUE on success or FALSE on failure. socket_getpeername() may also return FALSE if the socket type is not any of AF_INET, AF_INET6, or AF_UNIX, in which case the last socket error code is not updated.

getSockName()
getSockName($addr, $port)
Queries the local side of the given socket which may either result in host/port or in a Unix filesystem path, dependent on its type

Parameters

$addr

No description

$port

No description

lastError()
lastError() : This
Returns the last error on the socket

If a socket resource is passed to this function, the last error which occurred on this particular socket is returned. If the socket resource is omitted, the error code of the last failed socket function is returned. The latter is particularly helpful for functions like Socket::select() which can fail for reasons not directly tied to a particular socket. The error code is suitable to be fed to Socket::strerror() which returns a string describing the given error code.

Returns

\Hazaar\This

function returns a socket error code.

listen()
listen($backlog = 0) : boolean
Listens for a connection on a socket

After the socket socket has been created using socket_create() and bound to a name with Socket::bind(), it may be told to listen for incoming connections on socket.

Socket::listen() is applicable only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.

Parameters

$backlog

No description

Returns

boolean

Returns TRUE on success or FALSE on failure. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error.

read()
read($length, $type = 'php_binary_read') : mixed
Reads a maximum of length bytes from a socket

The function Socket::read() reads from the socket resource socket created by the socket_create() or socket_accept() functions.

Parameters

$length

No description

$type

No description

Returns

mixed

Socket::read() returns the data as a string on success, or FALSE on error (including if the remote host has closed the connection). The error code can be retrieved with Socket::lastError(). This code may be passed to Socket::strerror() to get a textual representation of the error.

readSelect()
readSelect($tv_sec, $tv_usec = 0) : boolean
Runs the select() system call on the socket and waits for data to be available for reading

Socket::readSelect() will execute a socket_select call on the socket and wait for data to be available for reading. This is really only useful if you are working with a single socket as it does no allow the select call to wait on multiple sockets.

Parameters

$tv_sec

No description

$tv_usec

No description

Returns

boolean

Returns TRUE if the socket had data to be read. FALSE otherwise.

recv()
recv($buf, $len, $flags) : mixed
Receives data from a connected socket

The socket_recv() function receives len bytes of data in buf from socket. socket_recv() can be used to gather data from connected sockets. Additionally, one or more flags can be specified to modify the behaviour of the function.

buf is passed by reference, so it must be specified as a variable in the argument list. Data read from socket by socket_recv() will be returned in buf.

Parameters

$buf

No description

$len

No description

$flags

No description

Returns

mixed

Socket::recv() returns the number of bytes received, or FALSE if there was an error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to Socket::strerror() to get a textual explanation of the error.

recvFrom()
recvFrom($buf, $len, $flags, $name, $port = 0) : mixed
Receives data from a socket whether or not it is connection-oriented

The Socke::recvFrom() function receives len bytes of data in buf from name on port port (if the socket is not of type AF_UNIX) using socket. Socket::recvFrom() can be used to gather data from both connected and unconnected sockets. Additionally, one or more flags can be specified to modify the behaviour of the function.

The name and port must be passed by reference. If the socket is not connection-oriented, name will be set to the internet protocol address of the remote host or the path to the UNIX socket. If the socket is connection-oriented, name is NULL. Additionally, the port will contain the port of the remote host in the case of an unconnected AF_INET or AF_INET6 socket.

Parameters

$buf

No description

$len

No description

$flags

No description

$name

No description

$port

No description

Returns

mixed

Socket::recvFrom() returns the number of bytes received, or FALSE if there was an error. The actual error code can be retrieved by calling Socket::lastError(). This error code may be passed to Socket::strerror() to get a textual explanation of the error.

recvMsg()
recvMsg($message, $flags = 0)
Read a message

This function is currently not document!

Parameters

$message

No description

$flags

No description

send()
send($buf, $len, $flags) : mixed
Sends data to a connected socket

The function socket_send() sends len bytes to the socket socket from buf.

Parameters

$buf

No description

$len

No description

$flags

No description

Returns

mixed

Socket::send() returns the number of bytes sent, or FALSE on error.

sendMsg()
sendMsg($message, $flags)
Send a message

Parameters

$message

No description

$flags

No description

sendTo()
sendTo($buf, $len, $flags, $addr, $port = 0) : mixed
Sends a message to a socket, whether it is connected or not

The function socket_sendto() sends len bytes from buf through the socket socket to the port at the address addr.

Parameters

$buf

No description

$len

No description

$flags

No description

$addr

No description

$port

No description

Returns

mixed

Socket::sendto() returns the number of bytes sent to the remote host, or FALSE if an error occurred.

setBlock()
setBlock() : boolean
Sets blocking mode on a socket resource

The socket_set_block() function removes the O_NONBLOCK flag on the socket specified by the socket parameter.

When an operation (e.g. receive, send, connect, accept, …) is performed on a blocking socket, the script will pause its execution until it receives a signal or it can perform the operation.

Returns

boolean

Returns TRUE on success or FALSE on failure.

setNonblock()
setNonblock() : boolean
Sets nonblocking mode for file descriptor fd

The socket_set_nonblock() function sets the O_NONBLOCK flag on the socket specified by the socket parameter.

When an operation (e.g. receive, send, connect, accept, …) is performed on a non-blocking socket, the script will not pause its execution until it receives a signal or it can perform the operation. Rather, if the operation would result in a block, the called function will fail.

Returns

boolean

Returns TRUE on success or FALSE on failure.

setOption()
setOption($level, $optname, $optval) : boolean
Sets socket options for the socket

The socket_set_option() function sets the option specified by the optname parameter, at the specified protocol level, to the value pointed to by the optval parameter for the socket.

Parameters

$level

No description

$optname

No description

$optval

No description

Returns

boolean

Returns TRUE on success or FALSE on failure.

shutdown()
shutdown($how = 2) : boolean
Shuts down a socket for receiving, sending, or both

The Socket::shutdown() function allows you to stop incoming, outgoing or all data (the default) from being sent through the socket

Parameters

$how

No description

Returns

boolean

Returns TRUE on success or FALSE on failure.

strerror()
strerror($errno) : string
Return a string describing a socket error

Socket::strerror() takes as its errno parameter a socket error code as returned by Socket::lastError() and returns the corresponding explanatory text.

Parameters

$errno

No description

Returns

string

Returns the error message associated with the errno parameter.

write()
write($buffer, $length = 0) : mixed
Write to a socket

The function socket_write() writes to the socket from the given buffer.

Parameters

$buffer

No description

$length

No description

Returns

mixed

Returns the number of bytes successfully written to the socket or FALSE on failure. The error code can be retrieved with Socket:lastError(). This code may be passed to Socket::strerror() to get a textual explanation of the error.

writeSelect()
writeSelect($tv_sec, $tv_usec = 0) : boolean
Runs the select() system call on the socket and waits for data to be available for writing

Socket::readSelect() will execute a socket_select call on the socket and wait for the socket to be available to write to. This is really only useful if you are working with a single socket as it does no allow the select call to wait on multiple sockets.

Parameters

$tv_sec

No description

$tv_usec

No description

Returns

boolean

Returns TRUE if the socket can be written to. FALSE otherwise.