tuum/respond

helpers and responders for PSR7 http/messages.

Saturday, December 2, 2017
by asaokamei
Repository
2 Watchers
0 Stars
78 Installations

PHP
1 Dependents
0 Suggesters
0 Forks
6 Open issues
30 Versions
0 % Grown

The README.md

Tuum/Respond

Tuum/Respond is a framework independent helpers and responders for PSR-7 Http/Message., _(*1)

Still an Alpha Release.
PSR-1, PSR-2, and PSR-4.

License

MIT license, _(*2)

Installation and samples

To install Tuum/Respond, use the composer., _(*3)

$ composer require "tuum/respond"

To see Tuum/Respond working in a sample site, use git and PHP's internal server at public folder as;, _(*4)

$ git clone https://github.com/TuumPHP/Respond
$ cd Respond/public
$ php -S localhost:8888 index.php

and access localhost:8888 by any browser. The sample site uses external bootstrap css and javascript., _(*5)

Overview

Tuum/Respond can be used together with Psr-7 based middlewares and micro-frameworks to compliment extra functionalities for developing ordinary web sites., _(*6)

Helper Classes

Helper classes helps to manage Psr-7 http message objects. For instance,, _(*7)

$bool = ResponseHelper::isRedirect($response);

will evaluate $response to check for redirect response. There are helpers for request and responce., _(*8)

Responder Classes

The responders are the main part of this package., _(*9)

Responders to simplify the composing a response object, by providing various response types such as text, jason, html, or redirection. But more uniquely, the responders enables to transfer data across http requests using sessions and flashes. For instance,, _(*10)

$app = new App(); // some micro-framework app. 

// redirects to /jumped.
$app->get('/jumper', function($request, $response) {
    return Respond::redirect($request, $response)
        ->withMessage('bad input!') // <- set up info.
        ->withInputData(['some' => 'value'])
        ->withInputErrors(['some' => 'bad value'])
        ->toPath('/jumped');
    });

// ...and this is jumped.
$app->get('/jumped', function($request, $response) {
    return Respond::view($request, $response)
        ->asView('template'); // with the 'welcome!' message.
});

Accessing /jumper will redirect to /jumped with the message "welcome!" and other data. These data appears automatically in the second request's view., _(*11)

looks familiar API? I like Laravel very much!, _(*12)

Services

The Psr-7 http/message does not provide all the necessary functionalities to use the responders. You need to supply services that are defined by following interfaces., _(*13)

SessionStorageInterface for session,
ViewStreamInterface for views, and
ErrorViewInterface.

optionaly,, _(*14)

ContainerInterface for containers,

maybe used to provide services., _(*15)

Packages

Currently, Tuum/Respond uses following packages., _(*16)

Zendframework/Zend-Diactoros as a default Psr-7 objects.
Aura/Session for managing session and flash storage.
Tuum/View for rendering a PHP as a template.
Tuum/Form for html form elements and data helpers.
Container-interop/container-interop for container.

Yep, uses home grown views and forms (;´д｀), _(*17)

Responders

The respnders simplfies the composition of response object by using various services and information from $request. There are 3 responders:, _(*18)

View: to create a response with a view body.
Redirect: to create a redirect response.
Error: to create response with error status and view.

Responder Class

There is a Responder class for conveniently access these responders;, _(*19)

use Tuum\Respond\Responder;
$responder = new Responder(
    $view, $redirect, $error
)->withSession($session);

The arguments for the constructors are the each responder., _(*20)

The $session must implements SessionStorageInterface. Session is set after the construction because the scope of the responder maybe different from construction and runtime., _(*21)

There is a static method for building a responder using default classes., _(*22)

use Tuum\Respond\Responder;
$responder = Responder::build(
    ViewStream::forge('view'), 
    ErrorView::forge([...config...])
)->withSession($session);

Access responders like., _(*23)

return $responder->view($request, $response)
    ->with('my', 'key')
    ->asView('view-file');

To start responders, provide $request and $response objects to the methods. If $response is not given, the responder will create a new $response object., _(*24)

Respond Class

The Respond class provides a quick way to create or access these responders using convenient static methods. The trick is, you must register the responder in the $request' attribute., _(*25)

use Tuum\Respond\Respond;
$request = $request->withAttribute(Responder::class, $responder);

Respond::view($request, $response);
// or...
Respond::view($request);

For the simplicity of the code, the subsequent samples use only $request as input., _(*26)

Setting Services for Respond Class

You can register the responder, either in, _(*27)

