Nyholm Psr7

https://github.com/nyholm/psr7
Admin
Nyholm Psr7 is a super lightweight, strict, and fast PSR-7 implementation for PHP with complete...
Tokens:73,760
Snippets:566
Trust Score:10
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install laminas-httphandlerrunner for emitting responses

Source: https://github.com/nyholm/psr7/blob/master/README.md

Install the laminas/laminas-httphandlerrunner package to emit PSR-7 responses.

```bash
composer require laminas/laminas-httphandlerrunner
```

--------------------------------

### withMethod usage example

Source: https://github.com/nyholm/psr7

Changes the HTTP method from GET to PATCH and prints it. Output is 'PATCH'.

```php
$r = (new Request('GET', '/'))->withMethod('PATCH');
echo $r->getMethod(); // PATCH
```

--------------------------------

### Install nyholm/psr7-server for server requests

Source: https://github.com/nyholm/psr7/blob/master/README.md

Install the nyholm/psr7-server package to create server requests from PHP superglobals.

```bash
composer require nyholm/psr7-server
```

--------------------------------

### Install Buzz HTTP client for sending requests

Source: https://github.com/nyholm/psr7/blob/master/README.md

Install the kriswallsmith/buzz package, a PSR-18 HTTP client, to send requests with Nyholm PSR-7.

```bash
composer require kriswallsmith/buzz
```

--------------------------------

### createServerRequest usage example

Source: https://github.com/nyholm/psr7

Example of creating a server request with the factory, passing the method, URI, and server parameters.

```php
$serverRequest = $factory->createServerRequest('POST', '/form', $_SERVER);
```

--------------------------------

### Create stream from file example

Source: https://github.com/nyholm/psr7

Example usage of createStreamFromFile to open a file and output its size.

```php
$stream = $factory->createStreamFromFile('/tmp/data.txt');
echo $stream->getSize();
```

--------------------------------

### createUri usage example

Source: https://github.com/nyholm/psr7

Creates a URI from a string and echoes it, producing the same string.

```php
$uri = $factory->createUri('https://example.com/path');
echo (string) $uri; // https://example.com/path
```

--------------------------------

### Create a request with HttplugFactory

Source: https://github.com/nyholm/psr7

Example of using createRequest to create a GET request to http://example.com.

```php
$factory = new HttplugFactory();
$request = $factory->createRequest('GET', 'http://example.com');
```

--------------------------------

### Create stream from resource example

Source: https://github.com/nyholm/psr7

Example usage of createStreamFromResource with fopen to create a stream from a file resource.

```php
$stream = $factory->createStreamFromResource(fopen('/tmp/data.txt', 'r'));
```

--------------------------------

### withUserInfo() usage example

Source: https://github.com/nyholm/psr7

Sets user info 'john' with password 's3cret' and outputs the resulting URI.

```php
$uri = (new Uri('http://example.com'))->withUserInfo('john', 's3cret');
echo (string) $uri; // http://john:s3cret@example.com
```

--------------------------------

### createStream usage example

Source: https://github.com/nyholm/psr7

Creates a stream with content 'foobar' and echoes it, outputting 'foobar'.

```php
$stream = $factory->createStream('foobar');
echo (string) $stream; // foobar
```

--------------------------------

### Usage example for withQuery and withFragment

Source: https://github.com/nyholm/psr7

Shows how to chain withQuery and withFragment on a Uri instance. The resulting string encodes spaces as %20 in both query and fragment.

```php
$uri = (new Uri('http://example.com'))
    ->withQuery('a=1 b')
    ->withFragment('sec tion');
echo (string) $uri; // http://example.com?a=1%20b#sec%20tion

```

--------------------------------

### withPath usage example

Source: https://github.com/nyholm/psr7

Shows how to set a path containing a space; the space is percent-encoded to %20 in the string representation.

```php
$uri = (new Uri('http://example.com'))->withPath('/a b/c');
echo (string) $uri; // http://example.com/a%20b/c
```

--------------------------------

### Install Nyholm PSR-7 via Composer

Source: https://github.com/nyholm/psr7/blob/master/README.md

Install the nyholm/psr7 package using Composer. If using Symfony Flex, message factories are automatically registered as services.

```bash
composer require nyholm/psr7
```

--------------------------------

### withUri usage example

Source: https://github.com/nyholm/psr7

Replaces the request URI and prints the new URI and Host header. Output is 'https://b.example.com' and 'b.example.com'.

```php
$r = (new Request('GET', 'https://a.example.com'))->withUri(new Uri('https://b.example.com'));
echo (string) $r->getUri(); // https://b.example.com
var_dump($r->getHeaderLine('Host')); // b.example.com
```

--------------------------------

### Response withAddedHeader and getHeaderLine Example

Source: https://github.com/nyholm/psr7

Shows how to create a Response with headers and body, add a header, and retrieve header and body values.

```php
$response = (new Response(200, ['Content-Type' => 'text/html'], '<h1>hi</h1>'))
    ->withAddedHeader('Set-Cookie', 'session=abc');
echo $response->getHeaderLine('Content-Type'); // text/html
echo (string) $response->getBody();            // <h1>hi</h1>
```

--------------------------------

### Example (via Nyholm\Psr7\Request)

Source: https://github.com/nyholm/psr7

Demonstrates usage of header manipulation methods on a Request object.

```APIDOC
## Example (via Nyholm\Psr7\Request)

### Description
Demonstrates usage of header manipulation methods on a Request object.

### Code
```php
use Nyholm\Psr7\Request;

