Documentation

dederobert · Aug 25, 2017 · 7fcfe55 · 7fcfe55
1 parent 634c168
commit 7fcfe55
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 35 deletions.
diff --git a/assets/homepage.html b/assets/homepage.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>DuskPHP - Homepage</title>
+</head>
+<body>
+    <h1>DuskPHP</h1>
+    <p>Welcome to the duskPHP's homepage. Enjoy it !</p>
+</body>
+</html>
diff --git a/src/Dispatcher.php b/src/Dispatcher.php
@@ -10,6 +10,7 @@
 
 /**
  * Class Dispacher
+ * A dispatcher call all saved middleware to create a response
  * @package DuskPHP
  */
 class Dispatcher implements DelegateInterface
@@ -25,6 +26,9 @@ class Dispatcher implements DelegateInterface
      */
     private $index = 0;
 
+    /**
+     * @var Response
+     */
     private $response;
 
     function __construct()
@@ -53,10 +57,10 @@ public function process(ServerRequestInterface $request)
     {
         $middleware = $this->getMiddleware();
         $this->index++;
+
+        //When all saved middleware were called
         if (is_null($middleware))
             return $this->response;
-        if(is_callable($middleware))
-            return $middleware($request, $this->response, [$this, 'process']);
         if ($middleware instanceof MiddlewareInterface)
             return $middleware->process($request, $this);
     }

diff --git a/src/Exception/RouterException.php b/src/Exception/RouterException.php
@@ -2,5 +2,8 @@
 
 namespace DuskPHP\Core\Exception;
 
-
+/**
+ * Class RouterException
+ * @package DuskPHP\Core\Exception
+ */
 class RouterException extends \Exception {}
