Guzzle PSR-7 Upgrade Guide ==========================
1.x to 2.0 ----------
Guzzle PSR-7 2.0 is a major release that removes deprecated APIs, raises the minimum PHP version, and adds PHP 7 parameter and return types. Applications that only depend on PSR-7 interfaces should usually need small changes. Applications that call helper functions, extend package classes, or pass invalid argument types need closer review.
PHP Version and Dependencies
Guzzle PSR-7 2.0 requires PHP ^7.2.5 || ^8.0. Guzzle PSR-7 1.x supported PHP >=5.4.0.
Composer dependency changes that can affect upgrades:
ralouphie/getallheadersv2 support was dropped; 2.0 requires^3.0.psr/http-factory:^1.0is required because 2.0 ships PSR-17 factories throughGuzzleHttp\Psr7\HttpFactory.
PHP 7 Type Hints and Return Types
Type hints and return types were added wherever possible. Please make sure:
- You pass values of the documented type when calling methods and functions.
- Classes that extend Guzzle PSR-7 classes update any overridden method signatures to remain compatible.
- Code that expected package-specific
InvalidArgumentExceptionexceptions for invalid argument types may now receive PHPTypeErrorexceptions instead.
Common examples include passing a real integer status code to Response::__construct() and passing a string method to Request::__construct().
Removed Function API
The static API was introduced in 1.7.0 to mitigate problems with functions conflicting between global and local copies of the package. The function API was removed in 2.0.0, along with the Composer files autoload entry that loaded src/functions_include.php.
Replace namespaced function calls with the corresponding static methods in the GuzzleHttp\Psr7 namespace:
// Before:
use function GuzzleHttp\Psr7\stream_for;
$stream = stream_for('body');
// After:
use GuzzleHttp\Psr7\Utils;
$stream = Utils::streamFor('body');
| Original Function | Replacement Method |
|---|---|
str | Message::toString |
uri_for | Utils::uriFor |
stream_for | Utils::streamFor |
parse_header | Header::parse |
normalize_header | Header::normalize |
modify_request | Utils::modifyRequest |
rewind_body | Message::rewindBody |
try_fopen | Utils::tryFopen |
copy_to_string | Utils::copyToString |
copy_to_stream | Utils::copyToStream |
hash | Utils::hash |
readline | Utils::readLine |
parse_request | Message::parseRequest |
parse_response | Message::parseResponse |
parse_query | Query::parse |
build_query | Query::build |
mimetype_from_filename | MimeType::fromFilename |
mimetype_from_extension | MimeType::fromExtension |
_parse_message | Message::parseMessage |
_parse_request_uri | Message::parseRequestUri |
get_message_body_summary | Message::bodySummary |
_caseless_remove | Utils::caselessRemove |
Header::normalize() remains the direct 2.0 replacement for normalize_header(). In newer 2.x versions, prefer Header::splitList() for new code.
Deprecated URI Methods Removed
The deprecated Uri::resolve() and Uri::removeDotSegments() methods were removed. Use UriResolver instead.
// Before:
$resolved = Uri::resolve($base, '../path');
$path = Uri::removeDotSegments('/a/../b');
// After:
use GuzzleHttp\Psr7\UriResolver;
use GuzzleHttp\Psr7\Utils;
$resolved = UriResolver::resolve($base, Utils::uriFor('../path'));
$path = UriResolver::removeDotSegments('/a/../b');
Stricter URI Validation
Guzzle PSR-7 1.x automatically fixed a URI that combined an authority with a relative path by prepending / to the path. That deprecated behavior was removed in 2.0. Such URIs now throw InvalidArgumentException.
// Before: automatically converted to //example.com/foo.
$uri = (new Uri())->withHost('example.com')->withPath('foo');
// After: make the absolute path explicit.
$uri = (new Uri())->withHost('example.com')->withPath('/foo');
Header Validation
Header names are validated more strictly according to RFC 7230 token syntax. Names containing whitespace, /, (, ), \\, or other invalid characters are rejected.
If you construct messages from untrusted or non-standard input, normalize or reject invalid header names before constructing Request, Response, or ServerRequest instances.
Query String Boolean Serialization
Query::build() now serializes booleans as 1 and 0, matching http_build_query() behavior.
Query::build(['enabled' => true, 'disabled' => false]);
// enabled=1&disabled=0
In current 2.x versions, pass false as the third argument if you need textual boolean values:
Query::build(['enabled' => true, 'disabled' => false], PHP_QUERY_RFC3986, false);
// enabled=true&disabled=false
Final Stream and Decorator Classes
Several classes that were annotated with @final in 1.x are declared final in 2.0:
AppendStreamBufferStreamCachingStreamDroppingStreamFnStreamInflateStreamLazyOpenStreamLimitStreamMultipartStreamNoSeekStreamPumpStreamStreamWrapper
If your code extends one of these classes, replace inheritance with composition. For custom streams, implement Psr\Http\Message\StreamInterface directly or use GuzzleHttp\Psr7\StreamDecoratorTrait in your own class.
Request, Response, ServerRequest, Stream, UploadedFile, and Uri remain extendable in 2.0, but overridden methods must have compatible signatures.
Public Constants and Internal Details
Some constants that were public in 1.x are implementation details in 2.0:
Stream::READABLE_MODESStream::WRITABLE_MODESUri::HTTP_DEFAULT_HOST
If your code used these constants, define application-specific constants instead of depending on package internals.
Stream Behavior Changes
BufferStream::write() returns 0 instead of false when the buffer exceeds its high-water mark. This keeps the method compatible with the int return type from StreamInterface::write().
Several stream __toString() implementations now catch Throwable. On PHP 7.4 and newer, exceptions thrown during stringification are rethrown. Avoid relying on (string) $stream to hide read failures; call getContents() or read() and handle exceptions when failures are possible.
PSR-17 Factories
Guzzle PSR-7 2.0 adds GuzzleHttp\Psr7\HttpFactory, an implementation of the PSR-17 factory interfaces from psr/http-factory. This is additive, but it is the reason for the new required dependency.
For the full 2.0 diff, see https://github.com/guzzle/psr7/compare/1.8.1...2.0.0.
Source
| 1 | Guzzle PSR-7 Upgrade Guide |
| 2 | ========================== |
| 3 | |
| 4 | 1.x to 2.0 |
| 5 | ---------- |
| 6 | |
| 7 | Guzzle PSR-7 2.0 is a major release that removes deprecated APIs, raises the |
| 8 | minimum PHP version, and adds PHP 7 parameter and return types. Applications that |
| 9 | only depend on PSR-7 interfaces should usually need small changes. Applications |
| 10 | that call helper functions, extend package classes, or pass invalid argument |
| 11 | types need closer review. |
| 12 | |
| 13 | #### PHP Version and Dependencies |
| 14 | |
| 15 | Guzzle PSR-7 2.0 requires PHP `^7.2.5 || ^8.0`. Guzzle PSR-7 1.x supported PHP |
| 16 | `>=5.4.0`. |
| 17 | |
| 18 | Composer dependency changes that can affect upgrades: |
| 19 | |
| 20 | - `ralouphie/getallheaders` v2 support was dropped; 2.0 requires `^3.0`. |
| 21 | - `psr/http-factory:^1.0` is required because 2.0 ships PSR-17 factories through `GuzzleHttp\Psr7\HttpFactory`. |
| 22 | |
| 23 | #### PHP 7 Type Hints and Return Types |
| 24 | |
| 25 | Type hints and return types were added wherever possible. Please make sure: |
| 26 | |
| 27 | - You pass values of the documented type when calling methods and functions. |
| 28 | - Classes that extend Guzzle PSR-7 classes update any overridden method signatures to remain compatible. |
| 29 | - Code that expected package-specific `InvalidArgumentException` exceptions for invalid argument types may now receive PHP `TypeError` exceptions instead. |
| 30 | |
| 31 | Common examples include passing a real integer status code to `Response::__construct()` and passing a string method to `Request::__construct()`. |
| 32 | |
| 33 | #### Removed Function API |
| 34 | |
| 35 | The static API was introduced in 1.7.0 to mitigate problems with functions |
| 36 | conflicting between global and local copies of the package. The function API was |
| 37 | removed in 2.0.0, along with the Composer `files` autoload entry that loaded |
| 38 | `src/functions_include.php`. |
| 39 | |
| 40 | Replace namespaced function calls with the corresponding static methods in the |
| 41 | `GuzzleHttp\Psr7` namespace: |
| 42 | |
| 43 | ```php |
| 44 | // Before: |
| 45 | use function GuzzleHttp\Psr7\stream_for; |
| 46 | |
| 47 | $stream = stream_for('body'); |
| 48 | |
| 49 | // After: |
| 50 | use GuzzleHttp\Psr7\Utils; |
| 51 | |
| 52 | $stream = Utils::streamFor('body'); |
| 53 | ``` |
| 54 | |
| 55 | | Original Function | Replacement Method | |
| 56 | |-------------------|--------------------| |
| 57 | | `str` | `Message::toString` | |
| 58 | | `uri_for` | `Utils::uriFor` | |
| 59 | | `stream_for` | `Utils::streamFor` | |
| 60 | | `parse_header` | `Header::parse` | |
| 61 | | `normalize_header` | `Header::normalize` | |
| 62 | | `modify_request` | `Utils::modifyRequest` | |
| 63 | | `rewind_body` | `Message::rewindBody` | |
| 64 | | `try_fopen` | `Utils::tryFopen` | |
| 65 | | `copy_to_string` | `Utils::copyToString` | |
| 66 | | `copy_to_stream` | `Utils::copyToStream` | |
| 67 | | `hash` | `Utils::hash` | |
| 68 | | `readline` | `Utils::readLine` | |
| 69 | | `parse_request` | `Message::parseRequest` | |
| 70 | | `parse_response` | `Message::parseResponse` | |
| 71 | | `parse_query` | `Query::parse` | |
| 72 | | `build_query` | `Query::build` | |
| 73 | | `mimetype_from_filename` | `MimeType::fromFilename` | |
| 74 | | `mimetype_from_extension` | `MimeType::fromExtension` | |
| 75 | | `_parse_message` | `Message::parseMessage` | |
| 76 | | `_parse_request_uri` | `Message::parseRequestUri` | |
| 77 | | `get_message_body_summary` | `Message::bodySummary` | |
| 78 | | `_caseless_remove` | `Utils::caselessRemove` | |
| 79 | |
| 80 | `Header::normalize()` remains the direct 2.0 replacement for |
| 81 | `normalize_header()`. In newer 2.x versions, prefer `Header::splitList()` for |
| 82 | new code. |
| 83 | |
| 84 | #### Deprecated URI Methods Removed |
| 85 | |
| 86 | The deprecated `Uri::resolve()` and `Uri::removeDotSegments()` methods were |
| 87 | removed. Use `UriResolver` instead. |
| 88 | |
| 89 | ```php |
| 90 | // Before: |
| 91 | $resolved = Uri::resolve($base, '../path'); |
| 92 | $path = Uri::removeDotSegments('/a/../b'); |
| 93 | |
| 94 | // After: |
| 95 | use GuzzleHttp\Psr7\UriResolver; |
| 96 | use GuzzleHttp\Psr7\Utils; |
| 97 | |
| 98 | $resolved = UriResolver::resolve($base, Utils::uriFor('../path')); |
| 99 | $path = UriResolver::removeDotSegments('/a/../b'); |
| 100 | ``` |
| 101 | |
| 102 | #### Stricter URI Validation |
| 103 | |
| 104 | Guzzle PSR-7 1.x automatically fixed a URI that combined an authority with a |
| 105 | relative path by prepending `/` to the path. That deprecated behavior was removed |
| 106 | in 2.0. Such URIs now throw `InvalidArgumentException`. |
| 107 | |
| 108 | ```php |
| 109 | // Before: automatically converted to //example.com/foo. |
| 110 | $uri = (new Uri())->withHost('example.com')->withPath('foo'); |
| 111 | |
| 112 | // After: make the absolute path explicit. |
| 113 | $uri = (new Uri())->withHost('example.com')->withPath('/foo'); |
| 114 | ``` |
| 115 | |
| 116 | #### Header Validation |
| 117 | |
| 118 | Header names are validated more strictly according to RFC 7230 token syntax. |
| 119 | Names containing whitespace, `/`, `(`, `)`, `\\`, or other invalid characters are |
| 120 | rejected. |
| 121 | |
| 122 | If you construct messages from untrusted or non-standard input, normalize or |
| 123 | reject invalid header names before constructing `Request`, `Response`, or |
| 124 | `ServerRequest` instances. |
| 125 | |
| 126 | #### Query String Boolean Serialization |
| 127 | |
| 128 | `Query::build()` now serializes booleans as `1` and `0`, matching |
| 129 | `http_build_query()` behavior. |
| 130 | |
| 131 | ```php |
| 132 | Query::build(['enabled' => true, 'disabled' => false]); |
| 133 | // enabled=1&disabled=0 |
| 134 | ``` |
| 135 | |
| 136 | In current 2.x versions, pass `false` as the third argument if you need textual |
| 137 | boolean values: |
| 138 | |
| 139 | ```php |
| 140 | Query::build(['enabled' => true, 'disabled' => false], PHP_QUERY_RFC3986, false); |
| 141 | // enabled=true&disabled=false |
| 142 | ``` |
| 143 | |
| 144 | #### Final Stream and Decorator Classes |
| 145 | |
| 146 | Several classes that were annotated with `@final` in 1.x are declared `final` in |
| 147 | 2.0: |
| 148 | |
| 149 | - `AppendStream` |
| 150 | - `BufferStream` |
| 151 | - `CachingStream` |
| 152 | - `DroppingStream` |
| 153 | - `FnStream` |
| 154 | - `InflateStream` |
| 155 | - `LazyOpenStream` |
| 156 | - `LimitStream` |
| 157 | - `MultipartStream` |
| 158 | - `NoSeekStream` |
| 159 | - `PumpStream` |
| 160 | - `StreamWrapper` |
| 161 | |
| 162 | If your code extends one of these classes, replace inheritance with composition. |
| 163 | For custom streams, implement `Psr\Http\Message\StreamInterface` directly or use |
| 164 | `GuzzleHttp\Psr7\StreamDecoratorTrait` in your own class. |
| 165 | |
| 166 | `Request`, `Response`, `ServerRequest`, `Stream`, `UploadedFile`, and `Uri` remain |
| 167 | extendable in 2.0, but overridden methods must have compatible signatures. |
| 168 | |
| 169 | #### Public Constants and Internal Details |
| 170 | |
| 171 | Some constants that were public in 1.x are implementation details in 2.0: |
| 172 | |
| 173 | - `Stream::READABLE_MODES` |
| 174 | - `Stream::WRITABLE_MODES` |
| 175 | - `Uri::HTTP_DEFAULT_HOST` |
| 176 | |
| 177 | If your code used these constants, define application-specific constants instead |
| 178 | of depending on package internals. |
| 179 | |
| 180 | #### Stream Behavior Changes |
| 181 | |
| 182 | `BufferStream::write()` returns `0` instead of `false` when the buffer exceeds |
| 183 | its high-water mark. This keeps the method compatible with the `int` return type |
| 184 | from `StreamInterface::write()`. |
| 185 | |
| 186 | Several stream `__toString()` implementations now catch `Throwable`. On PHP 7.4 |
| 187 | and newer, exceptions thrown during stringification are rethrown. Avoid relying |
| 188 | on `(string) $stream` to hide read failures; call `getContents()` or `read()` and |
| 189 | handle exceptions when failures are possible. |
| 190 | |
| 191 | #### PSR-17 Factories |
| 192 | |
| 193 | Guzzle PSR-7 2.0 adds `GuzzleHttp\Psr7\HttpFactory`, an implementation of the |
| 194 | PSR-17 factory interfaces from `psr/http-factory`. This is additive, but it is |
| 195 | the reason for the new required dependency. |
| 196 | |
| 197 | For the full 2.0 diff, see |
| 198 | https://github.com/guzzle/psr7/compare/1.8.1...2.0.0. |