$r = (new Request('GET', '/'))
    ->withHeader('Content-Type', 'application/json')
    ->withAddedHeader('Accept', 'application/json')
    ->withAddedHeader('Accept', 'text/html');

echo $r->getHeaderLine('Accept');        // application/json, text/html
echo $r->getHeader('content-type')[0];   // application/json  (lookup is case-insensitive)

try {
    $r->withHeader("Bad Header\n", 'x'); // invalid token chars
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Header name must be an RFC 7230 compatible string
}
```
```

--------------------------------

### withScheme() usage example

Source: https://github.com/nyholm/psr7

Changes the scheme from http to https and outputs the resulting URI.

```php
$uri = (new Uri('http://example.com'))->withScheme('https');
echo (string) $uri; // https://example.com
```

--------------------------------

### createUploadedFile usage example

Source: https://github.com/nyholm/psr7

Creates an uploaded file from a stream, passing null for size, UPLOAD_ERR_OK, and client metadata.

```php
$stream = $factory->createStream(file_get_contents('/tmp/photo.jpg'));
$upload = $factory->createUploadedFile($stream, null, UPLOAD_ERR_OK, 'photo.jpg', 'image/jpeg');
```

--------------------------------

### withUploadedFiles usage example

Source: https://github.com/nyholm/psr7

Creates an UploadedFile and attaches it to a ServerRequest, then retrieves the client filename.

```php
use Nyholm\Psr7\UploadedFile;

$file = new UploadedFile('/tmp/phpXYZ', 42, UPLOAD_ERR_OK, 'photo.jpg', 'image/jpeg');
$request = (new ServerRequest('POST', '/upload'))->withUploadedFiles(['photo' => $file]);
echo $request->getUploadedFiles()['photo']->getClientFilename(); // photo.jpg
```

--------------------------------

### getPath() usage examples

Source: https://github.com/nyholm/psr7

Shows how getPath() normalizes paths: adds a leading slash when authority is present and reduces multiple leading slashes to one.

```php
echo (new Uri('https://example.comfoo'))->getPath(); // /foo
echo (new Uri('//example.com//a//b'))->getPath();    // /a//b (leading slashes reduced)
```

--------------------------------

### getMetadata usage example

Source: https://github.com/nyholm/psr7

Fetches the 'uri' metadata key (returns a string) and an unknown key (returns null).

```php
$stream = Stream::create('data');
var_dump($stream->getMetadata('uri'));     // string
var_dump($stream->getMetadata('unknown')); // null
```

--------------------------------

### moveTo() usage example

Source: https://github.com/nyholm/psr7

Moves an uploaded file to a destination directory. The target path must be a non-empty string.

```php
$upload = new UploadedFile('/tmp/phpABC123', 2048, UPLOAD_ERR_OK, 'report.pdf');
$upload->moveTo(__DIR__ . '/uploads/report.pdf');
```

--------------------------------

### Get host with getHost

Source: https://github.com/nyholm/psr7

Returns the lower-cased host without port.

```php
public function getHost(): string   // src/Uri.php:105
```

--------------------------------

### getContents usage example

Source: https://github.com/nyholm/psr7

Creates a stream, seeks to position 3, and outputs the remaining contents 'bar'.

```php
$stream = Stream::create('foobar');
$stream->seek(3);
echo $stream->getContents(); // bar
```

--------------------------------

### moveTo() error handling example (moved twice)

Source: https://github.com/nyholm/psr7

Attempts to move the same file twice and catches the RuntimeException with message 'Cannot retrieve stream after it has already been moved'.

```php
$upload = new UploadedFile('/tmp/phpABC123', 2048, UPLOAD_ERR_OK, 'report.pdf');
$upload->moveTo('/tmp/first.pdf');
try {
    $upload->moveTo('/tmp/second.pdf');
} catch (\RuntimeException $e) {
    echo $e->getMessage(); // Cannot retrieve stream after it has already been moved
}
```

--------------------------------

### Usage example for withAttribute and withoutAttribute

Source: https://github.com/nyholm/psr7

Shows chaining withAttribute to set attributes, retrieving them with getAttribute (including a fallback), and removing one with withoutAttribute. After removal, getAttributes returns only ['id' => 42].

```php
$route = (new ServerRequest('GET', '/items/42'))
    ->withAttribute('id', 42)
    ->withAttribute('handler', 'items.show');

echo $route->getAttribute('id');                                    // 42
echo $route->getAttribute('missing', 'fallback');                   // fallback
$route = $route->withoutAttribute('handler');
var_dump($route->getAttributes());                                  // ['id' => 42]
```

--------------------------------

### withPort usage example

Source: https://github.com/nyholm/psr7

Shows how to set a valid port and the error message when the port is out of range. The first call returns 'https://example.com:8443'; the second throws an \InvalidArgumentException with message 'Invalid port: 70000. Must be between 0 and 65535'.

```php
$uri = (new Uri('https://example.com'))->withPort(8443);
echo (string) $uri; // https://example.com:8443

try {
    (new Uri('https://example.com'))->withPort(70000);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Invalid port: 70000. Must be between 0 and 65535
}
```

--------------------------------

### withQueryParams usage example

Source: https://github.com/nyholm/psr7

Sets query parameters on a ServerRequest and retrieves the page value.

```php
$request = (new ServerRequest('GET', '/?page=1'))->withQueryParams(['page' => 3]);
echo $request->getQueryParams()['page']; // 3
```

