PHPackages                             nimbly/capsule - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. nimbly/capsule

ActiveLibrary[HTTP & Networking](/categories/http)

nimbly/capsule
==============

Capsule is a simple PSR-7 HTTP message and PSR-17 HTTP factory implementation.

3.0.1(1y ago)64.0M—4.6%[1 issues](https://github.com/nimbly/Capsule/issues)4MITPHPPHP ^8.2CI passing

Since Apr 5Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/nimbly/Capsule)[ Packagist](https://packagist.org/packages/nimbly/capsule)[ RSS](/packages/nimbly-capsule/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (28)Used By (4)

Capsule
=======

[](#capsule)

[![Latest Stable Version](https://camo.githubusercontent.com/9b5ad2c946672305fabfec91f9ed39a1697d8406fb7e12cc2151dcd6a1afa129/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e696d626c792f63617073756c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nimbly/capsule)[![GitHub Workflow Status](https://camo.githubusercontent.com/c6cf937f5cc5a0bcb423944ad1eb9ad3a69a33f87ed4463ee4824743416a1b85/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6e696d626c792f63617073756c652f636f7665726167652e796d6c3f7374796c653d666c61742d737175617265)](https://github.com/nimbly/Capsule/actions/workflows/coverage.yml)[![Codecov branch](https://camo.githubusercontent.com/4f36dd3f6be0f195ead7167be23e212782875edbfa3a9f11c933172be72df44d/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6e696d626c792f63617073756c652f6d61737465723f7374796c653d666c61742d737175617265)](https://app.codecov.io/github/nimbly/Capsule)[![License](https://camo.githubusercontent.com/971e3c878b5adebddc3c9903db55e1681b4a996f02e5653bdb83bcafa53f137c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e696d626c792f63617073756c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nimbly/capsule)

Capsule is a simple [PSR-7](https://www.php-fig.org/psr/psr-7/) HTTP message interface and [PSR-17](https://www.php-fig.org/psr/psr-17) HTTP factory implementation.

Install
-------

[](#install)

```
composer require nimbly/capsule
```

HTTP Message (PSR-7)
--------------------

[](#http-message-psr-7)

### Request

[](#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

[](#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

[](#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

[](#helpers)

The `ServerRequest` instance offers helpers to test for and access various request property parameters.

#### Parsed body helpers

[](#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

[](#query-param-helpers)

```
if( $serverRequest->hasQueryParam("foo") ){
	// Do the foo...
}

$foo = $serverRequest->getQueryParam("foo");
```

#### Uploaded file helpers

[](#uploaded-file-helpers)

```
if( $serverRequest->hasUploadedFile("avatar") ){
	// Do something
}

$avatar = $serverRequest->getUploadedFile("avatar");
```

### Response

[](#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

[](#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)
---------------------

[](#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)

```
$requestFactory = new RequestFactory;
$request = $requestFactory->createRequest("get", "https://api.example.com");
```

### ServerRequestFactory

[](#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

[](#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

[](#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)

```
$responseFactory = new ResponseFactory;
$response = $responseFactory->createResponse(404);
```

### StreamFactory

[](#streamfactory)

#### Create a stream from string content

[](#create-a-stream-from-string-content)

```
$streamFactory = new StreamFactory;
$stream = $streamFactory->createStream(\json_encode($body));
```

#### Create a stream from a file

[](#create-a-stream-from-a-file)

```
$streamFactory = new StreamFactory;
$stream = $streamFactory->createStreamFromFile("/reports/q1.pdf");
```

#### Create a stream from any resource

[](#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

[](#uploadedfilefactory)

#### Create an UploadedFile instance

[](#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

[](#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");
```

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance48

Moderate activity, may be stable

Popularity46

Moderate usage in the ecosystem

Community16

Small or concentrated contributor base

Maturity82

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 97.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~86 days

Recently: every ~69 days

Total

26

Last Release

446d ago

Major Versions

0.11 → 1.02020-03-10

1.1.2 → 2.0.x-dev2022-10-18

2.x-dev → 3.0.x-dev2024-09-21

PHP version history (4 changes)0.5PHP >=7.2

1.1PHP >=7.3|^8.0

2.0.x-devPHP ^8.0

3.0.x-devPHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/723164?v=4)[Brent Scheffler](/maintainers/brentscheffler)[@brentscheffler](https://github.com/brentscheffler)

---

Top Contributors

[![brentscheffler](https://avatars.githubusercontent.com/u/723164?v=4)](https://github.com/brentscheffler "brentscheffler (161 commits)")[![8ctopus](https://avatars.githubusercontent.com/u/13252042?v=4)](https://github.com/8ctopus "8ctopus (3 commits)")[![roukmoute](https://avatars.githubusercontent.com/u/2140469?v=4)](https://github.com/roukmoute "roukmoute (1 commits)")

---

Tags

http-messageshttp-requestshttp-responsepsr-17psr-7

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/nimbly-capsule/health.svg)

```
[![Health](https://phpackages.com/badges/nimbly-capsule/health.svg)](https://phpackages.com/packages/nimbly-capsule)
```

###  Alternatives

[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.0B3.2k](/packages/guzzlehttp-psr7)[spiral/roadrunner-http

RoadRunner: HTTP and PSR-7 worker

799.2M48](/packages/spiral-roadrunner-http)[laudis/neo4j-php-client

Neo4j-PHP-Client is the most advanced PHP Client for Neo4j

184616.9k31](/packages/laudis-neo4j-php-client)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[mezzio/mezzio-authentication-oauth2

OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications.

28483.0k2](/packages/mezzio-mezzio-authentication-oauth2)[art4/requests-psr18-adapter

Use WordPress/Requests as a PSR-18 HTTP client

153.3k](/packages/art4-requests-psr18-adapter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)