Skip to content

Commit c113f46

Browse files
n0nag0nn0nag0n
committed
readme updates with examples
1 parent 5f60753 commit c113f46

File tree

1 file changed

+202
-3
lines changed

1 file changed

+202
-3
lines changed

‎README.md‎

Lines changed: 202 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# What is Async?
22

3-
Async is a package for the Flight framework that allows you to run your Flight apps in asynchronous frameworks like ReactPHP, Swoole, Amp, RoadRunner, Workerman, etc.
3+
Async is a package for the Flight framework that allows you to run your Flight apps in asynchronous frameworks like ReactPHP, Swoole, Amp, RoadRunner, Workerman, Adapterman, etc.
44

5-
# Basic Usage
5+
# Requirements
66

7-
Details to come
7+
- PHP 7.4 or higher
8+
- Swoole extension (for Swoole usage)
9+
- Flight framework 3.16.1 or higher
810

911
# Installation
1012

@@ -14,6 +16,203 @@ Installation is done through composer.
1416
composer require flightphp/async
1517
```
1618

19+
For Swoole support, you'll also need to install the Swoole extension:
20+
21+
```bash
22+
# Using PECL
23+
pecl install swoole
24+
25+
# Or using package manager (Ubuntu/Debian)
26+
sudo apt-get install php-swoole
27+
```
28+
29+
# Basic Usage (swoole)
30+
31+
Here is a simple example of how to use Flight Async where you can use Swoole or PHP-FPM as the server driver within the same project. This allows for you to develop your application using the PHP-FPM driver for better debugging and then switch to Swoole for production.
32+
33+
## Setup
34+
First you'll need the following files in your project:
35+
36+
### index.php
37+
```php
38+
<?php
39+
40+
define('NOT_SWOOLE', true);
41+
42+
include 'swoole_server.php';
43+
```
44+
### swoole_server.php
45+
```php
46+
<?php
47+
48+
// ./swoole_server.php file
49+
50+
require_once(__DIR__.'/vendor/autoload.php');
51+
52+
$app = Flight::app();
53+
54+
$app->route('/', function() use ($app) {
55+
$app->json([
56+
'hello' => 'world'
57+
]);
58+
});
59+
60+
if(!defined("NOT_SWOOLE")) {
61+
// Require the SwooleServerDriver class since we're running in Swoole mode.
62+
require_once(__DIR__.'/SwooleServerDriver.php');
63+
64+
// Custom little hack
65+
// Makes it so the app doesn't stop when it runs.
66+
$app->map('stop', function (?int $code = null) use ($app) {
67+
if ($code !== null) {
68+
$app->response()->status($code);
69+
}
70+
});
71+
Swoole\Runtime::enableCoroutine();
72+
$Swoole_Server = new SwooleServerDriver('127.0.0.1', 9501, $app);
73+
$Swoole_Server->start();
74+
} else {
75+
$app->start();
76+
}
77+
```
78+
79+
### SwooleServerDriver.php
80+
```php
81+
<?php
82+
83+
use flight\adapter\SwooleAsyncRequest;
84+
use flight\adapter\SwooleAsyncResponse;
85+
use flight\AsyncBridge;
86+
use flight\Engine;
87+
use Swoole\HTTP\Server as SwooleServer;
88+
use Swoole\HTTP\Request as SwooleRequest;
89+
use Swoole\HTTP\Response as SwooleResponse;
90+
91+
class SwooleServerDriver {
92+
93+
//use ConnectionPoolTrait;
94+
95+
/** @var SwooleServer */
96+
protected $Swoole;
97+
98+
/** @var Engine */
99+
protected $app;
100+
101+
public function __construct(string $host, int $port, Engine $app) {
102+
$this->Swoole = new SwooleServer($host, $port);
103+
$this->app = $app;
104+
105+
$this->setDefault();
106+
$this->bindWorkerEvents();
107+
$this->bindHttpEvent();
108+
}
109+
110+
protected function setDefault() {
111+
// A bunch of default settings for the Swoole server.
112+
// You can customize these settings based on your needs.
113+
$this->Swoole->set([
114+
'daemonize' => false,
115+
'dispatch_mode' => 1,
116+
'max_request' => 8000,
117+
'open_tcp_nodelay' => true,
118+
'reload_async' => true,
119+
'max_wait_time' => 60,
120+
'enable_reuse_port' => true,
121+
'enable_coroutine' => true,
122+
'http_compression' => false,
123+
'enable_static_handler' => false,
124+
'buffer_output_size' => 4 * 1024 * 1024,
125+
'worker_num' => 4, // Each worker holds a connection pool
126+
]);
127+
}
128+
129+
protected function bindHttpEvent() {
130+
$app = $this->app;
131+
$AsyncBridge = new AsyncBridge($app);
132+
$this->Swoole->on("Start", function(SwooleServer $server) {
133+
echo "Swoole http server is started at http://127.0.0.1:9501\n";
134+
});
135+
136+
// This is where the magic happens, the request is processed by the AsyncBridge
137+
$this->Swoole->on('Request', function (SwooleRequest $request, SwooleResponse $response) use ($AsyncBridge) {
138+
$SwooleAsyncRequest = new SwooleAsyncRequest($request);
139+
$SwooleAsyncResponse = new SwooleAsyncResponse($response);
140+
$AsyncBridge->processRequest($SwooleAsyncRequest, $SwooleAsyncResponse);
141+
$response->end();
142+
143+
gc_collect_cycles(); // Collect garbage to free memory (optional)
144+
});
145+
}
146+
147+
protected function bindWorkerEvents() {
148+
// You can use this to set custom events for the workers, such as creating connection pools.
149+
$createPools = function() {
150+
// Create connection pools for each worker
151+
// This is useful for managing database connections or other resources that need to be shared across requests.
152+
};
153+
$closePools = function() {
154+
// Close connection pools for each worker
155+
// This is useful for cleaning up resources when the worker stops or encounters an error.
156+
};
157+
$this->Swoole->on('WorkerStart', $createPools);
158+
$this->Swoole->on('WorkerStop', $closePools);
159+
$this->Swoole->on('WorkerError', $closePools);
160+
}
161+
162+
public function start()
163+
{
164+
$this->Swoole->start();
165+
}
166+
}
167+
```
168+
169+
## Running the server
170+
171+
### Development Mode (PHP Built-in Server)
172+
To run the server with PHP-FPM for development, you can use the following command in your terminal:
173+
```bash
174+
php -S localhost:8000 # or add -t public/ if you have your index file in the public directory
175+
```
176+
177+
### Production Mode (Swoole)
178+
When you are ready for production, you can switch to Swoole by running the following command:
179+
```bash
180+
php swoole_server.php
181+
```
182+
183+
### Daemonizing the Swoole Server
184+
If you want the Swoole server to run in the background (daemonized), you can modify the configuration in the `SwooleServerDriver.php` file by changing:
185+
186+
```php
187+
'daemonize' => true,
188+
```
189+
190+
**Note:** Swoole runs as its own process and is not a full-fledged web server like Apache or Nginx. You'll likely want to use a reverse proxy with Nginx or Apache to handle SSL termination, load balancing, and serving static files.
191+
192+
## Configuration
193+
194+
The `SwooleServerDriver` class includes several configuration options that you can customize:
195+
196+
- `worker_num`: Number of worker processes (default: 4)
197+
- `max_request`: Maximum requests per worker before restart (default: 8000)
198+
- `enable_coroutine`: Enable coroutines for better concurrency (default: true)
199+
- `buffer_output_size`: Output buffer size (default: 4MB)
200+
201+
## Error Handling
202+
203+
The AsyncBridge handles Flight exceptions and converts them to appropriate HTTP responses. You can also add custom error handling in your routes:
204+
205+
```php
206+
$app->route('/*', function() use ($app) {
207+
try {
208+
// Your route logic here
209+
} catch (Exception $e) {
210+
$app->response()->status(500);
211+
$app->json(['error' => $e->getMessage()]);
212+
}
213+
});
214+
```
215+
17216
# License
18217

19218
Flight Async is released under the [MIT](http://docs.flightphp.com/license) license.

0 commit comments

Comments
 (0)