README.md

Capsule

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");