Skip to content

Commit c960e00

Browse files
committed
Optimize documentation
1 parent 8a7f6e7 commit c960e00

1 file changed

Lines changed: 120 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 120 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,14 @@
2121

2222
## Description
2323

24-
A request handler adapter for swoole, using PSR-7, PSR-15 and PSR-17.
24+
A request handler adapter for [swoole][2], using PSR-7, PSR-15 and PSR-17.
25+
26+
It turns a [swoole][2] HTTP `Server` into a runtime for any [PSR-15][8] request handler: each incoming
27+
swoole request is converted into a [PSR-7][9] server request through [PSR-17][10] factories, handed to your
28+
application, and the returned PSR-7 response is sent back through the swoole response.
29+
30+
Because swoole is a long-running process, your application is bootstrapped once per worker process and then
31+
serves many requests. This removes the per-request bootstrap cost of a classic PHP-FPM setup.
2532

2633
## Requirements
2734

@@ -33,6 +40,16 @@ A request handler adapter for swoole, using PSR-7, PSR-15 and PSR-17.
3340
* [psr/http-server-handler][6]: ^1.0.2
3441
* [psr/log][7]: ^2.0|^3.0.2
3542

43+
## Suggest
44+
45+
Any [PSR-7][9] / [PSR-17][10] implementation can be used, for example:
46+
47+
* [guzzlehttp/psr7][11] (with [http-interop/http-factory-guzzle][12])
48+
* [laminas/laminas-diactoros][13]
49+
* [nyholm/psr7][14]
50+
* [slim/psr7][15]
51+
* [sunrise/http-message][16]
52+
3653
## Installation
3754

