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
3855Through [ 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
4158composer 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;
5481use Chubbyphp\SwooleRequestHandler\PsrRequestFactory;
5582use Chubbyphp\SwooleRequestHandler\SwooleResponseEmitter;
5683use 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;
6087use 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);
93166namespace App;
94167
95168use Blackfire\Client;
169+ use Blackfire\Profile\Configuration;
96170use 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);
116205namespace App;
117206
118207use 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
1332242026 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