nimbly / capsule
Capsule is a simple PSR-7 HTTP message and PSR-17 HTTP factory implementation.
Installs: 2 695 055
Dependents: 3
Suggesters: 0
Security: 0
Stars: 5
Watchers: 2
Forks: 2
Open Issues: 1
Requires
- php: ^8.0
- 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: ^4.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
helper class with HTTP response codes as constants and reason phrases.
$response = new Response(ResponseStatus::NOT_FOUND);
$phrase = ResponseStatus::getPhrase(ResonseStatus::NOT_FOUND); 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.
RequestFactory
, ServerRequestFactory
, ResponseFactory
, StreamFactory
, UploadedFileFactory
, and UriFactory
.