- Notifications
You must be signed in to change notification settings - Fork1
Capsule is a simple PSR-7 HTTP message interface and PSR-17 HTTP factory implementation.
License
nimbly/Capsule
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Capsule is a simplePSR-7 HTTP message interface andPSR-17 HTTP factory implementation.
composer require nimbly/capsule
TheRequest object represents anoutbound HTTP request your application would like to make, typically to be used with a PSR-18 compliant HTTP client.
$request =newRequest("get","https://example.org/books");$response =$httpClient->sendRequest($request);
TheServerRequest object represents anincoming HTTP request into your application, to be used with a PSR-7 compliant HTTP framework or other library.
$serverRequest =newServerRequest("get","https://example.org/books");$response =$framework->dispatch($serverRequest);
Typically, you will want to create aServerRequest instance from the PHP globals space ($_SERVER,$_POST,$_GET,$_FILES, and$_COOKIES) for your incoming requests. TheServerRequestFactory provides a static method to create such an instance.
$serverRequest = ServerRequestFactory::createFromGlobals();$response =$framework->dispatch($serverRequest);
TheServerRequest 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");
TheResponse object represents an HTTP response to either aRequest or aServerRequest action.
$response =newResponse(200,\json_encode(["foo" =>"bar"]), ["Content-Type" =>"application/json"]);
Capsule provides aResponseStatus enum with HTTP response codes and reason phrases.
$response =newResponse(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 createRequest,ServerRequest,Response,Stream,UploadedFile, andUri instances, found in theNimbly\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 =newRequestFactory;$request =$requestFactory->createRequest("get","https://api.example.com");
$serverRequestFactory =newServerRequestFactory;$serverRequest =$serverRequestFactory->createServerRequest("post","https://api.example.com/books");
In addition, theServerRequestFactory provides several static methods for creating server requests.
You can create aServerRequest instance from the PHP globals space ($_POST, $_GET, $_FILES, $_SERVER, and $_COOKIES).
$serverRequest = ServerRequestFactory::createFromGlobals();
You can create a CapsuleServerRequest instance from another PSR-7 ServerRequest instance:
$serverRequest = ServerRequestFactory::createServerRequestFromPsr7($otherServerRequest);
$responseFactory =newResponseFactory;$response =$responseFactory->createResponse(404);
$streamFactory =newStreamFactory;$stream =$streamFactory->createStream(\json_encode($body));
$streamFactory =newStreamFactory;$stream =$streamFactory->createStreamFromFile("/reports/q1.pdf");
$resource =\fopen("https://example.com/reports/q1.pdf","r");$streamFactory =newStreamFactory;$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 =newUploadedFileFactory;$stream = StreamFactory::createFromFile("/tmp/upload");$uploadedFile =$uploadedFileFactory->createUploadedFile($stream,$stream->getSize(),UPLOAD_ERR_OK,"q1_report.pdf","application/pdf");
TheUriFactory allows you to create and parse URIs.
$uriFactory =newUriFactory;$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");
About
Capsule is a simple PSR-7 HTTP message interface and PSR-17 HTTP factory implementation.