3855
Through [Composer](http://getcomposer.org) as [chubbyphp/chubbyphp-swoole-request-handler][1].
@@ -41,8 +58,18 @@ Through [Composer](http://getcomposer.org) as [chubbyphp/chubbyphp-swoole-reques
4158
composer require chubbyphp/chubbyphp-swoole-request-handler "^1.6"
4259
```
4360

61+
The examples below use [slim/psr7][15] as the PSR-7 / PSR-17 implementation:
62+
63+
```sh
64+
composer require slim/psr7 "^1.8"
65+
```
66+
4467
## Usage
4568

69+
### Basic server
70+
71+
Create a `server.php` and start it with `php server.php`:
72+
4673
```php
4774
<?php
4875

@@ -54,19 +81,22 @@ use Chubbyphp\SwooleRequestHandler\OnRequest;
5481
use Chubbyphp\SwooleRequestHandler\PsrRequestFactory;
5582
use Chubbyphp\SwooleRequestHandler\SwooleResponseEmitter;
5683
use Psr\Http\Server\RequestHandlerInterface;
57-
use Some\Psr17\Factory\ServerRequestFactory;
58-
use Some\Psr17\Factory\StreamFactory;
59-
use Some\Psr17\Factory\UploadedFileFactory;
84+
use Slim\Psr7\Factory\ServerRequestFactory;
85+
use Slim\Psr7\Factory\StreamFactory;
86+
use Slim\Psr7\Factory\UploadedFileFactory;
6087
use Swoole\Http\Server;
6188

62-
$loader = require __DIR__.'/vendor/autoload.php';
89+
require __DIR__.'/vendor/autoload.php';
6390

64-
/** @var RequestHandlerInterface $app*/
65-
$app = ...;
91+
/** @var RequestHandlerInterface $app */
92+
$app = ...; // your PSR-15 application, bootstrapped once per worker process
6693

6794
$http = new Server('0.0.0.0', 8080);
6895

69-
$http->on('start', function (Server $server): void {
96+
// number of worker processes, typically the number of CPU cores
97+
$http->set(['worker_num' => 4]);
98+
99+
$http->on('start', static function (Server $server): void {
70100
echo 'Swoole http server is started at http://0.0.0.0:8080'.PHP_EOL;
71101
});
72102

@@ -83,7 +113,50 @@ $http->on('request', new OnRequest(
83113
$http->start();
84114
```
85115

86-
### with blackfire
116+
### Components
117+
118+
The package consists of three small, replaceable parts. Each one has an interface, so you can swap in your own
119+
implementation where the defaults don't fit.
120+
121+
| Class | Interface | Responsibility |
122+
|--------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------|
123+
| `OnRequest` | `OnRequestInterface` | Swoole `request` callback: builds the PSR-7 request, calls the PSR-15 handler and emits the response. |
124+
| `PsrRequestFactory` | `PsrRequestFactoryInterface` | Converts a swoole request into a PSR-7 server request via the given PSR-17 factories. |
125+
| `SwooleResponseEmitter` | `SwooleResponseEmitterInterface` | Converts a PSR-7 response into a swoole response and sends it to the client. |
126+
127+
`PsrRequestFactory` maps the following data:
128+
129+
* method, URI and all headers
130+
* cookies, query params and the parsed body (form data)
131+
* uploaded files, including nested ones (as `UploadedFileInterface` instances)
132+
* the raw body, written to the request body stream
133+
* server params from swoole's server array, with upper-cased keys (`REQUEST_METHOD`, `REMOTE_ADDR`, ...)
134+
135+
`SwooleResponseEmitter` maps the following data:
136+
137+
* status code and reason phrase
138+
* all headers, with `Set-Cookie` headers translated to swoole cookies (including `SameSite`)
139+
* the body, streamed in chunks of 128 KiB by default; pass another chunk size to the constructor to change it
140+
141+
### Long-running process caveats
142+
143+
Swoole keeps the PHP process alive between requests, which differs from PHP-FPM:
144+
145+
* Superglobals like `$_GET`, `$_POST`, `$_SERVER` or `$_COOKIE` are not populated. Read everything from the
146+
PSR-7 request instead.
147+
* Anything you keep in static properties or in long-lived services persists across requests. Avoid request
148+
specific state in shared objects, or reset it per request.
149+
* `REMOTE_ADDR` is the address of the direct peer. If you run behind a reverse proxy,
150+
use a middleware such as [chubbyphp/chubbyphp-trusted-proxy][17] to resolve the client IP from headers.
151+
152+
### With Blackfire
153+
154+
`BlackfireOnRequestAdapter` wraps an `OnRequestInterface` and profiles a request whenever the
155+
`X-Blackfire-Query` header is present, for example when triggered by the Blackfire browser extension or the
156+
`blackfire curl` command. Requests without that header pass through untouched. The probe is always ended,
157+
even if the wrapped handler throws.
158+
159+
Requires the `blackfire` extension and the [blackfire/php-sdk][18] package.
87160

88161
```php
89162
<?php
@@ -93,20 +166,36 @@ declare(strict_types=1);
93166
namespace App;
94167

95168
use Blackfire\Client;
169+
use Blackfire\Profile\Configuration;
96170
use Chubbyphp\SwooleRequestHandler\Adapter\BlackfireOnRequestAdapter;
97-
use Chubbyphp\SwooleRequestHandler\OnRequest;
171+
use Chubbyphp\SwooleRequestHandler\OnRequestInterface;
172+
use Psr\Log\LoggerInterface;
98173

99-
/** @var OnRequest $onRequest */
174+
/** @var OnRequestInterface $onRequest */
100175
$onRequest = ...;
101176

102-
if (extension_loaded('blackfire') {
103-
$onRequest = new BlackfireOnRequestAdapter($onRequest, new Client());
177+
/** @var LoggerInterface $logger */
178+
$logger = ...;
179+
180+
if (extension_loaded('blackfire')) {
181+
$onRequest = new BlackfireOnRequestAdapter(
182+
$onRequest,
183+
new Client(),
184+
new Configuration(), // optional, defaults to new Configuration()
185+
$logger // optional, defaults to a NullLogger; receives Blackfire client errors
186+
);
104187
}
105188

106189
$http->on('request', $onRequest);
107190
```
108191

109-
### with newrelic
192+
### With New Relic
193+
194+
`NewRelicOnRequestAdapter` wraps an `OnRequestInterface` and starts a New Relic transaction for every request.
195+
The transaction is always ended, even if the wrapped handler throws, so each request is reported separately
196+
instead of as one endless transaction per worker process.
197+
198+
Requires the `newrelic` extension.
110199

111200
```php
112201
<?php
@@ -116,18 +205,20 @@ declare(strict_types=1);
116205
namespace App;
117206

118207
use Chubbyphp\SwooleRequestHandler\Adapter\NewRelicOnRequestAdapter;
119-
use Chubbyphp\SwooleRequestHandler\OnRequest;
208+
use Chubbyphp\SwooleRequestHandler\OnRequestInterface;
120209

121-
/** @var OnRequest $onRequest */
210+
/** @var OnRequestInterface $onRequest */
122211
$onRequest = ...;
123212

124-
if (extension_loaded('newrelic') && false !== $name = ini_get('newrelic.appname')) {
125-
$onRequest = new NewRelicOnRequestAdapter($onRequest, $name);
213+
if (extension_loaded('newrelic') && false !== $appname = ini_get('newrelic.appname')) {
214+
$onRequest = new NewRelicOnRequestAdapter($onRequest, $appname);
126215
}
127216

128217
$http->on('request', $onRequest);
129218
```
130219

220+
Both adapters implement `OnRequestInterface`, so they can be combined by nesting them.
221+
131222
## Copyright
132223

133224
2026 Dominik Zogg
@@ -139,3 +230,14 @@ $http->on('request', $onRequest);
139230
[5]: https://packagist.org/packages/psr/http-message
140231
[6]: https://packagist.org/packages/psr/http-server-handler
141232
[7]: https://packagist.org/packages/psr/log
233+
[8]: https://www.php-fig.org/psr/psr-15
234+
[9]: https://www.php-fig.org/psr/psr-7
235+
[10]: https://www.php-fig.org/psr/psr-17
236+
[11]: https://packagist.org/packages/guzzlehttp/psr7
237+
[12]: https://packagist.org/packages/http-interop/http-factory-guzzle
238+
[13]: https://packagist.org/packages/laminas/laminas-diactoros
239+
[14]: https://packagist.org/packages/nyholm/psr7
240+
[15]: https://packagist.org/packages/slim/psr7
241+
[16]: https://packagist.org/packages/sunrise/http-message
242+
[17]: https://packagist.org/packages/chubbyphp/chubbyphp-trusted-proxy
243+
[18]: https://packagist.org/packages/blackfire/php-sdk

0 commit comments

Comments
 (0)