Michael Camden – Software Ninja

In my last post about Socket Programming I used socket_read to read data from a socket. In further testing I have found it to be not very stable. The same code that worked on my Mac, didn’t work on my Ubuntu desktop. So I decided to modify the read method of ClientSocket to use socket_recv instead of socket_read. socket_recv seems to be more stable then socket_read but on the flip side, it doesn’t throw the same errors.

    public function read($bufferSize = 2048) {
	if($this->link == null) {
	    throw new SocketException("Socket not connected");
	}
	if(empty($bufferSize)) {
	    $bufferSize = 2048;
	}

	$buffer = "";
	$in = "";

	if(($bytes = @socket_recv($this->link, $in, $bufferSize, MSG_DONTWAIT)) > 0) {
	    if(!empty($in)) {
		$buffer .= $in;
	    }
	}
	else if($bytes === false) {
	    throw new SocketCloseException("Connection reset unexpectedly. PHP Said " . $this->getLastError(), $this->getLastErrorNo());
	}

	return $buffer;
    }

Unlike socket_read, socket_recv returns the number of bytes that are read. socket_recv takes four parameters, the resource socket, the string buffer to hold the data in, the length of bytes to read, and a flag which determines how the data is returned. In this case, I choose to use the MSG_DONTWAIT flag, which sets the function as non-blocking, and allows you to grab the data that is sent, even if it doesn’t match the buffer size.

The other modification to the method I’ve made is only reading up to $bufferSize, instead of until the buffer has been read completely. The method described in my previous post will still work with this method.

Since the same error types are not thrown when a connection is closed unexpectedly, I’ve created a monitor for each connection. First, I created a private variable that stores a Unix timestamp.

    /**
     * The unix timestamp of the last ping attempt
     * @var integer
     */
    private $lastPing = 0;

Then I created a ping method, that sends a single byte of null data to the client. If it fails, the client is likely disconnected.

    /**
     * Executes a 'ping' request against the socket
     *
     * @return boolean
     */
    public function ping() {
	if($this->link === null) {
	    return false;
	}
	// Ping each client every 30 seconds to validate they are still alive
	if(strtotime("now") >= strtotime("30 seconds", $this->lastPing)) {
	    $this->lastPing = strtotime("now");
	    try {
		$wrote = $this->write(chr(0));
	    } catch (SocketException $e) {
		return false;
	    }
	    return $wrote;
	}
	return true;
    }

As you can see, the ping is only sent every 30 seconds. Once it is sent, the $lastPing variable is updated to the current time. chr(0) is converted to the NULL character before sent.

The last modification to the ClientSocket class is to the write method, which allows for the NULL character to be sent to the socket.

    public function write($message) {
	if($this->link == null) {
	    throw new SocketException("Socket not connected");
	}
	if(empty($message) && $message !== chr(0)) {
	    return false;
	}
	$wrote = @socket_write($this->link, $message, strlen($message));

	if($wrote === false) {
	    throw new SocketException("Failed to write to socket.\n PHP said: " . $this->getLastError());
	}

	return (strlen($message) == $wrote);
    }

Once the ClientSocket was modified, I had to change up the main loop to include the new ping method.

		if(!$child->ping()) {
		    // Child socket closed unexpectedly, remove from active
		    // threads
		    echo "Terminating zombie thread at $index\n";
		    unset($this->threads[$index]);
		    continue;
		}

