Initial commit

doc/json-protos.md

@@ -0,0 +1,12 @@
+# JSON Protocols
+
+The JSON protocol simply serializes 
+
+
+
+
+## Available sub-formats
+
+### JsonRpcProtocol
+
+### NativeMessagingProtocol

doc/pack-ref.md

@@ -0,0 +1,34 @@
+# PHP pack/unpack reference
+
+| Code | Description                                                  |
+| ---- | ------------------------------------------------------------ |
+| a    | NUL-padded string                                            |
+| A    | SPACE-padded string                                          |
+| h    | Hex string, low nibble first                                 |
+| H    | Hex string, high nibble first                                |
+| c    | signed char                                                  |
+| C    | unsigned char                                                |
+| s    | signed short (always 16 bit, machine byte order)             |
+| S    | unsigned short (always 16 bit, machine byte order)           |
+| n    | unsigned short (always 16 bit, big endian byte order)        |
+| v    | unsigned short (always 16 bit, little endian byte order)     |
+| i    | signed integer (machine dependent size and byte order)       |
+| I    | unsigned integer (machine dependent size and byte order)     |
+| l    | signed long (always 32 bit, machine byte order)              |
+| L    | unsigned long (always 32 bit, machine byte order)            |
+| N    | unsigned long (always 32 bit, big endian byte order)         |
+| V    | unsigned long (always 32 bit, little endian byte order)      |
+| q    | signed long long (always 64 bit, machine byte order)         |
+| Q    | unsigned long long (always 64 bit, machine byte order)       |
+| J    | unsigned long long (always 64 bit, big endian byte order)    |
+| P    | unsigned long long (always 64 bit, little endian byte order) |
+| f    | float (machine dependent size and representation)            |
+| g    | float (machine dependent size, little endian byte order)     |
+| G    | float (machine dependent size, big endian byte order)        |
+| d    | double (machine dependent size and representation)           |
+| e    | double (machine dependent size, little endian byte order)    |
+| E    | double (machine dependent size, big endian byte order)       |
+| x    | NUL byte                                                     |
+| X    | Back up one byte                                             |
+| Z    | NUL-terminated (ASCIIZ) string, will be NUL padded           |
+| @    | NUL-fill to absolute position                                |

doc/recipes.md

@@ -0,0 +1,48 @@
+# Recipes
+
+These are some suggestions and ideas for when building your own protocols using the
+various protocol classes.
+
+## Marshalling objects
+
+You can use the beforePackCb and afterUnpackCb to serialize and unserialize parameters
+as desired. Consider the security implications of this before you do anything stupid
+though, as a spoofed frame could have unexpected consequences when unserialized.
+
+```php
+$proto = new JsonProtocol(
+    beforePackCb: function (array $frame): array {
+        $frame['obj'] = serialize($frame['obj']);
+        return $frame;
+    },
+    afterUnpackCb: function (array $frame): array {
+        $frame['obj'] = unserialize($frame['obj]);
+        return $frame;
+    },
+);
+```
+
+## Building line-based messages
+
+By using the `beforePackCb` callback, you can take messages in a structured format
+and return them as a list for line-based protocols. You can do the same in reverse
+with the `afterUnpackCb` callback.
+
+```php
+$proto = new LineProtocol(
+    beforePackCb: function (array $frame): array {
+        switch ($frame['cmd']) {
+            case 'search':
+                return [ "search", $frame['query'] ];
+            // ..
+        }
+    },
+    afterUnpackCb: function (array $frame): array {
+        switch ($frame[0]) {
+            case 'search':
+                return [ 'cmd' => $frame[0], 'query' => $frame[1] ];
+            // ..
+        }
+    }
+)
+```

doc/text-protos.md

@@ -0,0 +1,35 @@
+# Text/Line Protocols
+
+
+
+
+
+## Available sub-protocols
+
+### HttpLikeProtocol
+
+This is as the name says a HTTP-like parser. It can be used for HTTP, STOMP
+and more. All messages are expected to follow the following style:
+
+```text
+query-line <$lineSeparator>
+header-line* <$lineSeparator>
+<$lineSeparator>
+optional-body
+```
+
+Line separators default to `\n`, but can be set to any sequence or the value `true`
+to attempt to automatically detect the endings used.
+
+The presence of a body is determined by consulting the headers. The `$contentLengthHeader`
+constructor parameter defaults to 'content-length', and can be set to null to disable parsing
+of bodies entirely.
+
+```php
+$proto = new HttpLikeProtocol(
+    queryFormat: '{command} {path}',
+    lineSeparator: true, 
+)
+
+
+```