Capsule is a simple PSR-7 HTTP message interface and PSR-17 HTTP factory implementation.
composer require nimbly/capsuleThe Request object represents an outbound HTTP request your application would like to make, typically to be used with a PSR-18 compliant HTTP client.
$request = new Request("get", "https://example.org/books");
$response = $httpClient->sendRequest($request);The ServerRequest object represents an incoming HTTP request into your application, to be used with a PSR-7 compliant HTTP framework or other library.
$serverRequest = new ServerRequest("get", "https://example.org/books");
$response = $framework->dispatch($serverRequest);Typically, you will want to create a ServerRequest instance from the PHP globals space ($_SERVER, $_POST, $_GET, $_FILES, and $_COOKIES) for your incoming requests. The ServerRequestFactory provides a static method to create such an instance.
$serverRequest = ServerRequestFactory::createFromGlobals();
$response = $framework->dispatch($serverRequest);The ServerRequest instance offers helpers to test for and access various request property parameters.
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");The Response object represents an HTTP response to either a Request or a ServerRequest action.
$response = new Response(200, \json_encode(["foo" => "bar"]), ["Content-Type" => "application/json"]);Capsule provides a ResponseStatus enum with HTTP response codes and reason phrases.
$response = new Response(ResponseStatus::NOT_FOUND));$phrase = ResponseStatus::NOT_FOUND->getPhrase();
echo $phrase; // Outputs "Not Found"Capsule includes a set of PSR-17 factory classes to be used to create Request, ServerRequest, Response, Stream, UploadedFile, and Uri instances, found in the Nimbly\Capsule\Factory namespace. These factories are typically used with other libraries that are PSR-7 agnostic. They're also useful for creating mocked instances in unit testing.
$requestFactory = new RequestFactory;
$request = $requestFactory->createRequest("get", "https://api.example.com");$serverRequestFactory = new ServerRequestFactory;
$serverRequest = $serverRequestFactory->createServerRequest("post", "https://api.example.com/books");In addition, the ServerRequestFactory provides several static methods for creating server requests.
You can create a ServerRequest instance from the PHP globals space ($_POST, $_GET, $_FILES, $_SERVER, and $_COOKIES).
$serverRequest = ServerRequestFactory::createFromGlobals();You can create a Capsule ServerRequest instance from another PSR-7 ServerRequest instance:
$serverRequest = ServerRequestFactory::createServerRequestFromPsr7($otherServerRequest);$responseFactory = new ResponseFactory;
$response = $responseFactory->createResponse(404);$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);Alternatively, these methods are also available statically:
// 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 = new UploadedFileFactory;
$stream = StreamFactory::createFromFile("/tmp/upload");
$uploadedFile = $uploadedFileFactory->createUploadedFile(
$stream,
$stream->getSize(),
UPLOAD_ERR_OK,
"q1_report.pdf",
"application/pdf"
);The UriFactory allows you to create and parse URIs.
$uriFactory = new UriFactory;
$uri = $uriFactory->createUri("https://api.example.com/v1/books?a=Kurt+Vonnegut");This method is also available statically:
$uri = UriFactory::createFromString("https://api.example.com/v1/books?a=Kurt+Vonnegut");