From 82e0b1577c087d88531ed8ba2bbc2cb69caa1a00 Mon Sep 17 00:00:00 2001
From: Milos Stojanovic <alcalbg@gmail.com>
Date: Thu, 20 Jun 2019 11:09:05 +0200
Subject: [PATCH] docs upd

---
 backend/Services/Router/Router.php |  9 ------
 couscous.yml                       |  3 ++
 docs/configuration/auth.md         |  8 +++++
 docs/configuration/basic.md        |  7 ++--
 docs/configuration/router.md       | 52 ++++++++++++++++++++++++++++++
 docs/configuration/security.md     |  2 +-
 6 files changed, 69 insertions(+), 12 deletions(-)
 create mode 100644 docs/configuration/router.md

diff --git a/backend/Services/Router/Router.php b/backend/Services/Router/Router.php
index ff8df51..ef4a7a7 100644
--- a/backend/Services/Router/Router.php
+++ b/backend/Services/Router/Router.php
@@ -16,15 +16,6 @@ use Filegator\Kernel\Request;
 use Filegator\Services\Auth\AuthInterface;
 use Filegator\Services\Service;
 
-/**
- * Uses unique query parameter to pass the route info
- * Does not require rewrite rules, .htaccess or similar.
- *
- * Example routes:
- *
- * http://example.com/?r=/some/route&param1=val1&param2=val2
- * http://example.com/?r=/user/{user_id}&param1=val1
- */
 class Router implements Service
 {
     protected $request;
diff --git a/couscous.yml b/couscous.yml
index 7bff6e8..e57b55f 100644
--- a/couscous.yml
+++ b/couscous.yml
@@ -59,6 +59,9 @@ menu:
                 security:
                     text: Security
                     relativeUrl: configuration/security.html
+                router:
+                    text: Router
+                    relativeUrl: configuration/router.html
 
         multilang:
             name: Languages
diff --git a/docs/configuration/auth.md b/docs/configuration/auth.md
index 8ac28e5..b8393d3 100644
--- a/docs/configuration/auth.md
+++ b/docs/configuration/auth.md
@@ -54,3 +54,11 @@ At the end, open ```configuration.php``` and update AuthInterface handler to ref
         ],
 ```
 
+
+## API authentication
+
+Front-end will use session based authentication to authenticate and consume the back-end.
+
+Note: The application will not correctly if cookies are disabled.
+
+
diff --git a/docs/configuration/basic.md b/docs/configuration/basic.md
index e0495ea..49743d9 100644
--- a/docs/configuration/basic.md
+++ b/docs/configuration/basic.md
@@ -1,9 +1,12 @@
 
 ## Basic
-You can edit ```configuration.php``` to change the basic things like logo image, title, language and upload restrictions.
+All services are set with reasonable defaults. For regular users there is no need to change anything. The script should work out of the box.
 
 
-NOTE: if you've made a mistake in configuration file, forgot to close a quote, the script will throw an error. Please use provided default ```configuration_sample.php``` to verify this.
+You can edit ```/configuration.php``` file to change the basic things like logo image, title, language and upload restrictions.
+
+
+Note: if you've made a mistake in configuration file (forgot to close a quote?) the script will fail to load or throw an error. Please use provided default ```configuration_sample.php``` to put everything back to normal.
 
 ```
     'frontend_config' => [
diff --git a/docs/configuration/router.md b/docs/configuration/router.md
new file mode 100644
index 0000000..88db693
--- /dev/null
+++ b/docs/configuration/router.md
@@ -0,0 +1,52 @@
+
+## Router service
+
+Router service is using well-known [FastRoute](https://github.com/nikic/FastRoute) library. There is no need to change this service unless you're extending the script.
+
+The router uses unique query parameter ```?r=``` to pass the route info. Because of this feature, this (single-page) application does not require rewrite rules, .htaccess or similar tweaks.
+
+Example routes:
+
+- ```http://example.com/?r=/some/route&param1=val1&param2=val2```
+- ```http://example.com/?r=/user/{user_id}&param1=val1```
+
+
+## Routes file
+
+Routes file is located here ```/backend/Controllers/routes.php```. Each route in the routes array looks like this:
+
+
+```
+    [
+        'route' => [
+            'GET', '/download/{path_encoded}', '\Filegator\Controllers\DownloadController@download',
+        ],
+        'roles' => [
+            'guest', 'user', 'admin',
+        ],
+        'permissions' => [
+            'download',
+        ],
+    ],
+```
+
+As you can in the example, you can assign required user roles and permissions for each route.
+
+## Controllers
+
+Since FileGator is using an awesome dependency injection [container](https://github.com/PHP-DI/PHP-DI) you can type-hint dependencies directly in your controllers. 
+
+You can also mix route parameters and dependencies in any order like in this example:
+
+```
+
+    public function __construct(Config $config, Session $session, AuthInterface $auth, Filesystem $storage)
+    {
+      // ...
+    }
+
+    public function download($path_encoded, Request $request, Response $response, StreamedResponse $streamedResponse)
+    {
+      // ...
+    }
+```
diff --git a/docs/configuration/security.md b/docs/configuration/security.md
index 11eb178..fd682a4 100644
--- a/docs/configuration/security.md
+++ b/docs/configuration/security.md
@@ -2,7 +2,7 @@
 
 Simple security service is included in the script by default. This service provides:
 
-- Basic [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection
+- Basic session-based [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection
 - IP whitelisting
 - IP blacklisting