And the whole method…

    /**
     * After calling this method, the Socket will start to listen on the port
     * specified or the default port.
     *
     * @see Socket::$port
     * @param string $host
     * @param int $port
     */
    public function listen($host = "localhost", $port = 9999) {
	if($this->link === null) {
	    throw new SocketException("No socket available, cannot listen");
	}

	// Set a valid port to listen on
	if($port <= 1024) {
	    $port = 9999;
	}

	socket_set_nonblock($this->link);

	// Bind to the host/port
	if(!socket_bind($this->link, $host, $port)) {
	    throw new SocketException("Cannot bind to $host:$port. PHP said, " . $this->getLastError($this->link));
	}
	// Try to listen
	if(!socket_listen($this->link)) {
	    throw new SocketException("Cannot listen on $host:$port. PHP said, " . $this->getLastError($this->link));
	}

	echo "Listening on $host:$port\n";

	$this->listening = true;
	$this->lastPing = strtotime("now");

	// Start main loop
	while($this->listening) {
	    // Accept new connections
	    if(($thread = @socket_accept($this->link)) !== false) {
		$child = new ChildSocket($thread);
		array_push($this->threads, $child);

		echo "Accepted child, " . $child->getInfo() . "\n";
	    }

	    // Loop through children, listen for read
	    foreach($this->threads as $index => $child) {
		try {
		    $msg = $child->read();
		} catch (SocketCloseException $e) {

		    // Child socket closed unexpectedly, remove from active
		    // threads
		    echo "Terminating child at $index\n";
		    unset($this->threads[$index]);
		    continue;
		}
		$msg = trim($msg);

		if($msg !== false && !empty($msg)) {
		    $command = strtolower($msg);
		    
		    switch($command) {
			case "end":
			    $this->killAll();
			    die("Kill message received\n");
			    break;
                    }
		}
		if(!$child->ping()) {
		    // Child socket closed unexpectedly, remove from active
		    // threads
		    echo "Terminating zombie thread at $index\n";
		    unset($this->threads[$index]);
		    continue;
		}
	    }
	}
    }

Download the whole thing here.

I’ve been playing a lot with PHP sockets lately, and have finally come up with a good class that I wanted to talk about. There have been a number of PHP socket programming examples, but none that I have seen that wrap all that good functionality in to a class, and many that only serve a single connection. I’ve written a class that will serve multiple connections, even from the same IP, that just makes things… well, easy.

Note:
If you haven’t read the Dev-Shed, guide to socket programming, I highly suggest you drop by there first, and read their guide.

Additional note:
This wasn’t immediately clear from the article, but this class was designed to be executed using php-cli.

Final note:
The socket class has been revised due to it not working on non-OSX platforms, please also read Socket Programming Revised.

Lets start out with the simple class definition.

class Socket {
    /**
     * Domain type to use when creating the socket
     * @var int
     */
    public $domain = AF_INET;
    /**
     * The stream type to use when creating the socket
     * @var int
     */
    public $type = SOCK_STREAM;
    /**
     * The protocol to use when creating the socket
     * @var int
     */
    public $protocol = SOL_TCP;
    
    /**
     * Stores a reference to the created socket
     * @var Resource
     */
    private $link = null;
    /**
     * Array of connected children
     * @var array
     */
    private $threads = array();
    /**
     * Bool which determines if the socket is listening or not
     * @var boolean
     */
    private $listening = false;

    /**
     * Creates a new Socket.
     *
     * @param array $args
     * @param int $args[domain] AF_INET|AF_INET6|AF_UNIX
     * @param int $args[type] SOCK_STREAM|SOCK_DGRAM|SOCK_SEQPACKET|SOCK_RAW|SOCK_UDM
     * @param int $args[protocol] SOL_TCP|SOL_UDP
     * @return Socket
     */
    public function __construct(array $args = null) {
        // Default socket info
        $defaults = array(
            "domain" => AF_INET,
            "type" => SOCK_STREAM,
            "protocol" => SOL_TCP
        );
        if($args == null) {
            $args = array();
        }
        // Merge $args in to $defaults
        $args = array_merge($defaults, $args);

        // Store these values for later, just in case
        $this->domain = $args['domain'];
        $this->type = $args['type'];
        $this->protocol = $args['protocol'];

        if(($this->link = socket_create($this->domain, $this->type, $this->protocol)) === false) {
            throw new SocketException("Unable to create Socket. PHP said, " . $this->getLastError(), socket_last_error());
        }
    }

Sort of a lot to take in. The class variables are fairly self explanatory, they hold values to use for the connection. In fact the only interesting part about this function is connecting…

