phore/micro-app

Micro framework for rest api webservices

v0.3.1 2021-02-28 18:41 UTC

Requires

• php: >7.1
• ext-json: *
• ext-yaml: *
• phore/core: *
• phore/di-base: ^2.2.1
• psr/log: ^1.1

Requires (Dev)

• phore/http-client: *
• phore/theme-coreui: *
• phpunit/phpunit: *

MIT

• Matthias Leuffen

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"];
}