From 525f3fcb82523b7c352ee3a99658971778c24cdc Mon Sep 17 00:00:00 2001
From: Aldarien <aldarien85@gmail.com>
Date: Tue, 30 Mar 2021 17:38:20 -0300
Subject: [PATCH] License and Readme

---
 LICENSE   |  21 +++++++++++
 Readme.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 Readme.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..53e623f
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2021] [aldarien85@gmail.com]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..e90e0ee
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,111 @@
+# Events
+
+[WebSockets] app for PHP. Using [Ratchet] as a base for creating the **app** it can be used as **framework** for connecting to the database from the web **UI**.
+
+## Introduction
+
+I wrote this project because I had a hard time finding any alternative to handling Server-Side WebSocket with [PHP]. [Ratchet] handles the connection but not the **app** itself. I needed an app structure similar to [Slim] which was what I work with. This is the result.
+
+## Installation
+
+Use [composer] with the git repository `https://github.com/Aldarien/events` (don't have [Packagist] setup correctly).
+
+```
+{
+  "require": {
+    "aldarien/events": "~1"
+  },
+  "repositories": [
+    {
+      "type": "git",
+      "url": "https://github.com/Aldarien/events"
+    }
+  ]
+}
+```
+
+## Use
+
+I recommend you setup your **app** with a Container like [PHP-DI]
+
+*Base example*:
+
+```
+$app = ProVM\Common\Alias\Server\App::factory(
+  new Ratchet\Server\HttpServer(
+    new Ratchet\Server\WsServer(
+      new ProVM\Common\Alias\Event\Message(new SplObjectStorage())
+    )
+  ),
+  $port ?? 8010
+);
+$app->add('event_name', function($request, $response) {
+  // do action
+  return $response;
+})
+$app->run();
+```
+
+*Breakdown*:
+
+The **app** is created similar to [Ratchet] with the wrapper `ProVM\Common\Alias\Server\App` but the message handler is from this package `ProVM\Common\Alias\Event\Message` which handles all event dispatches and listeners.
+
+Then the event(s) are added with `$app->add` it requires a name for the event and a callable handler that work similar to [Slim] Controllers.
+
+Finally just `$app->run`
+
+You can use a **Listener** for the callable:
+
+```
+class Handler {
+  public function __invoke($request, $response) {
+    // do something else
+    return $response;
+  }
+  public function other($request, $response) {
+    // other action
+    return $response;
+  }
+}
+$app->add('event2', new Handler());
+$app->add('other', [new Handler(), 'other']);
+```
+
+In the web **UI** just create a websocket:
+
+```
+var conn = new WebSocket(websocket_url)
+conn.onopen = function(e) {
+  // open event
+}
+conn.onmessage = function(e) {
+  // listen to messages received
+}
+conn.onerror = function(e) {
+  console.error(e)
+}
+conn.onclose = function(e) {
+  // check if e.code == 1000 closed without error)
+}
+msg = {
+  action: 'event_name',
+  data: []
+}
+conn.send(JSON.stringify(msg))
+```
+
+*Breakdown*:
+
+Create the websocket connection `new WebSocket(websocket_url)` where `websocket_url` can be something like `ws://localhost:8010` or `wss://localhost:8010` where the port is the same one set in the app.
+
+Set the event listeners for `open`, `message`, `error` and `close` and start sending messages with `send`
+
+Take note of the last lines where the message received by the **app** needs an action equivalent to the event names added before and the data associated if any (can be missing).
+
+[PHP]: http://php.net
+[WebSocket]: https://en.wikipedia.org/wiki/WebSocket
+[Ratchet]: http://socketo.me/
+[Slim]: https://slimframework.com
+[PHP-DI]: https://php-di.org/
+[composer]: https://getcomposer.org
+[Packagist]: https://packagist.org