        if(($this->link = socket_create($this->domain, $this->type, $this->protocol)) === false) {
            throw new SocketException("Unable to create Socket. PHP said, " . $this->getLastError(), socket_last_error());
        }

Basically what’s happening here, is we are opening a Socket on the system. On error, socket_create returns false. In this case, when it returns false, I’m just throwing an extended Exception class that I will define later, along with the error number. There are a few types of sockets that you can create, and the PHP page does a better job of explaining them then I can.

Here is that custom exception class;

class SocketException extends Exception {
    private $logPath = "/var/log/php/socket.log";
    public function __construct($message = "", $code = 0) {
        if(file_exists("/var/log")) {
            if(!file_exists(dirname($this->logPath))) {
                $success = @mkdir(dirname($this->logPath));

                if(!$success) {
                    $message .= "\n";
                    $message .= "Unable to log error, check log path.\n";
                }
            }

            @error_log($message, 3, $this->logPath);
        }

        parent::__construct($message, $code);
    }
}
class SocketCloseException extends SocketException {
    public function __construct($message = "", $code = 0) {
        parent::__construct($message, $code);
    }
}

As you can see, all it really does it attempt to log the error if /var/log/ exists. I just like to use a custom exception class, because I can narrow down the error more easily that way.

The other function in the constructor was, getLastError(). In order to get the socket error as a string, you have to wrap the error number function socket_last_error with socket_strerror.

    /**
     * Returns the last error on the socket specified. If no socket is specified
     * the last error that occured is returned.
     * 
     * @param Resource $socket 
     * @return string
     */
    public function getLastError($socket = null) {
        if(empty($socket)) {
            return socket_strerror(socket_last_error());
        }
        else {
            return socket_strerror(socket_last_error($socket));
        }
    }

This method just wraps both together, so that I don’t have to do it all the time. I also included a $socket parameter, so if I wanted to get errors from connected sockets, I can do that too.

Now that I have a way to open the socket, I need a way to close the socket. For that I utilize the default __destruct method, as well as a close method.

    /**
     * At destruct, close the socket
     */
    public function __destruct() {
        @$this->close();
    }

    /**
     * Closes the listening socket
     * 
     * @return void
     */
    public function close() {
        $this->listening = false;

        // @see http://www.php.net/manual/en/function.socket-close.php#66810
        $socketOptions = array('l_onoff' => 1, 'l_linger' => 0);
        socket_set_option($this->link, SOL_SOCKET, SO_LINGER, $socketOptions);

        socket_close($this->link);
    }

__destruct just calls the close method, this makes sure that I am closing the socket even if something unexpected happens. The close method has some interesting stuff going on. Of course I call the socket_close function to close off the listening socket, but I also set listening to false to stop the main listening loop, and set a few options. By default, PHP will keep a connection open even after you call socket_close. PHP keeps the connection alive to make sure that any data sent through the socket isn’t abruptly cutoff. For my purposes I didn’t need this functionality, so by setting these options I’m telling PHP to immediately cut off the connection.

Two more methods before the main listen loop, send and killAll.

    /**
     * Sends a message to a child. Set child as "all" to send to all children.
     * 
     * @param string $message
     * @return void
     */
    public function send($child, $message) {
        if($this->link === null) {
            throw new SocketException("Socket not connected");
        }
        if(empty($message)) {
            return;
        }
        if(is_string($child) && strcasecmp($child, "all") === 0) {
            foreach($this->threads as $thread) {
                $thread->write($message . "\n");
            }
        }
        else {
            $child->write($message . "\n");
        }
    }
    /**
     * Terminates all active child connections
     * 
     * @return void;
     */
    public function killAll() {
        foreach($this->threads as $child) {
            $child->close();
        }
        $this->listening = false;
        $this->close();
    }

`send`, accesses the write method of the specified child to send a message through the socket to the connected child. It uses the socket_write function to send the message. I also wrote in the ability to send, ‘all’ as the child, to send a message to all connected children.

`killAll`, accesses the close method of all connected children, and the Socket. The close method mirrors the close method of the Socket class.

And now for the main event… the listen loop.

