Merge pull request #24 from ratchetphp/doc-n-functions

Shortcuts and documentation

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2014 Chris Boden
+Copyright (c) 2015 Chris Boden
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,9 +1,29 @@
 #Pawl
 
+[![Autobahn Testsuite](https://img.shields.io/badge/Autobahn-passing-brightgreen.svg)](http://socketo.me/reports/pawl/index.html)
+
 An asynchronous PHP WebSocket client
 
 ---
+Using Pawl as a standalone app: Connect to an echo server, send a message, display output back, close connection.
+```php
+<?php
+
+    require __DIR__ . '/vendor/autoload.php';
+
+    \Ratchet\Client\connect('ws://echo.socketo.me:9000')->then(function($conn) {
+        $conn->on('message', function($msg) use ($conn) {
+            echo "Received: {$msg}\n";
+            $conn->close();
+        });
 
+        $conn->send('Hello World!');
+    }, function ($e) {
+        echo "Could not connect: {$e->getMessage()}\n";
+    });
+```
+
+Using the components of Pawl: Requesting sub-protocols, and sending custom headers while using a specific React Event Loop.
 ```php
 <?php
 
@@ -12,13 +32,19 @@ An asynchronous PHP WebSocket client
     $loop = React\EventLoop\Factory::create();
     $connector = new Ratchet\Client\Connector($loop);
 
-    $connector('ws://127.0.0.1:8080')->then(function(Ratchet\Client\WebSocket $conn) {
-        $conn->on('message', function($msg) {
+    $connector('ws://127.0.0.1:9000', ['protocol1', 'subprotocol2'], ['Origin' => 'http://localhost'])
+    ->then(function(Ratchet\Client\WebSocket $conn) {
+        $conn->on('message', function(\Ratchet\RFC6455\Messaging\MessageInterface $msg) use ($conn) {
             echo "Received: {$msg}\n";
+            $conn->close();
+        });
+
+        $conn->on('close', function($code = null, $reason = null) {
+            echo "Connection closed ({$code} - {$reason})\n";
         });
 
         $conn->send('Hello World!');
-    }, function($e) use ($loop) {
+    }, function(\Exception $e) use ($loop) {
         echo "Could not connect: {$e->getMessage()}\n";
         $loop->stop();
     });

composer.json

@@ -1,17 +1,18 @@
 {
     "name": "ratchet/pawl"
   , "description": "Asynchronous WebSocket client"
-  , "keywords": ["WebSocket", "client", "Ratchet", "async"]
+  , "keywords": ["WebSocket", "client", "Ratchet", "async", "websocket client"]
   , "license": "MIT"
   , "autoload": {
         "psr-4": {
             "Ratchet\\Client\\": "src"
         }
+      , "files": ["src/functions_include.php"]
     }
   , "require": {
         "php": ">=5.4"
       , "react/socket-client": "0.4.*"
-      , "ratchet/rfc6455": "0.2.*"
+      , "ratchet/rfc6455": "^0.2.1"
     }
 
 }

src/Connector.php

@@ -29,6 +29,12 @@ public function __construct(LoopInterface $loop, Resolver $resolver = null) {
         $this->_negotiator      = new ClientNegotiator;
     }
 
+    /**
+     * @param string $url
+     * @param array  $subProtocols
+     * @param array  $headers
+     * @return \React\Promise\PromiseInterface
+     */
     public function __invoke($url, array $subProtocols = [], array $headers = []) {
         try {
             $request = $this->generateRequest($url, $subProtocols, $headers);
@@ -92,6 +98,12 @@ public function __invoke($url, array $subProtocols = [], array $headers = []) {
         });
     }
 
+    /**
+     * @param string $url
+     * @param array  $subProtocols
+     * @param array  $headers
+     * @return \Psr\Http\Message\RequestInterface
+     */
     protected function generateRequest($url, array $subProtocols, array $headers) {
         $uri = gPsr\uri_for($url);
 

src/WebSocket.php

@@ -42,7 +42,7 @@ class WebSocket implements EventEmitterInterface {
      * @param \Psr\Http\Message\ResponseInterface $response
      * @param \Psr\Http\Message\RequestInterface  $request
      * @event message
-     * @event end
+     * @event pong
      * @event close
      * @event error
      */

src/functions.php

@@ -0,0 +1,24 @@
+<?php
+namespace Ratchet\Client;
+use React\EventLoop\LoopInterface;
+use React\EventLoop\Factory as ReactFactory;
+
+/**
+ * @param string             $url
+ * @param array              $subProtocols
+ * @param array              $headers
+ * @param LoopInterface|null $loop
+ * @return \React\Promise\PromiseInterface
+ */
+function connect($url, array $subProtocols = [], $headers = [], LoopInterface $loop = null) {
+    $loop = $loop ?: ReactFactory::create();
+
+    $connector = new Connector($loop);
+    $connection = $connector($url, $subProtocols, $headers);
+
+    register_shutdown_function(function() use ($loop) {
+        $loop->run();
+    });
+
+    return $connection;
+}

src/functions_include.php

@@ -0,0 +1,5 @@
+<?php
+
+if (!function_exists('Ratchet\Client\connect')) {
+    require __DIR__ . '/functions.php';
+}