--------------------------------

### Example using Nyholm\Psr7\Request

Source: https://github.com/nyholm/psr7

Shows how to use withHeader, withAddedHeader, getHeaderLine, and getHeader on a Request. Demonstrates case-insensitive header lookup and catching InvalidArgumentException for invalid header names.

```php
use Nyholm\Psr7\Request;

$r = (new Request('GET', '/'))
    ->withHeader('Content-Type', 'application/json')
    ->withAddedHeader('Accept', 'application/json')
    ->withAddedHeader('Accept', 'text/html');

echo $r->getHeaderLine('Accept');        // application/json, text/html
echo $r->getHeader('content-type')[0];   // application/json  (lookup is case-insensitive)

try {
    $r->withHeader("Bad Header\n", 'x'); // invalid token chars
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Header name must be an RFC 7230 compatible string
}
```

--------------------------------

### getStream() usage example

Source: https://github.com/nyholm/psr7

Creates an UploadedFile with a valid upload and prints the stream contents. The output is the file contents.

```php
$upload = new UploadedFile('/tmp/phpABC123', 2048, UPLOAD_ERR_OK, 'report.pdf');
echo (string) $upload->getStream(); // file contents
```

--------------------------------

### withRequestTarget usage example

Source: https://github.com/nyholm/psr7

Sets an asterisk-form request target on an OPTIONS request and prints it. Output is '*'.

```php
$r = (new Request('OPTIONS', 'https://example.com'))->withRequestTarget('*');
echo $r->getRequestTarget(); // *
```

--------------------------------

### Create and reuse URI with HttplugFactory

Source: https://github.com/nyholm/psr7

Example of creating a URI and reusing it; createUri returns the same instance when passed a UriInterface, as verified by var_dump.

```php
$uri = $factory->createUri('https://example.com');
$same = $factory->createUri($uri);   // identical instance
var_dump($uri === $same);            // true
```

--------------------------------

### Stream::__toString usage example

Source: https://github.com/nyholm/psr7

Creates a stream with 'foobar' and casts it to string, outputting 'foobar'.

```php
$stream = Stream::create('foobar');
echo (string) $stream; // foobar
```

--------------------------------

### getClientMediaType usage example

Source: https://github.com/nyholm/psr7

Creates an UploadedFile with filename and media type, then echoes the media type as image/png.

```php
$upload = new UploadedFile('/tmp/x', 1, UPLOAD_ERR_OK, 'img.png', 'image/png');
echo $upload->getClientMediaType(); // image/png
```

--------------------------------

### Get user info with getUserInfo

Source: https://github.com/nyholm/psr7

Returns the 'user[:password]' part without the trailing '@'.

```php
public function getUserInfo(): string   // src/Uri.php:100
```

--------------------------------

### getRequestTarget usage example

Source: https://github.com/nyholm/psr7

Creates a Request with a URI containing a path and query, then prints the request target. Output is '/a?b=1'.

```php
$r = new Request('GET', 'https://example.com/a?b=1');
echo $r->getRequestTarget(); // /a?b=1
```

--------------------------------

### withParsedBody usage example

Source: https://github.com/nyholm/psr7

Sets parsed body data and retrieves it. Also demonstrates the exception thrown for invalid types.

```php
$request = (new ServerRequest('POST', '/'))->withParsedBody(['name' => 'John']);
var_dump($request->getParsedBody()); // array(1) { ["name"]=> string(4) "John" }

try {
    (new ServerRequest('POST', '/'))->withParsedBody('raw');
} catch (\InvalidArgumentException $e) {
    // First parameter to withParsedBody MUST be object, array or null
}
```

--------------------------------

### getReasonPhrase usage example

Source: https://github.com/nyholm/psr7

Shows how to retrieve the reason phrase for a response with status 418, which returns 'I'm a teapot'.

```php
(new Response(418))->getReasonPhrase(); // I'm a teapot
```

--------------------------------

### withScheme() method signature

Source: https://github.com/nyholm/psr7

Returns a new instance with the specified scheme. Throws InvalidArgumentException if scheme is not a string. Re-runs filterPort() on the existing port so a port that equals the new scheme's default gets dropped.

```php
/**
 * @return static
 */
public function withScheme($scheme): UriInterface   // src/Uri.php:146
```

--------------------------------

### Seek to a position with seek()

Source: https://github.com/nyholm/psr7

Moves the stream pointer to a byte offset. The example seeks to offset 3 and reads the remaining bytes.

```php
$stream = Stream::create('foobar');
$stream->seek(3);
echo $stream->read(3); // bar
```

--------------------------------

### Rewind stream with rewind()

Source: https://github.com/nyholm/psr7

Resets the stream pointer to the beginning. Equivalent to seek(0). The example seeks to offset 5, rewinds, then reads from the start.

```php
$stream = Stream::create('foobar');
$stream->seek(5);
$stream->rewind();
echo $stream->read(3); // foo
```

--------------------------------

### Nyholm\Psr7\Uri constructor

Source: https://github.com/nyholm/psr7

Creates a Uri instance from a URI string. The URI is parsed with `parse_url()`. Internal constants act as defaults for scheme ports.

```APIDOC
## Constructor: `Nyholm\Psr7\Uri`

### Description
Creates a Uri instance from a URI string. The URI is parsed with `parse_url()`. Internal constants act as defaults for scheme ports.

### Parameters
#### Constructor Parameters
- **uri** (string) - Optional - Default: `''` - URI string parsed with `parse_url()`

### Notes
Internal constants act as defaults: `SCHEMES = ['http' => 80, 'https' => 443]` — a port equal to the scheme default is normalized away.
```