    /**
     * After calling this method, the Socket will start to listen on the port
     * specified or the default port. 
     * 
     * @param string $host
     * @param int $port 
     */
    public function listen($host = "localhost", $port = 9999) {
        if($this->link === null) {
            throw new SocketException("No socket available, cannot listen");
        }
        
        // Set a valid port to listen on
        if($port <= 1024) {
            $port = 9999;
        }

        socket_set_nonblock($this->link);

So the first thing we do is validate the socket is connected, and that we are listening on a port that isn’t reserved by the system (1-1024 are reserved). The next function to call is socket_set_nonblock. This makes the newly created socket, non-blocking, which means that when a connection comes in, the system can handle that connection, instead of queueing the connection until the current connection is disconnected. That all means that we can serve multiple connections at the same time.

        // Bind to the host/port
        if(!socket_bind($this->link, $host, $port)) {
            throw new SocketException("Cannot bind to $host:$port. PHP said, " . $this->getLastError($this->link));
        }
        // Try to listen
        if(!socket_listen($this->link)) {
            throw new SocketException("Cannot listen on $host:$port. PHP said, " . $this->getLastError($this->link));
        }

        echo "Listening on $host:$port\n";

        $this->listening = true;

The first thing we need to is reserve a connection to the host, and port specified, and bind that to the socket we created. This is accomplished with socket_bind. The next step is to start listening on the socket, using socket_listen. If all went well, echo that the socket is listening, and set the listening bool to true.

        // Start main loop
        while($this->listening) {
            // Accept new connections
            if(($thread = @socket_accept($this->link)) !== false) {
                $child = new ChildSocket($thread);
                array_push($this->threads, $child);

                echo "Accepted child, " . $child->getInfo() . "\n";
            }

Now that we are bound, and listening, we start the main loop. The first thing to do is check if an incoming connection request has been made. If so, a new Socket Resource is returned from socket_accept, if not, false is returned. Once the connection has been accepted, we wrap the connection resource in the ChildSocket class I’ll define later, then add that object to the child threads array. Finally echo that we have accepted a new connection.

            // Loop through children, listen for read
            foreach($this->threads as $index => $child) {
                try {
                    $msg = $child->read();
                } catch (SocketCloseException $e) {
                    // Child socket closed unexpectedly, remove from active
                    // threads

                    echo "Terminating child at $index\n";
                    unset($this->threads[$index]);
                    continue;
                }

The next step in the loop, is to iterate through all the child connections and look for a message that has been sent by the client. The read method of the ChildSocket class has a chance to throw the SocketCloseException we defined earlier. If that is thrown, we know the child socket has been closed unexpectedly. An unexpected close can mean a lot of things, in most cases though we are talking about someone closing the terminal window after connecting. So if that exception is thrown, we echo a message to the server, and remove the thread from the active threads array.

                $msg = trim($msg);
                
                if($msg !== false && !empty($msg)) {
                    $command = strtolower($msg);
                    switch($command) {
                        case "end":
                            $this->killAll();
                            die("Kill message received\n");
                        break;
                    }
                    echo "Received message: $msg\n";

                    $this->send($child, "You said: $msg\n");
                }
            }
        }

The next thing we do is trim up the message, that’ll drop any extra spaces and the \r\n attached at the end of a message. After a quick message validation we check for specific commands that are sent. In this case I’m looking for the stand alone word, ‘end’. This command will close out all the connections, and terminate the program. If that command isn’t issued the message sent will be echo’d out to the server, and sent back to the child.

The last thing I’ll go over is the ChildSocket class. As we saw earlier, this class is created when a new connection is created on the server.

class ChildSocket {
    /**
     * Stores a reference to the created socket
     * @var Resource
     */
    private $link = null;
    
    /**
     * Connection reset by peer error number
     * @var int
     */
    const PEER_RESET = 104;

    public function __construct($thread = null) {
        if($thread === null || !is_resource($thread)) {
            throw new SocketException("No socket available, cannot create Child");
        }
        $this->link = $thread;
    }

Fairly simple to start, just take the socket resource that was passed and store it in the link class variable. I’ve set a class constant, PEER_RESET as the error number that is returned when someone just exits terminal.

    /**
     * Sends a message to the socket
     * 
     * @param string $message
     * @return boolean
     */
    public function write($message) {
        if($this->link == null) {
            throw new SocketException("Socket not connected");
        }
        if(empty($message)) {
            return false;
        }
        $wrote = socket_write($this->link, $message, strlen($message));

        if($wrote === false) {
            throw new SocketException("Failed to write to socket.\n PHP said: " . $this->getLastError());
        }

        return (strlen($message) == $wrote);
    }

The write method accesses the socket_write function to send the string, $message, to the connected client.

    /**
     * Reads from the Socket, returns false if there is nothing to read
     * 
     * @param int $bufferSize 
     * @return mixed
     */
    public function read($bufferSize = 1024) {
        if($this->link == null) {
            throw new SocketException("Socket not connected");
        }
        if(empty($bufferSize)) {
            $bufferSize = 1024;
        }

        $buffer = false;
        do {
            $in = "";
            $in = @socket_read($this->link, $bufferSize);

            // Connection reset
            if($this->getLastErrorNo() == self::PEER_RESET) {
                throw new SocketCloseException("Connection reset by peer");
                break;
            }

            if(!empty($in)) {
                if($buffer === false) {
                    $buffer = "";
                }
                $buffer .= $in;
            }
            // Socket error, close
            else if($in === '') {
                throw new SocketCloseException("Socket closed unexpectedly");
                break;
            }
        } while(!empty($in));

        /**
         * Sometimes when the connection is closed unexpectedly, like
         * if someone presses the exit button in the window, a series of
         * question marks (?) are sent as binary characters to the server. 
         * Converting them to hex, returns 04 then to ASCII returns (?); So,
         * if the returned buffer is not false, and the resulting text is only
         * made up of ?'s then kill the buffer.
         */

        if($buffer !== false) {
            $tmp = bin2hex($buffer);
            if(($cnt = preg_match_all("/(04)/", $tmp, $matches)) > 0 && $cnt*2 == strlen($tmp)) {
                $buffer = false;
            }
        }
        
        return $buffer;
    }

The read method uses the socket_read function to read data from the socket. We start by grabbing the buffer in small 1024 byte size chunks. Basically I just created a loop that stores data grabbed from socket_read, in to the $buffer variable. After we call socket_read, we validate that the connection reset error hasn’t occurred. Another sort of tricky error associated with a connection reset by peer, is if the socket_read is returned as equal to, ”. If no data is returned by socket_read, false is returned. Finally, some times when the connection reset by peer error occurs, binary characters are sent to the server. The string that comes through, will have no data, but be of a length between 1 and the $bufferSize variable. A var_dump of message received would look something like,

string(597) ""

In order to catch for this error, I’ve converted the binary message to hexadecimal, which returns a series of “04″ characters. The next step was to validate that the entire string consists of the 04 or in ASCII, “?” character, and set the buffer to false.

    /**
     * At destruct, close the socket
     */
    public function __destruct() {
        @$this->close();
    }
    /**
     * Closes the socket
     * 
     * @return void
     */
    public function close() {
        // @see http://www.php.net/manual/en/function.socket-close.php#66810
        $socketOptions = array('l_onoff' => 1, 'l_linger' => 0);
        @socket_set_option($this->link, SOL_SOCKET, SO_LINGER, $socketOptions);
        @socket_close($this->link);
    }
    /**
     * Returns a string which contains the connection info
     *
     * @return string
     */
    public function getInfo() {
        $IP = "0.0.0.0";
        $port = 0;
        
        if($this->link == null) {
            throw new SocketException("Socket not connected");
        }
        
        socket_getsockname($this->link, $IP, $port);
        
        return "IP: $IP:$port";
    }
    /**
     * Returns the last error number
     * 
     * @return int
     */
    public function getLastErrorNo() {
        return socket_last_error($this->link);
    }
    /**
     * Returns the last error this socket has received
     *
     * @return string
     */
    public function getLastError() {
        return socket_strerror(socket_last_error($this->link));
    }

Here we have the same destruct, close, and getLastError methods as Socket. I separated out getLastErrorNo, because I needed to check against the actual error number. The other method here is getInfo, which returns some information about the socket. socket_getsockname is a really strange function. It sets $IP and $port by reference instead of returning them, which doesn’t make any sense to me.

Anyhow that wraps up this post. If you wish to download the whole class, click here.