Initial commit

README.md

@@ -0,0 +1,63 @@
+# Protocol Base for ReactPHP
+
+Use this library to build protocols. It doesn't do any single protocol to any greater
+extent, but it provides callbacks and scaffolding for you to build and stream most
+protocol data.
+
+## About the protocols
+
+This library is intended to be generic, so only protocols that have no external
+dependencies will be included. 
+
+## Using
+
+### Protocols
+
+```php
+// Basic line-oriented protocol, think shell or SMTP
+$proto = new LineProtocol($stream, [
+    'lineSeparator' => "\n",
+    'fieldSeparator' => " ",
+    'fieldQuote' => '"',
+]);
+
+// encode your frames and send it however you desire
+$data = $proto->packFrame([ "mv", "foo.txt", "bar.txt" ]);
+// → mv foo.txt bar.txt\n
+
+// Or use JSON if you so desire
+$proto = new JsonProtocol($stream, [
+    'frameSeparator' => "\0",
+]);
+$data = $proto->packFrame([ 'foo' => 'bar' ]);
+// → {"foo":"bar"}\0
+```
+
+Unpacking works as expected:
+
+```php
+$proto = new LineProtocol($stream, [
+    'lineSeparator' => "\n",
+    'fieldSeparator' => " ",
+    'fieldQuote' => '"',
+]);
+
+// encode your frames and send it however you desire
+$cmdline = $proto->unpackFrame("mv foo.txt bar.txt\n" ]);
+// → [ "mv", "foo.txt", "bar.txt" ]
+```
+
+### Protocols with ProtocolStream
+
+ProtocolStream combines a ProtocolInterface and a DuplexStreamInterface into
+one package. It will emit an `message` event when a new frame has been
+decoded, an `error` event if something goes wrong, and an `overflow` event
+if the buffer overflows a configured max size.
+
+```php
+$stream = new ProtocolStream($proto, $someduplexstream);
+$stream->on("message", function (array $message) {
+    // ...
+});
+$stream->send([ 'data' => 'here' ]);
+```