--------------------------------

### Send a request using Buzz and PSR-18

Source: https://github.com/nyholm/psr7/blob/master/README.md

Create a PSR-17 factory and a Buzz Curl client, then create a request and send it. The response is returned by the client.

```php
$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
$psr18Client = new \Buzz\Client\Curl($psr17Factory);

$request = $psr17Factory->createRequest('GET', 'http://tnyholm.se');
$response = $psr18Client->sendRequest($request);
```

--------------------------------

### withCookieParams usage example

Source: https://github.com/nyholm/psr7

Sets cookie parameters on a ServerRequest and retrieves the session value.

```php
$request = (new ServerRequest('GET', '/'))->withCookieParams(['session' => 'abc123']);
echo $request->getCookieParams()['session']; // abc123
```

--------------------------------

### Nyholm\Psr7\Response constructor

Source: https://github.com/nyholm/psr7

Creates a PSR-7 Response instance with configurable status, headers, body, protocol version, and reason phrase.

```APIDOC
## Nyholm\Psr7\Response constructor

### Description
Creates a PSR-7 Response instance with configurable status, headers, body, protocol version, and reason phrase.

### Method
Constructor

### Endpoint
`new \Nyholm\Psr7\Response()`

### Parameters
#### Constructor Parameters
- **status** (`int`) - Optional - Status code (range not validated in constructor) (default `200`)
- **headers** (`array`) - Optional - Headers (default `[]`)
- **body** (`string | resource | StreamInterface | null`) - Optional - Body; `''`/`null` defers stream creation (default `null`)
- **version** (`string`) - Optional - Protocol version (default `'1.1'`)
- **reason** (`string | null`) - Optional - Reason phrase; `null` ⇒ standard phrase for the code, else `''` (default `null`)

### Response
#### Success Response
Returns a `Nyholm\Psr7\Response` instance.
```

--------------------------------

### getServerParams usage example

Source: https://github.com/nyholm/psr7

Creates a ServerRequest with server parameters and retrieves the REMOTE_ADDR value.

```php
$request = new ServerRequest('GET', '/', [], null, '1.1', ['REMOTE_ADDR' => '127.0.0.1']);
echo $request->getServerParams()['REMOTE_ADDR']; // 127.0.0.1
```

--------------------------------

### withStatus basic usage

Source: https://github.com/nyholm/psr7

Demonstrates setting a 404 status and retrieving the status code and reason phrase.

```php
$response = (new Response())->withStatus(404);
echo $response->getStatusCode();   // 404
echo $response->getReasonPhrase(); // Not Found
```

--------------------------------

### Create server request from globals

Source: https://github.com/nyholm/psr7/blob/master/README.md

Use the ServerRequestCreator from nyholm/psr7-server with the PSR-17 factory to create a server request from PHP superglobals.

```php
$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();

$creator = new \Nyholm\Psr7Server\ServerRequestCreator(
    $psr17Factory, // ServerRequestFactory
    $psr17Factory, // UriFactory
    $psr17Factory, // UploadedFileFactory
    $psr17Factory  // StreamFactory
);

$serverRequest = $creator->fromGlobals();
```

--------------------------------

### Get lower-cased scheme with getScheme

Source: https://github.com/nyholm/psr7

Returns the scheme lower-cased without the trailing colon.

```php
public function getScheme(): string   // src/Uri.php:77
```

```php
(new Uri('HTTPS://example.com'))->getScheme(); // https
```

--------------------------------

### getError usage example

Source: https://github.com/nyholm/psr7

Creates an UploadedFile with UPLOAD_ERR_OK and outputs the error status as int(0).

```php
$ok = new UploadedFile('/tmp/x', 1, UPLOAD_ERR_OK);
var_dump($ok->getError()); // int(0)
```

--------------------------------

### withUserInfo

Source: https://github.com/nyholm/psr7

Returns a new instance with the specified user info. The user name is percent-encoded for gen-delims and sub-delims. If the user info is unchanged, the same instance is returned; otherwise a clone is returned. Throws InvalidArgumentException for invalid user or password.

```APIDOC
## `withUserInfo`

```php
public function withUserInfo($user, $password = null): UriInterface
```

### Description
Returns a new instance with the specified user info. The user name is percent-encoded for gen-delims and sub-delims. If the user info is unchanged, the same instance is returned; otherwise a clone is returned. Throws InvalidArgumentException for invalid user or password.

### Parameters
- `$user` (string) - Required - User name (gen-delims and sub-delims are percent-encoded)
- `$password` (string|null) - Optional - Password; an empty string means "no password"

### Return
- static — same instance if unchanged, otherwise a clone.

### Throws
- `\InvalidArgumentException` — `'User must be a string'`
- `\InvalidArgumentException` — `'Password must be a string'` when a non-empty, non-string password is given

### Example
```php
$uri = (new Uri('http://example.com'))->withUserInfo('john', 's3cret');
echo (string) $uri; // http://john:s3cret@example.com
```
```

--------------------------------

### Basic Uri instantiation and string casting

Source: https://github.com/nyholm/psr7

Creates a Uri from a full URI string and casts it to string. The output preserves the original URI exactly, including user info, port, path, query, and fragment.