$request's attribute as Resonder::class, or
using a container which implements ContainerInterface.

To use the container, set up the container, and use RequestHelper::withApp method to set the container in the $request., _(*28)

$app = new Container; // some container. 
$app->set(ViewStreamInterface::class, 
    ViewStream::forge(__DIR__.'/views')
);
$request = RequestHelper::withApp($request, $app);

View Responder

View responder creates basic text, json, or html responces., _(*29)

use Tuum\Respond\Respond;
Respond::view($request)->asText('Hello World');
Respond::view($request)->asJson(['Hello' => 'World']);
Respond::view($request)->asHtml('<h1>Hello World</h1>');
Respond::view($request)->asDownload($fp, 'some.dat');
Respond::view($request)->asFileContents('tuum.pdf', 'application/pdf');

Using Views (Template)

View responder can create responce using view (or template)., _(*30)

Respond::view($request)
    ->with('name', 'value')
    ->withMessage('message')
    ->withAlert('alert-message')
    ->withError('error-message')
    ->asView('view-file');

Similarly, asContent method will render any text content within a template layout if ViewStream object implements it., _(*31)

Respond::view($request)
    ->asContent('<h1>My Content</h1>');

To use Views feature, provide ViewStreamInterface object to the responders., _(*32)

Redirect Responder

Redirect responder creates redirect responce to uri, path, base-path, or referrer., _(*33)

Respond::redirect($request)->toAbsoluteUri($request->getUri()->withPath('jump/to'));
Respond::redirect($request)->toPath('jump/to');
Respond::redirect($request)->toBasePath('to');
Respond::redirect($request)->toReferrer();

Passing Data From Redirect To View

Use Redirect and Respond responders to pass data between requests as,, _(*34)

Respond::redirect($request)
    ->with('extra', 'value')
    ->withInputData(['some' => 'value'])
    ->withInputErrors(['some' => 'error message'])
    ->withError('error-message')
    ->toPath('back/to');

then, receive the data as,, _(*35)

Respond::view($request)
    ->asView('some-view'); // all the data from the previous request.

The data set by using with methods will be stored in a session's flash data; the subsequent Respond::view method will automatically retrieve the flash data and populate them in the template view., _(*36)

To enable this feature, provide SessionStorageInterface object to the responders., _(*37)

Error Responder

Error responder generates a template view based on the status code by using ErrorViewInterface object. Set up the error view, then,, _(*38)

Respond::error($request)->forbidden();

To enable this feature, provide ErrorViewInterface object to the responders., _(*39)

Services

The responders requires many services to operate. These services are stored in $request->withAttribute method., _(*40)

SessionStorageInterface

SessionStorageInterface provides ways to access session and flash data storage, whose API is taken from Aura.Session's segment., _(*41)

using default SessionStorage object

The default implementation uses the Aura.Session., _(*42)

use Tuum\Respond\Service\SessionStorage;

$session = SessionStorage::forge('some-name');
$responder = $responder->withSession($session);

$response = $next($request, $response); // call next
$session->commit();

ViewStreamInterface

The ViewStreamInterface extends Psr-7's StreamInterface to add extra methods for rendering a view/template., _(*43)

withView($view_name, ViewData $data): sets the template file name for the view and render data.
withContent($view_name, ViewData $data): sets the contents of a view and render data. This method maybe used for rendering a static file.

To respond using view resopnder, provide a ViewStream object implementing ViewStreamInterface interface., _(*44)

using default ViewStream object

The default ViewStream class uses Tuum/View and Tuum/Form packages,, _(*45)

$view = ViewStream::forge($view_dir);

where the $view_dir points to the root of the view/template directory, such as __DIR__ . '/views'., _(*46)

ErrorViewInterface

The ErrorViewInterface is a simplified ViewStreamInterface which can render a view based on status code instead of view name as used in ViewStreamInterface., _(*47)

using default ErrorView object

To respond using the error responder, provide an ErrorView object. To use the default set,, _(*48)

$error = ErrorView::forge(
    ViewStream::forge($error_view_dir), [
    'default' => 'errors/error',
    'status' => [
        Error::FILE_NOT_FOUND => 'errors/notFound',
        Error::FORBIDDEN      => 'errors/forbidden',
    ],
    'handler' => true,
]);

The first argument is another ViewStreamInterface object to render a view.
second argument is an options array, which has
- default: default error view name,
- status: error code and associated view name,
- handler: use the ErrorView for catching uncaught exceptions using set_exception_handler.

