API Documentation

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;

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

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 {
     /**

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();
 

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);
 }