```php
use Nyholm\Psr7\Uri;

$uri = new Uri('https://user:pass@example.com:8443/path?q=1#frag');
echo (string) $uri; // https://user:pass@example.com:8443/path?q=1#frag
```

--------------------------------

### Emit a response using SapiEmitter

Source: https://github.com/nyholm/psr7/blob/master/README.md

Create a response with a stream body and emit it using the SapiEmitter from laminas-httphandlerrunner.

```php
$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();

$responseBody = $psr17Factory->createStream('Hello world');
$response = $psr17Factory->createResponse(200)->withBody($responseBody);
(new \Laminas\HttpHandlerRunner\Emitter\SapiEmitter())->emit($response);
```

--------------------------------

### Nyholm\Psr7\Request constructor

Source: https://github.com/nyholm/psr7

Creates a PSR-7 Request instance with configurable method, URI, headers, body, and protocol version.

```APIDOC
## Nyholm\Psr7\Request constructor

### Description
Creates a PSR-7 Request instance with configurable method, URI, headers, body, and protocol version.

### Method
Constructor

### Endpoint
`new \Nyholm\Psr7\Request()`

### Parameters
#### Constructor Parameters
- **method** (`string`) - Required - HTTP method
- **uri** (`string | UriInterface`) - Required - URI (string wrapped in `Uri`)
- **headers** (`array`) - Optional - Headers: `name => value` or `name => string[]`
- **body** (`string | resource | StreamInterface | null`) - Optional - Body; `''`/`null` defers stream creation
- **version** (`string`) - Optional - Protocol version (default `'1.1'`)

### Response
#### Success Response
Returns a `Nyholm\Psr7\Request` instance.
```

--------------------------------

### Nyholm\Psr7\ServerRequest constructor

Source: https://github.com/nyholm/psr7

Creates a PSR-7 ServerRequest instance with configurable method, URI, headers, body, protocol version, and server parameters.

```APIDOC
## Nyholm\Psr7\ServerRequest constructor

### Description
Creates a PSR-7 ServerRequest instance with configurable method, URI, headers, body, protocol version, and server parameters.

### Method
Constructor

### Endpoint
`new \Nyholm\Psr7\ServerRequest()`

### Parameters
#### Constructor Parameters
- **method** (`string`) - Required - HTTP method
- **uri** (`string | UriInterface`) - Required - URI (string wrapped in `Uri`)
- **headers** (`array`) - Optional - Headers (default `[]`)
- **body** (`string | resource | StreamInterface | null`) - Optional - Body; `''`/`null` defers stream creation (default `null`)
- **version** (`string`) - Optional - Protocol version (default `'1.1'`)
- **serverParams** (`array`) - Optional - Server environment, typically `$_SERVER`; query params are auto-parsed from the URI (default `[]`)

### Response
#### Success Response
Returns a `Nyholm\Psr7\ServerRequest` instance.
```

--------------------------------

### getContents error handling example

Source: https://github.com/nyholm/psr7

Closes the stream and catches the RuntimeException thrown by getContents(), printing 'Stream is detached'.

```php
$stream = Stream::create('');
$stream->close();
try {
    $stream->getContents();
} catch (\RuntimeException $e) {
    echo $e->getMessage(); // Stream is detached
}
```

--------------------------------

### Advanced usage of Stream::create() with all input types

Source: https://github.com/nyholm/psr7

Shows creating a stream from a string, a resource, and an existing StreamInterface. A StreamInterface is returned as-is.

```php
$fromString = Stream::create('body');                 // string
$fromResource = Stream::create(fopen('/tmp/file', 'r')); // resource
$fromStream = Stream::create($fromString);            // StreamInterface → returned as-is
```

--------------------------------

### withUserInfo() method signature

Source: https://github.com/nyholm/psr7

Returns a new instance with the specified user info. Throws InvalidArgumentException if user is not a string or if a non-empty, non-string password is given.

```php
/**
 * @return static
 */
public function withUserInfo($user, $password = null): UriInterface   // src/Uri.php:166
```

--------------------------------

### HttplugFactory::createResponse

Source: https://github.com/nyholm/psr7

Creates a PSR-7 Response object with configurable status code, reason phrase, headers, body, and version. The reason phrase defaults to null, headers to [], body to null, and version to '1.1'.

```APIDOC
## [METHOD] createResponse

### Description
Creates a PSR-7 Response object with configurable status code, reason phrase, headers, body, and version. The reason phrase defaults to null, headers to [], body to null, and version to '1.1'.

### Method
createResponse

### Parameters
#### Parameters
- **$statusCode** (int) - Optional - HTTP status code, defaults to 200
- **$reasonPhrase** (string|null) - Optional - Reason phrase, defaults to null
- **$headers** (array) - Optional - Headers, defaults to []
- **$body** (mixed) - Optional - Body, defaults to null
- **$version** (string) - Optional - Protocol version, defaults to '1.1'

### Response
#### Success Response
Returns a ResponseInterface object.
```

--------------------------------

### withQuery

Source: https://github.com/nyholm/psr7

Returns a new Uri instance with the specified query string. If the query is unchanged, returns the same instance; otherwise returns a clone.

```APIDOC
## withQuery

### Description
Returns a new Uri instance with the specified query string. If the query is unchanged, returns the same instance; otherwise returns a clone.

### Method
withQuery

### Signature
```php
public function withQuery($query): UriInterface
```

### Parameters
- `$query` (string) - Required - New query string, without leading `?`

### Return
- static - same instance if unchanged, otherwise a clone.

### Throws
- `\InvalidArgumentException` - `'Query and fragment must be a string'`
```

