README

Germania KG · Responder

安装

$ composer require germania-kg/responder

Responder 类

• TwigResponder
• JsonResponder
• ErrorResponder

接口

ResponderInterface

Germania\Responder\ResponderInterface 提供一个 createResponse 方法，该方法接受数据以创建一个 PSR-7 响应。数据可以是任何类型。

实现类也必须是 可调用的 并实现具有相同签名的 invoke 函数。

• 如果传递的数据不正确，则应抛出 ResponderInvalidArgumentException。
• 如果在执行过程中发生错误，则应抛出 ResponderRuntimeException。

public function createResponse( $data ) : ResponseInterface;
public function __invoke( $data ) : ResponseInterface;

ResponderExceptionInterface

Germania\Responder\ResponderExceptionInterface 是所有 Responder 异常共有的基接口。请参阅 异常 部分。

TwigResponder

构造函数接受一个 Twig 环境、包含模板的数组字段名称以及可选的默认 上下文变量 数组。

您可以可选地传递一个自定义的 PSR-17 响应工厂，默认情况下将使用 slim/psr7 的响应工厂。

传递给 createResponse 方法的模板 $data 将与 $default_context 合并。

设置

<?php
use Germania\Responder\TwigResponder;

// Have Twig\Environment at hand
$twig = ...;
$responder = new TwigResponder($twig, "template");

// These are optional
$default_context = array();
$psr17 = new \Nyholm\Psr7\Factory\Psr17Factory;
$responder = new TwigResponder($twig, "template", $default_context, $psr17);

配置

$responder->setTwig( $twig );
$responder->setTemplateField('template');
$responder->setDefaultContext( array('another' => 'data') );
$responder->setResponseFactory($psr17);

# Fallback when context lacks 'template' element
$responder->setDefaultTemplate('website.tpl');

用法

$data = array(
	'template' => 'website.tpl',
  'foo' => 'bar'
)

// These are equal:
$response = $responder->createResponse($data);
$response = $responder($data);

JsonResponder

从给定数据创建 JSON 响应。实现 ResponderInterface。响应将具有 Content-type: application/json。

您可以可选地传递一个自定义的 PSR-17 响应工厂，默认情况下将使用 slim/psr7 的响应工厂。

设置

<?php
use Germania\Responder\JsonResponder;
use Germania\Responder\ResponderExceptionInterface;
use Slim\Psr7\Factory\ResponseFactory;

$json = \JSON_PRETTY_PRINT;
$psr17 = new ResponseFactory; // Optional

$responder = new JsonResponder($json);
$responder = new JsonResponder($json, $psr17);

配置

$responder->setJsonOptions( \JSON_PRETTY_PRINT );
$responder->setResponseContentType('application/json');
$responder->setResponseFactory($psr17);

用法

try {
  $data = array('foo' => 'bar');
  
  // These
  $response = $responder->createResponse($data);
  $response = $responder($data);

  // Psr\Http\Message\ResponseInterface  
  return $response;
}
catch(ResponderExceptionInterface $e) {
  echo $e->getMessage();
}

CallbackResponder

此类将一个 回调 应用到给定数据，然后再将其传递给任何 内部响应器，该响应器必须是 ResponderInterface 的实例。

<?php
use Germania\Responder\CallbackResponder;
use Germania\Responder\JsonResponder;

// Do-nothing callback for demonstration purposes
$callback = function($item) { return $item; };
// Any kind of ResponderInterface will do
$inner = new JsonResponder();

$responder = new CallbackResponder($callback, $inner);

配置

$responder->setCallback(function($item) { return $item; });
$responder->setResponder($other_responder);

NoContentResponder

产生带有 204 状态的空响应。

<?php
use Germania\Responder\NoContentResponder;

$responder = new NoContentResponder();

ErrorResponder

ErrorResponder 修改 Throwables 并作为另一个 ResponderInterface 的装饰器。它扩展了 ResponderDecoratorAbstract 并实现了 ResponderInterface。

传递给 createResponse 的错误将转换为包含错误及其所有之前错误的数组（取决于 debug 模式）。然后该数组将传递给内部响应器。

默认响应状态码为 500，可以在调用时进行调整。

扩展 ResponderDecoratorAbstract 并实现 ResponderInterface。

设置

<?php
use Germania\Responder\ErrorResponder;
use Germania\Responder\JsonResponder;

$debug = true;
$inner_responder = new JsonResponder(\JSON_PRETTY_PRINT);

$error_responder = new ErrorResponder($debug, $inner_responder);

配置

$responder->setDebug( false );

用法

可选地传递一个自定义状态码；默认为 500。

try {
  // Throw something here
}
catch(\Throwable $e) {
  $response = $error_responder->createResponse($e);
  echo $response->getStatusCode(); // 500
  
  $response = $error_responder->createResponse($e, 503);  
  $response = $error_responder->createResponse($e, 400);

	// Psr\Http\Message\ResponseInterface    
  return $response;
}

$responder->setDebug( false );

响应示例

这些示例假设使用 JsonResponder 作为内部响应器。注意 errors 元素：它包含错误对象，以及可选地，其之前的错误。

{
  "errors": [
    {
      "type": "RuntimeException",
      "message": "Boo!",
      "code": 0
    }
  ]
}

当 debug 为 TRUE 时，包括之前的异常及其发生的位置

{
  "errors": [
    {
      "type": "Exception",
      "message": "Outer",
      "code": 0,
      "location": "\/path\/to\/file.php:67"
    },
    {
      "type": "MyLibrary\/CustomException",
      "message": "Boo!",
      "code": 0,
      "location": "\/path\/to\/file.php:64"
    }
  ]
}

异常

• Germania\Responder\ResponderExceptionInterface
• Germania\Responder\ResponderInvalidArgumentException 扩展了 \InvalidArgumentException 并实现了 ResponderExceptionInterface。
• Germania\Responder\ResponderRuntimeException 扩展了 \RuntimeException 并实现了 ResponderExceptionInterface。

示例：处理错误

<?php
use Germania\Responder\ResponderInvalidArgumentException;
use Germania\Responder\ResponderRuntimeException;
use Germania\Responder\ResponderExceptionInterface;

try {
  $data = array('foo' => 'bar');
  
  // These are equal:
  $response = $responder->createResponse($data);
  $response = $responder($data);

  // Psr\Http\Message\ResponseInterface  
  return $response;
}
catch(ResponderInvalidArgumentException $e) {
  // $data has been invalid
}
catch(ResponderRuntimeException $e) {
  // Something bad happened
}
catch(ResponderExceptionInterface $e) {
  // Catch any other Responder exceptions
}

特质

ResponderTrait

在您的类中使用 Germania\Responder\ResponderTrait

// @var ResponderInterface
protected $responder;

// @return ResponderInterface|null
public function getResponder() : ?ResponderInterface;

// @param ResponderInterface $responder
// @return static
public function setResponder( ResponderInterface $responder );

ResponseFactoryTrait

TwigResponder 和 JsonResponder 使用 Germania\Responder\ResponseFactoryTrait。默认情况下，它们使用 nyholm/psr7 的响应工厂。

// @var ResponseFactory
public $response_factory;

// @param ResponseFactoryInterface $response_factory
// @return static
public function setResponseFactory(ResponseFactoryInterface $response_factory ) : static

// @return ResponseFactoryInterface  
public function getResponseFactory() : ResponseFactoryInterface;

开发

$ git clone git@github.com:GermaniaKG/Responder.git
$ cd Responder
$ composer install