Yes, you can use the ErrorView object for PHP's set_exception_handler handle as well:, _(*49)
set_exception_handler($error); // catch uncaught exception!!!
  

ContainerInterface

A container maybe used to provide the services to responders. The container must implement ContainerInterface by Container-interop group., _(*50)

Populate the container with the services using interface class name as a key, and set it in the $request using RequestHelper::withApp method, as;, _(*51)

$app = new Container(); // some ContainerInterface...
$app->set(Responder::class, $responder);
$request = RequestHelper::withApp($request, $app);

Helpers

RequestHelper

constants:, _(*52)

APP_NAME:
BASE_PATH: key name for basePath.
PATH_INFO: key name for pathInfo.
SESSION_MANAGER: key name for session.
REFERRER: key name for referrer path.

public static methods., _(*53)

createFromPath: static method to construct a request .
withApp / getApp: manage application or container (ContainerInterface).
getService: a simplified way to get a service from the container.
withBasePath / getBasePath / getPathInfo: manage a base path. pathInfo is the remaining of the entire path minus the base path.
withSessionMgr / getSessionMgr: manage SessionStorageInterface object.
setSession / getSession: set and get values to the session.
setFlash / getCurrFlash / getFlash: set and get values to the flash memory of the current session. getCurrFlash gets the value set in the current request.
withReferrer / getReferrer: getReferer returns a path set by withReferrer, or $_SEVER['HTTP_REFERER'].

ResponseHelper

to-be-written, _(*54)

Views and Template

To use a view/template system, it has to satisfy the followings:, _(*55)

implement ViewStreamInterface,
understand ViewData object.

Currently, only the default ViewStream uses Tuum/View and Tuum/Form matches these criteria., _(*56)

ViewData

Turned out that this ViewData class is one of the center piece of this package, by managing data used for rendering a view template., _(*57)

The ViewData is the core of the responders which is used to transfer data between requests as well as from request to view's renderer., _(*58)

The ViewData manages following data,, _(*59)

ViewData::DATA, set by with method.
ViewData::MESSAGE, set by with{Message|AlertMsg|ErrorMsg} method.
ViewData::INPUTS, set by withInputData method.
ViewData::ERRORS, set by withInputErrors method.

To retrieve the data, use get method as, _(*60)

$data = $viewData->get(ViewData::DATA);

Tuum/Form

Tuum/Form provides helper objects which (not surprisingly) correspond to each of the data in the ViewData. All the helpers are combined into $view object in the template file., _(*61)

setLayout('layouts/layout');
$data = $view->data;
$forms = $view->forms;
$message = $view->message;
$inputs = $view->inputs;

?>

= $forms->text('jumped', $data->jumped)->id()->class('form-control'); ?>
= $errors->get('jumped'); ?>

The example code shows how to use $forms, $data, and $errors., _(*62)

But what about $inputs? It is in the $form object. If the (old) $inputs->get('jumped') value exist, the value is used instead of the given $data->jumped value., _(*63)

The Versions

02/12 2017

3.x-dev

3.9999999.9999999.9999999-dev

helpers and responders for PSR7 http/messages.

library respond

helpers and responders for PSR7 http/messages.

tuum/respond

The README.md

Tuum/Respond

License

Installation and samples

Overview

Helper Classes

Responder Classes

Services

Packages

Responders

Responder Class

Respond Class

Setting Services for Respond Class

View Responder

Using Views (Template)

Redirect Responder

Passing Data From Redirect To View

Error Responder

Services

SessionStorageInterface

using default SessionStorage object

ViewStreamInterface

using default ViewStream object

ErrorViewInterface

using default ErrorView object

ContainerInterface

Helpers

RequestHelper

ResponseHelper

Views and Template

ViewData

Tuum/Form

The Versions

3.x-dev

The Requires

The Development Requires

by Asao

3.0.2

The Requires

The Development Requires

by Asao

3.0.1

The Requires

The Development Requires

by Asao

dev-3.x-dev

The Requires

The Development Requires

by Asao

3.0.0

The Requires

The Development Requires

by Asao

3.0.0-b4

The Requires

The Development Requires

by Asao

3.0.0-b3

The Requires

The Development Requires

by Asao

3.0.0-b2

The Requires

The Development Requires

by Asao

3.0.0-b1

The Requires

The Development Requires

by Asao

0.2.0

The Requires

by Asao

dev-presenter

The Requires

The Development Requires

by Asao

dev-feature/container