--------------------------------

### Get port with getPort

Source: https://github.com/nyholm/psr7

Returns the port or null when unset or equal to the scheme's default port (http 80, https 443).

```php
public function getPort(): ?int   // src/Uri.php:110
```

```php
var_dump((new Uri('https://example.com:443'))->getPort()); // null
var_dump((new Uri('https://example.com:8443'))->getPort()); // int(8443)
```

--------------------------------

### Basic end-to-end usage of Psr17Factory

Source: https://github.com/nyholm/psr7

Shows how to instantiate Psr17Factory and create a request, response, and stream for basic usage.

```php
use Nyholm\Psr7\Factory\Psr17Factory;

$factory = new Psr17Factory();

$request  = $factory->createRequest('GET', 'http://tnyholm.se');
$response = $factory->createResponse(200)->withBody($factory->createStream('Hello world'));
```

--------------------------------

### getStream() error handling example

Source: https://github.com/nyholm/psr7

Shows the RuntimeException message when the upload error status is not UPLOAD_ERR_OK. The message is 'Cannot retrieve stream due to upload error'.

```php
$failed = new UploadedFile('', 0, UPLOAD_ERR_NO_FILE);
try {
    $failed->getStream();
} catch (\RuntimeException $e) {
    echo $e->getMessage(); // Cannot retrieve stream due to upload error
}
```

--------------------------------

### Request::__construct $uri

Source: https://github.com/nyholm/psr7

Constructor parameter accepting a URI string or UriInterface instance. The URI string is wrapped with new Uri(...).

```APIDOC
## Request::__construct $uri

### Description
Constructor parameter accepting a URI string or UriInterface instance. The URI string is wrapped with new Uri(...).

### Parameters
#### Constructor Parameters
- **$uri** (`string | UriInterface`) - Required - URI string or UriInterface instance
```

--------------------------------

### withQueryParams method signature

Source: https://github.com/nyholm/psr7

Returns a clone with the new query parameters, replacing the auto-parsed ones. The method signature is shown with its source file reference.

```php
/**
 * @return static
 */
public function withQueryParams(array $query): ServerRequestInterface   // src/ServerRequest.php:116
```

--------------------------------

### Response constructor signature

Source: https://github.com/nyholm/psr7

Constructor for Response with parameters: $status (default 200), $headers (default []), $body (default null), $version (default '1.1'), and $reason (default null). If $reason is null, the standard phrase from PHRASES is used when the status code exists, otherwise an empty string. Body initialization is deferred when $body is '' or null.

```php
/**
 * @param int $status Status code
 * @param array $headers Response headers
 * @param string|resource|StreamInterface|null $body Response body
 * @param string $version Protocol version
 * @param string|null $reason Reason phrase (when empty a default will be used based on the status code)
 */
public function __construct(int $status = 200, array $headers = [], $body = null, string $version = '1.1', ?string $reason = null)
```

--------------------------------

### Check end-of-stream with eof()

Source: https://github.com/nyholm/psr7

Returns true when the stream is detached or the end has been reached. The example creates a stream, reads one byte, then checks eof().

```php
$stream = Stream::create('a');
$stream->read(1);
var_dump($stream->eof()); // true
```

--------------------------------

### Using Request header and protocol methods

Source: https://github.com/nyholm/psr7

Shows how to set a header, retrieve it, change the protocol version, and access the body on a Request instance. The body is an empty lazy stream by default.

```php
<?php
$r = (new Request('GET', '/'))->withHeader('Accept', 'application/json');
echo $r->getHeaderLine('Accept');           // application/json
echo $r->withProtocolVersion('2.0')->getProtocolVersion(); // 2.0
echo (string) $r->getBody();               // (empty lazy stream)
?>
```

--------------------------------

### createUri

Source: https://github.com/nyholm/psr7

Creates a new UriInterface instance from a URI string. Throws InvalidArgumentException for unparseable strings.

```APIDOC
## createUri

### Description
Creates a new UriInterface instance from a URI string. Throws InvalidArgumentException for unparseable strings.

### Method
createUri

### Signature
public function createUri(string $uri = ''): UriInterface

### Parameters
- **$uri** (string) - Optional - URI string

### Return
UriInterface - a new Uri. \InvalidArgumentException propagates from the Uri constructor for unparseable strings.

### Request Example
```php
$uri = $factory->createUri('https://example.com/path');
echo (string) $uri; // https://example.com/path
```
```

--------------------------------

### Get authority with getAuthority

Source: https://github.com/nyholm/psr7

Returns '[user-info@]host[:port]'. Empty when host is empty; default port for scheme is omitted (stored as null after filterPort()).

```php
public function getAuthority(): string   // src/Uri.php:82
```

```php
echo (new Uri('http://user:pass@example.com:80'))->getAuthority();
// user:pass@example.com   (port 80 is the http default, so it is dropped)
```

--------------------------------

### withQueryParams

Source: https://github.com/nyholm/psr7

Returns a clone of the request with the new query parameters, replacing the auto-parsed ones.

```APIDOC
## withQueryParams

### Description
Returns a clone of the request with the new query parameters, replacing the auto-parsed ones.

### Method
`withQueryParams`

### Signature
```php
public function withQueryParams(array $query): ServerRequestInterface
```

### Parameters
- `$query` (array) - Required - New query parameters (replaces the auto-parsed ones)

### Return
- static — a clone with the new query parameters.

### Example
```php
$request = (new ServerRequest('GET', '/?page=1'))->withQueryParams(['page' => 3]);
echo $request->getQueryParams()['page']; // 3
```
```

