From c8a09114524f715f1682afa6a811831ccea2516b Mon Sep 17 00:00:00 2001 From: Chris Boden Date: Tue, 8 Nov 2011 12:20:18 -0500 Subject: [PATCH] API Documentation --- lib/Ratchet/Command/Action/CloseConnection.php | 2 +- lib/Ratchet/Command/ActionInterface.php | 3 +++ lib/Ratchet/Protocol/WebSocket.php | 1 + lib/Ratchet/Server.php | 4 ---- lib/Ratchet/SocketObserver.php | 13 +++++++------ 5 files changed, 12 insertions(+), 11 deletions(-) diff --git a/lib/Ratchet/Command/Action/CloseConnection.php b/lib/Ratchet/Command/Action/CloseConnection.php index 391e857..92194f6 100644 --- a/lib/Ratchet/Command/Action/CloseConnection.php +++ b/lib/Ratchet/Command/Action/CloseConnection.php @@ -11,6 +11,7 @@ use Ratchet\Command\Composite; */ class CloseConnection extends ActionTemplate { function execute(SocketObserver $scope = null) { + // All this code allows an application to have its onClose method executed before the socket is actually closed $ret = $scope->onClose($this->getSocket()); if ($ret instanceof CommandInterface) { @@ -21,7 +22,6 @@ class CloseConnection extends ActionTemplate { $rt->setCommand(function(SocketInterface $socket, SocketObserver $scope) { $socket->close(); }); - $comp->enqueue($rt); return $comp; diff --git a/lib/Ratchet/Command/ActionInterface.php b/lib/Ratchet/Command/ActionInterface.php index be675c9..bccae43 100644 --- a/lib/Ratchet/Command/ActionInterface.php +++ b/lib/Ratchet/Command/ActionInterface.php @@ -2,6 +2,9 @@ namespace Ratchet\Command; use Ratchet\SocketInterface; +/** + * A single command tied to 1 socket connection + */ interface ActionInterface extends CommandInterface { /** * Pass the Sockets to execute the command on diff --git a/lib/Ratchet/Protocol/WebSocket.php b/lib/Ratchet/Protocol/WebSocket.php index 22edec3..1713569 100644 --- a/lib/Ratchet/Protocol/WebSocket.php +++ b/lib/Ratchet/Protocol/WebSocket.php @@ -16,6 +16,7 @@ use Ratchet\Protocol\WebSocket\Util\HTTP; * @todo Make sure this works both ways (client/server) as stack needs to exist on client for framing * @todo Learn about closing the socket. A message has to be sent prior to closing - does the message get sent onClose event or CloseConnection command? * @todo Consider cheating the application...don't call _app::onOpen until handshake is complete - only issue is sending headers/cookies + * @todo Consider chaning this class to a State Pattern. If a SocketObserver is passed in __construct, do what is there now. If it's an AppInterface change behaviour of socket interaction (onOpen, handshake, etc) */ class WebSocket implements ProtocolInterface { /** diff --git a/lib/Ratchet/Server.php b/lib/Ratchet/Server.php index a7cc61c..5ad6802 100644 --- a/lib/Ratchet/Server.php +++ b/lib/Ratchet/Server.php @@ -71,7 +71,6 @@ class Server implements SocketObserver, \IteratorAggregate { * @param int The port to listen to connections on * @throws Exception * @todo Validate address. Use socket_get_option, if AF_INET must be IP, if AF_UNIX must be path - * @todo Should I make handling open/close/msg an application? * @todo Consider making the 4kb listener changable */ public function run($address = '127.0.0.1', $port = 1025) { @@ -139,9 +138,6 @@ class Server implements SocketObserver, \IteratorAggregate { return $this->_app->onRecv($from, $msg); } - /** - * @todo Make sure it's OK to executre the command after resources have been free'd - */ public function onClose(SocketInterface $conn) { $resource = $conn->getResource(); diff --git a/lib/Ratchet/SocketObserver.php b/lib/Ratchet/SocketObserver.php index 4c8cbe8..bbb1591 100644 --- a/lib/Ratchet/SocketObserver.php +++ b/lib/Ratchet/SocketObserver.php @@ -3,28 +3,29 @@ namespace Ratchet; /** * Observable/Observer design pattern interface for handing events on a socket + * @todo Consider an onException method. Since server is running its own loop the app currently doesn't know when a problem is handled + * @todo Consider an onDisconnect method for a server-side close()'ing of a connection - onClose would be client side close() */ interface SocketObserver { /** * When a new connection is opened it will be passed to this method - * @param SocketInterface + * @param SocketInterface The socket/connection that just connected to your application * @return Ratchet\Command\CommandInterface|null */ function onOpen(SocketInterface $conn); /** * Triggered when a client sends data through the socket - * @param SocketInterface - * @param string + * @param SocketInterface The socket/connection that sent the message to your application + * @param string The message received * @return Ratchet\Command\CommandInterface|null */ function onRecv(SocketInterface $from, $msg); /** - * This is called just before the connection is closed - * @param SocketInterface + * This is called before or after a socket is closed (depends on how it's closed). SendMessage to $conn will not result in an error if it has already been closed. + * @param SocketInterface The socket/connection that is closing/closed * @return Ratchet\Command\CommandInterface|null - * @todo This is triggered if the client or server terminates the connection; consider a new onDisconnect if server triggered */ function onClose(SocketInterface $conn); } \ No newline at end of file