API documentation

lib/Ratchet/Command/CloseConnection.php

@@ -2,7 +2,13 @@
 namespace Ratchet\Command;
 use Ratchet\SocketCollection;
 
+/**
+ * Close the connection to the sockets passed in the constructor
+ */
 class CloseConnection implements CommandInterface {
+    /**
+     * @var SocketCollection
+     */
     protected $_sockets;
 
     public function __construct(SocketCollection $sockets) {
@@ -10,6 +16,8 @@ class CloseConnection implements CommandInterface {
     }
 
     function execute() {
-        $this->_sockets->close();
+        foreach ($this->_sockets as $socket) {
+            $socket->close();
+        }
     }
 }

lib/Ratchet/Command/CommandInterface.php

@@ -2,8 +2,18 @@
 namespace Ratchet\Command;
 use Ratchet\SocketCollection;
 
+/**
+ * Socket implementation of the Command Pattern
+ * User created applications are to return a Command to the server for execution
+ */
 interface CommandInterface {
+    /**
+     * Pass the Sockets to execute the command on
+     */
     function __construct(SocketCollection $sockets);
 
+    /**
+     * The Server class will call the execution
+     */
     function execute();
 }

lib/Ratchet/Command/Null.php

@@ -2,6 +2,9 @@
 namespace Ratchet\Command;
 use Ratchet\SocketCollection;
 
+/**
+ * Null pattern - execution does nothing, something needs to be passed back though
+ */
 class Null implements CommandInterface {
     public function __construct(SocketCollection $sockets) {
     }

lib/Ratchet/Command/SendMessage.php

@@ -2,22 +2,43 @@
 namespace Ratchet\Command;
 use Ratchet\SocketCollection;
 
+/**
+ * Send text back to the client end of the socket(s)
+ */
 class SendMessage implements CommandInterface {
+    /**
+     * @var SocketCollection
+     */
     protected $_sockets;
+
+    /**
+     * @var string
+     */
     protected $_message = '';
 
     public function __construct(SocketCollection $sockets) {
         $this->_sockets = $sockets;
     }
 
+    /**
+     * The message to send to the socket(s)
+     * @param string
+     */
     public function setMessage($msg) {
         $this->_message = (string)$msg;
     }
 
+    /**
+     * Get the message from setMessage()
+     * @return string
+     */
     public function getMessage() {
         return $this->_message;
     }
 
+    /**
+     * @throws \UnexpectedValueException if a message was not set with setMessage()
+     */
     public function execute() {
         if (empty($this->_message)) {
             throw new \UnexpectedValueException("Message is empty");

lib/Ratchet/Exception.php

@@ -1,6 +1,9 @@
 <?php
 namespace Ratchet;
 
+/**
+ * Uses internal php methods to fill an Exception class (no parameters required)
+ */
 class Exception extends \Exception {
     public function __construct() {
         $int = socket_last_error();

lib/Ratchet/Logging/LoggerInterface.php

@@ -1,18 +1,24 @@
 <?php
 namespace Ratchet\Logging;
 
+/**
+ * A logger used by the server and extending applications for debugging info
+ */
 interface LoggerInterface {
     /**
+     * Just an informational log
      * @param string
      */
     function note($msg);
 
     /**
+     * A problem, but nothing too serious
      * @param string
      */
     function warning($msg);
 
     /**
+     * Bad things have happened...
      * @param string
      */
     function error($msg);

lib/Ratchet/Logging/MonologAdapter.php

@@ -2,6 +2,9 @@
 namespace Ratchet\Logging;
 use Monolog\Logger;
 
+/**
+ * Adapt the awesome Monolog Logger into the lowly Ratchet Logger
+ */
 class MonologAdapter extends Logger implements LoggerInterface {
     /**
      * Maps to Monolog\Logger::addInfo

lib/Ratchet/Logging/NullLogger.php

@@ -1,6 +1,10 @@
 <?php
 namespace Ratchet\Logging;
 
+/**
+ * Sends all logs into the void
+ * No one can hear you scream in /dev/null
+ */
 class NullLogger implements LoggerInterface {
     function note($msg) {
     }

lib/Ratchet/Protocol/WebSocket.php

@@ -7,6 +7,8 @@ use Ratchet\SocketInterface;
 use Ratchet\ReceiverInterface;
 
 /**
+ * The adapter to handle WebSocket requests/responses
+ * This is a mediator between the Server and your application to handle real-time messaging through a web browser
  * @link http://ca.php.net/manual/en/ref.http.php
  * @todo Make sure this works both ways (client/server) as stack needs to exist on client for framing
  * @todo Clean up Client/Version stuff.  This should be a factory making single instances of Version classes, implement chain of reponsibility for version - client should implement an interface?

lib/Ratchet/Protocol/WebSocket/AppInterface.php

@@ -1,5 +1,5 @@
 <?php
-namespace Ratchet\Protocol\Websocket;
+namespace Ratchet\Protocol\WebSocket;
 use Ratchet\ReceiverInterface;
 
 /**

lib/Ratchet/Protocol/WebSocket/Client.php

@@ -2,19 +2,22 @@
 namespace Ratchet\Protocol\WebSocket;
 use Ratchet\Protocol\WebSocket\Version\VersionInterface;
 
+/**
+ * A representation of a Socket connection of the user on the other end of the socket
+ */
 class Client {
     /**
-     * @type Ratchet\Protocol\WebSocket\Version\VersionInterface
+     * @var Ratchet\Protocol\WebSocket\Version\VersionInterface
      */
     protected $_version = null;
 
     /**
-     * @type bool
+     * @var bool
      */
     protected $_hands_shook = false;
 
     /**
-     * @param VersionInterface
+     * @param Version\VersionInterface
      * @return Client
      */
     public function setVersion(VersionInterface $version) {
@@ -23,7 +26,7 @@ class Client {
     }
 
     /**
-     * @return VersionInterface
+     * @return Version\VersionInterface
      */
     public function getVersion() {
         return $this->_version;

lib/Ratchet/Protocol/WebSocket/Version/Hixie76.php

@@ -1,6 +1,10 @@
 <?php
 namespace Ratchet\Protocol\WebSocket\Version;
 
+/**
+ * The Hixie76 is currently implemented by Safari
+ * Not yet complete
+ */
 class Hixie76 implements VersionInterface {
     public function handshake(array $headers) {
     }

lib/Ratchet/Protocol/WebSocket/Version/Hybi10.php

@@ -1,11 +1,13 @@
 <?php
 namespace Ratchet\Protocol\WebSocket\Version;
 
+/**
+ * The HyBi-10 version, identified in the headers as version 8, is currently implemented by the latest Chrome and Firefix version
+ * @link http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10
+ */
 class Hybi10 implements VersionInterface {
     const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 
-    /**
-     */
     public function handshake(array $headers) {
         $key = $this->sign($headers['Sec-Websocket-Key']);
 

lib/Ratchet/Protocol/WebSocket/Version/VersionInterface.php

@@ -1,6 +1,10 @@
 <?php
 namespace Ratchet\Protocol\WebSocket\Version;
 
+/**
+ * Despite the version iterations of WebInterface the actions they go through are similar
+ * This standardizes how the server handles communication with each protocol version
+ */
 interface VersionInterface {
     /**
      * Perform the handshake and return the response headers

lib/Ratchet/ReceiverInterface.php

@@ -4,6 +4,7 @@ use Ratchet\Server;
 use Ratchet\SocketObserver;
 
 /**
+ * Decorator interface for internal protocols
  * @todo Should probably move this into \Ratchet\Server namespace
  */
 interface ReceiverInterface extends SocketObserver {

lib/Ratchet/Server.php

@@ -6,6 +6,7 @@ use Ratchet\Logging\LoggerInterface;
 use Ratchet\Logging\NullLogger;
 
 /**
+ * Creates an open-ended socket to listen on a port for incomming connections.  Events are delegated through this to attached applications
  * @todo Consider using _connections as master reference and passing iterator_to_array(_connections) to socket_select
  * @todo Move SocketObserver methods to separate class, create, wrap class in __construct
  * @todo Currently passing Socket object down the decorated chain - should be sending reference to it instead; Receivers do not interact with the Socket directly, they do so through the Command pattern
@@ -48,7 +49,6 @@ class Server implements SocketObserver, \IteratorAggregate {
     /**
      * @param Ratchet\Socket
      * @param ReceiverInterface
-     * @param boolean True, enables debug mode and the server doesn't infiniate loop
      * @param Logging\LoggerInterface
      */
     public function __construct(SocketInterface $host, ReceiverInterface $application, LoggerInterface $logger = null) {
@@ -128,8 +128,8 @@ class Server implements SocketObserver, \IteratorAggregate {
     }
 
     /*
-     * @param mixed
-     * @param int
+     * @param mixed The address to listen for incoming connections on.  "0.0.0.0" to listen from anywhere
+     * @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?

lib/Ratchet/ServerInterface.php

@@ -1,6 +1,9 @@
 <?php
 namespace Ratchet;
 
+/**
+ * @deprecated
+ */
 interface ServerInterface extends \IteratorAggregate {
     function attatchReceiver(ReceiverInterface $receiver);
 

lib/Ratchet/SocketCollection.php

@@ -1,12 +1,17 @@
 <?php
 namespace Ratchet;
 
+/**
+ * A self-deprecating queue that can only hold Socket objects
+ */
 class SocketCollection extends \SplQueue {
     public function __construct() {
-//        parent::__construct();
         $this->setIteratorMode(static::IT_MODE_DELETE);
     }
 
+    /**
+     * @param SocketInterface
+     */
     public function enqueue(SocketInterface $value) {
         parent::enqueue($value);
     }

lib/Ratchet/SocketInterface.php

@@ -1,19 +1,27 @@
 <?php
 namespace Ratchet;
 
+/**
+ * An object-oriented container for a single socket connection
+ */
 interface SocketInterface {
     /**
+     * Send text to the client on the other end of the socket
      * @param string
      * @param int
      */
     function write($buffer, $length = 0);
 
     /**
+     * Called when the client sends data to the server through the socket
      * @param string
      * @param int
      * @param int
      */
     function recv(&$buf, $len, $flags);
 
+    /**
+     * Close the open connection to the client/socket
+     */
     function close();
 }

lib/Ratchet/SocketObserver.php

@@ -1,19 +1,25 @@
 <?php
 namespace Ratchet;
 
+/**
+ * Observable/Observer design pattern interface for handing events on a socket
+ */
 interface SocketObserver {
     /**
+     * When a new connection is opened it will be passed to this method
      * @param SocketInterface
      */
     function onOpen(SocketInterface $conn);
 
     /**
+     * Triggered when a client sends data through the socket
      * @param SocketInterface
      * @param string
      */
     function onRecv(SocketInterface $from, $msg);
 
     /**
+     * This is called just before the connection is closed
      * @param SocketInterface
      */
     function onClose(SocketInterface $conn);