--------------------------------

### Response constructor

Source: https://github.com/nyholm/psr7

Creates a new Response instance with the given status code, headers, and body.

```APIDOC
## Response Constructor

### Description
Creates a new Response instance with the specified status code, headers, and body.

### Method
Constructor

### Endpoint
`new Response(int $status = 200, array $headers = [], string|resource|StreamInterface $body = null, string $version = '1.1', string $reason = null)`

### Parameters
#### Constructor Parameters
- **$status** (int) - Required - HTTP status code (default: 200)
- **$headers** (array) - Optional - Associative array of headers (default: [])
- **$body** (string|resource|StreamInterface) - Optional - Response body (default: null)
- **$version** (string) - Optional - HTTP protocol version (default: '1.1')
- **$reason** (string) - Optional - Reason phrase (default: null)

### Response
#### Success Response (200)
Returns a new `Response` instance.

### Request Example
```php
$response = new Response(200, ['Content-Type' => 'text/html'], '<h1>hi</h1>');
```
```

--------------------------------

### Request Message Methods

Source: https://github.com/nyholm/psr7

The Request class inherits the full header/protocol/body API from MessageTrait, including methods to get and set protocol version, headers, and body. These methods allow you to manipulate the request message.

```APIDOC
## Request Message Methods

### Description
These methods are inherited from `MessageTrait` and provide full header/protocol/body API for the `Request` class.

### Methods
- `getProtocolVersion()` - Returns the HTTP protocol version as a string.
- `withProtocolVersion($version)` - Returns a new instance with the specified HTTP protocol version.
- `getHeaders()` - Returns all message headers.
- `hasHeader($name)` - Checks if a header exists by name.
- `getHeader($name)` - Retrieves a header by name.
- `getHeaderLine($name)` - Retrieves a comma-separated string of the values for a header.
- `withHeader($name, $value)` - Returns a new instance with the specified header.
- `withAddedHeader($name, $value)` - Returns a new instance with an additional header value.
- `withoutHeader($name)` - Returns a new instance without the specified header.
- `getBody()` - Returns the message body as a stream.
- `withBody($body)` - Returns a new instance with the specified body.

### Example
```php
$r = (new Request('GET', '/'))->withHeader('Accept', 'application/json');
echo $r->getHeaderLine('Accept');           // application/json
echo $r->withProtocolVersion('2.0')->getProtocolVersion(); // 2.0
echo (string) $r->getBody();               // (empty lazy stream)
```
```

--------------------------------

### Basic usage of Stream constructor

Source: https://github.com/nyholm/psr7

Creates a Stream instance from a PHP stream resource opened with fopen().

```php
$resource = fopen('php://temp', 'r+');
$stream = new Stream($resource);
```

--------------------------------

### Nyholm\Psr7\Stream constructor

Source: https://github.com/nyholm/psr7

Creates a Stream instance from a resource. Readability and writability are derived from the resource's mode.

```APIDOC
## Constructor: `Nyholm\Psr7\Stream`

### Description
Creates a Stream instance from a resource. Readability and writability are derived from the resource's mode.

### Parameters
#### Constructor Parameters
- **body** (resource) - Required - Stream resource; readability/writability derived from its mode via `READ_WRITE_HASH`

### Static Alternative
`Stream::create($body = '')` - No default requirement. Accepts `string` (≥ 200 000 bytes use the zval wrapper), `resource`, or `StreamInterface` (returned unchanged).
```

--------------------------------

### withScheme

Source: https://github.com/nyholm/psr7

Returns a new instance with the specified scheme. The scheme is stored lower-cased without a colon. If the scheme is unchanged, the same instance is returned; otherwise a clone is returned. Throws an InvalidArgumentException if the scheme is not a string.

```APIDOC
## `withScheme`

```php
public function withScheme($scheme): UriInterface
```

### Description
Returns a new instance with the specified scheme. The scheme is stored lower-cased without a colon. If the scheme is unchanged, the same instance is returned; otherwise a clone is returned. Throws an InvalidArgumentException if the scheme is not a string.

### Parameters
- `$scheme` (string) - Required - New scheme; stored lower-cased without `:`

### Return
- static — same instance if unchanged, otherwise a clone.

### Throws
- `\InvalidArgumentException` — `'Scheme must be a string'`

### Behavior
Re-runs `filterPort()` on the existing port so a port that equals the *new* scheme's default gets dropped.

### Example
```php
$uri = (new Uri('http://example.com'))->withScheme('https');
echo (string) $uri; // https://example.com
```
```

--------------------------------

### Instantiate HttplugFactory with error handling

Source: https://github.com/nyholm/psr7

Shows how to instantiate HttplugFactory when the optional php-http/message-factory package is missing. The constructor throws a \LogicException with a message instructing to run 'composer require php-http/message-factory'.

```php
use Nyholm\Psr7\Factory\HttplugFactory;

// If php-http/message-factory is not installed:
try {
    $factory = new HttplugFactory();
} catch (\LogicException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### getQuery

Source: https://github.com/nyholm/psr7

Returns the query string without the leading '?'.

```APIDOC
## `getQuery`

```php
public function getQuery(): string
```

### Description
Returns the query string without the leading '?'.

