nimbly / capsule
Capsule is a simple PSR-7 HTTP message and PSR-17 HTTP factory implementation.
Installs: 2 894 530
Dependents: 3
Suggesters: 0
Security: 0
Stars: 5
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: ^8.2
- psr/http-factory: ^1.0
- psr/http-message: ^1.0|^2.0
Requires (Dev)
- phpunit/phpunit: ^9.0
- symfony/var-dumper: ^4.3
- vimeo/psalm: ^5.0
Provides
README
Capsule is a simple PSR-7 HTTP message interface and PSR-17 HTTP factory implementation.
Install
composer require nimbly/capsule
HTTP Message (PSR-7)
Request
The 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);
ServerRequest
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);
Creating from globals
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);
Helpers
The ServerRequest
instance offers helpers to test for and access various request property parameters.
Parsed body helpers
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"]);
Query param helpers
if( $serverRequest->hasQueryParam("foo") ){ // Do the foo... } $foo = $serverRequest->getQueryParam("foo");
Uploaded file helpers
if( $serverRequest->hasUploadedFile("avatar") ){ // Do something } $avatar = $serverRequest->getUploadedFile("avatar");
Response
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"]);
Response Status
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"
HTTP Factory (PSR-17)
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
$requestFactory = new RequestFactory; $request = $requestFactory->createRequest("get", "https://api.example.com");
ServerRequestFactory
$serverRequestFactory = new ServerRequestFactory; $serverRequest = $serverRequestFactory->createServerRequest("post", "https://api.example.com/books");
In addition, the ServerRequestFactory
provides several static methods for creating server requests.
Creating ServerRequest from PHP globals
You can create a ServerRequest
instance from the PHP globals space ($_POST, $_GET, $_FILES, $_SERVER, and $_COOKIES).
$serverRequest = ServerRequestFactory::createFromGlobals();
Creating ServerRequest from another PSR-7 ServerRequest
You can create a Capsule ServerRequest
instance from another PSR-7 ServerRequest instance:
$serverRequest = ServerRequestFactory::createServerRequestFromPsr7($otherServerRequest);
ResponseFactory
$responseFactory = new ResponseFactory; $response = $responseFactory->createResponse(404);
StreamFactory
Create a stream from string content
$streamFactory = new StreamFactory; $stream = $streamFactory->createStream(\json_encode($body));
Create a stream from a file
$streamFactory = new StreamFactory; $stream = $streamFactory->createStreamFromFile("/reports/q1.pdf");
Create a stream from any resource
$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
Create an UploadedFile instance
$uploadedFileFactory = new UploadedFileFactory; $stream = StreamFactory::createFromFile("/tmp/upload"); $uploadedFile = $uploadedFileFactory->createUploadedFile( $stream, $stream->getSize(), UPLOAD_ERR_OK, "q1_report.pdf", "application/pdf" );
UriFactory
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");