phore/micro-app

Minimalistic Microservice Framework

This documentation is written along the guidelines of educational grade documentation discussed in the infracamp project. Please ask and document issues., _(*1)

Goals

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

Quicklinks - Assets - Authentication - Session - OAuth - Firewall ACL, _(*2)

Naming conventions

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

Quickstart

index.php:, _(*4)

$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:, _(*5)

composer require phore/micro-app

Routing (Example)

Define routes (Path) and connect them to controller functions:, _(*6)

• Execute the function if the browser hits http://domain.xy/hello/world:, _(*7)

  $app->router->onGet("/hello/world", function() {
    echo "Hello World";
    return true; 
  });
  

• Define Parameters (Prefix :) and optional parameters (?) in Routes:, _(*8)

  $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., _(*9)

• Delegate a request to a separate class: see Example, _(*10)

  $app->router->delegate("/admin/*", AdminController::class);
  

• Add a controller Class:, _(*11)

  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., _(*12)

Request specific parameters are:, _(*13)

Dependency Injection

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

• Define a value to property version:, _(*15)

  $app->define("version", new DiValue("1.0.1"));
  echo $app->version;
  

• Define a factory to property configFile:, _(*16)

  $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:, _(*17)

• 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., _(*18)

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

in the controller you can then just return the data:, _(*19)

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