diff --git a/src/HomePage.php b/src/HomePage.php
@@ -8,13 +8,21 @@
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Class HomePage
+ * Very simple middleware use as example
+ *
+ * @package DuskPHP\Core
+ */
 class HomePage implements MiddlewareInterface
 {
 
     /**
      * Process an incoming server request and return a response, optionally delegating
      * to the next middleware component to create the response.
      *
+     * Print a basic HTML page
+     *
      * @param ServerRequestInterface $request
      * @param DelegateInterface $delegate
      *
@@ -23,7 +31,7 @@ class HomePage implements MiddlewareInterface
     public function process(ServerRequestInterface $request, DelegateInterface $delegate)
     {
         $response = $delegate->process($request);
-        $response->getBody()->write('Homepage');
+        $response->getBody()->write(file_get_contents(dirname(__DIR__)."/assets/homepage.html"));
         return $response;
     }
 }
diff --git a/src/Router/Route.php b/src/Router/Route.php
@@ -6,13 +6,19 @@
  * Time: 00:39
  */
 
-namespace DuskPHP\Core  \Router;
+namespace DuskPHP\Core\Router;
 
 
 use Interop\Http\ServerMiddleware\DelegateInterface;
 use Interop\Http\ServerMiddleware\MiddlewareInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Class Route
+ * A route associate a path with a middleware
+ * The router search the matching route with the URI and call the middleware
+ * @package DuskPHP\Core  \Router
+ */
 class Route
 {
     /**
@@ -41,15 +47,24 @@ function __construct(string $path,MiddlewareInterface $middleware)
         $this->middleware = $middleware;
     }
 
-    public function with($param, string $regex)
+    /**
+     * Add a regex to the path's parameters
+     * eg: path: "/posts/:id-:slug" with id a integer and slug a string, id's regex is "[0-9]+" and slug's regex: "[a-z\-0-9]+"
+     * @param string $param The parameter's name
+     * @param string $regex The associate regex which use to identify parameter
+     * @return $this The Route
+     */
+    public function with(string $param, string $regex)
     {
         $this->params[$param] = str_replace('(', '(?:', $regex);
         return $this;
     }
 
     /**
-     * @param string $url
-     * @return bool
+     * Check if the route match with the current URI
+     *
+     * @param string $url The URI
+     * @return bool True if match
      */
     public function match(string $url): bool {
         $url = trim($url, '/');
@@ -71,15 +86,15 @@ private function paramMatch(array $match): string {
         return '([^/]+';
     }
 
+    /**
+     * Call the associate middleware
+     *
+     * @param ServerRequestInterface $request The current request
+     * @param DelegateInterface $delegate The delegate ware which call the next middleware
+     * @return \Psr\Http\Message\ResponseInterface The response
+     */
     public function call(ServerRequestInterface $request, DelegateInterface $delegate) {
-//        if (is_string($this->middleware)) {
-//            $params = explode('#', $this->middleware);
-//            $controller = "App\\Controller\\" . $params[0]."Controller";
-//            $controller = new $controller();
-//            return call_user_func_array([$controller, $params[1], $this->matches]);
-//        }
         return $this->middleware->process($request, $delegate);
-//        return call_user_func_array($this->middleware, $this->matches);
     }
 
     public function getURL($params): string {

diff --git a/src/Router/Router.php b/src/Router/Router.php
@@ -16,20 +16,44 @@
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Class Router
+ * A router is a middleware which call an other middleware compared to the URI
+ * @package DuskPHP\Core\Router
+ */
 class Router implements MiddlewareInterface
 {
     /**
      * @var array
      */
     private $routes = [];
 
+    /**
+     * @var array
+     */
     private $namedRoutes = [];
 
+    /**
+     * Add a route associate to the get http method
+     *
+     * @param string $path The path's route, which match with the URI
+     * @param MiddlewareInterface $middleware The associate middleware which will call if matching
+     * @param string $name The route's name, use to get the URL
+     * @return Route The created route
+     */
     public function get(string $path,MiddlewareInterface $middleware,string $name): Route
     {
         return $this->add($path, $middleware, $name, 'GET');
     }
 
+    /**
+     * Add a route associate to the get http method
+     *
+     * @param string $path The path's route, which match with the URI
+     * @param MiddlewareInterface $middleware The associate middleware which will call if matching
+     * @param string $name The route's name, use to get the URL
+     * @return Route The created route
+     */
     public function post(string $path, MiddlewareInterface $middleware,string $name): Route
     {
         return $this->add($path, $middleware, $name, 'POST');
@@ -48,21 +72,16 @@ private function add(string $path, MiddlewareInterface $middleware,string $name,
         return $route;
     }
 
-//    public function run(){
-//        if (!isset($this->routes[$_SERVER['REQUEST_METHOD']])) {
-//            throw new RouterException('REQUEST_METHOD does not exist');
-//        }
-//
-//        foreach ($this->routes[$_SERVER['REQUEST_METHOD']] as $route) {
-//            if ($route->match($this->url)) {
-//                return $route->call();
-//            }
-//        }
-//
-//        throw new RouterException('No matching routes');
-//    }
-
-    public function url($name, $params = []){
+    /**
+     * Get the named route's URL and matching param's values
+     *
+     * @param string $name The route's name
+     * @param array $params The param's values which will replace in the URL
+     * @return string The route's URL
+     * @throws RouterException when the given name doesn't match with route's name
+     */
+    public function url(string $name, array $params = []): string
+    {
         if (!isset($this->namedRoutes[$name]))
             throw new RouterException('No route matches this name');
         return $this->namedRoutes[$name]->getURl($params);
@@ -72,15 +91,17 @@ public function url($name, $params = []){
      * Process an incoming server request and return a response, optionally delegating
      * to the next middleware component to create the response.
      *
-     * @param ServerRequestInterface $request
-     * @param DelegateInterface $delegate
-     * @return ResponseInterface
-     * @throws RouterException
+     * Search the route and call the associate middleware
+     *
+     * @param ServerRequestInterface $request The current request
+     * @param DelegateInterface $delegate The next middleware
+     * @return ResponseInterface The response
+     * @throws RouterException when the http-method doesn't exist
      */
     public function process(ServerRequestInterface $request, DelegateInterface $delegate)
     {
         if (!isset($this->routes[$request->getMethod()]))
-            throw new RouterException($request->getMethod() . ' does not exist');
+            throw new RouterException('The method '.$request->getMethod() . ', does not exist');
 
         foreach ($this->routes[$request->getMethod()] as $route)
             if ($route->match($request->getQueryParams()['url']))