### Return
- `string` — the query string.
```

--------------------------------

### withMethod

Source: https://github.com/nyholm/psr7

Returns a clone of the request with a new HTTP method. Throws an InvalidArgumentException if the method is not a string.

```APIDOC
## withMethod

### Description
Returns a clone of the request with a new HTTP method. Throws an InvalidArgumentException if the method is not a string.

### Method
`withMethod`

### Signature
```php
public function withMethod($method): RequestInterface
```

### Parameters
- **$method** (string) - Required - New HTTP method

### Return
- **static** — a clone with the new method.

### Throws
- `\InvalidArgumentException` — `'Method must be a string'`

### Example
```php
$r = (new Request('GET', '/'))->withMethod('PATCH');
echo $r->getMethod(); // PATCH
```
```

--------------------------------

### ServerRequest::__construct $uri

Source: https://github.com/nyholm/psr7

Constructor parameter accepting a URI string or UriInterface instance. The URI string is wrapped with new Uri(...).

```APIDOC
## ServerRequest::__construct $uri

### Description
Constructor parameter accepting a URI string or UriInterface instance. The URI string is wrapped with new Uri(...).

### Parameters
#### Constructor Parameters
- **$uri** (`string | UriInterface`) - Required - URI string or UriInterface instance
```

--------------------------------

### withStatus method signature

Source: https://github.com/nyholm/psr7

Creates a clone with a new status code and reason phrase. Accepts integer or numeric string for the code, and an optional reason phrase. Throws InvalidArgumentException for invalid codes.

```php
/**
 * @return static
 */
public function withStatus($code, $reasonPhrase = ''): ResponseInterface   // src/Response.php:73
```

--------------------------------

### Response::__construct $body

Source: https://github.com/nyholm/psr7

Constructor parameter accepting body content as string, stream resource, StreamInterface, or null/'' for a lazily created empty stream.

```APIDOC
## Response::__construct $body

### Description
Constructor parameter accepting body content as string, stream resource, StreamInterface, or null/'' for a lazily created empty stream.

### Parameters
#### Constructor Parameters
- **$body** (`string | resource | StreamInterface | null`) - Required - Body content string, stream resource, StreamInterface, or null/'' for a lazily created empty stream
```

--------------------------------

### Nyholm\Psr7\UploadedFile constructor

Source: https://github.com/nyholm/psr7

Creates an UploadedFile instance from a stream or file, with size, error status, and optional client metadata.

```APIDOC
## Constructor: `Nyholm\Psr7\UploadedFile`

### Description
Creates an UploadedFile instance from a stream or file, with size, error status, and optional client metadata.

### Parameters
#### Constructor Parameters
- **streamOrFile** (StreamInterface | string | resource) - Required - Content source; only honored when `errorStatus` is `UPLOAD_ERR_OK`
- **size** (int) - Required - Size in bytes
- **errorStatus** (int) - Required - One of `UPLOAD_ERR_OK`, `UPLOAD_ERR_INI_SIZE`, `UPLOAD_ERR_FORM_SIZE`, `UPLOAD_ERR_PARTIAL`, `UPLOAD_ERR_NO_FILE`, `UPLOAD_ERR_NO_TMP_DIR`, `UPLOAD_ERR_CANT_WRITE`, `UPLOAD_ERR_EXTENSION`
- **clientFilename** (string | null) - Optional - Default: `null` - Original client filename
- **clientMediaType** (string | null) - Optional - Default: `null` - Original client media type
```

--------------------------------

### withUploadedFiles method signature

Source: https://github.com/nyholm/psr7

Returns a clone with the new uploaded files. No validation is performed on the array contents.

```php
/**
 * @return static
 */
public function withUploadedFiles(array $uploadedFiles): ServerRequestInterface   // src/ServerRequest.php:84
```

--------------------------------

### withHost

Source: https://github.com/nyholm/psr7

Returns a new URI instance with the specified host. The host is stored lower-cased. Throws an InvalidArgumentException if the host is not a string.

```APIDOC
## `withHost`

### Description
Returns a new URI instance with the specified host. The host is stored lower-cased. Throws an InvalidArgumentException if the host is not a string.

### Method
`withHost`

### Signature
```php
public function withHost($host): UriInterface
```

### Parameters
- `$host` (string) - Required - New host, stored lower-cased

### Return
- static — same instance if unchanged, otherwise a clone.

### Throws
- `\InvalidArgumentException` — `'Host must be a string'`
```

--------------------------------

### withProtocolVersion method signature

Source: https://github.com/nyholm/psr7

Sets a new protocol version. Returns static (same instance if unchanged, otherwise clone). Throws InvalidArgumentException if $version is not scalar.

```php
/**
 * @return static
 */
public function withProtocolVersion($version): MessageInterface   // src/MessageTrait.php:41
```

--------------------------------

### HttplugFactory::createRequest

Source: https://github.com/nyholm/psr7

Creates a PSR-7 Request object with configurable headers, body, and protocol version. The body defaults to null and protocol version to '1.1'.

```APIDOC
## [METHOD] createRequest

### Description
Creates a PSR-7 Request object with configurable headers, body, and protocol version. The body defaults to null and protocol version to '1.1'.

### Method
createRequest

### Parameters
#### Parameters
- **$headers** (array) - Optional - Headers, defaults to []
- **$body** (mixed) - Optional - Body, defaults to null
- **$protocolVersion** (string) - Optional - Protocol version, defaults to '1.1'

### Response
#### Success Response
Returns a RequestInterface object.
```
Tokens:
Raw