README

胶囊是一个简单的 PSR-7 HTTP消息接口和 PSR-17 HTTP工厂实现。

安装

composer require nimbly/capsule

HTTP消息（PSR-7）

请求

Request 对象代表应用程序想要发出的一个 出站 HTTP请求，通常用于与PSR-18兼容的HTTP客户端一起使用。

$request = new Request("get", "https://example.org/books");

$response = $httpClient->sendRequest($request);

ServerRequest

ServerRequest 对象代表进入应用程序的一个 入站 HTTP请求，用于与PSR-7兼容的HTTP框架或其他库一起使用。

$serverRequest = new ServerRequest("get", "https://example.org/books");

$response = $framework->dispatch($serverRequest);

从全局变量创建

通常，您将希望从PHP全局空间（$_SERVER、$_POST、$_GET、$_FILES 和 $_COOKIES）为您的入站请求创建一个 ServerRequest 实例。 ServerRequestFactory 提供了一个静态方法来创建此类实例。

$serverRequest = ServerRequestFactory::createFromGlobals();

$response = $framework->dispatch($serverRequest);

辅助工具

ServerRequest 实例提供了一些辅助工具来测试和访问各种请求属性参数。

解析主体辅助工具

if( $serverRequest->hasBodyParam("foo") ){
	// Do the foo...
}

/**
 * Get a single param ("bar") from the parsed body.
 */
$bar = $serverRequest->getBodyParam("bar");

/**
 * Get *only* the provided params from the parsed body.
 */
$serverRequest->onlyBodyParams(["foo", "bar"]);

/**
 * Get all params from the parsed body *except* those provided.
 */
$serverRequest->exceptBodyParams(["foo", "bar"]);

查询参数辅助工具

if( $serverRequest->hasQueryParam("foo") ){
	// Do the foo...
}

$foo = $serverRequest->getQueryParam("foo");

上传文件辅助工具

if( $serverRequest->hasUploadedFile("avatar") ){
	// Do something
}

$avatar = $serverRequest->getUploadedFile("avatar");

响应

Response 对象代表对 Request 或 ServerRequest 操作的HTTP响应。

$response = new Response(200, \json_encode(["foo" => "bar"]), ["Content-Type" => "application/json"]);

响应状态

Capsule提供了一个包含HTTP响应代码和原因短语的 ResponseStatus 枚举。

$response = new Response(ResponseStatus::NOT_FOUND));

$phrase = ResponseStatus::NOT_FOUND->getPhrase();

echo $phrase; // Outputs "Not Found"

HTTP工厂（PSR-17）

Capsule包含一组PSR-17工厂类，用于创建位于 Nimbly\Capsule\Factory 命名空间中的 Request、ServerRequest、Response、Stream、UploadedFile 和 Uri 实例。这些工厂通常与其他不遵循PSR-7的库一起使用。它们在单元测试中创建模拟实例时也非常有用。

RequestFactory

$requestFactory = new RequestFactory;
$request = $requestFactory->createRequest("get", "https://api.example.com");

ServerRequestFactory

$serverRequestFactory = new ServerRequestFactory;
$serverRequest = $serverRequestFactory->createServerRequest("post", "https://api.example.com/books");

此外，ServerRequestFactory 还提供了几个静态方法用于创建服务器请求。

从PHP全局变量创建ServerRequest

您可以从PHP全局空间（$_POST、$_GET、$_FILES、$_SERVER和$_COOKIES）创建一个 ServerRequest 实例。

$serverRequest = ServerRequestFactory::createFromGlobals();

从另一个PSR-7 ServerRequest创建ServerRequest

您可以从另一个PSR-7 ServerRequest 实例创建一个Capsule ServerRequest 实例。

$serverRequest = ServerRequestFactory::createServerRequestFromPsr7($otherServerRequest);

ResponseFactory

$responseFactory = new ResponseFactory;
$response = $responseFactory->createResponse(404);

StreamFactory

从字符串内容创建流

$streamFactory = new StreamFactory;
$stream = $streamFactory->createStream(\json_encode($body));

从文件创建流

$streamFactory = new StreamFactory;
$stream = $streamFactory->createStreamFromFile("/reports/q1.pdf");

从任何资源创建流

$resource = \fopen("https://example.com/reports/q1.pdf", "r");

$streamFactory = new StreamFactory;
$stream = $streamFactory->createStreamFromResource($resource);

此外，这些方法也可以静态调用

// Create a stream from a string.
$stream = StreamFactory::createFromString(\json_encode($body));

// Create a stream from a local file.
$stream = StreamFactory::createFromFile("/reports/q1.pdf");

// Create a stream from a PHP resource.
$resource = \fopen("https://example.com/reports/q1.pdf", "r");
$stream = StreamFactory::createFromResource($resource);

UploadedFileFactory

创建一个UploadedFile实例

$uploadedFileFactory = new UploadedFileFactory;

$stream = StreamFactory::createFromFile("/tmp/upload");

$uploadedFile = $uploadedFileFactory->createUploadedFile(
    $stream,
    $stream->getSize(),
    UPLOAD_ERR_OK,
    "q1_report.pdf",
    "application/pdf"
);

UriFactory

UriFactory 允许您创建和解析URI。

$uriFactory = new UriFactory;
$uri = $uriFactory->createUri("https://api.example.com/v1/books?a=Kurt+Vonnegut");

此方法也可静态调用

$uri = UriFactory::createFromString("https://api.example.com/v1/books?a=Kurt+Vonnegut");