Improved documentation

README.md

@@ -3,14 +3,14 @@
 ![](https://user-images.githubusercontent.com/104888/50957476-9c4acb80-14be-11e9-88ce-6447364dc1bb.png)
 ![](https://img.shields.io/badge/PHPStan-level%206-brightgreen.svg?style=flat)
 
-Flight is a fast, simple, extensible framework for PHP. Flight enables you to 
+Flight is a fast, simple, extensible framework for PHP. Flight enables you to
 quickly and easily build RESTful web applications.
 
 ```php
 require 'flight/Flight.php';
 
-Flight::route('/', function(){
-    echo 'hello world!';
+Flight::route('/', function() {
+  echo 'hello world!';
 });
 
 Flight::start();
@@ -30,14 +30,15 @@ Flight is released under the [MIT](http://flightphp.com/license) license.
 
 1\. Download the files.
 
-If you're using [Composer](https://getcomposer.org/), you can run the following command:
+If you're using [Composer](https://getcomposer.org/), you can run the following
+command:
 
-```
+```bash
 composer require mikecao/flight
 ```
 
-OR you can [download](https://github.com/mikecao/flight/archive/master.zip) them directly 
-and extract them to your web directory.
+OR you can [download](https://github.com/mikecao/flight/archive/master.zip)
+them directly and extract them to your web directory.
 
 2\. Configure your webserver.
 
@@ -50,15 +51,16 @@ RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^(.*)$ index.php [QSA,L]
 ```
 
-**Note**: If you need to use flight in a subdirectory add the line `RewriteBase /subdir/` just after `RewriteEngine On`.
+**Note**: If you need to use flight in a subdirectory add the line
+`RewriteBase /subdir/` just after `RewriteEngine On`.
 
 For *Nginx*, add the following to your server declaration:
 
 ```
 server {
-    location / {
-        try_files $uri $uri/ /index.php;
-    }
+  location / {
+  try_files $uri $uri/ /index.php;
+  }
 }
 ```
 3\. Create your `index.php` file.
@@ -78,8 +80,8 @@ require 'vendor/autoload.php';
 Then define a route and assign a function to handle the request.
 
 ```php
-Flight::route('/', function(){
-    echo 'hello world!';
+Flight::route('/', function () {
+  echo 'hello world!';
 });
 ```
 
@@ -94,16 +96,16 @@ Flight::start();
 Routing in Flight is done by matching a URL pattern with a callback function.
 
 ```php
-Flight::route('/', function(){
-    echo 'hello world!';
+Flight::route('/', function () {
+  echo 'hello world!';
 });
 ```
 
 The callback can be any object that is callable. So you can use a regular function:
 
 ```php
-function hello(){
-    echo 'hello world!';
+function hello() {
+  echo 'hello world!';
 }
 
 Flight::route('/', 'hello');
@@ -113,9 +115,9 @@ Or a class method:
 
 ```php
 class Greeting {
-    public static function hello() {
-        echo 'hello world!';
-    }
+  public static function hello() {
+    echo 'hello world!';
+  }
 }
 
 Flight::route('/', array('Greeting', 'hello'));
@@ -126,18 +128,18 @@ Or an object method:
 ```php
 class Greeting
 {
-    public function __construct() {
-        $this->name = 'John Doe';
-    }
+  public function __construct() {
+    $this->name = 'John Doe';
+  }
 
-    public function hello() {
-        echo "Hello, {$this->name}!";
-    }
+  public function hello() {
+    echo "Hello, {$this->name}!";
+  }
 }
 
 $greeting = new Greeting();
 
-Flight::route('/', array($greeting, 'hello')); 
+Flight::route('/', array($greeting, 'hello'));
 ```
 
 Routes are matched in the order they are defined. The first route to match a
@@ -149,20 +151,20 @@ By default, route patterns are matched against all request methods. You can resp
 to specific methods by placing an identifier before the URL.
 
 ```php
-Flight::route('GET /', function(){
-    echo 'I received a GET request.';
+Flight::route('GET /', function () {
+  echo 'I received a GET request.';
 });
 
-Flight::route('POST /', function(){
-    echo 'I received a POST request.';
+Flight::route('POST /', function () {
+  echo 'I received a POST request.';
 });
 ```
 
 You can also map multiple methods to a single callback by using a `|` delimiter:
 
 ```php
-Flight::route('GET|POST /', function(){
-    echo 'I received either a GET or a POST request.';
+Flight::route('GET|POST /', function () {
+  echo 'I received either a GET or a POST request.';
 });
 ```
 
@@ -171,8 +173,8 @@ Flight::route('GET|POST /', function(){
 You can use regular expressions in your routes:
 
 ```php
-Flight::route('/user/[0-9]+', function(){
-    // This will match /user/1234
+Flight::route('/user/[0-9]+', function () {
+  // This will match /user/1234
 });
 ```
 
@@ -182,8 +184,8 @@ You can specify named parameters in your routes which will be passed along to
 your callback function.
 
 ```php
-Flight::route('/@name/@id', function($name, $id){
-    echo "hello, $name ($id)!";
+Flight::route('/@name/@id', function(string $name, string $id) {
+  echo "hello, $name ($id)!";
 });
 ```
 
@@ -191,9 +193,9 @@ You can also include regular expressions with your named parameters by using
 the `:` delimiter:
 
 ```php
-Flight::route('/@name/@id:[0-9]{3}', function($name, $id){
-    // This will match /bob/123
-    // But will not match /bob/12345
+Flight::route('/@name/@id:[0-9]{3}', function(string $name, string $id) {
+  // This will match /bob/123
+  // But will not match /bob/12345
 });
 ```
 
@@ -205,13 +207,16 @@ You can specify named parameters that are optional for matching by wrapping
 segments in parentheses.
 
 ```php
-Flight::route('/blog(/@year(/@month(/@day)))', function($year, $month, $day){
+Flight::route(
+  '/blog(/@year(/@month(/@day)))',
+  function(?string $year, ?string $month, ?string $day) {
     // This will match the following URLS:
     // /blog/2012/12/10
     // /blog/2012/12
     // /blog/2012
     // /blog
-});
+  }
+);
 ```
 
 Any optional parameters that are not matched will be passed in as NULL.
@@ -222,16 +227,16 @@ Matching is only done on individual URL segments. If you want to match multiple
 segments you can use the `*` wildcard.
 
 ```php
-Flight::route('/blog/*', function(){
-    // This will match /blog/2000/02/01
+Flight::route('/blog/*', function () {
+  // This will match /blog/2000/02/01
 });
 ```
 
 To route all requests to a single callback, you can do:
 
 ```php
-Flight::route('*', function(){
-    // Do something
+Flight::route('*', function () {
+  // Do something
 });
 ```
 
@@ -241,16 +246,16 @@ You can pass execution on to the next matching route by returning `true` from
 your callback function.
 
 ```php
-Flight::route('/user/@name', function($name){
-    // Check some condition
-    if ($name != "Bob") {
-        // Continue to next route
-        return true;
-    }
+Flight::route('/user/@name', function (string $name) {
+  // Check some condition
+  if ($name != "Bob") {
+    // Continue to next route
+    return true;
+  }
 });
 
-Flight::route('/user/*', function(){
-    // This will get called
+Flight::route('/user/*', function () {
+  // This will get called
 });
 ```
 
@@ -262,18 +267,18 @@ the route method. The route object will always be the last parameter passed to y
 callback function.
 
 ```php
-Flight::route('/', function($route){
-    // Array of HTTP methods matched against
-    $route->methods;
+Flight::route('/', function(\flight\net\Route $route) {
+  // Array of HTTP methods matched against
+  $route->methods;
 
-    // Array of named parameters
-    $route->params;
+  // Array of named parameters
+  $route->params;
 
-    // Matching regular expression
-    $route->regex;
+  // Matching regular expression
+  $route->regex;
 
-    // Contains the contents of any '*' used in the URL pattern
-    $route->splat;
+  // Contains the contents of any '*' used in the URL pattern
+  $route->splat;
 }, true);
 ```
 
@@ -289,8 +294,8 @@ To map your own custom method, you use the `map` function:
 
 ```php
 // Map your method
-Flight::map('hello', function($name){
-    echo "hello $name!";
+Flight::map('hello', function ($name) {
+  echo "hello $name!";
 });
 
 // Call your custom method
@@ -321,7 +326,7 @@ Flight::register('db', 'PDO', array('mysql:host=localhost;dbname=test','user','p
 // Get an instance of your class
 // This will create an object with the defined parameters
 //
-//     new PDO('mysql:host=localhost;dbname=test','user','pass');
+// new PDO('mysql:host=localhost;dbname=test','user','pass');
 //
 $db = Flight::db();
 ```
@@ -332,8 +337,8 @@ new object. The callback function takes one parameter, an instance of the new ob
 
 ```php
 // The callback will be passed the object that was constructed
-Flight::register('db', 'PDO', array('mysql:host=localhost;dbname=test','user','pass'), function($db){
-    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
+Flight::register('db', 'PDO', array('mysql:host=localhost;dbname=test','user','pass'), function (PDO $db): void {
+  $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
 });
 ```
 
@@ -362,8 +367,8 @@ by using the `map` method:
 
 ```php
 Flight::map('notFound', function(){
-    // Display custom 404 page
-    include 'errors/404.html';
+  // Display custom 404 page
+  include 'errors/404.html';
 });
 ```
 
@@ -390,8 +395,8 @@ methods as well as any custom methods that you've mapped.
 A filter function looks like this:
 
 ```php
-function(&$params, &$output) {
-    // Filter code
+function (array &$params, string &$output) {
+  // Filter code
 }
 ```
 
@@ -400,16 +405,16 @@ Using the passed in variables you can manipulate the input parameters and/or the
 You can have a filter run before a method by doing:
 
 ```php
-Flight::before('start', function(&$params, &$output){
-    // Do something
+Flight::before('start', function (array &$params, string &$output) {
+  // Do something
 });
 ```
 
 You can have a filter run after a method by doing:
 
 ```php
-Flight::after('start', function(&$params, &$output){
-    // Do something
+Flight::after('start', function (array &$params, string &$output) {
+  // Do something
 });
 ```
 
@@ -420,20 +425,20 @@ Here's an example of the filtering process:
 
 ```php
 // Map a custom method
-Flight::map('hello', function($name){
-    return "Hello, $name!";
+Flight::map('hello', function ($name) {
+  return "Hello, $name!";
 });
 
 // Add a before filter
-Flight::before('hello', function(&$params, &$output){
-    // Manipulate the parameter
-    $params[0] = 'Fred';
+Flight::before('hello', function (array &$params, string &$output) {
+  // Manipulate the parameter
+  $params[0] = 'Fred';
 });
 
 // Add an after filter
-Flight::after('hello', function(&$params, &$output){
-    // Manipulate the output
-    $output .= " Have a nice day!";
+Flight::after('hello', function (array &$params, string &$output) {
+  // Manipulate the output
+  $output .= " Have a nice day!";
 });
 
 // Invoke the custom method
@@ -442,26 +447,28 @@ echo Flight::hello('Bob');
 
 This should display:
 
-    Hello Fred! Have a nice day!
+```
+Hello Fred! Have a nice day!
+```
 
 If you have defined multiple filters, you can break the chain by returning `false`
 in any of your filter functions:
 
 ```php
-Flight::before('start', function(&$params, &$output){
-    echo 'one';
+Flight::before('start', function (array &$params, string &$output){
+  echo 'one';
 });
 
-Flight::before('start', function(&$params, &$output){
-    echo 'two';
+Flight::before('start', function (array &$params, string &$output): bool {
+  echo 'two';
 
-    // This will end the chain
-    return false;
+  // This will end the chain
+  return false;
 });
 
 // This will not get called
-Flight::before('start', function(&$params, &$output){
-    echo 'three';
+Flight::before('start', function (array &$params, string &$output){
+  echo 'three';
 });
 ```
 
@@ -483,7 +490,7 @@ To see if a variable has been set you can do:
 
 ```php
 if (Flight::has('id')) {
-     // Do something
+  // Do something
 }
 ```
 
@@ -518,12 +525,14 @@ be reference like a local variable. Template files are simply PHP files. If the
 content of the `hello.php` template file is:
 
 ```php
-Hello, '<?php echo $name; ?>'!
+Hello, <?php echo $name; ?>!
 ```
 
 The output would be:
 
-    Hello, Bob!
+```
+Hello, Bob!
+```
 
 You can also manually set view variables by using the set method:
 
@@ -583,26 +592,26 @@ If the template files looks like this:
 
 ```php
 <html>
-<head>
-<title><?php echo $title; ?></title>
-</head>
-<body>
-<?php echo $header_content; ?>
-<?php echo $body_content; ?>
-</body>
+  <head>
+    <title><?php echo $title; ?></title>
+  </head>
+  <body>
+    <?php echo $header_content; ?>
+    <?php echo $body_content; ?>
+  </body>
 </html>
 ```
 
 The output would be:
 ```html
 <html>
-<head>
-<title>Home Page</title>
-</head>
-<body>
-<h1>Hello</h1>
-<div>World</div>
-</body>
+  <head>
+    <title>Home Page</title>
+  </head>
+  <body>
+    <h1>Hello</h1>
+    <div>World</div>
+  </body>
 </html>
 ```
 
@@ -618,11 +627,11 @@ require './Smarty/libs/Smarty.class.php';
 
 // Register Smarty as the view class
 // Also pass a callback function to configure Smarty on load
-Flight::register('view', 'Smarty', array(), function($smarty){
-    $smarty->template_dir = './templates/';
-    $smarty->compile_dir = './templates_c/';
-    $smarty->config_dir = './config/';
-    $smarty->cache_dir = './cache/';
+Flight::register('view', 'Smarty', array(), function (Smarty $smarty) {
+  $smarty->setTemplateDir() = './templates/';
+  $smarty->setCompileDir() = './templates_c/';
+  $smarty->setConfigDir() = './config/';
+  $smarty->setCacheDir() = './cache/';
 });
 
 // Assign template data
@@ -636,8 +645,8 @@ For completeness, you should also override Flight's default render method:
 
 ```php
 Flight::map('render', function($template, $data){
-    Flight::view()->assign($data);
-    Flight::view()->display($template);
+  Flight::view()->assign($data);
+  Flight::view()->display($template);
 });
 ```
 # Error Handling
@@ -651,9 +660,9 @@ response with some error information.
 You can override this behavior for your own needs:
 
 ```php
-Flight::map('error', function(Exception $ex){
-    // Handle error
-    echo $ex->getTraceAsString();
+Flight::map('error', function(Throwable $ex){
+  // Handle error
+  echo $ex->getTraceAsString();
 });
 ```
 
@@ -672,8 +681,8 @@ behavior is to send an `HTTP 404 Not Found` response with a simple message.
 You can override this behavior for your own needs:
 
 ```php
-Flight::map('notFound', function(){
-    // Handle not found
+Flight::map('notFound', function () {
+  // Handle not found
 });
 ```
 
@@ -704,26 +713,24 @@ $request = Flight::request();
 
 The request object provides the following properties:
 
-```
-url - The URL being requested
-base - The parent subdirectory of the URL
-method - The request method (GET, POST, PUT, DELETE)
-referrer - The referrer URL
-ip - IP address of the client
-ajax - Whether the request is an AJAX request
-scheme - The server protocol (http, https)
-user_agent - Browser information
-type - The content type
-length - The content length
-query - Query string parameters
-data - Post data or JSON data
-cookies - Cookie data
-files - Uploaded files
-secure - Whether the connection is secure
-accept - HTTP accept parameters
-proxy_ip - Proxy IP address of the client
-host - The request host name
-```
+- **url** - The URL being requested
+- **base** - The parent subdirectory of the URL
+- **method** - The request method (GET, POST, PUT, DELETE)
+- **referrer** - The referrer URL
+- **ip** - IP address of the client
+- **ajax** - Whether the request is an AJAX request
+- **scheme** - The server protocol (http, https)
+- **user_agent** - Browser information
+- **type** - The content type
+- **length** - The content length
+- **query** - Query string parameters
+- **data** - Post data or JSON data
+- **cookies** - Cookie data
+- **files** - Uploaded files
+- **secure** - Whether the connection is secure
+- **accept** - HTTP accept parameters
+- **proxy_ip** - Proxy IP address of the client
+- **host** - The request host name
 
 You can access the `query`, `data`, `cookies`, and `files` properties
 as arrays or objects.
@@ -742,7 +749,8 @@ $id = Flight::request()->query->id;
 
 ## RAW Request Body
 
-To get the raw HTTP request body, for example when dealing with PUT requests, you can do:
+To get the raw HTTP request body, for example when dealing with PUT requests,
+you can do:
 
 ```php
 $body = Flight::request()->getBody();
@@ -750,8 +758,8 @@ $body = Flight::request()->getBody();
 
 ## JSON Input
 
-If you send a request with the type `application/json` and the data `{"id": 123}` it will be available
-from the `data` property:
+If you send a request with the type `application/json` and the data `{"id": 123}`
+it will be available from the `data` property:
 
 ```php
 $id = Flight::request()->data->id;
@@ -771,9 +779,9 @@ and time a page was last modified. The client will continue to use their cache u
 the last modified value is changed.
 
 ```php
-Flight::route('/news', function(){
-    Flight::lastModified(1234567890);
-    echo 'This content will be cached.';
+Flight::route('/news', function () {
+  Flight::lastModified(1234567890);
+  echo 'This content will be cached.';
 });
 ```
 
@@ -783,9 +791,9 @@ Flight::route('/news', function(){
 want for the resource:
 
 ```php
-Flight::route('/news', function(){
-    Flight::etag('my-unique-id');
-    echo 'This content will be cached.';
+Flight::route('/news', function () {
+  Flight::etag('my-unique-id');
+  echo 'This content will be cached.';
 });
 ```
 
@@ -850,12 +858,12 @@ Flight::set('flight.log_errors', true);
 
 The following is a list of all the available configuration settings:
 
-    flight.base_url - Override the base url of the request. (default: null)
-    flight.case_sensitive - Case sensitive matching for URLs. (default: false)
-    flight.handle_errors - Allow Flight to handle all errors internally. (default: true)
-    flight.log_errors - Log errors to the web server's error log file. (default: false)
-    flight.views.path - Directory containing view template files. (default: ./views)
-    flight.views.extension - View template file extension. (default: .php)
+- **flight.base_url** - Override the base url of the request. (default: null)
+- **flight.case_sensitive** - Case sensitive matching for URLs. (default: false)
+- **flight.handle_errors** - Allow Flight to handle all errors internally. (default: true)
+- **flight.log_errors** - Log errors to the web server's error log file. (default: false)
+- **flight.views.path** - Directory containing view template files. (default: ./views)
+- **flight.views.extension** - View template file extension. (default: .php)
 
 # Framework Methods
 
@@ -867,15 +875,15 @@ or overridden.
 ## Core Methods
 
 ```php
-Flight::map($name, $callback) // Creates a custom framework method.
-Flight::register($name, $class, [$params], [$callback]) // Registers a class to a framework method.
-Flight::before($name, $callback) // Adds a filter before a framework method.
-Flight::after($name, $callback) // Adds a filter after a framework method.
-Flight::path($path) // Adds a path for autoloading classes.
-Flight::get($key) // Gets a variable.
-Flight::set($key, $value) // Sets a variable.
-Flight::has($key) // Checks if a variable is set.
-Flight::clear([$key]) // Clears a variable.
+Flight::map(string $name, callable $callback, bool $pass_route = false) // Creates a custom framework method.
+Flight::register(string $name, string $class, array $params = [], ?callable $callback = null) // Registers a class to a framework method.
+Flight::before(string $name, callable $callback) // Adds a filter before a framework method.
+Flight::after(string $name, callable $callback) // Adds a filter after a framework method.
+Flight::path(string $path) // Adds a path for autoloading classes.
+Flight::get(string $key) // Gets a variable.
+Flight::set(string $key, mixed $value) // Sets a variable.
+Flight::has(string $key) // Checks if a variable is set.
+Flight::clear(array|string $key = []) // Clears a variable.
 Flight::init() // Initializes the framework to its default settings.
 Flight::app() // Gets the application object instance
 ```
@@ -885,16 +893,16 @@ Flight::app() // Gets the application object instance
 ```php
 Flight::start() // Starts the framework.
 Flight::stop() // Stops the framework and sends a response.
-Flight::halt([$code], [$message]) // Stop the framework with an optional status code and message.
-Flight::route($pattern, $callback) // Maps a URL pattern to a callback.
-Flight::redirect($url, [$code]) // Redirects to another URL.
-Flight::render($file, [$data], [$key]) // Renders a template file.
-Flight::error($exception) // Sends an HTTP 500 response.
+Flight::halt(int $code = 200, string $message = '') // Stop the framework with an optional status code and message.
+Flight::route(string $pattern, callable $callback, bool $pass_route = false) // Maps a URL pattern to a callback.
+Flight::redirect(string $url, int $code) // Redirects to another URL.
+Flight::render(string $file, array $data, ?string $key = null) // Renders a template file.
+Flight::error(Throwable $exception) // Sends an HTTP 500 response.
 Flight::notFound() // Sends an HTTP 404 response.
-Flight::etag($id, [$type]) // Performs ETag HTTP caching.
-Flight::lastModified($time) // Performs last modified HTTP caching.
-Flight::json($data, [$code], [$encode], [$charset], [$option]) // Sends a JSON response.
-Flight::jsonp($data, [$param], [$code], [$encode], [$charset], [$option]) // Sends a JSONP response.
+Flight::etag(string $id, string $type = 'string') // Performs ETag HTTP caching.
+Flight::lastModified(int $time) // Performs last modified HTTP caching.
+Flight::json(mixed $data, int $code = 200, bool $encode = true, string $charset = 'utf8', int $option) // Sends a JSON response.
+Flight::jsonp(mixed $data, string $param = 'jsonp', int $code = 200, bool $encode = true, string $charset = 'utf8', int $option) // Sends a JSONP response.
 ```
 
 Any custom methods added with `map` and `register` can also be filtered.
@@ -908,12 +916,10 @@ as an object instance.
 ```php
 require 'flight/autoload.php';
 
-use flight\Engine;
+$app = new flight\Engine();
 
-$app = new Engine();
-
-$app->route('/', function(){
-    echo 'hello world!';
+$app->route('/', function () {
+  echo 'hello world!';
 });
 
 $app->start();