phore/micro-app

Micro framework for rest api webservices

v0.2 2018-09-18 10:17 UTC

This package is auto-updated.

Last update: 2020-06-25 14:28:29 UTC


README

This documentation is written along the guidelines of educational grade documentation discussed in the infracamp project. Please ask and document issues.

Goals

  • Minimal Footprint
  • No external dependencies
  • Clear and small stack trace
  • Fluent Api
  • Role-Based Authentication

Quicklinks

  • Assets
  • Authentication
  • Session
  • OAuth
  • Firewall ACL

Naming conventions

Classes for micro-app and libraries are not prefixed with phore_ for convenience. (It's not framework for framework stuff)

Quickstart

index.php:

$app = new App();

$app->router
    ->onGet("/",                                              // Define a Action for HTTP-GET-Requests to /
        function() {                             
            return "Hello world";                             // Important: Return true if output was already sent.
        }
    );
    
$app->serve();                                                // Run the App

Installation

We suggest using composer:

composer require phore/micro-app

Routing (Example)

Define routes (Path) and connect them to controller functions:

  • Execute the function if the browser hits http://domain.xy/hello/world:

    $app->router->onGet("/hello/world", function() {
        echo "Hello World";
        return true; 
    });
  • Define Parameters (Prefix :) and optional parameters (?) in Routes:

    $app->router->onGet("/api/create/:userId/:userName?", function(RouteParams $routeParams) {
        echo "Hello {$routeParams->get("userId")} - {$routeParams->get("userName", 'Default Username')}";
        return true;
    });

    $routeParams is automaticly generated by Dependency injection.

  • Delegate a request to a separate class: see Example

    $app->router->delegate("/admin/*", AdminController::class);
  • Add a controller Class:

    class ActionCtrl {
        const ROUTE = "/v1/some/route"
        public function on_get(){} 
    }
    $app->addCtrl(ActionCtrl::class);

Parameters at controller function are generated by Dependency Injection and may contain any service defined in DiContainer.

Request specific parameters are:

Parameter Name ClassName Description
$request Request The full request object
$post Post Post data
$get Get Get data (Query Params)
$body Body Body object
$files Files
$route Route The current route object
$params Params Container with QueryParameters
$routeParams RouteParams Container with parameters
$GET QueryParams Query parameters
$POST QueryParams Parameters send by HTTP-POST

Dependency Injection

The app-class is a dependency injection container. You can register values or services using the define() method.

  • Define a value to property version:

    $app->define("version", new DiValue("1.0.1"));
    echo $app->version;
  • Define a factory to property configFile:

    $app->define("configFile", new DiService(function() {
        return file_get_contents("config-file.json") 
    });
    echo $app->configFile;

Error Handling

The system has build-in functions for error-handling:

  • Activate json error/exception handling:
    $app->setOnExceptionHandler(new JsonExceptionHandler());
    

API Usage: Default Result Handler

Instead of formating the Result your own, the framework uses a result-handler to format results returned by return in controller.

$app->setDefaultResultHandler(new JsonResultHandler());

in the controller you can then just return the data:

$app->get("/", function() {
    return ["data"=>"someData"];
}