BlueGit

projects-timfalken-com microchess

Files

microchess / web / lib / push / vendor / guzzlehttp / psr7 / UPGRADING.md

UPGRADING.md

UPGRADING.md 6.6 KiB Download Raw

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/getallheaders v2 support was dropped; 2.0 requires ^3.0.
  • psr/http-factory:^1.0 is required because 2.0 ships PSR-17 factories through GuzzleHttp\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 InvalidArgumentException exceptions for invalid argument types may now receive PHP TypeError exceptions 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 FunctionReplacement Method
strMessage::toString
uri_forUtils::uriFor
stream_forUtils::streamFor
parse_headerHeader::parse
normalize_headerHeader::normalize
modify_requestUtils::modifyRequest
rewind_bodyMessage::rewindBody
try_fopenUtils::tryFopen
copy_to_stringUtils::copyToString
copy_to_streamUtils::copyToStream
hashUtils::hash
readlineUtils::readLine
parse_requestMessage::parseRequest
parse_responseMessage::parseResponse
parse_queryQuery::parse
build_queryQuery::build
mimetype_from_filenameMimeType::fromFilename
mimetype_from_extensionMimeType::fromExtension
_parse_messageMessage::parseMessage
_parse_request_uriMessage::parseRequestUri
get_message_body_summaryMessage::bodySummary
_caseless_removeUtils::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:

  • AppendStream
  • BufferStream
  • CachingStream
  • DroppingStream
  • FnStream
  • InflateStream
  • LazyOpenStream
  • LimitStream
  • MultipartStream
  • NoSeekStream
  • PumpStream
  • StreamWrapper

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_MODES
  • Stream::WRITABLE_MODES
  • Uri::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
1Guzzle PSR-7 Upgrade Guide
2==========================
3
41.x to 2.0
5----------
6
7Guzzle PSR-7 2.0 is a major release that removes deprecated APIs, raises the
8minimum PHP version, and adds PHP 7 parameter and return types. Applications that
9only depend on PSR-7 interfaces should usually need small changes. Applications
10that call helper functions, extend package classes, or pass invalid argument
11types need closer review.
12
13#### PHP Version and Dependencies
14
15Guzzle PSR-7 2.0 requires PHP `^7.2.5 || ^8.0`. Guzzle PSR-7 1.x supported PHP
16`>=5.4.0`.
17
18Composer 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
25Type 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
31Common 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
35The static API was introduced in 1.7.0 to mitigate problems with functions
36conflicting between global and local copies of the package. The function API was
37removed in 2.0.0, along with the Composer `files` autoload entry that loaded
38`src/functions_include.php`.
39
40Replace namespaced function calls with the corresponding static methods in the
41`GuzzleHttp\Psr7` namespace:
42
43```php
44// Before:
45use function GuzzleHttp\Psr7\stream_for;
46
47$stream = stream_for('body');
48
49// After:
50use 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
82new code.
83
84#### Deprecated URI Methods Removed
85
86The deprecated `Uri::resolve()` and `Uri::removeDotSegments()` methods were
87removed. Use `UriResolver` instead.
88
89```php
90// Before:
91$resolved = Uri::resolve($base, '../path');
92$path = Uri::removeDotSegments('/a/../b');
93
94// After:
95use GuzzleHttp\Psr7\UriResolver;
96use 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
104Guzzle PSR-7 1.x automatically fixed a URI that combined an authority with a
105relative path by prepending `/` to the path. That deprecated behavior was removed
106in 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
118Header names are validated more strictly according to RFC 7230 token syntax.
119Names containing whitespace, `/`, `(`, `)`, `\\`, or other invalid characters are
120rejected.
121
122If you construct messages from untrusted or non-standard input, normalize or
123reject 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
132Query::build(['enabled' => true, 'disabled' => false]);
133// enabled=1&disabled=0
134```
135
136In current 2.x versions, pass `false` as the third argument if you need textual
137boolean values:
138
139```php
140Query::build(['enabled' => true, 'disabled' => false], PHP_QUERY_RFC3986, false);
141// enabled=true&disabled=false
142```
143
144#### Final Stream and Decorator Classes
145
146Several classes that were annotated with `@final` in 1.x are declared `final` in
1472.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
162If your code extends one of these classes, replace inheritance with composition.
163For 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
167extendable in 2.0, but overridden methods must have compatible signatures.
168
169#### Public Constants and Internal Details
170
171Some 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
177If your code used these constants, define application-specific constants instead
178of depending on package internals.
179
180#### Stream Behavior Changes
181
182`BufferStream::write()` returns `0` instead of `false` when the buffer exceeds
183its high-water mark. This keeps the method compatible with the `int` return type
184from `StreamInterface::write()`.
185
186Several stream `__toString()` implementations now catch `Throwable`. On PHP 7.4
187and newer, exceptions thrown during stringification are rethrown. Avoid relying
188on `(string) $stream` to hide read failures; call `getContents()` or `read()` and
189handle exceptions when failures are possible.
190
191#### PSR-17 Factories
192
193Guzzle PSR-7 2.0 adds `GuzzleHttp\Psr7\HttpFactory`, an implementation of the
194PSR-17 factory interfaces from `psr/http-factory`. This is additive, but it is
195the reason for the new required dependency.
196
197For the full 2.0 diff, see
198https://github.com/guzzle/psr7/compare/1.8.1...2.0.0.