Skip to content

Commit 6ca832f

Browse files
clueclue
committed
Add factory methods for common HTML/JSON/plaintext/XML response types
1 parent 6acf1a7 commit 6ca832f

File tree

3 files changed

+467
-0
lines changed

3 files changed

+467
-0
lines changed

‎README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ multiple concurrent HTTP requests without blocking.
7070
* [withResponseBuffer()](#withresponsebuffer)
7171
* [React\Http\Message](#reacthttpmessage)
7272
* [Response](#response)
73+
* [html()](#html)
74+
* [json()](#json)
75+
* [plaintext()](#plaintext)
76+
* [xml()](#xml)
7377
* [ServerRequest](#serverrequest)
7478
* [ResponseException](#responseexception)
7579
* [React\Http\Middleware](#reacthttpmiddleware)
@@ -2463,6 +2467,183 @@ constants with the `STATUS_*` prefix. For instance, the `200 OK` and
24632467
response message and only adds required streaming support. This base class is
24642468
considered an implementation detail that may change in the future.
24652469

2470+
##### html()
2471+
2472+
The static `html(string $html): Response` method can be used to
2473+
create an HTML response.
2474+
2475+
```php
2476+
$html = <<<HTML
2477+
<!doctype html>
2478+
<html>
2479+
<body>Hello wörld!</body>
2480+
</html>
2481+
2482+
HTML;
2483+
2484+
$response = React\Http\Message\Response::html($html);
2485+
```
2486+
2487+
This is a convenient shortcut method that returns the equivalent of this:
2488+
2489+
```
2490+
$response = new React\Http\Message\Response(
2491+
React\Http\Message\Response::STATUS_OK,
2492+
[
2493+
'Content-Type' => 'text/html; charset=utf-8'
2494+
],
2495+
$html
2496+
);
2497+
```
2498+
2499+
This method always returns a response with a `200 OK` status code and
2500+
the appropriate `Content-Type` response header for the given HTTP source
2501+
string encoded in UTF-8 (Unicode). It's generally recommended to end the
2502+
given plaintext string with a trailing newline.
2503+
2504+
If you want to use a different status code or custom HTTP response
2505+
headers, you can manipulate the returned response object using the
2506+
provided PSR-7 methods or directly instantiate a custom HTTP response
2507+
object using the `Response` constructor:
2508+
2509+
```php
2510+
$response = React\Http\Message\Response::html(
2511+
"<h1>Error</h1>\n<p>Invalid user name given.</p>\n"
2512+
)->withStatus(React\Http\Message\Response::STATUS_BAD_REQUEST);
2513+
```
2514+
2515+
##### json()
2516+
2517+
The static `json(mixed $data): Response` method can be used to
2518+
create a JSON response.
2519+
2520+
```php
2521+
$response = React\Http\Message\Response::json(['name' => 'Alice']);
2522+
```
2523+
2524+
This is a convenient shortcut method that returns the equivalent of this:
2525+
2526+
```
2527+
$response = new React\Http\Message\Response(
2528+
React\Http\Message\Response::STATUS_OK,
2529+
[
2530+
'Content-Type' => 'application/json'
2531+
],
2532+
json_encode(
2533+
['name' => 'Alice'],
2534+
JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRESERVE_ZERO_FRACTION
2535+
) . "\n"
2536+
);
2537+
```
2538+
2539+
This method always returns a response with a `200 OK` status code and
2540+
the appropriate `Content-Type` response header for the given structured
2541+
data encoded as a JSON text.
2542+
2543+
The given structured data will be encoded as a JSON text. Any `string`
2544+
values in the data must be encoded in UTF-8 (Unicode). If the encoding
2545+
fails, this method will throw an `InvalidArgumentException`.
2546+
2547+
By default, the given structured data will be encoded with the flags as
2548+
shown above. This includes pretty printing (PHP 5.4+) and preserving
2549+
zero fractions for `float` values (PHP 5.6.6+) to ease debugging. It is
2550+
assumed any additional data overhead is usually compensated by using HTTP
2551+
response compression.
2552+
2553+
If you want to use a different status code or custom HTTP response
2554+
headers, you can manipulate the returned response object using the
2555+
provided PSR-7 methods or directly instantiate a custom HTTP response
2556+
object using the `Response` constructor:
2557+
2558+
```php
2559+
$response = React\Http\Message\Response::json(
2560+
['error' => 'Invalid user name given']
2561+
)->withStatus(React\Http\Message\Response::STATUS_BAD_REQUEST);
2562+
```
2563+
2564+
##### plaintext()
2565+
2566+
The static `plaintext(string $text): Response` method can be used to
2567+
create a plaintext response.
2568+
2569+
```php
2570+
$response = React\Http\Message\Response::plaintext("Hello wörld!\n");
2571+
```
2572+
2573+
This is a convenient shortcut method that returns the equivalent of this:
2574+
2575+
```
2576+
$response = new React\Http\Message\Response(
2577+
React\Http\Message\Response::STATUS_OK,
2578+
[
2579+
'Content-Type' => 'text/plain; charset=utf-8'
2580+
],
2581+
"Hello wörld!\n"
2582+
);
2583+
```
2584+
2585+
This method always returns a response with a `200 OK` status code and
2586+
the appropriate `Content-Type` response header for the given plaintext
2587+
string encoded in UTF-8 (Unicode). It's generally recommended to end the
2588+
given plaintext string with a trailing newline.
2589+
2590+
If you want to use a different status code or custom HTTP response
2591+
headers, you can manipulate the returned response object using the
2592+
provided PSR-7 methods or directly instantiate a custom HTTP response
2593+
object using the `Response` constructor:
2594+
2595+
```php
2596+
$response = React\Http\Message\Response::plaintext(
2597+
"Error: Invalid user name given.\n"
2598+
)->withStatus(React\Http\Message\Response::STATUS_BAD_REQUEST);
2599+
```
2600+
2601+
##### xml()
2602+
2603+
The static `xml(string $xml): Response` method can be used to
2604+
create an XML response.
2605+
2606+
```php
2607+
$xml = <<<XML
2608+
<?xml version="1.0" encoding="utf-8"?>
2609+
<body>
2610+
<greeting>Hello wörld!</greeting>
2611+
</body>
2612+
2613+
XML;
2614+
2615+
$response = React\Http\Message\Response::xml($xml);
2616+
```
2617+
2618+
This is a convenient shortcut method that returns the equivalent of this:
2619+
2620+
```
2621+
$response = new React\Http\Message\Response(
2622+
React\Http\Message\Response::STATUS_OK,
2623+
[
2624+
'Content-Type' => 'application/xml'
2625+
],
2626+
$xml
2627+
);
2628+
```
2629+
2630+
This method always returns a response with a `200 OK` status code and
2631+
the appropriate `Content-Type` response header for the given XML source
2632+
string. It's generally recommended to use UTF-8 (Unicode) and specify
2633+
this as part of the leading XML declaration and to end the given XML
2634+
source string with a trailing newline.
2635+
2636+
If you want to use a different status code or custom HTTP response
2637+
headers, you can manipulate the returned response object using the
2638+
provided PSR-7 methods or directly instantiate a custom HTTP response
2639+
object using the `Response` constructor:
2640+
2641+
```php
2642+
$response = React\Http\Message\Response::xml(
2643+
"<error><message>Invalid user name given.</message></error>\n"
2644+
)->withStatus(React\Http\Message\Response::STATUS_BAD_REQUEST);
2645+
```
2646+
24662647
#### ServerRequest
24672648

24682649
The `React\Http\Message\ServerRequest` class can be used to

0 commit comments

Comments
 (0)